# 📋 需求整理

## 矩形区域灰度测量功能详述

**功能描述**：用户可以在医学图像上绘制矩形选区，系统自动计算该选区内的平均灰度值并显示测量结果。

**需求要点**：
- 支持绘制矩形区域选择器
- 计算矩形区域内所有像素的灰度平均值
- 显示测量结果（数值和单位）
- 支持测量历史记录和清除功能
- 与现有测量工具集成

## 🏗️ 参与者分析

### 粗粒度参与者

| 参与者 | 职责描述 | 交互方式 |
|--------|----------|----------|
| `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
```typescript
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
```typescript
interface MeasurementToolConfig {
  toolName: string;                    // 工具类名
  activateFunction: Function;          // 激活函数
  logPrefix: string;                   // 日志前缀
}
```

#### CalculationParameters
```typescript
interface CalculationParameters {
  imageData: cornerstone.Types.IImageData;    // 图像数据
  rectanglePoints: Point3[];                  // 矩形顶点
  pixelSpacing: number[];                     // 像素间距 [x,y]
  modality: string;                          // 成像模态
}
```

## 🎯 执行流程

### 矩形区域灰度测量完整执行流程

**起点**: 用户在测量面板点击"矩形区域灰度"按钮

**主要步骤**：
1. **事件触发** → MeasurementPanel 按钮点击
2. **Action分发** → Redux更新measurementAction状态
3. **处理响应** → ViewerContainer useEffect监听状态变化
4. **工具激活** → MeasurementToolManager激活对应工具
5. **交互开始** → Cornerstone Tools处理鼠标事件
6. **标注创建** → Annotation Manager创建新的观察标注
7. **统计计算** → 计算选区内部素灰度统计信息
8. **结果显示** → 渲染测量结果覆盖层

### 详细子流程

#### 激活工具子流程
```
选择viewport → 检查toolGroup →
添加RectangleGrayscaleMeasurementTool → 设置工具为active模式 →
激活修改功能 → 创建默认标注 → 更新缓存统计 → 触发渲染
```

#### 数据计算子流程
```
获取图像数据 → 提取pixelData →
遍历矩形区域 → 累加像素值 →
计算Max/Min/Sum/Count → 计算Average和StdDev → 格式化结果
```

## 🧪 测试方案

### 功能测试场景

| 测试场景 | 测试步骤 | 预期结果 |
|----------|----------|----------|
| 正常使用场景 | 1. 点击"矩形区域灰度"按钮<br>2. 在图像上绘制矩形<br>3. 完成绘制 | 显示平均灰度值和统计信息 |
| CT图像测试 | 使用CT图像测试 | 显示HU值为负数，单位为HU |
| 多选区测试 | 在同一图像创建多个矩形 | 每个矩形独立显示统计信息 |
| 工具切换测试 | 使用后切换到其他测量工具 | 矩形标注保留，可以重新编辑 |
| 清除功能测试 | 使用"清除测量"功能 | 所有矩形标注消失 |

### 边界情况测试

| 边界情况 | 测试方法 | 预期结果 |
|----------|----------|----------|
| 空选区 | 绘制大小为0的矩形 | 显示警告或忽略操作 |
| 图像边界 | 绘制超出图像边界的矩形 | 自动裁剪到图像边界 |
| 小选区 | 选择1x1像素的矩形 | 显示单像素灰度值 |
| 大选区 | 选择覆盖整个图像的矩形 | 显示全局平均灰度值 |

### 人工测试操作步骤

1. **启动应用程序**
   ```bash
   npm run h5:browser
   # 或其他启动命令
   ```

2. **导航到测量面板**
   - 在主界面找到测量面板入口
   - 点击"图像测量"打开测量面板

3. **激活矩形区域灰度工具**
   - 在测量面板中找到"矩形区域灰度"按钮
   - 点击按钮激活测量工具

4. **执行测量**
   - 将鼠标移到图像上，鼠标指针变为测量工具样式
   - 按下鼠标左键，开始绘制矩形
   - 拖拽鼠标定义矩形区域
   - 松开鼠标左键完成绘制

5. **查看测量结果**
   - 观察矩形选区显示统计信息
   - 检查是否显示平均灰度值、面积等

6. **测试工具切换**
   - 激活其他测量工具，确认矩形标注保留
   - 重新选择矩形工具，点击标注进行编辑

7. **测试清除功能**
   - 在测量面板点击"清除测量"
   - 确认所有标注被移除

## 🐛 潜在问题检查

### 边界问题
- **内存管理**: 大图像大量标注可能造成内存压力
- **性能问题**: 实时计算大面积矩形的统计值可能较慢
- **多帧图像**: 需要考虑不同帧间的标注同步

### 异常处理
- **图像数据加载失败**: 应有错误提示而不是崩溃
- **网络请求超时**: 测量结果更新延迟的友好处理
- **不支持的图像格式**: 格式不支持时的降级提示

### 兼容性问题
- **不同DICOM模态**: CT和普通X-ray的灰度值处理差异

## 🔧 实现总结

### 核心文件修改

1. **新建文件**:
   - `src/components/measures/RectangleGrayscaleMeasurementTool.ts` - 矩形灰度测量工具类

2. **修改文件**:
   - `src/pages/view/components/viewers/stack.image.viewer.tsx` - 添加工具注册和导出函数
   - `src/utils/measurementToolManager.ts` - 添加工具管理方法
   - `src/pages/view/components/ViewerContainer.tsx` - 添加激活函数导入

### 解决的bug

1. **static方法中的this问题**: 将所有`this.getToolGroup(viewportId)`替换为`MeasurementToolManager.getToolGroup(viewportId)`

### 技术实现要点

1. **Cornerstone3D集成**: 基于BaseTool实现自定义测量工具
2. **统计计算**: 实现像素遍历和统计值计算
3. **状态管理**: 通过Redux集成到现有测量系统
4. **UI集成**: 无缝集成到测量面板和查看器

### 扩展性考虑

1. **配置驱动**: 通过MEASUREMENT_TOOL_CONFIGS支持新工具快速接入
2. **模态支持**: 基础架构支持不同DICOM模态的灰度处理
3. **多视口**: 完整的多视口支持和批量操作