DICOM plugin

Prohlížejte medicínské obrázky pomocí DicomPlugin

DICOM plugin přidává prohlížení medicínských obrázků do Doconut: soubory DICOM s více snímky 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.

Na .NET Framework 4.7.2 se soubory DICOM vykreslují kompletně — stránky, snímky a animace — ale technická metadata (DICOM značky) nejsou k dispozici. Viewer.GetDicomMetadataAsync vždy vrací null a požadavek prohlížeče na metadata (?token=…&meta=1 na DocImage.axd) odpovídá 404, takže prohlížeč nezobrazuje panel vlastností DICOM. Použijte Doconut.NET8, pokud vaše aplikace potřebuje značky.

RozhraníKdy použít
Viewer with DicomConfig (C#)Otevíráte soubory DICOM na serveru a vybíráte, jak budou jejich snímky prezentovány
Prohlížeč (docViewer) na DocImage.axdZobrazujete 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

powershell
Install-Package Doconut.NETFramework.Dicom

Pro připnutí pluginu k verzi, kterou tato dokumentace popisuje:

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

Udržujte balíček DICOM ve stejné verzi jako Doconut.NETFramework.

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

Registrace pluginu

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Plugin (Name: "Doconut DICOM Viewer") registruje prohlížeče pro rozšíření .dcm a .ima, omezené schopností Dicom. Pokud licence tuto schopnost nepovolí, DoconutHost.Initialize vyvolá výjimku z 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.

V System.Web to znamená, že každá žádost vrátí prázdný 500 a důvod je zaznamenán pouze v protokolu událostí Windows (zdroj ASP.NET). Vyvolá se 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.

Protože žádný vestavěný prohlížeč tyto formáty nepodporuje, jejich otevření selže okamžitě, 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é oknoApplication_Start vyvolá výjimku; každá žádost vrátí prázdný 500—

Rozhodnutí o běžném vodoznaku stránky se vztahuje i na výstup DICOM. U animovaného výstupu je každý GIF snímek opatřen vodoznakem, takže značka zůstává viditelná po celou dobu přehrávání. Vlastní DocOptions.Watermark se používá pouze tehdy, když licence povoluje vlastní vodoznaky; nemůže nahradit evaluační vodoznak.

Použití z C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// V .NET Framework je to vždy null: čtečka metadat DICOM pro toto není k dispozici
// target. Stránky, snímky a animace se vykreslují normálně.

Metoda existuje v tomto balíčku, aby kód sdílený s balíčkem .NET 8 byl kompilovatelný, ale čtení DICOM značek vyžaduje komponentu, která nemá sestavení pro .NET Framework. Navrhněte své uživatelské rozhraní bez nich — například skryjte panel metadat, když je výsledek null.

Zobrazovací režimy a rozlišení

Zobrazovací režimy

Více‑rámcové DICOM soubory lze prezentovat 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 a podrobnosti v jednom dokumentu

Časování animace je řízeno pomocí AnimationFrameDelayMs (výchozí 100 ms = 10 FPS; časování GIF používá jednotky 10 ms) a LoopCount (0 = nekonečná smyčka).

Prohlížeč zjistí, že stránka 1 je animovaná odesláním požadavku HEAD. Handler DocImage.axd proto musí přijímat HEAD v Web.config (verb="GET,HEAD,POST", viz Instalace); bez toho IIS odpoví 404 před spuštěním Doconut a detekce animace nikdy nefunguje.

Rozlišení

DicomConfig vykresluje ve výchozím nastavení 100 DPI na osu. Pokud explicitně nenastavíte HorizontalResolution/VerticalResolution, následují BaseConfig.ImageResolution, pokud je nastaven, a teprve poté se vrátí na 100.

csharp
// Jednotný nárůst přes základní vlastnost…
new DicomConfig { ImageResolution = 150 };

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

Vytvořte si vlastní frontend

Obrázky stránek, včetně animované první stránky, používají standardní cestu obrázku DocImage.axd. Požadavek na metadata, GET /DocImage.axd?token=<token>&meta=1, vrací 404 v tomto balíčku pro každý dokument, včetně DICOM souborů, protože čtečka metadat není k dispozici.

V produkci

Více‑rámcové studie mohou vytvořit jak animaci, tak jednu statickou stránku na snímek. AnimationAndFrames poskytuje nejbohatší navigaci, ale také nejvyšší náklady na vykreslování a paměť — a na jediném serveru tato paměť patří pracovnímu procesu IIS. Pro velké studie:

  • použijte FramesOnly, když je kontrola snímků důležitější než přehrávání;
  • vyhněte se zvyšování obou os rozlišení bez měření paměti;
  • ukončete relaci explicitně, když už studie není otevřená;
  • ponechte CachePages zapnuté pouze tehdy, když opakovaný přístup stojí za zachované obrázky.

Umístěte Doconut.Viewer.Dicom.lic vedle Doconut.Viewer.lic na každém serveru a ponechte HEAD v seznamu verb handleru.

Reference API

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

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

Vždy vrací null v tomto balíčku. Vyhodí InvalidOperationException, když je token neznámý nebo vypršelý. DicomMetadata je definováno, aby kód sdílený s balíčkem .NET 8 byl kompilovatelný.

Řešení problémů

PříznakPříčinaŘešení
Každý požadavek vrací prázdný 500 po přidání pluginu; Windows Event Log (zdroj ASP.NET) ukazuje The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Žádná licence, soubor TRIAL, licence bez Dicom, nebo placená licence mimo své č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í registrováno, nebo jeho balíček není nasazenPřidejte AddPlugin<DicomPlugin>() do DoconutHost.Initialize a nasadíte balíček
Otevření souboru .dcm vyvolá LicenseException: This document type requires the 'Dicom' plugin license.Načtená licence již neumožňuje DicomNainstalujte licenci, která poskytuje Dicom
Zobrazí se jen jedna stránkaZdroj je jednorámcový, nebo DisplayMode je AnimationOnlyPoužijte FramesOnly nebo AnimationAndFrames pro vícerámcový zdroj
Stránka 1 se neanimujeObsluha v Web.config nepřijímá HEADPoužijte verb="GET,HEAD,POST"
Animace je příliš rychlá nebo pomaláAnimationFrameDelayMs je vypnuté; časování GIF používá jednotky 10 msUpravte AnimationFrameDelayMs
Paměť roste u velkých vícerámcových souborůZobrazovací režim, rozlišení a mezipaměť stránek všechny přidávají uchovávané obrázkyViz V produkci; ukončete relace explicitně
Metadata jsou vždy nullOčekáváno v tomto balíčkuPouž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řenDokument otevřete znovu

Poznámky k frameworku

Ve srovnání s balíčky ASP.NET Core se tento balíček liší v hostování a v DICOM metadatech:

  • Registrace je v Application_Start, přes DoconutHost.Initialize, místo builder.Services.AddDoconut.
  • Selhání při spuštění se projevují jako prázdný 500 u každého požadavku, s důvodem v Windows Event Logu.
  • Detekce animace vyžaduje HEAD v seznamu verb obsluhy DocImage.axd.
  • Žádná DICOM metadata. Viewer.GetDicomMetadataAsync vždy vrací null a zaznamená jednorázové varování pro DICOM relaci; požadavek na metadata DocImage.axd odpovídá 404, nikoli 501 balíčků .NET 6 a .NET Standard.
  • Pouze Windows, stejně jako zbytek balíčku .NET Framework.

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