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.GetDicomMetadataAsync gibt immer null zurück, und die Metadaten‑Anfrage des Viewers (?token=…&meta=1 auf DocImage.axd) liefert 404, sodass der Viewer kein DICOM‑Eigenschafts‑Panel anzeigt. Verwenden Sie Doconut.NET8, wenn Ihre Anwendung die Tags benötigt.

OberflächeVerwendung
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.axdSie 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

powershell
Install-Package Doconut.NETFramework.Dicom

Um das Plugin an die in dieser Dokumentation beschriebene Version zu binden:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

Halten 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

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

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.

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:

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

Lizenzierung & Wasserzeichen

LizenzstatusStartDICOM‑Ausgabe
Paid license granting Dicom, within its version windowStartetWird nach den normalen Seiten‑Wasserzeichenregeln gerendert
Active Temporary (Demo/NFR) licenseStartetWird mit dem Evaluations‑Wasserzeichen gerendert
No license, a legacy TRIAL file, a license without Dicom, or a paid license outside its version windowApplication_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#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
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):

ModusErzeugte SeitenVerwendung
AnimationOnlySeite 1 = animiertes GIF, das alle Frames wiederholtSchnelle filmische Vorschau
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 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.

csharp
// 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 CachePages nur 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

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

SymptomUrsacheBehebung
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 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>() 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 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
Seite 1 wird nicht animiertDer Handler in Web.config akzeptiert HEAD nichtVerwenden Sie verb="GET,HEAD,POST"
Animation ist zu schnell oder zu langsamAnimationFrameDelayMs ist deaktiviert; GIF-Timing verwendet 10‑ms‑EinheitenPassen Sie AnimationFrameDelayMs an
Der Speicherverbrauch steigt bei großen MehrbilddateienAnzeige‑Modus, Auflösung und Seiten‑Cache fügen alle behaltene Bilder hinzuSiehe In Produktion; schließen Sie Sitzungen explizit
Metadaten sind immer nullErwartet in diesem PaketVerwenden 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, über DoconutHost.Initialize, anstelle von builder.Services.AddDoconut.
  • Startfehler zeigen sich als ein leeres 500 bei jeder Anfrage, mit dem Grund im Windows‑Ereignisprotokoll.
  • Animations‑Erkennung benötigt HEAD in der DocImage.axd‑Handler‑verb‑Liste.
  • Keine DICOM‑Metadaten. Viewer.GetDicomMetadataAsync gibt immer null zurück und protokolliert eine einmalige Warnung für eine DICOM‑Sitzung; die DocImage.axd‑Metadaten‑Anfrage liefert 404, nicht das 501 der .NET 6‑ und .NET‑Standard‑Pakete.
  • Nur Windows, wie der Rest des .NET‑Framework‑Pakets.

War diese Seite hilfreich?