Merge branch 'main' of github.com:isaac-sim/IsaacLab-Arena into peterd/lab_3_ga_main

Author: peterd-NV

AGENTS.md

@@ -60,6 +60,22 @@ Lint and format tooling (`pre-commit` and the hooks it runs — black, flake8, i
 
 ## Conventions
 
+### Coordinate-frame naming
+
+Use active target-source notation for Arena-owned poses and transforms:
+
+- `T_A_B` maps points from frame `B` into frame `A`.
+- `T_A_B = (t_A_B, q_A_B)` consists of translation `t_A_B` and rotation
+  `q_A_B`, with the rotation represented as a quaternion.
+- For example, `T_W_O` maps points from object frame `O` into world frame `W`.
+- Transform composition follows `T_C_A = T_C_B * T_B_A`.
+- Frame letters are contextual. Define each near its first use when its meaning is not obvious.
+- Preserve external API names such as Isaac Lab's `root_pose_w`. Its lowercase `_w`, `_e`, and `_b` suffixes
+  denote the simulation world, local environment, and robot base frames, respectively.
+- A lowercase API suffix names only the frame in which a quantity is expressed. When both source and target
+  frames matter in Arena calculations, bind the value to an explicit transform name, for example
+  `T_W_O = object.data.root_pose_w`.
+
 ### Wrapped Environment
 
 `ArenaEnvBuilder.make_registered()` returns the gym-wrapped env (not the base env). Use `env.unwrapped` explicitly to access Isaac Lab-specific attributes (`cfg`, `device`, `step_dt`, etc.) that are not forwarded by gymnasium's `OrderEnforcing` wrapper:

CONTRIBUTING.md

@@ -3,6 +3,11 @@
 This document describes the rules for contributing to Isaac Lab-Arena
 
 
+### Coordinate-frame naming
+
+See [Coordinate-frame naming](AGENTS.md#coordinate-frame-naming) in `AGENTS.md`.
+
+
 #### Signing Your Work
 
 * We require that all contributors "sign-off" on their commits.

docs/pages/concepts/scene/concept_assets_design.rst

@@ -58,8 +58,8 @@ Backgrounds
 
 Backgrounds are registered as ``BASE`` assets, but their composed USDs may contain
 dynamic rigid bodies and articulations whose states can change as they interact with
-the robot or other objects. Set ``reset_nested_physics=True`` on a ``Background`` to
-reset these nested physics roots.
+the robot or other objects. Arena resets these nested physics roots by default. Set
+``reset_nested_physics=False`` on a ``Background`` to opt out.
 
 Arena registers the roots as private Isaac Lab reset views. After simulation and RTX
 initialization, Arena creates the views and records one environment-local pose and
@@ -87,6 +87,32 @@ ownership away from the background.
 Instanceable subtrees that contribute dynamic physics are materialized at spawn
 time because physics views cannot control dynamic instance proxies.
 
+Rigid-body behavior
+^^^^^^^^^^^^^^^^^^^
+
+A background's ``BASE`` type does not remove physics authored in its USD. The
+``rigid_props`` value in ``spawn_cfg_addon`` is forwarded to Isaac Lab's USD spawner.
+When ``rigid_props=None`` (the default), the spawner does not add or modify rigid-body
+properties. A prim that already has ``UsdPhysics.RigidBodyAPI`` therefore keeps its
+authored behavior; for example, an authored dynamic body can move when gravity or
+contact forces act on it.
+
+For a background fixture that must not move, such as a table used only as a fixed
+work surface, make its rigid bodies kinematic:
+
+.. code-block:: python
+
+   spawn_cfg_addon = {
+       "rigid_props": sim_utils.RigidBodyPropertiesCfg(kinematic_enabled=True),
+   }
+
+A kinematic body still collides with dynamic objects, but gravity, forces, and contacts
+do not displace it. Its pose changes only when it is explicitly commanded. Do not use
+this setting when the background should respond physically. For example, a table that
+a humanoid is expected to push must remain dynamic: retain ``rigid_props=None`` when
+the USD already authors it as dynamic, or explicitly set ``kinematic_enabled=False``
+to override an authored kinematic setting.
+
 Object references
 -----------------
 

isaaclab_arena/assets/background.py

@@ -33,7 +33,7 @@ def __init__(
         object_min_z: float,
         prim_path: str | None = None,
         initial_pose: Pose | None = None,
-        reset_nested_physics: bool = False,
+        reset_nested_physics: bool = True,
         **kwargs,
     ):
         self.reset_nested_physics = reset_nested_physics

isaaclab_arena/assets/background_library.py

@@ -30,13 +30,10 @@ class LibraryBackground(Background):
     object_min_z: float
     spawn_cfg_addon: dict[str, Any] = {}
     asset_cfg_addon: dict[str, Any] = {}
-    reset_nested_physics: bool = False
 
-    def __init__(self, reset_nested_physics: bool | None = None, **kwargs):
+    def __init__(self, **kwargs):
         # Check lazy USD paths are set by here
         assert self.usd_path is not None
-        if reset_nested_physics is None:
-            reset_nested_physics = self.reset_nested_physics
         super().__init__(
             name=self.name,
             tags=self.tags,
@@ -45,7 +42,6 @@ def __init__(self, reset_nested_physics: bool | None = None, **kwargs):
             object_min_z=self.object_min_z,
             spawn_cfg_addon=self.spawn_cfg_addon,
             asset_cfg_addon=self.asset_cfg_addon,
-            reset_nested_physics=reset_nested_physics,
             **kwargs,
         )
 
@@ -62,9 +58,6 @@ class KitchenBackground(LibraryBackground):
     initial_pose = Pose(position_xyz=(0.772, 3.39, -0.895), rotation_xyzw=(0, 0, -0.70711, 0.70711))
     object_min_z = -0.2
 
-    def __init__(self):
-        super().__init__()
-
 
 @register_asset
 class KitchenWithOpenDrawerBackground(LibraryBackground):
@@ -80,9 +73,6 @@ class KitchenWithOpenDrawerBackground(LibraryBackground):
     initial_pose = Pose(position_xyz=(0.772, 3.39, -0.895), rotation_xyzw=(0, 0, -0.70711, 0.70711))
     object_min_z = -0.2
 
-    def __init__(self):
-        super().__init__()
-
 
 @register_asset
 class PackingTableBackground(LibraryBackground):
@@ -96,9 +86,6 @@ class PackingTableBackground(LibraryBackground):
     initial_pose = Pose(position_xyz=(0.72193, -0.04727, -0.92512), rotation_xyzw=(0.0, 0.0, -0.70711, 0.70711))
     object_min_z = -0.2
 
-    def __init__(self):
-        super().__init__()
-
 
 @register_asset
 class GalileoBackground(LibraryBackground):
@@ -112,9 +99,6 @@ class GalileoBackground(LibraryBackground):
     initial_pose = Pose(position_xyz=(4.420, 1.408, -0.795), rotation_xyzw=(0.0, 0.0, 0.0, 1.0))
     object_min_z = -0.2
 
-    def __init__(self):
-        super().__init__()
-
 
 @register_asset
 class GalileoLocomanipBackground(LibraryBackground):
@@ -128,9 +112,6 @@ class GalileoLocomanipBackground(LibraryBackground):
     initial_pose = Pose(position_xyz=(4.420, 1.408, -0.795), rotation_xyzw=(0.0, 0.0, 0.0, 1.0))
     object_min_z = -0.2
 
-    def __init__(self):
-        super().__init__()
-
 
 @register_asset
 class Table(LibraryBackground):
@@ -143,9 +124,6 @@ class Table(LibraryBackground):
     usd_path = f"{ISAAC_NUCLEUS_DIR}/Props/Mounts/SeattleLabTable/table_instanceable.usd"
     object_min_z = -0.05
 
-    def __init__(self):
-        super().__init__()
-
 
 @register_asset
 class OfficeTableBackground(LibraryBackground):
@@ -162,8 +140,8 @@ class OfficeTableBackground(LibraryBackground):
         "rigid_props": sim_utils.RigidBodyPropertiesCfg(kinematic_enabled=True),
     }
 
-    def __init__(self):
-        super().__init__(scale=self.scale)
+    def __init__(self, **kwargs):
+        super().__init__(scale=self.scale, **kwargs)
 
 
 @register_asset
@@ -179,7 +157,6 @@ class LightwheelKitchenBackground(LibraryBackground):
     object_min_z = -0.2
     layout_id = 1
     style_id = 1
-    reset_nested_physics = True
 
     def __init__(
         self,
@@ -228,9 +205,9 @@ class MapleTableRobolab(LibraryBackground):
     tags = ["background", "robolab"]
     usd_path = f"{ARENA_NUCLEUS_DIR}/Arena/assets/object_library/srl_robolab_assets/scenes/maple_table.usda"
     object_min_z = -0.05
-
-    def __init__(self):
-        super().__init__()
+    spawn_cfg_addon = {
+        "rigid_props": sim_utils.RigidBodyPropertiesCfg(kinematic_enabled=True),
+    }
 
 
 @register_asset
@@ -239,6 +216,9 @@ class TableOakRobolab(LibraryBackground):
     tags = ["background", "robolab"]
     usd_path = f"{ARENA_NUCLEUS_DIR}/Arena/assets/object_library/srl_robolab_assets/fixtures/table_oak.usd"
     object_min_z = -0.05
+    spawn_cfg_addon = {
+        "rigid_props": sim_utils.RigidBodyPropertiesCfg(kinematic_enabled=True),
+    }
 
 
 # -----------------------------------------------------------------------------
@@ -252,7 +232,6 @@ class ReplicatorKitchenBackground(LibraryBackground):
     tags = ["background", "replicator"]
     initial_pose = Pose.identity()
     object_min_z = -0.2
-    reset_nested_physics = True
 
     def get_viewer_cfg(self) -> ViewerCfg:
         return ViewerCfg(eye=(0.0, -1.0, 1.65), lookat=(0.0, 0.0, 1.35))

isaaclab_arena/scene/scene.py

@@ -101,15 +101,15 @@ def get_scene_cfg(self) -> Any:
         return scene_cfg
 
     def get_background_physics_paths(self) -> dict[str, dict[str, ObjectType]]:
-        """Return opted-in backgrounds mapped to deferred-reset physics roots."""
+        """Return reset-enabled backgrounds mapped to deferred-reset physics roots."""
         return {background: dict(paths) for background, paths in self._background_physics_paths.items()}
 
     def get_background_physics_referenced_paths(self) -> dict[str, dict[str, ObjectType]]:
-        """Return opted-in backgrounds mapped to object-reference-owned runtime paths."""
+        """Return reset-enabled backgrounds mapped to object-reference-owned runtime paths."""
         return {background: dict(paths) for background, paths in self._background_physics_referenced_paths.items()}
 
     def get_background_physics_prim_paths(self) -> dict[str, str]:
-        """Return opted-in backgrounds mapped to their runtime root paths."""
+        """Return reset-enabled backgrounds mapped to their runtime root paths."""
         return dict(self._background_physics_prim_paths)
 
     def get_observation_cfg(self) -> Any:

isaaclab_arena/terms/events.py

@@ -111,7 +111,7 @@ def _validate_runtime_composition(self, env: ManagerBasedEnv) -> None:
         for background_name, background_path_template in self._background_prim_paths.items():
             background_path = self._runtime_path(background_path_template, env_prim_path)
             background_prim = env.scene.stage.GetPrimAtPath(background_path)
-            assert background_prim.IsValid(), f"Missing opted-in background prim at '{background_path}'"
+            assert background_prim.IsValid(), f"Missing reset-enabled background prim at '{background_path}'"
             referenced_paths = {
                 self._runtime_path(path, env_prim_path): object_type
                 for path, object_type in self._referenced_paths[background_name].items()

isaaclab_arena/tests/test_background_physics_reset.py

@@ -127,8 +127,8 @@ def _test_background_physics_discovery_and_reset(
             "background",
             background_path,
             object_min_z=0.0,
-            reset_nested_physics=True,
         )
+        assert background.reset_nested_physics
         referenced_free_body = ObjectReference(
             name="referenced_free_body",
             prim_path="{ENV_REGEX_NS}/background/free_body",
@@ -290,3 +290,64 @@ def test_background_physics_reset_with_newton():
         check_interactivity=False,
         include_joint_network=False,
     )
+
+
+def _test_maple_table_pose_restored_on_reset(_) -> bool:
+    """Move the nested Maple table body and verify reset restores its cached pose."""
+    import torch
+
+    from isaaclab_arena.assets.object_base import ObjectType
+    from isaaclab_arena.assets.registries import AssetRegistry
+    from isaaclab_arena.cli.isaaclab_arena_cli import arena_env_builder_cfg_from_argparse, get_isaaclab_arena_cli_parser
+    from isaaclab_arena.environments.arena_env_builder import ArenaEnvBuilder
+    from isaaclab_arena.environments.isaaclab_arena_environment import IsaacLabArenaEnvironment
+    from isaaclab_arena.scene.scene import Scene
+
+    background_cls = AssetRegistry().get_asset_by_name("maple_table_robolab")
+    background = background_cls()
+    opt_out_background = background_cls(reset_nested_physics=False)
+    assert background.reset_nested_physics
+    assert not opt_out_background.reset_nested_physics
+    scene = Scene(assets=[background])
+    arena_env = IsaacLabArenaEnvironment(name="maple_table_background_reset", scene=scene)
+    args = get_isaaclab_arena_cli_parser().parse_args(["--num_envs", "1"])
+    builder = ArenaEnvBuilder(arena_env, arena_env_builder_cfg_from_argparse(args))
+    env_cfg, _ = builder.compose_manager_cfg()
+
+    table_path = "{ENV_REGEX_NS}/maple_table_robolab/table"
+    assert scene.get_background_physics_paths()[background.name][table_path] == ObjectType.RIGID
+
+    env = builder.make_registered(env_cfg)
+    try:
+        env.reset()
+        base_env = env.unwrapped
+        reset_term = base_env.event_manager.get_term_cfg("reset_background_physics").func
+        table_reset = next(
+            reset
+            for reset in reset_term._rigid_resets
+            if reset.asset.cfg.prim_path.endswith("/maple_table_robolab/table")
+        )
+        table = table_reset.asset
+        initial_pose = table.data.root_pose_w.torch.clone()
+        env_ids = torch.tensor([0], device=base_env.device)
+
+        moved_pose = initial_pose.clone()
+        moved_pose[:, 0] += 1.0
+        table.write_root_pose_to_sim_index(root_pose=moved_pose, env_ids=env_ids)
+        table.write_root_velocity_to_sim_index(
+            root_velocity=torch.ones((1, 6), device=base_env.device),
+            env_ids=env_ids,
+        )
+        assert torch.allclose(table.data.root_pose_w.torch, moved_pose)
+
+        env.reset()
+
+        assert torch.allclose(table.data.root_pose_w.torch, initial_pose, atol=1.0e-5)
+        assert torch.count_nonzero(table.data.root_vel_w.torch) == 0
+    finally:
+        env.close()
+    return True
+
+
+def test_maple_table_pose_restored_on_reset():
+    assert run_function_with_persistent_simulation_app(_test_maple_table_pose_restored_on_reset)

isaaclab_arena/tests/test_pose.py

@@ -47,6 +47,29 @@ def test_pose_composition():
     assert T_C_A.rotation_xyzw == (0.0, 0.0, 0.0, 1.0)
 
 
+def test_pose_composition_rotates_inner_translation():
+    """Check that the outer rotation is applied to the inner translation."""
+    square_root_of_half = math.sqrt(0.5)
+    quarter_turn_about_z_xyzw = (0.0, 0.0, square_root_of_half, square_root_of_half)
+    T_B_A = Pose(position_xyz=(1.0, 0.0, 0.0), rotation_xyzw=(0.0, 0.0, 0.0, 1.0))
+    T_C_B = Pose(position_xyz=(2.0, 0.0, 0.0), rotation_xyzw=quarter_turn_about_z_xyzw)
+
+    T_C_A = T_C_B.multiply(T_B_A)
+
+    torch.testing.assert_close(
+        torch.tensor(T_C_A.position_xyz),
+        torch.tensor((2.0, 1.0, 0.0)),
+        rtol=0.0,
+        atol=1e-6,
+    )
+    torch.testing.assert_close(
+        torch.tensor(T_C_A.rotation_xyzw),
+        torch.tensor(quarter_turn_about_z_xyzw),
+        rtol=0.0,
+        atol=1e-6,
+    )
+
+
 def test_rotate_points_by_yaw_batch_matches_scalar():
     """Batch rotation with per-element yaws produces the same result as scalar rotation per row."""
     points = torch.tensor([[1.0, 2.0, 0.5], [3.0, -1.0, 1.0], [0.0, 4.0, -0.3]])