ملحق DICOM

عرض الصور الطبية باستخدام DicomPlugin

يضيف ملحق DICOM عرض الصور الطبية إلى Doconut: ملفات DICOM متعددة الإطارات تُعرض كملخص متحرك، أو إطارات فردية، أو كلاهما. DICOM هو تنسيق يقتصر على الملحق — بدون هذا الملحق (وخاصية الترخيص الخاصة به)، لا يمكن فتح ملفات .dcm على الإطلاق.

السطحمتى تستخدمه
Viewer مع DicomConfig (C#)تقوم بفتح ملفات DICOM على الخادم وتختار كيفية عرض إطاراتها
العارض (docViewer)تعرض الدراسة في صفحتك: الرسوم المتحركة والإطارات

لا يحتوي الملحق على واجهة مستخدم خاصة به: تُفتح ملفات DICOM في العارض العادي. مع تسجيل ملحق التحويل أيضًا، يمكن تحويل ملفات .dcm و.ima إلى Pdf، Png، Jpeg، Bmp، Tiff أو Gif؛ هذا التحويل يحتاج أيضًا إلى خاصية Dicom.

تثبيت الحزمة

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: Windows، وLinux القائم على glibc على x64 (ليس Alpine أو توزيعات musl الأخرى). على Linux، ثبّت مكتبة تكوين الخطوط قبل فتح المستند الأول:

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.

تسجيل الملحق

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.

يطرح الاستثناء في حالة عدم وجود ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Dicom، أو ترخيص مدفوع يُستخدم خارج نافذة إصداره. تُقبل تراخيص Demo/NFR المؤقتة. راجع إعداد الترخيص لمعرفة كيفية تحميل التراخيص.

نظرًا لعدم وجود عارض مدمج يتعامل مع هذه الصيغ، فإن بوابة وقت التشغيل تفشل أيضًا بشدة إذا أصبحت القدرة غير متاحة لاحقًا:

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

الترخيص والعلامة المائية

حالة الترخيصبدء التشغيلإخراج DICOM
ترخيص مدفوع يمنح Dicom، ضمن نافذة إصدارهيبدأيُعرض وفق قواعد العلامة المائية العادية للصفحة
ترخيص مؤقت نشط (Demo/NFR)يبدأيُعرض مع علامة مائية تجريبية
بدون ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Dicom، أو ترخيص مدفوع خارج نافذة إصدارهيطرح AddDoconut()—

تنطبق قاعدة العلامة المائية للصفحة العادية أيضًا على إخراج DICOM. بالنسبة للإخراج المتحرك، يُطبع كل إطار GIF بحيث يبقى العلامة مرئية طوال التشغيل. يُستخدم DocOptions.Watermark مخصص فقط عندما تسمح مسار الترخيص بالعلامات المائية المخصصة؛ ولا يمكنه استبدال العلامة المائية التجريبية.

الاستخدام من C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});

Viewer.GetDicomMetadataAsync(token) موجود في هذه الحزمة، لكنه يُعيد null لجلسة DICOM: راجع ملاحظات الإطار.

أنماط العرض، الدقة والبيانات الوصفية

أنماط العرض

يمكن تقديم ملفات DICOM متعددة الإطارات بثلاث طرق (DicomDisplayMode):

الوضعالصفحات المنتجةالاستخدام
AnimationOnlyالصفحة 1 = GIF متحرك يكرر جميع الإطاراتمراجعة سينمائية سريعة
FramesOnlyالصفحات 1..N = صورة PNG ثابتة لكل إطارتنقل تشخيصي إطارًا تلو الآخر
AnimationAndFrames (الافتراضي)الصفحة 1 = GIF متحرك، الصفحات 2..N+1 = صورة PNG ثابتة لكل إطار (N = عدد الإطارات)نظرة عامة + تفاصيل في مستند واحد

يتم التحكم في توقيت الرسوم المتحركة بواسطة AnimationFrameDelayMs (الافتراضي 100 مللي ثانية = 10 إطار/ثانية؛ دقة GIF هي وحدات 10 مللي ثانية) و LoopCount (0 = حلقة إلى الأبد).

الدقة

DicomConfig يعرض بدقة 100 DPI لكل محور بشكل افتراضي. خصائص الدقة لها سلسلة احتياطية تستحق المعرفة: إذا لم تقم بتعيين HorizontalResolution/VerticalResolution صراحةً، فإنها تتبع BaseConfig.ImageResolution عندما يتم تكوينه، ثم تعود إلى 100 فقط.

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

يعيد null عندما لا يكون المستند ملف DICOM، ويعيد دائمًا 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 الفعّال يستخدم وحدات 10 مللي ثانيةاضبط AnimationFrameDelayMs
الذاكرة تزداد مع ملفات متعددة الإطارات الكبيرةوضع العرض، الدقة وذاكرة التخزين المؤقت للصفحات كلها تضيف صورًا محتفظًا بهاراجع في الإنتاج; أغلق الجلسات صراحةً
البيانات الوصفية هي nullالمستند ليس ملف DICOMتحقق من نوع الملف قبل طلب البيانات الوصفية
البيانات الوصفية هي null لملف DICOM، أو &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. استخدم حزمة .NET 8 عندما تكون البيانات الوصفية التقنية لـ DICOM مطلبًا.

هل كانت هذه الصفحة مفيدة؟