[Task Clean-up][Docs] Dexterous Part 7/10: Environment overview updates for the reorientation series

docs/source/overview/environments.rst

@@ -219,8 +219,8 @@ for the lift-cube environment:
     |                         | |allegro-direct-link|        |                                                                             | ``ovphysx`` (direct only)    |
     +-------------------------+------------------------------+-----------------------------------------------------------------------------+------------------------------+
     | |cube-shadow|           | |cube-shadow-link|           | In-hand reorientation of a cube using Shadow hand                           | **physics=** ``physx``,      |
-    |                         |                              |                                                                             | ``newton_mjwarp``            |
-    |                         | |cube-shadow-ff-link|        |                                                                             |                              |
+    |                         |                              |                                                                             | ``newton_mjwarp``,           |
+    |                         | |cube-shadow-ff-link|        |                                                                             | ``ovphysx``                  |
     |                         |                              |                                                                             |                              |
     |                         | |cube-shadow-lstm-link|      |                                                                             |                              |
     +-------------------------+------------------------------+-----------------------------------------------------------------------------+------------------------------+
@@ -355,10 +355,10 @@ for the lift-cube environment:
 .. |kuka-allegro-reorient-link| replace:: :isaaclab-source:`Isaac-Reorient-KukaAllegro <source/isaaclab_tasks/isaaclab_tasks/core/dexsuite/config/kuka_allegro/dexsuite_kuka_allegro_env_cfg.py>`
 .. |ka-lift-cam-link| replace:: :isaaclab-source:`Isaac-Lift-KukaAllegro-Camera <source/isaaclab_tasks/isaaclab_tasks/core/dexsuite/config/kuka_allegro/dexsuite_kuka_allegro_camera_env_cfg.py>`
 .. |ka-reorient-cam-link| replace:: :isaaclab-source:`Isaac-Reorient-KukaAllegro-Camera <source/isaaclab_tasks/isaaclab_tasks/core/dexsuite/config/kuka_allegro/dexsuite_kuka_allegro_camera_env_cfg.py>`
-.. |cube-shadow-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_env_cfg.py>`
-.. |cube-shadow-ff-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-OpenAI-FF-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_env_cfg.py>`
-.. |cube-shadow-lstm-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-OpenAI-LSTM-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_env_cfg.py>`
-.. |cube-shadow-vis-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-Camera-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_camera_env.py>`
+.. |cube-shadow-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_direct_env_cfg.py>`
+.. |cube-shadow-ff-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-OpenAI-FF-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_direct_env_cfg.py>`
+.. |cube-shadow-lstm-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-OpenAI-LSTM-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_direct_env_cfg.py>`
+.. |cube-shadow-vis-link| replace:: :isaaclab-source:`Isaac-Reorient-Cube-Shadow-Camera-Direct <source/isaaclab_tasks/isaaclab_tasks/core/reorient/config/shadow_hand/shadow_hand_direct_camera_env.py>`
 .. |agibot_place_mug-link| replace:: :isaaclab-source:`IsaacContrib-Place-Mug-Agibot-Left-Arm-RmpFlow <source/isaaclab_tasks/isaaclab_tasks/contrib/place/config/agibot/place_upright_mug_rmp_rel_env_cfg.py>`
 .. |agibot_place_toy-link| replace:: :isaaclab-source:`IsaacContrib-Place-Toy2Box-Agibot-Right-Arm-RmpFlow <source/isaaclab_tasks/isaaclab_tasks/contrib/place/config/agibot/place_toy2box_rmp_rel_env_cfg.py>`
 .. |reach_openarm_bi-link| replace:: :isaaclab-source:`IsaacContrib-Reach-OpenArmBi <source/isaaclab_tasks/isaaclab_tasks/contrib/reach/config/openarm/bimanual/joint_pos_env_cfg.py>`
@@ -1054,7 +1054,7 @@ inferencing, including reading from an already trained checkpoint and disabling
       - Isaac-Reorient-Cube-Allegro-Play
       - Manager Based
       - **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO)
-      -
+      - **physics=** ``newton_mjwarp``, ``ovphysx``, ``physx``
     * - Isaac-Reorient-Cube-Allegro-Direct
       -
       - Direct
@@ -1065,28 +1065,50 @@ inferencing, including reading from an already trained checkpoint and disabling
       - Direct
       - **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO)
       -
+    * - Isaac-Reorient-Cube-Shadow
+      -
+      - Manager Based
+      - **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO)
+      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
+    * - Isaac-Reorient-Cube-Shadow-Camera
+      - Isaac-Reorient-Cube-Shadow-Camera-Play
+      - Manager Based
+      - **rl_games** (PPO), **rsl_rl** (PPO)
+      - | **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
+          | **renderer=** ``isaacsim_rtx``, ``newton_renderer``, ``ovrtx``, ``rtx``
+          | **presets=** ``albedo``, ``depth``, ``full``, ``rgb``, ``rgb_depth``, ``semantic_segmentation``, ``simple_shading_constant_diffuse``, ``simple_shading_diffuse_mdl``, ``simple_shading_full_mdl``
     * - Isaac-Reorient-Cube-Shadow-Camera-Direct
       - Isaac-Reorient-Cube-Shadow-Camera-Direct-Play
       - Direct
       - **rl_games** (PPO), **rsl_rl** (PPO)
-      - | **physics=** ``newton_kamino``, ``newton_mjwarp``, ``physx``
+      - | **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
           | **renderer=** ``isaacsim_rtx``, ``newton_renderer``, ``ovrtx``, ``rtx``
-          | **presets=** ``albedo``, ``depth``, ``full``, ``rgb``, ``semantic_segmentation``, ``simple_shading_constant_diffuse``, ``simple_shading_diffuse_mdl``, ``simple_shading_full_mdl``
+          | **presets=** ``albedo``, ``depth``, ``full``, ``rgb``, ``rgb_depth``, ``semantic_segmentation``, ``simple_shading_constant_diffuse``, ``simple_shading_diffuse_mdl``, ``simple_shading_full_mdl``
     * - Isaac-Reorient-Cube-Shadow-Direct
       -
       - Direct
       - **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO)
-      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``physx``
+      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
+    * - Isaac-Reorient-Cube-Shadow-OpenAI-FF
+      -
+      - Manager Based
+      - **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO)
+      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
     * - Isaac-Reorient-Cube-Shadow-OpenAI-FF-Direct
       -
       - Direct
       - **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO)
-      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``physx``
+      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
+    * - Isaac-Reorient-Cube-Shadow-OpenAI-LSTM
+      -
+      - Manager Based
+      - **rl_games** (PPO), **rsl_rl** (PPO)
+      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
     * - Isaac-Reorient-Cube-Shadow-OpenAI-LSTM-Direct
       -
       - Direct
-      - **rl_games** (PPO)
-      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``physx``
+      - **rl_games** (PPO), **rsl_rl** (PPO)
+      - **physics=** ``newton_kamino``, ``newton_mjwarp``, ``ovphysx``, ``physx``
     * - Isaac-Reorient-Franka
       - Isaac-Reorient-Franka-Play
       - Manager Based
@@ -1106,11 +1128,16 @@ inferencing, including reading from an already trained checkpoint and disabling
       - | **physics=** ``newton_mjwarp``, ``physx``
           | **renderer=** ``isaacsim_rtx``, ``newton_renderer``, ``ovrtx``, ``rtx``
           | **presets=** ``albedo128``, ``albedo256``, ``albedo64``, ``cube``, ``depth128``, ``depth256``, ``depth64``, ``duo_camera``, ``raycaster_depth128``, ``raycaster_depth256``, ``raycaster_depth64``, ``rgb128``, ``rgb256``, ``rgb64``, ``semantic_segmentation128``, ``semantic_segmentation256``, ``semantic_segmentation64``, ``shapes``, ``simple_shading_constant_diffuse128``, ``simple_shading_constant_diffuse256``, ``simple_shading_constant_diffuse64``, ``simple_shading_diffuse_mdl128``, ``simple_shading_diffuse_mdl256``, ``simple_shading_diffuse_mdl64``, ``simple_shading_full_mdl128``, ``simple_shading_full_mdl256``, ``simple_shading_full_mdl64``, ``single_camera``
+    * - Isaac-Shadow-Handover
+      -
+      - Manager Based
+      - **rsl_rl** (PPO)
+      - **physics=** ``newton_mjwarp``, ``ovphysx``, ``physx``
     * - Isaac-Shadow-Handover-Direct
       -
       - Direct
-      - **rl_games** (PPO), **skrl** (PPO, IPPO, MAPPO)
-      - **physics=** ``newton_mjwarp``, ``physx``
+      - **rl_games** (PPO), **rsl_rl** (PPO), **skrl** (PPO, IPPO, MAPPO)
+      - **physics=** ``newton_mjwarp``, ``ovphysx``, ``physx``
     * - Isaac-Velocity-Flat-AnymalB-Warp-v0
       - Isaac-Velocity-Flat-AnymalB-Warp-Play-v0
       - Manager Based

source/isaaclab/changelog.d/dexterous-env-convergence.rst

@@ -0,0 +1,7 @@
+Fixed
+^^^^^
+
+* Fixed :meth:`~isaaclab.envs.DirectRLEnv.reset` to store the observation buffer
+  like :meth:`~isaaclab.envs.DirectRLEnv.step` already does, and exposed the
+  latest observations on the multi-agent-to-single-agent adapter through the
+  same public buffer.

source/isaaclab/isaaclab/envs/direct_rl_env.py

@@ -382,7 +382,9 @@ def reset(self, seed: int | None = None, options: dict[str, Any] | None = None)
                     self.sim.render()
 
         # return observations
-        return self._get_observations(), self.extras
+        # store the buffer like step() does, so consumers can read the latest observations
+        self.obs_buf = self._get_observations()
+        return self.obs_buf, self.extras
 
     def step(self, action: torch.Tensor) -> VecEnvStepReturn:
         """Execute one time-step of the environment's dynamics.

source/isaaclab/isaaclab/envs/utils/marl.py

@@ -81,22 +81,34 @@ def __init__(self, env: DirectMARLEnv) -> None:
             )
             self.action_space = gym.vector.utils.batch_space(self.single_action_space, self.num_envs)
 
-        def reset(self, seed: int | None = None, options: dict[str, Any] | None = None) -> tuple[VecEnvObs, dict]:
-            obs, extras = self.env.reset(seed, options)
+        @property
+        def episode_length_buf(self) -> torch.Tensor:
+            """Episode lengths from the wrapped multi-agent environment."""
+            return self.env.episode_length_buf
 
-            # use environment state as observation
-            if self._state_as_observation:
-                obs = {"policy": self.env.state()}
-            # concatenate agents' observations
+        @episode_length_buf.setter
+        def episode_length_buf(self, value: torch.Tensor) -> None:
+            self.env.episode_length_buf = value
+
+        @property
+        def obs_buf(self) -> VecEnvObs:
+            """Latest observations from the wrapped multi-agent environment."""
+            return self._convert_observations(self.env.obs_dict)
+
+        def _convert_observations(self, obs: dict[AgentID, ObsType]) -> VecEnvObs:
+            """Convert multi-agent observations to the single-agent policy observation."""
             # FIXME: This implementation assumes the spaces are fundamental ones. Fix it to support composite spaces
-            else:
-                obs = {
-                    "policy": torch.cat(
-                        [obs[agent].reshape(self.num_envs, -1) for agent in self.env.possible_agents], dim=-1
-                    )
-                }
+            if self._state_as_observation:
+                return {"policy": self.env.state()}
+            return {
+                "policy": torch.cat(
+                    [obs[agent].reshape(self.num_envs, -1) for agent in self.env.possible_agents], dim=-1
+                )
+            }
 
-            return obs, extras
+        def reset(self, seed: int | None = None, options: dict[str, Any] | None = None) -> tuple[VecEnvObs, dict]:
+            obs, extras = self.env.reset(seed, options)
+            return self._convert_observations(obs), extras
 
         def step(self, action: torch.Tensor) -> VecEnvStepReturn:
             # split single-agent actions to build the multi-agent ones
@@ -111,17 +123,7 @@ def step(self, action: torch.Tensor) -> VecEnvStepReturn:
             # step the environment
             obs, rewards, terminated, time_outs, extras = self.env.step(_actions)
 
-            # use environment state as observation
-            if self._state_as_observation:
-                obs = {"policy": self.env.state()}
-            # concatenate agents' observations
-            # FIXME: This implementation assumes the spaces are fundamental ones. Fix it to support composite spaces
-            else:
-                obs = {
-                    "policy": torch.cat(
-                        [obs[agent].reshape(self.num_envs, -1) for agent in self.env.possible_agents], dim=-1
-                    )
-                }
+            obs = self._convert_observations(obs)
 
             # process environment outputs to return single-agent data
             rewards = sum(rewards.values())

source/isaaclab/test/envs/test_marl_utils.py

@@ -0,0 +1,82 @@
+# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+from types import SimpleNamespace
+
+import gymnasium as gym
+import torch
+
+from isaaclab.envs.utils.marl import multi_agent_to_single_agent
+
+
+class _FakeMultiAgentEnv:
+    possible_agents = ["agent_0", "agent_1"]
+    observation_spaces = {
+        "agent_0": gym.spaces.Box(low=-1.0, high=1.0, shape=(2,)),
+        "agent_1": gym.spaces.Box(low=-1.0, high=1.0, shape=(1,)),
+    }
+    action_spaces = {
+        "agent_0": gym.spaces.Box(low=-1.0, high=1.0, shape=(1,)),
+        "agent_1": gym.spaces.Box(low=-1.0, high=1.0, shape=(1,)),
+    }
+    render_mode = None
+
+    def __init__(self):
+        self.unwrapped = self
+        self.cfg = SimpleNamespace(state_space=2)
+        self.state_space = gym.spaces.Box(low=-1.0, high=1.0, shape=(2,))
+        self.sim = object()
+        self.scene = SimpleNamespace(num_envs=2)
+        self.episode_length_buf = torch.tensor([1, 2])
+        self.obs_dict = {
+            "agent_0": torch.tensor([[1.0, 2.0], [3.0, 4.0]]),
+            "agent_1": torch.tensor([[5.0], [6.0]]),
+        }
+
+    def reset(self, seed=None, options=None):
+        return self.obs_dict, {}
+
+    def state(self):
+        return torch.tensor([[7.0, 8.0], [9.0, 10.0]])
+
+    def close(self):
+        pass
+
+
+def test_multi_agent_to_single_agent_reset_concatenates_agents():
+    """The adapter reset should concatenate the agents' observations."""
+    env = multi_agent_to_single_agent(_FakeMultiAgentEnv())
+
+    observations, _ = env.reset()
+
+    torch.testing.assert_close(observations["policy"], torch.tensor([[1.0, 2.0, 5.0], [3.0, 4.0, 6.0]]))
+
+
+def test_multi_agent_to_single_agent_reset_can_use_state():
+    """The adapter reset should support the state-as-observation mode."""
+    env = multi_agent_to_single_agent(_FakeMultiAgentEnv(), state_as_observation=True)
+
+    observations, _ = env.reset()
+
+    torch.testing.assert_close(observations["policy"], torch.tensor([[7.0, 8.0], [9.0, 10.0]]))
+
+
+def test_multi_agent_to_single_agent_forwards_episode_lengths():
+    """RSL-RL episode randomization should update the wrapped environment buffer."""
+    source_env = _FakeMultiAgentEnv()
+    env = multi_agent_to_single_agent(source_env)
+    episode_lengths = torch.tensor([3, 4])
+
+    env.episode_length_buf = episode_lengths
+
+    assert env.episode_length_buf is episode_lengths
+    assert source_env.episode_length_buf is episode_lengths
+
+
+def test_multi_agent_to_single_agent_exposes_latest_observations():
+    """The public observation buffer should reflect the wrapped environment's buffer."""
+    env = multi_agent_to_single_agent(_FakeMultiAgentEnv())
+
+    torch.testing.assert_close(env.obs_buf["policy"], torch.tensor([[1.0, 2.0, 5.0], [3.0, 4.0, 6.0]]))

source/isaaclab_assets/changelog.d/task-cleanup-dex-part03.minor.rst

@@ -0,0 +1,9 @@
+Added
+^^^^^
+
+* Added the dexterous-hand actuated-joint and fingertip body-name lists
+  (:obj:`~isaaclab_assets.robots.shadow_hand.SHADOW_ACTUATED_JOINT_NAMES`,
+  :obj:`~isaaclab_assets.robots.shadow_hand.SHADOW_FINGERTIP_BODY_NAMES`,
+  :obj:`~isaaclab_assets.robots.allegro.ALLEGRO_ACTUATED_JOINT_NAMES`,
+  :obj:`~isaaclab_assets.robots.allegro.ALLEGRO_FINGERTIP_BODY_NAMES`) to the
+  robot asset modules so tasks can reference them from a single source.

source/isaaclab_assets/isaaclab_assets/robots/allegro.py

@@ -66,3 +66,32 @@
     soft_joint_pos_limit_factor=1.0,
 )
 """Configuration of Allegro Hand robot."""
+
+
+ALLEGRO_FINGERTIP_BODY_NAMES: list[str] = [
+    "index_link_3",
+    "middle_link_3",
+    "ring_link_3",
+    "thumb_link_3",
+]
+"""Allegro Hand fingertip body names."""
+
+ALLEGRO_ACTUATED_JOINT_NAMES: list[str] = [
+    "index_joint_0",
+    "middle_joint_0",
+    "ring_joint_0",
+    "thumb_joint_0",
+    "index_joint_1",
+    "index_joint_2",
+    "index_joint_3",
+    "middle_joint_1",
+    "middle_joint_2",
+    "middle_joint_3",
+    "ring_joint_1",
+    "ring_joint_2",
+    "ring_joint_3",
+    "thumb_joint_1",
+    "thumb_joint_2",
+    "thumb_joint_3",
+]
+"""Allegro Hand actuated joint names, in the Direct task's actuation order."""

source/isaaclab_assets/isaaclab_assets/robots/shadow_hand.py

@@ -82,3 +82,37 @@
     soft_joint_pos_limit_factor=1.0,
 )
 """Configuration of Shadow Hand robot."""
+
+
+SHADOW_FINGERTIP_BODY_NAMES: list[str] = [
+    "robot0_ffdistal",
+    "robot0_mfdistal",
+    "robot0_rfdistal",
+    "robot0_lfdistal",
+    "robot0_thdistal",
+]
+"""Shadow Hand fingertip body names (identical on every backend asset)."""
+
+SHADOW_ACTUATED_JOINT_NAMES: list[str] = [
+    "robot0_WRJ1",
+    "robot0_WRJ0",
+    "robot0_FFJ3",
+    "robot0_FFJ2",
+    "robot0_FFJ1",
+    "robot0_MFJ3",
+    "robot0_MFJ2",
+    "robot0_MFJ1",
+    "robot0_RFJ3",
+    "robot0_RFJ2",
+    "robot0_RFJ1",
+    "robot0_LFJ4",
+    "robot0_LFJ3",
+    "robot0_LFJ2",
+    "robot0_LFJ1",
+    "robot0_THJ4",
+    "robot0_THJ3",
+    "robot0_THJ2",
+    "robot0_THJ1",
+    "robot0_THJ0",
+]
+"""Shadow Hand actuated joint names, in the Direct task's actuation order."""

source/isaaclab_experimental/changelog.d/dexterous-env-convergence.rst

@@ -0,0 +1,7 @@
+Fixed
+^^^^^
+
+* Fixed :meth:`~isaaclab_experimental.envs.DirectRLEnvWarp.step` and
+  :meth:`~isaaclab_experimental.envs.DirectRLEnvWarp.reset` to store the returned
+  observation dictionary in ``obs_buf``, which
+  :meth:`~isaaclab_rl.rsl_rl.RslRlVecEnvWrapper.get_observations` now reads.

source/isaaclab_experimental/isaaclab_experimental/envs/direct_rl_env_warp.py

@@ -377,7 +377,9 @@ def reset(self, seed: int | None = None, options: dict[str, Any] | None = None)
 
         # return observations
         self._get_observations()
-        return {"policy": self.torch_obs_buf.clone()}, self.extras
+        # store the returned buffer so RslRlVecEnvWrapper.get_observations() can read env.obs_buf
+        self.obs_buf = {"policy": self.torch_obs_buf.clone()}
+        return self.obs_buf, self.extras
 
     @Timer(name="env_step", msg="Step took:", enable=DEBUG_TIMER_STEP or DEBUG_TIMERS)
     def step(self, action: torch.Tensor) -> VecEnvStepReturn:
@@ -460,8 +462,10 @@ def step(self, action: torch.Tensor) -> VecEnvStepReturn:
             self._post_step_visualize()
 
         # return observations, rewards, resets and extras
+        # store the returned buffer so RslRlVecEnvWrapper.get_observations() can read env.obs_buf
+        self.obs_buf = {"policy": self.torch_obs_buf.clone()}
         return (
-            {"policy": self.torch_obs_buf.clone()},
+            self.obs_buf,
             self.torch_reward_buf,
             self.torch_reset_terminated,
             self.torch_reset_time_outs,