haoyi-duan/WorldScore

📚 什麼是 WorldScore？

WorldScore 是一個開源的 基準測試，用於評估 世界生成 模型——即從文字或影像生成 3D 場景、4D 空間-時間世界或影片的系統。它提供：

• 精選資料集（WorldScore‑Dataset）：初始場景與相機移動指令。
• 參考實作：用於下載資料、使用任何模型生成影片，以及執行一系列空間-時間指標的程式碼。
• 公開排行榜（托管於 HuggingFace）：研究人員可提交自己的分數。

此專案配合 ICCV‑2025 論文《WorldScore: A Unified Evaluation Benchmark for World Generation》，旨在提供一個單一數值，反映模型在 擴展 世界與遵循相機路徑方面的能力——這正是現有影片品質基準所忽略的面向。

---

🚀 快速入門（高階步驟）

1. 克隆與設定 – 在 .env 檔案中設定 WORLDSCORE_PATH、MODEL_PATH 和 DATA_PATH。
2. 安裝 – 建立 conda 環境（Python 3.10），執行 pip install -e . 並安裝大量相依性（PyTorch 2.5、DROID‑SLAM、Grounding‑SAM、SAM‑2、VFIMamba 等）。
3. 下載資料集 – 執行 python download.py 從 HuggingFace 下載 WorldScore‑Dataset。
4. 新增你的模型 –
   • 編寫一個小型 YAML 設定檔（model_name.yaml），描述解析度、生成類型（影像到影片 i2v 或文字到影片 t2v）、幀數、幀率等。
   • 在 worldscore/benchmark/utils/modeltype.py 中，將模型名稱註冊到相應的類別（threedgen、fourdgen、videogen）下。
   • 在 world_generators/ 中實作一個 Python 類別，公開 generate_video(prompt, image_path=None) 方法，回傳 PIL.Image 物件列表或 [N,3,H,W] 張量。
5. 生成影片 – 執行 python world_generators/generate_videos.py --model-name <your_model>（單一 GPU）或使用 Slurm 包裝器在多 GPU 集群上執行。
6. 執行評估 – 生成完成後，執行 python worldscore/run_evaluate.py --model_name <your_model>（或 Slurm 變體）。該腳本使用預先下載的 DROID‑SLAM、Grounding‑DINO、SAM 等檢查點計算一系列指標（如深度一致性、物件追蹤、定位品質）。
7. 提交結果 – 產生 worldscore_output/worldscore.json JSON 檔案。透過電子郵件寄至 haoyiduan@princeton.edu，或上傳影片供團隊評估；排行榜將自動更新。

---

📊 基準測試衡量的內容

WorldScore 結合了 空間 與 時間 指標：

• 幾何一致性 – 透過 DROID‑SLAM 姿態估計實現。
• 物件定位 – 使用 Grounding‑DINO 與 Segment-Anything（SAM / SAM‑2）。
• 時間連貫性 – 評估運動的平滑性與連續性。
• 提示遵循度 – 檢查生成的世界是否遵循提供的相機路徑與場景擴展指令。

具體的指標清單位於 worldscore/benchmark/metrics/，且可擴充；新模型可無縫接入同一管道，無需重寫評估程式碼。

---

🏅 排行榜與社群

結果展示於 HuggingFace Space。團隊可選擇：

• 自行評估並提交 JSON 分數（推薦——即時更新），或
• 傳送原始影片給作者進行人工評分。

倉儲還包含對流行世界生成模型（如 WonderJourney、WonderWorld、CogVideoX、DynamiCrafter）的範例適配器，展示如何整合它們。

---

📦 快速參考（關鍵檔案）

路徑	用途
download.py	從 HuggingFace 下載 WorldScore 資料集。
world_generators/	模型適配器與影片生成腳本。
worldscore/run_evaluate.py	指標計算的主入口點。
worldscore/benchmark/metrics/	各項評估指標的實作。
config/model_configs/	新模型的 YAML 模板。
worldscore/benchmark/utils/modeltype.py	模型家族與名稱的註冊表。

---

📖 引用

@article{duan2025worldscore,
  title={WorldScore: A Unified Evaluation Benchmark for World Generation},
  author={Duan, Haoyi and Yu, Hong-Xing and Chen, Sirui and Fei-Fei, Li and Wu, Jiajun},
  journal={arXiv preprint arXiv:2504.00983},
  year={2025}
}

---

簡而言之：WorldScore 為研究人員提供了一種開箱即用、可重現的方法，用於測試其生成模型在 建構 與 導航 虛擬世界方面的表現，填補了傳統影片品質基準所遺漏的空白。