افزونه DICOM
مشاهده تصاویر پزشکی با DicomPlugin
افزونه DICOM قابلیت مشاهده تصاویر پزشکی را به Doconut اضافه میکند: فایلهای DICOM چند‑قابلی به صورت یک نمای کلی انیمیشنی، قابهای جداگانه یا هر دو رندر میشوند. DICOM یک فرمت فقط‑افزونه است — بدون این افزونه (و قابلیت لایسنس آن)، فایلهای .dcm نمیتوانند بهطور کامل باز شوند.
| سطح | چه زمانی استفاده شود |
|---|---|
Viewer با DicomConfig (C#) | شما فایلهای DICOM را بر روی سرور باز میکنید و نحوه ارائه قابهای آنها را انتخاب میکنید |
نمایشگر (docViewer) | شما مطالعه را در صفحه خود نمایش میدهید: انیمیشن و قابها |
این افزونه ویجت خاص خود را ندارد: فایلهای DICOM در نمایشگر معمولی باز میشوند. با ثبت افزونه مبدل نیز، فایلهای .dcm و .ima میتوانند به Pdf، Png، Jpeg، Bmp، Tiff یا Gif تبدیل شوند؛ این تبدیل همچنین به قابلیت Dicom نیاز دارد.
نصب بسته
dotnet add package Doconut.NETStandard.Dicomدستور بدون نسخه آخرین نسخه پایدار را نصب میکند. برای قفل کردن افزونه به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
dotnet add package Doconut.NETStandard.Dicom --version 26.10.0بسته DICOM را در همان نسخهای که Doconut.NETStandard دارد نگه دارید. شناسه بسته Doconut.NETStandard.Dicom است؛ .<version> فقط در نام فایل دانلود شده .nupkg ظاهر میشود.
فایل لایسنس افزونه، Doconut.Viewer.Dicom.lic، در همان پوشهای که Doconut.Viewer.lic قرار دارد قرار میگیرد؛ همراه با لایسنس نمایشگر خوانده میشود.
ثبت افزونه
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.GetDicomMetadataAsync(token) در این بسته وجود دارد، اما برای یک جلسه DICOM مقدار null را برمیگرداند: به یادداشتهای چارچوب مراجعه کنید.
حالتهای نمایش، وضوح و فراداده
حالتهای نمایش
فایلهای DICOM چند‑قابلی میتوانند به سه روش نمایش داده شوند (DicomDisplayMode):
| Mode | Pages produced | Use for |
|---|---|---|
AnimationOnly | Page 1 = animated GIF looping all frames | مرور سریع سینمایی |
FramesOnly | Pages 1..N = one static PNG per frame | ناوبری تشخیصی قاب به قاب |
AnimationAndFrames (default) | Page 1 = animated GIF, pages 2..N+1 = one static PNG per frame (N = frame count) | نمای کلی + جزئیات در یک سند |
زمانبندی انیمیشن توسط AnimationFrameDelayMs (پیشفرض 100 ms = 10 FPS؛ دقت GIF واحدهای 10 ms است) و LoopCount (0 = حلقه بینهایت) کنترل میشود.
وضوح
DicomConfig بهصورت پیشفرض با 100 DPI در هر محور رندر میشود. ویژگیهای وضوح زنجیرهٔ بازگشت دارند که دانستن آن مفید است: اگر HorizontalResolution/VerticalResolution را بهصورت صریح تنظیم نکنید، آنها BaseConfig.ImageResolution را دنبال میکنند وقتی تنظیم شده باشد و فقط سپس به 100 باز میگردند.
// برآمدگی یکنواخت از طریق ویژگی پایه…
new DicomConfig { ImageResolution = 150 };
// …یا کنترل محور به محور
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };فراداده
DicomMetadata فقط برچسبهای فنی و تصویری را حمل میکند — تعداد قاب، ابعاد، عمق بیت، تفسیر فوتومتریک، سینتکس انتقال، مدالیتی و سطح پیشفرض پنجره. این شامل دادههای شناساییپذیر بیمار نیست. فهرست کامل در مرجع API موجود است. در این بسته، فراداده در دسترس نیست؛ رجوع کنید به یادداشتهای چارچوب.
در نمایشگر
نمایشگر نیازی به تنظیمات خاص DICOM ندارد. وقتی سند باز یک فایل DICOM باشد، فراداده را درخواست میکند (?token=<token>&meta=1) و یک دکمه DICOM اضافه میکند که پنل ویژگیهای فنی را باز میکند. اگر آن درخواست شکست بخورد، پنل مخفی میماند و سند همچنان رندر میشود. در این بسته، پاسخ درخواست 501 است، بنابراین پنل هرگز ظاهر نمیشود.
ساخت رابط کاربری خودتان
فراداده از طریق HTTP در مسیری که UseDoconut() سوار شده است (معمولاً /doconut) برای هر توکن سند باز در دسترس است:
| Route | Purpose | Success response |
|---|---|---|
GET ?token=<token>&meta=1 | خواندن فراداده فنی یک سند DICOM باز | 200 — DicomMetadata بهصورت JSON، با نامهای ویژگیهای مرجع API (Width, Height, NumberOfFrames, …) |
| Status | When | Body |
|---|---|---|
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 ثبت نشده است، یا بسته آن مستقر نشده است | در داخل AddDoconut()، AddPlugin<DicomPlugin>() را اضافه کنید و بسته را مستقر کنید |
باز کردن یک فایل .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 8 را استفاده کنید |
GetDicomMetadataAsync پرتاب میکند Document session not found. Please re-open document. | توکن منقضی شده یا هرگز باز نشده است | سند را دوباره باز کنید |
نکات چارچوب
- بدون متادیتای DICOM. رندر صفحه DICOM، فریمهای جداگانه، انیمیشن، تبدیلها و واترمارک پشتیبانی میشوند. متادیتای برچسب فنی در بسته .NET Standard موجود نیست زیرا خواننده متادیتا فقط یک نسخه .NET 8 را ارائه میدهد. بنابراین
Viewer.GetDicomMetadataAsync(token)برای یک جلسه DICOMnullرا برمیگرداند و یک هشدار یکباره ثبت میکند. درخواست مربوط به?token=…&meta=1، HTTP501 Not Implementedرا با کد خطای ثابتdicom_metadata_unsupportedبرمیگرداند. زمانی که متادیتای فنی DICOM نیاز است، از بسته .NET 8 استفاده کنید. - فقط ویندوز، مانند بقیه بسته .NET Standard.
آیا این صفحه مفید بود؟