# SAM 2 多对象跟踪教程

给两只同形纹理玩具分别分配稳定object_id，观察交叉时身份是否互换，再导出两路独立蒙版，适合视频多人分别抠像的练习。

## 执行范围

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

## 步骤

### 1. 先给两个实体建立身份表

播放input.mp4，确认ID 1在首帧画面右侧、ID 2在首帧画面左侧，两者随后交叉；ID 2略在后方。ID 1与ID 2是你给实体的稳定编号，不是模型识别人名，也不应每帧按左右位置重新编号。

### 2. 用官方多对象视频状态处理一段视频

复用一个inference_state，在同一个视频状态里添加两组提示。本题使用SAM 2.1小模型配置；不要每个对象重新打开视频后再凭文件夹名称猜对应关系。官方图是项目数据示例，非本次预测。

### 3. 为每个obj_id检查独立的正点

prompts.json列出两个objects；对照point-prompts.png确认每点落在对应实体。两只物体交叠时，首帧只要彼此可见即可建立ID；点位不能复用同一个像素后期待自动分开。

### 4. 使用multi模式传播两条对象轨

脚本把每帧返回的object_ids和logits逐一配对，再分别写object-1与object-2。用模型返回ID寻址，不按数组第0项永远代表左边物体，也不把两份相同mask重命名成两轨。

### 5. 重点回看相交与前后遮挡区

打开第18帧对应的两张实际mask并叠回原图。核对首帧指定的ID 1/ID 2对应实体，检查被遮挡部分是否被错误补成另一个实体；区域被遮住不等于可以擅自画出不可见结构。

### 6. 分开统计完整性与身份一致性

每路应有36张640×360蒙版；run.json保存每帧对象ID和面积。面积突变、两路完全相同、两路大面积重叠都是待检查信号，不凭数量通过就认定跟踪正确。

### 7. 交付两路原始mask及身份说明

保留原片、prompts、模型配置、两路mask和review.csv。若交叉帧身份交换，标记失败并进入补点修正，不在导出时交换文件夹名称来掩盖错误。

## 命令

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

## 参考文件

- 以“本题实际文件”列表为准：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类入口首次运行可能拉取大权重，本轮没有执行。