OHIF Viewer 工具栏实战指南：3 个高频操作、4 类工具与一次点击的源码路径
【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers
打开一台胸部 CT，把窗宽窗位拖到能看清肺纹理，量出最大结节的径线，再导出一张截图存档——这条影像工作流的每一步都发生在 OHIF Viewer 工具栏上。它是查看器顶部唯一常驻的交互横栏：最左端是返回检查列表的入口，中段排满当前模式激活的全部工具，右端挂着偏好设置与可换成机构品牌的 Logo 位。下面按"先会用、再看懂"的顺序拆解它。
心智模型：按钮是一段数据，不是一堆控件
理解这条横栏，先记住一句话：每个按钮本质是数据。一个按钮由三要素构成：
id与uiType（如ohif.toolButton、ohif.layoutSelector）：声明"我是什么、长什么样"；commands：点击后触发什么动作；evaluate：什么条件下按钮可用。
这些定义不在界面组件里写死，而是注册进 ToolbarService。服务在 TOOLBAR_SECTIONS（L15-L47） 中预置了分区：primary（主工具栏）、secondary，以及viewportActionMenu下 topLeft、topRight、bottomLeft、bottomRight 等八个视口角标位。React 组件只按分区名取数再渲染——分区一变，界面自动跟着变。
三分钟上手：3 个最高频操作
如何激活一个测量工具
主工具栏最前面的按钮组就是测量工具区。点一下 Length，按钮高亮，即成为当前激活工具；点按钮旁的下拉箭头（caret）可展开完整清单，切换到其他工具。
如何拖拽调整窗宽窗位
窗宽窗位≈控制图像亮度与对比度的两个旋钮。先选 Window/Level 按钮，再在视口上按住鼠标拖一段，明暗与对比实时变化。再点下拉箭头，能看到常见成像场景的预定义 W/L 设置，一键套用标准化显示方案。
如何截图并下载 📸
点相机图标（Capture），弹出下载配置框，可设置文件名、图像宽高、文件格式（png、jpg 等），确认后把当前视口的高质量截图存到本地。
工具分类详解
测量类：从 Length 到 Calibration
Basic Viewer 默认内置的测量能力如下（按钮定义集中在 L470-L558）：
| 工具 | 按钮 id | 你拿到什么 |
|---|---|---|
| 椭圆 | EllipticalROI | 区域面积与平均 CT 值（mm²、HU） |
| 矩形 | RectangleROI | 区域面积与 CT 值（mm²、HU） |
| 长度 | Length | 两点间线性距离（mm） |
| 双向径线 | Bidirectional | 最长径 LD 及其垂直径 LPD（mm） |
| 注释 | ArrowAnnotate | 带自由文本的定性标记 |
| 圆形 / 平面自由 / 样条 / 活线 | CircleROI等 | 各类轮廓区域测量 |
| 校准 | CalibrationLine | 修正像素间距 |
默认排布由 MeasurementTools 分区（L752-L762） 决定：Length、Bidirectional、ArrowAnnotate、EllipticalROI、RectangleROI、CircleROI、PlanarFreehandROI、SplineROI、LivewireContour 依次排列。
Calibration 工具校准什么属性？它修正的是 DICOM 的 Pixel Spacing——相邻像素中心之间的物理距离，由"行间距 / 列间距"两个数值指定（单位 mm）。长度类工具把像素换算成物理距离全靠它；图像元数据缺失或录错时，可手动校准。
显示调整类：窗宽窗位、反色与放大镜
Window/Level 相关按钮不止一个，源码按位置分了家：
WindowLevel：主工具栏主按钮（L570-L584）；windowLevelMenu：挂在视口左下角的 W/L 下拉菜单（定义于 L130，装配进 bottomLeft 分区，见 L750）；windowLevelMenuEmbedded（L117）与手动 VOI 控制的voiManualControlMenu（L142）：内嵌在视口底部中间的 AdvancedRenderingControls 区（分区定义 L736-L742，同区还有 Colorbar、opacity、threshold 菜单）。
反色是 More Tools 里的invert（命令invertViewport，L308）；放大镜Magnify点击图像放大局部细节（L375）。
导航类：Pan / Zoom / 序列滚动 / Cine
- Zoom：选中后在图像上点按拖拽即改缩放级别，放大倍数实时显示在视口（L596-L606）；
- Pan：同样点按拖拽，移动图像位置（L585-L595）；
- Stack Scroll：堆栈滚动工具（L297）；配合
ImageSliceSync（L231，命令toggleSynchronizer，type 为imageSlice）可让所有含图像的视口位置同步滚动； - Cine：在当前选中视口切换电影播放，点播放器上的
x或再次点按钮即可关闭（L336，命令toggleCine；evaluate.cine排除 volume3d 视口）。
导出与布局类：Capture 与 Layout Selector
Capture 按钮（L621-L636）的commands指向showDownloadViewportModal，弹出前述配置框；evaluate.viewport.supported把video与wholeSlide列入排除——视频与全切片（WSI）视口点不了这个相机图标。
Layout Selector 用ohif.layoutSelector类型（L637-L645），默认给出行 3 × 列 4 的网格范围，1x1、2x2、3x3 等分割方式在范围内任选。
More Tools 里的视图操作
| 按钮 id | 用户操作 | 触发命令 |
|---|---|---|
Reset | 重置位置、缩放、窗宽窗位等全部图像操作 | resetViewport |
rotate-right | 顺时针旋转 90° | rotateViewportCW |
flipHorizontal | 水平翻转 | flipViewportHorizontal |
ImageSliceSync | 开/关堆栈视口位置同步 | toggleSynchronizer（type:imageSlice） |
invert | 反转灰度刻度 | invertViewport |
Cine | 开/关电影播放 | toggleCine |
Probe/Angle/CobbAngle/Magnify | 激活对应工具 | setToolActiveToolbar |
MoreTools 分区的完整成员见 L764-L784。从该菜单选中的工具会保持激活，直到你在菜单或主工具栏点别的工具将其替换。
一次点击的旅程
以"点击 Length"为例，跟一遍内部链路：
- 按钮数据被按下：Length 的
commands指向 setToolActiveToolbar（L19-L24）； - 命令广播：该命令向
default、mpr、SRToolGroup、volume3d四个工具组同时发出激活事件，各视口的 cornerstone 工具随之切换； - 状态回算：各按钮的
evaluate（如evaluate.cornerstoneTool、evaluate.viewportProperties.toggle）随选中视口与数据状态重新求值，决定启用或禁用——modalityLoadBadge、trackingStatus这类徽标只在相关数据存在时出现在视口右上角（topRight 分区，L744-L748）； - 分区重渲染：服务发出 TOOLBAR_MODIFIED 事件（ToolbarService.ts L7-L10），Toolbar.tsx（L31-L42） 经
useToolbarhook 取回当前分区按钮列表，注入isOpen、isLocked、onOpen、onClose、onToggleLock等属性后渲染，buttonSection默认primary；ToolboxWrapper、ToolButtonWrapper、ToolButtonListWrapper、ToolRowWrapper（见 Toolbar 目录）负责分组、展开/收起与排布。
数据的源头，是扩展以"能力包"形式注册的两组定制项：cornerstone.toolbarButtons（全部按钮定义）与cornerstone.toolbarSections（分区→按钮 id 映射），见 L799-L802。
定制与扩展
- 调排布：改
toolbarSections里各分区的按钮 id 顺序即可重排工具栏（primary 分区默认成员见 L720-L730）。 - 换装配：Basic 模式在 index.tsx 中以
$reference指向这两个能力包（toolbarSections 在 L329，toolbarButtons 在 L370）；进入模式时 modeCustomization.ts 的 registerModeToolbar（L31-L38） 调toolbarService.register()注册按钮，再逐分区updateSection()装配。 - 不重建模式加按钮：第三方扩展或
?customization=模块走mode阶段，按mode.basic.toolbarButtons这类键用$push追加引用即可（示例见 index.tsx L325-L328 的注释）。
速查表：工具 → 操作 → 命令
| 工具 | 操作 | 对应命令 |
|---|---|---|
| Length / Bidirectional 等测量 | 点按钮激活，caret 展开清单 | setToolActiveToolbar |
| Window/Level | 选中后视口内拖拽；caret 选预设 | setToolActiveToolbar |
| Pan / Zoom | 视口内点按拖拽 | setToolActiveToolbar |
| Capture | 相机图标→配置框→下载 | showDownloadViewportModal |
| Layout Selector | 选择网格行列 | ohif.layoutSelector（rows 3 / columns 4） |
| Reset | 一键重置视图 | resetViewport |
| rotate-right / flipHorizontal / invert | 单击生效 | rotateViewportCW/flipViewportHorizontal/invertViewport |
| ImageSliceSync | 开/关堆栈位置同步 | toggleSynchronizer（type:imageSlice） |
| Cine | 开/关电影播放 | toggleCine |
| StackScroll / Probe / Angle / Magnify | 激活工具 | setToolActiveToolbar |
FAQ
为什么 video 与 wholeSlide 视口点不了相机图标？Capture 的evaluate.viewport.supported把这两类视口列入unsupportedViewportTypes，选中它们时按钮自动禁用（L628-L634）。
Calibration 校准的到底是什么属性？Pixel Spacing：相邻像素中心的物理距离，行间距/列间距两个数值（mm），是长度测量的物理换算基础。
为什么同一个按钮有时亮、有时灰？evaluate随选中视口重算：flipHorizontal排除 video 与 volume3d 视口，rotate-right排除 video，Cine 排除 volume3d。
窗宽窗位预设从哪里来？W/L 下拉列出的是常见成像场景的预定义设置，从windowLevelMenu（视口左下角）与windowLevelMenuEmbedded（底部中间内嵌区）两个入口都能进。
More Tools 选中的工具会一直保持吗？会，直到你在 More Tools 或主工具栏点其他工具将其替换。
记住这三件事
- 按钮是数据：改
toolbarSections与按钮定义，不动组件就能重排、增删工具栏； - commands 管动作，evaluate 管可用性：前者决定"点了干什么"，后者决定"何时能点"，两层分开让同一份按钮定义通吃 2D、MPR、3D、视频、WSI 多种视口；
- 一切经 ToolbarService 流转：注册、分区、事件、渲染都挂在服务上，扩展与
?customization=的定制入口也在这里汇合。
【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
