DICOM-Plugin
Medizinische Bilder mit DicomPlugin anzeigen
Das DICOM-Plugin fügt Doconut die Anzeige medizinischer Bilder hinzu: Mehrframe‑DICOM‑Dateien werden als animierte Übersicht, einzelne Frames oder beides dargestellt. DICOM ist ein nur‑Plugin‑Format — ohne dieses Plugin (und seine Lizenz‑Fähigkeit) können .dcm‑Dateien überhaupt nicht geöffnet werden.
| Oberfläche | Verwenden, wenn |
|---|---|
Viewer mit DicomConfig (C#) | Sie öffnen DICOM‑Dateien auf dem Server und wählen, wie deren Frames präsentiert werden |
Der Viewer (docViewer) | Sie zeigen die Studie auf Ihrer Seite: Animation und Frames |
Das Plugin hat kein eigenes Widget: DICOM‑Dateien öffnen sich im regulären Viewer. Mit dem ebenfalls registrierten Converter‑Plugin können .dcm‑ und .ima‑Dateien in Pdf, Png, Jpeg, Bmp, Tiff oder Gif konvertiert werden; diese Konvertierung benötigt ebenfalls die Dicom‑Fähigkeit.
Paket installieren
dotnet add package Doconut.NET6.DicomDer nicht versionierte Befehl installiert die neueste stabile Version. Um das Plugin auf die in dieser Dokumentation beschriebene Version festzulegen, übergeben Sie die Version separat:
dotnet add package Doconut.NET6.Dicom --version 26.10.0Halten Sie das DICOM‑Paket in derselben Version wie Doconut.NET6. Die Paket‑ID ist
Doconut.NET6.Dicom; .<version> erscheint nur im heruntergeladenen .nupkg‑Dateinamen.
Die Lizenzdatei des Plugins, Doconut.Viewer.Dicom.lic, wird im selben Ordner wie Doconut.Viewer.lic abgelegt; sie wird zusammen mit der Viewer‑Lizenz gelesen.
Plattformen. Das Plugin läuft überall dort, wo Doconut.NET6 läuft: Windows und auf glibc‑basiertem Linux auf x64 (nicht Alpine oder anderen musl‑basierten Distributionen). Unter Linux installieren Sie die Font‑Konfigurationsbibliothek, bevor das erste Dokument geöffnet wird:
apt-get update && apt-get install -y libfontconfig1Auf RHEL, Fedora und ähnlichen Distributionen ist das Paket fontconfig. Ohne dieses schlägt das Öffnen eines Dokuments mit The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. fehl.
Plugin registrieren
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});Das Plugin (Name: "Doconut DICOM Viewer") registriert Viewer für die .dcm‑ und .ima‑Erweiterungen, gesteuert durch die Dicom‑Fähigkeit. Ohne eine Lizenz, die dies gewährt, wirft AddDoconut() beim Start ein InvalidOperationException, bevor die Anwendung eine Anfrage bedient:
The Dicom plugin is registered via AddPlugin but no active license grants Dicom. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Dicom.Es wird ausgelöst bei fehlender Lizenz, einer Legacy‑TRIAL‑Datei, einer Lizenz ohne Dicom und einer kostenpflichtigen Lizenz, die außerhalb ihres Versionsfensters verwendet wird. Temporäre Demo/NFR‑Lizenzen werden akzeptiert. Siehe Lizenz‑Einrichtung für das Laden von Lizenzen.
Da kein integrierter Viewer diese Formate verarbeitet, schlägt das Laufzeit‑Gate ebenfalls hart fehl, wenn die Fähigkeit später nicht mehr verfügbar ist:
LicenseException: This document type requires the 'Dicom' plugin license.Lizenzierung & Wasserzeichen
| Lizenzstatus | Start | DICOM‑Ausgabe |
|---|---|---|
Kostenpflichtige Lizenz, die Dicom gewährt, innerhalb ihres Versionsfensters | Startet | Gerendert nach den normalen Seiten‑Wasserzeichen‑Regeln |
| Aktive temporäre (Demo/NFR) Lizenz | Startet | Gerendert mit dem Evaluations‑Wasserzeichen |
Keine Lizenz, eine Legacy‑TRIAL‑Datei, eine Lizenz ohne Dicom oder eine kostenpflichtige Lizenz außerhalb ihres Versionsfensters | wirft AddDoconut() | — |
Die Entscheidung für das normale Seiten‑Wasserzeichen gilt ebenfalls für die DICOM‑Ausgabe. Bei animierter Ausgabe wird jedes GIF‑Frame mit einem Stempel versehen, sodass das Zeichen während der Wiedergabe sichtbar bleibt. Ein benutzerdefiniertes DocOptions.Watermark wird nur verwendet, wenn der Lizenzpfad benutzerdefinierte Wasserzeichen zulässt; es kann ein Evaluations‑Wasserzeichen nicht ersetzen.
Verwendung in C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Viewer.GetDicomMetadataAsync(token) existiert in diesem Paket, gibt jedoch null für eine DICOM‑Sitzung zurück: siehe Framework‑Hinweise.
Anzeigemodi, Auflösung und Metadaten
Anzeigemodi
Mehrframe‑DICOM‑Dateien können auf drei Arten dargestellt werden (DicomDisplayMode):
| Modus | Erzeugte Seiten | Verwendung |
|---|---|---|
AnimationOnly | Seite 1 = animiertes GIF, das alle Frames wiederholt | Schnelle filmische Übersicht |
FramesOnly | Seiten 1..N = ein statisches PNG pro Frame | Frame‑für‑Frame‑Diagnostiknavigation |
AnimationAndFrames (default) | Seite 1 = animiertes GIF, Seiten 2..N+1 = ein statisches PNG pro Frame (N = Frame‑Anzahl) | Übersicht + Detail in einem Dokument |
Die Animationszeit wird von AnimationFrameDelayMs gesteuert (Standard 100 ms = 10 FPS; GIF‑Granularität ist 10 ms‑Einheiten) und LoopCount (0 = Endlosschleife).
Auflösung
DicomConfig rendert standardmäßig mit 100 DPI pro Achse. Die Auflösungseigenschaften haben eine nützliche Fallback‑Kette: Wenn Sie HorizontalResolution/VerticalResolution nicht explizit setzen, folgen sie BaseConfig.ImageResolution, sofern das konfiguriert ist, und erst dann wird auf 100 zurückgegriffen.
// Einheitlicher Bump über die Basiseigenschaft…
new DicomConfig { ImageResolution = 150 };
// …oder Steuerung pro Achse
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Metadaten
DicomMetadata enthält nur technische und bildgebende Tags — Frame‑Anzahl, Abmessungen, Bit‑Tiefe, photometrische Interpretation, Transfer‑Syntax, Modalität und den Standard‑Fenster‑Level. Es enthält keine patientenidentifizierbaren Daten. Die vollständige Liste befindet sich in der API‑Referenz. In diesem Paket sind die Metadaten nicht verfügbar; siehe Framework‑Hinweise.
Im Viewer
Der Viewer benötigt keine DICOM‑spezifische Einrichtung. Wenn das geöffnete Dokument eine DICOM‑Datei ist, fordert er die Metadaten (?token=<token>&meta=1) an und fügt einen DICOM‑Button hinzu, der ein technische‑Eigenschaften‑Panel öffnet. Wenn diese Anfrage fehlschlägt, bleibt das Panel verborgen und das Dokument wird trotzdem gerendert. In diesem Paket liefert die Anfrage 501, sodass das Panel nie erscheint.
Erstellen Sie Ihr eigenes Frontend
Die Metadaten sind über HTTP unter dem Pfad verfügbar, an dem UseDoconut() eingehängt ist (normalerweise /doconut), für jedes offene Dokument‑Token:
| Route | Zweck | Erfolgsantwort |
|---|---|---|
GET ?token=<token>&meta=1 | Technische Metadaten eines offenen DICOM‑Dokuments lesen | 200 — DicomMetadata als JSON, mit den Eigenschaftsnamen der API‑Referenz (Width, Height, NumberOfFrames, …) |
| Status | Wann | Inhalt |
|---|---|---|
404 | Das Dokument ist keine DICOM‑Datei | nur Status |
501 | Das Dokument ist eine DICOM‑Datei, aber dieses Paket kann ihre Tags nicht lesen | { "error": "dicom_metadata_unsupported", "message": "DICOM technical metadata is not supported on this package: the underlying medical-imaging engine has no build for this target framework. On this package it always returns null; use the .NET 8 package if you need it. DICOM rendering is unaffected." } |
500 | Das Lesen der Metadaten ist fehlgeschlagen | { "error": "metadata failed" } |
Seitenbilder, einschließlich der animierten ersten Seite, verwenden die Standard‑Viewer‑Bild‑Route.
In der Produktion
Mehrframe‑Studien können sowohl eine Animation als auch eine statische Seite pro Frame erzeugen. AnimationAndFrames bietet die umfangreichste Navigation, hat aber auch die höchsten Rendering‑ und Cache‑Kosten. Für große Studien:
- verwenden Sie
FramesOnly, wenn die Frame‑Inspektion wichtiger ist als die filmische Wiedergabe; - vermeiden Sie das Erhöhen beider Auflösungsachsen, ohne den Speicher zu messen;
- schließen Sie die Sitzung explizit, wenn die Studie nicht mehr geöffnet ist;
- halten Sie
CachePagesnur aktiviert, wenn der Nutzen wiederholten Zugriffs die gespeicherten Bilder überwiegt.
Platzieren Sie Doconut.Viewer.Dicom.lic neben Doconut.Viewer.lic auf jedem Server.
API-Referenz
DicomConfig, DicomDisplayMode und DicomMetadata befinden sich im Doconut Namespace. DicomPlugin ist in Doconut.Plugins.Dicom. Die vollständige DicomConfig Eigenschaftstabelle befindet sich in Formatkonfigurationen.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // Standard: ImageResolution, wenn gesetzt, sonst 100
public int VerticalResolution { get; set; } // Standard: ImageResolution, wenn gesetzt, sonst 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = Endlosschleife
public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}DicomDisplayMode
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);Gibt null zurück, wenn das Dokument keine DICOM-Datei ist, und gibt in diesem Paket immer null zurück. Wirft InvalidOperationException, wenn das Token unbekannt oder abgelaufen ist.
DicomMetadata
public sealed class DicomMetadata
{
public int Width { get; init; }
public int Height { get; init; }
public int NumberOfFrames { get; init; }
public int BitsAllocated { get; init; }
public int BitsStored { get; init; }
public int SamplesPerPixel { get; init; }
public string? PhotometricInterpretation { get; init; }
public string? PixelRepresentation { get; init; } // "Unsigned" or "Signed"
public string? PlanarConfiguration { get; init; }
public string? TransferSyntax { get; init; }
public string? Modality { get; init; } // null wenn nicht freigegeben
public double? WindowCenter { get; init; }
public double? WindowWidth { get; init; }
public bool IsColor { get; init; }
}Fehlerbehebung
| Symptom | Ursache | Lösung |
|---|---|---|
AddDoconut() wirft The Dicom plugin is registered via AddPlugin but no active license grants Dicom. | Keine Lizenz, eine TRIAL Datei, eine Lizenz ohne Dicom, oder eine bezahlte Lizenz außerhalb ihres Versionsfensters | Installieren Sie eine Lizenz, die Dicom gewährt, oder entfernen Sie AddPlugin<DicomPlugin>() |
Öffnen einer .dcm Datei wirft Document format '.dcm' is not supported. | DicomPlugin ist nicht registriert, oder sein Paket ist nicht bereitgestellt | Fügen Sie AddPlugin<DicomPlugin>() innerhalb von AddDoconut() hinzu und stellen Sie das Paket bereit |
Öffnen einer .dcm Datei wirft LicenseException: This document type requires the 'Dicom' plugin license. | Die geladene Lizenz gewährt Dicom nicht mehr | Installieren Sie eine Lizenz, die Dicom gewährt |
| Es wird nur eine Seite angezeigt | Die Quelle ist ein Einzelbild, oder DisplayMode ist AnimationOnly | Verwenden Sie FramesOnly oder AnimationAndFrames für eine Mehrbildquelle |
| Animation ist zu schnell oder zu langsam | AnimationFrameDelayMs ist deaktiviert; die effektive GIF-Zeit verwendet 10‑ms‑Einheiten | Passen Sie AnimationFrameDelayMs an |
| Speicherverbrauch steigt bei großen Mehrbilddateien | Anzeigemodus, Auflösung und Seiten-Cache fügen alle behaltene Bilder hinzu | Siehe In Produktion; schließen Sie Sitzungen explizit |
Metadaten sind null | Das Dokument ist keine DICOM-Datei | Überprüfen Sie den Dateityp, bevor Sie nach Metadaten fragen |
Metadaten sind null für eine DICOM-Datei, oder &meta gibt 501 zurück | Erwartete .NET‑6‑Einschränkung; das Rendering ist unverändert | Verwenden Sie das .NET‑8‑Paket, wenn Sie die Tags benötigen |
GetDicomMetadataAsync wirft Document session not found. Please re-open document. | Das Token ist abgelaufen oder wurde nie geöffnet | Öffnen Sie das Dokument erneut |
Framework-Hinweise
- Keine DICOM-Metadaten. DICOM-Seitenrendering, Einzelbilder, Animation, Transformationen und Wasserzeichen werden unterstützt. Technische Tag-Metadaten sind im .NET‑6‑Paket nicht verfügbar, weil der Metadatenleser keinen .NET‑6‑Build hat.
Viewer.GetDicomMetadataAsync(token)gibt daher für eine DICOM‑Sitzungnullzurück und protokolliert eine einmalige Warnung. Die entsprechende?token=…&meta=1‑Anfrage liefert HTTP501 Not Implementedmit dem stabilen Fehlercodedicom_metadata_unsupported. Verwenden Sie das .NET‑8‑Paket, wenn technische DICOM-Metadaten erforderlich sind.
War diese Seite hilfreich?