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 Einzelbilder oder beides dargestellt. DICOM ist ein nur‑Plugin‑Format — ohne dieses Plugin (und seine Lizenzfunktion) können .dcm‑Dateien überhaupt nicht geöffnet werden.

OberflächeVerwendung
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, Frames und ein DICOM‑Eigenschafts‑Panel
HTTP‑Endpunkt (?token=<token>&meta=1)Sie lesen die technischen Metadaten aus Ihrem eigenen Frontend

Das Plugin hat kein eigenes Widget: DICOM‑Dateien öffnen sich im regulären Viewer. Mit dem Konverter‑Plugin, das ebenfalls registriert ist, können .dcm‑ und .ima‑Dateien in Pdf, Png, Jpeg, Bmp, Tiff oder Gif konvertiert werden; diese Konvertierung benötigt außerdem die Dicom‑Fähigkeit.

Paket installieren

bash
dotnet add package Doconut.NET8.Dicom

Der nicht versionierte Befehl installiert die neueste stabile Version. Um das Plugin auf die in dieser Dokumentation beschriebene Version festzulegen, geben Sie die Version separat an:

bash
dotnet add package Doconut.NET8.Dicom --version 26.10.0

Halten Sie das DICOM‑Paket in derselben Version wie Doconut.NET8. Die Paket‑ID ist Doconut.NET8.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.NET8 läuft: Windows und glibc‑basiertes Linux auf x64 (nicht Alpine oder andere musl‑basierte Distributionen). Unter Linux installieren Sie die Font‑Konfigurationsbibliothek, bevor das erste Dokument geöffnet wird:

bash
apt-get update && apt-get install -y libfontconfig1

Unter 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

csharp
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:

text
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 wirft dies bei fehlender Lizenz, einer veralteten TRIAL‑Datei, einer Lizenz ohne Dicom sowie einer kostenpflichtigen Lizenz, die außerhalb ihres Versionsfensters verwendet wird. Temporäre Demo/NFR‑Lizenzen werden akzeptiert. Siehe Lizenz‑Einrichtung für Informationen, wie Lizenzen geladen werden.

Da kein integrierter Viewer diese Formate unterstützt, schlägt das Laufzeit‑Gate ebenfalls hart fehl, wenn die Fähigkeit später nicht mehr verfügbar ist:

text
LicenseException: This document type requires the 'Dicom' plugin license.

Lizenzierung & Wasserzeichen

LizenzstatusStartDICOM‑Ausgabe
Bezahlte Lizenz, die Dicom gewährt, innerhalb ihres VersionsfenstersStartetGerendert nach den normalen Seiten‑Wasserzeichen‑Regeln
Aktive temporäre (Demo/NFR) LizenzStartetMit dem Evaluations‑Wasserzeichen gerendert
Keine Lizenz, eine veraltete TRIAL‑Datei, eine Lizenz ohne Dicom oder eine bezahlte Lizenz außerhalb ihres VersionsfenstersAddDoconut() wirft—

Die Entscheidung für das normale Seiten‑Wasserzeichen gilt ebenfalls für DICOM‑Ausgaben. Bei animierten Ausgaben wird jedes GIF‑Frame mit dem Wasserzeichen 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 aus C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});

Für über dieses Plugin geöffnete Sitzungen stellt Viewer die Tag‑Metadaten bereit:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null, wenn die Sitzung kein DICOM-Dokument ist

Anzeige­modi, Auflösung und Metadaten

Anzeige­modi

Mehrframe‑DICOM‑Dateien können auf drei Arten dargestellt werden (DicomDisplayMode):

ModusErzeugte SeitenVerwendung
AnimationOnlySeite 1 = animiertes GIF, das alle Frames wiederholtSchnelle filmische Übersicht
FramesOnlySeiten 1..N = ein statisches PNG pro FrameFrame‑für‑Frame‑Diagnostik‑Navigation
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 = endlos wiederholen).

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 danach fällt auf 100 zurück.

csharp
// Einheitliche Erhöhung über die base property…
new DicomConfig { ImageResolution = 150 };

// …oder pro-Achsen-Steuerung
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.

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. Schlägt diese Anfrage fehl, bleibt das Panel verborgen und das Dokument wird weiterhin gerendert.

Erstellen Sie Ihr eigenes Frontend

Die Metadaten sind über HTTP unter dem Pfad verfügbar, an dem UseDoconut() eingebunden ist (normalerweise /doconut), für jedes offene Dokument‑Token:

RouteZweckErfolgsantwort
GET ?token=<token>&meta=1Lese die technischen Metadaten eines offenen DICOM‑Dokuments200 — DicomMetadata als JSON, mit den Eigenschaftsnamen der API‑Referenz (Width, Height, NumberOfFrames, …)
StatusWannInhalt
404Das Dokument ist keine DICOM‑Dateinur Status
500Lesen der Metadaten fehlgeschlagen{ "error": "metadata failed" }

Seitenbilder, einschließlich der animierten ersten Seite, verwenden die Standard‑Viewer‑Bild‑Route.

In 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 Render‑ und Cache‑Kosten. Für große Studien:

  • Verwenden Sie FramesOnly, wenn die Frame‑Inspektion wichtiger ist als die filmische Wiedergabe;
  • Vermeiden Sie, beide Auflösungsachsen zu erhöhen, ohne den Speicherverbrauch zu messen;
  • Schließen Sie die Sitzung explizit, wenn die Studie nicht mehr geöffnet ist;
  • Halten Sie CachePages nur aktiviert, wenn wiederholter Zugriff Nutzen bringt, der 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 Format‑Konfigurationen.

DicomConfig

csharp
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

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

Gibt null zurück, wenn das Dokument keine DICOM‑Datei ist. Wirft InvalidOperationException, wenn das Token unbekannt oder abgelaufen ist.

DicomMetadata

csharp
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" oder "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

SymptomUrsacheLö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 VersionsfenstersInstallieren 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 bereitgestelltFü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 mehrInstallieren Sie eine Lizenz, die Dicom gewährt
Es wird nur eine Seite angezeigtDie Quelle ist Einzelbild, oder DisplayMode ist AnimationOnlyVerwenden Sie FramesOnly oder AnimationAndFrames für eine Mehrbild‑Quelle
Animation ist zu schnell oder zu langsamAnimationFrameDelayMs ist deaktiviert; die effektive GIF‑Zeitmessung verwendet 10‑ms‑EinheitenPassen Sie AnimationFrameDelayMs an
Speicherverbrauch steigt bei großen Mehrbild‑DateienAnzeigemodus, Auflösung und Seiten‑Cache fügen alle behaltene Bilder hinzuSiehe In Produktion; schließen Sie Sitzungen explizit
Metadaten sind nullDas Dokument ist keine DICOM‑DateiÜberprüfen Sie den Dateityp, bevor Sie nach Metadaten fragen
GetDicomMetadataAsync wirft Document session not found. Please re-open document.Das Token ist abgelaufen oder wurde nie geöffnetÖffnen Sie das Dokument erneut

War diese Seite hilfreich?