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ächeVerwenden, 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

bash
dotnet add package Doconut.NET6.Dicom

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

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

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

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

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

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

Lizenzierung & Wasserzeichen

LizenzstatusStartDICOM‑Ausgabe
Kostenpflichtige Lizenz, die Dicom gewährt, innerhalb ihres VersionsfenstersStartetGerendert nach den normalen Seiten‑Wasserzeichen‑Regeln
Aktive temporäre (Demo/NFR) LizenzStartetGerendert mit dem Evaluations‑Wasserzeichen
Keine Lizenz, eine Legacy‑TRIAL‑Datei, eine Lizenz ohne Dicom oder eine kostenpflichtige Lizenz außerhalb ihres Versionsfensterswirft 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#

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

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‑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.

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

RouteZweckErfolgsantwort
GET ?token=<token>&meta=1Technische Metadaten eines offenen DICOM‑Dokuments lesen200 — DicomMetadata als JSON, mit den Eigenschaftsnamen der API‑Referenz (Width, Height, NumberOfFrames, …)
StatusWannInhalt
404Das Dokument ist keine DICOM‑Dateinur Status
501Das 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." }
500Das 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 CachePages nur 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

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, und gibt in diesem Paket immer null zurück. 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" 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

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 ein Einzelbild, oder DisplayMode ist AnimationOnlyVerwenden Sie FramesOnly oder AnimationAndFrames für eine Mehrbildquelle
Animation ist zu schnell oder zu langsamAnimationFrameDelayMs ist deaktiviert; die effektive GIF-Zeit verwendet 10‑ms‑EinheitenPassen Sie AnimationFrameDelayMs an
Speicherverbrauch steigt bei großen MehrbilddateienAnzeigemodus, 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
Metadaten sind null für eine DICOM-Datei, oder &meta gibt 501 zurückErwartete .NET‑6‑Einschränkung; das Rendering ist unverändertVerwenden 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‑Sitzung null zurück und protokolliert eine einmalige Warnung. Die entsprechende ?token=…&meta=1‑Anfrage liefert HTTP 501 Not Implemented mit dem stabilen Fehlercode dicom_metadata_unsupported. Verwenden Sie das .NET‑8‑Paket, wenn technische DICOM-Metadaten erforderlich sind.

War diese Seite hilfreich?