# SAM 2 视频抠像教程

用三秒原创玩具移动片，在首帧给一个正点，导出36张有序mask，再核对蒙版数量、尺寸与原视频时间轴。SAM 2负责分割，不会为你生成新视频。

## 执行范围

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

## 步骤

### 1. 先看原片，再固定帧率与点位

打开 input.mp4，确认只有一只纹理玩具横向移动。输入是 Blender 实际渲染的36帧、12fps练习片，不是SAM输出；先播放首尾，再用 input-manifest.json 记录宽高、时长与来源。

### 2. 准备视频预测器与已下载的官方小模型

按官方安装要求准备隔离环境；配置文件和checkpoint必须同为SAM 2.1对应规格。本题脚本默认sam2.1_hiera_s.yaml，checkpoint要由你显式提供本地文件，不自动下载权重。

### 3. 抽成从零开始的数字JPEG序列

运行 extract-frames.sh，frames/00000.jpg 对应原视频第0帧。官方视频示例使用数字帧名排序；不用文件修改时间排序，不把036当成第36秒。先数清36个JPEG，再开始推理。

### 4. 在首帧为目标添加一个正点

打开 point-prompts.png，人工确认标点在玩具主体内部，再检查prompts.json中的像素坐标。脚本将其以obj_id=1传给add_new_points_or_box。点到背景时先修坐标，不把空蒙版当成“自动识别成功”。

### 5. 传播并逐帧保存模型返回的mask

run-sam-video.py将logits>0转为0/255 PNG，并保留模型返回的frame_idx与object_id。实际结果写入全新actual-sam-output/baseline/object-1，不覆盖原片，也不会把原始几何参考复制成模型输出。

### 6. 对齐首、中、末帧再做合成

检查00000、00018、00035的目标位置、脚部和天线；确认每张mask与640×360原帧一致。数量正确只说明文件齐全，边缘、漏选和背景污染仍需叠加回原片逐段看。

### 7. 保存真实结果与未通过的帧号

运行verify.py检查练习包，再把你实际的模型版本、运行设备和失败帧填入review.csv。runtime.json初始为not-executed；只有自己完成推理后，才另存实际运行记录。

## 命令

```bash
bash extract-frames.sh
python run-sam-video.py --frames frames --checkpoint /path/to/sam2.1_hiera_small.pt --mode single --out actual-sam-single
```

## 参考文件

- 以“本题实际文件”列表为准：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`
- `review.csv`
- `run-sam-video.py`
- `runtime.json`
- `verify.py`

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