企业官网建设流程全解析

OHIF Viewer 界面完全指南：Basic Viewer 模式的四大组件与测量追踪工作流

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

本文基于 OHIF Viewer 3.11 用户文档，系统拆解Basic Viewer（longitudinal）模式的界面构成：左侧研究面板（Study Panel）、视口（Viewport）、右侧测量面板（Measurement Panel）与工具栏（Toolbar）四大组件，并结合本仓库的源码实现（ViewerLayout、mode 定义、toolbarButtons、measurement-tracking 扩展）与配套子文档，说明每个组件的功能、交互方式与测量追踪（Measurement Tracking）的完整工作流。读完本文，你将能够熟练操作 Basic Viewer 完成图像浏览、布局切换、标注测量、追踪管理、DICOM SR 导入导出与报告生成等日常阅片任务。

一、模式驱动的界面：什么是 Viewer

在 OHIF v3 中，当你打开一个mode（模式）时，该模式所定义的视图结构就会被渲染出来，包括视口（viewport）、工具栏（toolbar）以及左右面板（panels）。需要特别强调的是：每个 mode 拥有不同的 UI，服务于不同的用途。例如Basic Viewer、Segmentation、TMTV、Longitudinal等模式，其布局、工具和面板各不相同。

本文聚焦于带测量追踪功能的Basic Viewer模式（即 longitudinal 变体），其完整界面如下图所示：

从实现角度看，Viewer 的整体布局由@ohif/extension-default扩展提供的ViewerLayout组件负责渲染。该组件接收来自 mode 的leftPanels、rightPanels、viewports、leftPanelClosed、rightPanelClosed等配置，将整个界面组织为一个可伸缩的三段式布局（左侧面板｜视口网格｜右侧面板），核心逻辑见 extensions/default/src/ViewerLayout/index.tsx。布局通过panelService.getPanels(side)动态判断左右两侧是否有面板需要渲染（见 ViewerLayout/index.tsx），并通过ResizablePanelGroup支持拖拽调整面板宽度。

将 Viewer 拆解开来，可以归纳为以下四大主组件：

• 左侧面板（研究面板 Study Panel）：显示带系列详情（series details）的缩略图列表
• 视口（Viewport）：渲染图像并显示标注（annotations）
• 右侧面板（测量面板 Measurements）：显示标注详情
• 工具栏（Toolbar）：显示工具与 Logo

下文将逐一详解每个组件及其子元素。

二、左侧面板：Study Panel（研究面板）

在Basic Viewer模式下，左侧面板展示当前患者相关的所有研究（studies），共分三类：

Study Panel 还会展示每个系列（series）的测量追踪状态：每个系列左侧的虚线圆圈表示该系列是否处于测量追踪状态（tracked for measurement）。详细说明见 user-guide/viewer/study-panel.md。

交互要点：

• 点击 Study Panel 中的研究信息即可展开或折叠该研究；
• 如果某个研究内有系列处于追踪状态，即使该研究处于折叠状态，测量面板（Measurement Panel）仍会显示相关信息；
• 后续文档还规划了针对 SR（Structured Report，结构化报告）功能的说明。

在源码层面，纵向（longitudinal）模式将左侧面板指定为测量追踪扩展提供的缩略图列表：

leftPanels: [tracked.thumbnailList], // '@ohif/extension-measurement-tracking.panelModule.seriesList'

见 modes/longitudinal/src/index.ts。而基础（basic）模式则使用默认扩展的seriesList面板（'@ohif/extension-default.panelModule.seriesList'），见 modes/basic/src/index.tsx。两个模式均开启leftPanelResizable: true，允许用户拖拽调整面板宽度。

三、视口：图像渲染与交互操作

图像的渲染发生在Viewport（视口）中，视口包含用于绘制序列的 canvas（或一组 canvas）。

默认图像操作

默认情况下，你可以在视口中进行以下三类基本操作：

这些交互由 Cornerstone 渲染引擎与工具（cornerstoneTools）提供，相关视口注册见 modes/basic/src/index.tsx 中的cornerstone.viewport模块。

更换显示的系列

要更换视口中显示的系列，可以从左侧面板拖拽目标系列的缩略图，将其拖放到视口上即可完成替换。

更换布局（Layout）

点击工具栏上的布局图标，会弹出布局选择器 UI。更改布局后，可以为每个新建的视口分别选择要显示的系列（同样通过拖拽缩略图到对应视口的方式）。

值得注意的是：当布局从 1×1 切换为多视口后，每个视口会被标记一个字母，该字母与其在研究列表中的系列区域一一对应，方便你快速识别各视口正在显示哪个系列：

布局切换通过setViewportGridLayout命令实现（见 modes/basic-dev-mode/src/toolbarButtons.ts），布局选择器最多支持 3 行 × 4 列。更详细的视口交互说明见 user-guide/viewer/viewport.md。

四、右侧面板：Measurement Panel（测量面板）

在Basic Viewer模式下，右侧面板即Measurement Panel（测量面板）。点击 "Measurements" 左侧的箭头可以展开或隐藏该面板。

发起测量追踪

选择任一测量工具并在图像上标记后，会弹出对话框询问是否为该系列开启测量追踪：

三种选择对应的行为：

实现上，右侧面板由'@ohif/extension-measurement-tracking.panelModule.trackedMeasurements'（追踪测量面板）与'@ohif/extension-cornerstone.panelModule.panelSegmentation'（分割面板）共同组成，见 modes/longitudinal/src/index.ts 与 modes/longitudinal/src/index.ts。测量面板本身是PanelMeasurement的包装组件，通过useMeasurements钩子获取经过筛选的测量数据后交由StudyMeasurements子组件渲染，见 extensions/cornerstone/src/panels/PanelMeasurement.tsx。

标注（Labeling）测量

• 重命名：将鼠标悬停在某条测量上，点击编辑图标即可修改测量名称；
• 快捷标注 / 重新标注：在视口中右键点击该测量，同样可以进行标注操作。

删除测量

删除一条测量有两种方式：

1. 在视口中将该测量拖拽到图像外部；
2. 在视口中右键点击该测量并选择 "Delete"。

跳转到某条测量

• 视口顶部的测量导航按钮可以切换上一条 / 下一条测量：
• 如果包含某条测量的系列当前正显示在视口中，直接在测量面板中点击该测量即可跳转并定位显示。

导出测量与生成报告

点击Export按钮，会下载一份包含全部已绘制测量的CSV 文件到本地：

如果你的 DICOM 服务器已配置为允许 viewer 写入实例，还可以点击Create Report：viewer 会基于测量生成一份DICOM Structured Report（SR）并推送回服务器（例如本地运行 DCM4CHEE 的场景）。完整的测量绘制与导出流程说明见 user-guide/viewer/measurement-panel.md。

五、工具栏：工具、Logo 与偏好设置

工具栏（Toolbar）的四个主要组成部分：

1. 返回研究列表的导航按钮（返回 Study List）
2. Logo 与白标（white labelling）
3. 工具（Tools）
4. 偏好设置（Preferences）

工具栏的 UI 骨架由ViewerHeader渲染，其右侧项（默认为撤销/重做、患者信息，以及 About / Preferences 菜单入口）可通过ohif.headerRightSide定制化项进行重排，见 extensions/default/src/ViewerLayout/ViewerHeader.tsx。返回按钮会根据当前数据源名称构造查询参数并跳回/路由（即 Study List），见 ViewerHeader.tsx。

测量工具（Measurement Tools）

Basic Viewer 默认提供以下测量工具：

从工具栏选择某个测量工具后，它会成为当前激活工具（active tool）；点击测量工具组旁的下拉箭头（caret）可以展开并选择其他工具。这些按钮在源码中以数据驱动方式声明，例如 Length、Bidirectional、Ellipse、Circle 等均通过setToolActiveToolbar（执行setToolActive命令并指定 toolGroupIds）来激活对应toolName，完整定义见 modes/basic-dev-mode/src/toolbarButtons.ts。

Window/Level（窗宽窗位）

Window/Level工具用于调整渲染图像的窗宽（window width）与窗位（window level）：

1. 点击该工具进入自由调整模式；
2. 在视口上点击并拖拽即可自由调整窗宽窗位。

点击工具旁的下拉箭头，还可以从预定义 W/L 预设中选择常见影像场景的显示参数：

Pan 与 Zoom

• Zoom：选中后，在图像上点击并拖拽即可调整缩放，放大倍数会显示在视口中；
• Pan：选中后，在图像上点击并拖拽即可调整图像位置。

Image Capture（图像捕获）

点击相机图标可以下载一张高质量图像截图，支持常见图片格式（png、jpg）：

在弹出的模态框中，可以配置文件名、图像宽高、文件类型后再下载到本地：

该功能由showDownloadViewportModal命令触发，并会排除 video 与 wholeSlide 类型的视口（见 modes/basic-dev-mode/src/toolbarButtons.ts）。

Layout Selector（布局选择器）

详见上文"更换布局"一节。

More Tools 菜单（更多工具）

More Tools菜单中提供的工具如下：

当从More Tools菜单中选择某个工具后，它会成为激活工具，直到被主工具栏或其他 More Tools 菜单项替换。上述 Reset、RotateRight、FlipHorizontal、Invert、StackScroll 等按钮的命令定义（resetViewport、rotateViewportCW、flipViewportHorizontal、invertViewport、StackScroll工具激活）均可在 modes/basic-dev-mode/src/toolbarButtons.ts 中查到。完整的工具说明见 user-guide/viewer/toolbar.md。

六、测量追踪工作流：从标注到 DICOM SR

OHIF v3 的Basic Viewer实现了完整的Measurement Tracking（测量追踪）工作流，其能力包括：

• 绘制标注并显示在测量面板中；
• 基于追踪测量生成报告并导出为DICOM SR；
• 加载已导出的 DICOM SR，将测量在 viewer 中重新水合（re-hydrate）。

状态图标

每个视口左侧的图标标识该系列当前包含的内容类型：

• tracked measurement（已追踪测量）
• untracked measurement（未追踪测量）
• Structured Report（结构化报告）
• Locked（不可编辑）Structured Report（锁定的结构化报告）

追踪与未追踪的测量

整个追踪决策流程如下：

简单总结：创建标注时会弹出是否开始追踪的提示——

• 开始追踪：标注样式变为实线，标注详情显示在测量面板中；
• 拒绝追踪：测量被视为"临时"状态，标注保持虚线样式，不显示在右侧面板中，且无法导出。

两种状态的系列图标对比如下：

这一"实线 vs 虚线"的样式差异在源码中有明确的对应实现：TrackedCornerstoneViewport根据系列是否在trackedSeries中，动态切换工具标注样式——被追踪时清除全局虚线并将 ReferenceLines 设为虚线；未追踪时全局lineDash设为'4,4'（虚线），见 extensions/measurement-tracking/src/viewports/TrackedCornerstoneViewport.tsx。该组件同时监听cornerstoneViewportService的VIEWPORT_DATA_CHANGED事件与VOLUME_VIEWPORT_NEW_VOLUME事件来同步追踪状态（见 TrackedCornerstoneViewport.tsx）。

读写 DICOM SR

OHIF v3 提供对DICOM Structured Report（SR）的完整读写与映射支持，可将 SR 映射为可交互的 Cornerstone 工具。当你将已导出的 DICOM SR 加载进 viewer 时，会弹出是否追踪该系列测量的提示：

• 点击Yes：DICOM SR 中的测量被重新水合到 viewer 中，该系列成为追踪系列；
• 点击No：稍后若改变主意，可以随时点击SR 按钮再次弹出相同提示，选择开始追踪：

将测量保存为 SR 以及将 SR 加载回 viewer 的完整流程如下图所示：

SR 的读写能力由@ohif/extension-cornerstone-dicom-sr扩展提供，其 SOP 类处理器（dicom-sr/dicom-sr-3d）与专用视口（dicom-sr）在 basic 模式中被注册为dicomsr模块（见 modes/basic/src/index.tsx）。

将 DICOM SR 加载到已追踪系列

如果某个系列已经是追踪系列，再尝试加载 DICOM SR 测量时，会显示以下锁定图标：

其含义是：你可以查看DICOM SR 中的测量、操作图像、绘制"临时"测量，但无法编辑DICOM SR 中的测量本身。完整的追踪工作流说明见 user-guide/viewer/measurement-tracking.md。

七、快捷键（Hotkeys）

点击 viewer 右上角的Preferences（偏好设置）齿轮图标即可打开快捷键分配面板，查看默认的按键绑定：

快捷键可以重新绑定为自定义按键组合，该设置在浏览器会话期间持续生效。相关说明见 user-guide/viewer/hotkeys.md。

八、MPR 与更多模式

除 Basic Viewer 外，Basic Viewer家族还支持Multiplanar Reconstruction（MPR，多平面重建）功能，包含 Crosshairs（十字定位线）与 MPR Slab Oblique 等交互，相关说明见 user-guide/viewer/mpr.md。不同的 mode（如 basic、longitudinal、segmentation、tmtv 等）在 modes 目录下各自定义了自己的布局、工具组与面板组合，其中 longitudinal 模式通过继承 basic 模式并替换为测量追踪专用面板/视口来获得完整追踪能力（见 modes/longitudinal/src/index.ts）。

总结

• 布局：Basic Viewer 由左侧研究面板、中央视口网格、右侧测量面板与顶部工具栏四大组件构成，整体由ViewerLayout数据驱动渲染，左右面板可拖拽调整、可折叠；
• 浏览交互：视口默认支持左键调窗、右键缩放、中键平移；布局切换后各视口以字母与系列一一对应；
• 测量与追踪：标注后可选择开启系列追踪，追踪测量显示在右侧面板并可导出 CSV / 生成 DICOM SR；未追踪的测量为临时状态，呈虚线且不可导出；
• SR 闭环：已导出的 DICOM SR 可重新加载并水合为可交互测量，加载到已追踪系列时进入锁定（只读）状态；
• 扩展性：所有工具、面板、布局均以模块化配置声明，可通过customizations机制替换，为二次开发提供了清晰的切入点。

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