Плагін DICOM

Переглядайте медичні зображення за допомогою DicomPlugin

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

СередовищеКоли використовувати
Viewer with DicomConfig (C#)Ви відкриваєте файли DICOM на сервері та обираєте, як їхні кадри будуть представлені
Переглядач (docViewer)Ви показуєте дослідження на своїй сторінці: анімація та кадри

Плагін не має власного віджета: файли DICOM відкриваються у звичайному переглядачі. За наявності також зареєстрованого Плагін Converter файли .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 ліцензії. Дивіться Налаштування ліцензії щодо завантаження ліцензій.

Оскільки жоден вбудований переглядач не обробляє ці формати, ворота виконання також жорстко падають, якщо можливість пізніше стає недоступною:

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: дивіться Нотатки щодо Framework.

Режими відображення, роздільна здатність та метадані

Режими відображення

Багатокадрові 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
// Однорідне підвищення через базову властивість…
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" or "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.

Чи була ця сторінка корисною?