Ma-Zhuang/OmniNWM

📚 OmniNWM란 무엇인가요?

OmniNWM(Omniscient Driving Navigation World Models)는 자율주행 시뮬레이션을 위한 파노라마형 월드 모델을 구축하는 연구용 코드베이스입니다. 이 모델은 차량의 계획된 경로에서 6대의 주변 카메라에 대해 RGB 이미지, 세분화 지도, 깊이 지도, 3D 점유 그리드를 포함한 완전한 센서 수준의 출력을 동시에 생성합니다. 생성된 세계는 밀도가 높고 다중 모달이므로, 현실적인 주행 영상 렌더링뿐만 아니라 드라이빙 정책의 훈련 또는 평가를 위한 폐루프 환경으로도 사용할 수 있습니다.

🎯 핵심 아이디어

아이디어	의미
다중 모달 생성	하나의 신경망이 360도 전체에 대해 RGB, 세분화, 깊이, 3D 점유를 예측합니다.
정규화된 Plücker 레이 맵	모델이 픽셀 수준의 예측을 정확한 차량 동작으로 변환할 수 있는 기하학적 표현입니다.
자기회귀적 안정성	"포싱" 전략을 통해 진짜 영상 길이를 초과해 생성을 지속해도 흐트러지지 않습니다.
점유 기반 밀도 보상	예측된 점유 그리드를 보상 신호로 변환할 수 있어 현실적인 폐루프 정책 평가가 가능합니다.
제로샷 전이	동일한 체크포인트가 다른 주행 데이터셋(예: nuPlan)과 다른 카메라 구성에서도 추가 미세조정 없이 작동합니다.

🛠️ 시작하기 (빠른 시작)

클론 및 설정

git clone https://github.com/Ma-Zhuang/OmniNWM.git && cd OmniNWM
mkdir -p pretrained data
pip install -e .
pip install "huggingface_hub[cli]"

transformers 패치 – modeling_utils.py를 지시에 따라 편집 (torch 버전 체크를 2.3에서 2.5로 변경).

체크포인트 다운로드

huggingface-cli download Arlolo0/OmniNWM --local-dir ./pretrained
huggingface-cli download hpcai-tech/Open-Sora-v2 --local-dir ./pretrained

데이터 준비 – README에 있는 링크에서 nuScenes v1.0의 train/val 분할과 12Hz 깊이/세그멘테이션 어노테이션을 다운로드. 리포지토리에 표시된 디렉터리 구조를 따르세요 (예: data/nuscenes/CAM_FRONT, data/nuscenes_12hz_depth_unzip 등).

🚀 일반적인 워크플로우

작업	명령어	비고
추론 – 경로에서 영상 생성	`torchrun --nproc-per-node 8 tools/inference.py configs/inference/infer.py`	6대의 카메라에 대해 33프레임 영상 생성 (448×800).
분포 외 (nuPlan) 추론	`torchrun --nproc-per-node 8 tools/inference.py configs/inference/infer_nuplan.py`	nuPlan 데이터셋에서 수동으로 제공된 경로 사용.
폐루프 VLA 테스트	`torchrun --nproc-per-node 8 tools/inference.py configs/inference/infer_with_occ_vla.py`	모델의 점유 예측을 보상으로 피드백하는 루프 (321프레임).
학습 – 단계별	`bash dist_train_mlp.sh configs/train/stage_1.py` (그 후 스테이지 2, 스테이지 3)	스테이지별로 해상도와 영상 길이를 늘려 학습 안정성 유지.

📦 리포지토리 내부 내용

omninwm/models/OmniNWM-VLA – Tri-MMi 삼중 모달 융합 및 VLA(Vision-Language-Action) 파이프라인 구현.
configs/ – 추론 및 세 가지 학습 스테이지용 즉시 실행 가능한 YAML/py 설정 파일.
tools/ – 분산 추론용 스크립트 (inference.py).
pretrained/ – 다운로드한 체크포인트(VAE, 점유 모델, Open-Sora-v2 가중치)를 위한 자리표시자.
data/ – nuScenes 이미지, 깊이 맵, 세그멘테이션 마스크의 예상 디렉터리 구조.

📖 인용

OmniNWM을 연구에 사용할 경우, arXiv 논문을 인용해 주세요:

@article{li2025omninwm,
  title={OmniNWM: Omniscient Driving Navigation World Models},
  author={Li, Bohan and Ma, Zhuang and Du, Dalong and Peng, Baorui and Liang, Zhujin and Liu, Zhenqiang and Ma, Chao and Jin, Yueming and Zhao, Hao and Zeng, Wenjun and others},
  journal={arXiv preprint arXiv:2510.18313},
  year={2025}
}

⚖️ 라이선스

Apache License 2.0 (see LICENSE).

요약하면: OmniNWM은 드라이빙 계획을 고해상도 다중 센서 시뮬레이션으로 변환하는 최첨단 월드 모델로, 현실적인 영상 합성과 자율주행 연구를 위한 폐루프 정책 테스트를 모두 가능하게 합니다.