ملحق 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.NET6.Dicomالأمر غير المُصنَّف يثبت أحدث إصدار ثابت. لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:
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، ثبّت مكتبة تكوين الخطوط قبل فتح المستند الأول:
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.
تسجيل الملحق
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) موجود في هذه الحزمة، لكنه يُعيد 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 فقط.
// ارتفاع موحد عبر الخاصية الأساسية…
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
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);يعيد null عندما لا يكون المستند ملف DICOM، ويعيد دائمًا 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 غير مسجل، أو حزمته غير منشورة | أضف 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يعيد HTTP501 Not Implementedمع رمز الخطأ المستقرdicom_metadata_unsupported. استخدم حزمة .NET 8 عندما تكون البيانات الوصفية التقنية لـ DICOM مطلبًا.
هل كانت هذه الصفحة مفيدة؟