Плагин DICOM

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

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

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

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

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

bash
dotnet add package Doconut.NET6.Dicom

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

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

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

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

Платформы. Плагин работает везде, где работает Doconut.NET6: Windows и Linux на базе glibc для x64 (не Alpine и другие дистрибутивы на musl). В Linux установите библиотеку конфигурации шрифтов (например, libfontconfig1) перед открытием первого документа:

bash
apt-get update && apt-get install -y libfontconfig1

В RHEL, Fedora и подобных дистрибутивах пакет называется fontconfig. Без него открытие документа приводит к ошибке The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation..

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

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. См. Настройка лицензии для информации о загрузке лицензий.

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

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 (default)Страница 1 = анимированный GIF, страницы 2..N+1 = один статический PNG на кадр (N = количество кадров)Обзор + детали в одном документе

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

Разрешение

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

csharp
// Равномерный бамп через базовое свойство…
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; }   // по умолчанию: 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;
}

DicomDisplayMode

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 6; рендеринг не затронутИспользуйте пакет .NET 8, когда нужны теги
GetDicomMetadataAsync вызывает Document session not found. Please re-open document.Токен истёк или никогда не открывалсяОткройте документ снова

Заметки о фреймворке

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

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