Плагин DICOM

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

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

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

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

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

bash
dotnet add package Doconut.NETStandard.Dicom

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

bash
dotnet add package Doconut.NETStandard.Dicom --version 26.10.0

Держите пакет DICOM на той же версии, что и Doconut.NETStandard. Идентификатор пакета — Doconut.NETStandard.Dicom; .<version> появляется только в имени загруженного файла .nupkg.

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

Зарегистрировать плагин

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Плагин (Name: "Doconut DICOM Viewer") регистрирует просмотрщики для расширений .dcm и .ima, доступ к которым контролируется возможностью Dicom. Без лицензии, предоставляющей её, AddDoconut() генерирует InvalidOperationException при запуске, до того как приложение обслужит запрос:

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.

Это происходит при отсутствии лицензии, при наличии устаревшего файла TRIAL, лицензии без Dicom, а также при использовании платной лицензии вне её периода действия. Принимаются временные лицензии Demo/NFR. Смотрите License Setup для информации о загрузке лицензий.

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

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

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

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

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

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

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});

Viewer.GetDicomMetadataAsync(token) существует в этом пакете, но возвращает null для сессии DICOM: см. Заметки о фреймворке.

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

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

Мульти‑кадровые 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 = бесконечный цикл).

Разрешение

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

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

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

Метаданные

DicomMetadata содержит только технические и визуальные теги — количество кадров, размеры, глубину цвета, фотометрическую интерпретацию, синтаксис передачи, модальность и уровень окна по умолчанию. Он не содержит данных, позволяющих идентифицировать пациента. Полный список находится в справочнике API. В этом пакете метаданные недоступны; см. заметки о фреймворке.

В просмотрщике

Просмотрщику не требуется специфическая настройка DICOM. Когда открытый документ является DICOM‑файлом, он запрашивает метаданные (?token=<token>&meta=1) и добавляет кнопку DICOM, открывающую панель технических свойств. Если запрос не удался, панель остаётся скрытой, и документ всё равно отображается. В этом пакете запрос возвращает 501, поэтому панель никогда не появляется.

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

Метаданные доступны по HTTP по пути, где смонтирован UseDoconut() (обычно /doconut), для любого токена открытого документа:

МаршрутНазначениеОтвет при успехе
GET ?token=<token>&meta=1Прочитать технические метаданные открытого DICOM‑документа200 — DicomMetadata в виде JSON, с именами свойств из справочника API (Width, Height, NumberOfFrames, …)
СтатусКогдаТело
404Документ не является DICOM‑файломтолько статус
501Документ является DICOM‑файлом, но этот пакет не может прочитать его теги{ "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Не удалось прочитать метаданные{ "error": "metadata failed" }

Изображения страниц, включая анимированную первую страницу, используют стандартный маршрут изображений просмотрщика.

В продакшене

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

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

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

Справочник API

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

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // default: ImageResolution если установлено, иначе 100
    public int VerticalResolution { get; set; }     // default: 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, когда документ не является DICOM‑файлом, и всегда возвращает null в этом пакете. Выбрасывает InvalidOperationException, когда токен неизвестен или истёк.

DicomMetadata

csharp
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" или "Signed"
    public string? PlanarConfiguration { get; init; }
    public string? TransferSyntax { get; init; }
    public string? Modality { get; init; }              // null, когда не раскрыт
    public double? WindowCenter { get; init; }
    public double? WindowWidth { get; init; }
    public bool IsColor { get; init; }
}

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

СимптомПричинаРешение
AddDoconut() вызывает 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>() внутрь AddDoconut() и разверните пакет
Открытие файла .dcm вызывает LicenseException: This document type requires the 'Dicom' plugin license.Загруженная лицензия больше не предоставляет DicomУстановите лицензию, предоставляющую Dicom
Появляется только одна страницаИсточник однокадровый, или DisplayMode является AnimationOnlyИспользуйте FramesOnly или AnimationAndFrames для многокадрового источника
Анимация слишком быстрая или медленнаяAnimationFrameDelayMs отключён; эффективное время GIF использует единицы 10 мсОтрегулируйте AnimationFrameDelayMs
Память растёт при больших многокадровых файлахРежим отображения, разрешение и кэш страниц добавляют сохраняемые изображенияСмотрите В продакшене; закрывайте сеансы явно
Метаданные nullДокумент не является DICOM‑файломПроверьте тип файла перед запросом метаданных
Метаданные null для DICOM‑файла, или &meta возвращает 501Ожидаемое ограничение этого пакета; рендеринг не затронутИспользуйте пакет .NET 8, когда нужны теги
GetDicomMetadataAsync вызывает Document session not found. Please re-open document.Токен истёк или никогда не был открытОткройте документ снова

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

  • Нет метаданных DICOM. Отображение страниц DICOM, отдельные кадры, анимация, трансформации и водяные знаки поддерживаются. Технические метаданные тегов недоступны в пакете .NET Standard, потому что считыватель метаданных поставляется только в сборке .NET 8. Viewer.GetDicomMetadataAsync(token) поэтому возвращает null для DICOM‑сессии и записывает одноразовое предупреждение. Соответствующий запрос ?token=…&meta=1 возвращает HTTP 501 Not Implemented со стабильным кодом ошибки dicom_metadata_unsupported. Используйте пакет .NET 8, когда технические метаданные DICOM требуются.
  • Только Windows, как и остальная часть пакета .NET Standard.

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