Wtyczka DICOM
Wyświetlaj obrazy medyczne za pomocą DicomPlugin
Wtyczka DICOM dodaje przeglądanie obrazów medycznych do Doconut: pliki DICOM wieloklatkowe renderują się jako animowany podgląd, poszczególne klatki lub oba jednocześnie. DICOM jest formatem wyłącznie wtyczkowym — bez tej wtyczki (i jej możliwości licencyjnej) pliki .dcm nie mogą być w ogóle otwarte.
| Środowisko | Użyj, gdy |
|---|---|
Viewer z DicomConfig (C#) | Otwierasz pliki DICOM na serwerze i wybierasz, jak ich klatki mają być prezentowane |
Przeglądarka (docViewer) | Wyświetlasz badanie na swojej stronie: animację i klatki |
Wtyczka nie posiada własnego widgetu: pliki DICOM otwierają się w zwykłej przeglądarce. Z wtyczką konwertera również zarejestrowaną, 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.NET6.DicomPolecenie bez wersji instaluję najnowsze stabilne wydanie. Aby przypiąć wtyczkę do wersji opisanej w tej dokumentacji, przekaż wersję osobno:
dotnet add package Doconut.NET6.Dicom --version 26.10.0Utrzymuj pakiet DICOM w tej samej wersji co Doconut.NET6. Identyfikator pakietu to Doconut.NET6.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.NET6: Windows oraz Linux oparty na glibc na x64 (nie Alpine ani inne dystrybucje oparte na musl). Na Linuxie zainstaluj bibliotekę konfiguracyjną czcionek przed otwarciem pierwszego dokumentu:
apt-get update && apt-get install -y libfontconfig1Na RHEL, Fedorze i podobnych dystrybucjach pakiet to fontconfig. Bez niego otwarcie 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 okresem wersji. Licencje tymczasowe Demo/NFR są akceptowane. Zobacz Konfigurację licencji, aby dowiedzieć się, jak ładowane są licencje.
Ponieważ żaden wbudowany podgląd 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 oceny |
Brak licencji, starszy plik TRIAL, licencja bez Dicom lub płatna licencja poza okresem wersji | AddDoconut() zgłasza | — |
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ły odtwarzanie. Niestandardowy DocOptions.Watermark jest używany tylko wtedy, gdy ścieżka licencyjna pozwala na niestandardowe znaki wodne; nie może on zastąpić znaku wodnego oceny.
Użycie z C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Viewer.GetDicomMetadataAsync(token) istnieje w tym pakiecie, ale zwraca null dla sesji DICOM: zobacz Notatki frameworka.
Tryby wyświetlania, rozdzielczość i metadane
Tryby wyświetlania
Pliki DICOM wieloklatkowe mogą być prezentowane na trzy sposoby (DicomDisplayMode):
| Tryb | Strony generowane | Zastosowanie |
|---|---|---|
AnimationOnly | Strona 1 = animowany GIF powtarzający wszystkie klatki | Szybki przegląd filmowy |
FramesOnly | Strony 1..N = jeden statyczny PNG na klatkę | Nawigacja diagnostyczna 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 się domyślnie z 100 DPI na oś. Właściwości rozdzielczości mają łańcuch awaryjny, który warto znać: jeśli nie ustawisz explicite HorizontalResolution/VerticalResolution, podążają za BaseConfig.ImageResolution, gdy jest skonfigurowane, i dopiero wtedy wracają do 100.
// Jednolity bump poprzez właściwość bazową…
new DicomConfig { ImageResolution = 150 };
// …lub sterowanie po osiach
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Metadane
DicomMetadata zawiera wyłącznie tagi techniczne i obrazowe — 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 odniesieniu API. W tym pakiecie metadane nie są dostępne; zobacz Notatki frameworka.
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. W tym pakiecie odpowiedź na żądanie to 501, więc panel nigdy się nie pojawia.
Zbuduj własny frontend
Metadane są dostępne przez HTTP pod ścieżką, w której zamontowano 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 odniesienia API (Width, Height, NumberOfFrames, …) |
| Status | Kiedy | Treść |
|---|---|---|
404 | Dokument nie jest plikiem DICOM | tylko status |
501 | Dokument jest plikiem DICOM, ale ten pakiet nie może odczytać jego tagów | { "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 | 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 środowisku produkcyjnym
Badania wieloklatkowe mogą generować zarówno animację, jak i jedną statyczną stronę na klatkę. AnimationAndFrames zapewnia najbogatszą nawigację, ale ma także 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 pamięci;
- zamknij sesję explicite, gdy badanie nie jest już otwarte;
- pozostaw
CachePageswłączone tylko wtedy, gdy korzyści z powtarzającego się dostępu przewyższają zachowane obrazy.
Umieść Doconut.Viewer.Dicom.lic obok Doconut.Viewer.lic na każdym serwerze.
Odniesienie 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 w nieskończoność
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, i zawsze zwraca null w tym pakiecie. 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 | Rozwiązanie |
|---|---|---|
AddDoconut() zgłasza 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 swoim oknem wersji | Zainstaluj licencję, która przyznaje Dicom, lub usuń AddPlugin<DicomPlugin>() |
Otwieranie pliku .dcm zgłasza 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 zgłasza 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 jednoframkowe, lub DisplayMode jest AnimationOnly | Użyj FramesOnly lub AnimationAndFrames dla źródła wieloframkowego |
| Animacja jest zbyt szybka lub zbyt wolna | AnimationFrameDelayMs jest wyłączony; efektywne taktowanie GIF używa jednostek 10 ms | Dostosuj AnimationFrameDelayMs |
| Pamięć rośnie przy dużych plikach wieloframkowych | Tryb wyświetlania, rozdzielczość i pamięć podręczna stron wszystkie dodają zatrzymane obrazy | Zobacz W produkcji; zamykaj sesje explicite |
Metadane są null | Dokument nie jest plikiem DICOM | Sprawdź typ pliku przed żądaniem metadanych |
Metadane są null dla pliku DICOM, lub &meta zwraca 501 | Oczekiwane ograniczenie .NET 6; renderowanie nie jest dotknięte | Użyj pakietu .NET 8, gdy potrzebujesz tagów |
GetDicomMetadataAsync zgłasza Document session not found. Please re-open document. | Token wygasł lub nigdy nie został otwarty | Otwórz dokument ponownie |
Notatki dotyczące frameworka
- Brak metadanych DICOM. Renderowanie stron DICOM, pojedyncze klatki, animacja, przekształcenia i znakowanie wodne są obsługiwane. Metadane techniczne tagów nie są dostępne w pakiecie .NET 6, ponieważ czytnik metadanych nie ma kompilacji .NET 6.
Viewer.GetDicomMetadataAsync(token)dlatego zwracanulldla sesji DICOM i loguje jednorazowe ostrzeżenie. Odpowiednie żądanie?token=…&meta=1zwraca HTTP501 Not Implementedz trwałym kodem błędudicom_metadata_unsupported. Użyj pakietu .NET 8, gdy techniczne metadane DICOM są wymagane.
Czy ta strona była pomocna?