Welcome to the Tesseract wiki

The new planning framework (Tesseract) was designed to be lightweight, limiting the number of dependencies, mainly to only used standard library, eigen, boost, orocos and to the core packages below are ROS agnostic and have full python support.

Tesseract Core Packages

• tesseract – This is the main class that manages the major component Environment, Forward Kinematics, Inverse Kinematics and loading from various data.
• tesseract_collision – This package contains privides a common interface for collision checking prividing several implementation of a Bullet collision library and FCL collision library. It includes both continuous and discrete collision checking for convex-convex, convex-concave and concave-concave shapes.
• tesseract_common – This package contains common functionality needed by the majority of the packages.
• tesseract_environment – This package contains the Tesseract Environment which provides functionality to add,remove,move and modify links and joint. It also manages adding object to the contact managers and provides the ability.
• tesseract_geometry – This package contains geometry types used by Tesseract including primitive shapes, mesh, convex hull mesh, octomap and signed distance field.
• tesseract_kinematics – This package contains a common interface for Forward and Inverse kinematics for Chain, Tree’s and Graphs including implementation using KDL and OPW Kinematics.
• tesseract_planners – This package contains a common interface for Planners and includes implementation for OMPL, TrajOpt and Descartes.
• tesseract_scene_graph – This package contains the scene graph which is the data structure used to manage the connectivity of objects in the environment. It inherits from boost graph and provides addition functionality for adding,removing and modifying Links and Joints along with search implementation.
• tesseract_support – This package contains support data used for unit tests and examples throughout Tesseract.
• tesseract_visualization – This package contains visualization utilities and libraries.
• tesseract_urdf - This package contains a custom urdf parser supporting addition shapes and features currently not supported by urdfdom.

Tesseract ROS Packages

• tesseract_examples – This package contains examples using tesseract and tesseract_ros for motion planning and collision checking.
• tesseract_plugins – This contains plugins for collision and kinematics which are automatically loaded by the monitors.
• tesseract_rosutils – This package contains the utilities like converting from ROS message types to native Tesseract types and the reverse.
• tesseract_msgs – This package contains the ROS message types used by Tesseract ROS.
• tesseract_rviz – This package contains the ROS visualization plugins for Rviz to visualize Tesseract. All of the features have been composed in libraries to enable to the ability to create custom displays quickly.
• tesseract_monitoring – This package contains different types of environment monitors. It currently contains a contact monitor and environment monitor. The contact monitor will monitor the active environment state and publish contact information. This is useful if the robot is being controlled outside of ROS, but you want to make sure it does not collide with objects in the environment. The second is the environment monitor, which is the main environment which facilitates requests to add, remove, disable and enable collision objects, while publishing its current state to keep other ROS nodes updated with the latest environment.

Warning

These packages are under heavy development and are subject to change.

Packages

Tesseract Scene Graph Package

Background

This package contains the scene graph and parsers. The scene graph is used to manage the connectivity of the environment. The scene graph inherits from boost graph so you are able to leverage boost graph utilities for searching.

Scene Graph (Tree)

Scene Graph (Acyclic)

Features

1. Links - Get, Add, Remove, Modify, Show/Hide, and Enable/Disable Collision
2. Joints - Get, Add, Remove, Move and Modify
3. Allowed Collision Matrix - Get, Add, Remove
4. Graph Functions
   • Get Inbound/Outbound Joints for Link
   • Check if acyclic
   • Check if tree
   • Get Adjacent/InvAdjacent Links for Joint
5. Utility Functions
   • Save to Graph to Graph Description Language (DOT)
   • Get shortest path between two Links
6. Parsers
   • URDF Parser
   • SRDF Parser
   • KDL Parser
   • Mesh Parser

Examples

1. Building A Scene Graph
2. Create Scene Graph from URDF
3. Parse SRDF adding ACM to Scene Graph
4. Parse Mesh

Building A Scene Graph

Example Explanation

Create Scene Graph

Add Links

Create the links. The links are able to be configured see Link documentation.

Add the links to the scene graph

Add Joints

Create the joints. The links are able to be configured see Joint documentation.

Add the joints to the scene graph_acyclic_tree_example

Inspect Scene Graph

Get the adjacent links for link_3 and print to terminal

Get the inverse adjacent links for link_3 and print to terminal

Get child link names for link link_3 and print to terminal

Get child link names for joint joint_1 and print to terminal

Save the graph to a file for visualization

Test if the graph is Acyclic and print to terminal

Test if the graph is a tree and print to terminal

Detect Unused Links

First add a link but do not create joint and check if it is a tree. It should return false because the link is not associated with a joint.

Remove link and check if it is a tree. It should return true.

Create Acyclic Graph

Add joint connecting link_5 and link_4 to create an Acyclic graph_acyclic_tree_example

Save the Acyclic graph

Test to confirm it is acyclic, should return true.

Test if it is a tree, should return false.

Get Shortest Path

Create Scene Graph from URDF

Example Explanation

Create Resource Locator

Because this is ROS agnostic you need to provide a resource locator for interpreting package:/.

Load URDF

Get the file path to the urdf file

Create scene graph from urdf

Print information about the scene graph to the terminal

Save the graph to a file.

Parse SRDF adding Allowed Collision Matrix to Graph

Example Explanation

Create Resource Locator

Because this is ROS agnostic you need to provide a resource locator for interpreting package:/.

Load URDF and SRDF

Get the file path to the URDF and SRDF file

Create Scene Graph from URDF

Parse SRDF

Add Allowed Collision Matrix to Scene Graph

Methods for getting Allowed Collision Matrix from Scene Graph

Parse Mesh from file

Example Explanation

Parse Mesh from File

Mesh files can contain multiple meshes. This is a critical difference between MoveIt which merges all shapes in to a single triangle list for collision checking. By keeping each mesh independent, each will have its own bounding box and if you want to convert to a convex hull you will get a closer representation of the geometry.

Print Mesh Information to Terminal

Tesseract Collision Package

Background

This package is a used for performing both discrete and continuous collision checking. It understands nothing about connectivity of the object within. It purely allows for the user to add objects to the checker, set object transforms, enable/disable objects, set contact distance per objects and perform collision checks.

Features

1. Add/Remove collision objects consisting of multiple collision shapes.
2. Enable/Disable collision objects
3. Set collision objects transformation
4. Set contact distance threshold. If two objects are further than this distance they are ignored.
5. Perform Contact Test with various exit conditions
   • Exit on first tesseract::ContactTestType::FIRST
   • Store only closets for each collision object tesseract::ContactTestType::CLOSEST
   • Store all contacts for each collision object tesseract::ContactTestType::ALL

Discrete Collision Checker Example

Example Explanation

Create Contact Checker

There are several available contact checkers.

• Recommended
  • BulletDiscreteBVHManager
  • BulletCastBVHManager
• Alternative
  • BulletDiscreteSimpleManager
  • BulletCastSimpleManager
• Beta
  • FCLDiscreteBVHManager

Add Collision Objects to Contact Checker

Add collision object in a enabled state

Note

A collision object can consist of multiple collision shape.

Add collision object in a disabled state

Add another collision object

Set the active collision object’s

Set the contact distance threshold

Set the collision object’s transform

Perform collision check

Note

One object is inside another object

Set the collision object’s transform

Perform collision check

Note

The objects are outside the contact threshold

Change contact distance threshold

Perform collision check

Note

The objects are inside the contact threshold

Tesseract Geometry Package

Background

This package contains geometries used by Tesseract

Features

1. Primitive Shapes
   • Box
   • Cone
   • Capsule
   • Cylinder
   • Plane
   • Sphere
2. Mesh
3. Convex Mesh
4. SDF Mesh
5. Octree

Creating Geometry Shapes

Example Explanation

1. Create a box.

2. Create a cone.

3. Create a capsule.

4. Create a cylinder.

5. Create a plane.

6. Create a sphere.

7. Create a mesh.

   Note

   This shows how to create a mesh provided vertices and faces. You may also use utilities in tesseract_scene_graph mesh parser to load meshes from file.

8. Create a signed distance field mesh.

   Note

   This should be the same as a mesh, but when interperated as the collision object it will be encoded as a signed distance field.

   Note

   This shows how to create a SDF mesh provided vertices and faces. You may also use utilities in tesseract_scene_graph mesh parser to load meshes from file.

9. Create a convex mesh.

   Warning

   This expects the data to already represent a convex mesh. If yours does not load as a mesh and then use tesseract utility to convert to a convex mesh.

   Note

   This shows how to create a convex mesh provided vertices and faces. You may also use utilities in tesseract_scene_graph mesh parser to load meshes from file.

10. Create an octree.

    Note

    It is benificial to prune the octree prior to creating the tesseract octree shap to simplify

    Octree support multiple shape types to represent a cell in the octree.

    • BOX tesseract_geometry::Octree::SubType::BOX
    • SPHERE_INSIDE tesseract_geometry::Octree::SubType::SPHERE_INSIDE
    • SPHERE_OUTSIDE tesseract_geometry::Octree::SubType::SPHERE_OUTSIDE

Tesseract ROS Package

Tesseract Msgs Package

Tesseract Rviz Package

Tesseract Monitoring Package

Tesseract Planning Package

This is a meta package which contains packages related to motion planning within Tesseract.

Packages

Tesseract URDF Package

Background

This package contains urdf parser used by Tesseract. It supports additional shape and features not supported by urdfdom. This wiki only contains additional items and for more information please refer to http://wiki.ros.org/urdf/XML.

Features

1. New Shapes
   • Capsule
   • Cone
   • Mesh
   • Convex Mesh
   • SDF Mesh
   • Octomap
2. Origin
   • Quaternion
3. Limits
   • Acceleration - Oddly this was not supported by the original urdf specification
4. URDF Version
   • The original implementation of Tesseract interpreted mesh tags different than what is called version 2. It originally converted mesh geometry types to convex hull because there was no way to distinguish different types of meshes. Now in version 2 it supports the shape types (mesh, convex_mesh, sdf_mesh, etc.), therefore in version 2 the mesh tag is now interpreted as a detailed mesh and is no longer converted to a convex hull. To get the same behavior using version 2 change the tag to convex_mesh and set convert equal to true. For backwards compatibility any URDF without a version is assumed version 1 and mesh tags will be converted to convex hulls.

Change URDF Version

<robot name="kuka_iiwa" version="2">
</robot>

Defining New Shapes

Create Capsule

<capsule radius="1" length="2"/>

The total height is the length + 2 * radius, so the length is just the height between the center of each sphere of the capsule caps.

Create Cone

<cone radius="1" length="2"/>

The cone is like the cylinder. It is around z-axis and centered at the origin.

Create Convex Mesh

<convex_mesh filename="package://tesseract_support/meshes/box_2m.ply" scale="1 2 1" convert="false"/>

This will create a convex hull shape type. This shape is more efficient than a regular mesh for collision checking. Also it provides an accurate penetration distance where in the case of mesh type you only get the penetration of one triangle into another.

Parameter	Required/Optional	Description
filename	Required	If convert is false (default) the mesh must be a convex hull represented by a polygon mesh. If it is triangulated such that multiple triangles represent the same surface you will get undefined behavior from collision checking.
scale	Optional	Scales the mesh axis aligned bounding box. Default scale = [1, 1, 1].
convert	Optional	If true the mesh is converted to a convex hull. Default convert = false.

Create SDF Mesh

<sdf_mesh filename="package://tesseract_support/meshes/box_2m.ply" scale="1 2 1" />

This will create a signed distance field shape type, which only affects collision shapes. This shape is more efficient than a regular mesh for collision checking, but not as efficient as convex hull.

Parameter	Required/Optional	Description
filename	Required	A path to a convex or non-convex mesh.
scale	Optional	Scales the mesh axis aligned bounding box. Default scale = [1, 1, 1].

Create Octree/Octomap

There are two methods for creating an octomap collision object. The first is to provide and octree file (.bt | .ot) and the second option is to provide a point cloud file (.pcd) with a resolution.

<octomap shape_type="box" prune="false" >
  <octree filename="package://tesseract_support/meshes/box_2m.bt"/>
</octomap>

<octomap shape_type="box" prune="false" >
  <point_cloud filename="package://tesseract_support/meshes/box_2m.pcd" resolution="0.1"/>
</octomap>

This will create an octomap shape type. Each occupied cell is represented by either a box, shere outside, or sphere inside shape.

Octomap Element

Parameter	Required/Optional	Description
shape_type	Required	Currently three shape types (box, sphere_inside, sphere_outside).
prune	Optional	This executes the octree toMaxLikelihood() the prune() method prior to creating shape which will combine adjacent occupied cell into larget cells resulting in fewer shapes.

Octree Element

Parameter	Required/Optional	Description
filename	Required	A path to a binary or ascii octree file.

Point Cloud Element

Parameter	Required/Optional	Description
filename	Required	A path to a PCL point clound file.
resolution	Required	The resolution of the octree populated by the provided point cloud

Create Origin

<origin xyz="0 0 0" rpy="0 0 0" wxyz="1 0 0 0"/>;

This allows the ability to use a quaternion instead of roll, pitch and yaw values. It is acceptable to have both to allow backwards compatability with other parsers, but the quaternion will take preference over rpy.

Parameter	Required/Optional	Description
wxyz	Optional	A Quaternion = [w, x, y, z]. It will be normalized on creation.

Acceleration Limits

<limit effort="30" velocity="1.0" acceleration="1.0" lower="-2.2" upper="0.7" />

Note

For backwards compatability acceleration is required. If not provided it is assigned to be 0.5 * velocity.

Tesseract SRDF Format

Background

Tesseract has its own SRDF format which is similar to the one used through ROS, but includes features specific to Tesseract.

Example File

<robot name="abb_irb2400" version="1.0.0">
    <group name="manipulator_chain">
        <chain base_link="base_link" tip_link="tool0"/>
    </group>

    <group name="manipulator_joints">
        <joint name="joint_1"/>
        <joint name="joint_2"/>
        <joint name="joint_3"/>
        <joint name="joint_4"/>
        <joint name="joint_5"/>
        <joint name="joint_6"/>
    </group>

    <group_state name="zeros" group="manipulator_joints">
        <joint name="joint_6" value="0"/>
        <joint name="joint_4" value="0"/>
        <joint name="joint_5" value="0"/>
        <joint name="joint_3" value="0"/>
        <joint name="joint_1" value="0"/>
        <joint name="joint_2" value="0"/>
    </group_state>

    <group_state name="zeros" group="manipulator_chain">
        <joint name="joint_6" value="0"/>
        <joint name="joint_4" value="0"/>
        <joint name="joint_5" value="0"/>
        <joint name="joint_3" value="0"/>
        <joint name="joint_1" value="0"/>
        <joint name="joint_2" value="0"/>
    </group_state>

    <group_tcps group="manipulator_chain">
        <tcp name="scanner" xyz="  0   0 0.2" wxyz="1 0 0 0"/>
    </group_tcps>

    <group_tcps group="manipulator_joints">
        <tcp name="scanner" xyz="  0   0 0.2" wxyz="1 0 0 0"/>
    </group_tcps>

    <group_opw group="manipulator_chain" a1="0.10000000000000001" a2="-0.13500000000000001" b="0" c1="0.61499999999999999" c2="0.70499999999999996" c3="0.755" c4="0.085000000000000006" offsets="0.000000 0.000000 -1.570796 0.000000 0.000000 0.000000" sign_corrections="1 1 1 1 1 1"/>

    <disable_collisions link1="link_3" link2="link_5" reason="Never"/>
    <disable_collisions link1="link_3" link2="link_6" reason="Never"/>
    <disable_collisions link1="link_2" link2="link_5" reason="Never"/>
    <disable_collisions link1="link_2" link2="link_4" reason="Never"/>
    <disable_collisions link1="link_4" link2="link_6" reason="Allways"/>
    <disable_collisions link1="link_1" link2="link_5" reason="Never"/>
    <disable_collisions link1="link_3" link2="link_4" reason="Adjacent"/>
    <disable_collisions link1="link_2" link2="link_3" reason="Adjacent"/>
    <disable_collisions link1="base_link" link2="link_1" reason="Adjacent"/>
    <disable_collisions link1="link_1" link2="link_2" reason="Adjacent"/>
    <disable_collisions link1="link_1" link2="link_4" reason="Never"/>
    <disable_collisions link1="base_link" link2="link_4" reason="Never"/>
    <disable_collisions link1="link_1" link2="link_6" reason="Never"/>
    <disable_collisions link1="link_5" link2="link_6" reason="Adjacent"/>
    <disable_collisions link1="base_link" link2="link_5" reason="Never"/>
    <disable_collisions link1="link_1" link2="link_3" reason="Never"/>
    <disable_collisions link1="base_link" link2="link_2" reason="Never"/>
    <disable_collisions link1="link_2" link2="link_6" reason="Never"/>
    <disable_collisions link1="link_4" link2="link_5" reason="Adjacent"/>
    <disable_collisions link1="base_link" link2="link_6" reason="Never"/>
    <disable_collisions link1="base_link" link2="link_3" reason="Never"/>
</robot>

FAQ

Frequently Asked Questions

This wiki highlights the frequently asked questions on the issue tracker.

1. Place Holder 1?
2. Place Holder 2?

Place Holder 1?

TBD

Place Holder 2?

TBD