ملحق 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.
تثبيت الحزمة
dotnet add package Doconut.NET8.Dicomالأمر غير المحدد الإصدار يثبت أحدث إصدار ثابت. لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:
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، قم بتثبيت مكتبة تكوين الخطوط قبل فتح أول مستند:
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 يكشف عن بيانات العلامات الوصفية:
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 فقط.
// زيادة موحدة عبر الخاصية الأساسية…
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
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
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }عارض.احصل على بيانات DICOM الوصفية بشكل غير متزامن
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);تُعيد null عندما لا يكون المستند ملف DICOM. تُثير InvalidOperationException عندما يكون الرمز غير معروف أو منتهي الصلاحية.
بيانات DICOM الوصفية
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. | انتهت صلاحية الرمز أو لم يُفتح أبدًا | افتح المستند مرة أخرى |
هل كانت هذه الصفحة مفيدة؟