افزونه DICOM
مشاهده تصاویر پزشکی با DicomPlugin
افزونه DICOM قابلیت مشاهده تصاویر پزشکی را به Doconut اضافه میکند: فایلهای DICOM چند‑قابلی بهصورت یک نمای کلی انیمیشنی، قابهای جداگانه یا هر دو رندر میشوند. DICOM یک فرمت فقط افزونهای است — بدون این افزونه (و قابلیت مجوز آن)، فایلهای .dcm بههیچوجه نمیتوانند باز شوند.
| سطح | زمانی که استفاده میکنید |
|---|---|
Viewer with DicomConfig (C#) | شما فایلهای DICOM را روی سرور باز میکنید و نحوه ارائه قابهای آنها را انتخاب میکنید |
نمایشگر (docViewer) | شما مطالعه را در صفحه خود نمایش میدهید: انیمیشن و قابها |
افزونه ویجت خاص خود را ندارد: فایلهای DICOM در نمایشگر معمولی باز میشوند. با ثبت افزونه افزونه مبدل نیز، فایلهای .dcm و .ima میتوانند به Pdf، Png، Jpeg، Bmp، Tiff یا Gif تبدیل شوند؛ این تبدیل به قابلیت Dicom نیز نیاز دارد.
Install the package
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 اجرا میشود، کار میکند: ویندوز و لینوکس مبتنی بر glibc روی x64 (نه Alpine و نه توزیعهای دیگر مبتنی بر musl). در لینوکس، قبل از اولین باز شدن سند، کتابخانهٔ پیکربندی فونت را نصب کنید:
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. مواجه میشود.
Register the plugin
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.این خطا برای عدم وجود مجوز، فایل legacy TRIAL، مجوز بدون Dicom، و مجوز پرداختشدهای که خارج از بازهٔ نسخهٔ خود است، رخ میدهد. مجوزهای موقت Demo/NFR پذیرفته میشوند. برای نحوه بارگذاری مجوزها به راهاندازی مجوز مراجعه کنید.
چون هیچ نمایشگر داخلی این فرمتها را پشتیبانی نمیکند، دروازهٔ زمان اجرا نیز در صورتی که بعداً این قابلیت در دسترس نباشد، بهصورت سختگیرانه شکست میخورد:
LicenseException: This document type requires the 'Dicom' plugin license.Licensing & watermark
| وضعیت مجوز | راهاندازی | خروجی DICOM |
|---|---|---|
مجوز پرداختشده که Dicom را اعطا میکند، در بازهٔ نسخهٔ خود | شروع میشود | بر اساس قوانین معمول واترمارک صفحه رندر میشود |
| مجوز موقت فعال (Demo/NFR) | شروع میشود | با واترمارک ارزیابی رندر میشود |
عدم وجود مجوز، فایل legacy TRIAL، مجوز بدون Dicom، یا مجوز پرداختشده خارج از بازهٔ نسخهٔ خود | AddDoconut() خطا میدهد | — |
تصمیم واترمارک معمول صفحه نیز برای خروجی DICOM اعمال میشود. برای خروجی انیمیشنی، هر قاب GIF مهر میشود تا علامت در طول پخش قابل مشاهده بماند. یک DocOptions.Watermark سفارشی فقط زمانی استفاده میشود که مسیر مجوز امکان واترمارکهای سفارشی را بدهد؛ نمیتواند واترمارک ارزیابی را جایگزین کند.
استفاده از C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Viewer.GetDicomMetadataAsync(token) در این بسته موجود است، اما برای یک جلسه DICOM مقدار null را برمیگرداند: ببینید یادداشتهای چارچوب.
حالتهای نمایش، وضوح و فراداده
حالتهای نمایش
فایلهای DICOM چند‑قابلی میتوانند به سه روش ارائه شوند (DicomDisplayMode):
| حالت | صفحات تولید شده | موارد استفاده |
|---|---|---|
AnimationOnly | صفحه 1 = GIF انیمیشنی که تمام فریمها را حلقه میزند | مرور سریع سینمایی |
FramesOnly | صفحات 1..N = یک PNG ثابت برای هر فریم | ناوبری تشخیصی فریم به فریم |
AnimationAndFrames (default) | صفحه 1 = GIF انیمیشن، صفحات 2..N+1 = یک PNG ثابت برای هر فریم (N = تعداد فریمها) | نمای کلی + جزئیات در یک سند |
زمانبندی انیمیشن توسط AnimationFrameDelayMs کنترل میشود (پیشفرض ۱۰۰ میلیثانیه = ۱۰ فریم بر ثانیه؛ دقت GIF به واحدهای ۱۰ میلیثانیه است) و LoopCount (0 = حلقه بینهایت).
وضوح
DicomConfig بهصورت پیشفرض با ۱۰۰ DPI برای هر محور رندر میشود. ویژگیهای وضوح دارای زنجیرهٔ پیشفرضی هستند که دانستن آن مهم است: اگر HorizontalResolution/VerticalResolution را بهطور صریح تنظیم نکنید، آنها به BaseConfig.ImageResolution پیروی میکنند وقتی که پیکربندی شده باشد، و فقط سپس به ۱۰۰ باز میگردند.
// برآمدگی یکنواخت از طریق ویژگی پایه…
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);در صورتی که سند یک فایل DICOM نیست، null برمیگرداند، و همیشه در این بسته 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 از واحدهای ۱۰ میلیثانیه استفاده میکند | AnimationFrameDelayMs را تنظیم کنید |
| حافظه در فایلهای بزرگ چند‑فریم افزایش مییابد | حالت نمایش، وضوح و کش صفحه همگی تصاویر نگهداشتهشده را اضافه میکنند | به در تولید مراجعه کنید؛ جلسات را بهصورت صریح ببندید |
متادیتا null است | سند یک فایل DICOM نیست | قبل از درخواست متادیتا، نوع فایل را بررسی کنید |
متادیتا برای یک فایل DICOM null است، یا &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=1HTTP501 Not Implementedبا کد خطای ثابتdicom_metadata_unsupportedرا برمیگرداند. هنگام نیاز به متادیتای فنی DICOM، بستهٔ .NET 8 را استفاده کنید.
آیا این صفحه مفید بود؟