Плагін 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 (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, яка відкриває панель технічних властивостей. Якщо цей запит не вдається, панель залишається прихованою, а документ все одно відображається.
Створіть власний інтерфейс
Метадані доступні через 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;
}DicomDisplayMode
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" 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 | Перевірте тип файлу перед запитом метаданих |
GetDicomMetadataAsync генерує Document session not found. Please re-open document. | Токен прострочений або ніколи не був відкритий | Відкрийте документ знову |
Чи була ця сторінка корисною?