ملحق 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.

تثبيت الحزمة

bash
dotnet add package Doconut.NET8.Dicom

الأمر غير المحدد الإصدار يثبت أحدث إصدار ثابت. لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:

bash
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: 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 يكشف عن بيانات العلامات الوصفية:

csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// null عندما لا تكون الجلسة مستند DICOM

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

أوضاع العرض

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

الوضعالصفحات المنتجةالاستخدام
AnimationOnlyالصفحة 1 = GIF متحرك يكرر جميع الإطاراتمراجعة سينمائية سريعة
FramesOnlyالصفحات 1..N = صورة PNG ثابتة لكل إطارتنقل تشخيصي إطارًا بإطار
AnimationAndFrames (default)الصفحة 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 يفتح لوحة الخصائص التقنية. إذا فشل هذا الطلب، تظل اللوحة مخفية ولا يزال المستند يُعرض.

أنشئ الواجهة الأمامية الخاصة بك

البيانات الوصفية متاحة عبر 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

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

وضع عرض DICOM

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

عارض.احصل على بيانات DICOM الوصفية بشكل غير متزامن

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

تُعيد null عندما لا يكون المستند ملف DICOM. تُثير InvalidOperationException عندما يكون الرمز غير معروف أو منتهي الصلاحية.

بيانات DICOM الوصفية

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تحقق من نوع الملف قبل طلب البيانات الوصفية
GetDicomMetadataAsync يثير Document session not found. Please re-open document.انتهت صلاحية الرمز أو لم يُفتح أبدًاافتح المستند مرة أخرى

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