2026-05-18-17-40-02 构建导丝分割Web系统

工程分析/实现方案-2026-05-18-17-40-02.md

@@ -0,0 +1,54 @@
+# 实现方案
+
+开始时间：2026-05-18-17-40-02
+
+## 总体架构
+
+- `backend/`：Python FastAPI 服务，负责文件上传、帧抽取、导丝分割、结果落盘和静态文件服务。
+- `frontend/`：单页 Web 操作台，使用原生 HTML/CSS/JS，避免额外前端构建依赖。
+- `storage/`：运行时存放上传文件、处理帧、掩膜、叠加图和输出视频。
+- `scripts/`：生成演示视频、启动服务和测试辅助脚本。
+- `tests/`：算法与 API 的基础回归测试。
+
+## 分割方法
+
+1. `hessian_ridge`
+   - 对灰度图做 CLAHE 增强。
+   - 使用 `skimage.filters.frangi` 进行多尺度细线/管状结构增强。
+   - 自适应阈值与形态学清理后输出掩膜。
+
+2. `edge_morphology`
+   - 对反相增强图执行黑帽/顶帽和 Canny 边缘提取。
+   - 结合细长形态学核连接断裂线段。
+   - 用连通域面积过滤去除噪声。
+
+3. `temporal_difference`
+   - 视频场景下利用相邻帧差分提取移动细线候选。
+   - 与 `hessian_ridge` 的结构响应相交/相并，降低静态骨骼假阳性。
+   - 图片场景无前一帧时自动退化为 `hessian_ridge`。
+
+4. `fusion`
+   - 将 Hessian、边缘形态学、时序差分结果按权重融合。
+   - 提供更稳定的第一版默认结果。
+
+5. `compare`
+   - 对同一批帧运行多种方法，前端以矩阵方式对比。
+
+## Web 交互
+
+- 上传图片区和算法参数面板置于首屏，面向工程调试而非营销页。
+- 结果区显示原帧、叠加图、掩膜覆盖率、细线骨架长度等指标。
+- 提供输出视频与单帧结果链接。
+- 页面风格采用冷静的医学影像工作台：深色背景、清晰边界、克制高亮。
+
+## 部署方式
+
+- 使用 Python 虚拟环境安装依赖。
+- `scripts/run_dev.sh` 启动 FastAPI，默认监听 `0.0.0.0:8000`。
+- FastAPI 直接服务前端静态文件，访问 `http://127.0.0.1:8000`。
+
+## 后续扩展路径
+
+- 增加 PyTorch/ONNX 模型适配器，接入训练好的 U-Net/FRA-Net/MSLNet 类模型。
+- 接入 CathAction 或自有标注数据训练流程。
+- 增加人工修正、导丝中心线导出、端点定位和时序跟踪。

工程分析/测试方案-2026-05-18-17-40-02.md

@@ -0,0 +1,41 @@
+# 测试方案
+
+开始时间：2026-05-18-17-40-02
+
+## 自动化测试
+
+1. 算法单元测试
+   - 使用合成含导丝图像验证每种方法能输出非空掩膜。
+   - 验证 `compare` 返回多方法结果。
+   - 验证指标字段存在且数值范围合理。
+
+2. API 测试
+   - `GET /api/health` 返回运行状态。
+   - `GET /api/methods` 返回算法清单。
+   - `POST /api/segment` 上传合成图片并获得结果 URL。
+
+3. 启动验证
+   - 启动服务后访问首页。
+   - 调用健康检查接口。
+   - 使用合成演示视频跑一次分割。
+
+## 手工验证
+
+- 在浏览器打开 `http://127.0.0.1:8000`。
+- 上传 `storage/samples/synthetic_guidewire.mp4`。
+- 分别选择 `fusion` 和 `compare`，检查叠加结果、掩膜和视频下载链接。
+
+## 验收标准
+
+- 项目可通过启动脚本运行。
+- Web 页面可打开并完成上传分割流程。
+- 至少三种分割方式可选择，融合和对比模式可用。
+- 测试命令通过，或明确记录未通过原因与处理方式。
+
+## 执行结果
+
+- `bash scripts/generate_sample.sh`：通过，已生成 `storage/samples/synthetic_guidewire.mp4` 和 `storage/samples/synthetic_guidewire.png`。
+- `pytest -q`：通过，4 个测试全部通过。
+- `curl http://127.0.0.1:8001/api/health`：通过，返回 `status=ok`。
+- `curl http://127.0.0.1:8001/`：通过，首页返回 HTTP 200。
+- 使用合成视频调用 `POST /api/segment`：通过，返回 3 帧分割结果与叠加视频链接。

工程分析/经验记录.md

@@ -0,0 +1,35 @@
+# 经验记录
+
+本文件用于记录每次执行中出现的关键问题和解决方案。
+
+## 2026-05-18-17-40-02 Web 导丝分割系统第一版
+
+### 1. pytest 无法导入本地 backend 包
+
+A. 具体问题：执行 `pytest -q` 时，`tests/test_api.py` 和 `tests/test_segmentation.py` 报 `ModuleNotFoundError: No module named 'backend'`。
+
+B. 产生问题原因：项目是从空目录新建，尚未安装为 Python 包；pytest 启动时没有稳定地把项目根目录放入 `pythonpath`。
+
+C. 解决问题方案：新增 `pytest.ini`，配置 `pythonpath = .` 和 `testpaths = tests`。
+
+D. 后续如何避免问题：从零构建 Python 项目时同步添加 pytest 配置，或使用标准包管理配置声明测试路径。
+
+### 2. scikit-image 0.26 参数变更警告
+
+A. 具体问题：`remove_small_objects` 使用 `min_size` 时测试出现 FutureWarning。
+
+B. 产生问题原因：当前环境的 scikit-image 版本将 `min_size` 标记为废弃参数，并引入 `max_size` 表达“移除小于等于该面积的对象”。
+
+C. 解决问题方案：将 `remove_small_objects(binary, min_size=...)` 改为 `remove_small_objects(binary, max_size=...)`。
+
+D. 后续如何避免问题：固定依赖版本后仍要关注测试警告；图像处理库升级时优先查看函数签名和文档。
+
+### 3. 融合模式首帧过分割
+
+A. 具体问题：视频第 0 帧没有前帧，融合模式覆盖率一度达到约 22%，明显偏宽。
+
+B. 产生问题原因：时序差分在无前帧时退化为 Hessian，融合投票逻辑对无前帧使用了一票通过，导致边缘形态学噪声被并入。
+
+C. 解决问题方案：融合模式统一使用两票通过，低响应时才回退到一票；同时将边缘形态学改成暗线候选约束下的边缘检测。
+
+D. 后续如何避免问题：视频算法要单独检查首帧、丢帧和单图退化路径；融合策略必须记录每个子方法的置信约束。

工程分析/需求分析-2026-05-18-17-40-02.md

@@ -0,0 +1,42 @@
+# 需求分析
+
+开始时间：2026-05-18-17-40-02
+
+## 用户目标
+
+构建一个用于介入导丝视频中导丝分割的 Web 系统，支持多种分割方式、上传视频或图像、展示原图/掩膜/叠加结果，并可持续迭代到系统可运行。
+
+## 工作流要求
+
+1. 每次需求开始前记录时间戳。
+2. 阅读或创建 `工程分析` 文件夹。
+3. 本次需求分析写入当前文档。
+4. 实现方案写入 `工程分析/实现方案-2026-05-18-17-40-02.md`。
+5. 测试方案写入 `工程分析/测试方案-2026-05-18-17-40-02.md`。
+6. 执行前阅读 `工程分析/经验记录.md`；执行后将关键问题按四段式写入。
+7. 完成后使用 Gitea 备份 commit，并重新部署项目。
+
+## 第一版可运行范围
+
+- 后端提供导丝分割 API，支持图片和视频文件上传。
+- 前端提供 Web 操作台，支持选择算法、参数调整、结果预览和下载。
+- 分割方法至少包含：
+  - Hessian/Frangi 类细线增强。
+  - 边缘与形态学细线检测。
+  - 视频时序差分增强。
+  - 多方法融合与对比模式。
+- 提供合成示例视频生成脚本，便于无真实介入视频时验证系统。
+- 提供基础自动化测试和启动脚本。
+
+## 技术检索摘要
+
+- 近期导丝分割研究普遍强调 X 射线透视下低信噪比、导丝像素占比极低、骨骼/器械干扰和实时性要求。
+- 深度学习方向包括多帧输入 CNN、轻量注意力网络、U-Net/Transformer 变体、拓扑保持损失和 sim-to-real 自适应。
+- 当前工程第一版优先实现无需训练数据即可运行的传统图像处理与融合路线，并保留深度学习模型接入接口。
+
+## 参考来源
+
+- MSLNet and Perceptual Grouping for Guidewire Segmentation and Localization: https://www.mdpi.com/1424-8220/25/20/6426
+- CathAction segmentation task: https://airvlab.github.io/cathaction/docs/segmentation/
+- Fully Automatic and Real-Time Catheter Segmentation in X-Ray Fluoroscopy: https://arxiv.org/abs/1707.05137
+- Lightweight attention network for guidewire segmentation and localization: https://qims.amegroups.org/article/view/136604/html