Плагин DICOM
Просмотр медицинских изображений с DicomPlugin
Плагин DICOM добавляет просмотр медицинских изображений в Doconut: многокадровые файлы DICOM отображаются как анимированный обзор, отдельные кадры или и то, и другое. DICOM — это формат только для плагина — без этого плагина (и его возможности лицензирования) файлы .dcm открыть невозможно.
| Поверхность | Когда использовать |
|---|---|
Viewer с DicomConfig (C#) | Вы открываете файлы DICOM на сервере и выбираете, как будут представлены их кадры |
Просмотрщик (docViewer) | Вы показываете исследование на своей странице: анимацию и кадры |
У плагина нет собственного виджета: файлы DICOM открываются в обычном просмотрщике. При также зарегистрированном Плагине Converter файлы .dcm и .ima могут быть преобразованы в Pdf, Png, Jpeg, Bmp, Tiff или Gif; для этого преобразования также требуется возможность Dicom.
Установить пакет
dotnet add package Doconut.NET6.DicomКоманда без указания версии устанавливает последнюю стабильную версию. Чтобы зафиксировать плагин на версии, описанной в этой документации, укажите версию отдельно:
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) перед открытием первого документа:
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.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.
// Равномерный бамп через базовое свойство…
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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);Возвращает null, когда документ не является файлом DICOM, и всегда возвращает null в этом пакете. Выбрасывает 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 | Проверьте тип файла перед запросом метаданных |
Метаданные 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возвращает HTTP501 Not Implementedсо стабильным кодом ошибкиdicom_metadata_unsupported. Используйте пакет .NET 8, когда технические метаданные DICOM являются требованием.
Была ли эта страница полезной?