پلاگین 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 نیاز دارد.
نصب بسته
Install-Package Doconut.NETFramework.Dicomبرای قفل کردن پلاگین به نسخهای که این مستندات توصیف میکند:
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0بستهٔ DICOM را با همان نسخهٔ Doconut.NETFramework نگه دارید.
فایل لایسنس پلاگین، Doconut.Viewer.Dicom.lic، در همان پوشهای که Doconut.Viewer.lic قرار دارد قرار میگیرد؛ همراه با لایسنس نمایشگر خوانده میشود.
ثبت پلاگین
Doconut.DoconutHost.Initialize(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});پلاگین (Name: "Doconut DICOM Viewer") نمایشگرهایی را برای پسوندهای .dcm و .ima ثبت میکند، که توسط قابلیت Dicom محدود شدهاند. اگر لایسنس این قابلیت را ندهد، DoconutHost.Initialize از Application_Start استثنا میاندازد:
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 پذیرفته میشوند. به راهاندازی لایسنس مراجعه کنید.
از آنجا که هیچ نمایشگر داخلی این فرمتها را پشتیبانی نمیکند، باز کردن یکی از آنها در صورتی که قابلیت بعداً در دسترس نباشد، بهطور کامل شکست میخورد:
LicenseException: This document type requires the 'Dicom' plugin license.مجوزدهی و واترمارک
| وضعیت لایسنس | راهاندازی | خروجی DICOM |
|---|---|---|
لایسنس پرداختشده که Dicom را اعطا میکند، در بازهٔ نسخهٔ خود | شروع میشود | رندر شده تحت قوانین واترمارک صفحهٔ معمولی |
| لایسنس موقت فعال (Demo/NFR) | شروع میشود | رندر شده با واترمارک ارزیابی |
بدون لایسنس، فایل قدیمی TRIAL، لایسنس بدون Dicom، یا لایسنس پرداختشده خارج از بازهٔ نسخه | Application_Start استثنا میاندازد؛ هر درخواست یک 500 خالی را پاسخ میدهد | — |
تصمیم واترمارک صفحهٔ معمولی همچنین برای خروجی DICOM اعمال میشود. برای خروجی انیمیشنی، هر قاب GIF مهر میشود، بنابراین علامت در طول پخش قابل مشاهده باقی میماند. یک DocOptions.Watermark سفارشی فقط زمانی استفاده میشود که لایسنس اجازهٔ واترمارکهای سفارشی را بدهد؛ نمیتواند واترمارک ارزیابی را جایگزین کند.
استفاده از C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});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 آن را دنبال میکنند و فقط سپس به ۱۰۰ باز میگردند.
// افزایش یکنواخت از طریق ویژگی پایه…
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
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 را برمیگرداند. وقتی توکن ناشناخته یا منقضی باشد، 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.
آیا این صفحه مفید بود؟