Wtyczka DICOM

Wyświetlaj obrazy medyczne za pomocą DicomPlugin

Wtyczka DICOM dodaje możliwość przeglądania obrazów medycznych do Doconut: pliki DICOM wieloklatkowe są renderowane jako animowany przegląd, poszczególne klatki lub oba jednocześnie. DICOM jest formatem wyłącznie dla wtyczek — bez tej wtyczki (i jej możliwości licencyjnej), pliki .dcm nie mogą być w ogóle otwarte.

ŚrodowiskoKiedy używać
Viewer z DicomConfig (C#)Otwierasz pliki DICOM na serwerze i wybierasz, w jaki sposób prezentowane są ich klatki
Przeglądarka (docViewer)Pokazujesz badanie na swojej stronie: animację, klatki i panel właściwości DICOM
Punkt końcowy HTTP (?token=<token>&meta=1)Odczytujesz techniczne metadane ze swojego frontendu

Wtyczka nie posiada własnego widgetu: pliki DICOM otwierają się w standardowej przeglądarce. Po zarejestrowaniu także wtyczki konwertera, pliki .dcm i .ima mogą być konwertowane do Pdf, Png, Jpeg, Bmp, Tiff lub Gif; ta konwersja wymaga również możliwości Dicom.

Zainstaluj pakiet

bash
dotnet add package Doconut.NET8.Dicom

Polecenie bez wersji instaluję najnowsze stabilne wydanie. Aby przypiąć wtyczkę do wersji opisanej w tej dokumentacji, przekaż wersję osobno:

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

Utrzymuj pakiet DICOM w tej samej wersji co Doconut.NET8. Identyfikator pakietu to Doconut.NET8.Dicom; .<version> pojawia się tylko w pobranej nazwie pliku .nupkg.

Plik licencji wtyczki, Doconut.Viewer.Dicom.lic, znajduje się w tym samym folderze co Doconut.Viewer.lic; jest odczytywany razem z licencją przeglądarki.

Platformy. Wtyczka działa wszędzie tam, gdzie działa Doconut.NET8: Windows oraz Linux oparty na glibc na architekturze x64 (nie Alpine ani inne dystrybucje oparte na musl). Na Linuksie zainstaluj bibliotekę konfiguracji czcionek przed otwarciem pierwszego dokumentu:

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

W dystrybucjach RHEL, Fedora i podobnych pakiet to fontconfig. Bez niego otwieranie dokumentu kończy się niepowodzeniem z The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Zarejestruj wtyczkę

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

Wtyczka (Name: "Doconut DICOM Viewer") rejestruje przeglądarki dla rozszerzeń .dcm i .ima, zabezpieczone możliwością Dicom. Bez licencji, która to umożliwia, AddDoconut() zgłasza InvalidOperationException przy uruchamianiu, zanim aplikacja obsłuży żądanie:

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.

Zgłasza to błąd przy braku licencji, starszym pliku TRIAL, licencji bez Dicom oraz płatnej licencji użytej poza jej oknem wersji. Tymczasowe licencje Demo/NFR są akceptowane. Zobacz Konfigurację licencji, aby dowiedzieć się, jak ładowane są licencje.

Ponieważ żaden wbudowany przeglądacz nie obsługuje tych formatów, bramka w czasie wykonywania również twardo zawiedzie, jeśli możliwość później stanie się niedostępna:

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

Licencjonowanie i znak wodny

Stan licencjiUruchomienieWyjście DICOM
Płatna licencja przyznająca Dicom, w ramach swojego okna wersjiUruchamia sięRenderowane zgodnie z normalnymi zasadami znaku wodnego strony
Aktywna tymczasowa licencja (Demo/NFR)Uruchamia sięRenderowane z znakiem wodnym ewaluacyjnym
Brak licencji, starszy plik TRIAL, licencja bez Dicom lub płatna licencja poza jej oknem wersjiAddDoconut() throws—

Decyzja o normalnym znaku wodnym strony ma również zastosowanie do wyjścia DICOM. Dla wyjścia animowanego każda klatka GIF jest znakowana, aby znak pozostał widoczny przez całe odtwarzanie. Niestandardowy DocOptions.Watermark jest używany tylko wtedy, gdy ścieżka licencyjna zezwala na niestandardowe znaki wodne; nie może on zastąpić znaku wodnego ewaluacyjnego.

Użycie w C#

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

Dla sesji otwieranych przez tę wtyczkę, Viewer udostępnia metadane tagów:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null, gdy sesja nie jest dokumentem DICOM

Tryby wyświetlania, rozdzielczość i metadane

Tryby wyświetlania

Pliki DICOM wieloklatkowe mogą być prezentowane na trzy sposoby (DicomDisplayMode):

TrybStrony wygenerowaneZastosowanie
AnimationOnlyStrona 1 = animowany GIF powtarzający wszystkie klatkiSzybki przegląd filmowy
FramesOnlyStrony 1..N = jeden statyczny PNG na klatkęDiagnostyczna nawigacja klatka po klatce
AnimationAndFrames (default)Strona 1 = animowany GIF, strony 2..N+1 = jeden statyczny PNG na klatkę (N = liczba klatek)Przegląd + szczegóły w jednym dokumencie

Czas trwania animacji jest kontrolowany przez AnimationFrameDelayMs (domyślnie 100 ms = 10 FPS; granularność GIF to jednostki 10 ms) oraz LoopCount (0 = pętla nieskończona).

Rozdzielczość

DicomConfig renderuje domyślnie z rozdzielczością 100 DPI na oś. Właściwości rozdzielczości mają łańcuch domyślnych wartości, który warto znać: jeśli nie ustawisz explicite HorizontalResolution/VerticalResolution, będą podążać za BaseConfig.ImageResolution, gdy jest skonfigurowane, i dopiero wtedy wracają do 100.

csharp
// Jednolity przyrost poprzez właściwość bazową…
new DicomConfig { ImageResolution = 150 };

// …lub kontrola po osiach
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Metadane

DicomMetadata zawiera wyłącznie techniczne i obrazowe tagi — liczbę klatek, wymiary, głębię bitową, interpretację fotometryczną, składnię transferu, modalność oraz domyślny poziom okna. Nie zawiera danych identyfikujących pacjenta. Pełna lista znajduje się w Referencja API.

W przeglądarce

Przeglądarka nie wymaga żadnej specyficznej konfiguracji DICOM. Gdy otwarty dokument jest plikiem DICOM, żąda metadanych (?token=<token>&meta=1) i dodaje przycisk DICOM, który otwiera panel właściwości technicznych. Jeśli to żądanie się nie powiedzie, panel pozostaje ukryty, a dokument nadal jest renderowany.

Zbuduj własny interfejs

Metadane są dostępne przez HTTP pod ścieżką, pod którą zamontowany jest UseDoconut() (zwykle /doconut), dla dowolnego tokenu otwartego dokumentu:

ŚcieżkaCelOdpowiedź sukcesu
GET ?token=<token>&meta=1Odczytaj techniczne metadane otwartego dokumentu DICOM200 — DicomMetadata jako JSON, z nazwami właściwości z Referencja API (Width, Height, NumberOfFrames, …)
StatusKiedyTreść
404Dokument nie jest plikiem DICOMtylko status
500Odczyt metadanych nie powiódł się{ "error": "metadata failed" }

Obrazy stron, w tym animowana pierwsza strona, używają standardowej ścieżki obrazu przeglądarki.

W produkcji

Badania wieloklatkowe mogą generować zarówno animację, jak i jedną statyczną stronę na klatkę. AnimationAndFrames zapewnia najbogatszą nawigację, ale ma też najwyższy koszt renderowania i pamięci podręcznej. Dla dużych badań:

  • użyj FramesOnly, gdy inspekcja klatek jest ważniejsza niż odtwarzanie filmowe;
  • unikaj zwiększania obu osi rozdzielczości bez pomiaru zużycia pamięci;
  • zamknij sesję explicite, gdy badanie nie jest już otwarte;
  • pozostaw CachePages włączone tylko wtedy, gdy korzyści z powtarzalnego dostępu przewyższają koszt przechowywanych obrazów.

Umieść Doconut.Viewer.Dicom.lic obok Doconut.Viewer.lic na każdym serwerze.

Referencja API

DicomConfig, DicomDisplayMode i DicomMetadata znajdują się w przestrzeni nazw Doconut. DicomPlugin jest w Doconut.Plugins.Dicom. Pełna tabela właściwości DicomConfig znajduje się w Konfiguracje formatu.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // domyślnie: ImageResolution gdy ustawione, w przeciwnym razie 100
    public int VerticalResolution { get; set; }     // domyślnie: ImageResolution gdy ustawione, w przeciwnym razie 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = pętla nieskończona
    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);

Zwraca null, gdy dokument nie jest plikiem DICOM. Rzuca InvalidOperationException, gdy token jest nieznany lub wygasł.

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" lub "Signed"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null gdy nie jest udostępniony
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

Rozwiązywanie problemów

ObjawPrzyczynaNaprawa
AddDoconut() rzuca The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Brak licencji, plik TRIAL, licencja bez Dicom, lub płatna licencja poza jej okresem wersjiZainstaluj licencję, która przyznaje Dicom, lub usuń AddPlugin<DicomPlugin>()
Otwieranie pliku .dcm rzuca Document format '.dcm' is not supported.DicomPlugin nie jest zarejestrowany, lub jego pakiet nie jest wdrożonyDodaj AddPlugin<DicomPlugin>() wewnątrz AddDoconut() i wdroż pakiet
Otwieranie pliku .dcm rzuca LicenseException: This document type requires the 'Dicom' plugin license.Załadowana licencja już nie przyznaje DicomZainstaluj licencję, która przyznaje Dicom
Wyświetla się tylko jedna stronaŹródło jest jednoklatkowe, lub DisplayMode jest AnimationOnlyUżyj FramesOnly lub AnimationAndFrames dla źródła wieloklatkowego
Animacja jest zbyt szybka lub zbyt wolnaAnimationFrameDelayMs jest wyłączone; skuteczne taktowanie GIF używa jednostek 10 msDostosuj AnimationFrameDelayMs
Pamięć rośnie przy dużych plikach wieloklatkowychTryb wyświetlania, rozdzielczość i pamięć podręczna stron wszystkie dodają zachowane obrazyZobacz W produkcji; zamykaj sesje wyraźnie
Metadane są nullDokument nie jest plikiem DICOMSprawdź typ pliku przed żądaniem metadanych
GetDicomMetadataAsync rzuca Document session not found. Please re-open document.Token wygasł lub nigdy nie został otwartyOtwórz dokument ponownie

Czy ta strona była pomocna?