DICOM 插件
使用 DicomPlugin 查看医学图像
DICOM 插件为 Doconut 添加医学图像查看功能:多帧 DICOM 文件可以渲染为动画概览、单帧或两者兼有。DICOM 是一种 仅插件格式 — 没有此插件(及其授权功能),.dcm 文件根本无法打开。
在 .NET Framework 4.7.2 上,DICOM 文件完整渲染 — 页面、帧和动画 — 但技术元数据(DICOM 标签)不可用。
Viewer.GetDicomMetadataAsync总是返回null,并且查看器的元数据请求(?token=…&meta=1在DocImage.axd上)返回404,因此查看器不显示 DICOM 属性面板。如果您的应用程序需要这些标签,请使用Doconut.NET8。
| 场景 | 使用时机 |
|---|---|
Viewer with DicomConfig (C#) | 您在服务器上打开 DICOM 文件,并选择其帧的呈现方式 |
The viewer (docViewer) on DocImage.axd | 您在页面中展示研究:动画和帧 |
插件本身没有独立小部件:DICOM 文件在常规查看器中打开。注册了 转换插件 后,.dcm 和 .ima 文件可以转换为 Pdf、Png、Jpeg、Bmp、Tiff 或 Gif;该转换同样需要 Dicom 功能。
安装包
Install-Package Doconut.NETFramework.Dicom将插件固定到本文档所描述的发布版本:
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0保持 DICOM 包与 Doconut.NETFramework 的版本一致。
插件的许可证文件 Doconut.Viewer.Dicom.lic 放置在与 Doconut.Viewer.lic 相同的文件夹中;它会与查看器许可证一起读取。
注册插件
Doconut.DoconutHost.Initialize(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});插件(Name: "Doconut DICOM Viewer")为 .dcm 和 .ima 扩展名注册查看器,这受 Dicom 功能的限制。如果许可证未授予该功能,DoconutHost.Initialize 会在 Application_Start 中抛出:
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.在 System.Web 中,这意味着每个请求都会返回空的 500,且原因仅记录在 Windows 事件日志(来源 ASP.NET)中。它会因无许可证、旧版 TRIAL 文件、缺少 Dicom 的许可证以及在版本窗口之外使用的付费许可证而抛出异常。临时 Demo/NFR 许可证是被接受的。参见 许可证设置。
由于没有内置查看器能够处理这些格式,如果相应功能随后不可用,打开这些文件将直接失败:
LicenseException: This document type requires the 'Dicom' plugin license.许可与水印
| 许可证状态 | 启动时 | DICOM 输出 |
|---|---|---|
付费许可证授予 Dicom,且在其版本窗口内 | 启动 | 按照正常页面水印规则渲染 |
| 有效的临时(Demo/NFR)许可证 | 启动 | 使用评估水印渲染 |
无许可证、旧版 TRIAL 文件、缺少 Dicom 的许可证,或在版本窗口之外的付费许可证 | Application_Start 抛出异常;每个请求返回空的 500 | — |
正常页面水印的决策同样适用于 DICOM 输出。对于动画输出,每个 GIF 帧都会加上水印,因此在播放期间标记始终可见。仅当许可证允许自定义水印时才会使用自定义 DocOptions.Watermark;它不能替代评估水印。
从 C# 使用
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});var metadata = await viewer.GetDicomMetadataAsync(token);
// 在 .NET Framework 上,这始终为 null:此时 DICOM 元数据读取器不可用
// target. 页面、帧和动画正常渲染。此方法存在于此包中,以便与 .NET 8 包共享的代码能够编译,但读取 DICOM 标记需要一个没有 .NET Framework 构建的组件。请在没有它们的情况下规划用户界面——例如,当结果为 null 时隐藏元数据面板。
显示模式和分辨率
显示模式
多帧 DICOM 文件可以通过三种方式呈现(DicomDisplayMode):
| 模式 | 生成的页面 | 用途 |
|---|---|---|
AnimationOnly | 第 1 页 = 动画 GIF,循环所有帧 | 快速电影式回顾 |
FramesOnly | 第 1..N 页 = 每帧一个静态 PNG | 逐帧诊断导航 |
AnimationAndFrames (默认) | 第 1 页 = 动画 GIF, 第 2..N+1 页 = 每帧一个静态 PNG(N = 帧数) | 在同一文档中提供概览和细节 |
动画定时由 AnimationFrameDelayMs 控制(默认 100 毫秒 = 10 FPS;GIF 定时使用 10 毫秒单位),以及 LoopCount(0 = 永久循环)。
查看器通过发送 HEAD 请求来判断第 1 页是否为动画。DocImage.axd 处理程序因此必须在 Web.config 中接受 HEAD(verb="GET,HEAD,POST",参见安装);如果没有它,IIS 会在 Doconut 运行之前返回 404,导致动画检测永远失效。
分辨率
DicomConfig 默认以每轴 100 DPI 渲染。如果未显式设置 HorizontalResolution/VerticalResolution,它们会在设置了 BaseConfig.ImageResolution 时遵循该值,只有在此之后才回退到 100。
// 通过基属性统一提升…
new DicomConfig { ImageResolution = 150 };
// …或每轴控制
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };构建您自己的前端
页面图像(包括动画的第一页)使用标准的 DocImage.axd 图像路径。元数据请求 GET /DocImage.axd?token=<token>&meta=1 在此包中对每个文档(包括 DICOM 文件)返回 404,因为元数据读取器不可用。
在生产环境中
多帧研究可以生成动画以及每帧一个静态页面。AnimationAndFrames 提供最丰富的导航,但也带来最高的渲染和内存开销——在单服务器上,这些内存归属于 IIS 工作进程。对于大型研究:
- 在帧检查比播放更重要时使用
FramesOnly; - 避免在未测量内存的情况下提升两个分辨率轴;
- 在研究不再打开时显式关闭会话;
- 仅在重复访问值得保留图像时才保持
CachePages开启。
在每台服务器上将 Doconut.Viewer.Dicom.lic 放在 Doconut.Viewer.lic 旁边,并在处理程序的 verb 列表中保留 HEAD。
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;
}DicomDisplayMode
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);在此包中始终返回 null。当令牌未知或已过期时抛出 InvalidOperationException。DicomMetadata 已定义,以便与 .NET 8 包共享的代码能够编译。
故障排除
| 症状 | 原因 | 解决方案 |
|---|---|---|
在添加插件后,每个请求返回空的 500;Windows 事件日志(来源 ASP.NET)显示 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 未注册,或其包未部署 | 在 DoconutHost.Initialize 中添加 AddPlugin<DicomPlugin>() 并部署包 |
打开 .dcm 文件时抛出 LicenseException: This document type requires the 'Dicom' plugin license. | 已加载的许可证不再授予 Dicom | 安装授予 Dicom 的许可证 |
| 仅出现一页 | 源是单帧,或 DisplayMode 为 AnimationOnly | 对多帧源使用 FramesOnly 或 AnimationAndFrames |
| 第 1 页未动画 | Web.config 中的处理程序不接受 HEAD | 使用 verb="GET,HEAD,POST" |
| 动画速度过快或过慢 | AnimationFrameDelayMs 已关闭;GIF 定时使用 10 毫秒单位 | 调整 AnimationFrameDelayMs |
| 在大型多帧文件上内存增长 | 显示模式、分辨率和页面缓存都会增加保留的图像 | 参见 在生产环境;显式关闭会话 |
元数据始终为 null | 此包中预期如此 | 当需要标签时,请使用 .NET 8 包 |
GetDicomMetadataAsync 抛出 Document session not found. Please re-open document. | 令牌已过期或从未打开 | 重新打开文档 |
框架说明
与 ASP.NET Core 包相比,此包在托管方式和 DICOM 元数据方面有所不同:
- 注册 在
Application_Start中,通过DoconutHost.Initialize,而不是builder.Services.AddDoconut。 - 启动失败 在每个请求上表现为一个空的
500,原因记录在 Windows 事件日志中。 - 动画检测 需要在
DocImage.axd处理程序的verb列表中加入HEAD。 - 没有 DICOM 元数据。
Viewer.GetDicomMetadataAsync总是返回null,并记录一次性警告用于 DICOM 会话;DocImage.axd元数据请求返回404,而不是 .NET 6 和 .NET Standard 包的501。 - 仅限 Windows,与 .NET Framework 包的其余部分一样。
此页面对您有帮助吗?