Repository navigation
Description
[Proposal] Support USD closed-loop gripper constraints in robot imports
Proposal
Please support importing USD robot articulations with closed-loop gripper constraints, starting with PhysicsSphericalJoint relationships marked physics:excludeFromArticulation = true in the AGIBot G1 asset.
Loading this asset through EmbodiChain currently raises NotImplementedError in the DexSim USD parser before simulation starts. Please preserve these relationships as physical closure constraints alongside the articulation tree, rather than rejecting the entire robot or silently dropping the constraints.
The immediate failure is in dexsim.kit.usd.parser. We are reporting it here because it blocks EmbodiChain's robot import workflow. If there is a preferred public DexSim issue tracker, please redirect this report or coordinate the corresponding SDK change.
Motivation
We encountered this while building a real-to-sim replay pipeline for recorded AGIBot manipulation tasks. We need the source robot geometry, link frames, gripper linkage and joint relationships to remain consistent with the recorded robot. Import currently fails before trajectory replay, contact simulation or rendering can begin.
The original G1 gripper has a tree of ordinary joints plus four excluded spherical joints that close its linkages. Exclusion from the articulation tree should not mean deletion of the physical relationship. Removing those joints to make import succeed would change the gripper mechanism.
Asset and provenance
- Asset: official GenieSim AGIBot
G1_120sUSD robot. - Recorded upstream source: agibot-world/GenieSimAssets.
- Recorded source revision:
a0813aad7c16165daffbe6c2737754e0344809ee. - Source path:
robot/G1_120s/robot.usda. - License: CC BY-NC-SA 4.0; the asset bundle retains the supplied license and provenance.
- Entry-file SHA256:
6ecb91bc40a3e9b2fe883c5f8c63d6bc29186a5ed124025ff9c3811f4df8d603.
The prepared attachment contains the complete original G1_120s directory, including its referenced USD layers; robot.usda alone is insufficient. It also contains a much smaller synthetic reproduction without robot meshes.
The four excluded joints are:
/G1/joints/idx39_gripper_l_inner_joint2
/G1/joints/idx49_gripper_l_outer_joint2
/G1/joints/idx79_gripper_r_inner_joint2
/G1/joints/idx89_gripper_r_outer_joint2
All four have type PhysicsSphericalJoint.
Reproduction
Environment verified on 2026-10-30:
| Component | Value |
|---|---|
| Container OS | Ubuntu 22.04.5 LTS |
| Python | 3.10.19 |
| DexSim package | dexsim_engine==0.5.1rc1 |
| OpenUSD package | usd-core==26.8 |
| Execution | CPU parser only; no world, renderer or GPU required |
The original EmbodiChain runtime was a source copy without Git metadata, so its exact commit is not asserted. SHA256 fingerprints of its relevant source files and the installed DexSim parser are included in the attachment. The parser-only reproduction below bypasses our application adapter entirely.
After extracting the attachment, run this inside an environment with the above DexSim/OpenUSD versions:
python repro_usd_loop.pyThe script generates three small USD stages, parses each, and also parses the bundled original G1 asset. It writes results.json; exceptions are collected deliberately, so process exit status alone is not the test result.
For the original asset alone, the essential operation is:
from pxr import Usd
from dexsim.kit.usd.parser import parse_stage
stage = Usd.Stage.Open("assets/G1_120s/robot.usda")
assert stage is not None
parse_stage(stage)Observed results:
| Input | Result |
|---|---|
| Three rigid bodies with a fixed base and ordinary revolute tree joints | Parses successfully |
| Same tree plus one excluded spherical closure between two links | Fails with contains loop/excluded joint |
| Tree with a spherical joint and no closure | Fails with unsupported OpenUSD type SphericalJoint |
| Original G1 USD | Fails at idx39_gripper_l_inner_joint2 |
The ordinary spherical-joint case is an adjacent importer limitation; the primary request here is support for the excluded closure relationships used by G1.
Debugging context
The original application used a project-specific ForegroundSimulationManager adapter with CPU physics, a 0.001 s timestep, no-render, fixed base and self-collision disabled. The exception occurred in add_robot(), before prepare() completed:
EmbodiChain SimulationManager.add_robot
-> _declare_spawn_articulation
-> articulation_desc_from_usd
-> _parse_singleton
-> dexsim.kit.usd.parser.parse_usd
-> parse_stage
-> _parse_physics_articulation
NotImplementedError: Articulation /G1 contains loop/excluded joint
/G1/joints/idx39_gripper_l_inner_joint2.
In the tested wheel, _parse_physics_articulation() explicitly raises on joint.excludeFromArticulation at parser.py:335–338. Its ordinary articulation-joint allowlist contains fixed, prismatic and revolute joints. The parser also rejects enabled standalone joints because this version's SceneDesc has no standalone-joint representation.
The original log contains CollisionAPI warnings as well. The small mesh-free reproduction triggers the same closure rejection, isolating this blocker from those geometry warnings, camera calibration, controllers and GPU execution.
Workaround and its limits
We temporarily converted the source model to MuJoCo, preserving the ordinary joint tree and translating:
- Four excluded spherical closures into site-to-site
connectequalities. - Six mimic relationships into joint equalities.
The converted model has 47 bodies including the world, 34 velocity degrees of freedom and 10 equalities. A fresh smoke test with MuJoCo 3.12.0 ran 1,000 steps at a 0.001 s timestep with finite joint positions; the maximum absolute equality residual at the end was approximately 9.37e-6 in MuJoCo constraint coordinates. This maximum includes both connect and joint equality rows, so it is not presented as a uniform distance metric.
This workaround also replaces the source acceleration drives with force-based PD controls and uses collision fallbacks where source collision geometry is absent. It is therefore not a controlled solver comparison or proof of equivalent dynamics. It demonstrates why retaining explicit closure relationships is useful; it does not establish a DexSim solver defect or full manipulation-task success.
Requested behavior and validation
- Preserve excluded closure relationships, their body endpoints and local frames separately from the articulation tree.
- Instantiate supported closure constraints in the selected physics backend. Keep an explicit capability error for unsupported semantics; do not silently discard constraints.
- Expose a supported EmbodiChain import route for such robots. If a whole-scene import is required instead of
add_robot(), provide a documented example that retains robot control access. - Validate the small fixture and the real G1 asset through import and physical stepping. For G1, exercise gripper opening/closing, measure closure-anchor error, and check that reset/reimport does not lose or duplicate constraints. Retain the source mimic semantics or report any remaining unsupported relationship explicitly.
- Add regression coverage for ordinary tree imports, endpoint/frame preservation and unsupported-backend reporting. A successful parse alone should not count as complete closed-loop support.
Related work
PR #795, “Preserve USD source intent and scene constraints,” is relevant to the import infrastructure. At review time it is a draft awaiting a compatible DexSim dependency, and its description explicitly states: “No soft-body reader or closed-loop implementation is included.” This request targets the closed-loop gap beyond that PR's stated scope and should reuse its infrastructure where appropriate.
Attachments prepared for review
embodichain-g1-closed-loop-repro.zip is prepared locally and has not been uploaded. It contains the original asset and license, SHA256 manifest, portable reproduction, observed parser results, relevant source fingerprints, and a sanitized traceback excerpt. The attachment must be uploaded when the issue is actually submitted.
Checklist
- Searched for existing issues concerning
excludeFromArticulationand closed-loop import; no matching issue was found. Related PR Unify USD loading through import recipes and authored scene semantics #795 is acknowledged above. - Reproduced the failure independently of our application adapter and rendering pipeline.
- Included the original asset provenance and a synthetic minimal reproduction.
Activity
[-][Proposal] Proposal title[/-][+][Proposal] Support USD closed-loop gripper constraints in robot imports[/+]