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‑snímkové DICOM soubory 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 s DicomConfig (C#)Otevřete DICOM soubory 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: DICOM soubory se otevírají v běžném prohlížeči. S také registrovaným Converter plugin 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.NETStandard.Dicom

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

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

Udržujte balíček DICOM ve stejné verzi jako Doconut.NETStandard. ID balíčku je Doconut.NETStandard.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.

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 umožňuje, AddDoconut() při spuštění vyhodí InvalidOperationException, ještě předtí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ě licence, 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íDICOM výstup
Placená licence poskytující Dicom, v rámci její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 DICOM výstup. Pro animovaný výstup je každý GIF snímek opatřen razítkem, aby značka zůstala viditelná během přehrávání. Vlastní DocOptions.Watermark se používá jen 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

Více‑rámcové DICOM soubory lze zobrazit třemi způsoby (DicomDisplayMode):

RežimVytvořené stránkyPoužití
AnimationOnlyStránka 1 = animovaný GIF opakující všechny snímkyRychlý filmový přehled
FramesOnlyStránky 1..N = jeden statický PNG na snímekDiagnostická navigace snímek po snímku
AnimationAndFrames (výchozí)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 v jednotkách 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áhradních hodnot, 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 osách
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Metadata

DicomMetadata obsahuje 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á k pacientovi. Úplný seznam je v referenčním 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í 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ěď na požadavek je 501, takže se panel nikdy nezobrazí.

Vytvořte si vlastní frontend

Metadata jsou dostupná přes HTTP na cestě, kde je UseDoconut() nasazen (obvykle /doconut), pro jakýkoli 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 referenčního API (Width, Height, NumberOfFrames, …)
StavKdyTělo
404Dokument není DICOM souborpouze stav
501Dokument je DICOM soubor, ale tento balíček nedokáže př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

Více‑rámcové 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řená;
  • ponechte CachePages povolené pouze tehdy, když výhody opakovaného přístupu převáží nad uchovávaný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ých konfiguracích.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // výchozí: ImageResolution, pokud je nastaveno, jinak 100
    public int VerticalResolution { get; set; }     // výchozí: ImageResolution, pokud 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á 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é okno verzeNainstalujte 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 nasadíte 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
Zobrazí 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 souborů s více snímkyRežim zobrazení, rozlišení a mezipaměť stránek všechny přidávají zachované obrázkyViz Ve výrobě; 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í tohoto balíčku; 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 nebyl nikdy otevřenZnovu otevřete dokument

Poznámky k frameworku

  • Žádná metadata DICOM. Vykreslová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 Standard, protože čtečka metadat je distribuována pouze v sestavení .NET 8. Viewer.GetDicomMetadataAsync(token) tedy 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.
  • Pouze Windows, stejně jako zbytek balíčku .NET Standard.

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