Skip to content

tesseract_robotics.geometry

Geometric primitives for collision and visualization.

Primitives

Box

Python
from tesseract_robotics.geometry import Box

box = Box(1.0, 0.5, 0.25)  # x, y, z dimensions
print(f"Dimensions: {box.getX()} x {box.getY()} x {box.getZ()}")

Sphere

Python
from tesseract_robotics.geometry import Sphere

sphere = Sphere(0.1)  # radius
print(f"Radius: {sphere.getRadius()}")

Cylinder

Python
from tesseract_robotics.geometry import Cylinder

cylinder = Cylinder(0.05, 0.2)  # radius, length
print(f"Radius: {cylinder.getRadius()}, Length: {cylinder.getLength()}")

Capsule

Python
from tesseract_robotics.geometry import Capsule

capsule = Capsule(0.05, 0.2)  # radius, length

Cone

Python
from tesseract_robotics.geometry import Cone

cone = Cone(0.1, 0.3)  # radius, length

Plane

Python
from tesseract_robotics.geometry import Plane

# ax + by + cz + d = 0
plane = Plane(0, 0, 1, 0)  # XY plane (z = 0)

Meshes

Mesh

Triangle mesh from file.

Python
from tesseract_robotics.geometry import Mesh, createMeshFromPath
import numpy as np

# Load from file
meshes = createMeshFromPath("model.stl")
mesh = meshes[0]

# Access data
vertices = mesh.getVertices()   # list of 3-vectors
faces = mesh.getFaces()         # [count, i0, i1, ..., count, ...]

# With scale
meshes = createMeshFromPath("model.stl", scale=np.array([0.001, 0.001, 0.001]))

Mesh, ConvexMesh and PolygonMesh bind both native constructors. faces is flat: each face is its vertex count followed by that many vertex indices. Every argument after faces is optional and takes the C++ default; the pointer arguments take None for "not set".

Python
from tesseract_robotics.common import BytesResource
from tesseract_robotics.geometry import Mesh, MeshFaceCountError, MeshMaterial
import numpy as np

vertices = [np.array(v, dtype=float) for v in ([0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0])]
faces = np.array([3, 0, 1, 2, 3, 0, 2, 3], dtype=np.int32)

mesh = Mesh(vertices, faces)  # counts the faces
mesh = Mesh(
    vertices, faces,
    resource=BytesResource("square.stl", b"..."),
    scale=np.array([1.0, 1.0, 1.0]),
    normals=[np.array([0.0, 0.0, 1.0])] * 4,
    vertex_colors=[np.array([1.0, 0.0, 0.0, 1.0])] * 4,
    mesh_material=MeshMaterial(np.array([1.0, 0.0, 0.0, 1.0]), 0.0, 0.5, np.zeros(4)),
    mesh_textures=None,
)
mesh = Mesh(vertices, faces, 2)  # face_count given

try:
    Mesh(vertices, faces, 3)
except MeshFaceCountError:  # a ValueError
    pass

The face_count overload exists in C++ to skip counting. Upstream stores the count without checking it; the binding counts the faces anyway and raises MeshFaceCountError when the two disagree, so getFaceCount() always matches getFaces(). PolygonMesh also takes a trailing type=GeometryType.POLYGON_MESH. Fixed-size vectors (scale, each normal) must be numpy arrays: nanobind's Eigen caster refuses a plain list.

ConvexMesh

Convex hull for efficient collision.

Python
from tesseract_robotics.geometry import ConvexMesh, createConvexMeshFromPath

meshes = createConvexMeshFromPath("model.stl")
convex = meshes[0]

getCreationMethod() reports how the mesh was made, as ConvexMesh.CreationMethod: DEFAULT (a new mesh), MESH, or CONVERTED, which the URDF parser sets when tesseract:make_convex turned a mesh into its convex hull. setCreationMethod sets it, and ConvexMesh equality compares it. clone() returns a DEFAULT mesh without normals, colors, material or textures: upstream's clone passes only the vertices, faces, face count, resource and scale (convex_mesh.cpp:77 @ 0.35.0).

Python
from tesseract_robotics.geometry import ConvexMesh

convex.getCreationMethod() == ConvexMesh.CreationMethod.DEFAULT
convex.setCreationMethod(ConvexMesh.CreationMethod.MESH)

CompoundMesh

Multiple mesh parts as single geometry.

Python
from tesseract_robotics.geometry import CompoundMesh, createMeshFromPath

# Combine multiple meshes (a compound needs more than one)
parts = createMeshFromPath("model.stl") + createMeshFromPath("model.stl")
compound = CompoundMesh(parts)

SignedDistanceField

A volumetric geometry: instead of a surface, it stores the signed distance to a surface — negative inside, zero on it, positive outside — sampled on a regular axis-aligned grid in the geometry's local frame. That yields distance and gradient everywhere in the volume, including for concave shapes a convex hull cannot represent, which is what trajectory optimization consumes. The discrete Bullet and FCL contact managers support it; continuous (cast) managers do not, because the field is concave.

Note

Unrelated to the Gazebo "SDF" Simulation Description Format. This replaces the old SDFMesh, which was a mesh despite the name.

From a distance function

The usual entry point. createDiscreteSignedDistanceField evaluates your callable once per grid point and keeps only the samples, so the returned geometry is pure data — it holds no reference to your Python objects and takes no GIL during collision checking.

Python
import numpy as np
from tesseract_robotics.geometry import createDiscreteSignedDistanceField

def sphere(point):            # negative inside, positive outside
    return float(np.linalg.norm(point) - 0.5)

field = createDiscreteSignedDistanceField(
    sphere,
    domain_min=np.array([-1.0, -1.0, -1.0]),
    domain_max=np.array([1.0, 1.0, 1.0]),
    dimensions=np.array([33, 33, 33], dtype=np.int32),  # >= 2 per axis
)

field.getDistance(np.zeros(3))   # -0.5

Pass batched=True to receive every sample point as one (N, 3) float64 array and return N distances — the fast path for a vectorised or GPU evaluator, and one Python call instead of dimensions.prod():

Python
field = createDiscreteSignedDistanceField(
    lambda points: np.linalg.norm(points, axis=1) - 0.5,
    np.array([-1.0, -1.0, -1.0]),
    np.array([1.0, 1.0, 1.0]),
    np.array([33, 33, 33], dtype=np.int32),
    batched=True,
)

From a grid you already have

distances is flat and ordered x-fastest (index = i + nx*(j + ny*k)), so a numpy grid built with indexing="ij" transfers with ravel(order="F") and comes back with reshape(..., order="F").

Python
import numpy as np
from tesseract_robotics.geometry import SignedDistanceField

dims = np.array([33, 33, 33], dtype=np.int32)
lo, hi = np.full(3, -1.0), np.full(3, 1.0)

x, y, z = np.meshgrid(*[np.linspace(lo[i], hi[i], dims[i]) for i in range(3)], indexing="ij")
grid = np.sqrt(x**2 + y**2 + z**2) - 0.5

field = SignedDistanceField(lo, hi, dims, grid.ravel(order="F"))
assert np.allclose(field.getDistances().reshape(dims, order="F"), grid)

From a VDB file

Fields round-trip through the standard OpenVDB and NanoVDB grid formats as raw bytes, so a field baked offline loads directly. The local scale is not stored in the grid and is supplied on read.

Python
from pathlib import Path
from tesseract_robotics.geometry import (
    readSignedDistanceFieldVDB, writeSignedDistanceFieldVDB,
)

field = readSignedDistanceFieldVDB(Path("part.vdb").read_bytes())
Path("out.vdb").write_bytes(writeSignedDistanceFieldVDB(field))

readSignedDistanceFieldNVDB / writeSignedDistanceFieldNVDB do the same for NanoVDB. Both readers accept exactly one FloatGrid with an axis-aligned, uniformly scaled transform.

Lazy fields

createSignedDistanceField keeps your callable as the field's source of truth instead of sampling up front, so queries are exact rather than trilinearly interpolated. dimensions then only sets the resolution used if the grid is ever materialized (on serialization, comparison, or an explicit discretize()).

Prefer the discrete form unless you need that exactness. A lazy field must be thread-safe, and it holds a reference to your callable — so storing one in a module-level global forms a reference cycle the garbage collector cannot see through (the callable reaches its __globals__, which reaches the field, and nanobind instances have no tp_traverse).

Python
from tesseract_robotics.geometry import createSignedDistanceField

field = createSignedDistanceField(sphere, lo, hi, dims)
field.isDiscretized()   # False
field.getDistance(p)    # exact - calls sphere(p)
field.discretize()      # materialize the grid up front

Use a discrete field for collision

The collision backends call getDistance() once per sample point, and each call re-acquires the GIL. contactTest releases the GIL specifically so trajectory sweeps can run in parallel across threads; a lazy field hands that parallelism straight back to the interpreter. Bullet also transcodes the field into its own grid when the geometry is added to a manager, which is one Python call per lattice point.

discretize() does not change this: it fills the grid for serialization and comparison, and getDistance() still calls the sampler, taking the GIL, every time. For pure data, build the field with createDiscreteSignedDistanceField:

Python
from tesseract_robotics.planning import create_obstacle

field = createDiscreteSignedDistanceField(sphere, lo, hi, dims)
create_obstacle(robot, name="field", geometry=field)

Note discretize() holds a process-wide static mutex while calling the sampler, so it must never run on a thread that has released the GIL: that thread would hold the mutex and block on the GIL while a Python thread holding the GIL blocks on the mutex. The bindings avoid this (the VDB writers discretize before releasing the GIL); avoid arranging it yourself from a C++ callback.

Octree

Occupancy octree from 3D sensor data, backed by octomap.

PointCloud → Octree

Python
from tesseract_robotics.geometry import (
    PointCloud, Octree, OctreeSubType, createOctree,
)

# Build a point cloud and convert to an octomap OcTree
pc = PointCloud()
pc.addPoint(0.0, 0.0, 0.0)
pc.addPoint(0.1, 0.0, 0.0)
pc.addPoint(0.0, 0.1, 0.0)

# Or assign whole points: the point type is nested, as in C++ (PointCloud::Point)
pc.points = [PointCloud.Point(0.0, 0.0, 0.0), PointCloud.Point(0.1, 0.0, 0.0)]

ot = createOctree(pc, resolution=0.05, prune=True, binary=True)

# Wrap in a tesseract Octree geometry
octree = Octree(ot, OctreeSubType.BOX, pruned=True, binary_octree=True)
print(octree.calcNumSubShapes())

Building an Octree directly

Python
from tesseract_robotics.geometry import OcTree

ot = OcTree(0.05)  # leaf resolution
ot.updateNode(0.0, 0.0, 0.0, True)
ot.updateNode(0.1, 0.0, 0.0, True)
ot.updateInnerOccupancy()
ot.toMaxLikelihood()
ot.writeBinary("/tmp/scene.bt")

# Load back from file
loaded = OcTree("/tmp/scene.bt")
OctreeSubType Description
BOX Each occupied voxel becomes a box
SPHERE_INSIDE Inscribed sphere per voxel
SPHERE_OUTSIDE Circumscribed sphere per voxel

Utilities & Conversions

Python
from tesseract_robotics.geometry import (
    Box, Sphere, isIdentical, extractVertices, toTriangleMesh,
)
from tesseract_robotics.common import Isometry3d

origin = Isometry3d()
box = Box(1, 1, 1)

# Compare two geometries structurally
isIdentical(box, Box(1, 1, 1))   # True
isIdentical(box, Sphere(1))      # False

# Extract vertices (primitives are converted to a mesh first)
verts = extractVertices(box, origin)        # 8 verts

# Convert a primitive to a triangle Mesh
mesh = toTriangleMesh(box, tolerance=0.01, origin=origin)

Mesh Materials

MeshMaterial

Surface material properties.

Python
from tesseract_robotics.geometry import MeshMaterial
import numpy as np

material = MeshMaterial(
    np.array([1.0, 0.0, 0.0, 1.0]),  # base_color_factor (RGBA red)
    0.0,                             # metallic_factor
    0.5,                             # roughness_factor
    np.zeros(4),                     # emissive_factor (RGBA)
)
material.getBaseColorFactor()

MeshTexture

A texture image and its per-vertex UV coordinates.

Python
from tesseract_robotics.common import BytesResource
from tesseract_robotics.geometry import MeshTexture
import numpy as np

png_bytes = open("texture.png", "rb").read()
uvs = [np.array([0.0, 0.0]), np.array([1.0, 0.0]), np.array([1.0, 1.0]), np.array([0.0, 1.0])]
texture = MeshTexture(BytesResource("texture.png", png_bytes), uvs)
texture.getTextureImage().getUrl()  # "texture.png"

texture_image must be a jpg or png resource. Neither argument takes None (TypeError): upstream stores both without checking them, but a texture without an image or UVs is never valid.

Geometry Base

Geometry

Base class for all geometry types.

Python
from tesseract_robotics.geometry import Geometry, GeometryType

geom = box  # any geometry

# Type checking
geom_type = geom.getType()
if geom_type == GeometryType.BOX:
    print("It's a box")

# Clone
copy = geom.clone()

== compares the geometry type and its UUID, not its content: every constructor and clone() draws a new random UUID, so Box(1, 1, 1) == Box(1, 1, 1) and geom == geom.clone() are False. Use isIdentical to compare content. Each class adds its own fields to ==: the mesh classes compare vertex count, face count and scale (PolygonMesh, Mesh, ConvexMesh, which also compares its creation method). getUUID() returns the UUID as its canonical string; setUUID(str) sets it and raises ValueError for a malformed string, leaving the UUID unchanged.

Python
from tesseract_robotics.geometry import Box, isIdentical

a, b = Box(1, 1, 1), Box(1, 1, 1)
a == b               # False: different UUIDs
isIdentical(a, b)    # True: same content
b.setUUID(a.getUUID())
a == b               # True
GeometryType Description
BOX Rectangular box
SPHERE Sphere
CYLINDER Cylinder
CAPSULE Capsule (cylinder + hemisphere caps)
CONE Cone
PLANE Infinite plane
MESH Triangle mesh
CONVEX_MESH Convex hull
SIGNED_DISTANCE_FIELD Volumetric signed distance field
OCTREE Occupancy octree
COMPOUND_MESH Multiple meshes

Factory Functions

Function Description
createMeshFromPath(path, scale) Load mesh from file
createMeshFromResource(resource, scale) Load mesh from Resource
createConvexMeshFromPath(path, scale) Load as convex hull
createConvexMeshFromResource(resource, scale) Convex from Resource
createMeshFromBytes(url, data, scale) Load mesh from an in-memory file
createConvexMeshFromBytes(url, data, scale) Convex from an in-memory file
createOctree(point_cloud, resolution, prune, binary) Build an octomap OcTree from a PointCloud
createDiscreteSignedDistanceField(sdf, domain_min, domain_max, dimensions, scale, batched) Sample a distance function onto a grid
createSignedDistanceField(sdf, domain_min, domain_max, dimensions, scale, batched) Lazy field backed by a distance function
readSignedDistanceFieldVDB(data, scale) / writeSignedDistanceFieldVDB(sdf) OpenVDB FloatGrid bytes ↔ field
readSignedDistanceFieldNVDB(data, scale) / writeSignedDistanceFieldNVDB(sdf) NanoVDB FloatGrid bytes ↔ field

Every loader also takes flatten, normals, vertex_colors and material_and_texture, all False by default as in C++. Turn the last three on to load a mesh's normals, vertex colors, materials and textures. The URDF parser loads visual meshes with flatten and all three flags on. Every mesh loader defaults to triangulate=True, where the C++ header says false. The URDF parser always triangulates (urdf/src/mesh.cpp:84–88), and Mesh expects triangles.

Python
from tesseract_robotics.geometry import createMeshFromPath

meshes = createMeshFromPath(
    "textured.dae", flatten=True, normals=True, vertex_colors=True, material_and_texture=True
)
meshes[0].getMaterial().getBaseColorFactor()

The …FromBytes loaders take bytes you already hold. The extension of url selects the format, so url must end in .stl, .dae, and so on. The bytes are copied, so the returned meshes do not depend on data afterwards. createMeshFromAsset and extractMeshData are not bound: they take assimp's aiScene, which Python never sees.

Python
from pathlib import Path
from tesseract_robotics.geometry import createMeshFromBytes

data = Path("model.stl").read_bytes()
meshes = createMeshFromBytes("model.stl", data)

Reference

tesseract_geometry Python bindings

GeometryType

Bases: Enum

UNINITIALIZED class-attribute instance-attribute

Python
UNINITIALIZED = 0

SPHERE class-attribute instance-attribute

Python
SPHERE = 1

CYLINDER class-attribute instance-attribute

Python
CYLINDER = 2

CAPSULE class-attribute instance-attribute

Python
CAPSULE = 3

CONE class-attribute instance-attribute

Python
CONE = 4

BOX class-attribute instance-attribute

Python
BOX = 5

PLANE class-attribute instance-attribute

Python
PLANE = 6

MESH class-attribute instance-attribute

Python
MESH = 7

CONVEX_MESH class-attribute instance-attribute

Python
CONVEX_MESH = 8

SIGNED_DISTANCE_FIELD class-attribute instance-attribute

Python
SIGNED_DISTANCE_FIELD = 9

OCTREE class-attribute instance-attribute

Python
OCTREE = 10

POLYGON_MESH class-attribute instance-attribute

Python
POLYGON_MESH = 11

COMPOUND_MESH class-attribute instance-attribute

Python
COMPOUND_MESH = 12

Geometry

getType

Python
getType() -> GeometryType

Get the geometry type

clone

Python
clone() -> Geometry

Create a copy of this geometry

getUUID

Python
getUUID() -> str

UUID as its canonical string

setUUID

Python
setUUID(uuid: str) -> None

Set the UUID from its canonical string; a malformed string raises ValueError

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

GeometriesConst

__init__

Python
__init__() -> None

__len__

Python
__len__() -> int

__getitem__

Python
__getitem__(arg: int) -> Geometry

append

Python
append(arg: Geometry) -> None

clear

Python
clear() -> None

Box

Bases: Geometry

getX

Python
getX() -> float

Get X dimension

getY

Python
getY() -> float

Get Y dimension

getZ

Python
getZ() -> float

Get Z dimension

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

Sphere

Bases: Geometry

getRadius

Python
getRadius() -> float

Get the radius

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

Cylinder

Bases: Geometry

getRadius

Python
getRadius() -> float

Get the radius

getLength

Python
getLength() -> float

Get the length

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

Capsule

Bases: Geometry

getRadius

Python
getRadius() -> float

Get the radius

getLength

Python
getLength() -> float

Get the length

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

Cone

Bases: Geometry

getRadius

Python
getRadius() -> float

Get the radius

getLength

Python
getLength() -> float

Get the length

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

Plane

Bases: Geometry

getA

Python
getA() -> float

Get coefficient a

getB

Python
getB() -> float

Get coefficient b

getC

Python
getC() -> float

Get coefficient c

getD

Python
getD() -> float

Get coefficient d

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

MeshMaterial

getBaseColorFactor

Python
getBaseColorFactor() -> Annotated[NDArray[numpy.float64], dict(shape=4, order=C)]

Get base color (RGBA)

getMetallicFactor

Python
getMetallicFactor() -> float

Get metallic factor (0-1)

getRoughnessFactor

Python
getRoughnessFactor() -> float

Get roughness factor (0-1)

getEmissiveFactor

Python
getEmissiveFactor() -> Annotated[NDArray[numpy.float64], dict(shape=4, order=C)]

Get emissive factor (RGBA)

MeshTexture

__init__

Python
__init__(texture_image: Resource, uvs: Sequence[Annotated[NDArray[float64], dict(shape=2, order=C)] | Sequence[float]]) -> None

Create a texture from a jpg or png image resource and per-vertex UVs

getTextureImage

Python
getTextureImage() -> tesseract_robotics.common.Resource

Get the texture image resource

getUVs

Python
getUVs() -> list[Annotated[NDArray[numpy.float64], dict(shape=2, order=C)]]

Get UV coordinates

MeshFaceCountError

Bases: ValueError

A mesh constructor's face_count disagrees with the number of faces its faces array describes.

PolygonMesh

Bases: Geometry

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

getVertexCount

Python
getVertexCount() -> int

Get number of vertices

getFaceCount

Python
getFaceCount() -> int

Get number of faces

getScale

Python
getScale() -> Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]

Get mesh scale

getVertices

Python
getVertices() -> list[Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]]

getFaces

Python
getFaces() -> Annotated[NDArray[numpy.int32], dict(shape=(None,), order=C)]

getNormals

Python
getNormals() -> list[Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]] | None

Get vertex normals (optional)

getVertexColors

Python
getVertexColors() -> list[Annotated[NDArray[numpy.float64], dict(shape=4, order=C)]] | None

Get vertex colors (optional)

getMaterial

Python
getMaterial() -> MeshMaterial

Get mesh material (optional)

getTextures

Python
getTextures() -> list[MeshTexture] | None

Get mesh textures (optional)

getResource

Python
getResource() -> tesseract_robotics.common.Resource

Get mesh resource

Mesh

Bases: PolygonMesh

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

ConvexMesh

Bases: PolygonMesh

CreationMethod

Bases: Enum

DEFAULT class-attribute instance-attribute
Python
DEFAULT = 0
MESH class-attribute instance-attribute
Python
MESH = 1
CONVERTED class-attribute instance-attribute
Python
CONVERTED = 2

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

getCreationMethod

Python
getCreationMethod() -> ConvexMesh.CreationMethod

How the mesh was made; the URDF parser sets CONVERTED for tesseract:make_convex

setCreationMethod

Python
setCreationMethod(method: CreationMethod) -> None

Set how the mesh was made

SignedDistanceFieldInterpolation

Bases: Enum

How a grid-backed or sparse field is read between its samples

TRILINEAR class-attribute instance-attribute

Python
TRILINEAR = 0

2x2x2 samples; the gradient jumps at cell faces (the default)

TRICUBIC class-attribute instance-attribute

Python
TRICUBIC = 1

4x4x4 samples, Catmull-Rom; the gradient is continuous

SignedDistanceField

Bases: Geometry

getDomainMin

Python
getDomainMin() -> Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]

Get the minimum corner of the sampled domain (local frame)

getDomainMax

Python
getDomainMax() -> Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]

Get the maximum corner of the sampled domain (local frame)

getDimensions

Python
getDimensions() -> Annotated[NDArray[numpy.int32], dict(shape=3, order=C)]

Get the number of samples along each axis

getDistances

Python
getDistances() -> Annotated[NDArray[numpy.float64], dict(shape=(None,), order=C)]

Get the sampled signed distances, flat and x-fastest (index = i + nx*(j + ny*k)). Reshape with .reshape(field.getDimensions(), order='F') for a 3D view. Discretizes a function-backed field on first call. Raises for a sparse field, which has no dense grid.

getScale

Python
getScale() -> Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]

Get the local scaling applied to the field

getDistance

Python
getDistance(point: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float]) -> float

Get the signed distance at a point in the field's local frame. A function-backed field evaluates its sampler directly; a grid-backed field interpolates (see setInterpolation), with the point clamped to the domain. A sparse field returns +inf where it has no answer.

getGradient

Python
getGradient(point: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float]) -> Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]

Get the gradient of the signed distance at a point in the field's local frame (not normalized)

getDistanceAndGradient

Python
getDistanceAndGradient(point: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float]) -> tuple[float, Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]]

Get (distance, gradient) at a point in the field's local frame, from one lookup

isSparse

Python
isSparse() -> bool

Whether this is a sparse field: one NanoVDB grid, or levels of them

getNVDB

Python
getNVDB() -> bytes

A sparse field's grid as its bare NanoVDB grid buffer (empty for a dense, function-backed or multi-level field; a multi-level field's grids are its levels')

getBandClamp

Python
getBandClamp() -> float

A sparse field's band clamp (0 for a dense, function-backed or multi-level field)

getLevels

Python
getLevels() -> list[SignedDistanceField]

A multi-level field's levels, finest first (empty otherwise)

setInterpolation

Python
setInterpolation(interpolation: SignedDistanceFieldInterpolation) -> None

Choose how distances (and, unless setGradientInterpolation overrides it, gradients) are read between samples

getInterpolation

Python
getInterpolation() -> SignedDistanceFieldInterpolation

How the distance is read

setGradientInterpolation

Python
setGradientInterpolation(interpolation: SignedDistanceFieldInterpolation) -> None

Read the gradient with a different method from the distance

getGradientInterpolation

Python
getGradientInterpolation() -> SignedDistanceFieldInterpolation

How the gradient is read (defaults to the distance's method)

isDiscretized

Python
isDiscretized() -> bool

Whether the dense sample grid has been materialized

discretize

Python
discretize() -> None

Materialize the dense sample grid from the sampler (idempotent, no-op if already discretized). A function-backed field must be discretized before it can be serialized or compared; that happens automatically at those boundaries, so call this only to pin the snapshot up front.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

CompoundMesh

Bases: Geometry

__init__

Python
__init__(meshes: Sequence[PolygonMesh]) -> None

getMeshes

Python
getMeshes() -> list[PolygonMesh]

Get the vector of meshes

getResource

Python
getResource() -> tesseract_robotics.common.Resource

Get the resource used to create this mesh

getScale

Python
getScale() -> Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]

Get the scale applied to the mesh

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

OcTree

getResolution

Python
getResolution() -> float

Get the leaf resolution

size

Python
size() -> int

Get the total number of nodes

getNumLeafNodes

Python
getNumLeafNodes() -> int

Get the number of leaf nodes

updateNode

Python
updateNode(x: float, y: float, z: float, occupied: bool, lazy_eval: bool = False) -> None

Insert/update a node at the given coordinate

updateInnerOccupancy

Python
updateInnerOccupancy() -> None

Recompute inner occupancies after lazy updates

toMaxLikelihood

Python
toMaxLikelihood() -> None

Convert occupancy probabilities to a binary maximum-likelihood representation

writeBinary

Python
writeBinary(filename: str) -> bool

Write the octree to a binary .bt file

OctreeSubType

Bases: Enum

BOX class-attribute instance-attribute

Python
BOX = 0

SPHERE_INSIDE class-attribute instance-attribute

Python
SPHERE_INSIDE = 1

SPHERE_OUTSIDE class-attribute instance-attribute

Python
SPHERE_OUTSIDE = 2

PointCloud

points property writable

Python
points: list[Point]

Point

x property writable
Python
x: float
y property writable
Python
y: float
z property writable
Python
z: float

__init__

Python
__init__() -> None

addPoint

Python
addPoint(x: float, y: float, z: float) -> None

Add a point to the cloud

Octree

Bases: Geometry

__init__

Python
__init__(octree: OcTree, sub_type: OctreeSubType, pruned: bool = False, binary_octree: bool = False) -> None

Create an Octree geometry wrapping an octomap OcTree

getOctree

Python
getOctree() -> OcTree

Get the underlying octomap OcTree

getSubType

Python
getSubType() -> OctreeSubType

Get the sub-shape type

getPruned

Python
getPruned() -> bool

Whether the octree was pruned

calcNumSubShapes

Python
calcNumSubShapes() -> int

Calculate the number of sub-shapes (expensive)

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

prune staticmethod

Python
prune(octree: OcTree) -> None

Prune the octomap OcTree using tesseract's occupancy-threshold rule

createOctree

Python
createOctree(point_cloud: PointCloud, resolution: float, prune: bool, binary: bool = True) -> OcTree

Build an octomap OcTree from a PointCloud

createMeshFromPath

Python
createMeshFromPath(path: str, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., triangulate: bool = True, flatten: bool = False, normals: bool = False, vertex_colors: bool = False, material_and_texture: bool = False) -> list[Mesh]

Load mesh from file and return vector of Mesh geometries

createConvexMeshFromPath

Python
createConvexMeshFromPath(path: str, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., triangulate: bool = True, flatten: bool = False, normals: bool = False, vertex_colors: bool = False, material_and_texture: bool = False) -> list[ConvexMesh]

Load mesh from file and return vector of ConvexMesh geometries

createMeshFromResource

Python
createMeshFromResource(resource: Resource, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., triangulate: bool = True, flatten: bool = False, normals: bool = False, vertex_colors: bool = False, material_and_texture: bool = False) -> list[Mesh]

Load Mesh from resource (e.g., package:// URL)

createConvexMeshFromResource

Python
createConvexMeshFromResource(resource: Resource, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., triangulate: bool = True, flatten: bool = False, normals: bool = False, vertex_colors: bool = False, material_and_texture: bool = False) -> list[ConvexMesh]

Load ConvexMesh from resource (e.g., package:// URL)

createMeshFromBytes

Python
createMeshFromBytes(url: str, data: bytes, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., triangulate: bool = True, flatten: bool = False, normals: bool = False, vertex_colors: bool = False, material_and_texture: bool = False) -> list[Mesh]

Load Mesh geometries from an in-memory mesh file; url's extension (.stl, .dae, ...) selects the format

createConvexMeshFromBytes

Python
createConvexMeshFromBytes(url: str, data: bytes, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., triangulate: bool = True, flatten: bool = False, normals: bool = False, vertex_colors: bool = False, material_and_texture: bool = False) -> list[ConvexMesh]

Load ConvexMesh geometries from an in-memory mesh file; url's extension selects the format

createDiscreteSignedDistanceField

Python
createDiscreteSignedDistanceField(sdf: Callable, domain_min: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float], domain_max: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float], dimensions: Annotated[NDArray[int32], dict(shape=3, order=C)] | Sequence[int], scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., batched: bool = False) -> SignedDistanceField

Sample a signed distance function onto a dense grid up front and return the resulting field.

sdf is negative inside the surface and evaluated in the field's local frame. The grid spans [domain_min, domain_max] inclusive with dimensions samples per axis (>= 2 per axis), so the callable is invoked dimensions.prod() times - pass batched=True to evaluate them in one call.

Prefer this over createSignedDistanceField: sdf is called only during this call and is not retained, so the returned field is pure data - no GIL taken during collision checking and no reference back into your Python objects.

createSignedDistanceField

Python
createSignedDistanceField(sdf: Callable, domain_min: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float], domain_max: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float], dimensions: Annotated[NDArray[int32], dict(shape=3, order=C)] | Sequence[int], scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ..., batched: bool = False) -> SignedDistanceField

Create a lazily-evaluated field that keeps the distance function as its source of truth.

No grid is sampled up front: queries and collision backends call sdf directly (exact, no resampling), and the grid is materialized only for serialization or comparison. dimensions is the resolution used when that happens.

Use createDiscreteSignedDistanceField unless you specifically need exact sampling. The field keeps sdf alive and re-enters it from C++, which costs you three things.

  1. sdf must be thread-safe.
  2. Every evaluation takes the GIL, and the collision backends call getDistance() once per sample point. contactTest releases the GIL precisely so trajectory sweeps can run in parallel; a lazy field re-acquires it per query, serializing that work back against the interpreter. discretize() does not change that: it fills the grid for serialization and comparison, and getDistance() still calls sdf, taking the GIL, every time. For pure data use createDiscreteSignedDistanceField.
  3. The field references sdf (and so its globals), so storing it in a module-level global forms a reference cycle the garbage collector cannot see through - drop the field explicitly or keep it out of module scope.

Discretizing from a thread that does not hold the GIL is also a deadlock risk: discretize() holds a process-wide static mutex while calling the sampler, so it must not run inside a GIL-released region. The bindings never do that (the VDB writers discretize up front), but do not arrange it yourself by, say, discretizing from inside a C++ callback.

writeSignedDistanceFieldVDB

Python
writeSignedDistanceFieldVDB(sdf: SignedDistanceField) -> bytes

Serialize a field as a standard OpenVDB FloatGrid (raises if the voxel spacing is non-uniform)

readSignedDistanceFieldVDB

Python
readSignedDistanceFieldVDB(data: bytes, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ...) -> SignedDistanceField

Reconstruct a field from OpenVDB FloatGrid bytes (exactly one axis-aligned, uniformly scaled grid)

writeSignedDistanceFieldNVDB

Python
writeSignedDistanceFieldNVDB(sdf: SignedDistanceField) -> bytes

Serialize a field as a standard NanoVDB file: one FloatGrid, or a multi-level field's levels' grids in order

readSignedDistanceFieldNVDB

Python
readSignedDistanceFieldNVDB(data: bytes, scale: Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float] = ...) -> SignedDistanceField

Reconstruct a field from NanoVDB FloatGrid bytes (exactly one axis-aligned, uniformly scaled grid)

getSignedDistanceFieldNVDBGridNames

Python
getSignedDistanceFieldNVDBGridNames(data: bytes) -> list[str]

The names of the grids in NanoVDB bytes, in file order

isIdentical

Python
isIdentical(geom1: Geometry, geom2: Geometry) -> bool

Check if two geometries are identical

extractVertices

Python
extractVertices(geom: Geometry, origin: Isometry3d) -> list[Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]]

Extract vertices from a geometry, transforming primitives to a mesh first

toTriangleMesh

Python
toTriangleMesh(geom: Geometry, tolerance: float, origin: Isometry3d) -> Mesh

Convert a primitive geometry to a triangle Mesh