2026-05-24-22-40-13 新增自动微调匹配工作区

工程分析/实现方案-2026-05-24-22-40-13.md

@@ -0,0 +1,64 @@
+# 实现方案-2026-05-24-22-40-13
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-24-22-40-13.md`
+
+## 修改目标
+
+- 新增自动微调匹配工作区和逆向工作区入口按钮。
+- 新增后端自动微调匹配接口，固定旋转，只优化允许的平移和缩放。
+- 实现骨窗/骨骼构件匹配的首版可解释评分。
+- 支持将最佳结果应用回项目位姿。
+
+## 涉及路径
+
+- `WebSite/src/App.tsx`
+- `WebSite/src/components/Sidebar.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/src/components/AutoMatchWorkspace.tsx`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/types.ts`
+- `WebSite/server.ts`
+- `Docker部署/README.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+- 路由层新增 `auto-match` 视图，左侧导航新增图标入口。
+- 逆向工作区保存按钮左侧增加“自动微调匹配”，点击进入自动匹配页面并携带当前项目 ID。
+- 后端新增 `POST /api/projects/:projectId/auto-match`，接收位姿、构件、参数开关和迭代设置，返回最佳 pose 与轨迹。
+- 后端新增 `PATCH /api/projects/:projectId/model-pose`，用于应用最佳 pose 到项目库。
+- 评分函数采用：骨窗命中奖励、离骨惩罚、移动惩罚、缩放偏移惩罚；多切片抽样并对骨骼 STL 顶点/三角采样投影评分。
+- 优化策略采用多模式坐标搜索：粗到细步长，逐轮生成候选，允许每轮只改一个参数或组合改多个参数，选择最高分收敛。
+
+## 执行步骤
+
+1. 阅读现有 App、Sidebar、ReverseWorkspace、api、server 类型与项目状态逻辑。
+2. 新增 API 类型与后端自动匹配/位姿应用接口。
+3. 新增 AutoMatchWorkspace 页面，提供项目选择、参数开关、构件选择、权重和运行结果。
+4. 在逆向工作区顶部接入入口按钮。
+5. 更新 Docker 文档和经验记录。
+6. 执行类型检查、构建和接口 smoke test。
+7. 重启服务并验证本机与公网入口。
+8. 提交并推送到 Gitea。
+
+## 兼容性与回滚方案
+
+- 不改变原有保存项目和导出结果接口。
+- 自动匹配结果只有点击应用后才写入项目位姿。
+- 若评分效果不理想，可回滚本次 commit 或替换后端评分函数。
+
+## 预计文件变更
+
+- 4-5 个前端源码文件。
+- 1 个后端服务文件。
+- 1 个 Docker 部署说明文件。
+- 3 个工程分析当次文档。
+- 1 个经验记录追加。
+
+## 提交与部署策略
+
+- Commit message 使用 `2026-05-24-22-40-13 新增自动微调匹配工作区`。
+- 构建通过后重启 `tmux` 会话 `revoxelseg-dicom`。
+- 验证本机和公网入口。

工程分析/测试方案-2026-05-24-22-40-13.md

@@ -0,0 +1,50 @@
+# 测试方案-2026-05-24-22-40-13
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-24-22-40-13.md`
+
+## 静态检查
+
+- 执行 `cd WebSite && npm run lint`。
+- 搜索新增路由、API 和自动匹配类型，确认前后端字段一致。
+
+## 构建检查
+
+- 执行 `cd WebSite && npm run build`。
+- 确认生产构建成功。
+
+## 关键业务场景验证
+
+- 左侧出现“自动微调匹配工作区”入口。
+- 逆向工作区“保存至项目库”左侧出现“自动微调匹配”按钮。
+- 自动匹配页面默认选中平移 X/Y/Z 和缩放，旋转不可选。
+- 默认骨骼构件包含 rib、vertebrae、sternum、hipbone、sacrum 等。
+- 点击运行后返回最佳位姿、评分轨迹和候选结果。
+- 点击应用后项目位姿更新，回到逆向工作区可看到新位姿。
+
+## 医学影像数据相关边界验证
+
+- 本次不修改原始 DICOM/STL。
+- 第一版评分是演示级骨窗匹配，不承诺临床级配准。
+- DICOM 切片顺序、分割导出和锁定项目逻辑不应受影响。
+
+## 部署验证
+
+- 重启 `tmux` 会话 `revoxelseg-dicom`。
+- 验证 `http://127.0.0.1:4000/api/health`。
+- 验证 `http://127.0.0.1:4000/`。
+- 验证 `https://revoxel.huijutec.cn/api/health` 与 `https://revoxel.huijutec.cn/`。
+
+## Git/Gitea 备份验证
+
+- 暂存本次相关源码、Docker 说明和工程分析文档。
+- 提交 message 包含本次时间戳。
+- 推送到 Gitea `main` 后确认本地分支与远端同步。
+
+## 风险与回归关注点
+
+- 自动匹配不能自动修改旋转。
+- 应用最佳结果前不应覆盖项目位姿。
+- 评分接口要限制迭代规模，避免阻塞服务太久。
+- 锁定项目不应被自动应用位姿覆盖。

工程分析/经验记录.md

@@ -1833,3 +1833,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 涉及 DICOM/STL 配准的坐标系必须独立于可见性、筛选条件和 UI 状态；性能优化可以只加载可见构件的高精度网格，但全局中心、缩放、slice Z 映射应来自稳定的全部模型边界。凡是用户反馈“隐藏某构件后其他构件位置变了”，优先检查 bounds 是否被可见列表重算。
+
+## 2026-05-24-22-40-13 自动微调匹配要锁定人工旋转并使用同一导出坐标系
+
+A. 具体问题
+
+用户希望在逆向工作区先人工调好大致旋转，然后进入一个新的自动微调匹配工作区，只让系统自动尝试平移 X/Y/Z 与缩放，使用骨骼区域和 DICOM 骨窗收敛到更好的位置。
+
+B. 产生问题原因
+
+项目此前只有人工位姿控件和导出时的 STL/DICOM 映射逻辑，没有单独的自动优化入口。若自动匹配重新定义坐标系或允许修改旋转，会破坏用户已经完成的人工粗配准；若评分只奖励重合，不限制移动和缩放，也容易出现“为了命中骨窗而漂移”的局部最优。
+
+C. 解决问题方案
+
+新增 `AUTO_MATCH` 视图、侧边栏入口和逆向工作区顶部“自动微调匹配”按钮，点击时携带当前位姿。服务端新增 `POST /api/projects/:projectId/auto-match` 和 `PATCH /api/projects/:projectId/model-pose`：匹配接口复用导出模块的 STL 全局 bounds、DICOM HU 体数据和 `transformPointForExportPose` 位姿变换；默认选择骨骼命名 STL，按三角面中心采样，使用 HU 骨窗阈值给骨命中奖励、非骨/越界惩罚，并叠加移动惩罚和缩放惩罚；候选搜索从粗到细尝试单参数和组合参数。应用接口会写入 `auto-match` 位姿，并在项目锁定时拒绝覆盖。
+
+D. 后续如何避免问题
+
+后续继续优化自动配准时，要保持“人工旋转锁定、自动只微调平移/缩放”的边界，且必须复用导出/映射同一坐标系。评分函数可以继续替换为 Dice、Chamfer、距离变换或多线程 Worker，但移动惩罚、缩放惩罚、候选上限和锁定项目保护不能省；否则会出现匹配看似得分更高、实际位置漂移或覆盖锁定项目的问题。

工程分析/需求分析-2026-05-24-22-40-13.md

@@ -0,0 +1,50 @@
+# 需求分析-2026-05-24-22-40-13
+
+## 开始时间
+
+2026-05-24-22-40-13
+
+## 原始需求摘要
+
+用户要求新增“自动微调匹配工作区”：左侧新增入口；逆向工作区“保存至项目库”左侧增加“自动微调匹配”按钮。用户会先在逆向工作区大致调整旋转，进入自动微调后选择允许修改的参数，默认平移 X/Y/Z 与缩放，不允许自动调整旋转；选择骨骼区域，使用 DICOM 骨窗作为匹配依据，自动迭代优化，可尝试多种模式并收敛到最佳位置。
+
+## 业务目标
+
+- 提供从逆向工作区进入自动微调匹配的工作流。
+- 保留人工旋转作为前置步骤，自动优化只调整用户允许的平移和缩放参数。
+- 以骨窗 DICOM 与骨性 STL 构件为初始匹配目标，形成可解释的评分、奖励项和惩罚项。
+- 自动迭代输出最佳位姿，可应用回项目状态，供用户回到逆向工作区复核和保存。
+
+## 输入与输出
+
+- 输入：项目 ID、当前模型位姿、构件样式、允许调整参数、骨骼构件范围、迭代模式和惩罚权重。
+- 输出：最佳位姿、评分变化、每轮候选结果、可应用到项目的位姿更新。
+
+## 影响范围
+
+- 前端导航与工作区路由。
+- `ReverseWorkspace` 顶部操作入口。
+- 新增 `AutoMatchWorkspace` 前端页面。
+- `WebSite/src/lib/api.ts` API 封装与类型。
+- `WebSite/server.ts` 自动微调匹配 API、位姿评分和项目位姿应用逻辑。
+- `Docker部署/README.md` 和 `工程分析/经验记录.md`。
+
+## 关键约束
+
+- 自动匹配不能修改旋转，只能使用已有旋转作为前提。
+- 默认只允许平移 X/Y/Z 与缩放，可由用户关闭某些参数。
+- 不修改原始 DICOM/STL 数据，不伪装成临床级配准算法。
+- 第一版以可解释、可复核、可继续替换真实算法为目标。
+
+## 风险点
+
+- 如果评分函数只看重合奖励，可能为了覆盖骨窗而过度平移或放大，需要移动惩罚和尺度惩罚。
+- 如果只使用单切片评分，容易局部最优；需要多切片抽样。
+- 如果迭代步长过大，可能跳过最佳点；步长过小会运行太慢。
+- 运行时间不能阻塞页面太久，需要限制样本数量和候选数量。
+
+## 待确认问题或默认假设
+
+- 默认骨骼区域包含文件名含 `rib`、`vertebrae`、`sternum`、`hipbone`、`sacrum` 的 STL 构件。
+- 默认使用 DICOM 骨窗阈值筛选高亮骨性像素，并以 STL 骨性构件投影点附近的骨窗响应作为奖励。
+- 第一版内部使用多候选并发评分的坐标搜索，而不是引入外部优化库。