افزونه 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

bash
dotnet add package Doconut.NET6.Dicom

دستور بدون نسخه، آخرین انتشار پایدار را نصب می‌کند. برای ثابت نگه داشتن افزونه به نسخه‌ای که این مستندات توصیف می‌کند، نسخه را به‌صورت جداگانه پاس دهید:

bash
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). در لینوکس، قبل از اولین باز شدن سند، کتابخانهٔ پیکربندی فونت را نصب کنید:

bash
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

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

افزونه (Name: "Doconut DICOM Viewer") برای پسوندهای .dcm و .ima نمایشگرها را ثبت می‌کند و توسط قابلیت Dicom محدود می‌شود. بدون مجوزی که این قابلیت را بدهد، AddDoconut() در زمان راه‌اندازی یک InvalidOperationException پرتاب می‌کند، پیش از این که برنامه درخواست را سرویس دهد:

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.

این خطا برای عدم وجود مجوز، فایل legacy TRIAL، مجوز بدون Dicom، و مجوز پرداخت‌شده‌ای که خارج از بازهٔ نسخهٔ خود است، رخ می‌دهد. مجوزهای موقت Demo/NFR پذیرفته می‌شوند. برای نحوه بارگذاری مجوزها به راه‌اندازی مجوز مراجعه کنید.

چون هیچ نمایشگر داخلی این فرمت‌ها را پشتیبانی نمی‌کند، دروازهٔ زمان اجرا نیز در صورتی که بعداً این قابلیت در دسترس نباشد، به‌صورت سخت‌گیرانه شکست می‌خورد:

text
LicenseException: This document type requires the 'Dicom' plugin license.

Licensing & watermark

وضعیت مجوزراه‌اندازیخروجی DICOM
مجوز پرداخت‌شده که Dicom را اعطا می‌کند، در بازهٔ نسخهٔ خودشروع می‌شودبر اساس قوانین معمول واترمارک صفحه رندر می‌شود
مجوز موقت فعال (Demo/NFR)شروع می‌شودبا واترمارک ارزیابی رندر می‌شود
عدم وجود مجوز، فایل legacy TRIAL، مجوز بدون Dicom، یا مجوز پرداخت‌شده خارج از بازهٔ نسخهٔ خودAddDoconut() خطا می‌دهد—

تصمیم واترمارک معمول صفحه نیز برای خروجی DICOM اعمال می‌شود. برای خروجی انیمیشنی، هر قاب GIF مهر می‌شود تا علامت در طول پخش قابل مشاهده بماند. یک DocOptions.Watermark سفارشی فقط زمانی استفاده می‌شود که مسیر مجوز امکان واترمارک‌های سفارشی را بدهد؛ نمی‌تواند واترمارک ارزیابی را جایگزین کند.

استفاده از C#

csharp
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 پیروی می‌کنند وقتی که پیکربندی شده باشد، و فقط سپس به ۱۰۰ باز می‌گردند.

csharp
// برآمدگی یکنواخت از طریق ویژگی پایه…
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

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);

در صورتی که سند یک فایل DICOM نیست، null برمی‌گرداند، و همیشه در این بسته null برمی‌گرداند. هنگامیکه توکن ناشناخته یا منقضی باشد، InvalidOperationException پرتاب می‌شود.

DicomMetadata

csharp
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=1 HTTP 501 Not Implemented با کد خطای ثابت dicom_metadata_unsupported را برمی‌گرداند. هنگام نیاز به متادیتای فنی DICOM، بستهٔ .NET 8 را استفاده کنید.

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