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 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, w jaki sposób ich klatki są prezentowane |
Przeglądarka (docViewer) | Wyświetlasz badanie na swojej stronie: animację i klatki |
Wtyczka nie posiada własnego widgetu: pliki DICOM otwierają się w standardowej przeglądarce. Z Wtyczka konwertera również zarejestrowaną, pliki .dcm i .ima mogą być konwertowane na Pdf, Png, Jpeg, Bmp, Tiff lub Gif; ta konwersja wymaga również możliwości Dicom.
Zainstaluj pakiet
dotnet add package Doconut.NETStandard.DicomPolecenie bez wersji instaluje najnowsze stabilne wydanie. Aby przypiąć wtyczkę do wersji opisanej w tej dokumentacji, przekaż wersję osobno:
dotnet add package Doconut.NETStandard.Dicom --version 26.10.0Utrzymuj pakiet DICOM w tej samej wersji co Doconut.NETStandard. Identyfikator pakietu to
Doconut.NETStandard.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.
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 błąd przy braku licencji, starszym pliku TRIAL, licencji bez Dicom oraz płatnej licencji użytej poza jej okresem wersji. Tymczasowe licencje Demo/NFR są akceptowane. Zobacz Ustawienia licencji, aby dowiedzieć się, jak ładowane są licencje.
Ponieważ żaden wbudowany podgląd nie obsługuje tych formatów, bramka w czasie wykonania 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 jej oknem 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 zezwala na niestandardowe znaki wodne; nie może 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 dotyczące frameworka.
Tryby wyświetlania, rozdzielczość i metadane
Tryby wyświetlania
Pliki DICOM wieloklatkowe mogą być prezentowane na trzy sposoby (DicomDisplayMode):
| Tryb | Generowane strony | Zastosowanie |
|---|---|---|
AnimationOnly | Strona 1 = animowany GIF odtwarzający wszystkie klatki w pętli | Szybki przegląd kinowy |
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; rozdzielczość GIF to jednostki 10 ms) oraz LoopCount (0 = pętla nieskończona).
Rozdzielczość
DicomConfig renderuje domyślnie z 100 DPI na oś. Właściwości rozdzielczości mają łańcuch wartości domyślnych, który warto znać: jeśli nie ustawisz explicite HorizontalResolution/VerticalResolution, podążają one za BaseConfig.ImageResolution, gdy jest skonfigurowane, i dopiero wtedy wracają do 100.
// Jednolita wypukłość poprzez właściwość bazową…
new DicomConfig { ImageResolution = 150 };
// …lub sterowanie 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 umożliwiających identyfikację pacjenta. Pełna lista znajduje się w odniesieniu API. W tym pakiecie metadane nie są dostępne; zobacz notatki dotyczące 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 żądanie zwraca 501, więc panel nigdy się nie pojawia.
Zbuduj własny interfejs
Metadane są dostępne przez HTTP pod ścieżką, gdzie UseDoconut() jest zamontowany (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 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 kinowe; - unikaj zwiększania obu osi rozdzielczości bez pomiaru zużycia pamięci;
- zamknij sesję explicite, gdy badanie nie jest już otwarte;
- pozostaw
CachePageswłączony tylko wtedy, gdy korzyści z powtarzalnego 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 Format Configs.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // default: ImageResolution gdy ustawione, w przeciwnym razie 100
public int VerticalResolution { get; set; } // default: 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, oraz 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() 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 oknem 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 został 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 |
| Pojawia 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; efektywne 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 jawnie |
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 tego pakietu; renderowanie nie jest dotknięte | Użyj pakietu .NET 8, gdy potrzebujesz tagów |
GetDicomMetadataAsync rzuca Document session not found. Please re-open document. | Token wygasł lub nigdy nie został otwarty | Otwórz dokument ponownie |
Uwagi 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 Standard, ponieważ czytnik metadanych dostarcza tylko wersję .NET 8.
Viewer.GetDicomMetadataAsync(token)dlatego zwracanulldla sesji DICOM i zapisuje 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. - Tylko Windows, tak jak reszta pakietu .NET Standard.
Czy ta strona była pomocna?