ملحق 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.NETStandard.Dicomالأمر غير المحدد للإصدار يثبت أحدث إصدار ثابت. لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق، مرّر الإصدار بشكل منفصل:
dotnet add package Doconut.NETStandard.Dicom --version 26.10.0حافظ على حزمة DICOM بنفس الإصدار كـ Doconut.NETStandard. معرف الحزمة هو Doconut.NETStandard.Dicom؛ يظهر .<version> فقط في اسم الملف .nupkg الذي تم تنزيله.
ملف ترخيص الملحق، Doconut.Viewer.Dicom.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يتم قراءته مع ترخيص العارض.
تسجيل الملحق
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;
}وضع عرض DICOM
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 8 عندما تحتاج إلى العلامات |
GetDicomMetadataAsync يرمى Document session not found. Please re-open document. | انتهت صلاحية الرمز أو لم يُفتح أبداً | افتح المستند مرة أخرى |
ملاحظات الإطار
- لا توجد بيانات وصفية DICOM. دعم عرض صفحات DICOM، الإطارات الفردية، الرسوم المتحركة، التحويلات، وإضافة العلامات المائية. البيانات الوصفية التقنية للعلامات غير متوفرة في حزمة .NET Standard لأن قارئ البيانات الوصفية يوزع فقط نسخة .NET 8.
Viewer.GetDicomMetadataAsync(token)لذلك تُعيدnullلجلسة DICOM وتسجل تحذيرًا لمرة واحدة. طلب?token=…&meta=1المقابل يُعيد HTTP501 Not Implementedمع رمز الخطأ المستقرdicom_metadata_unsupported. استخدم حزمة .NET 8 عندما تكون البيانات الوصفية التقنية لـ DICOM مطلبًا. - Windows فقط، مثل باقي حزمة .NET Standard.
هل كانت هذه الصفحة مفيدة؟