Adds FORGE tasks for contact-rich manipulation with force sensing to IsaacLab (#2968)

# Description

This MR adds new tasks which extend the `Factory` tasks to include:
1. Force sensing: Add observations for force experienced by the
end-effector.
2. Excessive force penalty: Add an option to penalize the agent for
excessive contact forces.
3. Dynamics randomization: Randomize controller gains, asset properties
(friction, mass), and dead-zone.
4. Success prediction: Add an extra action that predicts task success.

The new tasks are: `Isaac-Forge-PegInsert-Direct-v0`,
`Isaac-Forge-GearMesh-Direct-v0`, and `Isaac-Forge-NutThread-Direct-v0`

## Type of change

- New feature (non-breaking change which adds functionality)
- This change requires a documentation update

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

---------

Signed-off-by: Kelly Guo <[email protected]>
Co-authored-by: Octi Zhang <[email protected]>
Co-authored-by: Kelly Guo <[email protected]>

Author: 3 people

.github/workflows/license-exceptions.json

@@ -360,5 +360,10 @@
     "package": "referencing",
     "license": "UNKNOWN",
     "comment": "MIT"
+  },
+  {
+    "package": "regex",
+    "license": "UNKNOWN",
+    "comment": "Apache 2.0"
   }
 ]

docs/source/overview/environments.rst

@@ -245,6 +245,44 @@ We provide environments for both disassembly and assembly.
 .. |assembly-link| replace:: `Isaac-AutoMate-Assembly-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab_tasks/isaaclab_tasks/direct/automate/assembly_env_cfg.py>`__
 .. |disassembly-link| replace:: `Isaac-AutoMate-Disassembly-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab_tasks/isaaclab_tasks/direct/automate/disassembly_env_cfg.py>`__
 
+FORGE
+~~~~~~~~
+
+FORGE environments extend Factory environments with:
+
+* Force sensing: Add observations for force experienced by the end-effector.
+* Excessive force penalty: Add an option to penalize the agent for excessive contact forces.
+* Dynamics randomization: Randomize controller gains, asset properties (friction, mass), and dead-zone.
+* Success prediction: Add an extra action that predicts task success.
+
+These tasks share the same task configurations and control options. You can switch between them by specifying the task name.
+
+* |forge-peg-link|: Peg insertion with the Franka arm
+* |forge-gear-link|: Gear meshing with the Franka arm
+* |forge-nut-link|: Nut-Bolt fastening with the Franka arm
+
+.. table::
+    :widths: 33 37 30
+
+    +--------------------+-------------------------+-----------------------------------------------------------------------------+
+    | World              | Environment ID          | Description                                                                 |
+    +====================+=========================+=============================================================================+
+    | |forge-peg|        | |forge-peg-link|        | Insert peg into the socket with the Franka robot                            |
+    +--------------------+-------------------------+-----------------------------------------------------------------------------+
+    | |forge-gear|       | |forge-gear-link|       | Insert and mesh gear into the base with other gears, using the Franka robot |
+    +--------------------+-------------------------+-----------------------------------------------------------------------------+
+    | |forge-nut|        | |forge-nut-link|        | Thread the nut onto the first 2 threads of the bolt, using the Franka robot |
+    +--------------------+-------------------------+-----------------------------------------------------------------------------+
+
+.. |forge-peg| image:: ../_static/tasks/factory/peg_insert.jpg
+.. |forge-gear| image:: ../_static/tasks/factory/gear_mesh.jpg
+.. |forge-nut| image:: ../_static/tasks/factory/nut_thread.jpg
+
+.. |forge-peg-link| replace:: `Isaac-Forge-PegInsert-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab_tasks/isaaclab_tasks/direct/forge/forge_env_cfg.py>`__
+.. |forge-gear-link| replace:: `Isaac-Forge-GearMesh-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab_tasks/isaaclab_tasks/direct/forge/forge_env_cfg.py>`__
+.. |forge-nut-link| replace:: `Isaac-Forge-NutThread-Direct-v0 <https://github.com/isaac-sim/IsaacLab/blob/main/source/isaaclab_tasks/isaaclab_tasks/direct/forge/forge_env_cfg.py>`__
+
+
 Locomotion
 ~~~~~~~~~~
 
@@ -743,6 +781,18 @@ inferencing, including reading from an already trained checkpoint and disabling
       -
       - Direct
       -
+    * - Isaac-Forge-GearMesh-Direct-v0
+      -
+      - Direct
+      - **rl_games** (PPO)
+    * - Isaac-Forge-NutThread-Direct-v0
+      -
+      - Direct
+      - **rl_games** (PPO)
+    * - Isaac-Forge-PegInsert-Direct-v0
+      -
+      - Direct
+      - **rl_games** (PPO)
     * - Isaac-Franka-Cabinet-Direct-v0
       -
       - Direct

source/isaaclab_tasks/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.10.36"
+version = "0.10.37"
 
 # Description
 title = "Isaac Lab Environments"

source/isaaclab_tasks/docs/CHANGELOG.rst

@@ -1,6 +1,18 @@
 Changelog
 ---------
 
+0.10.37 (2025-07-16)
+~~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added ``Isaac-Forge-PegInsert-Direct-v0``, ``Isaac-Forge-GearMesh-Direct-v0``,
+  and ``Isaac-Forge-NutThread-Direct-v0`` environments as direct RL envs. These
+  environments extend ``Isaac-Factory-*-v0`` with force sensing, an excessive force
+  penalty, dynamics randomization, and success prediction.
+
+
 0.10.36 (2025-06-26)
 ~~~~~~~~~~~~~~~~~~~~
 

source/isaaclab_tasks/isaaclab_tasks/direct/factory/factory_control.py

@@ -31,6 +31,7 @@ def compute_dof_torque(
     task_prop_gains,
     task_deriv_gains,
     device,
+    dead_zone_thresholds=None,
 ):
     """Compute Franka DOF torque to move fingertips towards target pose."""
     # References:
@@ -61,6 +62,15 @@ def compute_dof_torque(
     )
     task_wrench += task_wrench_motion
 
+    # Offset task_wrench motion by random amount to simulate unreliability at low forces.
+    # Check if absolute value is less than specified amount. If so, 0 out, otherwise, subtract.
+    if dead_zone_thresholds is not None:
+        task_wrench = torch.where(
+            task_wrench.abs() < dead_zone_thresholds,
+            torch.zeros_like(task_wrench),
+            task_wrench.sign() * (task_wrench.abs() - dead_zone_thresholds),
+        )
+
     # Set tau = J^T * tau, i.e., map tau into joint space as desired
     jacobian_T = torch.transpose(jacobian, dim0=1, dim1=2)
     dof_torque[:, 0:7] = (jacobian_T @ task_wrench.unsqueeze(-1)).squeeze(-1)
@@ -135,7 +145,7 @@ def get_pose_error(
         return pos_error, axis_angle_error
 
 
-def _get_delta_dof_pos(delta_pose, ik_method, jacobian, device):
+def get_delta_dof_pos(delta_pose, ik_method, jacobian, device):
     """Get delta Franka DOF position from delta pose using specified IK method."""
     # References:
     # 1) https://www.cs.cmu.edu/~15464-s13/lectures/lecture6/iksurvey.pdf