DICOM Плагин
Просмотр медицинских изображений с DicomPlugin
Плагин DICOM добавляет просмотр медицинских изображений в Doconut: многокадровые файлы DICOM отображаются как анимированный обзор, отдельные кадры или оба варианта. DICOM — это только‑плагинный формат — без этого плагина (и его лицензионной возможности) файлы .dcm открыть невозможно.
| Среда | Когда использовать |
|---|---|
Viewer with DicomConfig (C#) | Вы открываете файлы DICOM на сервере и выбираете, как будут представлены их кадры |
Просмотрщик (docViewer) | Вы показываете исследование на своей странице: анимацию, кадры и панель свойств DICOM |
HTTP‑конечная точка (?token=<token>&meta=1) | Вы читаете технические метаданные со своего фронтенда |
У плагина нет собственного виджета: файлы DICOM открываются в обычном просмотрщике. При также зарегистрированном Плагине конвертера файлы .dcm и .ima могут быть преобразованы в Pdf, Png, Jpeg, Bmp, Tiff или Gif; для этого преобразования также требуется возможность Dicom.
Установить пакет
dotnet add package Doconut.NET8.DicomКоманда без указания версии устанавливает последнюю стабильную версию. Чтобы зафиксировать плагин на версии, описанной в этой документации, передайте версию отдельно:
dotnet add package Doconut.NET8.Dicom --version 26.10.0Держите пакет DICOM той же версии, что и Doconut.NET8. Идентификатор пакета — Doconut.NET8.Dicom; .<version> появляется только в имени загруженного файла .nupkg.
Файл лицензии плагина, Doconut.Viewer.Dicom.lic, помещается в ту же папку, что и Doconut.Viewer.lic; он читается вместе с лицензией просмотрщика.
Платформы. Плагин работает везде, где работает Doconut.NET8: Windows и Linux на основе glibc для x64 (не Alpine и другие дистрибутивы на musl). В Linux установите библиотеку конфигурации шрифтов перед открытием первого документа:
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.
Зарегистрировать плагин
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});Плагин (Name: "Doconut DICOM Viewer") регистрирует просмотрщики для расширений .dcm и .ima, ограниченные возможностью Dicom. Без лицензии, предоставляющей её, AddDoconut() генерирует InvalidOperationException при запуске, до того как приложение обслужит запрос:
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. См. Настройка лицензий для информации о загрузке лицензий.
Поскольку ни один встроенный просмотрщик не обрабатывает эти форматы, ограничение времени выполнения также приводит к жесткой ошибке, если возможность позже становится недоступной:
LicenseException: This document type requires the 'Dicom' plugin license.Лицензирование и водяной знак
| Состояние лицензии | Запуск | Вывод DICOM |
|---|---|---|
Платная лицензия, предоставляющая Dicom, в пределах её периода действия | Запускается | Отображается согласно обычным правилам водяного знака страницы |
| Активная временная (Demo/NFR) лицензия | Запускается | Отображается с оценочным водяным знаком |
Отсутствие лицензии, устаревший файл TRIAL, лицензия без Dicom или платная лицензия вне её периода действия | AddDoconut() генерирует | — |
Обычное решение о водяном знаке страницы также применяется к выводу DICOM. Для анимированного вывода каждый кадр GIF помечается, чтобы знак оставался видимым на протяжении воспроизведения. Пользовательский DocOptions.Watermark используется только когда путь лицензии позволяет пользовательские водяные знаки; он не может заменить оценочный водяной знак.
Использование из C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Для сеансов, открытых через этот плагин, Viewer предоставляет метаданные тегов:
var metadata = await 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.
// Равномерное увеличение через базовое свойство…
new DicomConfig { ImageResolution = 150 };
// …или управление по осям
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Метаданные
DicomMetadata содержит только технические и визуальные теги — количество кадров, размеры, глубину цвета, фотометрическую интерпретацию, синтаксис передачи, модальность и уровень окна по умолчанию. Он не содержит данных, позволяющих идентифицировать пациента. Полный список находится в Справочник API.
В просмотрщике
Просмотрщику не требуется специфическая настройка DICOM. Когда открытый документ является DICOM‑файлом, он запрашивает метаданные (?token=<token>&meta=1) и добавляет кнопку DICOM, открывающую панель технических свойств. Если запрос не удался, панель остаётся скрытой, но документ всё равно отображается.
Создайте собственный фронтенд
Метаданные доступны по HTTP по пути, где смонтирован UseDoconut() (обычно /doconut), для любого токена открытого документа:
| Маршрут | Назначение | Ответ при успехе |
|---|---|---|
GET ?token=<token>&meta=1 | Прочитать технические метаданные открытого DICOM‑документа | 200 — DicomMetadata в виде JSON, с именами свойств из Справочник API (Width, Height, NumberOfFrames, …) |
| Статус | Когда | Тело |
|---|---|---|
404 | Документ не является DICOM‑файлом | только статус |
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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);Возвращает null, когда документ не является файлом DICOM. Вызывает InvalidOperationException, когда токен неизвестен или истёк.
DicomMetadata
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 | Проверьте тип файла перед запросом метаданных |
GetDicomMetadataAsync вызывает Document session not found. Please re-open document. | Токен истёк или никогда не был открыт | Откройте документ снова |
Была ли эта страница полезной?