OHIF 视口叠加层Viewport Overlay定制指南四个角落的信息自定义实现与源码解析【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers本指南讲解 OHIF Viewer 中 Viewport Overlay视口叠加层的定制机制——即显示在医学影像视口四个角落左上、右上、左下、右下的文字信息如何通过customizationService在window.config中按需增删改查。读完本文你将掌握四个定制端点的作用、默认项结构、$set/$push/$splice等配置操作符的用法以及底层渲染组件和 overlay item 的完整实现原理。Viewport Overlay 是什么Viewport Overlay 是渲染在视口Viewport之上的信息层用于在不遮挡影像主体的情况下向用户展示当前影像的关键元数据例如检查日期、序列描述、窗宽窗位W/L、缩放级别、实例编号等。这些信息以绝对定位的div覆盖在影像画布四角且默认不响应鼠标事件pointer-events-none不会干扰影像操作。根据 官方文档OHIF 提供4 个视图叠加层定制端点customization end pointsviewportOverlay.topRightviewportOverlay.topLeftviewportOverlay.bottomLeftviewportOverlay.bottomRight每个端点对应视口的一个角落其值是一个overlay item 数组。你可以通过定制服务CustomizationService单独替换任意一个角落的内容也可以只对默认项做局部增删。四个角落的默认内容官方 示例定制文档 与 cornerstone 扩展源码 中给出了一致的默认值汇总如下定制端点默认内容说明viewportOverlay.topLeftStudyDate检查日期、SeriesDescription序列描述通过contentF从referenceInstance提取并格式化viewportOverlay.topRight[]空默认不显示任何内容viewportOverlay.bottomLeftWindowLevel窗宽窗位、ZoomLevel缩放级别ZoomLevel仅在当前活动工具为 Zoom 时显示viewportOverlay.bottomRightInstanceNumber实例编号显示当前实例在序列中的序号以viewportOverlay.topLeft为例默认两个 item 的定义如下来自 viewportOverlayCustomization.tsxviewportOverlay.topLeft: [ { id: StudyDate, inheritsFrom: ohif.overlayItem, label: , title: Study date, condition: ({ referenceInstance }) referenceInstance?.StudyDate, contentF: ({ referenceInstance, formatters: { formatDate } }) formatDate(referenceInstance.StudyDate), }, { id: SeriesDescription, inheritsFrom: ohif.overlayItem, label: , title: Series description, condition: ({ referenceInstance }) { return referenceInstance referenceInstance.SeriesDescription; }, contentF: ({ referenceInstance }) referenceInstance.SeriesDescription, }, ],可以看到默认内容由一组 item 组成每个 item 都基于ohif.overlayItem这一基础定制项派生而来。Overlay Item 的字段结构与渲染规则每个 overlay item 本质上是一个“声明式组件描述”核心渲染逻辑集中在 overlayItemCustomization.tsx 的ohif.overlayItem中。它支持的字段包括字段类型作用idstringitem 的唯一标识用于定位和后续操作inheritsFromstring继承的基础定制项 ID如ohif.overlayItem、ohif.overlayItem.windowLevelattributestring直接从instance上读取的 DICOM 属性名如PatientName有值时优先于contentFconditionfunction接收props返回false时该 item 不渲染不满足条件则返回nullcontentFfunction计算显示内容的函数接收props并返回字符串labelstring显示在内容前的标签文本如PN:、PatienttitlestringHTMLtitle属性鼠标悬停时的提示文字colorstring文字颜色CSS 颜色值如yellow底层渲染逻辑见 overlayItemCustomization.tsx依次执行以下步骤若定义了condition且返回假值直接不渲染该 item若定义了attribute且instance存在则取instance[attribute]作为原始值否则调用contentF(props)计算值用utils.formatValue格式化最终值若格式化后为空则返回null渲染为一个span应用label、title与color。ohif.overlayItem: function (props) { if (this.condition !this.condition(props)) { return null; } const { instance } props; const value instance this.attribute ? instance[this.attribute] : this.contentF typeof this.contentF function ? this.contentF(props) : null; const displayValue utils.formatValue(value); if (!displayValue) { return null; } return ( span classNameoverlay-item flex flex-row style{{ color: this.color || undefined }} title{this.title || } {this.label span classNamemr-1 shrink-0{this.label}/span} span classNamefont-light{displayValue}/span /span ); },除基础ohif.overlayItem外cornerstone 扩展还注册了三种派生 item用于渲染特殊内容见 CustomizableViewportOverlay.tsxohif.overlayItem.windowLevel渲染窗宽窗位如W: 1892 L: 1048ohif.overlayItem.zoomLevel渲染当前缩放级别通常配合活动工具判断toolGroupService.getActiveToolForViewportohif.overlayItem.instanceNumber渲染实例编号。通过 window.config 定制叠加层叠加层定制与其他 CustomizationService 定制一样通过应用配置文件中的customizationService数组完成。下面给出四种常见操作。1. 用$set整体替换topRightviewportOverlay.topRight默认是空数组用$set可以整体注入自定义 item参考 sampleCustomizations.tsxwindow.config { // rest of window config customizationService: [ { viewportOverlay.topRight: { $set: [ // Add your overlay items here, e.g.: // { id: CustomOverlay, inheritsFrom: ohif.overlayItem.custom }, ], }, }, ], };$set会以传入的新数组整体替换该端点的默认数组。2. 用$splice删除默认项topLeft如果不希望左上角显示StudyDate可以在viewportOverlay.topLeft上使用$splice按索引删除第一个元素参考 sampleCustomizations.tsxwindow.config { // rest of window config customizationService: [ { viewportOverlay.topLeft: { $splice: [ [0, 1], // Remove 1 item starting at index 0 (removes StudyDate) ], }, }, ], };3. 用$push追加新 itembottomLeft在左下角追加一个自定义的黄色患者姓名叠加项PatientNameOverlay参考 sampleCustomizations.tsxwindow.config { // rest of window config customizationService: [ { viewportOverlay.bottomLeft: { $push: [ { id: PatientNameOverlay, inheritsFrom: ohif.overlayItem, attribute: PatientName, label: PN:, title: Patient Name, color: yellow, condition: ({ instance }) instance instance.PatientName instance.PatientName.Alphabetic, contentF: ({ instance, formatters: { formatPN } }) formatPN(instance.PatientName.Alphabetic) (instance.PatientSex ? ( instance.PatientSex ) : ), }, ], }, }, ], };这个例子综合演示了多个字段attribute用于直接取 DICOM 标签PatientNamelabel提供PN:前缀color设为黄色condition在影像没有姓名信息时隐藏该 itemcontentF则利用formatPN格式化姓名并附加性别信息。4. 条件显示的 ZoomLevel 默认项默认的ZoomLevelitem 演示了“根据上下文决定是否显示”的典型写法见 viewportOverlayCustomization.tsx{ id: ZoomLevel, inheritsFrom: ohif.overlayItem.zoomLevel, condition: props { const activeToolName props.toolGroupService.getActiveToolForViewport(props.viewportId); return activeToolName Zoom; }, },condition接收的props中包含toolGroupService、viewportId、instance、referenceInstance、formatters等运行上下文开发者可以据此实现任意的显示逻辑。源码级原理叠加层如何被读取与渲染叠加层的实际渲染由 cornerstone 扩展的 CustomizableViewportOverlay.tsx 组件完成。其核心流程如下从servicesManager.services中取出customizationService、toolGroupService、displaySetService、cornerstoneViewportService分别调用customizationService.getCustomization(viewportOverlay.topLeft)等四个方法读取四个角落的定制数组对应源码通过displaySetService与当前imageIndex组装出displaySetProps其中包含instance当前实例与referenceInstance参考实例这些正是 overlay item 的condition/contentF所依赖的数据对应源码监听 Cornerstone 的相机/注释事件如缩放变化、超声 Pleura B-line 标注修改以刷新 scale、VOI 与叠加层内容对应源码将每个 item 与OverlayItemComponents中的对应组件ohif.overlayItem、ohif.overlayItem.windowLevel等匹配渲染到对应角落的容器中。源码注释还特别指出早期版本将四个角落定义成独立 item由于当时缺少追加append能力才这样做现在推荐直接向cornerstoneOverlay的默认数组中追加/修改而不是为单个角落定义独立 item见 CustomizableViewportOverlay.tsx。不过四个viewportOverlay.*端点依然保持向后兼容可继续使用。此外微缩显微镜dicom-microscopy扩展提供了一套较早的、基于config对象的叠加层生成方式generateFromConfig接收{ topLeft, topRight, bottomLeft, bottomRight }四组 item 列表直接渲染到对应角落见 index.tsx其 item 字段使用value/contents函数而非contentF供以config驱动叠加层的扩展参考。实战案例兽医影像的运行时叠加层定制仓库提供了一个完整、可直接对照的实战案例——兽医影像veterinary叠加层文件位于 veterinaryOverlay.jsonc。该文件演示了用global顶层结构承载定制用$set整体替换viewportOverlay.topLeft与viewportOverlay.topRight每个 item 均使用inheritsFrom: ohif.overlayItem与 cornerstone 扩展默认项写法保持一致通过attribute直接绑定兽医专用 DICOM 标签如PatientSpeciesDescription、PatientBreedDescription。{ global: { viewportOverlay.topLeft: { $set: [ { id: PatientName, inheritsFrom: ohif.overlayItem, attribute: PatientName, label: Patient, title: Patient name }, { id: PatientID, inheritsFrom: ohif.overlayItem, attribute: PatientID, label: ID, title: Patient ID }, { id: StudyDate, inheritsFrom: ohif.overlayItem, attribute: StudyDate, label: Date, title: Study date } ] }, viewportOverlay.topRight: { $set: [ { id: PatientSpecies, inheritsFrom: ohif.overlayItem, attribute: PatientSpeciesDescription, label: Species, title: Patient species }, { id: PatientBreed, inheritsFrom: ohif.overlayItem, attribute: PatientBreedDescription, label: Breed, title: Patient breed } ] } } }根据文件头注释该定制支持通过 URL 参数?customizationveterinary/veterinaryOverlay在运行时动态加载CustomizationService 的 URL 处理机制这为多院区、多科室按需切换叠加层布局提供了轻量方案。小结与排查建议定制 Viewport Overlay 只需记住三条主线四个端点各管一个角落viewportOverlay.topLeft/topRight/bottomLeft/bottomRight值均为 item 数组item 是声明式组件基于inheritsFrom: ohif.overlayItem派生可用attribute、contentF、condition、label、title、color精确控制内容与显隐定制操作符决定增删改方式$set整体替换、$push追加、$splice按索引删除、$merge合并属性。排查叠加层不生效的问题时可以从 CustomizableViewportOverlay.tsx 的getCustomization读取逻辑入手确认四个端点定制是否被正确加载若自定义 item 始终不显示请检查condition是否返回了假值、contentF/attribute是否能取到非空值以及formatValue格式化后的结果是否为空——这三处是 ohif.overlayItem 渲染链路上最常见的“静默跳过”原因。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考