Add tendon actuation to the Shadow Hand tasks

Author: hujc7

source/isaaclab_tasks/changelog.d/codex-shadow-hand-unified-asset.minor.rst

@@ -0,0 +1,39 @@
+Added
+^^^^^
+
+* Added fixed-tendon actuation to the Shadow Hand tasks. The hand's twenty motors drive sixteen
+  joints and four tendons, so each manager-based task pairs a joint action term with a fixed-tendon
+  action term -- one pair per hand, so handover carries two -- and the direct tasks apply the joint
+  and tendon halves of the action in turn. Without the tendon term the eight joints coupled by a
+  tendon took no command at all. Each hand also observes the tendon half of its previous command,
+  which takes the manager-based handover policy input from 282 to 290 values.
+
+Fixed
+^^^^^
+
+* Fixed the direct Shadow Hand reorientation and handover tasks rescaling their whole twenty-motor
+  action against their sixteen actuated joints, which raised a shape error on the first step.
+
+* Fixed the Shadow Hand reorientation task spawning the hand in an orientation that left the palm
+  facing sideways on the current asset, so the object could not be held.
+
+* Fixed the Shadow Hand reorientation and handover tasks diverging on PhysX. Twenty-four joints
+  under finger-object contact need more solver iterations than the default budget provides, and
+  training ended with non-finite observations. The hand's configuration sets them again for both
+  engines; Newton ignores them.
+
+Changed
+^^^^^^^
+
+* Changed ``Metrics/success_rate`` for the Shadow Hand handover task to report whether the object is
+  at the goal when the episode ends. It previously latched as soon as the object first came within
+  the success distance, so an object swung through the goal scored the same as one left resting
+  there. Both the manager-based and direct environments were updated together. Reported success
+  rates are lower than before for the same policy, and are not comparable with values recorded
+  under the previous definition; re-evaluate any checkpoint whose success rate is being compared
+  across this change.
+
+* Reduced the default RSL-RL training length for the Shadow Hand tasks: reorientation from 10000 to
+  3000 iterations and handover from 5000 to 3500. Success rate flattens well before the previous
+  budgets, so a default run reaches the same success rate in roughly a third of the wall time. Pass
+  ``agent.max_iterations=<n>`` to train longer.

source/isaaclab_tasks/isaaclab_tasks/core/handover/handover_common.py

@@ -15,16 +15,7 @@
 import isaaclab.sim as sim_utils
 from isaaclab.markers import VisualizationMarkersCfg
 
-from isaaclab_assets.robots.shadow_hand import (
-    SHADOW_ACTUATED_JOINT_NAMES as ACTUATED_JOINT_NAMES,
-)
-from isaaclab_assets.robots.shadow_hand import (
-    SHADOW_FINGERTIP_BODY_NAMES as FINGERTIP_BODY_NAMES,
-)
-
 __all__ = [
-    "ACTUATED_JOINT_NAMES",
-    "FINGERTIP_BODY_NAMES",
     "GOAL_MARKER_CFG",
     "GOAL_POSITION_OFFSET",
     "OBJECT_RADIUS",

source/isaaclab_tasks/isaaclab_tasks/core/handover/handover_env.py

@@ -21,9 +21,10 @@
 from isaaclab_tasks.core.handover.handover_common import GOAL_POSITION_OFFSET
 from isaaclab_tasks.core.handover.handover_env_cfg import HandoverEnvCfg
 from isaaclab_tasks.core.handover.mdp.rewards import evaluate_handover_success, handover_reward
-from isaaclab_tasks.core.utils import (
+from isaaclab_tasks.core.reorient.utils import (
     EpisodeErrorRecorder,
     randomize_rotation,
+    resolve_actuated_tendons,
     sample_joint_positions_within_limits,
 )
 
@@ -57,6 +58,18 @@ def __init__(self, cfg: HandoverEnvCfg, render_mode: str | None = None, **kwargs
                 f"Expected {len(cfg.actuated_joint_names)} actuated joints, found {len(self.actuated_dof_indices)}."
             )
 
+        # Motors that pull a tendon rather than drive a joint. Both hands are the same model, so
+        # one index set serves both.
+        self.actuated_tendon_indices: list[int] = []
+        if cfg.actuated_tendon_names:
+            self.actuated_tendon_indices, self.tendon_lower_limits, self.tendon_upper_limits = resolve_actuated_tendons(
+                self.right_hand,
+                cfg.actuated_tendon_names,
+                self.num_envs,
+                self.device,
+                cfg.actuated_tendon_position_limits,
+            )
+
         # finger bodies
         self.finger_bodies, _ = self.right_hand.find_bodies(self.cfg.fingertip_body_names)
         if len(self.finger_bodies) != len(self.cfg.fingertip_body_names):
@@ -83,14 +96,15 @@ def __init__(self, cfg: HandoverEnvCfg, render_mode: str | None = None, **kwargs
 
         # Sticky per-env flag: True once the object reached the goal within threshold.
         self._episode_succeeded = torch.zeros(self.num_envs, dtype=torch.bool, device=self.device)
+        # Goal distance from the most recent reward step, read at reset as the episode's final value.
+        self._last_goal_dist = torch.full((self.num_envs,), float("inf"), device=self.device)
         self._goal_distance = EpisodeErrorRecorder(self.num_envs, self.device)
 
         # unit tensors for sampling goal/object rotations about the x and y axes
         self.x_unit_tensor = torch.tensor([1, 0, 0], dtype=torch.float, device=self.device).repeat((self.num_envs, 1))
         self.y_unit_tensor = torch.tensor([0, 1, 0], dtype=torch.float, device=self.device).repeat((self.num_envs, 1))
 
     def _setup_scene(self):
-        # add hand, in-hand object, and goal object
         self.right_hand = Articulation(self.cfg.right_robot_cfg)
         self.left_hand = Articulation(self.cfg.left_robot_cfg)
         self.object = RigidObject(self.cfg.object_cfg)
@@ -128,23 +142,35 @@ def _apply_hand_action(
         curr_targets: torch.Tensor,
         prev_targets: torch.Tensor,
     ) -> None:
-        """Map one agent's actions to joint position targets and write them to its hand.
+        """Map one agent's actions to position targets and write them to its hand.
 
-        The raw ``[-1, 1]`` action is rescaled to the joint limits, blended with the previous
-        target via the exponential moving average, clamped to the limits, and set on the hand.
+        Actions are ordered joints first, then tendons, matching the manager task's action term.
+        Each raw ``[-1, 1]`` joint action is rescaled to the joint limits, blended with the
+        previous target via the exponential moving average, clamped to the limits, and set on the
+        hand. Tendon actions are rescaled to the tendon's commandable range and written directly.
         """
         idx = self.actuated_dof_indices
         lower = self.hand_dof_lower_limits[:, idx]
         upper = self.hand_dof_upper_limits[:, idx]
 
-        targets = unscale_transform(self.actions[agent], lower, upper)
+        targets = unscale_transform(self.actions[agent][:, : len(idx)], lower, upper)
         targets = self.cfg.act_moving_average * targets + (1.0 - self.cfg.act_moving_average) * prev_targets[:, idx]
         targets = saturate(targets, lower, upper)
 
         curr_targets[:, idx] = targets
         prev_targets[:, idx] = targets
         hand.set_joint_position_target_index(target=targets, joint_ids=idx)
 
+        if self.actuated_tendon_indices:
+            # No moving average on the tendon target: the manager task's action term applies none,
+            # and the two task variants have to stay comparable.
+            hand.set_fixed_tendon_position_target_index(
+                target=unscale_transform(
+                    self.actions[agent][:, len(idx) :], self.tendon_lower_limits, self.tendon_upper_limits
+                ),
+                fixed_tendon_ids=self.actuated_tendon_indices,
+            )
+
     def _hand_proprio_obs(self, agent: str) -> torch.Tensor:
         """Per-hand proprioceptive observation block for ``agent`` (133 dims).
 
@@ -213,8 +239,10 @@ def _get_rewards(self) -> dict[str, torch.Tensor]:
         self.extras["log"]["dist_reward"] = rew_dist.mean()
         self.extras["log"]["dist_goal"] = goal_dist_mean
         self.extras["log"]["Metrics/goal_distance"] = goal_dist_mean
-        # Sticky per-env success: True once the object reached the goal within threshold.
+        # Reaching the goal is necessary but not sufficient; the object must still be there when
+        # the episode ends. ``_reset_idx`` combines this with the final distance.
         self._episode_succeeded |= succeeded
+        self._last_goal_dist = goal_dist
 
         return {"right_hand": rew_dist, "left_hand": rew_dist}
 
@@ -233,9 +261,12 @@ def _get_dones(self) -> tuple[dict[str, torch.Tensor], dict[str, torch.Tensor]]:
     def _reset_idx(self, env_ids: Sequence[int] | torch.Tensor | None):
         if env_ids is None:
             env_ids = self.right_hand._ALL_INDICES
-        # Flush per-episode success (sticky binary: object ever reached the goal within threshold).
-        # 0-dim device tensor, for the same reason
-        self.extras.setdefault("log", {})["Metrics/success_rate"] = self._episode_succeeded[env_ids].float().mean()
+        # Flush per-episode success: the object is AT the goal as the episode ends, not merely
+        # that it passed through. 0-dim device tensor, for the same reason.
+        succeeded = (self._last_goal_dist[env_ids] < self.cfg.success_distance_threshold) & self._episode_succeeded[
+            env_ids
+        ]
+        self.extras.setdefault("log", {})["Metrics/success_rate"] = succeeded.float().mean()
         for statistic, value in self._goal_distance.reset(env_ids).items():
             self.extras["log"][f"Diagnostics/episode_min_goal_distance_{statistic}"] = value
         self._episode_succeeded[env_ids] = False

source/isaaclab_tasks/isaaclab_tasks/core/handover/handover_env_cfg.py

@@ -9,89 +9,95 @@
 from isaaclab_physx.physics import PhysxCfg
 
 import isaaclab.sim as sim_utils
-import isaaclab.utils.math as math_utils
-from isaaclab.assets import ArticulationCfg, RigidObjectCfg
+from isaaclab.assets import RigidObjectCfg
+from isaaclab.assets.articulation import ArticulationCfg
 from isaaclab.envs import DirectMARLEnvCfg
 from isaaclab.markers import VisualizationMarkersCfg
 from isaaclab.physics import PhysxAutoCfg
 from isaaclab.scene import InteractiveSceneCfg
 from isaaclab.sim import SimulationCfg
 from isaaclab.sim.spawners.materials import RigidBodyMaterialBaseCfg
+from isaaclab.utils import math as math_utils
 from isaaclab.utils.configclass import configclass
-
-from isaaclab_tasks.core.handover.handover_common import (
-    ACTUATED_JOINT_NAMES,
-    FINGERTIP_BODY_NAMES,
-    GOAL_MARKER_CFG,
-    OBJECT_RADIUS,
+from isaaclab.visualizers import VisualizerCfg
+
+from isaaclab_tasks.core.handover.handover_common import GOAL_MARKER_CFG, OBJECT_RADIUS
+from isaaclab_tasks.utils import PresetCfg
+
+from isaaclab_assets.robots.shadow_hand import (
+    FINGERTIP_NAMES,
+    JOINT_NAMES,
+    SHADOW_HAND_NEWTON_CFG,
+    SHADOW_HAND_PHYSX_CFG,
+    TENDON_NAMES,
+    TENDON_POSITION_LIMITS,
 )
-from isaaclab_tasks.utils import PresetCfg, preset
-
-from isaaclab_assets.robots.shadow_hand import SHADOW_HAND_CFG, SHADOW_HAND_NEWTON_CFG
 
 
-def _shadow_hand_cfg(
+def _hand_cfg(
+    base: ArticulationCfg,
     prim_path: str,
     init_pos: tuple[float, float, float],
     init_rot: tuple[float, float, float, float],
-) -> PresetCfg:
-    """Build the per-hand Shadow Hand preset for each supported backend.
+) -> ArticulationCfg:
+    """Place one engine's Shadow Hand at this task's pose for one hand.
+
+    The catch needs more joint authority than reorientation, but the hand's gains belong to the
+    hand, so both tasks take them as the asset configuration supplies them. This task used to raise
+    every actuator to stiffness 20 / damping 2, which also drove the tendon-coupled joints -- they
+    take no position command, and MEASURED, giving them one costs the tendon most of its travel:
+    11.1 rad falls to 1.0 rad.
 
     Args:
+        base: The hand on the engine's asset variant.
         prim_path: Scene path the hand spawns at.
         init_pos: Spawn position [m].
         init_rot: Spawn orientation as ``(w, x, y, z)``.
 
     Returns:
-        A preset carrying the PhysX, Newton MJWarp and OvPhysX variants, each at
-        *prim_path* with the given pose. The two hands differ only in these arguments.
+        That configuration at *prim_path* with the given pose.
     """
-    physx_cfg = SHADOW_HAND_CFG.replace(prim_path=prim_path).replace(
-        init_state=ArticulationCfg.InitialStateCfg(pos=init_pos, rot=init_rot, joint_pos={".*": 0.0})
-    )
-    # Newton's importer bakes the asset's root orientation into the root joint (see the note on
-    # SHADOW_HAND_NEWTON_CFG.init_state), so the task rotation must compose with it rather than
-    # replace it — replacing leaves both palms rotated 90 degrees.
-    newton_rot = tuple(
+    # The asset's own spawn rotation is shared by both engines, so the per-hand rotation COMPOSES
+    # with it rather than replacing it -- replacing leaves both palms turned 90 degrees. See
+    # SHADOW_HAND_PHYSX_CFG's init_state for why the asset carries that rotation.
+    hand_rot = tuple(
         math_utils.quat_mul(
             torch.tensor(init_rot, dtype=torch.float64),
-            torch.tensor(SHADOW_HAND_NEWTON_CFG.init_state.rot, dtype=torch.float64),
+            torch.tensor(base.init_state.rot, dtype=torch.float64),
         ).tolist()
     )
-    newton_mjwarp_cfg = SHADOW_HAND_NEWTON_CFG.replace(
-        prim_path=prim_path,
-        init_state=SHADOW_HAND_NEWTON_CFG.init_state.replace(pos=init_pos, rot=newton_rot),
-        actuators={
-            **SHADOW_HAND_NEWTON_CFG.actuators,
-            "fingers": SHADOW_HAND_NEWTON_CFG.actuators["fingers"].replace(stiffness=20.0, damping=2.0),
-        },
-    )
-    ovphysx_cfg = SHADOW_HAND_CFG.replace(
+    return base.replace(
         prim_path=prim_path,
-        # OVPhysX does not expose the fixed-tendon runtime API, so spawn without tendon overrides.
-        spawn=SHADOW_HAND_CFG.spawn.replace(fixed_tendons_props=None),
-        init_state=SHADOW_HAND_CFG.init_state.replace(pos=init_pos, rot=init_rot),
-    )
-    return preset(
-        default=newton_mjwarp_cfg,
-        physx=physx_cfg,
-        isaacsim_physx=physx_cfg,
-        newton_mjwarp=newton_mjwarp_cfg,
-        ovphysx=ovphysx_cfg,
+        init_state=base.init_state.replace(pos=init_pos, rot=hand_rot),
     )
 
 
-# Per-hand presets shared by the Direct environment and the manager scene.
-RIGHT_HAND_CFG = _shadow_hand_cfg(
-    prim_path="{ENV_REGEX_NS}/RightRobot",
-    init_pos=(0.0, 0.0, 0.5),
-    init_rot=(0.0, 0.0, 0.0, 1.0),
-)
-LEFT_HAND_CFG = _shadow_hand_cfg(
-    prim_path="{ENV_REGEX_NS}/LeftRobot",
-    init_pos=(0.0, -1.0, 0.5),
-    init_rot=(0.0, 0.0, 1.0, 0.0),
-)
+# Per-hand poses. The rotations are composed with the asset's own; they are unchanged from the
+# previous Newton asset, which the two assets being identical geometry makes valid.
+_RIGHT_POSE = ("{ENV_REGEX_NS}/RightRobot", (0.0, 0.0, 0.5), (0.0, 0.0, 0.0, 1.0))
+_LEFT_POSE = ("{ENV_REGEX_NS}/LeftRobot", (0.0, -1.0, 0.5), (0.0, 0.0, 1.0, 0.0))
+
+
+@configclass
+class RightHandCfg(PresetCfg):
+    """The right hand on every engine; only the asset's physics variant differs."""
+
+    newton_mjwarp = _hand_cfg(SHADOW_HAND_NEWTON_CFG, *_RIGHT_POSE)
+    isaacsim_physx = _hand_cfg(SHADOW_HAND_PHYSX_CFG, *_RIGHT_POSE)
+    physx = isaacsim_physx
+    ovphysx = isaacsim_physx
+    default = newton_mjwarp
+
+
+@configclass
+class LeftHandCfg(PresetCfg):
+    """The left hand on every engine; only the asset's physics variant differs."""
+
+    newton_mjwarp = _hand_cfg(SHADOW_HAND_NEWTON_CFG, *_LEFT_POSE)
+    isaacsim_physx = _hand_cfg(SHADOW_HAND_PHYSX_CFG, *_LEFT_POSE)
+    physx = isaacsim_physx
+    ovphysx = isaacsim_physx
+    default = newton_mjwarp
 
 
 BALL_CFG = RigidObjectCfg(
@@ -169,13 +175,18 @@ class HandoverEnvCfg(DirectMARLEnvCfg):
         render_interval=decimation,
         physics_material=RigidBodyMaterialBaseCfg(static_friction=1.0, dynamic_friction=1.0),
         physics=PhysicsCfg(),
+        # Frame both hands and the object between them. Without this the visualizer looks at the
+        # origin from its default 4 m away, which renders the pair a few pixels wide.
+        default_visualizer_cfg=VisualizerCfg(eye=(1.15, -1.65, 1.15), lookat=(0.0, -0.5, 0.55), focal_length=35.0),
     )
 
     # robot
-    right_robot_cfg: PresetCfg = RIGHT_HAND_CFG
-    left_robot_cfg: PresetCfg = LEFT_HAND_CFG
-    actuated_joint_names = ACTUATED_JOINT_NAMES
-    fingertip_body_names = FINGERTIP_BODY_NAMES
+    right_robot_cfg: RightHandCfg = RightHandCfg()
+    left_robot_cfg: LeftHandCfg = LeftHandCfg()
+    actuated_joint_names = JOINT_NAMES
+    actuated_tendon_names = TENDON_NAMES
+    actuated_tendon_position_limits = TENDON_POSITION_LIMITS
+    fingertip_body_names = FINGERTIP_NAMES
 
     # in-hand object
     object_cfg: RigidObjectCfg = BALL_CFG