README.md

---
license: other
license_name: waymo-dataset-license-nc
license_link: https://waymo.com/open/terms
library_name: worldflow3d
tags:
  - 3d-scene-generation
  - flow-matching
  - diffusers
  - waymo
  - non-commercial
---

# WorldFlow3D — Waymo models (NON-COMMERCIAL)

Map-conditioned 3D scene generation for outdoor (Waymo) scenes, as a coarse →
refinement flow-matching cascade. Use with the
[`worldflow3d`](https://github.com/princeton-computational-imaging/WorldFlow3D)
package (`pip install worldflow3d`).

> ## ⚠️ Non-commercial license (Waymo Open Dataset)
>
> These models (`waymo-coarse`, `waymo-refine`, `waymo-color`) are **Distributed WOD Models**
> developed using the [Waymo Open Dataset](https://waymo.com/open). They are
> released under the **Waymo Dataset License Agreement for Non-Commercial Use**.
> **Any further downstream use or modification — including scenes, meshes, or
> datasets generated with these models — is subject to that Agreement, including
> its non-commercial restrictions.** A copy of the Agreement is available at
> <https://waymo.com/open/terms>. This notice applies to recipients with respect
> to the whole of these models. The `worldflow3d` *code* is Apache-2.0, but that
> license does **not** grant any rights to these Waymo-derived weights.

**Attribution:**

> This model was made using the Waymo Open Dataset, provided by Waymo LLC under
> the Waymo Dataset License Agreement for Non-Commercial Use, available at
> waymo.com/open/terms.

## Cascade stages

| Subfolder | Role |
|-----------|------|
| `waymo-coarse` | coarse map-conditioned generation (voxel 0.4 m) |
| `waymo-refine` | source-flow refinement, **geometry only** (voxel 0.2 m) |
| `waymo-color` | source-flow refinement, **geometry + color** (voxel 0.2 m) |

`waymo-refine` and `waymo-color` are **alternatives**: pick one refinement stage
for the same coarse output. `waymo-color` additionally predicts per-voxel color, so
`save_mesh` writes both a geometry mesh and a colored `<name>_color.ply` sidecar.

## Usage

```python
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

pipe = WorldFlow3DPipeline.from_hub(
    "pci-lab/worldflow3d-waymo", stage="waymo-coarse",
    refinement_stages=["waymo-refine"], device="cuda",
)

# A shipped sample map (in the GitHub repo's examples/sample_maps/), self-contained.
map_json = load_waymo_map_json("1172406780360799916", map_dir="examples/sample_maps")
ctx = LayoutContext("waymo", "1172406780360799916", map_json)

result = pipe(layout_context=ctx, cfg_scale=1.5, sampling_steps=30,
              refine=True, refine_sampling_steps=30, use_uniform_chunking=True,
              simultaneous=True, smaller_map=True, fraction=0.12)
save_mesh(result.voxels.cpu(), result.voxel_size, "scene.ply")
```

For the **colored** refinement, use the `waymo-color` stage. It is
**tag-conditioned** (`location` / `time_of_day` / `weather`) — pass tags for a
coherent result; without them the color channels are unconditioned and the mesh
shows color/surface artifacts.

```python
pipe = WorldFlow3DPipeline.from_hub(
    "pci-lab/worldflow3d-waymo", stage="waymo-coarse",
    refinement_stages=["waymo-color"], device="cuda",
)
result = pipe(layout_context=ctx, cfg_scale=1.5, sampling_steps=30,
              refine=True, refine_sampling_steps=30, use_uniform_chunking=True,
              simultaneous=True, smaller_map=True, fraction=0.12,
              tags={"location": "location_sf"},
              refine_tags={"time_of_day": "Dawn/Dusk", "weather": "sunny"})
# save_mesh also writes scene_color.ply (per-voxel color).
```

Valid tag values — `location` ∈ {location_sf, location_phx, location_other};
`time_of_day` ∈ {Dawn/Dusk, Day, Night}; `weather` ∈ {sunny, rain}.

See the [GitHub repo](https://github.com/princeton-computational-imaging/WorldFlow3D)
for the full docs, sample maps, and the loading semantics (subfolder cascades load
via `from_hub`, not the bare-diffusers `subfolder=` one-liner).

The Front3D (indoor) models are trained on 3D-FRONT and live in a separate repo
under 3D-FRONT's terms.