Skip to content

Unify USD loading through import recipes and authored scene semantics - #795

Merged
yuecideng merged 19 commits into
mainfrom
codex/usd-import-contracts
Nov 11, 2026
Merged

yuecideng merged 19 commits into
mainfrom
codex/usd-import-contracts

Conversation

@yuecideng

@yuecideng yuecideng commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Description

USD imports now use one recipe, SimulationManager.add_usd(UsdImportCfg(...)), and return stable source-path mappings through UsdImportResult. This resolves duplicated source-file ownership and binds imported soft bodies and cloth into the existing EmbodiChain lifecycle.

imported = sim.add_usd(
    UsdImportCfg(
        name="cell",
        source=UsdSourceCfg(file_path="cell.usda", root_prim_path="/World/Cell"),
        namespace="cell_1",
    )
)
sim.prepare()
  • Source selection/variants belong to UsdSourceCfg; namespace, scene placement and sparse asset overrides belong to UsdImportCfg. Typed overrides retain their class and unset-placement semantics when serialized.
  • Scene and single-asset loading share the DexSim source parser. Unset USD pose, scale, actor and articulation-root intent is preserved. Runtime UID changes remap constraints and collision-filter endpoints while result keys retain original source prim paths.
  • Validate configuration, UID collisions, facade support and mounted-camera bindings before native declaration. Backend materialization validation remains at prepare() and does not promise rollback.
  • Volume/surface particle sets bind through existing deformable facades on Newton/CUDA, retaining source topology and physics. NoRender retains authored material metadata while omitting native texture/alpha writes that have no renderer consumer.
  • Legacy add_usd(name, file_path, ...) calls retain their mutable dictionary return. Source-address compatibility spellings remain supported.
  • Synchronize with main through 460939c83 and use its pinned DexSim 0.6.0rc1 contract, preserving the native DexUni default.

Validation

Latest five review follow-ups (2026-11-10)

Fixed in 52896be4c5285513993a522659aecc84a61cb7e7:

  • Legacy USD mesh loading no longer converts an unused nullable actor before import; direct and dictionary-created configs retain authored USD physics.
  • RobotCfg decoding constructs with decoded source/file ownership present, preserving omitted USD scale through portable round trips without erasing explicit or preset scale defaults.
  • USD results retain every resource when one prim emits multiple descriptors. Unique source keys stay unchanged; repeated prims use <prim_path>#<ordinal>, with resource_source_paths retaining the exact prim path. UID/type/source maps and constraint subsets share the same key assignment.
  • Portable sparse articulation overrides accept JSON/YAML list-valued pose matrices.
  • Acceptance manifests reject duplicate case IDs before launching children or overwriting case artifacts.

Validation: 737 related tests, 126 robot configuration tests, 6 native USD binding/reset/replacement cases, 11 GenSim USD tests, 42 context tests, and 11 API-checker tests passed. Black 26.10.1 and API coverage 4672/4672 passed. A real one/two-curve USD fixture checks complete/stable resource metadata across namespace variants; cable physics recertification and the historical 54-input asset matrix were not rerun. The independent API review confirmed both result/serialization fixes, and public docs/context now describe derived resource keys.

Remote CI for this head is pending; local validation is reported separately.

URDF scale CI regression fix (2026-11-10)

  • The previous CI passed 12,975 fast tests and 531 GPU tests; the simulation lane failed six left/right dexterous-hand cases because late-assembled URDF configs retained body_scale=None.
  • Fixed the shared non-USD articulation lowering boundary to resolve omitted scale to (1, 1, 1). Explicit scale and USD source-scale preservation are unaffected. Regression coverage includes both ArticulationCfg and RobotCfg with omitted and non-unit scale.
  • Re-ran the exact six failing native cases (BrainCo Revo1, SharpaWave and WujiHand, left/right): 6 passed. Focused source/config/descriptor coverage: 412 passed. API coverage 4438/4438 and Black 26.10.1 passed.
  • Existing context already specifies unit-scale defaults for non-USD imports, so no context edit was needed. Merged main through 1070fcdc4 to clear the PR merge conflict and restore CI triggering. After merging: 412 focused tests, the same 6 native cases, and API coverage 4672/4672 pass. Fresh remote CI is pending.

Latest follow-up review and CI fix (2026-11-09)

  • Fixed explicit zero pose fields in sparse USD overrides: field presence is retained while Euler conversion stays consistent. Omitted pose and explicitly preserved source placement remain distinct.
  • Resolved ordinary mesh defaults after dictionary decoding, preserving nullable defaults for recipe-owned typed/source configurations. The legacy mesh loader is covered with its fake Arena.
  • Returned facade configs now represent resolved absolute placement in config mode. Original caller configs retain their input intent. Reusing asset.cfg.copy() preserves singleton offsets and whole-scene placement across repeated replacement/reset, including the legacy scene API.
  • Fixed the import-order-dependent CI failure by using real SDK constraint descriptors and removing the fake global class replacement/capability-check bypass. Preloading usd_import before running the complete override module passes 30 tests.
  • Validation: 837 affected tests, 6 native cases, 11 GenSim USD tests, 42 context tests, Black 26.10.1, and API coverage 4438/4438 passed. The reported failures were reproduced before the fixes. Configuration docs and the source-physics context now describe explicit sparse placement and reusable resolved configs.
  • CI recheck for this head has started; remote outcomes are tracked separately from local verification.

Latest PR feedback and CI fixes (2026-11-09)

  • Addressed all ten newly confirmed feedback roots through independent API, engine and security review. Singleton imports now keep caller configuration intent unchanged; native add/reset/replacement and Gym unchanged-object comparison retain the same placement.
  • Preserve mode keeps source actors/scales, including legacy serialized defaults. Actor/scale overrides require explicit overlay. Restored positional config compatibility and aligned sparse/typed Euler conversion.
  • Limited singleton constraint rejection to selected physical assets; kept Default root settings in legacy robot metadata; preflighted mounted-camera factories/config pairing.
  • Remapped Newton weld/body-order references only for actual rigid bodies, keeping joint references and same-named visual/articulation links unchanged.
  • Validated acceptance manifest IDs, output containment and preexisting artifact symlinks before writing or deleting files.
  • Fixed all five failures from the previous CI test job: declare fixed roots in four articulation examples and parse USD example help before importing NumPy. Existing CI checks and assertions remain enabled.
  • Local verification: 828 affected tests, 4 native binding/reset/replacement cases, 11 GenSim USD tests, 42 context tests, Black 26.10.1, and API coverage 4438/4438 passed. Regression additions target the reported gaps; existing tutorial tests were reused.
  • Updated the simulation source-physics context for preserve/overlay ownership and runtime config copies. The historical 54-input asset matrix was not repeated in full.
  • Remote CI recheck is in progress; local verification is not reported as remote CI success.

Greptile review fixes (2026-11-09)

Fixed all five findings in ee3ffceda0b0cabaeeda81a525479a18928edd45:

  • Preserve resolved source poses in singleton facade initialization/reset baselines, including soft bodies and cloth.
  • Honor collider-only mesh UID/placement overrides, retain static source physics, and remap constraint endpoints.
  • Preserve explicit init_local_pose=None across singleton USD config round trips.
  • Reject mounted native cameras on NoRender before declaring assets; a corrected import can retry without duplicate UIDs.
  • Delete stale per-case acceptance results before launching a new child process.

Validation: 583 affected tests, 11 GenSim USD tests, and 2 native binding/reset regressions passed on Python 3.12.16 / DexSim 0.6.0rc1. Black 26.10.1, context validation and API documentation coverage 4438/4438 passed. Existing source/descriptor tests were reused; focused additions cover the reported config, registry, native reset, retry and acceptance-runner gaps. Context guidance already documents authored placement and pre-declaration validation, so no prose changes were needed.

Latest main synchronization (2026-11-09)

  • Merged main at 460939c83; merge commit 16ca62a338830bcc53fc870a347e1dc2369b0143.
  • Python 3.12.16, DexSim 0.6.0rc1: 543 affected tests, 11 GenSim USD tests, and 42 context tests passed.
  • Four native loading/binding/step/reset regressions passed: existing SugarBox and RubiksCube, two-instance soft duck and cloth shirt.
  • Black 26.10.1, context validation, and API documentation coverage 4438/4438 passed.
  • The previous collision-field schema check failure is resolved by main's DexSim migration (Adapt EmbodiChain to DexSim 0.6.0rc1 on Python 3.12 #1124), verified in the affected test run. Historical asset compatibility findings below remain recorded; the complete 54-input asset matrix was not rerun.
  • Context review retained main's solver/contact contracts and the USD source/placement guidance. Existing tests cover this merge; no new cases were needed.

Initial asset acceptance (2026-11-07)

Committed acceptance report

  • 54 input files/versions: 43 passed, 11 compatibility findings, using dexsim_engine==0.6.0+c3e92584a3dc31479ad07cb1a3551965077109e6 on an RTX 5090. Entry-file SHA256 values remained unchanged. The suite covers the six non-3DGS document categories and all 10 cached EmbodiChain USD entry points (10/10 passed).
  • All five typed entry points passed. Six physical soft/cloth inputs passed an additional nonempty-node check, including two-instance duck/cow/curtain/shirt cases. Thirteen selected native offscreen images were inspected. Original garment geometry remains visual-only when its USD authors no cloth physics.
  • The 11 findings are preserved in the report: three joint-name/mimic representations; four PhysX settings without an equivalent Newton translation; two tetrahedral-topology representations; one legacy surface-deformable schema; and the raw Newton duck's unconfigured tet-visual representation. These are reported as parser/backend compatibility limits, without repairing source files.
  • 3DGS and composites containing it were excluded. Derived inputs and the three six-type composites lacking original packages were deferred at the user's request.
  • 344 focused behavioral tests, 11 GenSim USD tests, 42 context tests, 11 API-checker tests, and 2 scalar-particle-flag regressions passed. Black 26.10.1 and API documentation coverage 4335/4335 passed. Sphinx dummy build succeeded with 852 project warnings.
  • Initial broader configuration sampling: 179 passed, 1 failed (test_backend_property_groups_track_dexsim_spawn_descriptors). That schema gap is resolved by main's DexSim migration (Adapt EmbodiChain to DexSim 0.6.0rc1 on Python 3.12 #1124), and the check passes in the latest synchronization run above.

Acceptance covers loading, facade binding, finite simulation state, stepping/reset and selected offscreen views. Profile recertification and reference-based appearance-fidelity comparison were outside this run.

Type of change

  • Bug fix / enhancement
  • Public configuration and result API
  • Dependency update
  • Documentation and context update

Checklist

  • Ran black . before each commit.
  • Reviewed test necessity; reused existing source/descriptor coverage and added focused recipe, relationship, facade and rejection checks.
  • Updated public API documentation and simulation source/deformable guidance.
  • Kept native materialization and resource ownership in DexSim Spawn.

@yuecideng yuecideng added enhancement Improvements to existing capabilities; use feature for new capabilities. physics Physics backends, dynamics, contacts, fluids, deformables and physics solvers. dependencies Dependency versions, upgrades and compatibility. dexsim DexSim SDK interfaces, version adaptation and integration. assets Robot and scene assets, meshes, materials, asset catalogs and downloads. labels Oct 16, 2026
@yuecideng yuecideng added scene Shared scene composition, layout, state restoration, validation and expansion services. sim-object Simulation entity configuration, state, creation, destruction and lifecycle. and removed scene Shared scene composition, layout, state restoration, validation and expansion services. labels Oct 25, 2026
@yuecideng yuecideng changed the title Preserve USD source intent and scene constraints Unify USD imports with typed recipes and source-preserving scene binding Nov 7, 2026
@yuecideng yuecideng changed the title Unify USD imports with typed recipes and source-preserving scene binding Unify USD loading through import recipes and authored scene semantics Nov 7, 2026
@yuecideng
yuecideng requested a review from han-xudong November 9, 2026 02:30
@yuecideng
yuecideng marked this pull request as ready for review November 9, 2026 02:35
@greptile-apps

greptile-apps Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The reviewed changes appear safe to merge; the previous replacement bug is fixed and no new blocking issue was established.

Summary

USD loading now shares UsdImportCfg, source parsing, and stable source-path results.

  • USD scenes load from recipes and return stable source-path lookups.
  • Unset USD settings keep the values authored in the source scene.
  • USD soft bodies and cloth bind through the existing deformable facades.
  • NoRender keeps authored material details without sending render-only fields to native code.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[UsdImportCfg] --> B[Parse source]
  B --> C[Check overrides and bindings]
  C --> D[Declare shared Spawn scene]
  D --> E[UsdImportResult]
  D --> F[prepare]
  F --> G[Bind existing facades]
Loading

Reviews (3) · Last reviewed commit: "fix(examples): restore fixed bases and d..." · Reviewed by Greptile

Comment thread embodichain/lab/sim/spawn/usd.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread embodichain/lab/sim/cfg/asset.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread scripts/validation/accept_usd_import.py Resolved
Comment thread embodichain/lab/sim/spawn/usd.py Resolved

@han-xudong han-xudong left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The existing preserve config regression and the offset reuse issue can silently change simulation behavior. The inline comments include reproduction details for the remaining P1 and P2 findings. The offset issue is tracked in the existing Greptile thread. Offset reuse discussion

Local validation on Python 3.12.14 and DexSim 0.6.0rc1 passed 518 focused tests, two native binding and reset tests, two GenSim offscreen texture tests, and four Newton/CUDA deformable smoke cases. The targeted reproductions cover additional paths beyond that passing set.

Comment thread embodichain/lab/sim/spawn/usd.py Resolved
Comment thread embodichain/lab/sim/cfg/asset.py Resolved
Comment thread embodichain/lab/sim/cfg/rigid_object.py Resolved
Comment thread embodichain/lab/sim/spawn/usd.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread scripts/validation/accept_usd_import.py Resolved

@han-xudong han-xudong left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes on c6982f84 for the three remaining regressions. The two inline comments cover explicit zero placement and procedural defaults. The returned .cfg issue is tracked in the existing Greptile discussion. Offset reuse discussion

CI. The Python 3.11 fast lane reported 12,967 passed, 1 failed, and 51 skipped. test_sparse_override_keeps_actor_and_pose_and_remaps_constraint fails with AttributeError: 'ConstraintDesc' object has no attribute 'usd', which also fails the test gate. The fixture replaces dexsim.spawn.ConstraintDesc after usd_import can already have bound the real class. The fake then passes through the constraint filter and lacks usd. I reproduced the same failure locally by importing embodichain.lab.sim.spawn.usd_import before running the single test. Using a real SDK constraint descriptor would remove this dependency on import order. CI log

Local verification. On Python 3.12.14 and DexSim 0.6.0rc1, 515 focused tests and four native binding, reset, and replacement cases passed. Separate native Default CPU probes using replace_rigid_object(asset.cfg.copy()) still changed x from 3 to 5 for a singleton offset import and from 3 to 2 for a translated scene import. The inline comments include the previous-head and current-head results for the other two regressions.

Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread embodichain/lab/sim/cfg/rigid_object.py Resolved

@han-xudong han-xudong left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up review of 7283a95 against 1070fcd. I checked the fixes for explicit zero placement, ordinary mesh defaults, and reuse of returned facade configs. The isolated follow-up run passed 265 configuration and import tests and 15 acceptance-runner tests. The inline comments record three remaining P2 issues and two P3 issues, each verified with a focused probe. The current GitHub build and test jobs were still pending at the time of review.

Comment thread embodichain/lab/sim/cfg/rigid_object.py Resolved
Comment thread embodichain/lab/sim/cfg/articulation.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread embodichain/lab/sim/spawn/usd_import.py Resolved
Comment thread scripts/validation/accept_usd_import.py Resolved

@han-xudong han-xudong left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Thanks for addressing the review feedback. Please resolve the merge conflicts with main and make sure the failing CI checks pass before merging.

@yuecideng
yuecideng merged commit 33a81cd into main Nov 11, 2026
5 of 8 checks passed
@yuecideng
yuecideng deleted the codex/usd-import-contracts branch November 11, 2026 03:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

assets Robot and scene assets, meshes, materials, asset catalogs and downloads. dependencies Dependency versions, upgrades and compatibility. dexsim DexSim SDK interfaces, version adaptation and integration. enhancement Improvements to existing capabilities; use feature for new capabilities. physics Physics backends, dynamics, contacts, fluids, deformables and physics solvers. sim-object Simulation entity configuration, state, creation, destruction and lifecycle.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants