DICOM Plugin

Prohlížejte lékařské snímky pomocí DicomPlugin

Plugin DICOM přidává prohlížení lékařských snímků do Doconut: více‑rámcové soubory DICOM se vykreslují jako animovaný přehled, jednotlivé snímky nebo obojí. DICOM je formát pouze pro plugin — bez tohoto pluginu (a jeho licenční schopnosti) nelze soubory .dcm vůbec otevřít.

RozhraníPoužijte, když
Viewer with DicomConfig (C#)Otevřete soubory DICOM na serveru a zvolíte, jak budou jejich snímky prezentovány
Prohlížeč (docViewer)Zobrazíte studii na své stránce: animaci a snímky

Plugin nemá vlastní widget: soubory DICOM se otevírají v běžném prohlížeči. S také registrovaným Plugin převodníku lze soubory .dcm a .ima převést na Pdf, Png, Jpeg, Bmp, Tiff nebo Gif; tato konverze také vyžaduje schopnost Dicom.

Instalace balíčku

bash
dotnet add package Doconut.NET6.Dicom

Příkaz bez verze nainstaluje nejnovější stabilní vydání. Pro připnutí pluginu k verzi, kterou tato dokumentace popisuje, předávejte verzi samostatně:

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

Udržujte balíček DICOM ve stejné verzi jako Doconut.NET6. ID balíčku je Doconut.NET6.Dicom; .<version> se objevuje pouze v názvu staženého souboru .nupkg.

Licenční soubor pluginu, Doconut.Viewer.Dicom.lic, umístěte do stejné složky jako Doconut.Viewer.lic; je načten spolu s licencí prohlížeče.

Platformy. Plugin běží všude tam, kde běží Doconut.NET6: Windows a Linux založený na glibc na x64 (ne Alpine ani jiné distribuce založené na musl). Na Linuxu nainstalujte knihovnu pro konfiguraci fontů před otevřením prvního dokumentu:

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

Na distribucích RHEL, Fedora a podobných je balíček fontconfig. Bez něj selže otevření dokumentu s chybou The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Registrace pluginu

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Plugin (Name: "Doconut DICOM Viewer") registruje prohlížeče pro rozšíření .dcm a .ima, řízené schopností Dicom. Bez licence, která to povoluje, AddDoconut() při startu vyhodí InvalidOperationException, ještě před tím, než aplikace obslouží požadavek:

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.

Vyhodí to při chybějící licenci, starém souboru TRIAL, licenci bez Dicom a placené licenci použití mimo její časové okno. Dočasné licence Demo/NFR jsou akceptovány. Viz Nastavení licence pro způsob načítání licencí.

Protože žádný vestavěný prohlížeč tyto formáty neobsluhuje, runtime brána také tvrdě selže, pokud se schopnost později stane nedostupnou:

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

Licencování a vodoznak

Stav licenceSpuštěníVýstup DICOM
Placená licence poskytující Dicom, v rámci svého časového oknaSpustí seVykresleno podle běžných pravidel vodoznaku stránky
Aktivní dočasná (Demo/NFR) licenceSpustí seVykresleno s evaluačním vodoznakem
Žádná licence, starý soubor TRIAL, licence bez Dicom, nebo placená licence mimo její časové oknoAddDoconut() vyhodí—

Rozhodnutí o běžném vodoznaku stránky se vztahuje i na výstup DICOM. Pro animovaný výstup je každý snímek GIF opatřen razítkem, aby značka zůstala viditelná po celou dobu přehrávání. Vlastní DocOptions.Watermark se používá pouze tehdy, když licenční cesta umožňuje vlastní vodoznaky; nemůže nahradit evaluační vodoznak.

Použití z C#

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

Viewer.GetDicomMetadataAsync(token) existuje v tomto balíčku, ale vrací null pro DICOM relaci: viz Poznámky k frameworku.

Zobrazovací režimy, rozlišení a metadata

Zobrazovací režimy

Multi‑frame DICOM soubory lze prezentovat třemi způsoby (DicomDisplayMode):

RežimVytvořené stránkyPoužití
AnimationOnlyStránka 1 = animovaný GIF, který přehrává všechny snímkyRychlý filmový přehled
FramesOnlyStránky 1..N = jeden statický PNG na snímekDiagnostická navigace snímek po snímku
AnimationAndFrames (default)Stránka 1 = animovaný GIF, stránky 2..N+1 = jeden statický PNG na snímek (N = počet snímků)Přehled + detail v jednom dokumentu

Časování animace je řízeno pomocí AnimationFrameDelayMs (výchozí 100 ms = 10 FPS; granularita GIF je jednotky po 10 ms) a LoopCount (0 = nekonečné opakování).

Rozlišení

DicomConfig vykresluje ve výchozím nastavení 100 DPI na osu. Vlastnosti rozlišení mají řetězec náhrad, který stojí za to znát: pokud explicitně nenastavíte HorizontalResolution/VerticalResolution, řídí se podle BaseConfig.ImageResolution, pokud je nastaven, a až poté se vrátí na 100.

csharp
// Jednotné vyboulení pomocí základní vlastnosti…
new DicomConfig { ImageResolution = 150 };

// …nebo řízení po jednotlivých osách
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Metadata

DicomMetadata nese pouze technické a zobrazovací značky — počet snímků, rozměry, bitovou hloubku, fotometrickou interpretaci, přenosovou syntaxi, modalitu a výchozí úroveň okna. Neobsahuje žádná data identifikovatelná pacienta. Úplný seznam je v referenci API. V tomto balíčku metadata nejsou k dispozici; viz Poznámky k frameworku.

V prohlížeči

Prohlížeč nevyžaduje žádné specifické nastavení pro DICOM. Když je otevřený dokument DICOM soubor, požaduje metadata (?token=<token>&meta=1) a přidá tlačítko DICOM, které otevře panel technických vlastností. Pokud požadavek selže, panel zůstane skrytý a dokument se i tak vykreslí. V tomto balíčku odpovídá požadavek 501, takže panel se nikdy neobjeví.

Vytvořte si vlastní frontend

Metadata jsou dostupná přes HTTP na cestě, kde je nasazeno UseDoconut() (obvykle /doconut), pro libovolný token otevřeného dokumentu:

CestaÚčelÚspěšná odpověď
GET ?token=<token>&meta=1Přečíst technická metadata otevřeného DICOM dokumentu200 — DicomMetadata jako JSON, s názvy vlastností z referenci API (Width, Height, NumberOfFrames, …)
StavKdyTělo
404Dokument není DICOM souborpouze stav
501Dokument je DICOM soubor, ale tento balíček nedokáže číst jeho značky{ "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Čtení metadat selhalo{ "error": "metadata failed" }

Obrázky stránek, včetně animované první stránky, používají standardní cestu obrázku prohlížeče.

V produkci

Multiframe studie mohou generovat jak animaci, tak jednu statickou stránku na snímek. AnimationAndFrames poskytuje nejbohatší navigaci, ale také nejvyšší náklady na vykreslování a cache. Pro velké studie:

  • použijte FramesOnly, když je kontrola snímků důležitější než filmové přehrávání;
  • vyhněte se zvyšování obou os rozlišení bez měření paměti;
  • ukončete relaci explicitně, když studie již není otevřena;
  • ponechte CachePages povoleno pouze tehdy, když výhody opakovaného přístupu převáží nad zachovanými obrázky.

Umístěte Doconut.Viewer.Dicom.lic vedle Doconut.Viewer.lic na každém serveru.

Referenční API

DicomConfig, DicomDisplayMode a DicomMetadata jsou v jmenném prostoru Doconut. DicomPlugin je v Doconut.Plugins.Dicom. Kompletní tabulka vlastností DicomConfig se nachází v Formátové konfigurace.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // default: ImageResolution když je nastaveno, jinak 100
    public int VerticalResolution { get; set; }     // default: ImageResolution když je nastaveno, jinak 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = smyčka navždy
    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);

Vrací null, když dokument není soubor DICOM, a vždy vrací null v tomto balíčku. Vyvolá výjimku InvalidOperationException, když je token neznámý nebo vypršel.

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" nebo "Signed"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null když není vystaveno
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Řešení problémů

PříznakPříčinaOprava
AddDoconut() vyvolá The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Žádná licence, soubor TRIAL, licence bez Dicom, nebo placená licence mimo její časové oknoNainstalujte licenci, která poskytuje Dicom, nebo odstraňte AddPlugin<DicomPlugin>()
Otevření souboru .dcm vyvolá Document format '.dcm' is not supported.DicomPlugin není zaregistrován, nebo jeho balíček není nasazenPřidejte AddPlugin<DicomPlugin>() do AddDoconut() a nasadte balíček
Otevření souboru .dcm vyvolá LicenseException: This document type requires the 'Dicom' plugin license.Načtená licence již neposkytuje DicomNainstalujte licenci, která poskytuje Dicom
Zobrazuje se pouze jedna stránkaZdroj je jednoframový, nebo DisplayMode je AnimationOnlyPoužijte FramesOnly nebo AnimationAndFrames pro vícefrámový zdroj
Animace je příliš rychlá nebo pomaláAnimationFrameDelayMs je vypnutý; efektivní časování GIF používá jednotky 10 msUpravte AnimationFrameDelayMs
Paměť roste u velkých vícefrámových souborůRežim zobrazení, rozlišení a mezipaměť stránek všechny přidávají uchovávané obrázkyViz V produkci; ukončete relace explicitně
Metadata jsou nullDokument není soubor DICOMZkontrolujte typ souboru před požádáním o metadata
Metadata jsou null pro soubor DICOM, nebo &meta vrací 501Očekávané omezení .NET 6; vykreslování není ovlivněnoPoužijte balíček .NET 8, když potřebujete značky
GetDicomMetadataAsync vyvolá Document session not found. Please re-open document.Token vypršel nebo nikdy nebyl otevřenZnovu otevřete dokument

Poznámky k frameworku

  • Žádná metadata DICOM. Renderování stránek DICOM, jednotlivé snímky, animace, transformace a vodoznakování jsou podporovány. Technická metadata značek nejsou k dispozici v balíčku .NET 6, protože čtečka metadat nemá sestavení .NET 6. Viewer.GetDicomMetadataAsync(token) proto vrací null pro DICOM relaci a zaznamená jednorázové varování. Odpovídající požadavek ?token=…&meta=1 vrací HTTP 501 Not Implemented se stabilním chybovým kódem dicom_metadata_unsupported. Použijte balíček .NET 8, když jsou technická metadata DICOM požadavkem.

Byla tato stránka užitečná?