DICOM 插件

使用 DicomPlugin 查看医学图像

DICOM 插件为 Doconut 添加了医学图像查看功能:多帧 DICOM 文件可渲染为动画概览、单帧或两者兼有。DICOM 是一种 仅插件格式 —— 没有此插件(及其许可功能),.dcm 文件根本无法打开。

场景使用时机
Viewer with DicomConfig (C#)您在服务器上打开 DICOM 文件并选择其帧的呈现方式
查看器 (docViewer)您在页面中展示研究:动画和帧

插件本身没有小部件:DICOM 文件在常规查看器中打开。注册了转换插件后,.dcm 和 .ima 文件可以转换为 Pdf、Png、Jpeg、Bmp、Tiff 或 Gif;该转换同样需要 Dicom 功能。

安装软件包

bash
dotnet add package Doconut.NET6.Dicom

未指定版本的命令会安装最新的稳定版。若要将插件固定到本文档所描述的版本,请单独传入版本号:

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

保持 DICOM 包与 Doconut.NET6 的版本一致。包 ID 为 Doconut.NET6.Dicom;.<version> 仅出现在下载的 .nupkg 文件名中。

插件的许可证文件 Doconut.Viewer.Dicom.lic 放在与 Doconut.Viewer.lic 相同的文件夹中;它会与查看器许可证一起读取。

平台。 插件可在 Doconut.NET6 运行的任何环境中运行:Windows,以及基于 glibc 的 x64 Linux(不支持 Alpine 或其他基于 musl 的发行版)。在 Linux 上,首次打开文档前请安装字体配置库:

bash
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. 而失败

注册插件

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

插件(Name:"Doconut DICOM Viewer")为 .dcm 和 .ima 扩展名注册查看器,由 Dicom 功能进行控制。若没有授予该功能的许可证,AddDoconut() 会在启动时抛出 InvalidOperationException,在应用提供请求之前:

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.

它会因缺少许可证、旧版 TRIAL 文件、缺少 Dicom 的许可证,以及在版本窗口之外使用的付费许可证而抛出异常。临时 Demo/NFR 许可证亦被接受。请参阅许可证设置了解许可证的加载方式。

由于没有内置查看器能够处理这些格式,如果该功能随后不可用,运行时门也会强制失败:

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

许可与水印

许可证状态启动时DICOM 输出
授予 Dicom 的付费许可证,在其版本窗口内启动按照正常页面水印规则渲染
有效的临时(Demo/NFR)许可证启动使用评估水印渲染
无许可证、旧版 TRIAL 文件、缺少 Dicom 的许可证,或在版本窗口之外的付费许可证AddDoconut() 抛出—

正常页面水印的决定同样适用于 DICOM 输出。对于动画输出,每个 GIF 帧都会被加上水印,以便在播放期间始终可见。仅当许可证路径允许自定义水印时才会使用自定义 DocOptions.Watermark;它不能替代评估水印。

在 C# 中使用

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

Viewer.GetDicomMetadataAsync(token) 在此包中存在,但它在 DICOM 会话中返回 null:请参见 框架说明。

显示模式、分辨率和元数据

显示模式

多帧 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。

csharp
// 通过 base property 实现统一凹凸…
new DicomConfig { ImageResolution = 150 };

// …或 per-axis 控制
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

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

DicomDisplayMode

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

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

当文档不是 DICOM 文件时返回 null,在此包中始终返回 null。当令牌未知或已过期时抛出 InvalidOperationException。

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" 或 "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 未注册,或其包未部署在 AddDoconut() 中添加 AddPlugin<DicomPlugin>() 并部署包
打开 .dcm 文件时抛出 LicenseException: This document type requires the 'Dicom' plugin license.已加载的许可证不再授予 Dicom安装授予 Dicom 的许可证
仅出现一页源是单帧,或 DisplayMode 为 AnimationOnly对多帧源使用 FramesOnly 或 AnimationAndFrames
动画过快或过慢AnimationFrameDelayMs 已关闭;有效的 GIF 时间使用 10 毫秒单位调整 AnimationFrameDelayMs
大多帧文件导致内存增长显示模式、分辨率和页面缓存都会增加保留的图像参见 在生产环境;显式关闭会话
元数据为 null文档不是 DICOM 文件在请求元数据前检查文件类型
对于 DICOM 文件,元数据为 null,或 &meta 返回 501预期的 .NET 6 限制;渲染不受影响当需要标签时使用 .NET 8 包
GetDicomMetadataAsync 抛出 Document session not found. Please re-open document.令牌已过期或从未打开重新打开文档

框架说明

  • 无 DICOM 元数据。 支持 DICOM 页面渲染、单帧、动画、变换和水印。技术标签元数据在 .NET 6 包中不可用,因为元数据读取器没有 .NET 6 构建。因此 Viewer.GetDicomMetadataAsync(token) 对 DICOM 会话返回 null 并记录一次性警告。相应的 ?token=…&meta=1 请求返回带有稳定错误码 dicom_metadata_unsupported 的 HTTP 501 Not Implemented。当技术 DICOM 元数据是必需时,请使用 .NET 8 包。

此页面对您有帮助吗?