Scene package cooking pipeline

[Nabla7]

Problem

Closes N/A

Runtime code can load scene packages, but source assets still need a repeatable offline cooking path. The cooking path must not hardcode one browser GLB heuristic: Rerun needs conservative GLBs, while Babylon/PimSim can use a different extension and optimization profile.

Solution

• Adds the offline scene cooking pipeline under dimos.experimental.pimsim.scene for source normalization, inspection, sidecar loading, entity planning, browser artifacts, MuJoCo wrapper XML, entity collision hulls, and optional MuJoCo binaries.
• Adds explicit browser visual targets: rerun, babylon, and generic.
• Stores named browser visuals in scene metadata so consumers can call package.browser_visual_path("rerun") or package.browser_visual_path("babylon").
• Moves GLB JSON/BIN rewrite utilities into dimos.simulation.scene_assets.glb so Rerun-specific sanitization is a target policy, not a hidden global cooking rule.
• Rewrites the scene cooking README as standalone documentation: inspect source, author sidecar, choose visual target, cook, inspect output layout, load through runtime.
• Removes the extra demo/preflight module from the PR.
• Adds the scene dependency extra for cook-time packages. Blender and native gltfpack remain external tools.
• Keeps data publishing separate through docs/development/large_file_management.md and ./bin/lfs_push.

How to Test

Inspect source geometry before authoring sidecars:

python - <<'PY'
from pathlib import Path
import numpy as np
from dimos.experimental.pimsim.scene.source_asset import prepare_scene_source
from dimos.simulation.scene_assets.mesh_scene import SceneMeshAlignment, load_scene_prims
source = Path("data/dimos_office_mesh/dimos_office_mesh.glb")
prepared = prepare_scene_source(source)
alignment = SceneMeshAlignment(scale=2.0, y_up=False)
for prim in load_scene_prims(prepared.cook_path, alignment=alignment):
    name = prim.visual_node_name or prim.prim_path or prim.name
    if "Floor" in name:
        lo = np.min(prim.vertices, axis=0)
        hi = np.max(prim.vertices, axis=0)
        print(name, lo.round(4).tolist(), hi.round(4).tolist())
PY

Cook the office package for Rerun:

python -m dimos.experimental.pimsim.scene.cook \
  data/dimos_office_mesh/dimos_office_mesh.glb \
  --cook-spec data/dimos_office_mesh/dimos_office_mesh.cook.json \
  --output-dir data/scene_packages/dimos_office \
  --scale 2.0 \
  --no-y-up \
  --visual-target rerun \
  --rebake

Cook a Babylon/PimSim visual:

python -m dimos.experimental.pimsim.scene.cook \
  data/my_scene/source.blend \
  --cook-spec data/my_scene/source.cook.json \
  --output-dir data/scene_packages/my_scene \
  --visual-target babylon \
  --rebake

Checks run locally:

ruff check dimos/simulation/scene_assets/spec.py dimos/simulation/scene_assets/glb.py dimos/simulation/scene_assets/test_glb.py dimos/experimental/pimsim/scene/cook.py dimos/experimental/pimsim/scene/visual_glb.py dimos/experimental/pimsim/scene/test_spec.py
python -m py_compile dimos/simulation/scene_assets/spec.py dimos/simulation/scene_assets/glb.py dimos/experimental/pimsim/scene/cook.py dimos/experimental/pimsim/scene/visual_glb.py
python -m pytest dimos/simulation/scene_assets/test_glb.py dimos/experimental/pimsim/scene/test_spec.py -q
python -m dimos.experimental.pimsim.scene.cook --help

Earlier branch validation also covered focused scene-cooking tests for source assets, entity collision, and MuJoCo collision specs.

Contributor License Agreement

• I have read and approved the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 51.31707% with 998 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/simulation/scene_assets/mesh_scene.py	10.02%	332 Missing ⚠️
dimos/simulation/mujoco/collision_spec.py	40.49%	201 Missing and 15 partials ⚠️
...mos/experimental/pimsim/scene/browser_collision.py	26.56%	94 Missing ⚠️
dimos/experimental/pimsim/scene/inspect.py	23.46%	75 Missing ⚠️
dimos/experimental/pimsim/scene/command.py	19.23%	63 Missing ⚠️
dimos/simulation/scene_assets/glb.py	65.11%	32 Missing and 28 partials ⚠️
...imos/experimental/pimsim/scene/entity_collision.py	34.48%	35 Missing and 3 partials ⚠️
dimos/experimental/pimsim/scene/sidecar.py	71.42%	29 Missing and 7 partials ⚠️
dimos/experimental/pimsim/scene/plan.py	83.87%	23 Missing and 12 partials ⚠️
dimos/experimental/pimsim/scene/source_asset.py	73.49%	16 Missing and 6 partials ⚠️
... and 3 more

@@                        Coverage Diff                         @@
##           pim/feat/runtime-scene-loading    #2544      +/-   ##
==================================================================
- Coverage                           70.71%   70.10%   -0.62%     
==================================================================
  Files                                 897      886      -11     
  Lines                               80362    80366       +4     
  Branches                             7255     7309      +54     
==================================================================
- Hits                                56827    56339     -488     
- Misses                              21671    22132     +461     
- Partials                             1864     1895      +31     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	62.52% <51.31%> (-0.61%)	⬇️
OS-ubuntu-latest	65.23% <51.31%> (-0.61%)	⬇️
Py-3.10	65.23% <51.31%> (-0.60%)	⬇️
Py-3.11	65.23% <51.31%> (-0.61%)	⬇️
Py-3.12	65.23% <51.31%> (-0.61%)	⬇️
Py-3.13	65.23% <51.31%> (-0.61%)	⬇️
Py-3.14	65.24% <51.31%> (-0.61%)	⬇️
Py-3.14t	65.23% <51.31%> (-0.61%)	⬇️
SelfHosted-Large	29.84% <22.31%> (-0.15%)	⬇️
SelfHosted-Linux	37.26% <22.31%> (-0.17%)	⬇️
SelfHosted-macOS	36.09% <22.31%> (-0.20%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...mos/experimental/pimsim/scene/test_source_asset.py	100.00% <100.00%> (ø)
dimos/experimental/pimsim/scene/test_spec.py	100.00% <100.00%> (ø)
dimos/simulation/mujoco/test_collision_spec.py	100.00% <100.00%> (ø)
dimos/simulation/scene_assets/test_glb.py	96.92% <96.92%> (ø)
dimos/simulation/scene_assets/spec.py	88.46% <88.00%> (+15.67%)	⬆️
dimos/experimental/pimsim/scene/source_asset.py	73.49% <73.49%> (ø)
...experimental/pimsim/scene/test_entity_collision.py	38.88% <38.88%> (ø)
dimos/experimental/pimsim/scene/plan.py	83.87% <83.87%> (ø)
dimos/experimental/pimsim/scene/sidecar.py	71.42% <71.42%> (ø)
...imos/experimental/pimsim/scene/entity_collision.py	34.48% <34.48%> (ø)
... and 6 more

... and 45 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.