ปลั๊กอิน DICOM
ดูภาพการแพทย์ด้วย DicomPlugin
ปลั๊กอิน DICOM เพิ่มการดูภาพการแพทย์ให้กับ Doconut: ไฟล์ DICOM แบบหลายเฟรมจะแสดงเป็นภาพรวมแบบเคลื่อนไหว, เฟรมเดี่ยว, หรือทั้งสองอย่าง. DICOM เป็น รูปแบบเฉพาะปลั๊กอิน — หากไม่มีปลั๊กอินนี้ (และความสามารถด้านใบอนุญาตของมัน), ไฟล์ .dcm ไม่สามารถเปิดได้เลย.
| พื้นผิว | ใช้เมื่อ |
|---|---|
Viewer with 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 (default) | หน้า 1 = GIF แบบเคลื่อนไหว, หน้า 2..N+1 = PNG คงที่หนึ่งไฟล์ต่อเฟรม (N = จำนวนเฟรม) | ภาพรวม + รายละเอียดในเอกสารเดียว |
การกำหนดเวลาการเคลื่อนไหวถูกควบคุมโดย AnimationFrameDelayMs (ค่าเริ่มต้น 100 ms = 10 FPS; ความละเอียดของ GIF คือหน่วย 10 ms) และ 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. ตาราง property DicomConfig ฉบับเต็มอยู่ใน Format Configs.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // default: ImageResolution เมื่อกำหนด, มิฉะนั้น 100
public int VerticalResolution { get; set; } // default: 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 |
| ปรากฏเพียงหน้าเดียว | แหล่งข้อมูลเป็น single-frame, หรือ DisplayMode คือ AnimationOnly | ใช้ FramesOnly หรือ AnimationAndFrames สำหรับแหล่งข้อมูลหลายเฟรม |
| แอนิเมชันเร็วหรือช้าเกินไป | AnimationFrameDelayMs ปิดอยู่; การจับเวลา GIF ที่มีประสิทธิภาพใช้หน่วย 10 มิลลิวินาที | ปรับ AnimationFrameDelayMs |
| หน่วยความจำเพิ่มขึ้นเมื่อไฟล์หลายเฟรมขนาดใหญ่ | โหมดการแสดงผล, ความละเอียดและแคชหน้าทั้งหมดเพิ่มภาพที่เก็บไว้ | ดูที่ ในขั้นตอนผลิต; ปิดเซสชันอย่างชัดเจน |
Metadata คือ null | เอกสารไม่ใช่ไฟล์ DICOM | ตรวจสอบประเภทไฟล์ก่อนขอ metadata |
Metadata คือ null สำหรับไฟล์ DICOM, หรือ &meta คืนค่า 501 | เป็นข้อจำกัดที่คาดไว้ของ .NET 6; การเรนเดอร์ไม่ได้รับผลกระทบ | ใช้แพคเกจ .NET 8 เมื่อคุณต้องการแท็ก |
GetDicomMetadataAsync ขว้าง Document session not found. Please re-open document. | โทเคนหมดอายุหรือไม่เคยเปิด | เปิดเอกสารใหม่อีกครั้ง |
หมายเหตุของเฟรมเวิร์ก
- ไม่มี metadata ของ DICOM. การเรนเดอร์หน้า DICOM, เฟรมเดี่ยว, แอนิเมชัน, การแปลง, และการใส่ลายน้ำได้รับการสนับสนุน. metadata แท็กทางเทคนิคไม่พร้อมใช้งานในแพคเกจ .NET 6 เนื่องจากตัวอ่าน metadata ไม่มีการสร้างสำหรับ .NET 6.
Viewer.GetDicomMetadataAsync(token)จึงคืนค่าnullสำหรับเซสชัน DICOM และบันทึกคำเตือนหนึ่งครั้ง. คำขอ?token=…&meta=1ที่สอดคล้องกันคืนค่า HTTP501 Not Implementedพร้อมรหัสข้อผิดพลาดที่คงที่dicom_metadata_unsupported. ใช้แพคเกจ .NET 8 เมื่อ metadata ของ DICOM ทางเทคนิคเป็นความต้องการ.
หน้านี้เป็นประโยชน์หรือไม่?