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.

Trên .NET Framework 4.7.2, các tệp DICOM được hiển thị đầy đủ — các trang, khung và hoạt ảnh — nhưng siêu dữ liệu kỹ thuật (các thẻ DICOM) không khả dụng. Viewer.GetDicomMetadataAsync luôn trả về null, và yêu cầu siêu dữ liệu của trình xem (?token=…&meta=1 trên DocImage.axd) trả lời 404, vì vậy trình xem không hiển thị bảng thuộc tính DICOM. Sử dụng Doconut.NET8 nếu ứng dụng của bạn cần các thẻ.

Giao diệnKhi nào sử dụng
Viewer with 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
The viewer (docViewer) on DocImage.axdBạn hiển thị nghiên cứu trên trang của mình: hoạt ảnh và khung

Plugin không có widget riêng: các tệp DICOM mở trong trình xem thông thường. Khi plugin Plugin Chuyển Đổi 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 này cũng cần khả năng Dicom.

Cài đặt gói

powershell
Install-Package Doconut.NETFramework.Dicom

Để cố định plugin vào bản phát hành mà tài liệu này mô tả:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

Giữ gói DICOM ở cùng phiên bản với Doconut.NETFramework.

Tệp giấy phép của plugin, Doconut.Viewer.Dicom.lic, được đặt 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.

Đăng ký plugin

csharp
Doconut.DoconutHost.Initialize(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 giấy phép không cấp quyền, DoconutHost.Initialize sẽ ném lỗi từ Application_Start:

text
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.

Trong System.Web điều này có nghĩa là mỗi yêu cầu trả về một 500 trống, và lý do chỉ được ghi trong nhật ký sự kiện Windows (nguồn ASP.NET). Nó ném lỗi khi không có giấy phép, tệp legacy TRIAL, giấy phép không có 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 tạm thời Demo/NFR được chấp nhận. Xem Cài Đặt 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, việc mở một tệp sẽ thất bại ngay nếu khả năng sau này không còn khả dụng:

text
LicenseException: This document type requires the 'Dicom' plugin license.

Cấp phép & watermark

Trạng thái giấy phépKhởi độngĐầu ra 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 watermark trang bình thường
Giấy phép tạm thời (Demo/NFR) đang hoạt độngBắt đầuĐược hiển thị với watermark đánh giá
Không có giấy phép, tệp legacy TRIAL, giấy phép không có Dicom, hoặc giấy phép trả phí ngoài khung thời gian phiên bảnApplication_Start ném lỗi; mỗi yêu cầu trả về một 500 trống—

Quyết định watermark trang bình thường cũng áp dụng cho đầu ra DICOM. Đối với đầu ra hoạt ảnh, mỗi khung GIF đều được dán dấu, vì vậy dấu 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 giấy phép cho phép watermark tùy chỉnh; nó không thể thay thế watermark đánh giá.

Sử dụng từ C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
var metadata = await viewer.GetDicomMetadataAsync(token);
// Trên .NET Framework, giá trị này luôn là null: bộ đọc siêu dữ liệu DICOM không khả dụng cho trường hợp này
// target. Các trang, khung và hoạt ảnh được hiển thị bình thường.

Phương thức này tồn tại trong gói này để mã được chia sẻ với gói .NET 8 biên dịch, nhưng việc đọc các thẻ DICOM cần một thành phần không có bản dựng cho .NET Framework. Hãy lên kế hoạch giao diện người dùng của bạn mà không có chúng — ví dụ, ẩn bảng siêu dữ liệu khi kết quả là null.

Chế độ hiển thị và độ phân giải

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ạoDùng cho
AnimationOnlyTrang 1 = GIF động lặp lại tất cả các khungXem nhanh kiểu điện ảnh
FramesOnlyCác trang 1..N = một PNG tĩnh cho mỗi khungĐiều hướng chẩn đoán khung theo khung
AnimationAndFrames (mặc định)Trang 1 = GIF động, các trang 2..N+1 = một PNG tĩnh cho mỗi khung (N = số khung)Tổng quan và chi tiết trong một tài liệu

Thời gian hoạt ảnh được kiểm soát bởi AnimationFrameDelayMs (mặc định 100 ms = 10 FPS; thời gian GIF sử dụng đơn vị 10 ms) và LoopCount (0 = vòng lặp vô hạn).

Trình xem phát hiện rằng trang 1 là hoạt ảnh bằng cách gửi một yêu cầu HEAD cho nó. Trình xử lý DocImage.axd do đó phải chấp nhận HEAD trong Web.config (verb="GET,HEAD,POST", xem Cài đặt); nếu không, IIS trả lời 404 trước khi Doconut chạy và việc phát hiện hoạt ảnh không bao giờ hoạt động.

Độ phân giải

DicomConfig hiển thị với 100 DPI mỗi trục theo mặc định. Nếu bạn không đặt HorizontalResolution/VerticalResolution một cách rõ ràng, chúng sẽ theo BaseConfig.ImageResolution khi nó được đặt, và chỉ sau đó mới quay lại 100.

csharp
// 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 };

Xây dựng giao diện phía trước của bạn

Các hình ảnh trang, bao gồm trang đầu tiên động, sử dụng tuyến ảnh DocImage.axd tiêu chuẩn. Yêu cầu siêu dữ liệu, GET /DocImage.axd?token=<token>&meta=1, trả lời 404 trên gói này cho mọi tài liệu, bao gồm cả tệp DICOM, vì bộ đọc siêu dữ liệu không khả dụng.

Trong môi trường sản xuất

Các nghiên cứu đa khung có thể tạo cả một 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à bộ nhớ cao nhất — và trên một máy chủ đơn, bộ nhớ đó thuộc về tiến trình worker của IIS. Đối với các nghiên cứu lớn:

  • sử dụng FramesOnly khi việc kiểm tra khung quan trọng hơn phát lại;
  • 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ữ CachePages bật chỉ khi việc truy cập lặp lại đáng giá các hình ảnh đã lưu.

Đặt Doconut.Viewer.Dicom.lic bên cạnh Doconut.Viewer.lic trên mọi máy chủ, và giữ HEAD trong danh sách verb của trình xử lý.

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 đủ nằm trong Cấu hình Định dạng.

DicomConfig

csharp
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 = lặp vô hạn
    public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}

DicomDisplayMode

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);

Luôn trả về null trên gói này. Ném InvalidOperationException khi token không xác định hoặc đã hết hạn. DicomMetadata được định nghĩa để mã chia sẻ với gói .NET 8 biên dịch.

Khắc phục sự cố

Triệu chứngNguyên nhânCách khắc phục
Mỗi yêu cầu trả về một 500 trống sau khi thêm plugin; nhật ký sự kiện Windows (nguồn ASP.NET) hiển thị 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ảnCài đặt giấy phép cung cấp Dicom, hoặc loại bỏ AddPlugin<DicomPlugin>()
Mở tệp .dcm gây ra lỗi Document format '.dcm' is not supported.DicomPlugin chưa được đăng ký, hoặc gói của nó chưa được triển khaiThêm AddPlugin<DicomPlugin>() vào DoconutHost.Initialize và triển khai gói
Mở tệp .dcm gây ra lỗi LicenseException: This document type requires the 'Dicom' plugin license.Giấy phép đã tải không còn cung cấp DicomCà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à AnimationOnlySử dụng FramesOnly hoặc AnimationAndFrames cho nguồn đa khung
Trang 1 không hoạt ảnhTrình xử lý trong Web.config không chấp nhận HEADSử dụng verb="GET,HEAD,POST"
Hoạt ảnh quá nhanh hoặc quá chậmAnimationFrameDelayMs bị tắt; thời gian GIF sử dụng đơn vị 10 msĐiều chỉnh AnimationFrameDelayMs
Bộ nhớ tăng lên khi xử lý tệp đa khung lớnChế độ hiển thị, độ phân giải và bộ nhớ đệm trang đều thêm hình ảnh được giữ lạiXem Trong môi trường sản xuất; đóng các phiên một cách rõ ràng
Siêu dữ liệu luôn là nullĐược mong đợi trên gói nàySử dụng gói .NET 8 khi bạn cần các thẻ
GetDicomMetadataAsync gây ra lỗi 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

Ghi chú về Framework

So với các gói ASP.NET Core, gói này khác nhau về việc lưu trữ và siêu dữ liệu DICOM:

  • Đăng ký nằm trong Application_Start, thông qua DoconutHost.Initialize, thay vì builder.Services.AddDoconut.
  • Lỗi khởi động xuất hiện dưới dạng một 500 trống trên mỗi yêu cầu, với lý do được ghi trong nhật ký sự kiện Windows.
  • Phát hiện hoạt ảnh cần HEAD trong danh sách verb của trình xử lý DocImage.axd.
  • Không có siêu dữ liệu DICOM. Viewer.GetDicomMetadataAsync luôn trả về null và ghi một cảnh báo một lần cho một phiên DICOM; yêu cầu siêu dữ liệu DocImage.axd trả lời 404, không phải 501 của các gói .NET 6 và .NET Standard.
  • Chỉ Windows, giống như phần còn lại của gói .NET Framework.

Trang này có hữu ích không?