# 实现方案

开始时间：2026-05-08-02-36-12

## 本次方案路径

`工程分析/实现方案-2026-05-08-02-36-12.md`

## 实现目标

在 DICOM 阅览中实现真实 STL 模型切分 mask，并用单个双端点进度条控制起点/终点帧。

## 涉及文件

- `web_backend.py`
- `WebSite/src/App.tsx`
- `工程分析/经验记录.md`

## 执行步骤

1. 后端新增 STL 模型目录和缓存：
   - `MODEL_DIR = web_library/_stl_models`
   - `STL_MODEL_CACHE`
   - 支持 ASCII STL 和 binary STL 解析为三角面数组。
2. 后端新增 STL 上传接口：
   - `POST /api/model/upload`
   - 使用请求体保存 STL 文件。
   - 返回 `modelId`、`name`、`triangleCount`。
3. 后端新增 DICOM 几何元数据提取：
   - 基于排序后的 DICOM 文件读取 `ImagePositionPatient`、`ImageOrientationPatient`、`PixelSpacing`。
   - 构造 patient 坐标到体素坐标的转换。
   - 元数据不足时降级为 STL 已是体素坐标。
4. 后端增强 `/api/library/reformat-preview`：
   - 支持 `modelId` 参数。
   - 当传入模型时，根据 `plane` 和 `index` 计算 STL 三角面与当前 DICOM 切片平面的交线。
   - 将交线栅格化并填充形成 mask，叠加到 DICOM PNG 上。
   - 返回 `maskPixels`，便于前端知道该帧是否有模型穿透。
5. 前端 DICOM 阅览新增模型切分控制：
   - STL 文件上传按钮。
   - 模型切分开关。
   - 一个双端点进度条控制起点/终点，两个端点允许交叉。
   - 起点/终点数值按当前切片总数约束。
6. 前端模型切分展示：
   - 模型切分关闭：保留当前单帧 DICOM 阅览。
   - 模型切分开启：显示起点帧、终点帧两张 DICOM 图，并请求后端叠加真实 STL mask。
   - 不再显示无意义的 CT MASK 图片或伪造圆圈 mask。
7. 执行测试方案。
8. 更新 `工程分析/经验记录.md`。
9. 提交并推送 Gitea，commit 信息使用 `2026-05-08-02-36-12 实现STL模型切分mask`。
10. 重新部署到 `http://192.168.3.11:3005/`。

## 回滚思路

若 STL mask 功能不符合预期，可回滚 `web_backend.py` 中 STL 上传/解析/mask 叠加逻辑，以及 `WebSite/src/App.tsx` 中模型切分 UI，恢复纯 DICOM 阅览。

## 风险控制

- STL 解析结果和 DICOM 体数据都使用缓存，避免高频重复解析。
- mask 叠加只影响阅览 PNG，不修改原始 DICOM 和形变输出。
- 双端点进度条不影响普通 DICOM 阅览切片滑杆。
- 若 STL 与 DICOM 空间不匹配，前端仍显示 DICOM 切片，并以 `maskPixels=0` 表示该帧无交集。

## 人工审核状态

用户已明确本次不需要人工二次确认，直接执行。