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
dotnet add package Doconut.NET6.DicomPříkaz bez verze nainstaluje nejnovější stabilní vydání. Pro připnutí pluginu k verzi, kterou tato dokumentace popisuje, předávejte verzi samostatně:
dotnet add package Doconut.NET6.Dicom --version 26.10.0Udrž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:
apt-get update && apt-get install -y libfontconfig1Na 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
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:
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:
LicenseException: This document type requires the 'Dicom' plugin license.Licencování a vodoznak
| Stav licence | Spuštění | Výstup DICOM |
|---|---|---|
Placená licence poskytující Dicom, v rámci svého časového okna | Spustí se | Vykresleno podle běžných pravidel vodoznaku stránky |
| Aktivní dočasná (Demo/NFR) licence | Spustí se | Vykresleno s evaluačním vodoznakem |
Žádná licence, starý soubor TRIAL, licence bez Dicom, nebo placená licence mimo její časové okno | AddDoconut() 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#
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žim | Vytvořené stránky | Použití |
|---|---|---|
AnimationOnly | Stránka 1 = animovaný GIF, který přehrává všechny snímky | Rychlý filmový přehled |
FramesOnly | Stránky 1..N = jeden statický PNG na snímek | Diagnostická 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.
// 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=1 | Přečíst technická metadata otevřeného DICOM dokumentu | 200 — DicomMetadata jako JSON, s názvy vlastností z referenci API (Width, Height, NumberOfFrames, …) |
| Stav | Kdy | Tělo |
|---|---|---|
404 | Dokument není DICOM soubor | pouze stav |
501 | Dokument 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
CachePagespovoleno 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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
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
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říznak | Příčina | Oprava |
|---|---|---|
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 | Nainstalujte 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í nasazen | Př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 Dicom | Nainstalujte licenci, která poskytuje Dicom |
| Zobrazuje se pouze jedna stránka | Zdroj je jednoframový, nebo DisplayMode je AnimationOnly | Použ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 ms | Upravte 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ázky | Viz V produkci; ukončete relace explicitně |
Metadata jsou null | Dokument není soubor DICOM | Zkontrolujte typ souboru před požádáním o metadata |
Metadata jsou null pro soubor DICOM, nebo &meta vrací 501 | Očekávané omezení .NET 6; vykreslování není ovlivněno | Použ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řen | Znovu 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ínullpro DICOM relaci a zaznamená jednorázové varování. Odpovídající požadavek?token=…&meta=1vrací HTTP501 Not Implementedse stabilním chybovým kódemdicom_metadata_unsupported. Použijte balíček .NET 8, když jsou technická metadata DICOM požadavkem.
Byla tato stránka užitečná?