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.GetDicomMetadataAsync zawsze zwraca null, a żądanie metadanych przeglądarki (?token=…&meta=1 na DocImage.axd) odpowiada 404, więc przeglądarka nie wyświetla panelu właściwości DICOM. Użyj Doconut.NET8 jeśli twoja aplikacja potrzebuje tagów.

PowierzchniaKiedy używać
Viewer z DicomConfig (C#)Otwierasz pliki DICOM na serwerze i wybierasz, jak prezentowane są ich klatki
Przeglądarka (docViewer) na DocImage.axdWyś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

powershell
Install-Package Doconut.NETFramework.Dicom

Aby przypiąć wtyczkę do wydania opisanego w tej dokumentacji:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

Utrzymuj 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

csharp
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:

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.

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:

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 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 wersjiApplication_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#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
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):

TrybStrony generowaneZastosowanie
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 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.

csharp
// 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 CachePages włą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

csharp
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

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
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

ObjawPrzyczynaRozwią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 wersjiZainstaluj 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żonyDodaj 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ż 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
Strona 1 nie animuje sięObsługa w Web.config nie akceptuje HEADUżyj verb="GET,HEAD,POST"
Animacja jest zbyt szybka lub zbyt wolnaAnimationFrameDelayMs jest wyłączone; timing 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 jawnie
Metadane są zawsze nullOczekiwane w tym pakiecieUżyj pakietu .NET 8, gdy potrzebujesz tagów
GetDicomMetadataAsync rzuca Document session not found. Please re-open document.Token wygasł lub nigdy nie został otwartyOtwó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, przez DoconutHost.Initialize, zamiast builder.Services.AddDoconut.
  • Błędy uruchamiania pojawiają się jako pusty 500 przy każdym żądaniu, z przyczyną w dzienniku zdarzeń Windows.
  • Wykrywanie animacji wymaga HEAD w liście verb obsługi DocImage.axd.
  • Brak metadanych DICOM. Viewer.GetDicomMetadataAsync zawsze zwraca null i loguje jednorazowe ostrzeżenie dla sesji DICOM; żądanie metadanych DocImage.axd odpowiada 404, a nie 501 pakietów .NET 6 i .NET Standard.
  • Tylko Windows, jak reszta pakietu .NET Framework.

Czy ta strona była pomocna?