DICOM-Plugin
Medizinische Bilder mit DicomPlugin anzeigen
Das DICOM-Plugin fügt Doconut die Anzeige medizinischer Bilder hinzu: Mehrfachrahmen‑DICOM‑Dateien werden als animierte Übersicht, einzelne Rahmen oder beides dargestellt. DICOM ist ein nur‑Plugin‑Format — ohne dieses Plugin (und seine Lizenzfunktion) können .dcm‑Dateien überhaupt nicht geöffnet werden.
Unter .NET Framework 4.7.2 werden DICOM‑Dateien vollständig gerendert — Seiten, Rahmen und Animation — aber technische Metadaten (die DICOM‑Tags) sind nicht verfügbar.
Viewer.GetDicomMetadataAsyncgibt immernullzurück, und die Metadaten‑Anfrage des Viewers (?token=…&meta=1aufDocImage.axd) liefert404, sodass der Viewer kein DICOM‑Eigenschafts‑Panel anzeigt. Verwenden SieDoconut.NET8, wenn Ihre Anwendung die Tags benötigt.
| Oberfläche | Verwendung |
|---|---|
Viewer with DicomConfig (C#) | Sie öffnen DICOM‑Dateien auf dem Server und wählen, wie deren Rahmen präsentiert werden |
Der Viewer (docViewer) auf DocImage.axd | Sie zeigen die Studie auf Ihrer Seite: Animation und Rahmen |
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 erfordert ebenfalls die Dicom‑Fähigkeit.
Paket installieren
Install-Package Doconut.NETFramework.DicomUm das Plugin an die in dieser Dokumentation beschriebene Version zu binden:
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0Halten Sie das DICOM‑Paket in derselben Version wie Doconut.NETFramework.
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.
Plugin registrieren
Doconut.DoconutHost.Initialize(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. Wenn die Lizenz dies nicht gewährt, wirft DoconutHost.Initialize von Application_Start:
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.In System.Web bedeutet das, dass jede Anfrage ein leeres 500 zurückgibt, und der Grund ist nur im Windows‑Ereignisprotokoll (Quelle ASP.NET) zu finden. Es wirft bei fehlender Lizenz, einer veralteten TRIAL‑Datei, einer Lizenz ohne Dicom und einer bezahlten Lizenz, die außerhalb ihres Versionsfensters verwendet wird. Temporäre Demo/NFR‑Lizenzen werden akzeptiert. Siehe Lizenz‑Einrichtung.
Da kein integrierter Viewer diese Formate unterstützt, schlägt das Öffnen sofort 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 |
|---|---|---|
Paid license granting Dicom, within its version window | Startet | Wird nach den normalen Seiten‑Wasserzeichenregeln gerendert |
| Active Temporary (Demo/NFR) license | Startet | Wird mit dem Evaluations‑Wasserzeichen gerendert |
No license, a legacy TRIAL file, a license without Dicom, or a paid license outside its version window | Application_Start throws; every request answers an empty 500 | — |
Die Entscheidung für das normale Seiten‑Wasserzeichen gilt ebenfalls für die DICOM‑Ausgabe. Bei animierter Ausgabe wird jedes GIF‑Frame versehen, sodass das Zeichen während der Wiedergabe sichtbar bleibt. Ein benutzerdefiniertes DocOptions.Watermark wird nur verwendet, wenn die Lizenz benutzerdefinierte Wasserzeichen erlaubt; es kann ein Evaluations‑Wasserzeichen nicht ersetzen.
Verwendung aus C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});var metadata = await viewer.GetDicomMetadataAsync(token);
// Unter .NET Framework ist dies immer null: Der DICOM-Metadatenleser ist dafür nicht verfügbar.
// target. Seiten, Frames und Animationen werden normal gerendert.Die Methode existiert in diesem Paket, damit Code, der mit dem .NET 8‑Paket geteilt wird, kompiliert, aber das Lesen von DICOM‑Tags erfordert eine Komponente, die keinen .NET‑Framework‑Build hat. Planen Sie Ihre Benutzeroberfläche ohne sie – zum Beispiel, verstecken Sie ein Metadaten‑Panel, wenn das Ergebnis null ist.
Anzeigemodi und Auflösung
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 Vorschau |
FramesOnly | Seiten 1..N = ein statisches PNG pro Frame | Frame‑für‑Frame‑Diagnostik‑Navigation |
AnimationAndFrames (default) | Seite 1 = animiertes GIF, Seiten 2..N+1 = ein statisches PNG pro Frame (N = Frame‑Anzahl) | Übersicht und Detail in einem Dokument |
Die Animationszeit wird von AnimationFrameDelayMs gesteuert (Standard 100 ms = 10 FPS; GIF‑Timing verwendet 10‑ms‑Einheiten) und von LoopCount (0 = endlos wiederholen).
Der Viewer erkennt, dass Seite 1 animiert ist, indem er eine HEAD‑Anfrage dafür sendet. Der DocImage.axd‑Handler muss daher HEAD in Web.config akzeptieren (verb="GET,HEAD,POST", siehe Installation); ohne das antwortet IIS mit 404, bevor Doconut läuft, und die Animationserkennung funktioniert nie.
Auflösung
DicomConfig rendert standardmäßig mit 100 DPI pro Achse. Wenn Sie HorizontalResolution/VerticalResolution nicht explizit setzen, folgen sie BaseConfig.ImageResolution, wenn das gesetzt ist, und erst dann wird auf 100 zurückgegriffen.
// Einheitliche Erhöhung über die Basiseigenschaft…
new DicomConfig { ImageResolution = 150 };
// …oder pro Achsensteuerung
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Erstellen Sie Ihr eigenes Frontend
Seitenbilder, einschließlich der animierten ersten Seite, verwenden die Standard‑DocImage.axd‑Bildroute. Die Metadaten‑Anfrage, GET /DocImage.axd?token=<token>&meta=1, liefert 404 in diesem Paket für jedes Dokument, DICOM‑Dateien eingeschlossen, weil der Metadaten‑Reader nicht verfügbar ist.
In Produktion
Mehrframe‑Studien können sowohl eine Animation als auch eine statische Seite pro Frame erzeugen. AnimationAndFrames bietet die umfangreichste Navigation, verursacht aber auch die höchsten Render‑ und Speicher‑Kosten – und auf einem einzelnen Server gehört dieser Speicher zum IIS‑Worker‑Process. Für große Studien:
- Verwenden Sie
FramesOnly, wenn die Frame‑Inspektion wichtiger ist als die 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;
- Lassen Sie
CachePagesnur aktiv, wenn wiederholter Zugriff die behaltenen Bilder rechtfertigt.
Platzieren Sie Doconut.Viewer.Dicom.lic neben Doconut.Viewer.lic auf jedem Server und behalten Sie HEAD in der verb‑Liste des Handlers.
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 immer null in diesem Paket zurück. Wirft InvalidOperationException, wenn das Token unbekannt oder abgelaufen ist. DicomMetadata ist definiert, damit gemeinsam genutzter Code mit dem .NET 8-Paket kompiliert.
Fehlerbehebung
| Symptom | Ursache | Behebung |
|---|---|---|
Jede Anfrage liefert ein leeres 500 nach dem Hinzufügen des Plugins; das Windows-Ereignisprotokoll (Quelle ASP.NET) zeigt 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>() in DoconutHost.Initialize 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 |
| Seite 1 wird nicht animiert | Der Handler in Web.config akzeptiert HEAD nicht | Verwenden Sie verb="GET,HEAD,POST" |
| Animation ist zu schnell oder zu langsam | AnimationFrameDelayMs ist deaktiviert; GIF-Timing verwendet 10‑ms‑Einheiten | Passen Sie AnimationFrameDelayMs an |
| Der 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 immer null | Erwartet in diesem Paket | 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
Im Vergleich zu den ASP.NET‑Core‑Paketen unterscheidet sich dieses Paket im Hosting und bei den DICOM‑Metadaten:
- Registrierung erfolgt in
Application_Start, überDoconutHost.Initialize, anstelle vonbuilder.Services.AddDoconut. - Startfehler zeigen sich als ein leeres
500bei jeder Anfrage, mit dem Grund im Windows‑Ereignisprotokoll. - Animations‑Erkennung benötigt
HEADin derDocImage.axd‑Handler‑verb‑Liste. - Keine DICOM‑Metadaten.
Viewer.GetDicomMetadataAsyncgibt immernullzurück und protokolliert eine einmalige Warnung für eine DICOM‑Sitzung; dieDocImage.axd‑Metadaten‑Anfrage liefert404, nicht das501der .NET 6‑ und .NET‑Standard‑Pakete. - Nur Windows, wie der Rest des .NET‑Framework‑Pakets.
War diese Seite hilfreich?