2026-05-20-00-19-47 同步位姿并填充实体映射

工程分析/实现方案-2026-05-20-00-19-47.md

@@ -0,0 +1,54 @@
+# 实现方案-2026-05-20-00-19-47
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-20-00-19-47.md`
+
+## 修改目标
+
+让右侧“逆向分割映射视图”的 Overlay Label Map 实时响应中部模型位姿，并将渲染形态从表面三角面投影升级为闭合实体 Mask 区域填充。
+
+## 涉及路径
+
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `工程分析/需求分析-2026-05-20-00-19-47.md`
+- `工程分析/实现方案-2026-05-20-00-19-47.md`
+- `工程分析/测试方案-2026-05-20-00-19-47.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 在 `VoxelizationMappingView` 新增 `modelPose` 入参，父组件直接传入中部工具栏当前位姿。
+2. 新增浏览器端刚性变换函数：
+   - 以全局 STL bounds 中心归一化顶点。
+   - 按 `scale -> rotateX -> rotateY -> rotateZ -> translate` 顺序变换。
+   - 将变换后坐标映射到固定 DICOM Overlay 画布坐标系。
+3. 将原先“靠近切片的三角面填充”改为“切片平面求交”：
+   - 对每个三角面与当前 Z 平面求交。
+   - 收集切面边界线段。
+4. 将边界线段按扫描线射线法光栅化为实心 Mask：
+   - 逐行收集边界线段与水平扫描线的交点。
+   - 采用奇偶配对填充闭合区域内部像素。
+   - 按构件颜色与透明度写入 Overlay ImageData，并通过离屏画布合成，避免多构件互相覆盖。
+5. 对边界不完全闭合的极少数抽样场景，使用端点多边形保底填充，避免完全空白。
+6. 使用 `requestAnimationFrame` 合并高频位姿变化，做到位姿滑条拖动时实时刷新。
+7. 更新右侧状态文案，显示实心 Mask 像素数量和参与构件数量。
+
+## 兼容性与回滚方案
+
+- 不修改后端 API，不影响 DICOM preview、STL preview 和导出接口。
+- 如果新填充算法异常，可回退到上一版 `drawVoxelOverlayLayer`。
+- 如果某个构件没有形成闭合区域，只影响该构件 Overlay，不影响 Base Layer 和其他构件。
+
+## 预计文件变更
+
+- `ReverseWorkspace.tsx`：新增位姿变换、切面求交、Mask flood fill、Overlay rAF 重绘。
+- 新增本次三份工程文档。
+- 更新 `经验记录.md`。
+
+## 提交与部署策略
+
+- 执行 `npm run lint` 与 `npm run build`。
+- 重新部署 `tmux` 会话 `revoxelseg-dicom`。
+- 提交信息：`2026-05-20-00-19-47 同步位姿并填充实体映射`
+- 使用已验证的 Gitea 临时凭据方式推送。

工程分析/测试方案-2026-05-20-00-19-47.md

@@ -0,0 +1,59 @@
+# 测试方案-2026-05-20-00-19-47
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-20-00-19-47.md`
+
+## 静态检查
+
+- 在 `WebSite/` 下执行 `npm run lint`。
+
+## 构建检查
+
+- 在 `WebSite/` 下执行 `npm run build`。
+
+## 关键业务场景验证
+
+- 打开逆向工作区，确认右侧仍为“逆向分割映射视图”。
+- 拖动中部模型位姿的 X/Y/Z 平移滑条，右侧 Overlay 位置即时变化。
+- 拖动 X/Y/Z 旋转滑条，右侧 Overlay 截面形态即时变化。
+- 拖动缩放滑条，右侧 Overlay 大小即时变化。
+- 右侧 Overlay 应显示连续实心色块，而不是零散表面三角面/点云。
+- 调整构件颜色、透明度、显示隐藏后，右侧实心 Mask 即时联动。
+- 拖动右侧 Slice Navigator，DICOM Base Layer 与实心 Mask 共同切换。
+
+## 医学影像数据相关边界验证
+
+- STL preview 不可用时，Base Layer 仍显示 DICOM。
+- 构件交线无法闭合时，不应导致页面报错。
+- 切片序号需要 clamp 到合法范围。
+- 位姿拖动时不应重新请求 STL preview，只应重绘 Overlay。
+
+## 部署验证
+
+- 重启 `tmux` 会话 `revoxelseg-dicom`。
+- 验证：
+  - `curl http://127.0.0.1:4000/api/health`
+  - `curl -I http://127.0.0.1:4000/`
+
+## Git/Gitea 备份验证
+
+- 显式暂存本次相关代码和文档。
+- 创建包含时间戳和描述的 commit。
+- 推送到 Gitea `origin/main`。
+
+## 回归关注点
+
+- 不影响左侧三维融合视图。
+- 不影响中部构件层级保存。
+- 不影响 `.nii` / `.nii.gz` 导出按钮。
+
+## 实际执行结果
+
+- `npm run lint`：通过。
+- `npm run build`：通过；Vite 保留既有 chunk 体积提示，不影响构建产物生成。
+- 部署：已重启 `tmux` 会话 `revoxelseg-dicom`，服务日志显示 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
+- `curl http://127.0.0.1:4000/api/health`：通过，返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
+- `curl -I http://127.0.0.1:4000/`：通过，返回 `HTTP/1.1 200 OK`。
+- `curl http://127.0.0.1:4000/api/projects/head-ct-demo`：通过，确认示例项目含 300 张 DICOM 与 9 个 STL 构件。
+- `curl` 验证 DICOM preview 与 STL preview 接口：通过，右侧 Base/Overlay 所需数据可正常返回。

工程分析/经验记录.md

@@ -883,3 +883,39 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 新增影像浏览控件前先判断其控制对象是“单切片位置”还是“显示范围/切割范围”。单切片校验使用独立 slice 状态，范围切割使用起止端点状态，避免不同视图之间产生隐式联动。
+
+## 2026-05-20-00-19-47 右侧映射视图必须复用中部模型位姿
+
+A. 具体问题
+
+右侧“逆向分割映射视图”虽然已经使用 DICOM Base Layer 和 STL Overlay，但 Overlay 计算没有接入中部“模型位姿”状态；用户拖动 X/Y/Z 平移或旋转后，左侧三维视图变化，右侧二维映射仍按旧 STL 原始坐标绘制。
+
+B. 产生问题原因
+
+上一版 `VoxelizationMappingView` 只接收 `moduleStyles`、`slice` 和 STL preview 数据，没有接收 `modelPose`；`drawVoxelOverlayLayer` 直接使用 STL 原始顶点和全局 bounds 计算投影，没有先执行与三维场景一致的归一化、旋转、缩放和平移。
+
+C. 解决问题方案
+
+为 `VoxelizationMappingView` 增加 `modelPose` 入参，由父组件直接传入中部工具栏的当前位姿；在 Overlay 计算前对 STL 顶点执行 `scale -> rotateX -> rotateY -> rotateZ -> translate`，再与当前 Z 轴 DICOM 切片平面求交，并使用 `requestAnimationFrame` 合并高频滑条更新。
+
+D. 后续如何避免问题
+
+凡是右侧二维映射、Mask、Label Map 或导出预览依赖 STL 空间位置时，都必须确认其输入状态包含当前权威位姿；不能让三维视图和二维视图各自维护坐标变换。新增视图前先列出共享状态：位姿、构件样式、切片位置和数据源。
+
+## 2026-05-20-00-19-47 实体 Mask 填充不能覆盖多构件叠加
+
+A. 具体问题
+
+将截面交线转为实心 Mask 时，如果每个构件直接在主 Overlay canvas 上 `putImageData`，后一个构件的透明像素会覆盖掉前一个构件，导致多构件同时显示时可能只剩最后绘制的构件。
+
+B. 产生问题原因
+
+Canvas 的 `putImageData` 是像素替换操作，不是透明合成操作；即使 ImageData 中某些像素 alpha 为 0，也会把目标 canvas 对应位置写成透明，从而擦掉已有 Overlay。
+
+C. 解决问题方案
+
+每个构件先在离屏 canvas 中生成扫描线射线法填充的实心 Mask，再使用 `drawImage` 以 `source-over` 合成到主 Overlay canvas；边界描边也在合成后按构件颜色与透明度绘制，保留多构件叠加效果。
+
+D. 后续如何避免问题
+
+多层或多构件 Canvas 叠加时，优先使用离屏画布或单次合并后的 ImageData；只有在明确要替换整张图时才使用主 canvas 的 `putImageData`。涉及透明叠加的渲染改动，必须检查“前一层是否会被透明像素擦除”。

工程分析/需求分析-2026-05-20-00-19-47.md

@@ -0,0 +1,54 @@
+# 需求分析-2026-05-20-00-19-47
+
+## 开始时间
+
+2026-05-20-00-19-47
+
+## 原始需求摘要
+
+用户要求继续优化右侧“逆向分割映射视图”：一是让中部“位姿调整”中的 X/Y/Z 平移与旋转实时驱动右侧二维映射重算，实现三维刚性变换与二维切片结果所见即所得；二是将当前偏表面边界/点云式的 Overlay 映射升级为医学标准的闭合实体区域实心 Mask 色块填充。
+
+## 业务目标
+
+- 中部模型位姿调整后，右侧 Overlay Label Map 立即按新位姿刷新。
+- 右侧视图不再显示零散表面投影，而是显示连续、饱满、可透明叠加的闭合区域 Mask。
+- 保持 DICOM 原始灰度图作为 Base Layer。
+- 保持构件层级颜色、透明度、显隐、Label ID 与右侧 Overlay 实时联动。
+
+## 输入与输出
+
+- 输入：
+  - 当前 `modelPose` 中的旋转、平移、缩放参数。
+  - STL preview 三角面顶点。
+  - 当前右侧 `mappingSlice`。
+  - 构件层级 `moduleStyles`。
+  - DICOM preview 灰度像素。
+- 输出：
+  - 应用位姿矩阵后的 STL 切片交线。
+  - 由交线闭合填充生成的二维实心 Label Map。
+  - 与 DICOM Base Layer 对齐的 Overlay Mask。
+
+## 影响范围
+
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- 本次工程分析文档与 `工程分析/经验记录.md`
+- 不修改后端 API、不引入新的依赖。
+
+## 关键约束
+
+- 右侧映射必须直接使用中部 `modelPose`，不能另建位姿状态。
+- 位姿变换需要作用于 STL 顶点后再参与切片平面求交。
+- 生成 Mask 时必须从 STL 几何交线推导，避免无来源伪 Mask。
+- 右侧 Slice Navigator 仍保持独立，不影响左侧 DICOM 范围。
+- 本次提交不能混入历史 `工程分析` 文档删除状态。
+
+## 风险点
+
+- 浏览器端基于 STL preview 抽样做切面栅格化，精度仍受抽样数量影响，不能等同于后端医学级体素化。
+- flood fill 对边界闭合质量敏感，需要加粗边界并提供保底闭合策略。
+- 位姿滑条高频更新时，需要避免每次都重新请求 STL，只应在内存中重算 Overlay。
+
+## 默认假设
+
+- 当前需求继续按已确认的“后续直接搞”执行。
+- 默认把右侧 Overlay 算法升级为浏览器端交线光栅化与闭合填充，后续可替换为后端真实体素化 Label Map。