hzxie/CityDreamer

CityDreamer – 無限3D城市生成的生成模型

是什麼 – CityDreamer 是一個研究級的組合式生成模型，能夠合成無限且逼真的3D城市景觀。它透過結合三個學習元件來實現：

1. 無限佈局生成器 – 使用 VQ-VAE + 自回歸取樣器生成全域城市佈局（道路網絡、區塊排列）。
2. 背景元素生成器 – 以地形、植被、天空等非建築元素填滿佈局。
3. 建築實例生成器 – 為每個區塊生成詳細的建築幾何與紋理。

此系統基於 PyTorch（已測試版本 1.13.1 + CUDA 11.7），推論時可在單一高記憶體 GPU（如 RTX 3090）上執行，訓練則假設使用多 GPU 環境。

---

快速開始（推論）

1. 安裝 – 安裝所需的 PyTorch 版本，克隆程式碼庫，並執行 pip install -r requirements.txt。
2. 編譯 CUDA 擴展 – 位於 extensions/ 中的擴展（每個子資料夾透過 pip install . 安裝）。
3. 執行示範：

   python -m demo.run   # 在 http://localhost:3186 開啟 Web UI
   

   或使用 CLI：

   python -m scripts.inference   # 輸出 output/rendering.mp4
   

   若 GPU 顯存不足 24 GB，請調整 --patch_height / --patch_width。

---

訓練（研究用途）

1. 資料集 – CityDreamer 提供兩個大型資料集：
   • OSM（OpenStreetMap）道路網絡資料。
   • GoogleEarth 航拍影像與實例分割遮罩（透過 SEEM 生成）。 兩者均可透過提供的網關連結下載。
2. 準備 GoogleEarth 標註（約 1 TB） – 執行 SEEM 分割腳本，再執行 scripts/dataset_generator.py。
3. 訓練三個模組（每個模組使用通用 run.py 入口點搭配 torchrun）：
   • 佈局用 VQ-VAE → 4 GPU。
   • 佈局用取樣器 → 2 GPU（載入 VQ-VAE 檢查點）。
   • 背景元素生成器 → 8 GPU（設定 BUILDING_MODE=False）。
   • 建築實例生成器 → 8 GPU（設定 BUILDING_MODE=True）。 各部分的設定調整詳見 README。

---

預訓練模型與資源

組件	檢查點（下載）
佈局生成器（取樣器）	LayoutGen.pth
背景元素生成器	CityDreamer-Bgnd.pth
建築實例生成器	CityDreamer-Fgnd.pth

即時示範託管於 Hugging Face Spaces，短篇亮點影片連結至 YouTube。

---

授權

程式碼以 NTU S-Lab License 1.0（參見程式碼庫中的 LICENSE）發布。再分發必須遵守該授權條款。

---

開發團隊

由南洋理工大學 S-Lab 的謝浩哲、陳兆熙、洪方舟、劉子威開發。此研究已發表於 CVPR 2024，並有後續研究（CityDreamer4D）被 TPAMI 接受。

---

總結 – CityDreamer 為對大規模、程序化生成真實 3D 城市環境感興趣的研究者提供了完整管道（資料準備、訓練腳本、推論示範）。