Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
80bfd92
Preserve USD source intent across asset and scene imports
yuecideng Oct 16, 2026
0cbfd82
Align USD config module documentation with the public facade
yuecideng Oct 16, 2026
e98704b
Check resolved URDF root intent in existing helper assertions
yuecideng Oct 16, 2026
f90b173
Merge main and adapt USD imports to DexSim 0.6
yuecideng Nov 7, 2026
9414d21
fix(gym): validate resolved USD actor before declaration
yuecideng Nov 7, 2026
36cda18
feat(sim): unify USD imports through typed recipes and source-path re…
yuecideng Nov 7, 2026
a80e886
Merge latest main into USD import integration
yuecideng Nov 7, 2026
f309106
test(sim): record USD import acceptance and preserve scalar particle …
yuecideng Nov 7, 2026
3c40686
fix(sim): route packaged USD through typed source translation
yuecideng Nov 7, 2026
16ca62a
Merge latest main and align USD imports with DexSim 0.6.0rc1
yuecideng Nov 9, 2026
ee3ffce
fix(sim): address USD import placement and preflight review findings
yuecideng Nov 9, 2026
a2b59d5
fix(sim): preserve USD caller intent and scene reference contracts
yuecideng Nov 9, 2026
c6982f8
fix(examples): restore fixed bases and dependency-free USD help
yuecideng Nov 9, 2026
1a76c53
fix(sim): make resolved USD configs reusable and retain explicit pose…
yuecideng Nov 9, 2026
af24cbc
fix(sim): resolve nullable URDF scale before articulation spawning
yuecideng Nov 10, 2026
7283a95
Merge latest main to restore PR CI mergeability
yuecideng Nov 10, 2026
52896be
fix(sim): preserve derived USD resources and portable source configs
yuecideng Nov 10, 2026
3daea27
Merge latest main and verify full local test plan
yuecideng Nov 11, 2026
f47386a
Merge current main and retain unified USD source selection
yuecideng Nov 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion agent_context/MAP.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ topics:
title: Simulation System
aliases: [simulation system, simulation manager, Newton physics backend, motion module, sim motion, camera attachment, 运动能力模块, 仿真系统, 仿真管理器]
keywords: [SimulationManager, SimulationManagerCfg, RenderCfg, DenoisingCfg, DenoisingMode, DLSSCfg,
NRDCfg, DLSS, NRD, frame_time_delta_ms, explicit physics stepping, simulation_time, arena, DexSim, LightCfg, LightBatch, 灯光批次, PhysicsBackendCfg,
NRDCfg, DLSS, NRD, frame_time_delta_ms, explicit physics stepping, simulation_time, arena, DexSim, UsdImportCfg, UsdImportResult, root_prim_path, LightCfg, LightBatch, 灯光批次, PhysicsBackendCfg,
DefaultPhysicsCfg, NewtonPhysicsCfg, VisualObject, VisualObjectCfg, VisualMaterial, VisualMaterialCfg, VisualMaterialInst, preview-material, 材质预览, UsdSourceCfg, source_prim_path, add_visual_object, 纯渲染对象, DexUniSolverCfg, DexUni, runtime control, deformable, particle set,
UsdSourceSnapshot, read_usd_source, LinkMesh,
PhysicalCollisionGeometry, capture_physical_collision_geometry,
Expand Down
6 changes: 6 additions & 0 deletions agent_context/topics/simulation-system/deformables.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,12 @@ accept the default DexUni solver or an explicit supported particle solver
post-finalization additions. Default soft/cloth compatibility is absent.
Future backend support belongs at dispatch, not inside a monolithic config.

`UsdImportCfg` whole-scene loading and a deformable config's optional `source`
bind authored soft-body/cloth descriptors through these same facades. Source
physics and simulation/render topology are retained; the source route accepts
identity, pose and particle flag/radius overrides rather than regenerating a
mesh with the procedural meshing defaults.

`spawn/descriptors.py` translates volume/surface configs to typed `SoftBodyDesc`
and `ClothDesc`; volume meshing uses `SoftBodyMeshingDesc`. Runtime mutation
uses `Scene.create_particle_set_batch()`, not renderer buffers or legacy native
Expand Down
18 changes: 17 additions & 1 deletion agent_context/topics/simulation-system/physics-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,10 +73,26 @@ MuJoCo force reports are unavailable. See `physics/` and
`"overlay"` applies non-`None` config fields after source translation. The
same policy covers USD rigid objects and USD/URDF articulations. Generic rigid
objects/articulations preserve by default; Robot configs overlay their authored
drives. Preserve-mode articulation configs warn about ignored overlay fields.
drives. Preserve mode keeps the source actor and scale even when saved config
fields contain legacy defaults; explicit actor/scale changes require overlay.
Preserve-mode articulation configs warn about ignored overlay fields.
Root import intent is handled separately in
[articulation adapters](articulation-adapters.md).

Unset USD actor type, scale, root flags and placement retain parsed source
values. An explicit singleton `source_pose_mode` replaces, preserves or offsets
the source transform. Singleton translation resolves a runtime-owned config
copy, preserving caller placement intent for repeated imports and Gym
replacement comparisons. Returned facade configs store resolved absolute poses
in `config` mode, so copying them for replacement retains source offsets and
scene placement without applying them again. Sparse pose keys preserve explicit
zero values; only omitted pose fields retain source placement in `auto` mode.
Non-USD rigid and URDF articulation imports keep their
dynamic/unit-scale and fixed-root defaults respectively. Whole-scene
`add_usd(UsdImportCfg(...))` applies sparse dictionary fields before Spawn
declaration. Source subtree and variants belong to its `source`; namespace and
scene placement belong to the import recipe.

`RigidBodyPhysicsCfg` is the single grouped schema. `mass_props`,
`rigid_props`, `collision_props` and `material_props` each own one physical
concept; concrete subclasses/local backend discriminators carry native fields.
Expand Down
20 changes: 16 additions & 4 deletions agent_context/topics/simulation-system/simulation-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
| Public simulation facade | `embodichain/lab/sim/__init__.py` |
| World, registries, readiness and stepping | `embodichain/lab/sim/sim_manager.py` → `SimulationManager`, `SimulationManagerCfg` |
| Declaration, source resolution and binding | `embodichain/lab/sim/spawn/scene.py`, `spawn/source.py`, `spawn/descriptors.py` |
| USD import recipes, preflight and source-path results | `cfg/usd.py`, `spawn/usd_import.py`, `spawn/usd_result.py` |
| Fresh static USD reads and owned authored link meshes | `embodichain/lab/sim/spawn/source_geometry.py` |
| Manager-level backend hooks and capabilities | `embodichain/lab/sim/physics/` |
| Object-level Scene batch adapters | `embodichain/lab/sim/objects/backends/scene.py`, `newton.py` |
Expand All @@ -31,15 +32,26 @@ that same object in place. UIDs identify resources in the manager registry.
`VisualObject` owns render-only root poses, visibility and material assignments,
with no rigid-body buffers or collision API. Its config lives in
`cfg/visual_object.py`; mesh files use `MeshCfg.fpath`, as for rigid objects.
`cfg/source.py:UsdSourceCfg` owns the source file and exact `source_prim_path`;
`cfg/source.py:UsdSourceCfg` owns the source file, exact singleton
`source_prim_path` and optional parser subtree/variants;
visual, rigid and articulation configs accept it through `source`, exclusively
with their existing shape/file input. `ObjectBaseCfg` keeps runtime identity
and initial pose independent of file formats. `add_visual_object()` compiles mesh/primitive appearance or
selects a USD object's appearance. Whole-scene `add_usd()`
preserves physical types and wraps only objects without physics and colliders
selects a USD object's appearance. Whole-scene `add_usd(UsdImportCfg(...))`
owns namespace, scene placement and sparse per-asset overrides keyed by source
prim paths. Single-asset placement belongs to `source_pose_mode` on the asset
configuration. Both routes share the fresh DexSim source parser and validate
before native declaration. `UsdImportResult` maps source paths to facades and
records logical UIDs for constraints and native-only resources. Unique sources
retain prim-path keys; multiple resources from one prim receive ordinal keys,
with `resource_source_paths` retaining the original prim identity. It remaps
standalone constraint endpoints after UID changes, preserves physical types,
and wraps only objects without physics and colliders
as visuals. Conflicting visual UIDs receive the scene-name prefix while returned
keys preserve source prim paths. Other import UID conflicts fail before declaration.
Imported facades retain their source address in `cfg.source`. This metadata
Volume and surface particle sets bind through the existing deformable facades;
they require Newton/CUDA and retain source topology and physics. Imported
facades retain their source address in `cfg.source`. This metadata
does not request a second spawn or bind an unrelated existing scene entity.
Visuals retain facade-owned pose/visibility/material-assignment state across native
topology rebuilds, with separate reset baselines. They use the same prepare,
Expand Down
37 changes: 37 additions & 0 deletions docs/source/api_reference/embodichain/embodichain.lab.sim.cfg.rst
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ UV seams and render detail.
NewtonJointDrivePropertiesCfg
ObjectBaseCfg
UsdSourceCfg
UsdImportCfg
LightCfg
VisualObjectCfg
RigidObjectCfg
Expand Down Expand Up @@ -107,6 +108,42 @@ existing ``shape``/``fpath`` input. Ordinary mesh files continue to use
of the requested type; ambiguous sources fail instead of selecting the first
object. Whole-scene imports preserve this source address on their facades.

USD import recipes
------------------

``SimulationManager.add_usd(UsdImportCfg(...))`` declares a complete scene
selection. ``source.root_prim_path`` selects a source subtree and ``variants``
selects source variants. The import recipe separately owns runtime namespace,
the optional left-multiplied scene pose and overrides keyed by unchanged source
prim paths. Unset source properties are retained. Source and override validation
precedes native declaration; returned facades bind in place at ``prepare()``.

.. code-block:: python

from embodichain.lab.sim.cfg import UsdImportCfg, UsdSourceCfg

imported = sim.add_usd(
UsdImportCfg(
name="workcell",
source=UsdSourceCfg(
file_path="workcell.usda",
root_prim_path="/World/Cell",
),
namespace="cell_1",
)
)
sim.prepare()
robot = imported["/World/Cell/Robot"]

.. autoclass:: embodichain.lab.sim.cfg.usd.UsdImportCfg
:members:

Single-asset configurations retain their exact ``source_prim_path`` selector.
Their ``source_pose_mode`` chooses automatic, replacement, preservation or
offset placement. Legacy source-option spellings remain accepted by the
compatibility adapter. New scene recipes keep namespace and placement on
``UsdImportCfg``.

Deformable physics and meshing
-----------------------------

Expand Down
18 changes: 18 additions & 0 deletions docs/source/api_reference/public_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2697,6 +2697,7 @@ embodichain.lab.sim
VisualMaterialInst
ReuseSegmentState
BatchEntity
UsdImportResult
SimulationManager
SimulationManagerCfg
SIM_CACHE_DIR
Expand Down Expand Up @@ -3753,6 +3754,23 @@ embodichain.lab.sim.spawn.usd
rigid_desc_from_usd
visual_desc_from_usd

embodichain.lab.sim.spawn.usd_result
-------------------------------------

.. currentmodule:: embodichain.lab.sim.spawn.usd_result

USD import results retain stable source keys for declared facades and logical
resource UIDs. A unique source keeps its prim path as its key. If one prim emits
several resources, keys append ``#0``, ``#1``, and so on in parser order;
``resource_source_paths`` maps each key back to its exact source prim path.
The UID, type and source-path maps use the same keys, independently of namespace
and runtime UID changes. Results share the manager's ``prepare()`` lifecycle and
do not own another object registry or native-resource lifetime.

.. autosummary::

UsdImportResult

embodichain.lab.sim.utility.dynamic_pybind
----------------------------------------

Expand Down
6 changes: 5 additions & 1 deletion embodichain/gen_sim/scene_engine/pipeline/utils/usd_scene.py
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,11 @@ def load_into(cls, sim: object, stage_path: str | Path) -> "UsdSceneBinding":
"""Import a schema-v2 USD stage and bind every indexed entity."""
path = Path(stage_path).expanduser().resolve()
index = UsdSceneIndex.load(path, require_schema=True)
assets = sim.add_usd(name=path.stem, file_path=str(path))
from embodichain.lab.sim.cfg import UsdImportCfg, UsdSourceCfg

assets = sim.add_usd(
UsdImportCfg(name=path.stem, source=UsdSourceCfg(file_path=str(path)))
)
bindings: list[UsdEntityBinding] = []
for desc in index.entities:
runtime = assets.get(desc.prim_path)
Expand Down
25 changes: 15 additions & 10 deletions embodichain/lab/gym/envs/embodied_env.py
Original file line number Diff line number Diff line change
Expand Up @@ -3116,27 +3116,32 @@ def _setup_lights(self) -> None:

def _setup_background(self) -> None:
"""Setup the static rigid objects in the environment."""
for cfg in self.cfg.visual_object:
self.sim.add_visual_object(cfg)
for cfg in self.cfg.background:

def validate_resolved(cfg: RigidObjectCfg) -> None:
if cfg.body_type == "dynamic":
logger.log_error(
f"Background object must be kinematic or static rigid object."
"Background object must be kinematic or static rigid object."
)
self.sim.add_rigid_object(cfg=cfg)

for cfg in self.cfg.visual_object:
self.sim.add_visual_object(cfg)
for cfg in self.cfg.background:
self.sim.add_rigid_object(cfg=cfg, validate_resolved=validate_resolved)

def _setup_interactive_objects(self) -> None:
"""Setup the interactive objects in the environment."""

def validate_resolved(cfg: RigidObjectCfg) -> None:
if cfg.body_type != "dynamic":
logger.log_error(
"Interactive rigid object must be dynamic rigid object."
)

for cfg in self.cfg.articulation:
self.sim.add_articulation(cfg=cfg)

for cfg in self.cfg.rigid_object:
if cfg.body_type != "dynamic":
logger.log_error(
f"Interactive rigid object must be dynamic rigid object."
)
self.sim.add_rigid_object(cfg=cfg)
self.sim.add_rigid_object(cfg=cfg, validate_resolved=validate_resolved)

for cfg in self.cfg.rigid_object_group:
self.sim.add_rigid_object_group(cfg=cfg)
Expand Down
2 changes: 2 additions & 0 deletions embodichain/lab/sim/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
)
from .cfg import DenoisingCfg, DenoisingMode, DLSSCfg, NRDCfg
from .common import BatchEntity
from .spawn.usd_result import UsdImportResult
from .profiler import Profiler, ProfilerCfg

from .sim_manager import *
Expand All @@ -39,6 +40,7 @@
"VisualMaterialInst",
"ReuseSegmentState",
"BatchEntity",
"UsdImportResult",
"Profiler",
"ProfilerCfg",
"SimulationManager",
Expand Down
2 changes: 2 additions & 0 deletions embodichain/lab/sim/cfg/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
from .asset import AssetPhysicsMode, ObjectBaseCfg, _resolve_asset_physics_mode
from .fluid import FluidObjectCfg, FluidSpawnCfg, FluidRenderCfg
from .source import UsdSourceCfg
from .usd import UsdImportCfg
from .deformable import (
SurfaceElementPropertiesCfg,
VolumeDeformableMeshingCfg,
Expand Down Expand Up @@ -125,6 +126,7 @@
"RigidBodyPhysicsCfg",
"ObjectBaseCfg",
"UsdSourceCfg",
"UsdImportCfg",
"LightCfg",
"RigidObjectCfg",
"VisualObjectCfg",
Expand Down
39 changes: 30 additions & 9 deletions embodichain/lab/sim/cfg/articulation.py
Original file line number Diff line number Diff line change
Expand Up @@ -76,18 +76,18 @@ class ArticulationRootPropertiesCfg:

``fixed_base`` and ``self_collision_enabled`` are consumed by both
backends. ``sleep_threshold`` and the solver-iteration fields are supported
only by the Default backend and are ignored by Newton. By default, the
articulation root is fixed and self-collision is disabled. Explicit
``None`` values preserve the source value or backend/import default.
only by the Default backend and are ignored by Newton. Unset values
preserve USD intent; URDF and procedural imports resolve to a fixed root
without self-collision.
"""

fixed_base: bool | None = True
fixed_base: bool | None = None
"""Whether the articulation root is rigidly fixed to the world frame.

Set to ``None`` to preserve the source value or backend/import default.
"""

self_collision_enabled: bool | None = False
self_collision_enabled: bool | None = None
"""Whether non-filtered link pairs in the articulation may self-collide.

Newton may still apply source-authored or Spawn-owned filtering to adjacent
Expand Down Expand Up @@ -445,9 +445,17 @@ class ArticulationCfg(ObjectBaseCfg):
source: UsdSourceCfg | None = field(default=None, kw_only=True)
"""USD source asset; mutually exclusive with :attr:`fpath`."""

body_scale: tuple | list = (1.0, 1.0, 1.0)
body_scale: tuple | list | None = None
"""Scale of the articulation in the simulation world frame."""

def __post_init__(self) -> None:
path = self.source.file_path if self.source is not None else self.fpath
if path is None or not str(path).lower().endswith(
(".usd", ".usda", ".usdc", ".usdz")
):
if self.body_scale is None:
self.body_scale = (1.0, 1.0, 1.0)
Comment thread
han-xudong marked this conversation as resolved.
Resolved

compute_uv: bool = False
"""Whether to compute the UV mapping for the articulation link.

Expand Down Expand Up @@ -482,9 +490,8 @@ class ArticulationCfg(ObjectBaseCfg):

Fixed-base and self-collision intent is portable. Root sleep and solver
iterations are Default-only fields and are ignored by Newton. The portable
fields default to a fixed base with self-collision disabled. Set either
field to ``None`` to preserve an authored USD/backend value; URDF imports
then use the established fixed-base, self-collision-off defaults.
fields default to ``None`` so USD imports retain their authored values.
URDF imports retain the fixed-base, self-collision-off defaults.
"""

joint_drive_props: JointDrivePropertiesCfg | None = None
Expand Down Expand Up @@ -573,9 +580,23 @@ def from_dict(
else:
from scipy.spatial.transform import Rotation as R

cfg.init_local_pose = np.asarray(cfg.init_local_pose)
cfg.init_pos = tuple(cfg.init_local_pose[:3, 3])
cfg.init_rot = tuple(
R.from_matrix(cfg.init_local_pose[:3, :3]).as_euler("xyz", degrees=True)
)

path = cfg.source.file_path if cfg.source is not None else cfg.fpath
if path is not None and str(path).lower().endswith(
(".usd", ".usda", ".usdc", ".usdz")
):
if "body_scale" not in init_dict:
cfg.body_scale = None
if (
"init_local_pose" in init_dict and init_dict["init_local_pose"] is None
) or not {"init_pos", "init_rot", "init_local_pose"}.intersection(
init_dict
):
cfg.init_local_pose = None

return cfg
32 changes: 32 additions & 0 deletions embodichain/lab/sim/cfg/asset.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
from __future__ import annotations

from collections.abc import Mapping
from dataclasses import field
from typing import Dict, Literal

import numpy as np
Expand Down Expand Up @@ -59,6 +60,15 @@ class ObjectBaseCfg:
init_local_pose: np.ndarray | None = None
"""4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot."""

source_pose_mode: Literal["auto", "config", "preserve", "offset"] = field(
default="auto", kw_only=True
)
"""USD input placement: retain an unset pose, replace, preserve, or offset it.

Imported facades use ``"config"`` with their resolved ``init_local_pose``
so reusing the returned configuration preserves its effective placement.
"""

@classmethod
def from_dict(cls, init_dict: Dict[str, str | float | tuple]) -> ObjectBaseCfg:
"""Initialize the configuration from a dictionary."""
Expand Down Expand Up @@ -109,4 +119,26 @@ def from_dict(cls, init_dict: Dict[str, str | float | tuple]) -> ObjectBaseCfg:
cfg.init_pos = tuple(T[:3, 3])
cfg.init_rot = tuple(R.from_matrix(T[:3, :3]).as_euler("xyz", degrees=True))

source = getattr(cfg, "source", None)
path = (
getattr(source, "file_path", None)
if source is not None
else getattr(
getattr(cfg, "shape", None), "fpath", getattr(cfg, "fpath", None)
)
)
if (
path is not None
and str(path).lower().endswith((".usd", ".usda", ".usdc", ".usdz"))
and (
(
"init_local_pose" in init_dict
and init_dict["init_local_pose"] is None
)
or not {"init_pos", "init_rot", "init_local_pose"}.intersection(
init_dict
)
)
):
cfg.init_local_pose = None
Comment thread
greptile-apps[bot] marked this conversation as resolved.
Resolved
return cfg
Loading
Loading