پلاگین 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 خالی را پاسخ می‌دهد، و دلیل آن فقط در لاگ رویدادهای ویندوز (منبع 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صفحه ۱ = GIF انیمیشنی که تمام فریم‌ها را حلقه می‌زندمرور سریع سینمایی
FramesOnlyصفحات ۱..N = یک PNG ثابت برای هر فریمناوبری تشخیصی فریم‑به‑فریم
AnimationAndFrames (پیش‌فرض)صفحه ۱ = GIF انیمیشنی، صفحات ۲..N+1 = یک PNG ثابت برای هر فریم (N = تعداد فریم‌ها)نمای کلی و جزئیات در یک سند

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

نمایشگر متوجه می‌شود که صفحه ۱ انیمیشنی است با ارسال یک درخواست HEAD برای آن. بنابراین هندلر DocImage.axd باید HEAD را در Web.config بپذیرد (verb="GET,HEAD,POST"، ببینید نصب); بدون آن، IIS قبل از اجرای Doconut پاسخ 404 می‌دهد و تشخیص انیمیشن هرگز کار نمی‌کند.

وضوح

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

csharp
// افزایش یکنواخت از طریق ویژگی پایه…
new DicomConfig { ImageResolution = 150 };

// …یا کنترل محور‑به‌محور
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

ساخت رابط کاربری خود

تصاویر صفحات، از جمله صفحهٔ اول انیمیشنی، از مسیر تصویر استاندارد DocImage.axd استفاده می‌کنند. درخواست متادیتا، GET /DocImage.axd?token=<token>&meta=1، در این بسته برای هر سند، شامل فایل‌های DICOM، پاسخ 404 می‌دهد، زیرا خوانندهٔ متادیتا در دسترس نیست.

در محیط تولید

مطالعات چند‑قابلی می‌توانند هم یک انیمیشن و هم یک صفحهٔ ثابت برای هر فریم تولید کنند. 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 خالی پاسخ می‌دهد؛ لاگ رویداد ویندوز (منبع 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 استفاده کنید
صفحهٔ ۱ انیمیشن نمی‌دهدهندلر در Web.config ، HEAD را قبول نمی‌کنداز verb="GET,HEAD,POST" استفاده کنید
انیمیشن خیلی سریع یا خیلی آهسته استAnimationFrameDelayMs غیرفعال است؛ زمان‌بندی GIF از واحدهای ۱۰ میلی‌ثانیه استفاده می‌کند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 خالی در هر درخواست ظاهر می‌شوند، با دلیل در لاگ رویداد ویندوز.
  • تشخیص انیمیشن نیاز به HEAD در فهرست verb هندلر DocImage.axd دارد.
  • بدون متادیتای DICOM. Viewer.GetDicomMetadataAsync همیشه null را برمی‌گرداند و یک هشدار یک‌بار برای یک جلسه DICOM ثبت می‌کند؛ درخواست متادیتای DocImage.axd پاسخ 404 می‌دهد، نه 501 بسته‌های .NET 6 و .NET Standard.
  • فقط ویندوز، مانند بقیهٔ بستهٔ .NET Framework.

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