Плагин DICOM
Просмотр медицинских изображений с DicomPlugin
Плагин DICOM добавляет просмотр медицинских изображений в Doconut: многокадровые файлы DICOM отображаются как анимированный обзор, отдельные кадры или и то, и другое. DICOM — это только плагинный формат — без этого плагина (и его возможности лицензирования) файлы .dcm открыть невозможно.
| Поверхность | Когда использовать |
|---|---|
Viewer с DicomConfig (C#) | Вы открываете файлы DICOM на сервере и выбираете, как будут представлены их кадры |
Просмотрщик (docViewer) | Вы показываете исследование на своей странице: анимацию и кадры |
У плагина нет собственного виджета: файлы DICOM открываются в обычном просмотрщике. При также зарегистрированном Converter plugin файлы .dcm и .ima могут быть преобразованы в Pdf, Png, Jpeg, Bmp, Tiff или Gif; для такого преобразования также требуется возможность Dicom.
Установить пакет
dotnet add package Doconut.NETStandard.DicomКоманда без указания версии устанавливает последнюю стабильную версию. Чтобы зафиксировать плагин на версии, описанной в этой документации, укажите версию отдельно:
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; он читается вместе с лицензией просмотрщика.
Зарегистрировать плагин
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. Смотрите License Setup для информации о загрузке лицензий.
Поскольку ни один встроенный просмотрщик не поддерживает эти форматы, ограничение во время выполнения также приводит к жесткой ошибке, если возможность позже становится недоступной:
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 (по умолчанию) | Страница 1 = анимированный GIF, страницы 2..N+1 = один статический PNG на кадр (N = количество кадров) | Обзор + детали в одном документе |
Время анимации управляется AnimationFrameDelayMs (по умолчанию 100 мс = 10 FPS; гранулярность GIF — единицы по 10 мс) и LoopCount (0 = бесконечный цикл).
Разрешение
DicomConfig отображается с 100 DPI по каждой оси по умолчанию. Свойства разрешения имеют цепочку резервных значений, которую стоит знать: если вы явно не задаёте HorizontalResolution/VerticalResolution, они следуют за BaseConfig.ImageResolution, когда он настроен, и только затем возвращаются к 100.
// Равномерный 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
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
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 8, когда нужны теги |
GetDicomMetadataAsync вызывает Document session not found. Please re-open document. | Токен истёк или никогда не был открыт | Откройте документ снова |
Примечания к фреймворку
- Нет метаданных DICOM. Отображение страниц DICOM, отдельные кадры, анимация, трансформации и водяные знаки поддерживаются. Технические метаданные тегов недоступны в пакете .NET Standard, потому что считыватель метаданных поставляется только в сборке .NET 8.
Viewer.GetDicomMetadataAsync(token)поэтому возвращаетnullдля DICOM‑сессии и записывает одноразовое предупреждение. Соответствующий запрос?token=…&meta=1возвращает HTTP501 Not Implementedсо стабильным кодом ошибкиdicom_metadata_unsupported. Используйте пакет .NET 8, когда технические метаданные DICOM требуются. - Только Windows, как и остальная часть пакета .NET Standard.
Была ли эта страница полезной?