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äche | Verwendung |
|---|---|
Viewer with 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 erfordert ebenfalls die Dicom‑Fähigkeit.
Paket installieren
dotnet add package Doconut.NETStandard.DicomDer unveröffentlichte 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.NETStandard.Dicom --version 26.10.0Halten Sie das DICOM-Paket in derselben Version wie Doconut.NETStandard. Die Paket-ID ist Doconut.NETStandard.Dicom; .<version> erscheint nur im heruntergeladenen .nupkg‑Dateinamen.
Die Lizenzdatei des Plugins, Doconut.Viewer.Dicom.lic, liegt im selben Ordner wie Doconut.Viewer.lic; sie wird zusammen mit der Viewer-Lizenz gelesen.
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 wirft bei fehlender Lizenz, einer veralteten 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 Lizenzsetup für die Art, 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:
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‑Wasserzeichenregeln |
| Aktive temporäre (Demo/NFR) Lizenz | Startet | Gerendert mit dem Evaluations‑Wasserzeichen |
Keine Lizenz, eine veraltete TRIAL‑Datei, eine Lizenz ohne Dicom oder eine kostenpflichtige Lizenz außerhalb ihres Versionsfensters | AddDoconut() wirft | — |
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 aus 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
Anzeige‑Modi
Multiframe‑DICOM‑Dateien können auf drei Arten präsentiert werden (DicomDisplayMode):
| Modus | Erzeugte Seiten | Verwendung |
|---|---|---|
AnimationOnly | Seite 1 = animiertes GIF, das alle Frames wiederholt | Schnelle filmische Vorschau |
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 Animationsgeschwindigkeit 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, wenn das konfiguriert ist, und erst dann fällt auf 100 zurück.
// Einheitlicher Bump über die Basiseigenschaft…
new DicomConfig { ImageResolution = 150 };
// …oder pro Achsensteuerung
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 weiterhin 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() eingebunden 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 die 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 schlug fehl | { "error": "metadata failed" } |
Seitenbilder, einschließlich der animierten ersten Seite, verwenden die Standard‑Viewer‑Bild‑Route.
In Produktion
Multiframe‑Studien können sowohl eine Animation als auch eine statische Seite pro Frame erzeugen. AnimationAndFrames bietet die umfangreichste Navigation, verursacht jedoch 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, beide Auflösungsachsen zu erhöhen, ohne den Speicher zu messen;
- schließen Sie die Sitzung explizit, wenn die Studie nicht mehr geöffnet ist;
- halten Sie
CachePagesnur aktiviert, wenn wiederholte Zugriffe den Nutzen der gespeicherten Bilder überwiegen.
Platzieren Sie Doconut.Viewer.Dicom.lic neben Doconut.Viewer.lic auf jedem Server.
API‑Referenz
DicomConfig, DicomDisplayMode und DicomMetadata befinden sich im Doconut‑Namensraum. 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 immer null in diesem Paket 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" oder "Signed"
public string? PlanarConfiguration { get; init; }
public string? TransferSyntax { get; init; }
public string? Modality { get; init; } // null wenn nicht exponiert
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 Einzelbild, oder DisplayMode ist AnimationOnly | Verwenden Sie FramesOnly oder AnimationAndFrames für eine Mehrbild‑Quelle |
| Animation ist zu schnell oder zu langsam | AnimationFrameDelayMs ist deaktiviert; die effektive GIF‑Timing‑Einheit verwendet 10‑ms‑Schritte | Passen Sie AnimationFrameDelayMs an |
| Speicherverbrauch steigt bei großen Mehrbilddateien | Anzeige‑Modus, 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 Einschränkung dieses Pakets; 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‑Seiten‑Rendering, einzelne Frames, Animation, Transformationen und Wasserzeichen werden unterstützt. Technische Tag‑Metadaten sind im .NET‑Standard‑Paket nicht verfügbar, weil der Metadaten‑Reader nur einen .NET‑8‑Build liefert.
Viewer.GetDicomMetadataAsync(token)gibt dahernullfür eine DICOM‑Sitzung zurü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. - Nur Windows, wie der Rest des .NET‑Standard‑Pakets.
War diese Seite hilfreich?