README.md

metadata

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 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. 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

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.

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 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.