model card: cascade overview, from_hub usage, dataset licensing

README.md

@@ -1,3 +1,108 @@
 ---
 license: apache-2.0
+tags:
+  - 3d-generation
+  - diffusion
+  - flow-matching
+  - voxel
+  - scene-generation
+  - autonomous-driving
+  - indoor-scenes
+datasets:
+  - waymo-open-dataset
+  - 3D-FRONT
 ---
+
+# WorldFlow3D
+
+Hierarchical, map/layout-conditioned **3D scene generation** via chunked flow
+matching. This repo holds the released model **cascade** (coarse → refinement) for
+both outdoor (Waymo, map-conditioned) and indoor (3D-FRONT, layout-conditioned)
+scenes, packaged in the [diffusers](https://github.com/huggingface/diffusers) style.
+
+- **Code:** <https://github.com/princeton-computational-imaging/WorldFlow3D>
+- **License:** Apache-2.0 (code & weights). **Training data** (Waymo Open Dataset,
+  3D-FRONT) carries its own terms — see *Training data & licensing* below.
+
+## Repository layout (one repo = the whole cascade)
+
+Each stage is a self-contained diffusers layout in its own **subfolder**. The model
+*code* ships in the `worldflow3d` package, so the subfolders hold only weights + config:
+
+```
+waymo-coarse/     coarse outdoor geometry (map-conditioned), 0.4 m voxels
+waymo-refine/     source-flow refinement -> 0.2 m voxels
+front3d-coarse/   coarse indoor geometry
+front3d-color/    source-flow + color refinement (unet in=4)
+```
+
+The four `unet/` folders are four distinct trained models, not copies.
+
+## Usage
+
+```bash
+pip install worldflow3d   # see the GitHub repo for source install
+```
+
+```python
+import numpy as np
+from worldflow3d import WorldFlow3DPipeline
+from worldflow3d.pipeline.datatypes import LayoutContext
+from worldflow3d.conditioning.waymo import load_waymo_map_json
+from worldflow3d.recon import save_mesh
+
+# Load the Waymo coarse -> refine cascade straight from this repo.
+pipe = WorldFlow3DPipeline.from_hub(
+    "pci-lab/worldflow3d", stage="waymo-coarse", refinement_stages=["waymo-refine"],
+    device="cuda",
+)
+
+map_json = load_waymo_map_json("102062", map_dir="waymo_maps", data_root="waymo_scenes")
+transform = np.load("waymo_scenes/coord_transforms/udf_voxel_0.4/segment-102062_training.npy",
+                    allow_pickle=True).item()
+ctx = LayoutContext("waymo", "102062", map_json, transform_data=transform)
+
+result = pipe(layout_context=ctx, cfg_scale=1.5, sampling_steps=30,
+              refine=True, refine_sampling_steps=30, use_uniform_chunking=True,
+              smaller_map=True, fraction=0.12)
+save_mesh(result.voxels.cpu(), result.voxel_size, "scene.ply")
+```
+
+Indoor (3D-FRONT), layout-conditioned coarse → color refinement:
+
+```python
+pipe = WorldFlow3DPipeline.from_hub(
+    "pci-lab/worldflow3d", stage="front3d-coarse", refinement_stages=["front3d-color"],
+    device="cuda",
+)
+```
+
+> **Loading note.** Use `WorldFlow3DPipeline.from_hub(...)` (this package). The bare
+> `diffusers.DiffusionPipeline.from_pretrained(repo, trust_remote_code=True)` one-liner
+> does **not** work here: diffusers reads `model_index.json` only from a repo *root*,
+> never a subfolder — so a subfolder/cascade repo is loaded via the package.
+
+## Model details
+
+| | |
+|---|---|
+| Architecture | 3D UNet, velocity-prediction (flow-matching) Euler sampler |
+| Representation | Truncated UDF voxels (direct-diffusion; no VAE). Z is the vertical axis |
+| Conditioning | Waymo vector maps (lanes, road edges/lines, crosswalks); 3D-FRONT layouts (walls/floors/doors/windows/furniture); optional tags (time/weather/location) |
+| Generation | Chunked, coarse→refine cascade; sequential or simultaneous (feather-averaged) |
+| Frameworks | `torch>=2.2`, `diffusers>=0.29` (tested on torch 2.2/diffusers 0.29.2 and torch 2.5/diffusers 0.38) |
+
+## Training data & licensing
+
+The weights are **derived from**:
+- **Waymo Open Dataset** — <https://waymo.com/open/> — non-commercial research license;
+  redistribution of raw data is restricted. The `waymo-*` weights are for research use
+  consistent with the WOD terms.
+- **3D-FRONT** — Alibaba; research license.
+
+Code and weights are Apache-2.0, but **your use must also comply with the upstream
+dataset licenses**. No raw dataset content is redistributed in this repo.
+
+## Citation
+
+If you use WorldFlow3D, please cite the project (see the GitHub repository).