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 hì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.

Mặt bề mặtKhi 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 và các 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

bash
dotnet add package Doconut.NET6.Dicom

Lệ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:

bash
dotnet add package Doconut.NET6.Dicom --version 26.10.0

Giữ gói DICOM ở cùng phiên bản với Doconut.NET6. ID gói là Doconut.NET6.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, đượ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.

Nền tảng. Plugin chạy ở bất kỳ nơi nào Doconut.NET6 chạy: Windows và Linux dựa trên glibc trên kiến trúc x64 (không phải Alpine hoặc các bản phân phối dựa trên musl). 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 mở:

bash
apt-get update && apt-get install -y libfontconfig1

Trê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

csharp
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ụ yêu cầu:

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.

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 khoảng 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:

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 khoảng thời gian phiên bản của nóBắt đầuĐược hiển thị theo quy tắc đánh dấu 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 đánh dấu đá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 khoảng thời gian phiên bảnAddDoconut() ném lỗi—

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

Sử dụng từ C#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});

Viewer.GetDicomMetadataAsync(token) tồn tại trong gói này, nhưng nó trả về null cho một phiên DICOM: xem Ghi chú khung.

Cá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ạoSử dụng cho
AnimationOnlyTrang 1 = GIF động lặp lại tất cả các khungXem nhanh dạng phim
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 (default)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 + 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 = vòng 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 đáng 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 nó được cấu hình, và chỉ sau đó mới quay lại 100.

csharp
// Bump đồng nhất 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ỉ mang 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, mô thức 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 gói này, siêu dữ liệu không khả dụng; xem Ghi chú khung.

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ở một 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ị. Trong gói này, yêu cầu trả về 501, vì vậy bảng không bao giờ xuất hiện.

Xây dựng giao diện phía trước của riêng 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ẫnMục đíchPhả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áiKhiNội dung
404Tài liệu không phải là tệp DICOMchỉ trạng thái
501Tài liệu là tệp DICOM, nhưng gói này không thể đọc các thẻ của nó{ "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Đọ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 động, 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 FramesOnly khi việc kiểm tra khung quan trọng hơn so với phát lại dạng phim;
  • 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 lợi ích truy cập lặp lại vượt quá 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ủ.

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 Format Configs.

DicomConfig

csharp
public sealed class DicomConfig : BaseConfig
{
    public int HorizontalResolution { get; set; }   // mặc định: ImageResolution khi được đặt, nếu không thì 100
    public int VerticalResolution { get; set; }     // mặc định: ImageResolution khi được đặt, nếu không thì 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);

Trả về null khi tài liệu không phải là tệp DICOM, và luôn trả về null trong gói này. Ném InvalidOperationException khi token không xác định hoặc đã hết hạn.

DicomMetadata

csharp
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ứngNguyên nhânCá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, một giấy phép không có Dicom, hoặc một giấy phép trả phí ngoài cửa sổ phiên bản của nóCài đặt mộ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 khaiThê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 DicomCài đặt một giấy phép cung cấp Dicom
Chỉ xuất hiện một trangNguồn là khung đơn, hoặc DisplayMode là AnimationOnlySử dụng FramesOnly hoặc AnimationAndFrames cho nguồn đa khung
Hoạt ảnh quá nhanh hoặc quá chậmAnimationFrameDelayMs bị tắt; thời gian GIF thực tế sử dụng đơn vị 10 msĐiều chỉnh AnimationFrameDelayMs
Bộ nhớ tăng lên khi xử lý các 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 phiên một cách rõ ràng
Siêu dữ liệu là nullTài liệu không phải là tệp DICOMKiểm tra loại tệp trước khi yêu cầu siêu dữ liệu
Siêu dữ liệu là null cho tệp DICOM, hoặc &meta trả về 501Giới hạn .NET 6 dự kiến; việc hiển thị không bị ảnh hưởngSử dụng gói .NET 8 khi bạn cần các thẻ
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

Ghi chú khung

  • Không có siêu dữ liệu DICOM. Việc hiển thị trang DICOM, các khung riêng lẻ, hoạt ảnh, biến đổi và đánh dấu nước được hỗ trợ. Siêu dữ liệu thẻ kỹ thuật không có trong gói .NET 6 vì trình đọc siêu dữ liệu không có bản dựng .NET 6. Viewer.GetDicomMetadataAsync(token) do đó trả về null cho một phiên DICOM và ghi lại một cảnh báo một lần. Yêu cầu ?token=…&meta=1 tương ứng trả về HTTP 501 Not Implemented với mã lỗi ổn định dicom_metadata_unsupported. Sử dụng gói .NET 8 khi siêu dữ liệu DICOM kỹ thuật là yêu cầu.

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