ملحق DICOM

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

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

على .NET Framework 4.7.2، تُظهر ملفات DICOM بالكامل — الصفحات، الإطارات، والرسوم المتحركة — لكن البيانات الوصفية التقنية (علامات DICOM) غير متوفرة. Viewer.GetDicomMetadataAsync دائمًا ما تُعيد null، وطلب البيانات الوصفية للعارض (?token=…&meta=1 على DocImage.axd) يجيب بـ 404، لذا لا يظهر لوحة خصائص DICOM في العارض. استخدم Doconut.NET8 إذا كان تطبيقك يحتاج إلى العلامات.

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

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

تثبيت الحزمة

powershell
Install-Package Doconut.NETFramework.Dicom

لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

احفظ حزمة DICOM بنفس الإصدار كما هو في Doconut.NETFramework.

ملف ترخيص الملحق، Doconut.Viewer.Dicom.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يتم قراءته مع ترخيص العارض.

تسجيل الملحق

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

الملحق (Name: "Doconut DICOM Viewer") يسجل عارضين للامتدادات .dcm و .ima، مقيدًا بقدرة Dicom. إذا لم يمنح الترخيص ذلك، فإن DoconutHost.Initialize يطرح استثناءً من Application_Start:

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.

في System.Web يعني ذلك أن كل طلب يجيب بـ 500 فارغ، والسبب موجود فقط في سجل أحداث Windows (المصدر ASP.NET). يطرح استثناءً عند عدم وجود ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Dicom، أو ترخيص مدفوع يُستخدم خارج نافذة إصداره. تُقبل تراخيص Demo/NFR المؤقتة. راجع إعداد الترخيص.

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

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

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

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

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

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

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// في .NET Framework يكون هذا دائمًا null: قارئ بيانات DICOM الوصفية غير متوفر لهذا
// target. الصفحات والإطارات والرسوم المتحركة تُعرض بشكل طبيعي.

الطريقة موجودة في هذه الحزمة بحيث يتم تجميع الشيفرة المشتركة مع حزمة .NET 8، لكن قراءة وسوم DICOM تحتاج إلى مكوّن لا يتوفر بنسخة .NET Framework. خطط واجهة المستخدم الخاصة بك بدونها — على سبيل المثال، أخفِ لوحة البيانات الوصفية عندما تكون النتيجة null.

أوضاع العرض والدقة

أوضاع العرض

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

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

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

يكتشف العارض أن الصفحة 1 متحركة بإرسال طلب HEAD لها. لذلك يجب على معالج DocImage.axd قبول HEAD في Web.config (verb="GET,HEAD,POST"، انظر التثبيت); بدون ذلك، يرد IIS بـ 404 قبل تشغيل Doconut ولا يعمل اكتشاف الرسوم المتحركة أبداً.

الدقة

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

csharp
// زيادة موحدة عبر الخاصية الأساسية…
new DicomConfig { ImageResolution = 150 };

// …أو تحكم لكل محور
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

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

تستخدم صور الصفحات، بما في ذلك الصفحة الأولى المتحركة، مسار الصورة القياسي DocImage.axd. طلب البيانات الوصفية، GET /DocImage.axd?token=<token>&meta=1، يجيب بـ 404 في هذه الحزمة لكل مستند، بما في ذلك ملفات DICOM، لأن قارئ البيانات الوصفية غير متوفر.

في بيئة الإنتاج

يمكن للدراسات متعددة الإطارات إنتاج كل من الرسوم المتحركة وصفحة ثابتة لكل إطار. AnimationAndFrames يوفر أغنى تنقل ولكنه أيضًا أعلى تكلفة في العرض والذاكرة — وعلى خادم واحد تلك الذاكرة تنتمي إلى عملية عامل IIS. للدراسات الكبيرة:

  • استخدم FramesOnly عندما تكون فحص الإطارات أهم من التشغيل؛
  • تجنب رفع كلا محوري الدقة دون قياس الذاكرة؛
  • أغلق الجلسة صراحةً عندما لا تكون الدراسة مفتوحة بعد الآن؛
  • احتفظ بـ CachePages مفعلاً فقط عندما يكون الوصول المتكرر يستحق الصور المحتفظ بها.

ضع Doconut.Viewer.Dicom.lic بجوار Doconut.Viewer.lic على كل خادم، واحتفظ بـ HEAD في قائمة verb الخاصة بالمعالج.

مرجع 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 في هذه الحزمة. يرمي InvalidOperationException عندما يكون الرمز غير معروف أو منتهي الصلاحية. تم تعريف DicomMetadata بحيث يتم تجميع الشيفرة المشتركة مع حزمة .NET 8.

استكشاف الأخطاء وإصلاحها

العَرَضالسببالحل
كل طلب يُجيب بـ 500 فارغ بعد إضافة الملحق؛ سجل أحداث Windows (المصدر ASP.NET) يُظهر 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>() في DoconutHost.Initialize وانشر الحزمة
فتح ملف .dcm يرمي LicenseException: This document type requires the 'Dicom' plugin license.الرخصة المحملة لم تعد تمنح Dicomثبّت رخصة تمنح Dicom
تظهر صفحة واحدة فقطالمصدر هو إطار واحد، أو DisplayMode هو AnimationOnlyاستخدم FramesOnly أو AnimationAndFrames لمصدر متعدد الإطارات
الصفحة 1 لا تُحركالمعالج في Web.config لا يقبل HEADاستخدم verb="GET,HEAD,POST"
الرسوم المتحركة سريعة جدًا أو بطيئةAnimationFrameDelayMs غير مفعّل؛ توقيت GIF يستخدم وحدات 10 مللي ثانيةاضبط AnimationFrameDelayMs
الذاكرة تزداد مع ملفات متعددة الإطارات الكبيرةوضع العرض، الدقة، وذاكرة الصفحات المؤقتة كلها تضيف صورًا محتفظًا بهاانظر في الإنتاج; أغلق الجلسات صراحةً
البيانات الوصفية دائمًا هي nullمتوقع في هذه الحزمةاستخدم حزمة .NET 8 عندما تحتاج إلى العلامات
GetDicomMetadataAsync يرمي Document session not found. Please re-open document.انتهت صلاحية الرمز أو لم يُفتح أبدًاافتح المستند مرة أخرى

ملاحظات الإطار

مقارنةً بحزم ASP.NET Core، تختلف هذه الحزمة في الاستضافة وفي بيانات DICOM الوصفية:

  • التسجيل موجود في Application_Start، عبر DoconutHost.Initialize، بدلاً من builder.Services.AddDoconut.
  • فشل بدء التشغيل يظهر كـ 500 فارغ في كل طلب، مع السبب في سجل أحداث Windows.
  • اكتشاف الرسوم المتحركة يحتاج إلى HEAD في قائمة verb للمعالج DocImage.axd.
  • لا توجد بيانات DICOM وصفية. Viewer.GetDicomMetadataAsync دائمًا ما يُعيد null ويسجّل تحذيرًا لمرة واحدة لجلسة DICOM؛ طلب بيانات DocImage.axd يُجيب بـ 404، وليس بـ 501 لحزم .NET 6 و .NET Standard.
  • Windows فقط، مثل بقية حزمة .NET Framework.

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