افزونه DICOM

مشاهده تصاویر پزشکی با DicomPlugin

افزونه DICOM قابلیت مشاهده تصاویر پزشکی را به Doconut اضافه می‌کند: فایل‌های DICOM چند‑قابلی به صورت یک نمای کلی انیمیشنی، قاب‌های جداگانه یا هر دو رندر می‌شوند. DICOM یک فرمت فقط‑افزونه است — بدون این افزونه (و قابلیت لایسنس آن)، فایل‌های .dcm نمی‌توانند به‌طور کامل باز شوند.

سطحچه زمانی استفاده شود
Viewer با DicomConfig (C#)شما فایل‌های DICOM را بر روی سرور باز می‌کنید و نحوه ارائه قاب‌های آن‌ها را انتخاب می‌کنید
نمایشگر (docViewer)شما مطالعه را در صفحه خود نمایش می‌دهید: انیمیشن و قاب‌ها

این افزونه ویجت خاص خود را ندارد: فایل‌های DICOM در نمایشگر معمولی باز می‌شوند. با ثبت افزونه مبدل نیز، فایل‌های .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) در این بسته وجود دارد، اما برای یک جلسه DICOM مقدار null را برمی‌گرداند: به یادداشت‌های چارچوب مراجعه کنید.

حالت‌های نمایش، وضوح و فراداده

حالت‌های نمایش

فایل‌های DICOM چند‑قابلی می‌توانند به سه روش نمایش داده شوند (DicomDisplayMode):

ModePages producedUse for
AnimationOnlyPage 1 = animated GIF looping all framesمرور سریع سینمایی
FramesOnlyPages 1..N = one static PNG per frameناوبری تشخیصی قاب به قاب
AnimationAndFrames (default)Page 1 = animated GIF, pages 2..N+1 = one static PNG per frame (N = frame count)نمای کلی + جزئیات در یک سند

زمان‌بندی انیمیشن توسط AnimationFrameDelayMs (پیش‌فرض 100 ms = 10 FPS؛ دقت GIF واحدهای 10 ms است) و 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) برای هر توکن سند باز در دسترس است:

RoutePurposeSuccess response
GET ?token=<token>&meta=1خواندن فراداده فنی یک سند DICOM باز200 — DicomMetadata به‌صورت JSON، با نام‌های ویژگی‌های مرجع API (Width, Height, NumberOfFrames, …)
StatusWhenBody
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);

وقتی سند یک فایل DICOM نیست، null را برمی‌گرداند و در این بسته همیشه 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" یا "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 ثبت نشده است، یا بسته آن مستقر نشده استدر داخل AddDoconut()، AddPlugin<DicomPlugin>() را اضافه کنید و بسته را مستقر کنید
باز کردن یک فایل .dcm پرتاب می‌کند LicenseException: This document type requires the 'Dicom' plugin license.لایسنس بارگذاری‌شده دیگر Dicom را اعطا نمی‌کندیک لایسنس که Dicom را اعطا می‌کند نصب کنید
فقط یک صفحه ظاهر می‌شودمنبع تک‑فریم است، یا DisplayMode برابر با AnimationOnly استبرای منبع چند‑فریم از FramesOnly یا AnimationAndFrames استفاده کنید
انیمیشن خیلی سریع یا خیلی آهسته استAnimationFrameDelayMs خاموش است؛ زمان‌بندی مؤثر GIF از واحدهای ۱۰ میلی‌ثانیه استفاده می‌کندAnimationFrameDelayMs را تنظیم کنید
حافظه در فایل‌های چند‑فریم بزرگ افزایش می‌یابدحالت نمایش، وضوح و کش صفحه همگی تصاویر نگهداری‌شده را اضافه می‌کنندبه در تولید مراجعه کنید؛ جلسات را به‌صورت صریح ببندید
متادیتا null استسند یک فایل DICOM نیستقبل از درخواست متادیتا نوع فایل را بررسی کنید
متادیتا برای یک فایل DICOM null است، یا &meta برمی‌گرداند 501محدودیت مورد انتظار این بسته؛ رندرینگ تحت تأثیر قرار نمی‌گیردزمانی که به برچسب‌ها نیاز دارید، بسته .NET 8 را استفاده کنید
GetDicomMetadataAsync پرتاب می‌کند Document session not found. Please re-open document.توکن منقضی شده یا هرگز باز نشده استسند را دوباره باز کنید

نکات چارچوب

  • بدون متادیتای DICOM. رندر صفحه DICOM، فریم‌های جداگانه، انیمیشن، تبدیل‌ها و واترمارک پشتیبانی می‌شوند. متادیتای برچسب فنی در بسته .NET Standard موجود نیست زیرا خواننده متادیتا فقط یک نسخه .NET 8 را ارائه می‌دهد. بنابراین Viewer.GetDicomMetadataAsync(token) برای یک جلسه DICOM null را برمی‌گرداند و یک هشدار یک‌باره ثبت می‌کند. درخواست مربوط به ?token=…&meta=1، HTTP 501 Not Implemented را با کد خطای ثابت dicom_metadata_unsupported برمی‌گرداند. زمانی که متادیتای فنی DICOM نیاز است، از بسته .NET 8 استفاده کنید.
  • فقط ویندوز، مانند بقیه بسته .NET Standard.

آیا این صفحه مفید بود؟