Плагін DICOM
Переглядайте медичні зображення за допомогою DicomPlugin
Плагін DICOM додає перегляд медичних зображень до Doconut: багатокадрові файли DICOM відображаються як анімований огляд, окремі кадри або і те, і інше. DICOM — це формат лише для плагінів — без цього плагіна (і його ліцензійної можливості) файли .dcm взагалі не можна відкрити.
| Середовище | Коли використовувати |
|---|---|
Viewer with DicomConfig (C#) | Ви відкриваєте файли DICOM на сервері та обираєте, як їхні кадри будуть представлені |
Переглядач (docViewer) | Ви показуєте дослідження на своїй сторінці: анімація та кадри |
Плагін не має власного віджета: файли DICOM відкриваються у звичайному переглядачі. За допомогою також зареєстрованого Плагін конвертера файли .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 встановіть бібліотеку налаштування шрифтів перед відкриттям першого документа:
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() генерує помилку | — |
Користується власний 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 є вимогою.
Чи була ця сторінка корисною?