CADx-4/research-wiki/任务书/02-CEUS定量.md

# 任务书 02：CEUS 定量

把旧项目的 CEUS（超声造影视频）定量算法迁到本仓库，在本机显卡上跑完全部病例。对每段视频，程序要圈出病灶、画出亮度随时间变化的曲线、挑出关键帧、算出灌注指标，最后由 build 把每例的 7 张关键帧和指标装进资料库的超声一路。资料库里原有医生截的关键结构图，加上这 7 张，一共 8 张图。

对应 `research-wiki/explanation/结构.md` 第七部分第 3 步。前提：任务书 01 已完成（提交 bceb01e）。

一份任务书分四个阶段，每个阶段做完单独提交，四个阶段都完成后一起交报告（负责人 2026-10-16：「任务书一份」）。

来源：

- 负责人 2026-10-16 定：CEUS 代码「直接一个个迁移」，不在本机重跑旧代码作对比基线（design 0002 决定 4）。
- 负责人 2026-10-16 定：「推注开始时间s」是视频第 0 秒时已经推注了多少秒；40 例没有医生标的造影剂到达时间，关键帧全部由程序从曲线上算或按推注时间取（design 0002 决定 5、6）。
- 负责人 2026-10-16 定：MedSAM2 用最快的方式装（从远程服务器拷代码和权重）；紫圈的颜色阈值先照搬旧值，记为待定问题（`待定问题/08`）；先把关键帧和指标放进资料库，「一个患者的资料库中有 8 帧」。
- 其余做法（四处已知问题怎么改、中间文件的布局、复用的键、对外接口）是监督者 2026-10-16 提出的，负责人确认任务书时一并认可。

## 先认识几个词

- **CEUS、造影画面**：往静脉推注造影剂后连续录下的超声视频。超声机录像时屏幕左右各一半：一半是造影画面（造影剂到了就变亮），另一半是普通灰阶超声画面。哪一半是造影画面，各例不一定相同。
- **绿框**：医生在造影画面上画的病灶框，烧录在视频里。
- **紫圈**：医生用紫色轮廓圈的一块正常胰腺（003、010、012 例圈的是肝，033 例没有），用作对照（`待定问题/08`）。
- **提示帧**：绿框位置或形状明显变化的那几帧。程序把这几帧的绿框交给分割模型，告诉它「病灶在这里」。
- **MedSAM2**：医学图像分割模型（GitHub `bowang-lab/MedSAM2`），给它几帧的提示，它能把病灶轮廓传播到整段视频的每一帧。要用显卡，是整个流程里最慢的一步。
- **ROI**：最终圈出的病灶区域。**暗区**：病灶里装囊液、不进造影剂、一直发黑的部分。
- **TIC**（时间-强度曲线）：ROI 平均亮度随时间的变化，先变亮再变暗。用 Lognormal（对数正态）形状的光滑曲线去拟合它，后面的时刻和指标都在拟合出的光滑曲线上算。
- **关键帧**：B0（刚开始变亮之前）、D1（开始变亮）、D2（变亮最快）、D3（最亮）、D4（变暗最快）这 5 张从拟合曲线上取；F1、F2 是推注后第 20、60 秒。定义见 `结构.md` 第四部分「CEUS 中间文件」。
- **灌注指标**：从拟合曲线算出的 11 个数（峰值强度、达峰时间、洗入速率等），口径仿照商用造影定量软件 VueBOX。
- **`work/`**：中间文件目录，不进 git，可以删掉重算。
- **两套编号**：本任务书的「第一阶段」到「第四阶段」是你交付的四个阶段；「第 1 步」到「第 9 步」是一段视频在 CEUS 定量里依次经过的 9 步（`结构.md` 第四部分有表）：1 解码与分屏，2 找绿框、选提示帧，3 MedSAM2 分割，4 整理轮廓（平滑、与绿框融合），5 找暗区，6 TIC 采样，7 拟合，8 关键帧，9 灌注指标。
- **在哪一半上分割**：沿用旧代码。绿框画在造影那一半；造影画面里病灶边界随造影剂进出时明时暗，所以旧代码把绿框挪到灰阶那一半，让 MedSAM2 在灰阶画面上分割，再把轮廓挪回造影那一半，在造影画面上采亮度。
- **监督者**：和负责人讨论、写任务书并验收的会话；执行者是拿着这份任务书写代码的你。

## 开工前先读

- `AGENTS.md`：全部，尤其是「不设默认值」「罕见情况怎么办」「错误怎么处理」「测试」。
- `research-wiki/explanation/结构.md`：第二部分（框架图）、第三部分（ceus、segment 的职责和「几条边界」）、第四部分（「CEUS 定量的产物」的 9 步和关键帧表）、第五部分（「配置」、文件格式、导入契约）、第八部分（任务书 01 已有的接口）。
- `research-wiki/design/0002-四段流水线与两个库.md`：决定 4、5、6。
- `research-wiki/待定问题/01`（绿框在最终轮廓里占多少）、`02`（参数何时冻结）、`07`（图上的信息栏）、`08`（紫圈阈值）。这一步都不处理，只要知道它们存在、不要顺手改。
- `research-wiki/任务书/01-装配两个库.md` 和 `src/cadx/` 现有代码。
- 旧代码（只读，路径相对 `reference/CADx-4-CAD/`）：
  - `app/domain/ceus_roi/` 除 `service.py` 外的 17 个模块，约 7300 行，都不依赖数据库或 HTTP。
  - `app/providers/video_decoder.py`（视频解码）。
  - 实际跑出 40 例结果的三个脚本：`debugs/t1_local_debug.py` 做第 1–6 步，用子进程调 `debugs/medsam2_local_track.py` 做分割；`debugs/tic_lognormal_replay.py` 读轨迹，做 TIC、拟合、关键帧和指标。**迁移时以这条路径的行为为准**，`service.py` 不搬。
  - `config/ceus_roi_default.yaml`：108 个参数。
  - `tests/unit/` 下 19 个算法测试文件（约 303 个测试，全用合成数据）。

**旧测试怎么接新配置**：配置去掉默认值以后，旧测试里靠默认值构造配置的地方，改成由一个夹具读入 `config/ceus.yaml`，需要不同取值的测试用 `model_copy(update=...)` 改那一项；断言和预期值不改。

**旧脚本里的编排逻辑放哪**：两个 debug 脚本里按顺序调用各模块的那部分逻辑，收进 ceus 对外的两段接口（第二阶段「ceus 对外交出什么」）；`scripts/ceus_quant.py` 只管读配置、找病例、读写文件、分割缓存和逐例循环。

**病人资料不进任何文字**：报告、提交说明、测试、日志里只写结构和计数，不写病例号、视频号、诊断和报告原文。

## 先修任务书 01 的一处

任务书 01 的执行者报告：关键图格式不对（不是 PNG、16 位、带透明）时，`library` 抛 `ValueError`，整次构建停下。这是只落在一个病例上的问题，按 `AGENTS.md`「错误怎么处理」应该跳过这一例。

要做：

- library 提供 `check_key_image(path) -> str | None`：能原样重编码时返回 None，不能时返回原因。现在 `_write_clean_png` 里的那几条判断移到这里。
- build 在写资料库之前对每例调它，返回原因的，这一例跳过，记为 **C14**「关键图能原样重编码」，涉及值写原因。
- `_write_clean_png` 里的判断保留为断言性质的报错（走到这里说明 build 漏了检查）。
- 补测试：一例关键图带透明，这一例被跳过、记 C14、其余照常进库。
- `结构.md` 第八部分相应几行改掉。

和第一阶段一起提交，提交说明里写明。

## 第一阶段：底层和分割之前的算法

迁移以下模块到 `src/cadx/ceus/`（文件名加 `_` 前缀，对外只经 `__init__.py`）：geometry、视频解码（旧 `video_decoder.py`）、配置（旧 `research_config.py`）、split_screen、green_prompt、prompt_frames、mapping。

### 怎么迁

- 逐个模块照旧代码搬，去掉产品层的东西（数据库、settings、日志框架、`app.*` 的引用），注释和 docstring 改成中文、只写现在做什么和为什么。
- 对应的旧测试一起搬，改 import，断言和预期值不改。旧测试要是因为下面「四处要改的地方」而不再成立，删掉或改写那一条，在报告里逐条列出。
- 视频解码：旧代码先把整段视频读成字节、写临时文件，再整段读进内存。改成直接按路径用 cv2 打开、逐帧读。行为（读出的帧和时间戳）不变。`test_video_decoder` 原来要一段真实样例视频，改成在测试里用 cv2 现造一段几十帧的小视频。

### 配置

- 旧 `research_config.py` 的 22 个 pydantic 配置类搬过来，**去掉全部默认值**（旧 schema 里约 134 处），每个字段必填；`strict=True`、`extra="forbid"`、`frozen=True`，规则同 `结构.md` 第五部分「配置」。
- 新建 `config/ceus.yaml`：数值逐个照抄旧 `ceus_roi_default.yaml`。每个参数的注释写明出处：旧 yaml 注释里引的出处（临床口径契约、旧 findings、旧 design）照抄并注明「出自旧项目」；没有出处的写「旧项目工程侧定的，无出处」。不改任何数值（`待定问题/02`）。
- `ceus.yaml` 分三段：`paths`（交付包位置、`runs/` 和 `work/` 位置）、`segment`（分割设置，第二阶段加）、`ceus`（算法参数）。字段定义各归其主：`ceus` 段归 ceus，`segment` 段归 segment，最外层和 `paths` 由 `scripts/ceus_quant.py` 定义，它读整份文件、把各段交给各自的模型校验。第一阶段先只有 `paths` 和 `ceus` 两段。
- 下面「四处要改的地方」用不到的旧字段（映射锚点、`source_view`、只给 `service.py` 用的裁黑边设置、D1 取医生时刻的那个模式开关）直接删掉，不留着不用。

### 四处要改的地方

这四处在旧代码里是错的，或者在 40 例上会出问题，按下面改，各配手算预期值的测试。

1. **左右两半之间的坐标换算。** 程序要把造影画面上的绿框挪到另一半画面的同一位置。两半大小相同、只差一个水平平移，旧代码却把换算用的锚点按某一种视频宽度（1856 像素）写死成像素坐标（旧 yaml 第 45–49 行、旧 `mapping.py:91`），40 例有 5 种宽度，其余宽度会挪偏一两百像素。改成：平移量 = 目标那一半视图的左上角 − 造影那一半视图的左上角，直接用第 1 步切分出来的两个视图矩形算。测试：至少 3 种宽度，手算平移量。
2. **造影画面在哪一半。** 旧代码配置写死造影在左半（旧 yaml 第 15–16 行），013 例造影在右半，找不到绿框。改成：两半各自按旧代码的办法选提示帧（`collect_prompt_observations` + `select_prompt_frames`，参数不变），选出至少一帧就算「这一半有绿框」；恰好一半有，这一半就是造影画面；两半都找到或都找不到，这一例失败，记原因。测试：合成视频，绿框分别在左、在右、两边都有、两边都没有。
3. **D1 不用医生的时刻。** 旧关键帧代码有一个模式让 D1 直接取医生标注的造影剂到达时间（旧 `anchor_frames.py:203–206`）。这条路删掉，只保留从拟合曲线算 D1（design 0002 决定 6）。
4. **推注时间的换算。** X 是超声报告表的「推注开始时间s」，含义是视频第 0 秒时已经推注了 X 秒。F1 取视频第 20 − X 秒，F2 取第 60 − X 秒，取帧的容差窗口照旧 `anchor_frames` 段对 F1、F2 的设置；落在视频之外（小于 0 或超过视频末尾），这一帧记为未定位，写明原因，不拿别的帧补（`结构.md` 第四部分）。旧代码按「推注发生在视频第 X 秒」处理（旧 `anchor_frames.py:204` 的符号），要改。测试手算：X = 7 时 F1 在第 13 秒、F2 在第 53 秒；X = 25 时 F1 在第 −5 秒，未定位。

另有两处旧 debug 路径和 `service.py` 不一样，**按 debug 路径**，因为 40 例的结果是它跑出来的：不裁画面黑边；找分屏线只用均匀抽的 25 帧。

### 收尾点

上面的模块和测试都搬完，`make check` 通过，提交。

## 第二阶段：分割和后半段算法

### MedSAM2

- 从远程服务器拷代码和权重（ssh/rsync 一律走 `wangwenhan@202.38.247.58`，见 `AGENTS.md`「本机环境的坑」）：
  - 代码：远程 `/home/wangwenhan/MedSAM2/`，排除 `checkpoints/` 和 `data/`（约 25MB），连同 `.git` 一起拷到本机 `reference/MedSAM2/`，提交号从这个 `.git` 读出，不写死。它是 GitHub `bowang-lab/MedSAM2` 的 332f30d 提交，远程只改了 `download.sh`，不影响代码。
  - 权重：只拷 `checkpoints/MedSAM2_latest.pt`（约 156MB）到本机 `models/MedSAM2_latest.pt`。
- 用 `SAM2_BUILD_CUDA=0 uv add --editable reference/MedSAM2` 装进项目环境（不编译 CUDA 扩展；旧项目也没用它）。装完确认 torch 能看到本机显卡。`guides/开发环境.md` 写明这几步，下一个人在新机器上照着就能装好。
- segment 模块（`src/cadx/segment/`）：从旧 `medsam2_local_track.py` 改写，**在同一进程里调用**，不再开子进程和 conda 环境。对外一个函数：输入逐帧图像（只是要分割的那一半画面）、若干提示帧的病灶掩码、分割设置，输出每一帧的病灶掩码。它不认识分屏和绿框（`结构.md` 第三部分）。MedSAM2 要求帧以 jpg 文件放在一个目录里，临时目录由 segment 自己建、自己删。
- 分割设置（权重路径、模型配置路径、设备、旧脚本里的两个 offload 开关）写进 `ceus.yaml` 的 `segment` 段，字段定义在 segment 里，全部必填。权重路径不写死在代码里。
- 导入契约：`cadx` 里只有 segment 能引用 `torch`、`sam2`（改 `pyproject.toml` 里现有那条）。

### 其余模块

迁移 polygons、dark_region、reference_region、tic_fitting、tic、anchor_frames、perfusion_metrics、trajectory、tic_curves、tic_plot、overlay，旧测试一起搬，做法同第一阶段。

- 绿框在最终轮廓里的融合权重（旧 `roi_shape` 段）照搬，写在 `ceus.yaml` 里（`待定问题/01`）。
- 紫圈的颜色阈值（旧 `pan_source` 段）照搬（`待定问题/08`）。
- 关键帧各时刻的容差窗口，逐个核对出处，写进 `ceus.yaml` 的注释（`结构.md` 第四部分）。

### ceus 对外交出什么

ceus 不能引用 segment（`结构.md` 第三部分依赖表），所以分两段对外：

1. 第一段：输入视频路径和参数，做第 1–2 步，交出分屏结果、哪一半是造影画面、要交给分割的那一半的逐帧图像，以及提示帧的掩码。
2. 第二段：输入第一段的结果、分割得到的逐帧掩码、推注时间 X 和参数，做第 4–9 步，交出轨迹、TIC 曲线、拟合、7 个关键帧的定位结果、灌注指标。

两段中间由 `scripts/ceus_quant.py` 调 segment。具体类型由执行者定，写进 `结构.md` 第八部分。

### 收尾点

全部模块和测试搬完，`make check` 通过。另写一条标 `gpu` 的测试：在一段合成小视频上真的调一次 MedSAM2，输出掩码的帧数和尺寸对。跑通后提交。

## 第三阶段：`scripts/ceus_quant.py`，跑全部病例

### 跑哪些病例

用 delivery 读交付包，跑**检查全部通过的病例**（目前 34 例）。C14（关键图）在 build 时才查，被它跳过的病例 CEUS 照跑，build 时不用就是了。医生改完数据重新交付后，再跑一次。

delivery 的 `CaseRecord` 目前没有视频路径和推注时间，加上这两项（C04、C08 已经检查过它们）。

### 输出

CEUS 的结果会进资料库，最终可能写进论文，按 `AGENTS.md` 硬性约束 5 要能追到一次真跑的原始记录，所以每次运行放在 `runs/ceus/` 下、只追加不删；只有能重算的分割缓存放 `work/`。

```
runs/
  ceus/<运行号>/
    snapshot/                快照：git 状态、ceus.yaml 原文、权重文件的 SHA-256、MedSAM2 的提交号
    failed.csv               失败的病例：视频号、失败在第几步、原因
    <视频号>/
      trajectory.npz         逐帧轮廓（格式同旧 trajectory.py）
      tic_curves.npz         曲线（格式同旧 tic_curves.py）
      summary.json           拟合结果、灌注指标、紫圈检出率、7 个关键帧的定位（帧号、视频时间、状态、未定位的原因）
      tic.png                曲线图，标出 D1–D4
      overlay.mp4            带轮廓的回放视频，供人目视检查
      keyframes/<槽位>.png   定位到的关键帧，B0、D1……F2，未定位的槽位没有文件
work/
  segment_cache/<键>/masks.npz
```

- 运行号的格式同构建号（用 runs 的 `make_build_id`）。运行目录先写成 `.partial`，跑完再改名，已存在就报错，规则同任务书 01。
- 关键帧图是该帧的**整幅原始画面**（左右两半都在），不裁剪。给超声专家时裁不裁、怎么遮信息栏，留给会诊任务书（`待定问题/07`）。
- 只有分割结果跨运行复用（`结构.md` 第四部分）。键是下面几样拼起来的 SHA-256：视频文件的 SHA-256、第 1–3 步用到的全部算法参数（规范化成 JSON；不含设备和两个 offload 开关，它们不改变结果）、权重文件的 SHA-256、MedSAM2 的提交号（从 `reference/MedSAM2/.git` 读）。键相同就直接读缓存，不调显卡。缓存目录也是先写 `.partial` 再改名。
- 某一例在第 1–6 步失败（包括第一阶段第 2 条的「两半都有或都没有绿框」、选不出提示帧），这一例记进 `failed.csv`、接着跑下一例，和交付资料的问题同一个规矩（`AGENTS.md`「错误怎么处理」）。拟合没过质量门不算失败：D1–D4 记为未定位、灌注指标写 null，原因写进 `summary.json`，F1、F2 照常按推注时间取。个别关键帧槽位未定位也不算失败。
- 终端只打印计数：总例数、成功数、按步分的失败数、关键帧按槽位分的定位数、耗时。不打印视频号。

`scripts/ceus_quant.py` 只接收 `--config config/ceus.yaml`。全部病例要跑一阵子，放进 tmux，日志写到文件。

### 收尾点

在本机跑完全部病例，提交代码（`runs/`、`work/` 不进 git）。

## 第四阶段：build 装入 CEUS 结果

- `build.yaml` 加一个必填字段 `ceus_run`：某次 CEUS 运行目录的路径，或者 null（不装 CEUS 结果，就是现在的情况）。
- 不为 null 时，build 按视频号找到每例的 CEUS 结果。这一例在 `failed.csv` 里或者找不到结果目录，这一例跳过，记为 **C15**「CEUS 定量结果齐全」，涉及值写失败阶段和原因。CEUS 失败的病例要不要改成「超声不可评价、仍参与会诊」，等 `待定问题/03` 定，这一步按跳过处理。
- 资料库超声一路加：
  - `ultrasound/keyframes/<槽位>.png`：定位到的关键帧，经 library 去掉附加数据重新编码（同 `key.png`）。加上原有的 `key.png`，每例最多 8 张图。
  - `ultrasound/tic.json`：从 `summary.json` 里只挑这几样，此外什么都不写：旧 `tic.py` 四条曲线（病灶整体、病灶去暗区、紫圈、背景圆）各自的拟合是否成功和拟合优度；灌注指标（同旧 replay `summary.json` 的 `perfusion_metrics` 段）；紫圈曲线是否可用；7 个槽位各自定位到没有，定位到的写视频时间（秒），未定位的写原因。视频号、文件路径、配置、帧号都不写。
- 资料库 `manifest.json` 的 CEUS 来源字段写 CEUS 运行号。
- 泄露扫描的禁词表加上视频文件名；扫描范围加上 `tic.json`。
- 用 `ceus_run` 指向第三阶段的那次运行，重新构建一次真实资料库，跑 `scripts/scan_library.py`。

### 收尾点

测试通过、真实构建和扫描跑完，提交。

## 测试

预期值照本任务书文字和旧测试写，不从新实现里推。

- 第一阶段的四处修改：各条手算测试，见上文。
- 旧测试：19 个文件中的 18 个（`test_tic_lognormal_replay` 不搬，它测的是旧 replay 脚本读标注工作簿的逻辑，第 3、4 条修改后不再适用）。conftest 里设产品层环境变量的那个夹具不搬。
- segment：一条 `gpu` 测试（第二阶段收尾点）。
- 分割缓存：同样的输入第二次运行不调 segment（用 pytest 的 monkeypatch 把脚本里用到的 segment 函数换成计数的假函数，不为测试加参数）；改一个第 1–3 步的参数，键就变。
- `ceus_quant`：合成的两例小视频，一例正常、一例两半都没有绿框，后者进 `failed.csv`，前者有完整输出。
- build：C15 跳过；`tic.json` 只有上面列的几样；keyframes 的附加数据被去掉。

## 规模

| 模块 | 预期行数 |
| --- | --- |
| ceus | 6000–7500（照搬旧算法，去掉产品层） |
| segment | 150–300 |
| `scripts/ceus_quant.py` | ≤ 300 |
| delivery、library、build 的增量 | 各 ≤ 150 |

超过区间上限的两倍就停下检查。完成后更新：`结构.md` 第六部分实际行数、第八部分 ceus 和 segment 的对外接口；`guides/开发环境.md`（MedSAM2 怎么装）；新写 `guides/CEUS定量.md`（怎么跑、产物在哪、怎么看 `failed.csv` 和 `overlay.mp4`，过一轮「硕士生阅读」）；`WORK_LOG.md`。

## 审阅

- 这一步大部分是「其余部分」那一档（`AGENTS.md`「两档标准」），写完派一个全新上下文的子 Agent 审阅：只给它本任务书、`结构.md` 第三到第五部分和 diff，让它重点看「四处要改的地方」是否改对、迁移有没有漏掉旧代码里的分支、关键帧和指标有没有算错。
- 第四阶段改的是资料库（决定专家能看见什么），属于账本级，另派一个全新上下文的子 Agent 单独审这部分，找：CEUS 结果里有没有带进视频号、文件名、医生的判断；CEUS 失败的病例有没有进库。
- Codex 可用时再加一轮对抗审查（`/codex:rescue --fresh --wait`）。
- 意见的处理同任务书 01。子 Agent 的 prompt 里写明本机 `grep`、`find` 用 `/usr/bin/` 下的版本。

## 报告

四个阶段都完成后，在回复里交一份报告。已验证的事实、推断、未验证的部分分开写。

1. 四个提交号；各模块行数。
2. `make check` 的完整输出；`gpu` 测试的输出。
3. 旧测试：搬了多少条，删改了哪些、为什么。
4. 真实运行：运行号、跑了几例、成功几例、按步分的失败数、关键帧按槽位分的定位数、总耗时和显存峰值。
5. **紫圈检出率**：每例一个数（有多少比例的帧认出了紫圈），只报分布（最小、四分位、最大），以及低于 50% 的有几例。给 `待定问题/08` 用。
6. **请负责人目视检查的样例**：挑 3 例 `overlay.mp4` 和 `tic.png` 的路径（成功、关键帧缺槽位、紫圈检出率最低的各一例），只给路径不描述内容。
7. 重新构建的资料库：构建号、进库数、C15 跳过数、扫描结果。
8. 审阅意见和处理。
9. 和本任务书、`结构.md`、`AGENTS.md` 不一致的地方，以及为什么。
10. 规则不清楚的地方：哪里犹豫、哪里靠猜。没有就写「没有」。