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.
| Środowisko | Kiedy 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
dotnet add package Doconut.NET8.DicomPolecenie bez wersji instaluję najnowsze stabilne wydanie. Aby przypiąć wtyczkę do wersji opisanej w tej dokumentacji, przekaż wersję osobno:
dotnet add package Doconut.NET8.Dicom --version 26.10.0Utrzymuj 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:
apt-get update && apt-get install -y libfontconfig1W 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ę
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:
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:
LicenseException: This document type requires the 'Dicom' plugin license.Licencjonowanie i znak wodny
| Stan licencji | Uruchomienie | Wyjście DICOM |
|---|---|---|
Płatna licencja przyznająca Dicom, w ramach swojego okna wersji | Uruchamia 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 wersji | AddDoconut() 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#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Dla sesji otwieranych przez tę wtyczkę, Viewer udostępnia metadane tagów:
var metadata = await viewer.GetDicomMetadataAsync(token);
// null, gdy sesja nie jest dokumentem DICOMTryby wyświetlania, rozdzielczość i metadane
Tryby wyświetlania
Pliki DICOM wieloklatkowe mogą być prezentowane na trzy sposoby (DicomDisplayMode):
| Tryb | Strony wygenerowane | Zastosowanie |
|---|---|---|
AnimationOnly | Strona 1 = animowany GIF powtarzający wszystkie klatki | Szybki przegląd filmowy |
FramesOnly | Strony 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.
// 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żka | Cel | Odpowiedź sukcesu |
|---|---|---|
GET ?token=<token>&meta=1 | Odczytaj techniczne metadane otwartego dokumentu DICOM | 200 — DicomMetadata jako JSON, z nazwami właściwości z Referencja API (Width, Height, NumberOfFrames, …) |
| Status | Kiedy | Treść |
|---|---|---|
404 | Dokument nie jest plikiem DICOM | tylko status |
500 | Odczyt 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
CachePageswłą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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
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
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
| Objaw | Przyczyna | Naprawa |
|---|---|---|
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 wersji | Zainstaluj 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żony | Dodaj 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 Dicom | Zainstaluj licencję, która przyznaje Dicom |
| Wyświetla się tylko jedna strona | Źródło jest jednoklatkowe, lub DisplayMode jest AnimationOnly | Użyj FramesOnly lub AnimationAndFrames dla źródła wieloklatkowego |
| Animacja jest zbyt szybka lub zbyt wolna | AnimationFrameDelayMs jest wyłączone; skuteczne taktowanie GIF używa jednostek 10 ms | Dostosuj AnimationFrameDelayMs |
| Pamięć rośnie przy dużych plikach wieloklatkowych | Tryb wyświetlania, rozdzielczość i pamięć podręczna stron wszystkie dodają zachowane obrazy | Zobacz W produkcji; zamykaj sesje wyraźnie |
Metadane są null | Dokument nie jest plikiem DICOM | Sprawdź typ pliku przed żądaniem metadanych |
GetDicomMetadataAsync rzuca Document session not found. Please re-open document. | Token wygasł lub nigdy nie został otwarty | Otwórz dokument ponownie |
Czy ta strona była pomocna?