Плагін DICOM

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

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

У .NET Framework 4.7.2 файли DICOM відображаються повністю — сторінки, кадри та анімація — але технічні метадані (теги DICOM) недоступні. Viewer.GetDicomMetadataAsync завжди повертає null, а запит метаданих переглядача (?token=…&meta=1 на DocImage.axd) відповідає 404, тому переглядач не показує панель властивостей DICOM. Використовуйте Doconut.NET8, якщо вашому застосунку потрібні теги.

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

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

Встановлення пакету

powershell
Install-Package Doconut.NETFramework.Dicom

Щоб закріпити плагін за випуском, який описує ця документація:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

Тримайте пакет DICOM тієї ж версії, що і Doconut.NETFramework.

Файл ліцензії плагіна, Doconut.Viewer.Dicom.lic, розташовується в тій же папці, що і Doconut.Viewer.lic; його читають разом з ліцензією переглядача.

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

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

Плагін (Name: "Doconut DICOM Viewer") реєструє переглядачі для розширень .dcm та .ima, обмежені можливістю Dicom. Якщо ліцензія не надає її, DoconutHost.Initialize генерує виключення з Application_Start:

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.

У System.Web це означає, що кожен запит повертає порожній 500, а причина записана лише в журналі подій Windows (джерело ASP.NET). Виключення виникає через відсутність ліцензії, застарілий файл TRIAL, ліцензію без Dicom, а також платну ліцензію, використану поза її часовим вікном. Тимчасові ліцензії Demo/NFR приймаються. Дивіться Налаштування ліцензії.

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

text
LicenseException: This document type requires the 'Dicom' plugin license.

Ліцензування та водяний знак

Стан ліцензіїЗапускВивід DICOM
Платна ліцензія, що надає Dicom, у межах її часових рамокЗапускаєтьсяВідображається згідно звичайних правил водяного знака сторінки
Активна тимчасова (Demo/NFR) ліцензіяЗапускаєтьсяВідображається з водяним знаком оцінки
Відсутня ліцензія, застарілий файл TRIAL, ліцензія без Dicom, або платна ліцензія поза її часовими рамкамиApplication_Start генерує виключення; кожен запит повертає порожній 500—

Рішення щодо звичайного водяного знака сторінки також застосовується до виводу DICOM. Для анімованого виводу кожен кадр GIF позначається, тому знак залишається видимим протягом відтворення. Користувацький DocOptions.Watermark використовується лише коли ліцензія дозволяє користувацькі водяні знаки; його не можна замінити на водяний знак оцінки.

Використання з C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// У .NET Framework це завжди null: читач метаданих DICOM недоступний для цього
// target. Сторінки, кадри та анімація відображаються нормально.

Метод існує в цьому пакеті, щоб код, спільний з пакетом .NET 8, компілювався, але читання DICOM‑тегів потребує компонента, який не має збірки для .NET Framework. Плануйте інтерфейс користувача без них — наприклад, сховайте панель метаданих, коли результат є null.

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

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

Багатокадрові 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 = безкінечний цикл).

Переглядач визначає, що сторінка 1 анімована, надсилаючи запит HEAD для неї. Обробник DocImage.axd повинен тому приймати HEAD у Web.config (verb="GET,HEAD,POST", див. Встановлення); без цього IIS відповідає 404 до запуску Doconut, і виявлення анімації ніколи не працює.

Роздільна здатність

DicomConfig виводить з 100 DPI на вісь за замовчуванням. Якщо ви не задаєте явно HorizontalResolution/VerticalResolution, вони слідують за BaseConfig.ImageResolution, коли він встановлений, і лише тоді повертаються до 100.

csharp
// Рівномірний підйом через базову властивість…
new DicomConfig { ImageResolution = 150 };

// …або керування по осях
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

Створіть власний інтерфейс

Зображення сторінок, включаючи анімовану першу сторінку, використовують стандартний маршрут зображень DocImage.axd. Запит метаданих, GET /DocImage.axd?token=<token>&meta=1, повертає 404 у цьому пакеті для кожного документа, включаючи DICOM‑файли, оскільки читач метаданих недоступний.

У продакшн‑середовищі

Багатокадрові дослідження можуть створювати як анімацію, так і одну статичну сторінку на кадр. AnimationAndFrames забезпечує найповнішу навігацію, але й найвищі витрати на рендеринг та пам'ять — і на одному сервері ця пам'ять належить процесу‑робітнику IIS. Для великих досліджень:

  • використовуйте FramesOnly, коли перевірка кадрів важливіша за відтворення;
  • уникайте збільшення обох осей роздільної здатності без вимірювання пам'яті;
  • закривайте сесію явно, коли дослідження більше не відкрите;
  • залишайте CachePages увімкненим лише тоді, коли повторний доступ вартий збережених зображень.

Розмістіть Doconut.Viewer.Dicom.lic поруч із Doconut.Viewer.lic на кожному сервері та залишайте HEAD у списку verb обробника.

Посилання на 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 у цьому пакеті. Викидає InvalidOperationException, коли токен невідомий або прострочений. DicomMetadata визначено, щоб код, спільний з пакетом .NET 8, компілювався.

Усунення проблем

СимптомПричинаВиправлення
Кожен запит відповідає порожнім 500 після додавання плагіна; журнал подій Windows (джерело ASP.NET) показує 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>() у DoconutHost.Initialize і розгорніть пакет
Відкриття файлу .dcm викликає LicenseException: This document type requires the 'Dicom' plugin license.Завантажена ліцензія більше не надає DicomВстановіть ліцензію, яка надає Dicom
З’являється лише одна сторінкаДжерело однокадрове, або DisplayMode є AnimationOnlyВикористайте FramesOnly або AnimationAndFrames для багатокадрового джерела
Сторінка 1 не анімуєтьсяОбробник у Web.config не приймає HEADВикористайте verb="GET,HEAD,POST"
Анімація занадто швидка або повільнаAnimationFrameDelayMs вимкнено; таймінг GIF використовує одиниці по 10 мсНалаштуйте AnimationFrameDelayMs
Пам’ять зростає при великих багатокадрових файлахРежим відображення, роздільна здатність та кеш сторінок додають збережені зображенняДивіться У продакшені; закривайте сеанси явно
Метадані завжди nullОчікується в цьому пакетіВикористовуйте пакет .NET 8, коли потрібні теги
GetDicomMetadataAsync викликає Document session not found. Please re-open document.Токен прострочений або ніколи не відкривавсяВідкрийте документ знову

Примітки щодо фреймворку

У порівнянні з пакетами ASP.NET Core, цей пакет відрізняється хостингом та метаданими DICOM:

  • Реєстрація знаходиться у Application_Start, через DoconutHost.Initialize, замість builder.Services.AddDoconut.
  • Помилки запуску проявляються як порожній 500 у кожному запиті, причину можна знайти у журналі подій Windows.
  • Виявлення анімації потребує HEAD у списку verb обробника DocImage.axd.
  • Немає метаданих DICOM. Viewer.GetDicomMetadataAsync завжди повертає null і записує одноразове попередження для DICOM сесії; запит метаданих DocImage.axd відповідає 404, а не 501 пакетів .NET 6 та .NET Standard.
  • Тільки Windows, як і решта пакетів .NET Framework.

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