Geometry Types

Tesseract supports primitive shapes, meshes, convex hulls, signed distance fields, and octrees for collision and visualization.

The tesseract_geometry package provides the geometry types used throughout Tesseract for both visualization and collision checking. Each geometry type can be attached to links in the scene graph and is used by the collision system.

Overview

Tesseract provides a comprehensive set of geometry types:

Primitive Shapes

Analytically-defined shapes with exact representations:

Shape	Description	Parameters
Box	Axis-aligned rectangular prism	width (x), height (y), depth (z)
Sphere	Perfect sphere	radius
Cylinder	Circular cylinder	radius, length
Cone	Circular cone	radius, length
Capsule	Cylinder with hemispherical end caps	radius, length
Plane	Infinite half-space	normal (a, b, c), offset (d)

• Mesh — General triangle mesh loaded from file or constructed manually. Important: Tesseract keeps each mesh in a file as an independent shape (unlike MoveIt which merges all shapes into a single triangle list). This preserves individual bounding boxes and enables better convex hull approximation.
• Convex Mesh — A mesh guaranteed to be convex. Used for efficient collision checking. The data must already be convex; use Tesseract utilities to convert if needed.

Signed Distance Field

A volumetric, implicit geometry: the signed distance to a surface (negative inside) sampled on a regular axis-aligned grid over a local-frame domain. The grid is stored in a backend-neutral form (domain, per-axis dimensions, and the sampled distances); each collision backend transcodes it into its own native representation when the geometry is added to a contact manager — the Bullet discrete backend builds a btMiniSDF blob for btSdfCollisionShape. It enables true concave volumetric contact and signed-distance/gradient queries, and is the canonical way to use a distance field. Create one in-process from any distance function (analytic, sensor-fused, or a sampler wrapping another library such as OpenVDB) — discretized lazily on demand, or up front with the discrete factory — or load a serialized VDB FloatGrid. VDB import currently accepts one FloatGrid with an axis-aligned, uniform transform.

‍Note: Only the Bullet discrete collision backend consumes a Signed Distance Field — it is concave, so it is not supported by FCL or the continuous/cast managers. This is distinct from the Gazebo "SDF" Simulation Description Format.

Octree

Volumetric representation using an octree data structure. Useful for representing point cloud data (e.g., from depth cameras) as collision geometry.

Octree cells can be represented as different shapes:

• Octree::SubType::BOX — Each cell is a box
• Octree::SubType::SPHERE_INSIDE — Each cell is an inscribed sphere
• Octree::SubType::SPHERE_OUTSIDE — Each cell is a circumscribed sphere

‍Tip: Prune the octree before creating the Tesseract octree shape to simplify the collision geometry.

Examples

See the Creating Geometries Example for complete code demonstrating how to create each geometry type programmatically.

For loading meshes from files, see the mesh parsing utilities in the scene_graph package.

Usage with Links

Geometry objects are assigned to links through Visual and Collision elements:

#include <tesseract_geometry/geometries.h>
#include <tesseract_scene_graph/link.h>
 
// Create a box geometry
auto box = std::make_shared<tesseract_geometry::Box>(0.1, 0.2, 0.3);
 
// Assign to a link's visual
auto visual = std::make_shared<tesseract_scene_graph::Visual>();
visual->geometry = box;
link->visual.push_back(visual);
 
// Assign to a link's collision (can use different geometry)
auto collision = std::make_shared<tesseract_scene_graph::Collision>();
collision->geometry = box;
link->collision.push_back(collision);

Mesh Handling: Tesseract vs MoveIt

A key difference from MoveIt is how mesh files with multiple shapes are handled:

• MoveIt merges all shapes in a mesh file into a single triangle list for collision checking
• Tesseract keeps each mesh independent — each gets its own bounding box, and convex hull conversion produces a closer approximation of the actual geometry

This is particularly important for complex parts where a single convex hull would be a poor approximation, but multiple convex hulls (one per sub-mesh) provide much better coverage.

Next Steps

• Collision Detection — See how geometry is used in collision checking
• Universal Robot Description Format (URDF) — Define geometry in your robot description
• Scene Graph — Attach geometry to links in the scene graph