افزونه 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 نیاز دارد.

نصب بسته

bash
dotnet add package Doconut.NET8.Dicom

دستور بدون نسخه، آخرین نسخهٔ پایدار را نصب می‌کند. برای قفل کردن افزونه به نسخه‌ای که این مستندات توصیف می‌کند، نسخه را به‌صورت جداگانه پاس دهید:

bash
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 اجرا می‌شود کار می‌کند: ویندوز و لینوکس مبتنی بر glibc بر روی x64 (نه Alpine یا توزیع‌های دیگر مبتنی بر musl). در لینوکس، قبل از باز شدن اولین سند کتابخانهٔ پیکربندی فونت را نصب کنید:

bash
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. شکست می‌خورد.

ثبت افزونه

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 متادیتای برچسب‌ها را در دسترس می‌گذارد:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null زمانی که جلسه یک سند DICOM نیست

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

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

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

حالتصفحات تولید شدهکاربرد
AnimationOnlyصفحه 1 = GIF انیمیشنی که تمام فریم‌ها را حلقه می‌زندمرور سریع سینمایی
FramesOnlyصفحات 1..N = یک PNG ثابت برای هر فریمناوبری تشخیصی فریم‑به‑فریم
AnimationAndFrames (پیش‌فرض)صفحه 1 = GIF انیمیشنی، صفحات 2..N+1 = یک PNG ثابت برای هر فریم (N = تعداد فریم‌ها)مرور کلی + جزئیات در یک سند

زمان‌بندی انیمیشن توسط AnimationFrameDelayMs کنترل می‌شود (پیش‌فرض ۱۰۰ میلی‌ثانیه = ۱۰ فریم بر ثانیه؛ دقت GIF واحدهای ۱۰ میلی‌ثانیه است) و LoopCount (0 = حلقه بی‌نهایت).

وضوح

DicomConfig به‌صورت پیش‌فرض با ۱۰۰ DPI برای هر محور رندر می‌شود. ویژگی‌های وضوح دارای زنجیرهٔ پیش‌فرضی هستند که دانستن آن مفید است: اگر HorizontalResolution/VerticalResolution را به‌طور صریح تنظیم نکنید، آن‌ها به BaseConfig.ImageResolution پیروی می‌کنند وقتی که پیکربندی شده باشد، و فقط سپس به ۱۰۰ باز می‌گردند.

csharp
// افزایش یکنواخت از طریق base property…
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

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

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