The Gripper Definition component reads USD gripper files and extracts the parameters needed for grasp generation. It analyzes the gripper's geometry, kinematics, and collision properties to create a definition that can be used by the grasp guess generation system.
This document describes the gripper definition component and its parameters in detail. There are also some examples of its use:
- Gripper Setup Example - Describes in detail how the Robotiq 85 was prepared for use in GraspDataGen
- Running the Gripper Definition Component - Visually verify your gripper will work with the simulation
The gripper definition process:
- Loads a USD gripper file and analyzes its structure
- Identifies finger colliders and their kinematic relationships
- Computes gripper parameters including approach direction, close direction, and collision bodies
- Saves the definition in a format that can be efficiently loaded by other components
The gripper definition code itself, gripper.py, does not have an executable path, but the code that creates the definition does.
python scripts/graspgen/create_gripper_lab.py --gripper_config onrobot_rg6Note: The
--gripper_configoption automatically sets all gripper parameters. For detailed information about gripper configurations and the parameter system, see Parameter System.
This section explains the command line arguments for the gripper in general, found in gripper.py, and those that the gripper creator, create_gripper_lab.py, uses. The gripper definition component also uses shared GraspDataGen Parameters.
The gripper.py file defines the default arguments for a gripper. These are the core gripper configuration parameters:
| Argument | Type | Default | Description |
|---|---|---|---|
--gripper_config |
str | None |
Predefined gripper configuration to use |
--gripper_file |
str | "bots/onrobot_rg6.usd" |
Path to gripper USD file |
--finger_colliders |
list | ["right_inner_finger", "left_inner_finger"] |
Names of finger collider bodies |
--base_frame |
str | "base_frame" |
Name of the base frame origin |
--bite |
float | 0.01 |
Depth of bite from fingertip (meters) |
--pinch_width_resolution |
int | 8 |
Number of pinch opening widths to test |
--open_configuration |
str | "{}" |
Initial joint configuration as JSON |
The create_gripper_lab.py component defines additional arguments/parameters specific to gripper creation:
| Argument | Type | Default | Description |
|---|---|---|---|
--measure_convergence |
flag | False |
Measure convergence of the gripper |
--convergence_iterations |
int | 20 |
Number of simulation iterations for convergence |
The gripper definition system uses several key parameters that are shared across all components:
gripper_file- Path to the USD gripper file (must be flattened for best compatibility)finger_colliders- Names of the two rigid bodies that serve as the gripper's fingersbase_frame- Name of the single rigid body prim that the fingers attach to (should be placed at the origin)bite- Minimum depth from the fingertip used to start grasp location (meters)pinch_width_resolution- Number of pinch opening widths to test during grasp generationopen_configuration- Initial joint configuration as JSON string
GraspDataGen has only been tested with gripper USD files that have been flattened so all their properties are in one file with no external references.
The names you want to use are the names of the two rigid bodies that are the fingers of the gripper. When setting up the gripper, make sure these names are unique.
The single rigid body prim that the fingers attach to. When setting up the gripper, this should be placed at the origin of the scene. All the grasp transforms will be relative to this prim. There should be no transforms attached to this base.
The bite is the minimum length from the end of the fingertip that is used to start the location of the guessed grasp. Consider your gripper grasping a sphere. A bite of 0.0 would mean that the fingertip would be exactly touching the sphere. In the image below, the gripper on the left has a bite that is half the height of the fingertip, and the one on the right has a bite of 0.0.
The pinch width resolution is the number of pinch opening sizes (widths) that the grasp guess generator will test when trying to create collision-free grasps. Consider the image below: with a pinch_width_resolution of 8 (left), there will be 8 opening sizes tested; with a pinch_width_resolution of 2 (right), only the closed and open positions are tested.
Aside from the max open and close positions, and the even spacings in between based on the pinch_width_resolution, you can add a custom opening size to test with the open configuration parameter.
The open_configuration is a string representation of a JSON map of joint names to angles. For example, running the following command will create a gripper definition with a specific open width that will be guaranteed to be tested:
python scripts/graspgen/create_gripper_lab.py --force_headed --gripper_config onrobot_rg6 --pinch_width_resolution 2 --open_configuration '{"finger_joint": -0.31}'
One of the things the gripper creator does is set the gripper joint positions to various opening sizes, and then solve the inverse kinematics for the individual link world-space positions. This process can be problematic if the IK solver can't converge. To monitor convergence, and to enforce smaller steps in the solve if necessary, there are two parameters specific to the gripper creator.
measure_convergence- Measure IK convergence and print the results to the terminal.convergence_iterations- Set a higher number of steps to solve for convergence.
Output the convergence of the IK solve in terms of maximum change in link position each frame. The result is printed to the terminal.
If the IK is not converging, you can increase the number of steps used when solving, which will in turn decrease the timestep size and improve stability.
The gripper definition component is used by several other components in the GraspDataGen system:
- Grasp Guess Generation - Uses gripper parameters to generate geometrically plausible grasps
- Grasp Simulation - The physics-based validation uses the same USD
--gripper_fileused in the grasp guess generation - Batch Data Generation - Processes multiple objects using gripper configurations
GraspDataGen includes predefined gripper configurations that automatically set all gripper parameters. These configurations are defined in scripts/graspgen/gripper_configurations.py and can be used to create new --gripper_config arguments:
robotiq_2f_85- Robotiq 2F-85 parallel gripperonrobot_rg6- OnRobot RG6 gripperfranka_panda- Franka Panda gripper
For more information about the parameter system and configurations, see Parameter System.
The gripper definition process creates:
.npzfile - Binary format containing all gripper parameters and collision data for grasp guessing- Debug output - OBJ files and JSON transforms for debug visualization