DICOM plugin

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

DICOM plugin přidává prohlížení lékařských snímků do Doconut: multi‑frame 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 with DicomConfig (C#)Otevřete DICOM soubory na serveru a zvolíte, jak budou jejich snímky prezentovány
Prohlížeč (docViewer)Zobrazujete studii na své stránce: animaci, snímky a panel vlastností DICOM
HTTP koncový bod (?token=<token>&meta=1)Čtete technická metadata ze svého frontendu

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.NET8.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.NET8.Dicom --version 26.10.0

Udržujte balíček DICOM ve stejné verzi jako Doconut.NET8. ID balíčku je Doconut.NET8.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ěží kdekoliv běží Doconut.NET8: 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 se otevření dokumentu nezdaří 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 spuštění 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ě 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 License Setup 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 jejího časového oknaSpouští seVykresleno podle běžných pravidel vodoznaku stránky
Aktivní dočasná (Demo/NFR) licenceSpouští 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ý 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á 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
});

Pro relace otevřené tímto pluginem, Viewer zpřístupňuje metadata značek:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null, pokud relace není DICOM dokument

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

Zobrazovací režimy

Víceframe 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 (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 10 ms jednotky) 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é zvýšení pomocí základní vlastnosti…
new DicomConfig { ImageResolution = 150 };

// …nebo řízení po jednotlivých 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á pacientem. Úplný seznam je v referenci API.

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

Vytvořte si vlastní frontend

Metadata jsou dostupná přes HTTP na cestě, kde je nasazeno UseDoconut() (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 referenci API (Width, Height, NumberOfFrames, …)
StavKdyTělo
404Dokument není DICOM souborpouze stav
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íceframe 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 když výhody opakovaného přístupu převáží nad uloženými obrázky.

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

Reference 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; }   // 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;
}

Režim zobrazení DICOM

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync – Získat DICOM metadata asynchronně

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

Vrátí null, pokud dokument není soubor DICOM. Vyvolá InvalidOperationException, pokud je token neznámý nebo vypršel.

DicomMetadata – DICOM metadata

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 V produkci; ukončete relace explicitně
Metadata jsou nullDokument není soubor DICOMZkontrolujte typ souboru před požádáním o metadata
GetDicomMetadataAsync vyvolá Document session not found. Please re-open document.Token vypršel nebo nebyl nikdy otevřenZnovu otevřete dokument

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