OHIF Viewers v3 全版本迁移路线图从 2.x 到 3.12 的升级指南总览【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers本指南以 OHIF Viewers开源 zero-footprint DICOM 浏览器及肿瘤学病灶追踪平台官方迁移文档为骨架系统梳理从 OHIF v2 到 v3、以及 v3 内部各次版本升级3.7→3.8、3.8→3.9、3.9→3.10、3.10→3.11、3.11→3.12的完整迁移路径。读完本文你将掌握v2→v3 的架构级重构要点Modes/Extensions、Cornerstone3D、配置结构变化、每次版本升级的破坏性变更清单与代码迁移动作以及如何在当前仓库中定位对应的源码佐证与示例。迁移总览从哪个版本开始迁移OHIF Viewers 的迁移文档按从哪个版本迁移而来组织选择对应指南即可获取升级到最新版本平台的路径见 migration-guide/index.md。当前仓库覆盖的迁移路线包括迁移路线对应文档2.x → 3.5from-v2.md3.7 → 3.8from-3p7-to-3p8.md3.8 → 3.93p8-to-3p9/index.md3.9 → 3.10 beta3p9-to-3p10/index.md3.10 → 3.113p10-to-3p11/index.md3.11 → 3.12 beta3p11-to-3p12/index.md大版本重构从 OHIF v2 迁移到 v3OHIF v3 是对 v2 的一次重大架构重写目的是让平台更模块化、更易维护。官方文档明确强调这份指南定位为迁移总览而非逐步迁移配方且仍在持续更新中。理解以下差异是成功迁移的前提。迁移动机与时间成本官方列出了 v2 用户迁移到 v3 的收益新 UI 与侧边面板/工具栏/布局系统带来更直观的体验采用 Cornerstone3D 渲染与工具库后性能显著提升支持 OffScreen 渲染、GPU 加速、体数据流式加载、3D 标注与测量、视口间工具状态共享Modes 与 Extensions 架构让定制聚焦于业务场景以及社区驱动的 Mode 生态与长期维护支持。迁移时长取决于 v2 中的定制复杂度。官方明确提示了三个痛点大量自定义代码v2 中的定制与覆盖需要针对 v3 新结构和新 API 重构UI 定制v3 的组件库迁移到了 Tailwind CSS自定义 UI 组件需要同步迁移硬件要求Cornerstone3D 使用 WebGL 渲染 volumeViewport虽保留 CPU 渲染回退需确认目标硬件支持 WebGL并建议 GPU 分级为 tier 1 及以上。核心变更清单v2→v3 的关键差异可归纳为platform/viewerohif/viewer更名为platform/appohif/app。原因是原包名沿用软件工程版本号已到 v4.12.51更名后可改用产品版本号如 v3.4.0。凡从ohif/viewer导入的导出项需改为ohif/app。扩展Extensions按需被 Modes 使用要加载扩展的模块必须编写 Mode 配置文件。应用配置结构变化servers更名为dataSources且配置变为异步。UI 全面改用 Tailwind CSS 重写。cornerstone-core与cornerstone-tools被移除全面转向 Cornerstone3D。新增 OHIF CLI 工具用于创建扩展与 Mode。Redux store 被移除改用 React Context API 的轻量状态管理。新配置结构servers → dataSourcesv3 的配置结构以dataSources数组取代了旧的servers对象数据源比服务器更抽象、能力更强。仓库中 platform/app/public/config/ 目录提供了多种现成配置示例default.js默认配置面向使用 Amazon S3 静态 WADO 数据源的主服务器local_orthanc.js/local_dcm4chee.js面向本地 Orthanc、dcm4chee 服务器netlify.js同 default.js用于 Netlify 部署google.js用于对接 Google Health API。配置迁移需要关注的具体点cornerstoneExtensionConfig属性被移除改用customizationServicemaxConcurrentMetadataRequests被maxNumRequests取代新增属性包括maxNumberOfWebWorkers、omitQuotationForMultipartRequest、showWarningMessageForCrossOrigin、showCPUFallbackMessage、showLoadingIndicator、strictZSpacingForVolumeViewport需确认服务器是否支持supportsWildcard不支持时必须置为false快捷键hotkeys数组中的命令名与选项已更新部分按键被移除。Modes不再需要 fork 整个 viewerModes 是用于加载扩展的配置对象让开发者无需复制fork整个 viewer 代码即可实现定制。官方给出的核心思路是v2 时代围绕注册扩展设计有定制需求就得复制 viewer 代码v3 通过 Modes 这一层抽象可以在不复制代码库的前提下在一个应用中同时承载多个业务场景如一个 segmentation Mode、一个 reading Mode各自拥有独立的布局、工具、挂片协议与初始化逻辑。进入 Mode 时Viewer 会注册其声明的扩展并按需加载模块模块通过字符串命名空间引用。官方示例展示了tmtvPET/CT 读取Mode 的配置骨架const ohif { layout: ohif/extension-default.layoutTemplateModule.viewerLayout, sopClassHandler: ohif/extension-default.sopClassHandlerModule.stack, measurements: ohif/extension-default.panelModule.measure, thumbnailList: ohif/extension-default.panelModule.seriesList, }; const cs3d { viewport: ohif/extension-cornerstone.viewportModule.cornerstone, }; const tmtv { hangingProtocol: ohif/extension-tmtv.hangingProtocolModule.ptCT, petSUV: ohif/extension-tmtv.panelModule.petSUV, ROIThresholdPanel: ohif/extension-tmtv.panelModule.ROIThresholdSeg, };路由是 Mode 配置中最核心的部分路由带 dataSourceName 时为{mode.id}/{dataSourceName}不带时默认使用默认数据源这使一个 Mode 无需重新构建即可连接多个数据源例如从一个 PACS 读取、向另一个写入。官方还给出了功能放 Mode 还是 Extension的决策参考特定用例/任务的功能如默认激活哪个工具、显示哪些面板、用哪种布局放 Mode跨 Mode 复用的功能如自定义面板做成 Extension需要大量定制或修改 viewer 核心行为的复杂逻辑放 Extension新服务也应做成 Extension 以便其他扩展扩展。Routes、生命周期钩子与 DICOM 端点Routesv2 在/viewer/:studyInstanceUID加载研究v3 将 Mode 绑定到具体路由同一应用可有多个 Mode/路由。也可通过customizationService注册自定义路由。DICOM 端点v3 新增要求 DICOM 服务器支持WADO-RS GET studies/{studyInstanceUid}/series用于获取挂片协议所需的系列列表。生命周期钩子v2 只有扩展的preRegistrationv3 增加了扩展和 Mode 上的onModeEnter进入 Mode、路由组件挂载时调用与onModeExit退出 Mode、路由组件卸载时调用。扩展模块的迁移v3 扩展仍通过get{ModuleName}Module导出模块但模块由单个对象变为带 name 属性的对象数组支持导出多个具名子模块。官方示例中getUtilityModule返回了common、core、tools三个子模块通过extensionManager.getModuleEntry(ohif/extension-cornerstone.utilityModule.common)访问。这也是 extensions/cornerstone/getToolbarModule.tsx 等文件中每个模块返回数组模式的原因。ToolbarModulev2 中工具栏按钮直接声明类型与命令v3 中 toolbarModule 被重新定位为定义按钮类型如ohif.radioGroup、ohif.splitButton按钮的实际添加放在 Mode 的onModeEnter钩子中通过toolbarService.addButtons()与toolbarService.createButtonSection()完成onModeEnter: ({ servicesManager, extensionManager, commandsManager }) { const { toolbarService, toolGroupService } servicesManager.services; initToolGroups(extensionManager, toolGroupService, commandsManager); toolbarService.addButtons(toolbarButtons); toolbarService.createButtonSection(primary, [ MeasurementTools, Zoom, WindowLevel, Pan, Capture, Layout, Crosshairs, MoreTools, ]); },PanelModule 与 SopClassHandlerModulev2 的面板返回menuOptions/components/defaultContext结构v3 简化为带name、iconName、label、component的对象数组。SopClassHandlerModule 是变化最小的模块但同样改为返回数组它根据元数据创建 displaySet 列表App 为每个 series 创建一个或多个 displaySet视口再基于 displaySet 渲染图像。displaySet 可带addInstances成员函数来更新实例数据以保留 UID。ViewportModulev3 中视口与 SOP Class UID 系列绑定每个扩展为特定 SOP Class UID 提供自己的视口Mode 配置中通过viewports数组声明要用的视口及其关联的displaySetsToDisplay并在sopClassHandlers中注册每个可处理的 SOP Class Handler。官方示例列出了cornerstone-tracked、dicom-sr、dicom-video、dicom-pdf、dicom-seg、dicom-rt等视口与处理器命名空间——这些扩展均可在仓库 extensions/ 下找到对应实现。元数据存储、构建与 UIMetadatav2 的StudyMetadata/SeriesMetadata/InstanceMetadata类被DICOMMetadataStore取代MetadataProvider仍保留在platform/core/classes中内部用于按 UID 检索实例元数据。构建从全量打包所有扩展转向按 Mode 按需动态加载带来更快的构建、更小的包体与更快的开发热更新。Script tag因 WebWorkers/WASM/WebGL 的引入script tag 用法已废弃替代方案是 iframe postMessage 通信。Redux 移除改用 React context providers 与基于 pub/sub 的服务架构用户信息通过authenticationService获取。3.7 → 3.8工具栏按钮与服务的破坏性变更这次升级有两个主要关注点详见 from-3p7-to-3p8.md。移除 activeTool 概念activeTool及其 getter/setter 被移除活动工具应从 toolGroup 与 viewport 推导。需要删除toolbarService.setDefaultTool()与toolbarService.recordInteraction()相关代码改为用addButtonscreateButtonSection定义按钮与布局。新按钮定义格式与 Evaluator按钮类型toggle/action/tool概念被移除采用简化对象格式顶层 UI 类型用uiType表达。旧格式的type: ohif.action新格式变为uiType: ohif.radioGroup并新增evaluate属性控制按钮状态evaluate.cornerstoneTool仅当工具为左键活动主工具时高亮evaluate.cornerstoneTool.toggle用于 toggle 类工具如参考线、图像叠加。仓库 modes/basic-test-mode/src/toolbarButtons.ts 中的uiType如ohif.toolButton、ohif.toolButtonList、ohif.modalityLoadBadge与evaluate定义即为新格式的落地示例官方还建议参考 modes/longitudinal/src/toolbarButtons.ts 中的 evaluator 用法。工具监听器、面板与路由参数工具可用listeners监听事件触发如ViewportGridService.EVENTS.ACTIVE_VIEWPORT_ID_CHANGED与VIEWPORTS_READY。若自定义视口组件覆盖onElementEnabled必须自行调用viewportGridService.setViewportIsReady(viewportId, true)否则VIEWPORTS_READY不会触发未覆盖时ViewportGrid.tsx传入的默认 handler 会代为调用。toolbarService.init()不再是函数应删除调用。leftPanelDefaultClosed/rightPanelDefaultClosed更名为leftPanelClosed/rightPanelClosed。URL 参数seriesInstanceUID与seriesInstanceUIDs合并为seriesInstanceUIDs。左右面板列表不再注入 LayoutTemplate改由 PanelService 获取自定义布局需参考 extensions/default/src/ViewerLayout/index.tsx。枚举如TimingEnum从Types导出迁移到Enums导出。3.8 → 3.9渲染栈与分割架构升级该版本迁移指南分为 General、Renamings、DataSources、Measurements、ViewportActionCorner、StateSyncService、RTSTRUCT、UI、Refactorings 等章节见 3p8-to-3p9/index.md其中 0-general.md 总结了通用变更。移除 SharedArrayBuffer 依赖与 React 18v3.9 去掉了加载体数据对共享数组缓冲区的依赖不再需要Cross-Origin-Opener-Policy与Cross-Origin-Embedder-Policy安全头降低了 Cornerstone3D 的接入门槛。同时升级到 React 18react/react-dom 版本改为^18.3.1defaultProps改为默认参数({ prop1 default value })SVG 导入由babel-inline-svg迁移到svgrimport { ReactComponent as arrowDown } from ...svg移除了 Polyfill.io 脚本升级 Cornerstone3D 2.0 后不再需要复制 dicom-image-loader 的 wasm 文件对应platform/app/.webpack/webpack.pwa.js中的拷贝逻辑。工具与绑定重构jumpToSlice从cornerstonejs/tools迁移到cornerstonejs/core/utilities。StackScrollMouseWheel→StackScroll 鼠标绑定Enums.MouseBindings.Wheel。VolumeRotateMouseWheel→VolumeRotate 鼠标绑定rotateIncrementDegrees配置保留。其他useAuthorizationCodeFlow配置废弃自动检测response_type codeCustomizationService改用contentFDICOM 上传改用标准 customization 模式启用dicomUploadEnabled时自动注册组件。工具栏按钮 Evaluator 统一新增evaluate.viewport.supported与evaluate.modality.supported废弃evaluate.not.sm、evaluate.action.not.video、evaluate.not3D、evaluate.isUS等旧评估器。替换示例// evaluate.not3D → 新写法 { name: evaluate.viewport.supported, unsupportedViewportTypes: [volume3d] } // evaluate.isUS → 新写法 { name: evaluate.modality.supported, supportedModalities: [US] }重命名与数据源配置默认扩展中的测量面板从measure更名为panelMeasurement完整命名空间ohif/extension-cornerstone.panelModule.panelMeasurement。ui包的addIcon增加了 default 扩展版本utils.addIcon同时向ui与ui-next注册图标。BulkDataURI配置从布尔值变为配置对象useBulkDataURI: false→bulkDataURI: { enabled: true }并支持startsWith/prefixWith自定义 URL 前缀修正逻辑便于处理经过多系统转发的检索 URL。测量数据模型测量displayText从字符串/字符串数组改为结构化对象primary数组放主测量值如长度、面积显示在左侧secondary数组放上下文信息如系列号、实例号显示在右侧。getDisplayText需按新格式返回同时selected属性更名为isSelected与isLocked、isVisible命名风格统一。3.10 → 3.11命令与二次显示集水合Hydration重构本次升级的核心是围绕 SR/SEG/RTSTRUCT 等二次显示集的水合hydrate逻辑集中化见 3p10-to-3p11/index.md 下的 commands.md 与 hydration.md。loadSRMeasurements 被 hydrateSecondaryDisplaySet 取代ohif/extension-cornerstone-dicom-sr中的loadSRMeasurements命令被移除。它原先承担水合 SR 并让视口显示被引用序列两件事现在hydrateStructuredReport只负责解析 SR 并返回数据不再直接操作视口新的hydrateSecondaryDisplaySet位于ohif/extension-cornerstone统一负责水合二次显示集并更新视口内部流程为调用hydrateStructuredReport解析 SR → 根据返回的SeriesInstanceUIDs找到对应图像 displaySet → 更新指定viewportId显示主被引用序列。迁移动作是把commandsManager.runCommand(loadSRMeasurements, { displaySetInstanceUID })替换为const { displaySetService, viewportGridService } servicesManager.services; const srDisplaySet displaySetService.getDisplaySetByUID(srDisplaySetInstanceUID); const viewportId viewportGridService.getActiveViewportId(); if (srDisplaySet viewportId) { commandsManager.runCommand(hydrateSecondaryDisplaySet, { displaySet: srDisplaySet, viewportId: viewportId, }); }同时updateStoredPositionPresentation的参数由displaySetInstanceUID改为displaySetInstanceUIDs。UI 层面Load SR按钮被重构使用 measurement-tracking 扩展时由TrackedMeasurementsContext触发或由新的ModalityLoadBadge组件在包含 SR/SEG/RTSTRUCT 的视口中提供 LOAD 动作。统一水合对话框promptHydrateSEG与promptHydrateRT函数改用ohif/extension-cornerstone的通用utils.promptHydrationDialog。以 RT 为例extensions/cornerstone-dicom-rt/src/utils/promptHydrateRT.ts 中旧的 promise/对话框逻辑被替换为对promptHydrationDialog的调用传入displaySet、preHydrateCallbacks、hydrateCallback、type: RTSTRUCT而 extensions/cornerstone-dicom-rt/src/viewports/OHIFCornerstoneRTViewport.tsx 中传给它的hydrateRTDisplaySet回调则改为运行hydrateSecondaryDisplaySet命令。3.11 → 3.12beta与 3.9 → 3.10beta3.11 → 3.12 beta官方指南3p11-to-3p12/index.md说明该版本仍处于 beta 阶段迁移内容围绕 3.11 到 3.12 beta 的差异展开。3.9 → 3.10 beta指南3p9-to-3p10/index.md按 General、CustomizationService、UI 三个方向组织覆盖命令处理、快捷键更新、路由 baseName 变更routerBaseName以及 UI 组件Colors/Icons/Button/Input/Tooltip/Select/Switch/Toolbar/SegmentationTable/Tours/DialogService/ModalService的系统性迁移与测试策略。迁移自检清单综合各版本官方指南可将迁移要点收敛为以下可执行清单包名ohif/viewer→ohif/app更新所有 import。配置servers→dataSources数组核对supportsWildcard、maxNumRequests、bulkDataURI等新属性。架构以 Mode Extension 组织功能路由按{mode.id}注册利用onModeEnter/onModeExit钩子。渲染栈移除cornerstone-core、cornerstone-tools、react-cornerstone-viewport、vtk 扩展依赖工具数据迁移到世界坐标系。扩展模块模块改为带name的对象数组Toolbar 按钮用uiTypeevaluate面板用 PanelService 获取。React 18默认参数替代defaultPropsSVG 用 svgr 导入清理 SharedArrayBuffer 相关安全头。水合逻辑改用hydrateSecondaryDisplaySet命令与promptHydrationDialog工具。状态与元数据DICOMMetadataStore取代旧 metadata 类Redux 迁移到 React Context 服务。参考资料与源码佐证迁移指南总览migration-guide/index.md各版本指南目录 migration-guide/ 下的from-v2.md、from-3p7-to-3p8.md、3p8-to-3p9/、3p9-to-3p10/、3p10-to-3p11/、3p11-to-3p12/工具栏按钮新格式示例modes/basic-test-mode/src/toolbarButtons.ts、modes/longitudinal/src/toolbarButtons.ts默认布局与面板获取方式extensions/default/src/ViewerLayout/index.tsx水合逻辑实现extensions/cornerstone-dicom-rt/src/utils/promptHydrateRT.ts、extensions/cornerstone-dicom-rt/src/viewports/OHIFCornerstoneRTViewport.tsx配置文件示例platform/app/public/config/【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考