OHIF Segmentation 模式全解析基于 Labelmap 的分割读/编辑/导出实现与扩展指南【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers导读本文以 modes/segmentation/README.md 为骨架深入剖析 OHIF Viewers 中Segmentation 模式ohif/mode-segmentation的实现原理。该模式面向医学影像的Labelmap 分割标注场景开箱即用地提供分割数据的读取read、编辑edit与导出export全流程能力并同时支持 Labelmap 与 Contour 两种分割表示。读完本文你将掌握Segmentation 模式与 Basic 模式的关系与差异、模式布局与视口如何组装、三套工具组的划分与画笔/擦除器/剪刀工具配置、标签图与轮廓分割面板的自动切换机制以及如何通过modeFactory与自定义定制块快速派生属于自己的分割模式。模式定位专注 Labelmap 分割的独立 ModeSegmentation 模式是 OHIF 平台中与 Basic、Longitudinal 等并列的独立模式Mode。按 modes/segmentation/README.md 的定义它是OHIF segmentation mode which enables labelmap segmentation read/edit/export即一个让用户对 Labelmap 分割数据进行读取、编辑与导出的专用模式。在 modes/segmentation/package.json 中该模式包名为ohif/mode-segmentation版本号与平台主线保持一致其description字段与 README 定义完全对应。值得注意的依赖结构peerDependencies覆盖了模式运行所需的全部扩展ohif/core、ohif/extension-cornerstone、ohif/extension-cornerstone-dicom-seg、ohif/extension-cornerstone-dicom-rt、ohif/extension-cornerstone-dicom-sr、ohif/extension-default、ohif/extension-dicom-pdf、ohif/extension-dicom-video以及基础模式ohif/mode-basic其中 SEG分割与 RT放疗结构扩展直接决定了该模式的分割能力边界SR 扩展则提供测量/报告的显示支持包入口为module: src/index.tsx即模式实例定义本身。从实现看Segmentation 模式不是从零搭建的而是以ohif/mode-basic为基座进行扩展它复用了 Basic 模式的modeFactory、onModeEnter、onModeExit、isValidMode、layoutTemplate与extensionDependencies再叠加自己特有的布局、工具组、工具栏与生命周期逻辑见 modes/segmentation/src/index.tsx。模式实例布局、路由与生命周期模式核心定义在 modes/segmentation/src/index.tsx 中modeInstance是模式的“自描述”数据对象包含以下关键字段export const modeInstance { id, routeName: segmentation, displayName: Segmentation, toolbarButtons: [ { $reference: cornerstone.toolbarButtons }, { $reference: cornerstone.segmentationToolbarButtons }, ], toolbarSections: [ { $reference: cornerstone.segmentationModeToolbarSections }, { $reference: cornerstone.segmentationToolbarSections }, ], toolGroupAdditions: { default: [], mpr: [], volume3d: [] }, initToolGroups, modeCustomizations: segmentationModeCustomizations, activatePanelTriggers: [], onModeEnter, onModeExit, isValidMode, nonModeModalities: [SM, ECG, OT, DOC], routes: [segmentationRoute], extensions: extensionDependencies, hangingProtocol: [ohif/mnGrid], sopClassHandlers: [ohif.sopClassHandler, segmentation.sopClassHandler, dicomRT.sopClassHandler], };要点解读routeName为segmentation路由路径为template挂载在segmentationRoute上toolbarButtons / toolbarSections使用$reference引用语法属于“组合式”声明它们指向 cornerstone 扩展中注册的通用工具栏按钮与分割专用按钮、分区见下文工具栏小节而不是在模式内硬编码按钮列表nonModeModalities声明[SM, ECG, OT, DOC]为“非模式模态”——当研究Study只包含这些模态时模式判定为无效即无法对纯超声SM、心电ECG、其他OT、文档DOC影像进行分割hangingProtocol显式优先使用网格布局协议ohif/mnGrid便于多视口同步分割sopClassHandlers只注册三个处理器默认栈处理器普通影像、SEG 处理器分割与 RT 处理器放疗结构这正是该模式的分割职能在数据层的体现。布局左右面板与三种视口segmentationLayout继承自 Basic 模式的布局 idohif.layout但在右面板上做了关键替换export const segmentationLayout { id: ohif.layout, props: { leftPanels: [ohif.thumbnailList], leftPanelResizable: true, rightPanels: [ cornerstone.labelMapSegmentationPanel, // Labelmap 分割面板含编辑工具 cornerstone.contourSegmentationPanel, // Contour 分割面板含编辑工具 ], rightPanelResizable: true, viewports: [ { namespace: cornerstone.viewport, displaySetsToDisplay: [ohif.sopClassHandler] }, { namespace: segmentation.viewport, displaySetsToDisplay: [segmentation.sopClassHandler] }, { namespace: dicomRT.viewport, displaySetsToDisplay: [dicomRT.sopClassHandler] }, ], }, };对照 modes/basic/src/index.tsx 中 Basic 模式的basicLayout两者的差异一目了然维度Basic 模式Segmentation 模式右面板cornerstone.segmentationcornerstone.measurements测量优先Labelmap 分割面板 Contour 分割面板分割优先视口命名空间6 类视口含 SR、PDF、ECG 等3 类视口常规影像、SEG 分割、RT 结构右面板默认状态rightPanelClosed: true无该字段右面板展开布局中注释明确指出面板列表以“字面量”形式在模式路由进入时注入到标准的leftPanels/rightPanels定制项中因此模式阶段的定制块与全局定制都可以在布局解析前覆盖它们——这是 OHIF 定制化体系Customization在该模式上的直接体现。生命周期钩子在 Basic 之上叠加自动切页模式定义了自己的onModeEnter其实现先调用 Basic 模式的onModeEnter负责初始化工具组、注册工具栏、应用toolGroupAdditions、清理测量等随后额外挂载分割面板自动切换处理器export function onModeEnter(ctx: withAppTypes) { basicOnModeEnter.call(this, ctx); const { segmentationService, viewportGridService, panelService } ctx.servicesManager.services; const { unsubscribeAutoTabSwitchEvents } setUpAutoTabSwitchHandler({ segmentationService, viewportGridService, panelService, }); this._unsubscriptions.push(...unsubscribeAutoTabSwitchEvents); }而onModeExit直接复用 Basic 模式的实现见 modes/basic/src/index.tsx它会统一执行this._unsubscriptions中的全部取消订阅函数并销毁 toolGroupService、syncGroupService、segmentationService 与 cornerstoneViewportService——因此 Segmentation 模式在onModeEnter中 push 的订阅能被正确清理不会泄漏。分割面板自动切换Labelmap 与 Contour 的智能联动setUpAutoTabSwitchHandler见 modes/segmentation/src/utils/setUpAutoTabSwitchHandler.ts是该模式区别于 Basic 模式的核心增强逻辑。它解决的实际问题是当用户首次添加分割时右面板应自动切换到与分割类型匹配的标签页。实现要点const autoTabSwitchEvents [ segmentationService.EVENTS.SEGMENTATION_MODIFIED, segmentationService.EVENTS.SEGMENTATION_REPRESENTATION_MODIFIED, ]; let shouldSwitchTab true; const unsubscribeAutoTabSwitchEvents autoTabSwitchEvents .map(eventName segmentationService.subscribe(eventName, () { const segmentations segmentationService.getSegmentations(); if (!segmentations.length) { shouldSwitchTab true; // 全部分割被移除后下次添加时重新触发切换 return; } const activeViewportId viewportGridService.getActiveViewportId(); const activeRepresentation segmentationService .getSegmentationRepresentations(activeViewportId) ?.find(representation representation.active); if (activeRepresentation shouldSwitchTab) { shouldSwitchTab false; switch (activeRepresentation.type) { case Labelmap: panelService.activatePanel( ohif/extension-cornerstone.panelModule.panelSegmentationWithToolsLabelMap, true ); break; case Contour: panelService.activatePanel( ohif/extension-cornerstone.panelModule.panelSegmentationWithToolsContour, true ); break; } } }) ) .map(subscription subscription.unsubscribe);逻辑拆解事件源订阅SEGMENTATION_MODIFIED与SEGMENTATION_REPRESENTATION_MODIFIED两个事件覆盖分割数据被修改或分割表示表示类型被修改的场景状态复位当getSegmentations()返回空数组全部分割被删除时将shouldSwitchTab置回true确保下一次新增分割时再次触发自动切换按类型分派通过viewportGridService.getActiveViewportId()找到当前活动视口再在其分割表示中查找active标记的表示依据type字段在Labelmap与Contour之间分派到不同的面板 IDpanelSegmentationWithToolsLabelMap/panelSegmentationWithToolsContour一次性语义shouldSwitchTab标志位保证整个会话中只在首次添加分割时切换一次之后用户手动切换的标签页状态不被干扰。返回值{ unsubscribeAutoTabSwitchEvents }是取消订阅函数数组正好被onModeEnter通过this._unsubscriptions.push(...)纳入统一清理。工具组初始化default / mpr / volume3d 三套配置Segmentation 模式的工具组初始化在 modes/segmentation/src/initToolGroups.ts入口函数签名与 Basic 模式完全一致function initToolGroups({ extensionManager, toolGroupService, commandsManager }) { initDefaultToolGroup(extensionManager, toolGroupService, commandsManager, default); initMPRToolGroup(extensionManager, toolGroupService, commandsManager); initVolume3DToolGroup(extensionManager, toolGroupService); }default2D 轴位工作流的主工具组mpr多平面重建MPR工具组额外绑定 Crosshairs十字线并禁用 ReferenceLinesvolume3d3D 体渲染工具组仅含旋转、缩放、平移三件套。toolGroupAdditions字段{ default: [], mpr: [], volume3d: [] }为后续定制预留了空数组钩子——扩展模式或?customization模块可以通过mode阶段的$push命令向这三个工具组追加额外工具。活跃工具与鼠标绑定三套工具组的活跃active工具保持一致即分割模式下的基础导航能力const tools { active: [ { toolName: toolNames.WindowLevel, bindings: [{ mouseButton: Enums.MouseBindings.Primary }] }, { toolName: toolNames.Pan, bindings: [{ mouseButton: Enums.MouseBindings.Auxiliary }] }, { toolName: toolNames.Zoom, bindings: [{ mouseButton: Enums.MouseBindings.Secondary }, { numTouchPoints: 2 }], }, { toolName: toolNames.StackScroll, bindings: [{ mouseButton: Enums.MouseBindings.Wheel }, { numTouchPoints: 3 }], }, ], ... };对应的按键/触控约定为PrimaryWindowLevel窗宽窗位、AuxiliaryPan平移、SecondaryZoom缩放、滚轮StackScroll翻页双指/三指触摸分别映射缩放与翻页。volume3d 工具组则把 Primary 换成了TrackballRotateTool旋转。被动工具完整的分割编辑工具清单Segmentation 模式在passive列表中注册了远超 Basic 模式的分割编辑工具矩阵这是本模式与 Basic 模式在工具层面最显著的区别。全部工具在创建后经由commandsManager.run(initializeSegmentLabelTool, { tools })统一初始化分割标签工具。按功能可归类如下画笔与擦除器Brush / Eraser 家族——均以Brush为父工具通过activeStrategy指定策略并统一受MIN_SEGMENTATION_DRAWING_RADIUS/MAX_SEGMENTATION_DRAWING_RADIUS约束见 modes/segmentation/src/constants.ts0.5与99.5工具名activeStrategy用途CircularBrushFILL_INSIDE_CIRCLE圆形画笔填充CircularEraserERASE_INSIDE_CIRCLE圆形擦除SphereBrushFILL_INSIDE_SPHERE球状画笔体数据SphereEraserERASE_INSIDE_SPHERE球状擦除ThresholdCircularBrushTHRESHOLD_INSIDE_CIRCLE阈值圆形画笔ThresholdSphereBrushTHRESHOLD_INSIDE_SPHERE阈值球状画笔ThresholdCircularBrushDynamicTHRESHOLD_INSIDE_CIRCLEthreshold: { isDynamic: true, dynamicRadius: 3 }动态阈值圆形画笔ThresholdSphereBrushDynamicTHRESHOLD_INSIDE_SPHEREthreshold: { isDynamic: true, dynamicRadius: 3 }动态阈值球状画笔剪刀工具ScissorsCircleScissors圆形、RectangleScissors矩形、SphereScissors球状用于快速框选区域生成分割。分割辅助工具LabelmapSlicePropagation切片传播、MarkerLabelmap标记、ClickSegment点击选中分割段、SegmentBidirectional分割内双向测量、SegmentSelect分割段选择、LabelMapEditWithContourTool用轮廓编辑标签图。轮廓分割Contour Segmentation工具PlanarFreehandContourSegmentation自由手绘轮廓、LivewireContourSegmentation活线/磁吸轮廓、SculptorTool雕刻工具。样条 ROI 工具——以SplineContourSegmentation为父工具全部开启enableTwoPointPreview两点预览CatmullRomSplineROItype: CATMULLROMLinearSplineROItype: LINEARBSplineROItype: BSPLINE。测量与浏览工具PlanarFreehandROI、WindowLevelRegion、Magnify、StackScroll、UltrasoundDirectional。禁用工具ReferenceLines与AdvancedMagnify在 default 组中被显式禁用disabled列表。MPR 工具组的 Crosshairs 细节MPR 工具组除复用上述工具外还以特殊方式注册Crosshairs见 modes/segmentation/src/initToolGroups.ts 中initMPRToolGroup将 Crosshairs 绑定到Primary ShiftmouseButton: Primary, modifierKey: Shift使其独占一个鼠标组合键——注释解释了原因若不绑定独立按键Crosshairs 会在 Primary 上激活而它是disableOnPassive的一旦工具栏激活其他 Primary 工具画笔/缩放/平移就会被立即禁用从而与它们互斥绑定独立按键后可与之共存开启viewportIndicators视口指示器配置circleRadius: 5、xOffset: 0.95、yOffset: 0.05通过getReferenceLineColor根据视口 id 或方位返回参考线颜色viewport-0为rgb(200, 0, 0)、viewport-1为rgb(200, 200, 0)、viewport-2为rgb(0, 200, 0)按方位axial/sagittal/coronal同样有对应色兜底色为#0c0autoPan默认关闭enabled: false, panSize: 10。MPR 工具组同时把ReferenceLines加入disabled避免与 Crosshairs 的参考线能力冲突。工具栏定制分割按钮包与分区模式实例通过$reference引用了 cornerstone 扩展注册的三个定制项其定义位于 extensions/cornerstone/src/customizations/segmentationToolbarCustomization.tscornerstone.segmentationToolbarButtons分割编辑工具栏按钮包与通用按钮包cornerstone.toolbarButtons一起构成该模式的默认按钮集合cornerstone.segmentationModeToolbarSections与cornerstone.segmentationToolbarSections工具栏分区容器定义。在按钮包内部结构非常清晰以BrushTools、LabelMapUtilities、ContourUtilities、LabelMapTools、ContourTools为容器BrushTools/LabelMapTools/ContourTools使用ohif.toolBoxButtonGroup嵌套工具盒子按钮组LabelMapUtilities/ContourUtilities使用ohif.Toolbar内嵌工具条具体工具按钮如PlanarFreehandContourSegmentationTool配置了evaluate评估函数如evaluate.cornerstone.segmentation在无分割时显示Create new segmentation to enable this tool.禁用提示、evaluate.cornerstone.hasSegmentationOfType校验 Contour 类型分割是否存在以及commands命令序列激活工具、激活对应类型的分割表示等。值得注意的是该定制文件也导出了与模式常量一致的MIN_SEGMENTATION_DRAWING_RADIUS 0.5/MAX_SEGMENTATION_DRAWING_RADIUS 99.5印证画笔半径上下限是跨模式与工具栏统一约定的。工具栏注释还提示这些按钮包可被segmentationEditing.jsonc等定制拉入 Basic / Longitudinal 模式即分割编辑能力可以被其他模式按需复用。模式有效性校验与自定义定制块数据驱动的有效性判断Segmentation 模式复用了 Basic 模式导出的isValidMode实现见 modes/basic/src/index.tsx其判定逻辑为数据驱动若存在excludedStudies研究中每条属性均命中任一排除项则无效若存在excludedModalities研究包含其中任一模态则无效若存在modeModalities研究至少包含一个列出的模态才有效数组条目要求全部模态都存在否则依据nonModeModalities只要研究包含任意一个不在该列表中的模态即有效。Segmentation 模式设置nonModeModalities: [SM, ECG, OT, DOC]因此只有当研究完全由这些模态构成时模式才不可用只要存在任何可分割的影像模态如 CT、MR、PT模式即为有效。定制块可编辑的分割面板模式注册了segmentationModeCustomizations定制块见 modes/segmentation/src/index.tsxexport const customizations { segmentationModeCustomizations: {}, };注释明确说明与 Basic 模式注册的basicModeCustomizations中panelSegmentation.disableEditing: trueBasic 模式默认禁用分割面板编辑不同Segmentation 模式的定制块是空的——分割面板在该模式下是可编辑的。该块虽为空但仍被注册以便 bootstrap 或?customization模块以模式作用域追加值。这正是该模式“默认可编辑”语义的定制化实现。基于 modeFactory 派生自定义分割模式模式的最终导出对象包含modeFactory来自 Basic 模式const mode { id, modeFactory, modeInstance, extensionDependencies, customizations, };modeFactory使用immutability-helper的update将modeConfiguration应用到modeInstance上见 modes/basic/src/index.tsx 中modeFactory实现。这意味着站点可以定义一个mySegmentation模式通过 modeConfiguration 以不可变更新的方式扩展本模式例如替换initToolGroups为自定义工具组初始化函数initToolGroups已被模式显式导出export { initToolGroups }通过$push向toolbarButtons/toolGroupAdditions追加按钮与工具覆盖modeCustomizations以调整面板行为修改nonModeModalities、hangingProtocol或sopClassHandlers以适配特定临床工作流。与相关扩展的协同Segmentation 模式的运转依赖若干扩展的能力注入均在 modes/basic/src/index.tsx 的extensionDependencies中声明ohif/extension-cornerstone-dicom-seg提供 SEG 的 SOP Class Handler 与专用视口见 extensions/cornerstone-dicom-seg/src/index.tsx视口以React.lazy懒加载OHIFCornerstoneSEGViewport承担分割数据的解析、显示与渲染ohif/extension-cornerstone-dicom-rt提供 RTSTRUCT 的读取与渲染使放疗结构可与分割同屏对照ohif/extension-cornerstone提供全部影像交互工具utilityModule.tools、分割面板Labelmap/Contour与分割工具栏按钮包ohif/mode-basic提供模式工厂、生命周期基座与有效性校验逻辑。小结Segmentation 模式以极简的包描述README 仅一句话启用 Labelmap 分割的读/编辑/导出承载了一套完整的分割工作流实现它复用 Basic 模式的生命周期与组合机制替换为双分割面板布局与三视口路由注册了覆盖画笔、擦除器、剪刀、阈值、动态阈值、样条与轮廓分割的完整工具矩阵并通过setUpAutoTabSwitchHandler在 Labelmap 与 Contour 表示之间智能切换面板。对于需要搭建专用分割应用的开发者该模式既可直接使用也可通过modeFactory与定制化体系低成本地派生定制版本——其完整实现均可从 modes/segmentation/src/index.tsx、modes/segmentation/src/initToolGroups.ts 与 extensions/cornerstone/src/customizations/segmentationToolbarCustomization.ts 中继续深入研读。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考