# CameraBench (/zh/docs/evaluation/benchmark-hub/camerabench)



## 简介 [#简介]

CameraBench 评估视频模型是否真正理解相机运动，而不是只生成视觉上好看的片段。它关注 pan、tilt、roll、zoom、tracking、follow 等运动，并判断生成或检索到的视频是否匹配目标相机行为。

该 benchmark 来自 CameraBench 项目与论文 "Towards Understanding Camera Motions in Any Video"。公开版本包含 Hugging Face 上的 test split，以及用于相机运动判断的 fine-tuned Qwen2.5-VL 模型。WorldFoundry 不要求用户获取外部源码树：结果导入和指标聚合代码已经在仓内，路径是 `worldfoundry/evaluation/tasks/execution/runners/camerabench/`。

当前 WorldFoundry 覆盖的是可复现的聚合阶段。你需要提供官方 CameraBench 结果 JSON，或者已经生成好的 CameraBench `score_dir`，WorldFoundry 会输出统一的 scorecard。从视频生成原始 CameraBench score JSON 仍需要准备 CameraBench scorer 资产和下面列出的 fine-tuned VLM checkpoint。

## 官方参考 [#官方参考]

| 资源        | 链接                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------ |
| 项目页       | [linzhiqiu.github.io/papers/camerabench](https://linzhiqiu.github.io/papers/camerabench/)        |
| 论文        | [arXiv:2504.15376](https://arxiv.org/abs/2504.15376)                                             |
| GitHub    | [github.com/sy77777en/CameraBench](https://github.com/sy77777en/CameraBench)                     |
| HF 数据集    | [syCen/CameraBench](https://huggingface.co/datasets/syCen/CameraBench)                           |
| 仓内 runner | `worldfoundry/evaluation/tasks/execution/runners/camerabench/run_camerabench_official_runner.py` |

## 需要准备什么 [#需要准备什么]

### 数据集 [#数据集]

从 Hugging Face 下载公开测试资产：

```bash
hf download syCen/CameraBench \
  --repo-type dataset \
  --local-dir /path/to/datasets/CameraBench
```

本地根目录应包含测试元数据和视频资产：

```text
/path/to/datasets/CameraBench/
|-- test.jsonl
`-- videos_gif/
    |-- *.gif
    `-- ...
```

运行时通过 `WORLDFOUNDRY_CAMERABENCH_DATA_ROOT` 或 `--benchmark-data-root` 指向这个目录。

### Scorer Checkpoint [#scorer-checkpoint]

CameraBench 报告使用 fine-tuned Qwen2.5-VL camera-motion 模型。把 checkpoint 下载到你的模型缓存或共享 checkpoint 目录：

```bash
hf download chancharikm/qwen2.5-vl-7b-cam-motion  --local-dir /path/to/checkpoints/qwen2.5-vl-7b-cam-motion
hf download chancharikm/qwen2.5-vl-32b-cam-motion --local-dir /path/to/checkpoints/qwen2.5-vl-32b-cam-motion
hf download chancharikm/qwen2.5-vl-72b-cam-motion --local-dir /path/to/checkpoints/qwen2.5-vl-72b-cam-motion
```

WorldFoundry 的 `worldfoundry/base_models/` 中已经有可复用的 Qwen/VQAScore 基础设施。checkpoint 建议放在源码树外，除非你正在制作本地发布包。

### Score Directory [#score-directory]

仓内 CameraBench runner 消费已经准备好的 JSON score 文件。文件名应符合：

```text
/path/to/camerabench/score_dir/
|-- classification_scores_*.json
|-- vqa_retrieval_scores_*.json
`-- caption_results_*.json
```

每个文件需要包含顶层 `scores` list，可选 `metadata` 字段包括 `model_name`、`checkpoint`、`split_name`。这些文件对应官方 CameraBench 的三个指标族：二分类相机运动判断、VQA/retrieval、caption matching。

## 运行评测 [#运行评测]

### 聚合已经准备好的 Score Directory [#聚合已经准备好的-score-directory]

```bash
export WORLDFOUNDRY_CAMERABENCH_DATA_ROOT=/path/to/datasets/CameraBench
export WORLDFOUNDRY_CAMERABENCH_SCORE_DIR=/path/to/camerabench/score_dir

PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/camerabench/run_camerabench_official_runner.py \
  --score-dir "${WORLDFOUNDRY_CAMERABENCH_SCORE_DIR}" \
  --benchmark-data-root "${WORLDFOUNDRY_CAMERABENCH_DATA_ROOT}" \
  --task all \
  --mode both \
  --output-dir tmp/camerabench/score-dir \
  --json
```

只跑部分指标时，把 `--task` 改成 `binary`、`vqa_retrieval` 或 `caption`。Caption matching 如果要用 API-backed judge，可以传 `--openai-api-key "$OPENAI_API_KEY"`；如果你的本地复现只覆盖 binary 和 VQA/retrieval，可以不跑 caption。

### 使用公开 CLI [#使用公开-cli]

```bash
worldfoundry-eval zoo benchmark-run \
  --benchmark-id camerabench \
  --mode official-validation \
  --score-dir "${WORLDFOUNDRY_CAMERABENCH_SCORE_DIR}" \
  --benchmark-data-root "${WORLDFOUNDRY_CAMERABENCH_DATA_ROOT}" \
  --output-dir tmp/camerabench/score-dir-cli \
  --json
```

### 导入已有官方结果 [#导入已有官方结果]

```bash
worldfoundry-eval zoo benchmark-run \
  --benchmark-id camerabench \
  --mode official-validation \
  --official-results-path /path/to/camerabench_results.json \
  --benchmark-data-root "${WORLDFOUNDRY_CAMERABENCH_DATA_ROOT}" \
  --output-dir tmp/camerabench/imported \
  --json
```

当你已经有一次 CameraBench 评测输出的 JSON，只需要把它转换成 WorldFoundry 统一 scorecard 时，使用这个路径。

## 指标 [#指标]

| Metric                            | 含义                                                    |
| --------------------------------- | ----------------------------------------------------- |
| `camera_motion_average_precision` | 二分类相机运动判断的 mean average precision。                    |
| `camera_motion_roc_auc`           | 二分类相机运动判断的 ROC-AUC。                                   |
| `camera_vqa_accuracy`             | CameraBench yes/no 与 question-level VQA accuracy 的平均。 |
| `camera_retrieval_accuracy`       | text、image、group retrieval accuracy 的平均。              |
| `camera_caption_score`            | 已准备 CameraBench caption 输出中的 caption agreement 分数。    |
| `camerabench_average`             | 可用 CameraBench 指标族的平均值。                               |

## 输出 [#输出]

runner 会写出：

* `scorecard.json`
* `camera_predictions.jsonl`
* `raw_metric_table.jsonl`
* `upstream_stdout.log`
* `upstream_stderr.log`

如果要做 leaderboard 级别复现，需要确认本地 dataset root 覆盖完整 test split，并且 score directory 包含你要报告的全部指标族。

[返回 Benchmark Hub](/zh/docs/evaluation/benchmark-hub)