افزونه 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 نیاز دارد.
نصب بسته
dotnet add package Doconut.NET8.Dicomدستور بدون نسخه، آخرین نسخهٔ پایدار را نصب میکند. برای قفل کردن افزونه به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
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). در لینوکس، قبل از باز شدن اولین سند کتابخانهٔ پیکربندی فونت را نصب کنید:
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. شکست میخورد.
ثبت افزونه
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.این خطا برای عدم وجود لایسنس، فایل قدیمی TRIAL، لایسنس بدون Dicom و لایسنس پرداختشدهای که خارج از بازهٔ نسخهٔ خود استفاده میشود، رخ میدهد. لایسنسهای موقت Demo/NFR پذیرفته میشوند. برای نحوه بارگذاری لایسنسها به راهاندازی لایسنس مراجعه کنید.
از آنجا که هیچ نمایشگر داخلی این فرمتها را پردازش نمیکند، دروازهٔ زمان اجرا نیز در صورتی که قابلیت بعداً در دسترس نباشد، بهصورت سختگیرانه شکست میخورد:
LicenseException: This document type requires the 'Dicom' plugin license.لایسنس و واترمارک
| وضعیت لایسنس | راهاندازی | خروجی DICOM |
|---|---|---|
لایسنس پرداختشده که Dicom را اعطا میکند، در بازهٔ نسخهٔ خود | شروع میشود | رندر شده تحت قوانین واترمارک صفحهٔ معمولی |
| لایسنس موقت فعال (Demo/NFR) | شروع میشود | رندر شده با واترمارک ارزیابی |
بدون لایسنس، فایل قدیمی TRIAL، لایسنس بدون Dicom، یا لایسنس پرداختشده خارج از بازهٔ نسخهٔ خود | AddDoconut() خطا میاندازد | — |
تصمیم واترمارک صفحهٔ معمولی نیز بر خروجی DICOM اعمال میشود. برای خروجی انیمیشنی، هر قاب GIF مهر میشود تا علامت در طول پخش قابل مشاهده بماند. یک DocOptions.Watermark سفارشی فقط زمانی استفاده میشود که مسیر لایسنس اجازهٔ واترمارکهای سفارشی را بدهد؛ این نمیتواند جایگزین واترمارک ارزیابی شود.
استفاده از C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});برای نشستهای باز شده از طریق این افزونه، Viewer متادیتای برچسبها را در دسترس میگذارد:
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 پیروی میکنند وقتی که پیکربندی شده باشد، و فقط سپس به ۱۰۰ باز میگردند.
// افزایش یکنواخت از طریق 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
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 را برمیگرداند. وقتی توکن ناشناخته یا منقضی باشد، 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 نیست | قبل از درخواست متادیتا، نوع فایل را بررسی کنید |
GetDicomMetadataAsync استثنا میاندازد Document session not found. Please re-open document. | توکن منقضی شده یا هرگز باز نشده است | سند را دوباره باز کنید |
آیا این صفحه مفید بود؟