矩形区域灰度测量的实现方案.md 11 KB
📋 需求整理
矩形区域灰度测量功能详述
功能描述：用户可以在医学图像上绘制矩形选区，系统自动计算该选区内的平均灰度值并显示测量结果。
需求要点：
- 支持绘制矩形区域选择器
- 计算矩形区域内所有像素的灰度平均值
- 显示测量结果（数值和单位）
- 支持测量历史记录和清除功能
- 与现有测量工具集成
🏗️ 参与者分析
粗粒度参与者
| 参与者 | 职责描述 | 交互方式 |
|---|---|---|
RectangleGrayscaleMeasurementTool |
矩形区域灰度测量工具主类 | 实现测量逻辑 |
MeasurementToolManager |
测量工具管理器 | 统一管理所有测量工具 |
StackImageViewer |
图片查看器组件 | UI界面和工具注册 |
ViewerContainer |
查看器容器 | 事件分发和状态管理 |
MeasurementPanel |
测量控制面板 | UI控制器 |
中等粒度参与者
RectangleGrayscaleMeasurementTool类分析：
- 数据结构：继承自BaseTool，提供几何计算和灰度统计
- 方法层级：创建默认标注 → 事件处理 → 数据计算 → 结果展示
- 依赖项：Cornerstone3D Annotations系统
MeasurementToolManager方法分析：
- 状态控制：工具激活/停用/切换
- 批量操作：多视口管理
- 数据清理：标注移除
细粒度参与者
核心方法链：
MeasurementPanel.onClick() →
ViewerContainer.handleMeasurementAction() →
MeasurementToolManager.activateRectangleGrayscaleMeasurementTool() →
StackImageViewer.registerTools() →
RectangleGrayscaleMeasurementTool.constructor()
数据流向：
mouseDown → geometry creation →
AnnotationManager.addAnnotation() →
cachedStats calculation →
render statistics overlay
🔄 交互流程
泳道图：矩形区域灰度测量过程
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Measurement │ │ ViewerContainer │ │ MeasurementTool │
│ Panel │ │ │ │ Manager │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ 用户点击"矩形区域灰度" │ │
│───────────────────────▶ │
│ │ │
│ │ dispatch测量action │
│ │──────────────────────▶
│ │ │
│ │ activateTool() │
│ │──────────────────────▶
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Cornerstone3D │ │ StackImageViewer │ │ RectangleTool │
│ Tools │ │ │ │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │ │
│ │ │ tool registered
│ │ │◀──────────────────────
│ │ │
│ │ mouseDown │
│ ◀────────────────────── │
│ │
│ │ │ create default
│ │ │ annotation
│ │ ◀──────────────────────│
│ │ │
│ calculate │
◀─────────────────────── │
│ │ │
│ render stats │
◀─────────────────────── │
🌊 数据流分析
1. 初始化数据流
测量面板初始化 → MEASUREMENT_TOOL_CONFIGS映射 →
CurrsorResetListener注册 → Tool注册
2. 用户操作数据流
用户点击 → Redux Action分发 → measurementAction更新 →
useEffect触发 → MEASUREMENT_TOOL_CONFIGS查找 →
配置对象提取 → activateMeasurementTool调用 →
MeasurementToolManager方法执行 → StackImageViewer函数调用
3. 工具启用数据流
ToolGroup增加工具 → 工具设置为active模式 →
_modify激活 → AnnotationManager添加默认标注 →
EnabledElement获取 → _updateCachedStats更新统计数据 → 界面更新
4. 统计计算数据流
Canvas获取 → imageData提取 →
pixelData数组处理 → 统计计算(Max/Min/Avg/StdDev) →
cachedStats更新 → 界面更新
🏢 数据结构
矩形区域灰度测量数据结构
RectangleAnnotationData
interface RectangleAnnotationData {
// 几何数据
handles: {
points: Point3[]; // 4个顶点坐标
activeHandleIndex: number;
};
// 统计数据
cachedStats: {
modality: string; // 成像模态
area: number; // 面积(单位:mm²)
mean: number; // 平均灰度值 (HU)
stdDev: number; // 标准差
min: number; // 最小值
max: number; // 最大值
units: string; // 单位
};
}
MeasurementToolConfig
interface MeasurementToolConfig {
toolName: string; // 工具类名
activateFunction: Function; // 激活函数
logPrefix: string; // 日志前缀
}
CalculationParameters
interface CalculationParameters {
imageData: cornerstone.Types.IImageData; // 图像数据
rectanglePoints: Point3[]; // 矩形顶点
pixelSpacing: number[]; // 像素间距 [x,y]
modality: string; // 成像模态
}
🎯 执行流程
矩形区域灰度测量完整执行流程
起点: 用户在测量面板点击"矩形区域灰度"按钮
主要步骤：
- 事件触发 → MeasurementPanel 按钮点击
- Action分发 → Redux更新measurementAction状态
- 处理响应 → ViewerContainer useEffect监听状态变化
- 工具激活 → MeasurementToolManager激活对应工具
- 交互开始 → Cornerstone Tools处理鼠标事件
- 标注创建 → Annotation Manager创建新的观察标注
- 统计计算 → 计算选区内部素灰度统计信息
- 结果显示 → 渲染测量结果覆盖层
详细子流程
激活工具子流程
选择viewport → 检查toolGroup →
添加RectangleGrayscaleMeasurementTool → 设置工具为active模式 →
激活修改功能 → 创建默认标注 → 更新缓存统计 → 触发渲染
数据计算子流程
获取图像数据 → 提取pixelData →
遍历矩形区域 → 累加像素值 →
计算Max/Min/Sum/Count → 计算Average和StdDev → 格式化结果
🧪 测试方案
功能测试场景
| 测试场景 | 测试步骤 | 预期结果 |
|---|---|---|
| 正常使用场景 | 1. 点击"矩形区域灰度"按钮 2. 在图像上绘制矩形 3. 完成绘制 |
显示平均灰度值和统计信息 |
| CT图像测试 | 使用CT图像测试 | 显示HU值为负数，单位为HU |
| 多选区测试 | 在同一图像创建多个矩形 | 每个矩形独立显示统计信息 |
| 工具切换测试 | 使用后切换到其他测量工具 | 矩形标注保留，可以重新编辑 |
| 清除功能测试 | 使用"清除测量"功能 | 所有矩形标注消失 |
边界情况测试
| 边界情况 | 测试方法 | 预期结果 |
|---|---|---|
| 空选区 | 绘制大小为0的矩形 | 显示警告或忽略操作 |
| 图像边界 | 绘制超出图像边界的矩形 | 自动裁剪到图像边界 |
| 小选区 | 选择1x1像素的矩形 | 显示单像素灰度值 |
| 大选区 | 选择覆盖整个图像的矩形 | 显示全局平均灰度值 |
人工测试操作步骤
启动应用程序
npm run h5:browser # 或其他启动命令- 导航到测量面板
- 在主界面找到测量面板入口
点击"图像测量"打开测量面板
激活矩形区域灰度工具
在测量面板中找到"矩形区域灰度"按钮
点击按钮激活测量工具
执行测量
将鼠标移到图像上，鼠标指针变为测量工具样式
按下鼠标左键，开始绘制矩形
拖拽鼠标定义矩形区域
松开鼠标左键完成绘制
查看测量结果
观察矩形选区显示统计信息
检查是否显示平均灰度值、面积等
测试工具切换
激活其他测量工具，确认矩形标注保留
重新选择矩形工具，点击标注进行编辑
测试清除功能
在测量面板点击"清除测量"
确认所有标注被移除
🐛 潜在问题检查
边界问题
- 内存管理: 大图像大量标注可能造成内存压力
- 性能问题: 实时计算大面积矩形的统计值可能较慢
- 多帧图像: 需要考虑不同帧间的标注同步
异常处理
- 图像数据加载失败: 应有错误提示而不是崩溃
- 网络请求超时: 测量结果更新延迟的友好处理
- 不支持的图像格式: 格式不支持时的降级提示
兼容性问题
- 不同DICOM模态: CT和普通X-ray的灰度值处理差异
🔧 实现总结
核心文件修改
- 新建文件:
src/components/measures/RectangleGrayscaleMeasurementTool.ts- 矩形灰度测量工具类修改文件:
src/pages/view/components/viewers/stack.image.viewer.tsx- 添加工具注册和导出函数src/utils/measurementToolManager.ts- 添加工具管理方法src/pages/view/components/ViewerContainer.tsx- 添加激活函数导入
解决的bug
- static方法中的this问题: 将所有
this.getToolGroup(viewportId)替换为MeasurementToolManager.getToolGroup(viewportId)
技术实现要点
- Cornerstone3D集成: 基于BaseTool实现自定义测量工具
- 统计计算: 实现像素遍历和统计值计算
- 状态管理: 通过Redux集成到现有测量系统
- UI集成: 无缝集成到测量面板和查看器
扩展性考虑
- 配置驱动: 通过MEASUREMENT_TOOL_CONFIGS支持新工具快速接入
- 模态支持: 基础架构支持不同DICOM模态的灰度处理
- 多视口: 完整的多视口支持和批量操作