DICOM 插件

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

安装软件包

dotnet add package Doconut.NETStandard.Dicom

未指定版本的命令会安装最新的稳定版。若要将插件固定在当前的 26.8.0 版本，请单独传入版本号：

dotnet add package Doconut.NETStandard.Dicom --version 26.8.0

保持 DICOM 软件包的版本与 Doconut.NETStandard 相同。软件包 ID 为 Doconut.NETStandard.Dicom；.26.8.0 仅出现在下载的 .nupkg 文件名中。

注册插件

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

插件（Name："Doconut DICOM Viewer"）为 .dcm 和 .ima 扩展名注册查看器，并受 Dicom 能力的控制。缺少或不足的非临时授权通常会在 AddDoconut() 时失败。由于没有内置查看器能够处理这些格式，运行时门也会在能力后续不可用时直接报错：

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

打开 DICOM 文件

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

显示模式

多帧 DICOM 文件可以通过三种方式呈现（DicomDisplayMode）：

动画时长由 AnimationFrameDelayMs 控制（默认 100 ms = 10 FPS；GIF 粒度为 10 ms 单位）以及 LoopCount（0 表示无限循环）。

分辨率

DicomConfig 默认以每轴 100 DPI 渲染。分辨率属性具有以下回退链：如果未显式设置 HorizontalResolution/VerticalResolution，它们会遵循已配置的 BaseConfig.ImageResolution，否则回退到 100。

// 通过基属性统一提升…
new DicomConfig { ImageResolution = 150 };

// …或按轴单独控制
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };

.NET Standard 上的 DICOM 元数据可用性

DICOM 页面渲染、单帧、动画、变换和水印均受支持。技术标签元数据在 .NET Standard 包中不可用，因为元数据读取器仅随 .NET 8 构建提供。

Viewer.GetDicomMetadataAsync(token) 因此在 DICOM 会话中返回 null 并记录一次性警告。对应的 ?token=…&meta 中间件请求会返回 HTTP 501 Not Implemented，错误码为 dicom_metadata_unsupported。当技术 DICOM 元数据是必需时，请使用 .NET 8 包。

完整配置参考

完整的 DicomConfig 属性表位于 API Reference → Format Configs。参考应用中按扩展名切换的生产示例：

".DCM" or ".IMA" => new DicomConfig { DisplayMode = DicomDisplayMode.AnimationAndFrames },

水印与内存行为

普通页面的水印决策同样适用于 DICOM 输出。对于动画输出，每个 GIF 帧都会加上水印，以保证在播放期间水印始终可见。只有在许可证路径允许自定义水印时，才会使用自定义的 DocOptions.Watermark；它不能替代评估版水印。

多帧研究可以生成动画以及每帧的静态页面。AnimationAndFrames 提供最丰富的导航体验，但也带来最高的渲染和缓存开销。针对大型研究：

• 当帧检查比电影式播放更重要时使用 FramesOnly；
• 避免在未测量内存的情况下同时提升两个轴的分辨率；
• 当研究不再打开时显式关闭会话；
• 仅在重复访问收益大于保留图像成本时才启用 CachePages。

故障排查