DICOM 插件
使用 DicomPlugin 查看医学图像
DICOM 插件为 Doconut 添加医学图像查看功能:多帧 DICOM 文件可呈现为动画概览、单帧或两者兼有。DICOM 是一种 仅插件格式 —— 没有此插件(以及其许可功能),.dcm 文件根本无法打开。
| 适用场景 | 使用情境 |
|---|---|
使用 Viewer 与 DicomConfig (C#) | 您在服务器上打开 DICOM 文件并选择帧的呈现方式 |
查看器(docViewer) | 您在页面中展示研究:动画、帧以及 DICOM 属性面板 |
HTTP 端点(?token=<token>&meta=1) | 您从自己的前端读取技术元数据 |
插件本身没有小部件:DICOM 文件在常规查看器中打开。注册了 转换插件 后,.dcm 和 .ima 文件可以转换为 Pdf、Png、Jpeg、Bmp、Tiff 或 Gif;该转换同样需要 Dicom 功能。
安装软件包
dotnet add package Doconut.NET8.Dicom未指定版本的命令会安装最新的稳定版。若要将插件固定到本文档所描述的发布版本,请单独传入版本号:
dotnet add package Doconut.NET8.Dicom --version 26.10.0保持 DICOM 包的版本与 Doconut.NET8 相同。包 ID 为 Doconut.NET8.Dicom;.<version> 仅出现在下载的 .nupkg 文件名中。
插件的许可证文件 Doconut.Viewer.Dicom.lic 放置在与 Doconut.Viewer.lic 相同的文件夹中;它会与查看器许可证一起读取。
平台。 插件可在 Doconut.NET8 所在的任何环境运行:Windows,以及基于 glibc 的 x64 Linux(不支持 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 提供标签元数据:
var metadata = await 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。
// 通过 base 属性实现统一提升…
new DicomConfig { ImageResolution = 150 };
// …或每轴控制
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };元数据
DicomMetadata 仅包含技术和成像标签——帧计数、尺寸、位深、光度解释、传输语法、模态以及默认窗口级别。它不包含任何可识别患者身份的数据。完整列表请参见 API 参考。
在查看器中
查看器无需 DICOM 特定的设置。当打开的文档是 DICOM 文件时,它会请求元数据(?token=<token>&meta=1)并添加一个 DICOM 按钮以打开技术属性面板。如果该请求失败,面板保持隐藏,文档仍会渲染。
构建您自己的前端
元数据可通过 HTTP 在 UseDoconut() 挂载的路径下获取(通常为 /doconut),适用于任何打开的文档令牌:
| 路由 | 目的 | 成功响应 |
|---|---|---|
GET ?token=<token>&meta=1 | 读取打开的 DICOM 文档的技术元数据 | 200 — DicomMetadata 作为 JSON,属性名称参考 API 参考(Width、Height、NumberOfFrames,…) |
| 状态 | 情形 | 内容 |
|---|---|---|
404 | 文档不是 DICOM 文件 | 仅返回状态 |
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
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;
}Dicom显示模式
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);当文档不是 DICOM 文件时返回 null。当令牌未知或已过期时抛出 InvalidOperationException。
Dicom元数据
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; } // "无符号" or "有符号"
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 文件 | 在请求元数据之前检查文件类型 |
GetDicomMetadataAsync 抛出 Document session not found. Please re-open document. | 令牌已过期或从未打开 | 重新打开文档 |
此页面对您有帮助吗?