# Copyright (c) 2022-2025, 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 dataclasses import MISSING
from isaaclab.controllers import DifferentialIKControllerCfg, OperationalSpaceControllerCfg
from isaaclab.managers.action_manager import ActionTerm, ActionTermCfg
from isaaclab.utils import configclass
from . import (
binary_joint_actions,
joint_actions,
joint_actions_to_limits,
non_holonomic_actions,
surface_gripper_actions,
task_space_actions,
)
##
# Joint actions.
##
[docs]@configclass
class JointActionCfg(ActionTermCfg):
"""Configuration for the base joint action term.
See :class:`JointAction` for more details.
"""
joint_names: list[str] = MISSING
"""List of joint names or regex expressions that the action will be mapped to."""
scale: float | dict[str, float] = 1.0
"""Scale factor for the action (float or dict of regex expressions). Defaults to 1.0."""
offset: float | dict[str, float] = 0.0
"""Offset factor for the action (float or dict of regex expressions). Defaults to 0.0."""
preserve_order: bool = False
"""Whether to preserve the order of the joint names in the action output. Defaults to False."""
[docs]@configclass
class JointPositionActionCfg(JointActionCfg):
"""Configuration for the joint position action term.
See :class:`JointPositionAction` for more details.
"""
class_type: type[ActionTerm] = joint_actions.JointPositionAction
use_default_offset: bool = True
"""Whether to use default joint positions configured in the articulation asset as offset.
Defaults to True.
If True, this flag results in overwriting the values of :attr:`offset` to the default joint positions
from the articulation asset.
"""
[docs]@configclass
class RelativeJointPositionActionCfg(JointActionCfg):
"""Configuration for the relative joint position action term.
See :class:`RelativeJointPositionAction` for more details.
"""
class_type: type[ActionTerm] = joint_actions.RelativeJointPositionAction
use_zero_offset: bool = True
"""Whether to ignore the offset defined in articulation asset. Defaults to True.
If True, this flag results in overwriting the values of :attr:`offset` to zero.
"""
[docs]@configclass
class JointVelocityActionCfg(JointActionCfg):
"""Configuration for the joint velocity action term.
See :class:`JointVelocityAction` for more details.
"""
class_type: type[ActionTerm] = joint_actions.JointVelocityAction
use_default_offset: bool = True
"""Whether to use default joint velocities configured in the articulation asset as offset.
Defaults to True.
This overrides the settings from :attr:`offset` if set to True.
"""
[docs]@configclass
class JointEffortActionCfg(JointActionCfg):
"""Configuration for the joint effort action term.
See :class:`JointEffortAction` for more details.
"""
class_type: type[ActionTerm] = joint_actions.JointEffortAction
##
# Joint actions rescaled to limits.
##
[docs]@configclass
class JointPositionToLimitsActionCfg(ActionTermCfg):
"""Configuration for the bounded joint position action term.
See :class:`JointPositionToLimitsAction` for more details.
"""
class_type: type[ActionTerm] = joint_actions_to_limits.JointPositionToLimitsAction
joint_names: list[str] = MISSING
"""List of joint names or regex expressions that the action will be mapped to."""
scale: float | dict[str, float] = 1.0
"""Scale factor for the action (float or dict of regex expressions). Defaults to 1.0."""
rescale_to_limits: bool = True
"""Whether to rescale the action to the joint limits. Defaults to True.
If True, the input actions are rescaled to the joint limits, i.e., the action value in
the range [-1, 1] corresponds to the joint lower and upper limits respectively.
Note:
This operation is performed after applying the scale factor.
"""
preserve_order: bool = False
"""Whether to preserve the order of the joint names in the action output. Defaults to False."""
[docs]@configclass
class EMAJointPositionToLimitsActionCfg(JointPositionToLimitsActionCfg):
"""Configuration for the exponential moving average (EMA) joint position action term.
See :class:`EMAJointPositionToLimitsAction` for more details.
"""
class_type: type[ActionTerm] = joint_actions_to_limits.EMAJointPositionToLimitsAction
alpha: float | dict[str, float] = 1.0
"""The weight for the moving average (float or dict of regex expressions). Defaults to 1.0.
If set to 1.0, the processed action is applied directly without any moving average window.
"""
##
# Gripper actions.
##
[docs]@configclass
class BinaryJointActionCfg(ActionTermCfg):
"""Configuration for the base binary joint action term.
See :class:`BinaryJointAction` for more details.
"""
joint_names: list[str] = MISSING
"""List of joint names or regex expressions that the action will be mapped to."""
open_command_expr: dict[str, float] = MISSING
"""The joint command to move to *open* configuration."""
close_command_expr: dict[str, float] = MISSING
"""The joint command to move to *close* configuration."""
[docs]@configclass
class BinaryJointPositionActionCfg(BinaryJointActionCfg):
"""Configuration for the binary joint position action term.
See :class:`BinaryJointPositionAction` for more details.
"""
class_type: type[ActionTerm] = binary_joint_actions.BinaryJointPositionAction
[docs]@configclass
class BinaryJointVelocityActionCfg(BinaryJointActionCfg):
"""Configuration for the binary joint velocity action term.
See :class:`BinaryJointVelocityAction` for more details.
"""
class_type: type[ActionTerm] = binary_joint_actions.BinaryJointVelocityAction
[docs]@configclass
class AbsBinaryJointPositionActionCfg(ActionTermCfg):
"""Configuration for the absolute binary joint position action term.
This action term is used for robust grasping by converting continuous gripper joint position actions
into binary open/close commands. Unlike directly applying continuous gripper joint position actions, this class
applies a threshold-based decision mechanism to determine whether to
open or close the gripper.
The action works by:
1. Taking a continuous input action value
2. Comparing it against a configurable threshold
3. Mapping the result to either open or close commands based on the threshold comparison
4. Applying the corresponding gripper open/close commands
This approach provides more predictable and stable grasping behavior compared to directly applying
continuous gripper joint position actions.
See :class:`AbsBinaryJointPositionAction` for more details.
"""
joint_names: list[str] = MISSING
"""List of joint names or regex expressions that the action will be mapped to."""
open_command_expr: dict[str, float] = MISSING
"""The joint command to move to *open* configuration."""
close_command_expr: dict[str, float] = MISSING
"""The joint command to move to *close* configuration."""
threshold: float = 0.5
"""The threshold for the binary action. Defaults to 0.5."""
positive_threshold: bool = True
"""Whether to use positive (Open actions > Close actions) threshold. Defaults to True."""
class_type: type[ActionTerm] = binary_joint_actions.AbsBinaryJointPositionAction
##
# Non-holonomic actions.
##
[docs]@configclass
class NonHolonomicActionCfg(ActionTermCfg):
"""Configuration for the non-holonomic action term with dummy joints at the base.
See :class:`NonHolonomicAction` for more details.
"""
class_type: type[ActionTerm] = non_holonomic_actions.NonHolonomicAction
body_name: str = MISSING
"""Name of the body which has the dummy mechanism connected to."""
x_joint_name: str = MISSING
"""The dummy joint name in the x direction."""
y_joint_name: str = MISSING
"""The dummy joint name in the y direction."""
yaw_joint_name: str = MISSING
"""The dummy joint name in the yaw direction."""
scale: tuple[float, float] = (1.0, 1.0)
"""Scale factor for the action. Defaults to (1.0, 1.0)."""
offset: tuple[float, float] = (0.0, 0.0)
"""Offset factor for the action. Defaults to (0.0, 0.0)."""
##
# Task-space Actions.
##
[docs]@configclass
class DifferentialInverseKinematicsActionCfg(ActionTermCfg):
"""Configuration for inverse differential kinematics action term.
See :class:`DifferentialInverseKinematicsAction` for more details.
"""
[docs] @configclass
class OffsetCfg:
"""The offset pose from parent frame to child frame.
On many robots, end-effector frames are fictitious frames that do not have a corresponding
rigid body. In such cases, it is easier to define this transform w.r.t. their parent rigid body.
For instance, for the Franka Emika arm, the end-effector is defined at an offset to the the
"panda_hand" frame.
"""
pos: tuple[float, float, float] = (0.0, 0.0, 0.0)
"""Translation w.r.t. the parent frame. Defaults to (0.0, 0.0, 0.0)."""
rot: tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.0)
"""Quaternion rotation ``(w, x, y, z)`` w.r.t. the parent frame. Defaults to (1.0, 0.0, 0.0, 0.0)."""
class_type: type[ActionTerm] = task_space_actions.DifferentialInverseKinematicsAction
joint_names: list[str] = MISSING
"""List of joint names or regex expressions that the action will be mapped to."""
body_name: str = MISSING
"""Name of the body or frame for which IK is performed."""
body_offset: OffsetCfg | None = None
"""Offset of target frame w.r.t. to the body frame. Defaults to None, in which case no offset is applied."""
scale: float | tuple[float, ...] = 1.0
"""Scale factor for the action. Defaults to 1.0."""
controller: DifferentialIKControllerCfg = MISSING
"""The configuration for the differential IK controller."""
[docs]@configclass
class OperationalSpaceControllerActionCfg(ActionTermCfg):
"""Configuration for operational space controller action term.
See :class:`OperationalSpaceControllerAction` for more details.
"""
[docs] @configclass
class OffsetCfg:
"""The offset pose from parent frame to child frame.
On many robots, end-effector frames are fictitious frames that do not have a corresponding
rigid body. In such cases, it is easier to define this transform w.r.t. their parent rigid body.
For instance, for the Franka Emika arm, the end-effector is defined at an offset to the the
"panda_hand" frame.
"""
pos: tuple[float, float, float] = (0.0, 0.0, 0.0)
"""Translation w.r.t. the parent frame. Defaults to (0.0, 0.0, 0.0)."""
rot: tuple[float, float, float, float] = (1.0, 0.0, 0.0, 0.0)
"""Quaternion rotation ``(w, x, y, z)`` w.r.t. the parent frame. Defaults to (1.0, 0.0, 0.0, 0.0)."""
class_type: type[ActionTerm] = task_space_actions.OperationalSpaceControllerAction
joint_names: list[str] = MISSING
"""List of joint names or regex expressions that the action will be mapped to."""
body_name: str = MISSING
"""Name of the body or frame for which motion/force control is performed."""
body_offset: OffsetCfg | None = None
"""Offset of target frame w.r.t. to the body frame. Defaults to None, in which case no offset is applied."""
task_frame_rel_path: str = None
"""The path of a ``RigidObject``, relative to the sub-environment, representing task frame. Defaults to None."""
controller_cfg: OperationalSpaceControllerCfg = MISSING
"""The configuration for the operational space controller."""
position_scale: float = 1.0
"""Scale factor for the position targets. Defaults to 1.0."""
orientation_scale: float = 1.0
"""Scale factor for the orientation (quad for ``pose_abs`` or axis-angle for ``pose_rel``). Defaults to 1.0."""
wrench_scale: float = 1.0
"""Scale factor for the wrench targets. Defaults to 1.0."""
stiffness_scale: float = 1.0
"""Scale factor for the stiffness commands. Defaults to 1.0."""
damping_ratio_scale: float = 1.0
"""Scale factor for the damping ratio commands. Defaults to 1.0."""
nullspace_joint_pos_target: str = "none"
"""The joint targets for the null-space control: ``"none"``, ``"zero"``, ``"default"``, ``"center"``.
Note: Functional only when ``nullspace_control`` is set to ``"position"`` within the
``OperationalSpaceControllerCfg``.
"""
##
# Surface Gripper actions.
##
[docs]@configclass
class SurfaceGripperBinaryActionCfg(ActionTermCfg):
"""Configuration for the binary surface gripper action term.
See :class:`SurfaceGripperBinaryAction` for more details.
"""
asset_name: str = MISSING
"""Name of the surface gripper asset in the scene."""
open_command: float = -1.0
"""The command value to open the gripper. Defaults to -1.0."""
close_command: float = 1.0
"""The command value to close the gripper. Defaults to 1.0."""
class_type: type[ActionTerm] = surface_gripper_actions.SurfaceGripperBinaryAction
