Plugin DICOM
Xem hình ảnh y tế với DicomPlugin
Plugin DICOM thêm khả năng xem hình ảnh y tế vào Doconut: các tệp DICOM đa khung được hiển thị dưới dạng tổng quan hoạt ảnh, các khung riêng lẻ, hoặc cả hai. DICOM là một định dạng chỉ dành cho plugin — nếu không có plugin này (và khả năng cấp phép của nó), các tệp .dcm không thể mở được hoàn toàn.
| Giao diện | Khi nào sử dụng |
|---|---|
Viewer với DicomConfig (C#) | Bạn mở các tệp DICOM trên máy chủ và chọn cách các khung của chúng được trình bày |
Trình xem (docViewer) | Bạn hiển thị nghiên cứu trên trang của mình: hoạt ảnh, các khung, và một bảng thuộc tính DICOM |
Điểm cuối HTTP (?token=<token>&meta=1) | Bạn đọc siêu dữ liệu kỹ thuật từ giao diện phía trước của mình |
Plugin không có widget riêng: các tệp DICOM mở trong trình xem thông thường. Khi plugin Converter cũng được đăng ký, các tệp .dcm và .ima có thể được chuyển đổi sang Pdf, Png, Jpeg, Bmp, Tiff hoặc Gif; việc chuyển đổi đó cũng cần khả năng Dicom.
Cài đặt gói
dotnet add package Doconut.NET8.DicomLệnh không chỉ định phiên bản sẽ cài đặt bản phát hành ổn định mới nhất. Để cố định plugin vào bản phát hành mà tài liệu này mô tả, hãy truyền phiên bản riêng biệt:
dotnet add package Doconut.NET8.Dicom --version 26.10.0Giữ gói DICOM ở cùng phiên bản với Doconut.NET8. ID gói là Doconut.NET8.Dicom; .<version> chỉ xuất hiện trong tên tệp .nupkg đã tải xuống.
Tệp giấy phép của plugin, Doconut.Viewer.Dicom.lic, nằm trong cùng thư mục với Doconut.Viewer.lic; nó được đọc cùng với giấy phép của trình xem.
Nền tảng. Plugin chạy ở bất kỳ nơi nào Doconut.NET8 chạy: Windows, và Linux dựa trên glibc trên x64 (không phải Alpine hay các bản phân phối dựa trên musl khác). Trên Linux, cài đặt thư viện cấu hình phông chữ trước khi tài liệu đầu tiên được mở:
apt-get update && apt-get install -y libfontconfig1Trên RHEL, Fedora và các bản phân phối tương tự, gói là fontconfig. Nếu không có, việc mở tài liệu sẽ thất bại với The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
Đăng ký plugin
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});Plugin (Name: "Doconut DICOM Viewer") đăng ký trình xem cho các phần mở rộng .dcm và .ima, được kiểm soát bởi khả năng Dicom. Nếu không có giấy phép cho phép, AddDoconut() sẽ ném một InvalidOperationException khi khởi động, trước khi ứng dụng phục vụ một yêu cầu:
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.Nó ném lỗi khi không có giấy phép, tệp legacy TRIAL, giấy phép thiếu Dicom, và giấy phép trả phí được sử dụng ngoài khung thời gian phiên bản của nó. Các giấy phép Demo/NFR tạm thời được chấp nhận. Xem Cài đặt giấy phép để biết cách tải giấy phép.
Vì không có trình xem tích hợp nào xử lý các định dạng này, cổng thời gian chạy cũng sẽ thất bại nghiêm trọng nếu khả năng này sau này không còn khả dụng:
LicenseException: This document type requires the 'Dicom' plugin license.Cấp phép & dấu watermark
| Trạng thái giấy phép | Khởi động | Kết quả DICOM |
|---|---|---|
Giấy phép trả phí cấp Dicom, trong khung thời gian phiên bản của nó | Bắt đầu | Được hiển thị theo quy tắc dấu watermark trang bình thường |
| Giấy phép Tạm thời (Demo/NFR) đang hoạt động | Bắt đầu | Được hiển thị với dấu watermark đánh giá |
Không có giấy phép, tệp legacy TRIAL, giấy phép thiếu Dicom, hoặc giấy phép trả phí ngoài khung thời gian phiên bản | AddDoconut() ném lỗi | — |
Quyết định dấu watermark trang bình thường cũng áp dụng cho kết quả DICOM. Đối với đầu ra hoạt ảnh, mỗi khung GIF đều được dán dấu để dấu này vẫn hiển thị trong suốt quá trình phát. Một DocOptions.Watermark tùy chỉnh chỉ được sử dụng khi đường giấy phép cho phép watermark tùy chỉnh; nó không thể thay thế dấu watermark đánh giá.
Sử dụng từ C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});Đối với các phiên được mở qua plugin này, Viewer cung cấp siêu dữ liệu thẻ:
var metadata = await viewer.GetDicomMetadataAsync(token);
// null khi phiên không phải là tài liệu DICOMCác chế độ hiển thị, độ phân giải và siêu dữ liệu
Các chế độ hiển thị
Các tệp DICOM đa khung có thể được trình bày theo ba cách (DicomDisplayMode):
| Chế độ | Trang được tạo | Mục đích |
|---|---|---|
AnimationOnly | Trang 1 = animated GIF looping all frames | Đánh giá nhanh kiểu điện ảnh |
FramesOnly | Các trang 1..N = một PNG tĩnh cho mỗi khung | Điều hướng chẩn đoán khung‑khung |
AnimationAndFrames (default) | Trang 1 = animated GIF, các trang 2..N+1 = một PNG tĩnh cho mỗi khung (N = số khung) | Tổng quan + chi tiết trong một tài liệu |
Thời gian hoạt ảnh được điều khiển bởi AnimationFrameDelayMs (mặc định 100 ms = 10 FPS; độ chi tiết GIF là đơn vị 10 ms) và LoopCount (0 = lặp vô hạn).
Độ phân giải
DicomConfig hiển thị ở 100 DPI mỗi trục theo mặc định. Các thuộc tính độ phân giải có một chuỗi dự phòng cần biết: nếu bạn không đặt HorizontalResolution/VerticalResolution một cách rõ ràng, chúng sẽ theo BaseConfig.ImageResolution khi được cấu hình, và chỉ sau đó mới quay lại 100.
// Tăng đồng đều qua thuộc tính cơ sở…
new DicomConfig { ImageResolution = 150 };
// …hoặc điều khiển theo từng trục
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Siêu dữ liệu
DicomMetadata chỉ chứa các thẻ kỹ thuật và hình ảnh — số khung, kích thước, độ sâu bit, cách diễn giải quang học, cú pháp truyền, chế độ và mức cửa sổ mặc định. Nó không chứa dữ liệu nhận dạng bệnh nhân. Danh sách đầy đủ có trong Tham chiếu API.
Trong trình xem
Trình xem không cần thiết lập đặc thù cho DICOM. Khi tài liệu mở là tệp DICOM, nó yêu cầu siêu dữ liệu (?token=<token>&meta=1) và thêm một nút DICOM mở bảng thuộc tính kỹ thuật. Nếu yêu cầu đó thất bại, bảng sẽ ẩn và tài liệu vẫn được hiển thị.
Xây dựng giao diện phía trước của bạn
Siêu dữ liệu có sẵn qua HTTP dưới đường dẫn nơi UseDoconut() được gắn (thông thường /doconut), cho bất kỳ token tài liệu mở nào:
| Đường dẫn | Mục đích | Phản hồi thành công |
|---|---|---|
GET ?token=<token>&meta=1 | Đọc siêu dữ liệu kỹ thuật của một tài liệu DICOM mở | 200 — DicomMetadata dưới dạng JSON, với các tên thuộc tính của Tham chiếu API (Width, Height, NumberOfFrames, …) |
| Trạng thái | Khi | Nội dung |
|---|---|---|
404 | Tài liệu không phải là tệp DICOM | chỉ trạng thái |
500 | Đọc siêu dữ liệu thất bại | { "error": "metadata failed" } |
Các hình ảnh trang, bao gồm trang đầu tiên hoạt hình, sử dụng đường dẫn hình ảnh chuẩn của trình xem.
Trong môi trường sản xuất
Các nghiên cứu đa khung có thể tạo cả hoạt ảnh và một trang tĩnh cho mỗi khung. AnimationAndFrames cung cấp khả năng điều hướng phong phú nhất nhưng cũng có chi phí render và cache cao nhất. Đối với các nghiên cứu lớn:
- sử dụng
FramesOnlykhi việc kiểm tra khung quan trọng hơn so với phát lại kiểu điện ảnh; - tránh tăng cả hai trục độ phân giải mà không đo bộ nhớ;
- đóng phiên một cách rõ ràng khi nghiên cứu không còn mở;
- giữ
CachePagesbật chỉ khi lợi ích của việc truy cập lặp lại vượt quá các hình ảnh được giữ lại.
Đặt Doconut.Viewer.Dicom.lic bên cạnh Doconut.Viewer.lic trên mọi máy chủ.
Tham chiếu API
DicomConfig, DicomDisplayMode và DicomMetadata nằm trong không gian tên Doconut. DicomPlugin nằm trong Doconut.Plugins.Dicom. Bảng thuộc tính DicomConfig đầy đủ có trong Cấu hình Định dạng.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // mặc định: ImageResolution khi được đặt, nếu không 100
public int VerticalResolution { get; set; } // mặc định: ImageResolution khi được đặt, nếu không 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = vòng lặp vô hạn
public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}Chế độ hiển thị DICOM
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);Trả về null khi tài liệu không phải là tệp DICOM. Ném InvalidOperationException khi token không xác định hoặc đã hết hạn.
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" hoặc "Signed"
public string? PlanarConfiguration { get; init; }
public string? TransferSyntax { get; init; }
public string? Modality { get; init; } // null khi không được phơi bày
public double? WindowCenter { get; init; }
public double? WindowWidth { get; init; }
public bool IsColor { get; init; }
}Khắc phục sự cố
| Triệu chứng | Nguyên nhân | Cách khắc phục |
|---|---|---|
AddDoconut() ném The Dicom plugin is registered via AddPlugin but no active license grants Dicom. | Không có giấy phép, một tệp TRIAL, giấy phép không có Dicom, hoặc giấy phép trả phí ngoài khoảng thời gian phiên bản của nó | Cài đặt giấy phép cung cấp Dicom, hoặc loại bỏ AddPlugin<DicomPlugin>() |
Mở tệp .dcm ném Document format '.dcm' is not supported. | DicomPlugin chưa được đăng ký, hoặc gói của nó chưa được triển khai | Thêm AddPlugin<DicomPlugin>() vào bên trong AddDoconut() và triển khai gói |
Mở tệp .dcm ném LicenseException: This document type requires the 'Dicom' plugin license. | Giấy phép đã tải không còn cung cấp Dicom | Cài đặt giấy phép cung cấp Dicom |
| Chỉ một trang hiển thị | Nguồn là khung đơn, hoặc DisplayMode là AnimationOnly | Sử dụng FramesOnly hoặc AnimationAndFrames cho nguồn đa khung |
| Hoạt ảnh quá nhanh hoặc chậm | AnimationFrameDelayMs bị tắt; thời gian GIF hiệu quả sử dụng đơn vị 10 ms | Điều chỉnh AnimationFrameDelayMs |
| Bộ nhớ tăng lên trên các tệp đa khung lớn | Chế độ hiển thị, độ phân giải và bộ nhớ đệm trang đều thêm hình ảnh được giữ lại | Xem Trong môi trường sản xuất; đóng phiên một cách rõ ràng |
Metadata là null | Tài liệu không phải là tệp DICOM | Kiểm tra loại tệp trước khi yêu cầu metadata |
GetDicomMetadataAsync ném Document session not found. Please re-open document. | Token đã hết hạn hoặc chưa bao giờ được mở | Mở lại tài liệu |
Trang này có hữu ích không?