haoyi-duan/WorldScore

Official implementation for WorldScore: A Unified Evaluation Benchmark for World Generation

📚 WorldScore란 무엇인가요?

WorldScore는 3D 장면, 4D 시공간 세계 또는 영상 등을 텍스트나 이미지에서 생성하는 세계 생성 모델을 평가하기 위한 오픈소스 벤치마크입니다. 다음과 같은 기능을 제공합니다:

선별된 데이터셋 (WorldScore‑Dataset): 초기 장면과 카메라 이동 지시어를 포함합니다.
기준 구현체 (Reference implementations): 데이터 다운로드, 어떤 모델로든 영상 생성, 공간-시간 메트릭스 실행을 위한 코드.
공개 리더보드 (HuggingFace에서 호스팅): 연구자들이 자신의 점수를 제출할 수 있는 장소.

이 프로젝트는 ICCV‑2025 논문 "WorldScore: A Unified Evaluation Benchmark for World Generation" 과 함께 제공되며, 기존 영상 품질 벤치마크가 놓치는 점인 모델이 세계를 확장하고 카메라 경로를 따르는 능력을 하나의 수치로 반영하는 것을 목표로 합니다.

🚀 시작하기 (고수준 단계)

클론 및 설정 – .env 파일에서 WORLDSCORE_PATH, MODEL_PATH, DATA_PATH를 설정합니다.
설치 – conda 환경(파이썬 3.10)을 생성하고 pip install -e .을 실행하며, PyTorch 2.5, DROID‑SLAM, Grounding‑SAM, SAM‑2, VFIMamba 등 긴 종속성 목록을 설치합니다.
데이터셋 다운로드 – python download.py를 실행하여 HuggingFace에서 WorldScore‑Dataset을 다운로드합니다.
모델 추가 –
- 해상도, 생성 유형(image-to-video i2v 또는 text-to-video t2v), 프레임 수, fps 등을 기술한 작은 YAML 설정 파일(model_name.yaml)을 작성합니다.
- worldscore/benchmark/utils/modeltype.py에 적절한 패밀리(threedgen, fourdgen, videogen) 아래에서 모델 이름을 등록합니다.
- world_generators/에 generate_video(prompt, image_path=None) 메서드를 노출하는 Python 클래스를 구현합니다. 반환값은 PIL.Image 객체 리스트 또는 [N,3,H,W] 텐서입니다.
영상 생성 – python world_generators/generate_videos.py --model-name <your_model>를 실행합니다 (단일 GPU) 또는 Slurm 래퍼를 사용해 멀티 GPU 클러스터에 적용합니다.
평가 실행 – 생성 후 python worldscore/run_evaluate.py --model_name <your_model>를 실행합니다 (또는 Slurm 버전). DROID‑SLAM, Grounding‑DINO, SAM 등 사전 다운로드된 체크포인트를 사용해 깊이 일관성, 객체 추적, 지향성 품질 등의 메트릭을 계산합니다.
결과 제출 – 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는 연구자들이 자신의 생성 모델이 가상 세계를 구축하고 탐색하는 능력을 즉시 실행 가능하고 재현 가능한 방식으로 테스트할 수 있도록 도와주며, 기존 영상 품질 벤치마크가 놓친 갭을 메웁니다.