Surface Gripper


The Surface Gripper Extension is used to create a suction-cup gripper behavior for an end-effector. It works by creating a Joint between two bodies when the parent body is close enough to the child at the gripper point of contact.

This extension is enabled by default. If it is ever disabled, it can be re-enabled from the Extension Manager by searching for omni.isaac.surface_gripper.

API Documentation

See the API Documentation for usage information.

Tutorials & Examples

The following example showcases how to best use this extension:


  • Surface Gripper Example: Isaac Examples > Manipulation > Surface Gripper

Surface Gripper Example

To run the Example:

  1. Go to the top menu bar and click Isaac Examples > Manipulation > Surface Gripper

  2. Press the Load Scene button.

  3. Press the PLAY button to begin simulating.

  4. Toggle the Gripper State button to CLOSE to attach the cone to the cube. The cone will turn RED on successful attachment.

  5. Adjust the Gripper Force and Gripper Speed sliders to change the force intensity at the Cone and press the respective APPLY`. Excessive forces will break the gripper attachment, and the cone will go back to GREEN when the surface gripper is open.


Surface Gripper Properties



Parent Path

The rigid body that will contain the gripper


local Offset transform from the origin of the parent. The Gripper will attempt to close on the X direction of the offset pose.

Grip Threshold

Distance from the gripper point that will accept closing contact

Force Limit

Force that the gripper can hold before it will break the constraint

Torque Limit

Torque that the gripper can withstand before it will break the constraint

Bend Angle

Angle that the surface gripper can bend when a load is applied


Bend Stiffness


Bend Damping

Retry Close

When flag is on, the gripper will attempt to close until it is sucessful in grabbing an object, otherwise it will attempt once and stop.

Omniverse OmniGraph Node

The Surface Gripper extension provides a UI implementation through Omniverse OmniGraph. To use it, select the rigid body prim to attach the surface gripper, and click on Create > Isaac > Grippers > Surface Gripper. This will create the surface gripper action graph.

  1. Use the SurfaceGripperOffset prim to define the gripper placement

  2. Change the Surface Gripper properties in the SurfaceGripperNode on the properties panel.


The body selected must have the Rigid Body API applied to it, otherwise it will result on an error and the gripper won’t be created on simulation.

You can interact with the gripper by clicking on the open/close State.


To interact with the Omnigraph through code, first get the prim at the node path, then use

1node = "/path/to/surface_gripper_node"
2attr_open = "state:open"
3attr_open = "state:close"
4node_attr_open = og.Controller.attribute("{}.{}".format(node,attr_open))
5node_attr_close = og.Controller.attribute("{}.{}".format(node,attr_close))
6node_attr_close.Set(True) #Used to call the node to close. It will auto-reset once action is executed
7og.Controller.evaluate_sync(node) # Force node execution to feed from the node update (so we don't have a one frame delay to desired action
8node_attr_open.Set(True) #Used to call the node to open. It will auto-reset once action is executed

Code Snippets

This section describes the functionality of the Surface Gripper Sample code. On this document, we will only cover the portion that pertains to the Surface Gripper.

Create Gripper Properties

Surface Gripper properties are defined within the _create_scenario function. Let’s take a closer look at the different parameters of the Gripper Properties:

 1async def _create_scenario(self, task):
 2    # [...]
 4    # Create the Gripper Properties
 5    self.sgp = Surface_Gripper_Properties()
 6    self.sgp.d6JointPath = ""
 7    self.sgp.parentPath = "/GripperCone"                # Set the Cone as the parent object
 8    self.sgp.offset = dc.Transform()                    # Offset the transform to the base of the Cone
 9    self.sgp.offset.p.x = 0
10    self.sgp.offset.p.z = -0.1001
11    self.sgp.offset.r = [0.7171, 0, 0.7171, 0]          # Rotate to point gripper in Z direction
12    self.sgp.gripThreshold = 2                          # Set attachment to within 2cm of the base of the Cone
13    self.sgp.forceLimit = 1.0e2                         # Set other limits of the gripper ...
14    self.sgp.torqueLimit = 1.0e3
15    self.sgp.bendAngle = np.pi / 4
16    self.sgp.stiffness = 1.0e4
17    self.sgp.damping = 1.0e3
18    self.sgp.retryClose = False                         # If set to True, surface gripper will keep trying to close until it picks up an object
20    self.surface_gripper = Surface_Gripper(self._dc)    # Create the Gripper
21    self.surface_gripper.initialize(self.sgp)           # Initialize the Gripper with these Properties
23    # [...]

Update Gripper State

The Surface Gripper is updated on every simulation step in the _on_simulation_step function. Use it to update the gripper status, and then change the cone color to RED if it’s closed or GREEN if it’s open.

 1def _on_simulation_step(self, step):
 3    # [...]
 5    self.surface_gripper.update()                       # On every sim step, update the gripper status
 6    if self.surface_gripper.is_closed():                # Assign color to Cone based on current state
 7        self.coneGeom.GetDisplayColorAttr().Set([self.color_closed])
 8    else:
 9        self.coneGeom.GetDisplayColorAttr().Set([self.color_open])
11    # [...]

Toggle the Gripper

The Gripper State is controlled by the on_toggle_gripper_button_clicked function connected to the extension’s UI. It toggle the Gripper State between OPEN and CLOSE.

1def _on_toggle_gripper_button_clicked(self, button):    # When receiving a button press
2    if self._editor.is_playing():
3        if self.surface_gripper.is_closed():            # Toggle Open or Close
5        else:
6            self.surface_gripper.close()