Add whole-scene USD export and preview

[MuziWong]

Description

This PR adds a portable whole-scene USD package alongside the existing editable
Scene Export output.

• Generate scene_usd/scene.usda, a manifest, externally textured GLTF
  payloads, and articulated USDC payloads after both scene generation and scene
  editing.
• Preserve final object poses, textures, GLB internal transforms, and
  articulated-object behavior through the package manifest.
• Add embodichain preview-scene --output_root <path> --usd to preview the
  packaged scene; this also works with --viser and supported articulation
  joint controls.
• Keep scene_export/ as the editable GLB/USDC source form, while
  scene_usd/ is the portable preview/delivery package.
• Document the package layout and preview commands.

The native DexSim adapter deliberately loads packaged GLTF/USDC payloads
through the manifest because flattened USD mesh import does not currently
preserve GLB internal node transforms faithfully.

scene_usd.py is an internal Scene Engine adapter, not a public API module.

Dependencies: no new runtime dependencies.

No linked issue.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Enhancement (non-breaking change which improves an existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (existing functionality will not work without user modification)
• Documentation update

Screenshots

N/A — CLI and simulation-preview change.

Validation

• black --check --diff --color ./
• Black formatting run; no formatting changes produced.
• python docs/scripts/check_api_docs.py
  — 1680/1680 public exports documented.
• python -m pytest tests/gen_sim/scene_engine/test_scene_core_and_export.py
  — 18 passed.

Checklist

• I have run Black formatting for the code base.
• I have made corresponding Scene Engine documentation changes.
• Public API documentation coverage is aligned.
• I have added and run focused tests for the Scene USD package and preview adapter.
• No dependency updates are required.

[greptile-apps]

Greptile Summary

The PR adds a portable whole-scene USD package, manifest-driven native preview loading, and GLTF/USDC texture preservation after scene generation and editing.

• Adds scene_usd package construction and manifest-based loading.
• Extends preview-scene with --usd while retaining articulated joint controls.
• Adds a glTF loader option to simulation mesh configuration.
• Documents and tests the new export and preview paths.

Confidence Score: 3/5

This PR should not merge until scene UIDs are validated or mapped to contained package paths before writing runtime assets.

The edit path accepts arbitrary nonempty UIDs from an existing scene export and passes them to new path joins that write and copy files, allowing absolute or parent-relative identifiers to escape the package directory.

Files Needing Attention: embodichain/gen_sim/scene_engine/pipeline/utils/scene_usd.py, embodichain/gen_sim/scene_engine/pipeline/utils/scene_importer.py

Security Review

The package builder trusts imported scene UIDs as directory paths. A traversal-bearing or absolute UID can therefore direct generated runtime assets outside the intended scene_usd directory.

Important Files Changed

Filename	Overview
embodichain/gen_sim/scene_engine/pipeline/utils/scene_usd.py	Implements USD package construction and loading, but unrestricted imported UIDs can escape temporary and persistent package directories.
embodichain/gen_sim/scene_engine/cli/preview.py	Adds manifest-backed --usd preview selection and delegates common scene loading to the new adapter.
embodichain/gen_sim/scene_engine/pipeline/generate.py	Builds the USD package after the editable export and preserves explicitly reported RuntimeError fallback behavior.
embodichain/gen_sim/scene_engine/pipeline/edit.py	Rebuilds the USD package after edits, which also makes imported scene identifiers reachable by the vulnerable path construction.
embodichain/lab/sim/utility/sim_utils.py	Propagates the optional glTF loader switch when supported by the installed DexSim version.
tests/gen_sim/scene_engine/test_scene_core_and_export.py	Covers manifest loading and texture conversion but omits traversal-bearing imported UIDs.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Scene generation or edit] --> B[Editable scene_export]
  B --> C[Externalize GLB and USDC assets]
  C --> D[Export scene.usda]
  C --> E[Package native assets]
  D --> F[scene_usd manifest]
  E --> F
  F --> G[preview-scene --usd]
  G --> H[Static rigid objects]
  G --> I[Articulations and joint controls]

Loading

Prompt To Fix All With AI

### Issue 1
embodichain/gen_sim/scene_engine/pipeline/utils/scene_usd.py:515-518
**UID paths escape package roots**

When editing or rebuilding a scene export whose accepted `uid` is absolute or contains parent-directory components, this code appends that value directly to the runtime-assets root and later the packaged-assets root, causing generated GLTF or USDC payloads to be written outside `scene_usd` and potentially overwrite another writable location. Validate or safely encode UIDs before using them as path components. **How this was verified:** The importer accepts any nonempty string as a UID, and the package builder uses that string directly as the destination path without a containment check.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "deleted the scene usd api export" | Re-trigger Greptile}

[greptile-apps]

UID paths escape package roots

When editing or rebuilding a scene export whose accepted uid is absolute or contains parent-directory components, this code appends that value directly to the runtime-assets root and later the packaged-assets root, causing generated GLTF or USDC payloads to be written outside scene_usd and potentially overwrite another writable location. Validate or safely encode UIDs before using them as path components. How this was verified: The importer accepts any nonempty string as a UID, and the package builder uses that string directly as the destination path without a containment check.

Knowledge Base Used:

• Generative simulation pipelines
• Scene generation engine

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/gen_sim/scene_engine/pipeline/utils/scene_usd.py
Line: 515-518

Comment:
**UID paths escape package roots**

When editing or rebuilding a scene export whose accepted `uid` is absolute or contains parent-directory components, this code appends that value directly to the runtime-assets root and later the packaged-assets root, causing generated GLTF or USDC payloads to be written outside `scene_usd` and potentially overwrite another writable location. Validate or safely encode UIDs before using them as path components. **How this was verified:** The importer accepts any nonempty string as a UID, and the package builder uses that string directly as the destination path without a containment check.

**Knowledge Base Used:**
- [Generative simulation pipelines](https://app.greptile.com/dexforce/-/custom-context/knowledge-base/dexforce/embodichain/-/docs/generative-simulation.md)
- [Scene generation engine](https://app.greptile.com/dexforce/-/custom-context/knowledge-base/dexforce/embodichain/-/docs/scene-generation-engine.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.