Плагин DICOM

Просмотр медицинских изображений с DicomPlugin

Плагин DICOM добавляет просмотр медицинских изображений в Doconut: многокадровые файлы DICOM отображаются как анимированный обзор, отдельные кадры или оба варианта. DICOM — это формат только для плагина — без этого плагина (и его лицензии) файлы .dcm открыть невозможно.

В .NET Framework 4.7.2 файлы DICOM отображаются полностью — страницы, кадры и анимация — но технические метаданные (теги DICOM) недоступны. Viewer.GetDicomMetadataAsync всегда возвращает null, а запрос метаданных просмотрщика (?token=…&meta=1 на DocImage.axd) отвечает 404, поэтому просмотрщик не показывает панель свойств DICOM. Используйте Doconut.NET8, если вашему приложению нужны теги.

СредаКогда использовать
Viewer with DicomConfig (C#)Вы открываете файлы DICOM на сервере и выбираете, как представлять их кадры
Просмотрщик (docViewer) на DocImage.axdВы показываете исследование на своей странице: анимацию и кадры

У плагина нет собственного виджета: файлы DICOM открываются в обычном просмотрщике. При также зарегистрированном Converter plugin файлы .dcm и .ima могут быть преобразованы в Pdf, Png, Jpeg, Bmp, Tiff или Gif; для этого преобразования также требуется возможность Dicom.

Установка пакета

powershell
Install-Package Doconut.NETFramework.Dicom

Чтобы закрепить плагин за релизом, описанным в этой документации:

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

Сохраняйте пакет DICOM той же версии, что и Doconut.NETFramework.

Файл лицензии плагина, Doconut.Viewer.Dicom.lic, помещается в ту же папку, что и Doconut.Viewer.lic; он читается вместе с лицензией просмотрщика.

Регистрация плагина

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Плагин (Name: "Doconut DICOM Viewer") регистрирует просмотрщики для расширений .dcm и .ima, ограниченные возможностью Dicom. Если лицензия не предоставляет её, DoconutHost.Initialize выбрасывает из 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.

В System.Web это означает, что каждый запрос возвращает пустой 500, а причина указана только в журнале событий Windows (источник ASP.NET). Выбрасывается при отсутствии лицензии, при наличии устаревшего файла TRIAL, лицензии без Dicom и при использовании платной лицензии вне её временного окна. Принимаются временные лицензии Demo/NFR. См. License Setup.

Поскольку ни один встроенный просмотрщик не поддерживает эти форматы, попытка открыть файл сразу завершается ошибкой, если возможность позже становится недоступной:

text
LicenseException: This document type requires the 'Dicom' plugin license.

Лицензирование и водяной знак

Состояние лицензииЗапускВывод DICOM
Платная лицензия, предоставляющая Dicom, в пределах её временного окнаЗапускаетсяОтображается согласно обычным правилам водяного знака страницы
Активная временная (Demo/NFR) лицензияЗапускаетсяОтображается с оценочным водяным знаком
Отсутствие лицензии, устаревший файл TRIAL, лицензия без Dicom или платная лицензия вне её временного окнаApplication_Start выбрасывает; каждый запрос возвращает пустой 500—

Обычное решение о водяном знаке страницы также применяется к выводу DICOM. Для анимированного вывода каждый кадр GIF помечается, поэтому знак остаётся видимым на протяжении воспроизведения. Пользовательский DocOptions.Watermark используется только когда лицензия позволяет пользовательские водяные знаки; он не может заменить оценочный водяной знак.

Использование из C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// В .NET Framework это всегда null: читатель метаданных DICOM недоступен для этого
// target. Страницы, кадры и анимация отображаются нормально.

Метод существует в этом пакете, чтобы код, совместный с пакетом .NET 8, компилировался, но чтение тегов DICOM требует компонента, который не имеет сборки для .NET Framework. Планируйте ваш пользовательский интерфейс без них — например, скрывайте панель метаданных, когда результат равен null.

Режимы отображения и разрешение

Режимы отображения

Многокадровые файлы DICOM могут быть представлены тремя способами (DicomDisplayMode):

РежимСозданные страницыПрименение
AnimationOnlyСтраница 1 = анимированный GIF, повторяющий все кадрыБыстрый кинематографический обзор
FramesOnlyСтраницы 1..N = один статический PNG на кадрПошаговая диагностическая навигация
AnimationAndFrames (по умолчанию)Страница 1 = анимированный GIF, страницы 2..N+1 = один статический PNG на кадр (N = количество кадров)Обзор и детали в одном документе

Время анимации контролируется AnimationFrameDelayMs (по умолчанию 100 мс = 10 FPS; тайминг GIF использует единицы в 10 мс) и LoopCount (0 = бесконечный цикл).

Просмотрщик определяет, что страница 1 анимирована, отправляя запрос HEAD. Поэтому обработчик DocImage.axd должен принимать HEAD в Web.config (verb="GET,HEAD,POST", см. Установка); без этого IIS отвечает 404 до запуска Doconut, и обнаружение анимации никогда не срабатывает.

Разрешение

DicomConfig рендерится с 100 DPI по каждой оси по умолчанию. Если вы явно не задаете HorizontalResolution/VerticalResolution, они следуют за BaseConfig.ImageResolution, когда он установлен, и только затем возвращаются к 100.

csharp
// Равномерный прирост через базовое свойство…
new DicomConfig { ImageResolution = 150 };

// …или управление по осям
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Создайте собственный фронтенд

Изображения страниц, включая анимированную первую страницу, используют стандартный маршрут изображений DocImage.axd. Запрос метаданных, GET /DocImage.axd?token=<token>&meta=1, возвращает 404 в этом пакете для каждого документа, включая файлы DICOM, поскольку считыватель метаданных недоступен.

В продакшене

Многокадровые исследования могут создавать как анимацию, так и одну статическую страницу на кадр. AnimationAndFrames обеспечивает наиболее богатую навигацию, но также требует наибольших затрат на рендеринг и память — и на одном сервере эта память принадлежит процессу рабочего потока IIS. Для больших исследований:

  • используйте FramesOnly, когда проверка кадров важнее воспроизведения;
  • избегайте увеличения обеих осей разрешения без измерения памяти;
  • закрывайте сессию явно, когда исследование больше не открыто;
  • оставляйте CachePages включённым только тогда, когда повторный доступ стоит сохранённых изображений.

Разместите Doconut.Viewer.Dicom.lic рядом с Doconut.Viewer.lic на каждом сервере и держите HEAD в списке verb обработчика.

Справочник API

DicomConfig, DicomDisplayMode и DicomMetadata находятся в пространстве имён Doconut. DicomPlugin находится в Doconut.Plugins.Dicom. Полная таблица свойств DicomConfig находится в Конфигурации формата.

Конфигурация DICOM

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // по умолчанию: ImageResolution, если задано, иначе 100
    public int VerticalResolution { get; set; }     // по умолчанию: ImageResolution, если задано, иначе 100
    public int AnimationFrameDelayMs { get; set; } = 100;
    public ushort LoopCount { get; set; } = 0;      // 0 = бесконечный цикл
    public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}

Режим отображения DICOM

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

Всегда возвращает null в этом пакете. Выбрасывает InvalidOperationException, когда токен неизвестен или истёк. DicomMetadata определён, чтобы код, общий с пакетом .NET 8, компилировался.

Устранение неполадок

СимптомПричинаРешение
Каждый запрос возвращает пустой 500 после добавления плагина; журнал событий Windows (источник ASP.NET) показывает The Dicom plugin is registered via AddPlugin but no active license grants Dicom.Отсутствует лицензия, файл TRIAL, лицензия без Dicom или платная лицензия вне её версииУстановите лицензию, предоставляющую Dicom, или удалите AddPlugin<DicomPlugin>()
Открытие файла .dcm вызывает Document format '.dcm' is not supported.DicomPlugin не зарегистрирован, или его пакет не развернутДобавьте AddPlugin<DicomPlugin>() в DoconutHost.Initialize и разверните пакет
Открытие файла .dcm вызывает LicenseException: This document type requires the 'Dicom' plugin license.Загруженная лицензия больше не предоставляет DicomУстановите лицензию, предоставляющую Dicom
Отображается только одна страницаИсточник однокадровый, или DisplayMode является AnimationOnlyИспользуйте FramesOnly или AnimationAndFrames для многокадрового источника
Страница 1 не анимируетсяОбработчик в Web.config не принимает HEADИспользуйте verb="GET,HEAD,POST"
Анимация слишком быстрая или медленнаяAnimationFrameDelayMs отключён; тайминг GIF использует единицы в 10 мсОтрегулируйте AnimationFrameDelayMs
Память растёт при больших многокадровых файлахРежим отображения, разрешение и кэш страниц добавляют сохраняемые изображенияСмотрите В продакшене; закрывайте сеансы явно
Метаданные всегда nullОжидается в этом пакетеИспользуйте пакет .NET 8, когда нужны теги
GetDicomMetadataAsync вызывает Document session not found. Please re-open document.Токен истёк или никогда не открывалсяОткройте документ снова

Примечания к фреймворку

По сравнению с пакетами ASP.NET Core, этот пакет отличается хостингом и метаданными DICOM:

  • Регистрация находится в Application_Start, через DoconutHost.Initialize, вместо builder.Services.AddDoconut.
  • Сбои при запуске проявляются как пустой 500 на каждом запросе, причина указана в журнале событий Windows.
  • Обнаружение анимации требует HEAD в списке verb обработчика DocImage.axd.
  • Нет метаданных DICOM. Viewer.GetDicomMetadataAsync всегда возвращает null и записывает одноразовое предупреждение для DICOM‑сессии; запрос метаданных DocImage.axd отвечает 404, а не 501 пакетов .NET 6 и .NET Standard.
  • Только Windows, как и остальные пакеты .NET Framework.

Была ли эта страница полезной?