OHIF Viewer 技术 FAQ 实战指南：元数据要求、大体积渲染内存优化与测量/排序自定义

OHIF Viewer 技术 FAQ 实战指南：元数据要求、大体积渲染内存优化与测量/排序自定义

【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers

OHIF Viewer 是一个零足迹（zero-footprint）的 DICOM 浏览器，其工作列表查询、多平面重建（MPR）、体渲染、测量与标注等工作流在实际部署中经常会遇到"缩略图不显示""大体积数据内存占用过高""测量无法动态注入""系列排序不符合预期"等实现类问题。本文基于仓库中的 Technical FAQ 文档，逐条梳理这些高频问题的成因、配置与代码级解决方案，并对照 OHIF 仓库源码给出可验证的实现依据，帮助你在自己的部署与扩展开发中快速定位和解决问题。

相关阅读：如需在视口四角（viewport corners）添加自定义图标，可参考同目录下的 add-viewport-icon.md。

1. Viewer 打开但没有缩略图：supportsWildcard与服务器通配符支持

1.1 问题现象与根因

当 DICOMWeb 应用打开后工作列表（worklist）一片空白、没有缩略图时，原因可能有很多。Technical FAQ 重点指出了一种最常见的场景：配置文件中开启了supportsWildcard: true，但你的 DICOMweb 服务器并不支持通配符（wildcard）匹配查询。

以工作列表标签页的过滤为例，OHIF 会构造如下形式的查询请求（图片见 filtering-worklist.png）：

https://<server>/dicomweb/studies?PatientName=*Head*&limit=101&offset=0&fuzzymatching=false&includefield=00081030%2C00080060

可以看到PatientName=*Head*使用了*通配符包裹查询值。如果服务器能正确处理这种请求，一切正常；但如果服务器不支持这种过滤语法，查询就会失败，进而导致缩略图无法加载。

1.2 源码层面：通配符是如何产生的

通配符拼接逻辑位于 DICOMWeb 数据源实现中：

• qido.js 中的mapParams函数会根据配置决定是否为患者姓名、患者 ID、检查号、检查描述等字段添加*通配符：

const useWildcard = params?.disableWildcard !== undefined ? !params.disableWildcard : options.supportsWildcard; const withWildcard = value => { return useWildcard && value ? `*${value}*` : value; }; const parameters = { PatientName: withWildcard(params.patientName), '00100020': withWildcard(params.patientId), AccessionNumber: withWildcard(params.accessionNumber), StudyDescription: withWildcard(params.studyDescription), // ... };

• index.ts 中定义了DicomWebConfig类型的supportsWildcard字段，注释明确说明其含义为"服务器是否支持通配符匹配"。

1.3 解决方案

根据你的服务器能力，二选一即可：

方案 A：关闭 OHIF 端的通配符拼接。在配置文件（如 default.js）的数据源configuration中设置supportsWildcard: false。注意该选项的默认值就是false（见 configurationFiles.md 中的说明），只有当你确认服务器支持时才应显式开启。

方案 B：修改服务器代码以支持*通配符。FAQ 给出了一个伪代码示例，把*转换为 SQL 的LIKE通配符%：

Pseudocode: For each filter in filters: if filter.value contains "*": Convert "*" to SQL LIKE wildcard ("%") Add "metadataField LIKE ?" to query else: Add "metadataField = ?" to query

此外，若你的服务器连fuzzymatching也不支持，还应注意配套的supportsFuzzyMatching配置项（默认不开启模糊匹配），两者常常需要一起评估。

2. OHIF Viewer 正常工作所需的 DICOM 元数据清单

如果你的数据源返回的元数据缺失关键字段，OHIF 的显示集（displaySet）组织、图像渲染、MPR、分割与结构化报告等工作流都可能失败。以下清单完整来自 Technical FAQ，并标注了每一项的用途，建议作为对接数据源时的核对表。

2.1 必备（Mandatory）

所有模态（All Modalities）

渲染（Rendering）：要正确渲染图像，还需要以下标签，否则应使用窗宽窗位工具手动调整：

• RescaleIntercept、RescaleSlope：用于可视化时对像素值进行重新缩放（CT 值换算等）。
• WindowCenter、WindowWidth：显示用的窗位与窗宽参数。

部分数据集（Some Datasets）

• InstanceNumber：用于实例排序；缺失时实例可能乱序。

MPR（多平面重建）渲染与工具

• ImagePositionPatient、ImageOrientationPatient：图像在患者坐标系中的位置与方向，是 MPR 正确重建的前提。

SEG（分割）

• FrameOfReferenceUID：用于处理分割图层。
• 序列（sequences）：ReferencedSeriesSequence、SharedFunctionalGroupsSequence、PerFrameFunctionalGroupsSequence。

RTSTRUCT（放疗结构集）

• FrameOfReferenceUID：用于处理分割图层。
• 序列：ROIContourSequence、StructureSetROISequence、ReferencedFrameOfReferenceSequence。

US（超声）

• NumberOfFrames：多帧图像的帧数。
• SequenceOfUltrasoundRegions：用于测量。
• FrameTime：帧间隔时间（若存在）。

SR（结构化报告）

• 编码报告内容与模板所需的各种序列：ConceptNameCodeSequence、ContentSequence、ContentTemplateSequence、CurrentRequestedProcedureEvidenceSequence、CodingSchemeIdentificationSequence。

PT 伴 SUV 校正（正电子发射断层扫描标准化摄取值）

• 与放射性药物、单位、校正和时间相关的序列与标签：RadiopharmaceuticalInformationSequence、SeriesDate、SeriesTime、CorrectedImage、Units、DecayCorrection、AcquisitionDate、AcquisitionTime、PatientWeight。

PDF

• EncapsulatedDocument：包含 PDF 文档本体。

Video

• NumberOfFrames：视频帧数。

2.2 可选（Optional）

还有大量可选的标签可以增强查看体验，但对基本功能不是必需的，例如：患者信息（Patient Information）、检查信息（Study Information）、序列信息（Series Information）、实例信息（Instance Information）以及帧信息（Frame Information）。这些标签缺失不会阻断查看，但会减少界面上可展示的元数据丰富度。

3. MPR 与体渲染处理大数据量：useNorm16Texture与preferSizeOverAccuracy

当患者影像数据量超过客户端机器内存时，OHIF 提供了两个配置项来降低内存占用，它们都是**应用级配置（App Config）**中的布尔开关。在 AppTypes.ts 中可以看到这两个字段与experimentalStudyBrowserSort、useCPURendering等一同定义：

experimentalStudyBrowserSort?: boolean; preferSizeOverAccuracy?: boolean; useNorm16Texture?: boolean;

3.1useNorm16Texture：使用 16 位纹理

WebGL 官方只支持 8 位和 32 位数据类型。对大多数医学图像来说，8 位不够用，32 位又太浪费；但 MPR 和体渲染此前必须使用 32 位数据类型，导致内存消耗不理想。

通过 WebGL 2.0 的EXT_texture_norm16扩展，WebGL 可以支持 16 位数据类型，这对大多数图像而言是理想的选择（可在 WebGL 报告类工具中检查你的环境是否启用了该扩展，界面示例见 webgl-report-norm16.png）。

在配置文件中开启该标志后，MPR 与体渲染会强制使用 16 位数据类型，内存占用约可减少一半。FAQ 以一个大型 PT/CT 检查为例（见 large-pt-ct.jpeg）：

• 未开启标志时，应用显示约399 MB内存占用（见 memory-profiling-regular.png）；
• 本地开启标志后，内存降至约249 MB（见 webgl-int16.png）。

仓库中提供了一个专门开启该选项的示例配置 default_16bit.js，其核心就是一行：

useNorm16Texture: true,

注意：

• 使用 16 位纹理（若被支持）不会对渲染产生任何影响，pixelData会原样呈现。
• 对于无法用 16 位数据类型表示的数据集，该标志会被忽略，回退到 32 位数据类型。
• 虽然 WebGL 已提供 16 位数据类型支持，但在某些环境（例如基于 Intel 的 macOS）中仍存在已知问题，可能引发渲染异常，部署前需要在目标浏览器环境中充分验证。

3.2preferSizeOverAccuracy：优先体积而非精度

这是另一个可在配置文件中设置的标志，用于强制 MPR 和体渲染使用half_float（16 位浮点）数据类型。选择它而非useNorm16Texture的主要原因是它在硬件和浏览器上有更广泛的支持；代价是精度低于 16 位整数纹理，可能引入一些渲染伪影。

half_float的精度范围如下（数字越大舍入误差越大）：

Integers between 0 and 2048 can be exactly represented (and also between −2048 and 0) Integers between 2048 and 4096 round to a multiple of 2 (even number) Integers between 4096 and 8192 round to a multiple of 4 Integers between 8192 and 16384 round to a multiple of 8 Integers between 16384 and 32768 round to a multiple of 16 Integers between 32768 and 65519 round to a multiple of 32

可以看到，超过 2048 的区间就会出现精度损失。开启preferSizeOverAccuracy后，同一检查的内存快照见 preferSizeOverAccuracy.png。

3.3 如何选择

两者都可作为 configurationFiles.md 所述的应用配置直接写在window.config顶层。配置方式与常规配置文件完全一致，例如APP_CONFIG=config/default_16bit.js指定 16 位配置，或按npm run build前的环境变量方式切换。

4. 如何动态加载测量（动态注入标注）

在某些工作流中，你需要在进入检查（mode）时根据外部数据（例如服务器返回的测量结果）以编程方式动态添加测量，而不是依赖用户在界面上手动绘制。Technical FAQ 给出的推荐做法是组合使用 OHIF 的MeasurementService与 CornerstoneTools 的 Annotation API，下面以Rectangle矩形测量为例完整展开。

4.1 背景：OHIF 的 mapped 测量与 Cornerstone 原始标注

当你在 OHIF 中创建一个测量后，终端里获取measurementService会看到一条测量记录，但它是 OHIF 内部的mapped（已映射）cornerstone 测量，包含geReport、source等 OHIF 内部细节，这些并不需要关心。

如果需要拿到原始标注数据，可以调用 CornerstoneTools 的 API，按uid直接获取：

cornerstoneTools.annotation.state.getAnnotation("ea45a45c-0731-47d4-9438-d2a53ffea4ff");

注意：对于Rectangle、EllipticalRoi这类工具，annotation 的data中会保存一个pointsInShape属性用于存放形状内的点，动态加载时同样可以移除该属性。

4.2 在 mode 生命周期钩子中动态添加标注

OHIF 中有很多可以添加标注的地方，但官方始终推荐拥有自己的扩展与 mode，以便对你的自定义 API 保持完全控制。此处以在longitudinalmode 中添加逻辑为例（你也可以创建自己的扩展和 mode，在onModeEnter或其他生命周期钩子中加入标注；完整的生命周期钩子说明见 lifecycle.md）。

实际应用中，你需要为每个检查加载对应的测量；为了示例简洁，下面先硬编码一个存放测量 JSON 的 URL（该 URL 应替换为你自己的数据服务地址）：

import * as cs3dTools from '@cornerstonejs/tools'; onModeEnter: function ({ servicesManager, extensionManager, commandsManager }: withAppTypes) { // rest of logic const annotationResponse = await fetch( '<your-server>/rectangle-roi.json' ); const annotationData = await annotationResponse.json(); cs3dTools.annotation.state.addAnnotation(annotationData); },

4.3 自动映射到 OHIF MeasurementService

关键点在于：OHIF 为 CornerstoneTools 预先配置了测量映射器（位于 measurementServiceMappingsFactory.ts）。当你调用cs3dTools.annotation.state.addAnnotation(annotationData)添加标注后，OHIF 会自动将其映射到 OHIF 的 measurement service，从而刷新后即可在图像上看到该测量。

该工厂函数为各类工具（Length、Bidirectional、RectangleROI、EllipticalROI、Angle、CobbAngle、ArrowAnnotate、CircleROI、SplineROI、LivewireContour、Probe、SegmentBidirectional、UltrasoundDirectional等）建立了从 cornerstone 事件到MeasurementService格式的双向转换逻辑；仓库中 RectangleROI.ts 即为矩形测量的具体映射实现。

4.4 右侧面板不显示测量？切换到非追踪测量面板

刷新查看器后测量会出现在图像上，但如果右侧面板仍是空的，原因在于右侧面板默认使用的是追踪测量面板（tracking measurement panel）。此时可以把布局配置中的

rightPanels: [dicomSeg.panel, tracked.measurements],

改为使用默认扩展的非追踪测量面板：

rightPanels: [dicomSeg.panel, '@ohif/extension-default.panelModule.measure'],

修改后，右侧面板即可展示该动态加载的测量。

5. 按指定值对序列排序（实验性 StudyBrowserSort）

5.1 开启实验性组件

当前 OHIF 正在重新设计 study panel 与 study browser。在此期间，可以通过在配置文件（应用级配置）中开启experimentalStudyBrowserSort: true来启用实验性的StudyBrowserSort组件：

{ experimentalStudyBrowserSort: true, }

该配置字段同样定义在 AppTypes.ts 中（experimentalStudyBrowserSort?: boolean）。开启后，study panel 中会出现一个排序下拉框，用于按指定值对序列排序。该组件之所以标注为"实验性"，是因为 study panel 仍在重新设计中、未来界面可能变化，但排序功能本身会保留。

组件内置了 3 个默认排序函数：Series Number（序列号）、Series Image Count（序列图像数）、Series Date（序列日期）。在仓库的默认定制模块 studyBrowserCustomization.ts 中可以看到studyBrowser.sortFunctions的默认实现，例如：

'studyBrowser.sortFunctions': [ { label: i18n.t('StudyBrowser:Series Number'), sortFunction: (a, b) => { return a?.SeriesNumber - b?.SeriesNumber; }, }, { label: i18n.t('StudyBrowser:Series Date'), sortFunction: (a, b) => { const dateA = new Date(formatDate(a?.SeriesDate)); const dateB = new Date(formatDate(b?.SeriesDate)); return dateB.getTime() - dateA.getTime(); }, }, ],

5.2 通过 customizationModule 添加自定义排序函数

你可以通过 customization 模块添加自定义排序函数，键名为studyBrowser.sortFunctions，位于default键之下。既可以使用默认扩展中现成的 getCustomizationModule.tsx，也可以在自己的扩展中创建。

方式一：定义在 extension 的 customizationModule 中

export default function getCustomizationModule({ servicesManager, extensionManager }) { return [ { name: 'default', value: [ { id: 'studyBrowser.sortFunctions', values: [ { label: 'Series Number', sortFunction: (a, b) => { return a?.SeriesNumber - b?.SeriesNumber; }, }, // Add more sort functions as needed ], }, ], }, ]; }

方式二：通过customizationService.addModeCustomizations在运行时添加

customizationService.addModeCustomizations([ { id: 'studyBrowser.sortFunctions', values: [{ label: 'Series Images', sortFunction: (a, b) => { return a?.numImageFrames - b?.numImageFrames; }, }], }, ]);

注意：studyBrowser.sortFunctions下的values是一个数组，其中每个元素是一个包含label和sortFunction的对象；多个排序函数可以共存。

5.3 工作原理

StudyBrowserSort组件会检索这些排序函数，并在displaySetService 层面对全部 displaySets 进行排序。由于它作用于服务层，排序结果会反映到应用的所有部分——包括 study panel 中的缩略图。你可以在组件下拉框中定义多个函数并选择使用哪一个。

6. 修改 Cine 自动挂载行为（autoCineModalities）

OHIF 在进入某些模态时默认会自动挂载 Cine 播放（即自动循环播放多帧序列）。你可以通过autoCineModalities这个 mode customization 修改该行为，其值为应自动挂载 Cine 的模态数组。

默认行为：查看器默认对OT和US两种模态开启 Cine。这一默认值在 cornerstone 扩展的 miscCustomization.ts 中定义：

export default { cinePlayer: CinePlayer, autoCineModalities: ['OT', 'US'], // ... };

自定义示例：通过customizationService.addModeCustomizations覆盖：

customizationService.addModeCustomizations([ { id: 'autoCineModalities', modalities: ['OT', 'US'], }, ]);

将modalities数组改成你需要自动挂载 Cine 的模态列表即可；例如只想对超声开启，可改为modalities: ['US']，或者按需求加入其他多帧模态。

7. 延伸阅读

本文内容源自 platform/docs/docs/faq/technical.md，相关实现细节可继续深入以下仓库文件：

• 配置项全量说明：configurationFiles.md（含supportsWildcard、useNorm16Texture、experimentalStudyBrowserSort、maxNumRequests等参数与默认值）
• 配置类型定义：AppTypes.ts
• DICOMWeb 数据源通配符实现：qido.js、index.ts
• 16 位纹理示例配置：default_16bit.js
• 测量映射工厂：measurementServiceMappingsFactory.ts
• 排序函数默认定制：studyBrowserCustomization.ts
• Cine 默认模态：miscCustomization.ts
• 生命周期钩子（用于动态加载测量的onModeEnter等）：lifecycle.md

【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers