5 Collision and Contact DetectionTop3 Getting Started4 Main Data Types and Data Files

Contents

4 Main Data Types and Data Files

There are three main types of entities in GraspIt!. The first one is a Body, which is characterized by having some geometry (a shape), a transform (its position) and material properties (such as friction coefficient). The second one is a Robot, which is comprised of multiple Bodies (such as its links) as well as information on kinematics, actuation, etc. Finally, a World groups together instances of the other classes and places them in the correct positions relative to each other. Each of these classes has its own data file format, which GraspIt! can load (but, with the exception of the World, not save to). We will detail all of them in this section.

4.1 Bodies

There are two main types of bodies that exist in a GraspIt! simulation world: static bodies (also known as obstacles) and dynamic bodies (such as robot links and objects). Static objects do not participate in the dynamics, but provide collision surfaces for dynamic bodies. Note that this difference mainly applies when the dynamic engine is being used; otherwise, dynamic bodies can be used as static bodies as well. This document describes what makes up a basic GraspIt! body, and what a dynamic body adds to that definition.

Every GraspIt! body has the following data associated with it:

Geometry:
this describes the shape of the body. It is stored as an Inventor scene graph, a format similar to VRML. This structure can contain pure shape nodes such as cubes, spheres, cylinders, and cones, as well as sets of 2D polygons that define a surface. Although GraspIt! (through the Inventor scene graph) can display all of these geometry types, the collision detection system only works with triangles. When any body is imported to a GraspIt! world, it is faceted into triangles, and these are used for detecting collisions and finding contact points. The units in these files are assumed to be millimeters. Note that the origin of a body's coordinate system is the origin of its geometry, as loaded from a file or created by the user. This can be a tricky aspect, as the origin of a body's geometry is fairly arbitrary. To counter this, dynamic bodies also use the notion of center of mass, explained below. However, the origin of a body's coordinate system is always the origin of it's geometry.
Material:
the material affects the amount of friction possible at contacts on this body. For each pair of materials we define a coefficient of friction. When the dynamic engine is not used, GraspIt! uses a static coefficient of friction for all bodies. When not using dynamics, this coefficient only affects grasp quality computations, not the relative motion of the bodies. During the dynamic simulation, the coefficient of friction affects the relative motion of the bodies in contact. We also use a dynamic coefficient: if the relative speed at a contact point exceeds a threshold currently set at 1mm/sec, a kinetic coefficient of friction is used.
Transform:
each body keeps track of the 3D position and orientation of its body frame relative to the GraspIt! world coordinate system.
Name:
a body's name is currently derived from the its filename, except in the case robot links, which are named using the robot's name and their kinematic chain and link numbers.

Dynamic bodies also have the following properties:

Mass:
this is expressed in grams.
Center of mass:
this is a 3D position expressed relative to the body coordinate system. There are two main uses for this. The first one is to provide a stable point for grasp quality computations to use as reference. The second one is to be used as a reference point for transformation between forces and torques in dynamics. It should be more stable than the origin of the body's coordinate system, which is arbitrary.
Inertia tensor:
this is the standard 3x3 mass distribution matrix. It is expressed relative to a coordinate frame that is aligned with the coordinate system of the body, but positioned at the center of mass. When stored in a file, it is scaled by 1/mass so that changes to the mass can be made by changing only the mass value above.
Dynamic state:
two values, q and v, store the current position and velocity of the body's center of mass relative to world coordinates. q is expressed as a 7x1 vector: the first three values are the position, and the last four are the rotation in quaternion form. v is expressed as a 6x1 vector: the first three values are the linear velocity of the body, and the last three are the rotational velocity. When the dynamics updates each body state, the body transform is also updated. If a body is moved in the static mode, the position value of the dynamic state is also updated.

Body Files

Starting from version 2.1, GraspIt! uses an XML format for storing all of its data. For Bodies, there are two types of information that are required: the GraspIt! specific information, such as the parameters shown above, and the geometry itself. Each Body therefore comes with two files:

Here is an example of a typical Body file ($GRASPIT/models/objects/flask.xml): 

<?xml version="1.0" ?>
<root>
	<material>glass</material>
	<mass>300</mass>
	<cog>0 0 0</cog>
	<inertia_matrix>4853.0 -1.1196 -6.5156 -1.1196 4853.0 47.542 -6.5156 0.0 2357.6</inertia_matrix>
	<geometryFile type="Inventor">flask.iv</geometryFile>
</root>

The format is fully XML adherent, you should be able to also read it in with any XML parser (such as your web browser). This is the list of tags that GraspIt! will look for in the Body file:

For more examples, see the body files included with the distribution, in $GRASPIT/models/objects.

4.2 Robots

A Robot is made up of multiple links, connected into kinematic chains. A link is simply a dynamic body, as described above. A Robot always has a base link (called "palm" for hands) and one or more kinematic chains attached to it. Each chain is in turn made up of a succession of links, connected by joints. In order to define a robot, two things are needed: the Body files for all the links that are part of the Robot, plus an overall Robot configuration file, which has all the kinematic information and references the appropriate body files for the links. Here we describe the structure of the Robot configuration file.

Robot configuration files can seem daunting at first, and they are a bit annoying to get used to. However, you can start from one of the many robots that are included with this distribution, and use it as a starting block for your own robot that you are trying to build. Starting in version 2.1, GraspIt! robot files are now stored in an XML compatible format.

In general, a Robot configuration file contains the following data:

In this example, we will walk through the file for the Robonaut hand. The first XML tag, <robot>, encloses the entire contents of the file. It also has a specified property type, which tells GraspIt! whether this is a generic robot or hand or a particular subclass of one of those. A hand should use the "Hand" type. In some cases, if a robot has special features or its own inverse kinematics algorithm, it is necessary to use a subclass of these generic types, such as "Barrett", or "Puma560": 

<robot type="Robonaut">
... (rest of Robot file)
</robot>

The next item is the filename for the palm link: 

<palm>right_palm.xml</palm>

Degrees of Freedom

In each robot file, we have a set of degree of freedom tags <dof>, each describing one DOF of the robot. Note that a DOF can be connected to one or more joints in the kinematic chains, this information will be supplied later in the Robot configuration file. For more details about DOF's and joints in GraspIt!, see the Joint Coupling and Underactuated Hands chapter. Also note that the ORDER in which <dof> tags appear in the file is important: dof's will later be referenced by their position in this order!

For each DOF, the XML tag contains the following information:

Here's an example <dof> tag from the Robonaut.xml file: 

    <dof type="r">
        <defaultVelocity>1.0</defaultVelocity>
        <maxEffort>5.0e+9</maxEffort>
        <Kp>1.0e+10</Kp>
        <Kd>1.0e+7</Kd>
        <draggerScale>10</draggerScale>
    </dof>

Kinematic Chains

Each kinematic chain is stored in the tag chain. This tag has no properties, and can contain the following sub-tags:

Example of a kinematic chain from the Robonaut.xml file: 

    <chain>
        <transform>
            <translation>46.183982 -26.490473 5.890768</translation>
            <rotationMatrix>0.56107 -0.820276 -0.111118 0.145778 0.230056 -0.962197 0.814831 0.523661 0.248656</rotationMatrix>
        </transform>
        <joint type="Revolute">
            <theta>d0</theta>
            <d>0</d>
            <a>6.35</a>
            <alpha>90</alpha>
            <minValue>-60</minValue>
            <maxValue>5</maxValue>
        </joint>
        <joint type="Revolute">
            <theta>d1+8.9</theta>
            <d>0</d>
            <a>46.8376</a>
            <alpha>0</alpha>
            <minValue>-30</minValue>
            <maxValue>85</maxValue>
        </joint>
        <joint type="Revolute">
            <theta>d2</theta>
            <d>0</d>
            <a>0</a>
            <alpha>0</alpha>
            <minValue>0</minValue>
            <maxValue>75</maxValue>
        </joint>
        <link dynamicJointType="Revolute">tyoke.xml</link>
        <link dynamicJointType="Revolute">thumbphl.xml</link>
        <link dynamicJointType="Revolute">thdph1.xml</link>
    </chain>

Finally, the Robot file can contain some optional tags. These usually includes things such as Eigengrasp information, connection to a Flock of Birds sensor, etc. These are described in more detail in the dedicated chapters of this manual.

4.3 Worlds

In GraspIt!, robots and bodies populate a simulation world. This document describes how these elements can be added or deleted from a world and describes the format of a world file, which stores the current state of the world.

When GraspIt! begins the world is empty. The user may either load a previously saved world by choosing File -> Open, or populate the new world. To import an obstacle (a static body) or an object (a dynamic body), use File -> Import Obstacle or File -> Import Object, and then choose the Body file (see the previous section on bodies). Note that any Body file (regardless of whether it's meant for a static or dynamic body) can be loaded as an obstacle (GraspIt! will just ignore the dynamic parameters). However, when a body file is imported as an Object, GraspIt! will automatically instantiate it as a dynamic body. It will also try to find the dynamic parameters in the body file and, if it can not find them, assign default values. Be aware that the default values occasionally have unpredictable results.

To import a robot, use File -> Import Robot, open the correct robot folder, and select the robot configuration (.xml) file.

To delete a body, select it, and then press the <DELETE> key. To remove a robot, first select the entire robot (by double-clicking one of the links when the selection tool is active) and press the <DELETE> key.

Note: newly imported bodies or robots always appear at the world origin. You can move existing bodies out of the way before importing a new one. If you do not, than the newly imported body will overlap with an old one, and you will have to temporarily toggle collisions in order to move one of them out of the way.

When the user selects "Save" in the file menu, GraspIt! saves the current world state in an world file using an XML-compatible format. This file can contain the following tags:

For an example, take a look at the barrettGlassDyn.xml file supplied with this GraspIt! distribution.

4.4 Data files from previous versions of GraspIt!

Starting with version 2.1, GraspIt! loads all of its data (Bodies, Robots and Worlds) from a new, XML-compatible format. The new version is not backwards-compatible, meaning that the old data files will no longer work.

To help with the transition we have included a stand-alone converter that will convert your old data files to the new format. This converter is included in $GRASPIT/xmlconverter.

You will need to build the converter separately, starting from the Qt project file xmlconverter.pro. Here are the steps:

Once you have the executable, you can use it to convert any of the old GraspIt! data files. Just type xmlconverter [filename]. It will automatically figure out the type of the file being converted based on its extension. You can convert the following files:

Copyright (C) 2002-2009 Columbia University


5 Collision and Contact DetectionTop3 Getting Started4 Main Data Types and Data FilesContents