OHIF cornerstone-dicom-rt 扩展解析:DICOM RT 结构集(RTSTRUCT)读取与显示工作流
OHIF cornerstone-dicom-rt 扩展解析:DICOM RT 结构集(RTSTRUCT)读取与显示工作流
导读
@ohif/extension-cornerstone-dicom-rt 是 OHIF(Open Health Imaging Foundation)Viewers 中负责 DICOM RT 读取(DICOM RT read workflow) 的扩展包,它允许用户加载一个 DICOM RTSS(RT Structure Set,放射治疗结构集)图像并在 OHIF 中显示。本文将围绕该扩展的 README 与源码,完整梳理其从 SOP 注册、显示集构建、RT 结构解析,到 contour 轮廓渲染与按需水合(hydrate)的完整链路,并给出在 OHIF 中配置、安装与调试该扩展的实战方法。读完本文,你将掌握 RTSTRUCT 数据在 OHIF 中“如何被识别、如何被加载、如何被绘制、如何与基础影像联动”的全部技术细节。
一、扩展概览:README 说了什么
扩展的官方 README 内容非常精简,核心信息只有三条:
- 功能定位:DICOM RT 读取工作流(DICOM RT read workflow);
- 核心能力:允许加载一个 DICOM RTSS 图像并在 OHIF 中显示;
- 元数据:作者为 OHIF,许可证为 MIT。
package.json 中扩展名为 @ohif/extension-cornerstone-dicom-rt(版本 3.14.0-beta.29),描述字段与 README 一致,并声明了完整的 peerDependencies(@ohif/core、@ohif/extension-cornerstone、@ohif/extension-default、@ohif/i18n、React 18.3.1 等),说明它必须运行在已安装 cornerstone 扩展的 OHIF 环境中。
README 虽短,但“DICOM RT 读取工作流”这个定位背后承载着完整的实现:一个扩展要能在 OHIF 中显示 RTSS,需要同时提供 SOP Class Handler(把 RTSTRUCT 序列转成显示集)、Viewport Module(专用的 RT 渲染视口) 和 Commands Module(水合与跳转命令)。下面逐一从源码展开。
二、扩展装配:index.tsx 中的模块声明
扩展的入口 index.tsx 定义了一个标准的 OHIF 扩展对象,注册了以下模块:
const extension: Types.Extensions.Extension = {
id,
getCommandsModule,
getViewportModule({ servicesManager, extensionManager, commandsManager }) {
const ExtendedOHIFCornerstoneRTViewport = props => {
return (
<OHIFCornerstoneRTViewport
servicesManager={servicesManager}
extensionManager={extensionManager}
commandsManager={commandsManager}
{...props}
/>
);
};
return [{ name: 'dicom-rt', component: ExtendedOHIFCornerstoneRTViewport }];
},
getSopClassHandlerModule,
};
关键实现细节:
- 延迟加载视口:RT 视口组件通过
React.lazy按需加载(带webpackPrefetch: true),外层用React.Suspense包裹,避免未使用 RT 功能时拉取无关代码。 - 视口模块:以
{ name: 'dicom-rt', component: ... }形式注册,供各 Mode 消费。 - SOP 处理模块:负责将 RTSTRUCT 序列转化为显示集(详见下一节)。
- 扩展 ID 取自 id.js 中的包名,即
@ohif/extension-cornerstone-dicom-rt,其 SOP Class Handler 唯一 ID 为@ohif/extension-cornerstone-dicom-rt.sopClassHandlerModule.dicom-rt。
从源码结构看,该扩展没有独立的面板(Panel)模块,也没有工具栏模块——它专注于“读 RT 并画轮廓”,其余交互能力复用 cornerstone 扩展。
三、SOP Class Handler:RTSTRUCT 序列如何变成显示集
getSopClassHandlerModule.ts 是 RT 读取链路的起点。它注册了:
const { sopClassDictionary } = utils;
const sopClassUids = [sopClassDictionary.RTStructureSetStorage];
即只处理 RT Structure Set Storage 这一种 SOP Class,其余序列不会被本扩展接管。
3.1 显示集构建(_getDisplaySetsFromSeries)
当 OHIF 发现 RTSTRUCT 序列后,会调用 getDisplaySetsFromSeries(instances)。核心逻辑:
- 用
utils.sortStudyInstances(instances)排序,并选择最后一个实例作为“最近创建”的那个(RTSS 保存到既有序列时,只有实例级时间能反映保存动作); - 用
utils.getLatestInstanceDateTime(instance)取SeriesDate / SeriesTime作为显示集日期时间; - 构造一个
isDerivedDisplaySet: true、isOverlayDisplaySet: true、Modality: 'RTSTRUCT'的显示集对象,并携带instance、instances、wadoRoot/wadoUri/wadoUriRoot等数据源信息; - 建立引用关系:从实例的
ReferencedSeriesSequence(必要时由ReferencedFrameOfReferenceSequence.RTReferencedStudySequence.RTReferencedSeriesSequence推导,见_deriveReferencedSeriesSequenceFromFrameOfReferenceSequence)取得referencedSeriesInstanceUID与referencedImages,再通过displaySetService.getDisplaySetsForReferences(...)找到被引用的基础影像显示集,写入referencedDisplaySetInstanceUID; - 异步补引用:如果被引用的显示集尚未加载(例如 RT 序列先于影像序列到达),会订阅
displaySetService.EVENTS.DISPLAY_SETS_ADDED,等被引用的显示集加入后再回填引用信息; - 最后为显示集挂上
load方法,参数为{ headers, createSegmentation = true }。
3.2 延迟加载与去重(_load)
显示集的 load 最终落到 _load():
if (
(rtDisplaySet.loading || rtDisplaySet.isLoaded) &&
loadPromises[SOPInstanceUID] &&
_segmentationExists(rtDisplaySet)
) {
return loadPromises[SOPInstanceUID];
}
它用一个模块级 loadPromises 缓存按 SOPInstanceUID 去重的加载 Promise,避免同一 RT 显示集被多次请求时重复拉取。加载流程为:
- 若
structureSet尚未解析,调用loadRTStruct(extensionManager, rtDisplaySet, headers)解析 RT 结构; - 若
createSegmentation为真(默认),调用segmentationService.createSegmentationForRTDisplaySet(rtDisplaySet)创建对应分割(这里实际是 contour 表示,见第四节); resolve后置loading = false;出错则reject并在finally中复位 loading。
该文件还体现了两个工程细节:引用超过一个显示集时输出警告并只应用第一个;
_segmentationExists通过@cornerstonejs/tools的segmentation.state.getSegmentation(displaySetInstanceUID)判断分割是否已存在,防止重复创建。
四、loadRTStruct:RT 结构集的解析与轮廓数据装载
loadRTStruct.js 是 RT 解析的核心模块,内部依赖 dcmjs(DicomMessage.readFile + DicomMetaDictionary.naturalizeDataset)。
4.1 两种取数路径
loadRTStruct 根据数据源配置决定如何获取实例:
const dataSource = extensionManager.getActiveDataSource()[0];
const { bulkDataURI } = dataSource.getConfig?.() || {};
if (!bulkDataURI || !bulkDataURI.enabled) {
instance = await getRTStructInstance({ extensionManager, rtStructDisplaySet, headers });
} else {
instance = await checkAndLoadContourData({ instance, dataSource, ... });
}
- 路径一(常规):
getRTStructInstance通过 cornerstone 扩展注册的utilityModule.common中的dicomLoaderService.findDicomDataPromise(...)拉取整个 RT 实例的二进制数据,再用 dcmjs 解析为自然化数据集(naturalized dataset),设置_meta元信息。 - 路径二(bulk data):当数据源配置了
bulkDataURI.enabled(例如本地数据源绕过、或 DICOMweb 服务返回非内联的 bulk 数据)时,走checkAndLoadContourData。
4.2 checkAndLoadContourData 的三种 ContourData 形态
RTSS 的 ROIContourSequence 中每个 Contour 的 ContourData 可能有三种存储形态,该函数逐一处理:
- 内联数组:
Array.isArray(contourData),直接Promise.resolve; - BulkDataURI:通过
dataSource.retrieve.bulkDataURI({ BulkDataURI, StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID })异步拉取,拉回的是字节数组(Blob),随后用TextDecoder解码、按\分隔并parseFloat; - InlineBinary:
atob解码 Base64,按\切分,并校验“坐标总数能被 3 整除”(每 3 个数一组 x/y/z),逐组parseFloat过滤非法值。
每个 ROI 的轮廓数据用 Promise.allSettled 并发等待,最后统一写回 Contour.ContourData。校验失败(如实例无 ROIContourSequence、ContourData 非法、数据源缺少 retrieve.bulkDataURI 等)会以 Promise reject 的方式明确报错。
4.3 structureSet 结构对象
解析完成后,loadRTStruct 会构建一个结构集对象:
const structureSet = {
StructureSetLabel: instance.StructureSetLabel,
SeriesInstanceUID: instance.SeriesInstanceUID,
ROIContours: [],
visible: true,
ReferencedSOPInstanceUIDsSet: new Set(),
};
随后遍历 ROIContourSequence:
- 对每个 Contour,按
NumberOfContourPoints * 3步长把ContourData拆成{x, y, z}点数组; - 用
supportedContourTypesMap标注轮廓几何类型(CLOSED_PLANAR、OPEN_NONPLANAR、OPEN_PLANAR、POINT)及isSupported标记(当前仅POINT在映射表中标为支持,其余默认false); - 收集
ContourImageSequence.ReferencedSOPInstanceUID到ReferencedSOPInstanceUIDsSet; - 调用
_setROIContourMetadata填充每个 ROI 的元数据。
4.4 ROI 元数据与颜色
_setROIContourMetadata 把三张序列表关联起来:
- 用
ROINumber === ReferencedROINumber从StructureSetROISequence找到结构名ROIName、生成算法ROIGenerationAlgorithm、描述ROIDescription; _setROIContourDataColor优先取ROIDisplayColor,缺失时用dcmjs.data.Colors.dicomlab2RGB把RecommendedDisplayCIELabValue(CIELab)转成 RGB,写入colorArray;- 若存在
RTROIObservationsSequence,用ReferencedROINumber匹配观察记录,把ObservationNumber、ROIObservationDescription、RTROIInterpretedType、ROIInterpreter深拷贝进ROIContourData.RTROIObservations。
这些元数据最终交由 segmentation service 转换为 contour 表示渲染。
五、RT 视口:渲染、水合提示与工具组
5.1 视口组件结构
OHIFCornerstoneRTViewport.tsx 是扩展注册的 dicom-rt 视口,特点如下:
- 单显示集约束:
displaySets.length > 1时直接抛错(RT 视口只承载一个 RT 显示集); - 工具组按视口隔离:
toolGroupId = RTToolGroup-${viewportId},由 initRTToolGroup.ts 通过customizationService.getCustomization('cornerstone.overlayViewportTools')取得工具列表,再经ToolGroupService.createToolGroupAndAddTools创建;卸载时调用segmentationService.removeRepresentationsFromViewport与toolGroupService.destroyToolGroup清理; - 引用显示集缺失兜底:当 RT 序列被单独启动(如通过
SeriesInstanceUID直启)而找不到referencedDisplaySetInstanceUID时,读取 customizationmissingReferenceDisplaySetHandler并调用它优雅处理,而不是直接崩溃; - 加载进度:订阅
SEGMENTATION_LOADING_COMPLETE与SEGMENT_LOADING_COMPLETE事件,把percentComplete、numSegments传给ui.loadingIndicatorTotalPercent定制组件,渲染“Loading RTSTRUCT...”进度界面; - 首段定位:当
rtDisplaySet.firstSegmentedSliceImageId与viewportOptions.presentationIds存在时,通过usePositionPresentationStore的setPositionPresentation把视口位置预设到首个分割切片,实现加载完成后自动跳到病灶所在层面; - 渲染底层:实际仍复用
@ohif/extension-cornerstone的OHIFCornerstoneViewport,传入[referencedDisplaySet, rtDisplaySet](基础影像 + RT 叠加),从而保证缩放、平移、窗宽窗位等基础交互行为一致。
5.2 水合(Hydration)提示
视口挂载后,若 RT 尚未加载完(rtIsLoading),会进入 promptHydrateRT.ts 的流程:
return utils.promptHydrationDialog({
servicesManager,
viewportId,
displaySet: rtDisplaySet,
preHydrateCallbacks,
hydrateCallback: hydrateRTDisplaySet,
type: 'RTSTRUCT',
});
它会弹出一个类型为 RTSTRUCT 的水合确认对话框(与 SEG 的水合提示一致),用户确认后执行:
commandsManager.runCommand('hydrateSecondaryDisplaySet', {
displaySet: rtDisplaySet,
viewportId,
});
这条命令由 cornerstone 扩展注册,最终调用本扩展 commandsModule 中的 hydrateRTSDisplaySet(见下节)。水合的目的与 RT/SEG 场景一致:默认只把轮廓作为 overlay 轻量绘制(不重建体积分割),避免加载大量标注拖慢首屏;当用户真正需要测量、编辑或联动时再按需补齐完整数据。
六、Commands Module:水合命令与状态恢复
getCommandsModule.ts 注册了唯一的动作 hydrateRTSDisplaySet,默认上下文为 cornerstone-dicom-rt:
const actions = {
hydrateRTSDisplaySet: ({ displaySet, viewportId }) => {
if (displaySet.Modality !== 'RTSTRUCT') {
throw new Error('Display set is not an RTSTRUCT');
}
const referencedDisplaySet = displaySetService.getDisplaySetByUID(
displaySet.referencedDisplaySetInstanceUID
);
commandsManager.runCommand('updateStoredSegmentationPresentation', {
displaySet,
type: SegmentationRepresentations.Contour,
});
commandsManager.runCommand('updateStoredPositionPresentation', {
viewportId,
displaySetInstanceUIDs: [referencedDisplaySet.displaySetInstanceUID],
});
viewportGridService.setDisplaySetsForViewport({
viewportId,
displaySetInstanceUIDs: [referencedDisplaySet.displaySetInstanceUID],
});
},
};
这条命令做三件事:
- 校验:非 RTSTRUCT 显示集直接抛错;
- 状态恢复:分别调用
updateStoredSegmentationPresentation(记录当前 contour 表示的分割展示状态)与updateStoredPositionPresentation(记录视口当前的缩放/平移位置),确保后续把被引用的显示集放回视口时,轮廓与视角都能还原到水合前的状态; - 切回基础影像:用
viewportGridService.setDisplaySetsForViewport把视口中的显示集替换为被引用的基础影像显示集——完成“RT 轮廓完成水合后回到原始影像继续阅片”的闭环。
七、如何接入 OHIF:安装、注册与数据准备
7.1 安装与注册
在 OHIF monorepo 中,该扩展位于 extensions/cornerstone-dicom-rt,作为 workspace 包参与 pnpm install。要在自定义 Mode 中使用:
- 在应用的扩展列表中引入:
import cornerstoneRT from '@ohif/extension-cornerstone-dicom-rt';
// ...
extensions: [cornerstone, cornerstoneRT, defaultExtension, ...],
- 在 Mode 的
routes中把该扩展提供的视口dicom-rt挂到相应 layout(可参考 default 扩展的 Mode 装配 中getViewportModule的注册方式)。
7.2 RT 数据来源与格式要求
- SOP Class:仅支持
RT Structure Set Storage,其他 SOP Class 不会被本扩展接管; - 引用完整性:RTSTRUCT 实例必须携带
ReferencedSeriesSequence(或可由ReferencedFrameOfReferenceSequence推导出的引用关系),且被引用的影像序列需存在于同一 study 中,否则显示集无法建立referencedDisplaySetInstanceUID,视口会走missingReferenceDisplaySetHandler兜底流程; - ContourData 形态:内联数组、
BulkDataURI(需数据源配置bulkDataURI.enabled且实现retrieve.bulkDataURI)、InlineBinary(Base64、\分隔)三种形态均可解析; - 颜色:优先
ROIDisplayColor,否则使用RecommendedDisplayCIELabValue(CIELab)经 dcmjs 转换; - 轮廓类型:解析层对
CLOSED_PLANAR、OPEN_NONPLANAR、OPEN_PLANAR、POINT四种几何类型做了标记,POINT在映射表中标记为支持。
7.3 与分割(SEG)工作流的共性
该扩展的“overlay 显示 + 按需水合”模式与 cornerstone-dicom-seg 一致:RTSTRUCT 与 SEG 都被视为叠加在基础影像上的辅助显示集,加载后默认轻量展示,用户确认后才水合为可交互的 contour/labelmap 分割。区别在于 RT 的 contour 数据源是 RTSS 的 ROIContourSequence(包含三维坐标点列),而 SEG 则是逐体素的 labelmap。
八、总结
@ohif/extension-cornerstone-dicom-rt 虽然 README 只有寥寥数行,但源码实现了一条完整且健壮的 RT 读取链路:
- 识别:
getSopClassHandlerModule注册RT Structure Set Storage,把 RTSTRUCT 序列转换为带引用关系的派生显示集; - 解析:
loadRTStruct用 dcmjs 解析结构集,兼容内联、bulk data、inline binary 三种 ContourData,并合成 ROI 名称、类型、观察记录与颜色; - 渲染:
OHIFCornerstoneRTViewport将基础影像与 RT 显示集叠加渲染,提供加载进度与首段定位,工具组按视口隔离; - 水合:
promptHydrateRT弹出确认对话框,用户确认后由hydrateRTSDisplaySet命令恢复分割展示与视口位置,再切回基础影像完成闭环。
对开发者而言,这意味着:只要数据源能正确提供携带引用信息的 RTSS 实例,OHIF 即可开箱即用地完成放射治疗结构集的浏览;若要深度定制(如自定义轮廓类型支持、调整水合确认交互、修改加载进度组件),可分别通过 customization(cornerstone.overlayViewportTools、ui.loadingIndicatorTotalPercent、missingReferenceDisplaySetHandler)与既有命令链扩展实现。