Ma-Zhuang/OmniNWM

📚 什麼是 OmniNWM？

OmniNWM（Omniscient Driving Navigation World Models）是一個研究級的程式碼庫，用於建構用於自動駕駛模擬的全景世界模型。該模型能從車輛的規劃軌跡中，生成全部六個周圍相機的完整感測器輸出——RGB影像、語意地圖、深度圖與3D佔用網格。由於生成的世界是密集的且多模態的，它既可用於渲染逼真的駕駛影片，也可作為封閉迴路環境，用於訓練或評估駕駛策略。

---

🎯 核心概念

概念	含義
多模態生成	單一神經網路預測360°全景的RGB、語意、深度與3D佔用。
歸一化Plücker射線圖	一種幾何表示，讓模型能將像素級預測精確轉換為車輛動作。
自回歸穩定性	一種「強制」策略，使模型在生成長度超過真實影片時仍能保持穩定，不漂移。
基於佔用的密集獎勵	預測的佔用網格可轉換為獎勵信號，實現真實的封閉迴路策略評估。
零樣本遷移	相同檢查點可在其他駕駛資料集（如nuPlan）與不同相機配置上使用，無需額外微調。

---

🛠️ 快速上手

1. 克隆與設定

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

2. 修補 transformers – 按說明編輯 modeling_utils.py（將torch版本檢查從 2.3 改為 2.5）。
3. 下載檢查點

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

4. 準備資料 – 從README中提供的連結下載nuScenes v1.0的train/val分割資料，以及12 Hz的深度/分割標註。遵循倉儲中所示的目錄結構（例如，data/nuscenes/CAM_FRONT、data/nuscenes_12hz_depth_unzip等）。

---

🚀 常見工作流程

任務	命令	說明
推論 – 軌跡到影片	torchrun --nproc-per-node 8 tools/inference.py configs/inference/infer.py	為所有六個相機生成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（視覺-語言-動作）流程的實作。
• 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（見 LICENSE）。

---

簡而言之：OmniNWM是一種先進的世界模型，能將駕駛計畫轉化為高保真、多感測器模擬，既支援逼真的影片合成，也支援自動駕駛研究的封閉迴路策略測試。