dros/plans/cornerstone3d-tool-management-analysis.md

Cornerstone3D 多 Viewport 工具管理 - 当前按钮分析

一、当前 FunctionArea 按钮清单

基于 FunctionArea.tsx 的分析，当前共有 30 个功能按钮：

1. 标记类按钮 (Annotation Buttons)

Action	Title (i18n)	Icon	当前行为
Add L Mark	添加 L 标记	LMark	一次性操作
Add R Mark	添加 R 标记	RMark	一次性操作
AddMark	添加标记	AddMark	切换到标记面板
Delete Selected Mark	删除选中标记	EraseMark	一次性操作

2. 图像变换按钮 (Image Transform Buttons)

Action	Title (i18n)	Icon	当前行为
Horizontal Flip	水平翻转	HReverse	一次性操作
Vertical Flip	垂直翻转	VReverse	一次性操作
Rotate Counterclockwise 90	逆时针旋转90°	RotateL90	一次性操作
Rotate Clockwise 90	顺时针旋转90°	RotateR90	一次性操作
Rotate Any Angle	任意角度旋转	RotateAnyDegree	一次性操作

3. 裁剪/掩码按钮 (Crop/Mask Buttons)

Action	Title (i18n)	Icon	当前行为
Crop Selected Area	裁剪选定区域	Crop	❌ 未实现
Delete Digital Mask	删除数字掩码	btn_RemoveCrop	❌ 未实现
Add Mask	添加掩码	AddMask	激活掩码工具
Delete Mask	删除掩码	DeleteMask	清除掩码

4. 亮度/对比度按钮 (Brightness/Contrast Buttons)

Action	Title (i18n)	Icon	当前行为	特殊标记
Adjust Brightness and Contrast	调整亮度对比度	btn_BrightnessContrast	调整亮度对比度	✅ STATEFUL_BUTTON
Invert Contrast	反色对比	btn_ReverseColour	一次性操作

5. 布局按钮 (Layout Buttons)

Action	Title (i18n)	Icon	当前行为
1x1 Layout	1x1 布局	1x1_normal	切换布局
1x2 Layout	1x2 布局	1x2_normal	切换布局
2x2 Layout	2x2 布局	2x1_normal	切换布局
4x4 Layout	4x4 布局	2x2_normal	切换布局

6. 放大/缩放按钮 (Zoom/Magnify Buttons)

Action	Title (i18n)	Icon	当前行为	特殊标记
Magnifier	放大镜	Magnifier	激活放大镜工具	✅ STATEFUL_BUTTON
Fit Size	适应窗口大小	FitInWindow	一次性操作
Original Size	原始大小	1by1_normal	一次性操作
Zoom Image	缩放图像	Zoom	❌ 未实现

7. 导航/交互按钮 (Navigation/Interaction Buttons)

Action	Title (i18n)	Icon	当前行为
Reset Cursor	重置光标	btn_pointer	❌ 未实现
Pan	平移	Pan	❌ 未实现
Image Comparison	图像对比	btn_Compare	❌ 未实现

8. 图像处理按钮 (Image Processing Buttons)

Action	Title (i18n)	Icon	当前行为
Invert Image	反转图像	Invert	一次性操作
Reset Image	重置图像	Reset	一次性操作
Snapshot	快照	imgsnapshot	❌ 未实现

9. 高级功能按钮 (Advanced Feature Buttons)

Action	Title (i18n)	Icon	当前行为
Advanced Processing	高级处理	btn_Imageprocess	切换到高级处理面板
Image Measurement	图像测量	btn_Measurements	切换到测量面板
Rectangle Crop	矩形裁剪	rectangle-crop	切换到矩形裁剪面板
More	更多	btn_OtherSetting	切换到更多功能面板

---

二、按钮行为分类

A. 一次性操作按钮 (One-time Action)

特点： 点击后立即执行，不保持状态

• 所有标记按钮
• 所有图像变换按钮
• Invert Contrast, Fit Size, Original Size
• Invert Image, Reset Image
• Delete Mask

B. 状态按钮 (Stateful Toggle)

特点： 点击激活工具，再次点击停用

• ✅ Adjust Brightness and Contrast (在 STATEFUL_BUTTON_ACTIONS)
• ✅ Magnifier (在 STATEFUL_BUTTON_ACTIONS)
• Zoom Image
• Pan

C. 面板切换按钮 (Panel Switch)

特点： 打开侧边栏面板

• AddMark, Advanced Processing
• Image Measurement, Rectangle Crop, More

D. 未实现按钮 (Not Implemented)

• Crop Selected Area, Delete Digital Mask
• Image Comparison, Zoom Image
• Reset Cursor, Pan, Snapshot

---

三、关键发现

1. 当前问题

1. Pan 按钮未实现：设计文档提到的 Pan 工具目前被 showNotImplemented() 拦截
2. WindowLevel 工具缺失：没有独立的 WindowLevel 按钮
3. 状态管理不一致：
   • "Adjust Brightness and Contrast" 在 STATEFUL_BUTTON_ACTIONS 中
   • 但其 handleButtonClick 逻辑调用 adjustBrightnessAndContrast(viewportId) (一次性操作)
   • 与设计文档的 "持续工具" 语义冲突

2. Cornerstone3D 工具对应关系

FunctionArea Action	Cornerstone3D Tool	当前状态
Adjust Brightness and Contrast	WindowLevelTool	按钮存在，但行为是一次性函数调用
Pan	PanTool	按钮存在，但被标记为"未实现"
Magnifier	MagnifyTool	按钮存在，标记为 STATEFUL

---

四、设计文档要求对照

设计文档需求

// 两个工具作为示例
tools: ['WindowLevel', 'Pan']

// 行为规则
1. 点击按钮 → 工具 Active + 抢左键 + 按钮高亮
2. 再次点击 → 工具 Passive + 释放左键 + 取消高亮
3. 同一时间：允许无工具抢左键，不允许多个工具同时抢左键

当前实现差距

1. WindowLevel：

   • ❌ 无独立按钮名称（被隐藏在 "Adjust Brightness and Contrast"）
   • ❌ 无 Redux 状态管理（只在 STATEFUL_BUTTON_ACTIONS 集合中）
   • ❌ 无 ToolGroup 绑定逻辑

2. Pan：

   • ✅ 按钮存在
   • ❌ 被 showNotImplemented() 拦截
   • ❌ 无 Redux 状态管理
   • ❌ 无 ToolGroup 绑定逻辑

---

五、建议实现路径

选项 A：最小改动（推荐）

映射现有按钮到 Cornerstone3D 工具

1. WindowLevel → "Adjust Brightness and Contrast" 按钮

   • 修改 handleButtonClick 逻辑
   • 从一次性函数调用改为 Redux toggle
   • 添加 activeTools['WindowLevel'] 状态

2. Pan → "Pan" 按钮

   • 移除 showNotImplemented() 拦截
   • 添加 Redux toggle 逻辑
   • 添加 activeTools['Pan'] 状态

选项 B：完整重构

统一所有工具到新架构

1. 重命名/重构所有 STATEFUL 按钮
2. 区分 "交互工具"（需要鼠标绑定）和 "一次性操作"
3. 统一使用 Redux activeTools 管理所有持续工具

---

六、后续问题

请确认以下设计决策：

1. 工具互斥性：

   • WindowLevel 和 Pan 是否互斥？
   • 是否允许两者都处于非激活状态？

2. 按钮映射：

   • 确认使用 "Adjust Brightness and Contrast" → WindowLevel
   • 确认使用 "Pan" → PanTool

3. 其他工具：

   • Magnifier 是否也需要纳入新架构？
   • 测量工具是否保持现状？

4. 向后兼容：

   • 是否需要保持现有 adjustBrightnessAndContrast(viewportId) 函数？

   • 或完全替换为新的 ToolGroup 绑定逻辑？

     七、需求

5. Adjust Brightness and Contrast 、Magnifier 、Zoom Image、pan。这4个是有状态按钮。点击任一按钮后，其他三个按钮对应的工具处于失活状态，不再绑定鼠标左键了；被点击的按钮绑定了鼠标左键。对应工具成功激活并绑定左键后高亮。

6. 点击面板上的任一按钮，不论是一面板切换按钮，还是一次性按钮，当前绑定鼠标左键的按钮要失活，不再和鼠标左键绑定

7. 重置光标按钮的功能。清除几个状态按钮的按下状态。

8. 多分格状态下。按钮可用性如下表：

   1. 按钮名 所在分组 多分格可用性 Add L Mark【添加L标记】 FunctionArea (功能区) ❌ Add R Mark【添加R标记】 FunctionArea (功能区) ❌ Add Mask【添加标记】 FunctionArea (功能区) ❌ Delete Selected Mark【删除标记】 FunctionArea (功能区) ❌ 添加Mask【人医】 FunctionArea (功能区) ❌ Delete Mask【删除Mask】 FunctionArea (功能区) ❌ Horizontal Flip【水平翻转】 FunctionArea (功能区) ✅ Vertical Flip【竖直翻转】 FunctionArea (功能区) ✅ Rotate Counterclockwise 90°【逆时针旋转90°】 FunctionArea (功能区) ✅ Rotate Clockwise 90°【顺时针旋转90°】 FunctionArea (功能区) ✅ Rotate Any Angle【任意角度旋转】 FunctionArea (功能区) ❌ Crop Selected Area【裁剪图像】【人医】 FunctionArea (功能区) ❌ Delete Digital Mask【删除数字遮挡线】【人医】 FunctionArea (功能区) ❌ Adjust Brightness and Contrast【鼠标调节亮度对比度】 FunctionArea (功能区) ✅ Image Comparison【图像对比】 FunctionArea (功能区) ✅ 反色对比 FunctionArea (功能区) ✅ 1x1 Layout FunctionArea (功能区) ✅ 1x2 Layout FunctionArea (功能区) ✅ 2x2 Layout FunctionArea (功能区) ✅ 4x4 Layout FunctionArea (功能区) ✅ Magnifier【放大镜】 FunctionArea (功能区) ❌ Fit Size【适应大小】 FunctionArea (功能区) ✅ Original Size【原始大小】 FunctionArea (功能区) ✅ Zoom Image【缩放图像】 FunctionArea (功能区) ✅ Reset Cursor【重置光标】 FunctionArea (功能区) ✅ Pan【漫游】 FunctionArea (功能区) ✅ Invert Image【反色图像】 FunctionArea (功能区) ❌ Reset Image【重置图像】 FunctionArea (功能区) ❌ Snapshot【快照】 FunctionArea (功能区) ❌ Advanced Processing【高级处理】 FunctionArea (功能区) ❌ Image Measurement【测量工具】 FunctionArea (功能区) ❌ 矩形裁剪【人医】 FunctionArea (功能区) ❌ More【更多】 FunctionArea (功能区) ❌ 拒绝 ImageStateControl (图像状态控制) ❌ 恢复 ImageStateControl (图像状态控制) ❌ 另存为 ImageStateControl (图像状态控制) ❌ Send【发送】 TransferArea (传输区) ✅