Wtyczka DICOM
Wyświetl obrazy medyczne za pomocą DicomPlugin
Wtyczka DICOM dodaje możliwość przeglądania obrazów medycznych do Doconut: pliki DICOM wieloklatkowe renderują się 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ć otwarte wcale.
W .NET Framework 4.7.2 pliki DICOM renderują się w pełni — strony, klatki i animacja — ale techniczne metadane (tagi DICOM) nie są dostępne.
Viewer.GetDicomMetadataAsynczawsze zwracanull, a żądanie metadanych przeglądarki (?token=…&meta=1naDocImage.axd) odpowiada404, więc przeglądarka nie wyświetla panelu właściwości DICOM. UżyjDoconut.NET8jeśli twoja aplikacja potrzebuje tagów.
| Powierzchnia | Kiedy używać |
|---|---|
Viewer z DicomConfig (C#) | Otwierasz pliki DICOM na serwerze i wybierasz, jak prezentowane są ich klatki |
Przeglądarka (docViewer) na DocImage.axd | Wyświetlasz badanie na swojej stronie: animacja i klatki |
Wtyczka nie posiada własnego widgetu: pliki DICOM otwierają się w zwykłej przeglądarce. Z zarejestrowaną również Wtyczka Converter, pliki .dcm i .ima mogą być konwertowane na Pdf, Png, Jpeg, Bmp, Tiff lub Gif; ta konwersja wymaga również możliwości Dicom.
Instalacja pakietu
Install-Package Doconut.NETFramework.DicomAby przypiąć wtyczkę do wydania opisanego w tej dokumentacji:
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0Utrzymuj pakiet DICOM w tej samej wersji co Doconut.NETFramework.
Plik licencji wtyczki, Doconut.Viewer.Dicom.lic, znajduje się w tym samym folderze co Doconut.Viewer.lic; jest odczytywany razem z licencją przeglądarki.
Rejestracja wtyczki
Doconut.DoconutHost.Initialize(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});Wtyczka (Name: "Doconut DICOM Viewer") rejestruje przeglądarki dla rozszerzeń .dcm i .ima, kontrolowane przez możliwość Dicom. Jeśli licencja jej nie przyznaje, DoconutHost.Initialize zgłasza wyjątek z Application_Start:
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.W System.Web oznacza to, że każde żądanie zwraca pusty 500, a przyczyna jest widoczna tylko w dzienniku zdarzeń Windows (źródło ASP.NET). Zgłasza wyjątek 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 Ustawienia licencji.
Ponieważ żadna wbudowana przeglądarka nie obsługuje tych formatów, otwarcie takiego pliku kończy się niepowodzeniem, jeśli później możliwość 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 znakowania strony |
| Aktywna tymczasowa licencja (Demo/NFR) | Uruchamia się | Renderowane z znakowaniem ewaluacyjnym |
Brak licencji, starszy plik TRIAL, licencja bez Dicom lub płatna licencja poza jej oknem wersji | Application_Start zgłasza wyjątek; każde żądanie zwraca pusty 500 | — |
Decyzja o normalnym znakowaniu strony ma również zastosowanie do wyjścia DICOM. W przypadku wyjścia animowanego, każda klatka GIF jest znakowana, więc znak pozostaje widoczny przez cały odtwarzanie. Niestandardowy DocOptions.Watermark jest używany tylko wtedy, gdy licencja zezwala na niestandardowe znaki wodne; nie może zastąpić znaku wodnego ewaluacyjnego.
Użycie z C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});var metadata = await viewer.GetDicomMetadataAsync(token);
// W .NET Framework jest to zawsze null: czytnik metadanych DICOM nie jest dostępny dla tego
// target. Strony, klatki i animacja renderują się normalnie.Metoda istnieje w tym pakiecie, aby kod współdzielony z pakietem .NET 8 kompilował się, ale odczyt tagów DICOM wymaga komponentu, który nie ma wersji dla .NET Framework. Zaplanuj interfejs użytkownika bez nich — na przykład ukryj panel metadanych, gdy wynik jest null.
Tryby wyświetlania i rozdzielczość
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ę | 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 i szczegóły w jednym dokumencie |
Czas trwania animacji jest kontrolowany przez AnimationFrameDelayMs (domyślnie 100 ms = 10 FPS; timing GIF używa jednostek 10 ms) oraz LoopCount (0 = pętla nieskończona).
Przeglądarka ustala, że strona 1 jest animowana, wysyłając żądanie HEAD. Obsługa DocImage.axd musi więc akceptować HEAD w Web.config (verb="GET,HEAD,POST", zobacz Instalacja); bez tego IIS odpowiada 404 zanim uruchomi się Doconut i wykrywanie animacji nigdy nie działa.
Rozdzielczość
DicomConfig renderuje domyślnie z 100 DPI na oś. Jeśli nie ustawisz explicite HorizontalResolution/VerticalResolution, podążają za BaseConfig.ImageResolution, gdy jest ustawione, i dopiero wtedy wracają do 100.
// Jednolity przyrost za pomocą właściwości bazowej…
new DicomConfig { ImageResolution = 150 };
// …lub kontrola na poszczególnych osiach
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Zbuduj własny interfejs
Obrazy stron, w tym animowana pierwsza strona, używają standardowej trasy obrazu DocImage.axd. Żądanie metadanych, GET /DocImage.axd?token=<token>&meta=1, zwraca 404 w tym pakiecie dla każdego dokumentu, w tym plików DICOM, ponieważ czytnik metadanych nie jest dostępny.
W produkcji
Badania wieloklatkowe mogą generować zarówno animację, jak i jedną statyczną stronę na klatkę. AnimationAndFrames zapewnia najbogatszą nawigację, ale także najwyższy koszt renderowania i pamięci — a na pojedynczym serwerze ta pamięć należy do procesu roboczego IIS. Dla dużych badań:
- użyj
FramesOnly, gdy inspekcja klatek jest ważniejsza niż odtwarzanie; - 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 powtarzany dostęp jest wart zachowanych obrazów.
Umieść Doconut.Viewer.Dicom.lic obok Doconut.Viewer.lic na każdym serwerze i zachowaj HEAD na liście verb obsługi.
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; } // 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);Zawsze zwraca null w tym pakiecie. Rzuca InvalidOperationException, gdy token jest nieznany lub wygasł. DicomMetadata jest zdefiniowane, aby kod współdzielony z pakietem .NET 8 się kompilował.
Rozwiązywanie problemów
| Objaw | Przyczyna | Rozwiązanie |
|---|---|---|
Każde żądanie zwraca pusty 500 po dodaniu wtyczki; dziennik zdarzeń Windows (źródło ASP.NET) pokazuje 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 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 zarejestrowane, lub jego pakiet nie został wdrożony | Dodaj AddPlugin<DicomPlugin>() w DoconutHost.Initialize i wdroż pakiet |
Otwieranie pliku .dcm rzuca LicenseException: This document type requires the 'Dicom' plugin license. | Załadowana licencja nie przyznaje już 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 |
| Strona 1 nie animuje się | Obsługa w Web.config nie akceptuje HEAD | Użyj verb="GET,HEAD,POST" |
| Animacja jest zbyt szybka lub zbyt wolna | AnimationFrameDelayMs jest wyłączone; timing 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ą zawsze null | Oczekiwane w tym pakiecie | 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 |
Notatki o frameworku
W porównaniu z pakietami ASP.NET Core, ten pakiet różni się pod względem hostingu i metadanych DICOM:
- Rejestracja znajduje się w
Application_Start, przezDoconutHost.Initialize, zamiastbuilder.Services.AddDoconut. - Błędy uruchamiania pojawiają się jako pusty
500przy każdym żądaniu, z przyczyną w dzienniku zdarzeń Windows. - Wykrywanie animacji wymaga
HEADw liścieverbobsługiDocImage.axd. - Brak metadanych DICOM.
Viewer.GetDicomMetadataAsynczawsze zwracanulli loguje jednorazowe ostrzeżenie dla sesji DICOM; żądanie metadanychDocImage.axdodpowiada404, a nie501pakietów .NET 6 i .NET Standard. - Tylko Windows, jak reszta pakietu .NET Framework.
Czy ta strona była pomocna?