# iWorld-Bench (/zh/docs/evaluation/benchmark-hub/iworld-bench)



## 简介 [#简介]

iWorld-Bench 把 camera-controllable video generation model 当作 interactive world model 来评测。它不是通用视频美学 benchmark：模型不仅要生成好看的视频，还要响应 action 或 camera control，并在回到同一位置时保持场景记忆。

官方 release 提供 evaluation code、packaged metadata、camera trajectory resources、first-frame assets 和 reference inference adapters。WorldFoundry 已把评测代码集成在仓内：`worldfoundry/evaluation/tasks/execution/runners/iworldbench/`，因此 WorldFoundry 测评不需要额外准备官方源码 checkout。

## Benchmark 设计 [#benchmark-设计]

| 任务类型               | 说明                                    | 任务数   |
| ------------------ | ------------------------------------- | ----- |
| Action control D=1 | 静止 + 9 个基础平移/旋转动作                     | 1,000 |
| Action control D=2 | 二自由度组合动作                              | 1,000 |
| Action control D=3 | 三自由度组合动作                              | 1,000 |
| Action control D=4 | 四自由度复杂动作                              | 1,000 |
| Memory ability     | 需要 loop-closure 记忆的循环 reciprocal path | 200   |
| Camera following   | 基于 camera parameter 文件的轨迹跟随           | 700   |

项目从 330K video clips 筛选到 2.1K 高质量样本，并通过统一动作接口 `Ct = [D, T, R, V]`（difficulty、translation ID、rotation ID、validity）生成 4.9K 测试任务。

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

* Paper: [arXiv:2605.03941](https://arxiv.org/abs/2605.03941)
* Project page: [iworld-bench.com](https://iworld-bench.com/)
* 官方源码参考: [github.com/EmbodiedCity/iWorld-Bench](https://github.com/EmbodiedCity/iWorld-Bench)
* 数据集: [EmbodiedCity/iWorld-Bench-Dataset](https://huggingface.co/datasets/EmbodiedCity/iWorld-Bench-Dataset)
* 仓内 runner: `worldfoundry/evaluation/tasks/execution/runners/iworldbench/run_iworldbench_official_runner.py`

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

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

下载 packaged metadata、first-frame assets 和 camera-following metadata：

```bash
export WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT=/path/to/datasets/iWorld-Bench-Dataset

hf download EmbodiedCity/iWorld-Bench-Dataset \
  --repo-type dataset \
  --include "dataset/all_pack/**" \
  --local-dir "${WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT}"
```

期望目录：

```text
${WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT}/
`-- dataset/all_pack/
    |-- metadata.csv
    |-- camera_following_metadata.csv
    `-- assets/
```

`metadata.csv` 用于 Diff/action-control 和 Mem/memory 任务。`camera_following_metadata.csv` 只用于 trajectory-input 模型。

### 生成视频 [#生成视频]

先用你要评测的模型生成视频，再运行 scorer。可以使用 WorldFoundry 模型、API batch job 或自己的 runner，只要输出视频能和 iWorld-Bench metadata 行对应即可。

建议每个 track 一个目录：

```text
/path/to/iworld/generated/
|-- action_control/
|   |-- <prompt_id>.mp4
|   `-- ...
|-- memory_ability/
|   |-- <prompt_id>.mp4
|   `-- ...
`-- camera_following/
    |-- <prompt_id>.mp4
    `-- ...
```

视频文件 stem 应该匹配 metadata 中的 `prompt_id` / sample id。如果你的生成器使用 CSV 里的其他 official video name，就保留该文件名，并在评测时传同一份 metadata 文件。

### Metric 资产 [#metric-资产]

仓内 runtime 会复用 WorldFoundry 的 VBench 和 VIPe 相关代码路径。真实打分时显式设置 official backend，并把 VIPe 指向仓内 base-model package 或兼容的本地 package：

```bash
export WORLDFOUNDRY_IWORLD_BENCH_RUNTIME_BACKEND=official
export VIPE_ROOT="${VIPE_ROOT:-$PWD/worldfoundry/base_models/three_dimensions/general_3d/vipe}"
export CUDA_VISIBLE_DEVICES="${CUDA_VISIBLE_DEVICES:-0}"
```

不要用默认 mock backend 报告结果。它只用于本地链路联通，不是可报告分数。

## 指标 [#指标]

| Metric                         | 分组                   | 含义                                      |
| ------------------------------ | -------------------- | --------------------------------------- |
| `image_quality`                | Generation quality   | 基于 VBench/MUSIQ 的帧级质量。                  |
| `brightness_consistency`       | Generation quality   | 视频亮度的时序稳定性。                             |
| `color_temperature_constraint` | Generation quality   | 色相与白平衡是否稳定。                             |
| `sharpness_retention`          | Generation quality   | 细节保持，避免模糊和高频伪影。                         |
| `motion_smoothness`            | Trajectory following | 基于 VBench 的运动平滑性。                       |
| `trajectory_accuracy`          | Trajectory following | VIPe 估计 camera path 与指令是否一致。            |
| `trajectory_tolerance`         | Trajectory following | 相对 reference trajectory NPZ 的鲁棒性。       |
| `memory_symmetry`              | Memory ability       | 往返路径中的 loop-closure 一致性。                |
| `trajectory_alignment`         | Memory ability       | Memory task 中双向 camera trajectory 的一致性。 |
| `iworldbench_average`          | Aggregate            | 可用官方组件指标的平均值。                           |

## 复现 Leaderboard 形态的评测 [#复现-leaderboard-形态的评测]

对每个官方 track 分别评测对应生成视频。direct runner 是最清楚的入口，因为它同时暴露 task split 和 metric selector。

### Action Control / Diff [#action-control--diff]

```bash
export WORLDFOUNDRY_IWORLD_BENCH_ACTION_DIR=/path/to/iworld/generated/action_control

PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/iworldbench/run_iworldbench_official_runner.py \
  --run-official \
  --generated-videos-dir "${WORLDFOUNDRY_IWORLD_BENCH_ACTION_DIR}" \
  --prompt-manifest "${WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT}/dataset/all_pack/metadata.csv" \
  --split diff \
  --metric action_control \
  --output-dir tmp/iworld-bench/action-control \
  --json
```

### Memory Ability / Mem [#memory-ability--mem]

```bash
export WORLDFOUNDRY_IWORLD_BENCH_MEMORY_DIR=/path/to/iworld/generated/memory_ability

PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/iworldbench/run_iworldbench_official_runner.py \
  --run-official \
  --generated-videos-dir "${WORLDFOUNDRY_IWORLD_BENCH_MEMORY_DIR}" \
  --prompt-manifest "${WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT}/dataset/all_pack/metadata.csv" \
  --split mem \
  --metric memory_ability \
  --output-dir tmp/iworld-bench/memory-ability \
  --json
```

### Camera Following [#camera-following]

```bash
export WORLDFOUNDRY_IWORLD_BENCH_CAMERA_DIR=/path/to/iworld/generated/camera_following

PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/iworldbench/run_iworldbench_official_runner.py \
  --run-official \
  --generated-videos-dir "${WORLDFOUNDRY_IWORLD_BENCH_CAMERA_DIR}" \
  --prompt-manifest "${WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT}/dataset/all_pack/camera_following_metadata.csv" \
  --split camera_following \
  --metric camera_following \
  --output-dir tmp/iworld-bench/camera-following \
  --json
```

如果要声明 public leaderboard 级别结果，需要保存每个 reported track 的生成视频、scorecard，以及各输出目录下的原始 `reports/` CSV。

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

公开 CLI 适合跑单个 track。请显式传环境覆盖，确保使用真实 evaluator：

```bash
worldfoundry-eval zoo benchmark-run \
  --benchmark-id iworld-bench \
  --mode official-run \
  --generated-artifact-dir "${WORLDFOUNDRY_IWORLD_BENCH_ACTION_DIR}" \
  --env WORLDFOUNDRY_IWORLD_BENCH_RUNTIME_BACKEND=official \
  --env WORLDFOUNDRY_IWORLD_BENCH_METRIC=action_control \
  --env WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT="${WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT}" \
  --output-dir tmp/iworld-bench/action-control-cli \
  --json
```

Memory 和 camera-following 需要显式 `--split`，因此建议使用 direct runner。公开 CLI 对部分 benchmark 有全局 `--prompt-manifest` 选项，但 iWorld-Bench 的 split 选择用 direct runner 更清楚，也更不容易传错。

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

如果你已经有 iWorld-Bench report CSV 或 `reports/` 目录，可以导入成 WorldFoundry scorecard：

```bash
PYTHONPATH=. "${WORLDFOUNDRY_UNIFIED_PYTHON:-python}" \
  worldfoundry/evaluation/tasks/execution/runners/iworldbench/run_iworldbench_official_runner.py \
  --official-results-path /path/to/iworld/reports \
  --generated-videos-dir /path/to/iworld/generated/action_control \
  --prompt-manifest "${WORLDFOUNDRY_IWORLD_BENCH_DATASET_ROOT}/dataset/all_pack/metadata.csv" \
  --split diff \
  --output-dir tmp/iworld-bench/imported \
  --json
```

## 输出 [#输出]

每次运行会写出：

* `scorecard.json`
* `raw_metric_table.jsonl`
* 执行 official backend 时的 `upstream_command.json`
* 输出目录下的 upstream `reports/*.csv`

优先查看 `scorecard.json`。只有 requested split 视频覆盖完整，并且该 metric family 需要的资产都可用时，结果才适合和 public leaderboard 对比。

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