# SAM 2 遮挡补点教程

用玩具经过不透明箱体的原创短片练习补点。先保留真实首轮结果，找出你实际失败的帧，再加正负点并比较相邻帧；不会预造一次必然失败的模型结果。

## 执行范围

已执行：Blender 5.2.1原创几何、真实相机渲染、UV展开、CPU手工材质烘焙、GLB/OBJ导出重载；本题附带离线检查。未执行：目标项目模型下载/推理、Gradio运行、生成纹理/深度/视频mask。reference、geometry-reference、original命名文件都是原创输入或手工参考，绝非模型结果。官方图片只在网页按来源引用。

## 步骤

### 1. 看清遮挡发生在什么时间

原片中箱体处于玩具与相机之间；物体短暂不可见后重新出现。查看input-00018.png和input-00035.png，只把可见范围作为验收对象，不要求mask穿过不透明箱子画出隐藏玩具。

### 2. 先运行single基线，不提前声称模型失败

用同一checkpoint运行single，保存baseline/object-1。官方Notebook展示后续修正机制，但本机没有运行SAM模型；练习中是否跟丢，必须由你实际看到的mask决定。

### 3. 定位首个需要修正的真实帧

逐帧叠加原图和baseline，记录漏选或包含箱子的确切frame_idx。若首轮已经通过，就如实记录，不人为移动mask来制造“修复前”。

### 4. 把补点写入同一个对象ID

编辑prompts.json.refinement。示例frame_idx=28和点位仅是待调整的人工输入；把正点放可见目标内部，负点放误选的箱体上，labels分别为1和0，保持obj_id=1不变。

### 5. 从修正帧分别向后和反向传播

refine模式先保留baseline，再向同一state添加修正提示；随后从该帧传播到结尾，并用reverse=True回看前面帧。结果另存refined，不覆盖首轮证据。

### 6. 检查修正有没有破坏邻帧

比较真实失败帧、前后一帧和重新出现后的片段。补点可能改善一个区域却破坏另一个区域；如果前后结果没有变，也要如实记录，不能仅凭再次输出了文件就称修复。

### 7. 保存前后两套结果与点位

把失败帧截图、原始点位、修正点位、baseline和refined一起留存。下载包提供原创遮挡输入与脚本；未提供任何伪造的SAM错误或成功mask。

## 命令

```bash
bash extract-frames.sh
python run-sam-video.py --frames frames --checkpoint /path/to/sam2.1_hiera_small.pt --mode single --out actual-occlusion-baseline
# 回看结果并编辑prompts.json的refinement，再使用新输出目录
python run-sam-video.py --frames frames --checkpoint /path/to/sam2.1_hiera_small.pt --mode refine --out actual-occlusion-refined
```

## 参考文件

- 以“本题实际文件”列表为准：original-toy.png或front.png/views为Blender原创输入。
- 若本包含reference-colored.glb：它是手工材质参考。
- 若本包含reference-textured.obj/MTL/PNG：它们是Blender真实UV/烘焙交换文件。
- 若本包含geometry-reference-depth.npy/PLY：它们是原创场景已知几何，非深度模型预测。
- runtime.json：目标模型初始not-executed。
- verification.json / blender-reload.json：文件及重载证据，不是模型生成证据。

## 官方依据

https://github.com/facebookresearch/sam2
https://github.com/facebookresearch/sam2/blob/main/notebooks/video_predictor_example.ipynb

## 本题实际文件

- `blender-reload.json`
- `commands.md`
- `extract-frames.sh`
- `helper-checks.json`
- `input-00000.png`
- `input-00018.png`
- `input-00035.png`
- `input-manifest.json`
- `input.mp4`
- `original-toy.png`
- `point-prompts.png`
- `prompts-verified.json`
- `prompts.json`
- `refinement-input-example.png`
- `review.csv`
- `run-sam-video.py`
- `runtime.json`
- `verify.py`

模型命令仅供在你准备好的官方环境执行；from_pretrained类入口首次运行可能拉取大权重，本轮没有执行。