Isaac Grasp File

To execute a grasp on an identified object, it is useful to keep a reference file of known high quality grasps and to choose a grasp from that file that works the best in context. An isaac_grasp file is a YAML file that follows a human-readable format for storing pre-defined grasps.

Isaac Grasp Specification

A single isaac_grasp file stores a list of grasps for a specific gripper and object pair. The file uses the following format:

 1format: isaac_grasp
 2format_version: 1.0
 3
 4# These reference frames come from a grasp authored in USD, but grasps authored elsewhere
 5# will have alternative metadata.
 6object_frame: /World/mug
 7gripper_frame: /World/panda_hand
 8
 9grasps:
10  "grasp_0":
11    confidence: 1.0
12    position: [-0.04346, 0.06759, 0.19895]
13    orientation: {w: 0.00332, xyz: [0.98453, 0.16837, 0.04837]}
14    cspace_position:
15      panda_finger_joint1: 0.00943
16    pregrasp_cspace_position:
17      panda_finger_joint1: 0.04

A grasp is defined by the relative pose of the gripper with respect to the object. For this relative pose to have meaning, a representative frame must be chosen for the gripper and object. The gripper_frame and object_frame fields are a reference for human readers of what frames were used when defining a grasp.

Note

Do not rely on these fields in code, because the context for the authored grasp may differ.

In the example YAML snippet above, the grasp was authored using USD objects and the corresponding frames are USD paths. In other contexts, the reference frames might correspond to the implicit coordinate system of the object mesh and a frame from the robot URDF file.

Note

It is up to the consumer of an Isaac Grasp file to ensure that the gripper and object frames used to interpret a grasp exactly match the frames used when authoring or generating the grasp.

Each grasp in an isaac_grasp file has a unique (but otherwise arbitrary) name, e.g. "grasp_0" in the example above. The fields for a named grasp are:

  • confidence: A parameter between 0.0 and 1.0 describing the quality of a grasp.

  • position: The translation of the gripper frame relative to the object frame.

  • orientation: The orientation of the gripper frame relative to the object frame.

  • cspace_position: A dictionary of joint positions for every joint that is used to control the gripper. These joint positions are the state of the gripper as it is actively grasping the object.

  • pregrasp_cspace_position: A dictionary of joint positions for every joint that is used to control the gripper. These joint positions represent the open position of the gripper.

All together, a grasp may be applied, in practice, by moving the gripper to the correct relative position and orientation while in the pregrasp_cspace_position, then closing the gripper until the joints are in the cspace_position. If the object’s position and orientation in the world frame of reference is given by \(T_o, R_o\), with the position and orientation fields specifying relative transformation \(^oT_g, ^o\!\!R_g\) (that is, the translation and rotation of the gripper according to the object frame of reference), the desired position of the gripper in the world frame \(T_g , R_g\) is given by:

\[\begin{split}T_g = R_o \cdot {^oT_g + T_o} \\ R_g = R_o \cdot {^o\!R_g}\end{split}\]