Skip to content

tesseract_robotics.collision

Collision detection managers and contact queries.

Contact Managers

DiscreteContactManager

Checks collision at a single configuration.

Python
from tesseract_robotics.collision import ContactResultMap, DiscreteContactManager

# Get from environment
manager = env.getDiscreteContactManager()

# Clone for thread safety
my_manager = manager.clone()

# Set collision objects state
my_manager.setCollisionObjectsTransform(link_transforms)
# or K poses as one (K, 4, 4) float64 array, row k for link_ids[k] (both manager types);
# each row is checked as Isometry3d(matrix) checks it (NotRotationError names the row)
link_ids = list(link_transforms)
poses = np.stack([link_transforms[link_id].matrix for link_id in link_ids])
my_manager.setCollisionObjectsTransform(link_ids, poses)

# Run collision check — fills ContactResultMap
result_map = ContactResultMap()
my_manager.contactTest(result_map, request)

ContinuousContactManager

Checks collision along swept motion.

Python
from tesseract_robotics.collision import ContactResultMap, ContinuousContactManager

# Get from environment
manager = env.getContinuousContactManager()

# Clone for thread safety
my_manager = manager.clone()

# Moving objects: start and end transforms (dict/dict, name + 2 poses, or names + 2 pose lists).
# Static objects take the single-pose overloads.
my_manager.setCollisionObjectsTransform(
    link_transforms_start,
    link_transforms_end
)

# Run continuous collision check
result_map = ContactResultMap()
my_manager.contactTest(result_map, request)

ContactManagersPluginFactory

Loads contact manager plugins (Bullet, FCL) from a YAML config and creates managers.

Python
from pathlib import Path

from tesseract_robotics import get_tesseract_support_path
from tesseract_robotics.collision import ContactManagersPluginFactory

config = get_tesseract_support_path() / "urdf" / "contact_manager_plugins.yaml"
factory = ContactManagersPluginFactory(config, locator)

plugins = factory.getDiscreteContactManagerPlugins()  # dict[str, PluginInfo]
factory.addDiscreteContactManagerPlugin("MyBullet", plugins["BulletDiscreteBVHManager"])
factory.setDefaultDiscreteContactManagerPlugin("MyBullet")
manager = factory.createDiscreteContactManager("MyBullet")   # by registered name
manager = factory.createDiscreteContactManager("adhoc", plugins["BulletDiscreteBVHManager"])

print(factory.getConfig())                 # the config as a YAML string
factory.saveConfig(Path("cm.yaml"))        # OSError if the file cannot be written

The continuous methods mirror the discrete ones. remove…Plugin and setDefault…Plugin raise KeyError for an unknown name; create…ContactManager(name) returns None for one. A manager keeps its factory alive: its code lives in a plugin library the factory loaded, so dropping the factory first is safe.

Contact Request

Configure what contacts to find.

Python
from tesseract_robotics.collision import (
    ContactRequest, ContactTestType
)

request = ContactRequest()
request.type = ContactTestType.ALL  # find all contacts

# Alternatively
request.type = ContactTestType.FIRST    # stop at first contact
request.type = ContactTestType.CLOSEST  # only closest contact
request.type = ContactTestType.LIMITED  # up to max contacts
ContactTestType Description
FIRST Stop at first contact found
CLOSEST Only return closest contact
ALL Return all contacts
LIMITED Return up to N contacts

Validating contacts

ContactRequest.is_valid takes a ContactResultValidator: each contact the manager finds is passed to it, and a False return drops that contact. Subclass it and implement __call__. None (the default) disables validation.

Python
from tesseract_robotics.collision import ContactResultValidator


class IgnoreGripper(ContactResultValidator):
    def __call__(self, result):
        return "gripper" not in result.link_ids


request.is_valid = IgnoreGripper()   # the request keeps the validator alive
manager.contactTest(result_map, request)

contactTest releases the GIL; the validator takes it again for each call, so a contact test with a Python validator also runs from a worker thread. An exception raised in __call__ propagates out of contactTest. The result argument is a copy, so keeping it beyond the call is safe.

Contact Results

ContactResult, ContactResultMap, ContactRequest, ContactManagerConfig and CollisionCheckConfig compare by value (==, with the C++ tolerances) and are unhashable. Two ContactRequests are equal only while they hold the same is_valid validator object.

ContactResult

Single contact between two objects.

Python
from tesseract_robotics.collision import ContactResult, ContactResultVector

# ContactResultMap maps a link pair to its contacts.
# Flatten it to iterate individual contacts.
result_vector = ContactResultVector()
result_map.flattenMoveResults(result_vector)   # or flattenCopyResults()

for contact in result_vector:
    print(f"Contact: {contact.link_ids[0]} <-> {contact.link_ids[1]}")
    print(f"  Distance: {contact.distance}")
    print(f"  Point A: {contact.nearest_points[0]}")
    print(f"  Point B: {contact.nearest_points[1]}")
    print(f"  Normal: {contact.normal}")
Attribute Type Description
distance float Signed distance (negative = penetration)
link_ids list[LinkId] (2) Colliding links (str(link_id) is the link name)
type_id list[int] (2) Collision object type ids
shape_id list[int] (2) Shape index within each link (-1 if unset)
subshape_id list[int] (2) Sub-shape index within each shape (-1 if unset)
nearest_points list[np.ndarray] (2) Nearest points, world frame
nearest_points_local list[np.ndarray] (2) Nearest points, each link's frame
transform list[Isometry3d] (2) Link transforms at the contact
normal np.ndarray Unit contact normal, world frame, from link_ids[0] towards link_ids[1]
cc_time list[float] (2) Continuous collision times (-1 if not continuous)
cc_type list[ContinuousCollisionType] (2) Continuous collision type per link
cc_transform list[Isometry3d] (2) Cast object's end transform, per link

The pair fields hold exactly two items, one per link. Assigning a list of any other length raises TypeError. Every read returns a new list, so contact.link_ids[0] = "x" changes only that copy; assign the whole list instead.

Entry k of every pair field describes the same body, link_ids[k], and normal points from link_ids[0] towards link_ids[1] (moving link_ids[1] along it separates the pair). Which body is slot 0 is the contact manager's choice, not sorted: it is neither alphabetical nor the ContactResultMap key's first(), and it changes with the order the objects were added, their names, the backend and the build. Find a body by link_ids, never by slot.

ContactResultMap

Map from a LinkIdPair, in the order the manager reported the two links (at also takes a (str, str) tuple in that order), to a ContactResultVector. count() is the number of contacts, size() / len() the number of pairs that have at least one.

Python
from tesseract_robotics.collision import ContactResultMap
from tesseract_robotics.planning import Pose, box, create_obstacle

# A box around the robot's base gives the manager something to report
create_obstacle(robot, "obstacle", box(0.6, 0.6, 0.6), Pose.from_xyz(0.0, 0.0, 0.0))
manager = env.getDiscreteContactManager()
manager.setCollisionObjectsTransform(env.getState().link_transforms)

result_map = ContactResultMap()
manager.contactTest(result_map, request)

print(f"{result_map.size()} contact pairs, {result_map.count()} contacts")
print(result_map.getSummary())

# Read: every value is a copy, never a view into the map
for pair, contacts in result_map:                  # (LinkIdPair, ContactResultVector) pairs
    print(pair.first(), pair.second(), len(contacts))
pair, _ = next(iter(result_map))
contacts = result_map.at((str(pair.first()), str(pair.second())))  # KeyError if absent
as_dict = result_map.getContainer()                # dict[LinkIdPair, ContactResultVector]

# Drop every contact that involves the gripper (the vector is live only during the call)
def drop_gripper(key, contacts):
    if "gripper" in (str(key.first()), str(key.second())):
        contacts.clear()

result_map.filter(drop_gripper)

Building a map: addContactResult(key, result) appends, setContactResult(key, result) replaces the pair's results; both also take a ContactResultVector, and both return a copy of the last result stored. A key whose names are out of order raises UnorderedLinkPairError, and an empty vector raises EmptyContactResultsError (both subclass ValueError; upstream only asserts these). clear() empties every vector but keeps the keys, so iteration still yields them with empty vectors until shrinkToFit() removes them. Iteration walks a snapshot, so changing the map inside the loop is safe. addInterpolatedCollisionResults merges a sub-segment's results, setting cc_time / cc_type for the active links, with an optional filter callback.

ContactResultVector

Flat list of ContactResult. Use this for iteration.

Python
from tesseract_robotics.collision import ContactResultVector

all_contacts = ContactResultVector()
result_map.flattenMoveResults(all_contacts)   # or flattenCopyResults to keep map data

for contact in all_contacts:
    print(contact.distance, contact.link_ids)

ContactArrays

ContactResultMap.to_arrays() and ContactResultVector.to_arrays() read every result into numpy arrays in one call. Row r is result r of flattenCopyResults() (of the vector's own order), so arrays.<field>[r] is results[r].<field> for every ContactResult field except link_ids, which becomes links (the distinct links, in order of first appearance) and link_index. Every array is a new C-contiguous copy that owns its buffer: it stays valid after clear(), and writing to it does not change the results.

Python
from tesseract_robotics.collision import ContactArrays, ContactResultMap

result_map = ContactResultMap()
manager.contactTest(result_map, request)
arrays: ContactArrays = result_map.to_arrays()

n = len(arrays.distance)
assert arrays.nearest_points.shape == (n, 2, 3)
for r in range(n):
    a, b = (arrays.links[i] for i in arrays.link_index[r])   # link_ids of result r
    print(a, b, arrays.distance[r], arrays.normal[r])         # normal points from a towards b
Attribute dtype, shape Description
distance float64 (n,) Signed distance, m (negative = penetration)
normal float64 (n, 3) Unit normal, world frame, from slot 0 towards slot 1
nearest_points float64 (n, 2, 3) [r, k]: nearest point of slot k, world frame, m
nearest_points_local float64 (n, 2, 3) [r, k]: the same point in slot k's frame
transform float64 (n, 2, 4, 4) [r, k]: world pose of slot k (a cast's start pose)
type_id, shape_id, subshape_id int32 (n, 2) As on ContactResult, per slot (int in C++)
single_contact_point bool (n,) One contact point given: nearest_points[r, 0] == nearest_points[r, 1]
cc_time float64 (n, 2) Contact time along slot k's cast, 0 to 1; -1 if not cast
cc_type uint8 (n, 2) ContinuousCollisionType value of slot k (the enum's own uint8)
cc_transform float64 (n, 2, 4, 4) [r, k]: end pose of slot k's cast
link_index int32 (n, 2) links[link_index[r, k]] is link_ids[k] of result r
links tuple[LinkId, ...] Distinct links, first appearance row by row, slot 0 before slot 1

Column k of every two-slot array describes links[link_index[r, k]], as on ContactResult.

Configuration

CollisionCheckConfig

Configure collision checking behavior.

Python
from tesseract_robotics.collision import CollisionCheckConfig

config = CollisionCheckConfig()
config.contact_request = request
config.longest_valid_segment_length = 0.01  # for continuous

ContactManagerConfig

Configure contact manager settings.

Python
from tesseract_robotics.collision import ContactManagerConfig
from tesseract_robotics.common import CollisionMarginPairOverrideType

config = ContactManagerConfig()
config.default_margin = 0.025
config.pair_margin_data.setCollisionMargin("link_a", "link_b", 0.05)
config.pair_margin_override_type = CollisionMarginPairOverrideType.REPLACE

manager.applyContactManagerConfig(config)  # manager: a discrete or continuous contact manager

Convex Mesh Generation

Generate convex hulls for collision. makeConvexMesh turns a Mesh into a ConvexMesh; createConvexHull works on a raw point set (Bullet's convex hull computer).

Python
import numpy as np
from tesseract_robotics.collision import ConvexHullError, createConvexHull, makeConvexMesh

from tesseract_robotics.geometry import createMeshFromPath

mesh = createMeshFromPath("model.stl")[0]  # a geometry.Mesh
convex = makeConvexMesh(mesh)

points = [np.array([x, y, z]) for x in (0.0, 1.0) for y in (0.0, 1.0) for z in (0.0, 1.0)]
n_faces, vertices, faces = createConvexHull(points)
# faces is flat: [count, i0, ..., i{count-1}] per face, indexing into vertices.

# shrink > 0 moves every face inwards by that many metres; shrink_clamp > 0 caps it at
# shrink_clamp * (smallest face distance from the hull centre).
n_faces, vertices, faces = createConvexHull(points, shrink=0.1)

A shrink that cannot be applied (larger than the hull, unclamped) raises ConvexHullError (a RuntimeError). An empty point set is not an error: it gives 0 faces.

Convex decomposition (V-HACD)

ConvexDecompositionVHACD splits a triangle mesh into convex hulls, for meshes too concave for a single hull. ConvexDecomposition is its abstract base (no constructor).

Python
from tesseract_robotics.collision import ConvexDecompositionVHACD, FillMode, VHACDParameters

params = VHACDParameters()           # header defaults: 64 hulls, 400000 voxels, FLOOD_FILL
params.max_convex_hulls = 16
params.fill_mode = FillMode.SURFACE_ONLY

# vertices: list of 3-vectors; faces: flat int32 array of [3, i0, i1, i2] per triangle
vertices = [np.array(v) for v in ((0, 0, 0), (1, 0, 0), (0, 1, 0), (0, 0, 1))]
faces = np.array([3, 0, 2, 1, 3, 0, 1, 3, 3, 0, 3, 2, 3, 1, 2, 3], dtype=np.int32)
hulls = ConvexDecompositionVHACD(params).compute(vertices, faces, verbose=False)  # list[ConvexMesh]

compute releases the GIL, so it can run in a worker thread. faces is checked first: a face that is not a triangle raises NonTriangleFaceError, and a count running past the end or an index outside vertices raises MalformedFacesError (both ValueError). Upstream reads faces unchecked. verbose=True (the default, as upstream) prints the parameters and progress to stdout.

Collision Evaluator Types

Used with trajectory optimization.

Python
from tesseract_robotics.collision import CollisionEvaluatorType

CollisionEvaluatorType.DISCRETE           # single config
CollisionEvaluatorType.LVS_DISCRETE       # interpolated discrete
CollisionEvaluatorType.LVS_CONTINUOUS     # swept volume
CollisionEvaluatorType.CONTINUOUS         # continuous

Usage Example

Python
from tesseract_robotics.collision import (
    ContactRequest, ContactTestType, ContactResultMap, ContactResultVector
)

# Setup
manager = env.getDiscreteContactManager().clone()
request = ContactRequest()
request.type = ContactTestType.ALL

# Set state
env.setState({"joint_1": 0.0, "joint_2": 0.0})
state = env.getState()
manager.setCollisionObjectsTransform(state.link_transforms)

# Check collision
results = ContactResultMap()
manager.contactTest(results, request)

# Process results
if not results.empty():
    contacts = ContactResultVector()
    results.flattenMoveResults(contacts)
    for c in contacts:
        if c.distance < 0:
            print(f"Penetration: {c.link_ids} depth={-c.distance:.4f}")

Reference

tesseract_collision Python bindings

ContinuousCollisionType

Bases: Enum

CCType_None class-attribute instance-attribute

Python
CCType_None = 0

CCType_Time0 class-attribute instance-attribute

Python
CCType_Time0 = 1

CCType_Time1 class-attribute instance-attribute

Python
CCType_Time1 = 2

CCType_Between class-attribute instance-attribute

Python
CCType_Between = 3

ContactTestType

Bases: Enum

FIRST class-attribute instance-attribute

Python
FIRST = 0

CLOSEST class-attribute instance-attribute

Python
CLOSEST = 1

ALL class-attribute instance-attribute

Python
ALL = 2

LIMITED class-attribute instance-attribute

Python
LIMITED = 3

CollisionEvaluatorType

Bases: Enum

NONE class-attribute instance-attribute

Python
NONE = 0

DISCRETE class-attribute instance-attribute

Python
DISCRETE = 1

LVS_DISCRETE class-attribute instance-attribute

Python
LVS_DISCRETE = 2

CONTINUOUS class-attribute instance-attribute

Python
CONTINUOUS = 3

LVS_CONTINUOUS class-attribute instance-attribute

Python
LVS_CONTINUOUS = 4

CollisionCheckProgramType

Bases: Enum

ALL class-attribute instance-attribute

Python
ALL = 0

ALL_EXCEPT_START class-attribute instance-attribute

Python
ALL_EXCEPT_START = 1

ALL_EXCEPT_END class-attribute instance-attribute

Python
ALL_EXCEPT_END = 2

START_ONLY class-attribute instance-attribute

Python
START_ONLY = 3

END_ONLY class-attribute instance-attribute

Python
END_ONLY = 4

INTERMEDIATE_ONLY class-attribute instance-attribute

Python
INTERMEDIATE_ONLY = 5

ACMOverrideType

Bases: Enum

NONE class-attribute instance-attribute

Python
NONE = 0

ASSIGN class-attribute instance-attribute

Python
ASSIGN = 1

AND class-attribute instance-attribute

Python
AND = 2

OR class-attribute instance-attribute

Python
OR = 3

CollisionCheckExitType

Bases: Enum

FIRST class-attribute instance-attribute

Python
FIRST = 0

ONE_PER_STEP class-attribute instance-attribute

Python
ONE_PER_STEP = 1

ALL class-attribute instance-attribute

Python
ALL = 2

ContactResult

One contact between two links. Entry k of every two-slot field (link_ids, type_id, shape_id, subshape_id, nearest_points, nearest_points_local, transform, cc_time, cc_type, cc_transform) describes the same body, link_ids[k]; normal points from link_ids[0] towards link_ids[1].

Which body is slot 0 is chosen by the contact manager, not sorted: it is neither alphabetical nor the ContactResultMap key's first(), and it can change with insertion order, object names, the backend and the build. Resolve a body by link_ids, never by slot.

distance property writable

Python
distance: float

Signed distance between nearest_points[0] and nearest_points[1], in m: negative when the links penetrate.

type_id property writable

Python
type_id: list[int]

[k]: the type id (the mask id given to addCollisionObject) of link_ids[k].

Python
link_ids: list[LinkId]

The two links in contact. Entry k of every two-slot field describes link_ids[k]. Which link is first is the contact manager's choice (see the class docstring); never rely on it.

shape_id property writable

Python
shape_id: list[int]

[k]: index of the shape of link_ids[k] in contact (a link can have several).

subshape_id property writable

Python
subshape_id: list[int]

[k]: sub-shape of link_ids[k] in contact (mesh triangle, octree box); -1 for none.

nearest_points property writable

Python
nearest_points: list[Annotated[NDArray[float64], dict(shape=3, order=C)]]

[k]: the point of link_ids[k] nearest the other link, world frame, in m.

nearest_points_local property writable

Python
nearest_points_local: list[Annotated[NDArray[float64], dict(shape=3, order=C)]]

[k]: nearest_points[k] in the frame of link_ids[k] (transform[k] is its world pose), in m.

transform property writable

Python
transform: list[Isometry3d]

[k]: world pose of link_ids[k] (for a cast, its start pose).

normal property writable

Python
normal: Annotated[NDArray[float64], dict(shape=3, order=C)]

Unit vector, world frame: points from link_ids[0] towards link_ids[1], the direction to move link_ids[1] to separate the links.

cc_time property writable

Python
cc_time: list[float]

[k]: where along its cast link_ids[k] is in contact, 0 at its start pose and 1 at its end pose; -1 when link_ids[k] was not cast.

cc_type property writable

Python
cc_type: list[ContinuousCollisionType]

[k]: the ContinuousCollisionType of link_ids[k]; CCType_None when it was not cast.

cc_transform property writable

Python
cc_transform: list[Isometry3d]

[k]: world end pose of the cast of link_ids[k] (identity when it was not cast). The pose at contact interpolates transform[k] and cc_transform[k] at cc_time[k].

single_contact_point property writable

Python
single_contact_point: bool

True when the checker gave one contact point, so nearest_points[0] == nearest_points[1].

__hash__ class-attribute instance-attribute

Python
__hash__: None = None

__init__

Python
__init__() -> None

clear

Python
clear() -> None

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__copy__

Python
__copy__() -> ContactResult

__deepcopy__

Python
__deepcopy__(memo: dict) -> ContactResult

ContactArrays

Every ContactResult of a ContactResultMap or ContactResultVector as arrays, from to_arrays().

n rows, row r for result r in the container's order. Each array owns its buffer (each read returns a view of that buffer), independent of the results it was read from. A field of the same name on ContactResult reads results[r].<field> as arrays.<field>[r]; link_ids becomes links plus link_index.

Slots: column k (axis 1) of every two-slot field describes link_ids[k], the same body for every field of a row. Which body is slot 0 is chosen by the contact manager, not by the binding (see ContactResult.link_ids); resolve a body by links[link_index[r, k]], never by k. normal[r] points from slot 0 towards slot 1.

distance property

Python
distance: Annotated[NDArray[float64], dict(shape=(None,), order=C)]

(n,) float64, m: signed distance between the two nearest points; negative when the bodies penetrate.

normal property

Python
normal: Annotated[NDArray[float64], dict(shape=(None, 3), order=C)]

(n, 3) float64, world frame, unit vector: points from link slot 0 towards slot 1, the direction to move slot 1 to separate the pair.

nearest_points property

Python
nearest_points: Annotated[NDArray[float64], dict(shape=(None, 2, 3), order=C)]

(n, 2, 3) float64, world frame, m: [r, k] is the point of link slot k nearest the other.

nearest_points_local property

Python
nearest_points_local: Annotated[NDArray[float64], dict(shape=(None, 2, 3), order=C)]

(n, 2, 3) float64, m: nearest_points[r, k] in the frame of link slot k (transform[r, k] is that frame's world pose).

transform property

Python
transform: Annotated[NDArray[float64], dict(shape=(None, 2, 4, 4), order=C)]

(n, 2, 4, 4) float64, homogeneous, translation in m: [r, k] is the world pose of link slot k (for a cast, its start pose).

type_id property

Python
type_id: Annotated[NDArray[int32], dict(shape=(None, 2), order=C)]

(n, 2) int32: [r, k] is the type id (the mask id given to addCollisionObject) of link slot k.

shape_id property

Python
shape_id: Annotated[NDArray[int32], dict(shape=(None, 2), order=C)]

(n, 2) int32: [r, k] is the index of the shape of link slot k in contact.

subshape_id property

Python
subshape_id: Annotated[NDArray[int32], dict(shape=(None, 2), order=C)]

(n, 2) int32: [r, k] is the sub-shape (mesh triangle, octree box) of link slot k; -1 for none.

single_contact_point property

Python
single_contact_point: Annotated[NDArray[bool_], dict(shape=(None,), order=C)]

(n,) bool: True when the checker gave one contact point, so nearest_points[r, 0] == nearest_points[r, 1].

cc_time property

Python
cc_time: Annotated[NDArray[float64], dict(shape=(None, 2), order=C)]

(n, 2) float64, dimensionless: [r, k] is where in its cast link slot k is in contact, 0 at its start pose, 1 at its end pose; -1 when slot k was not cast.

cc_type property

Python
cc_type: Annotated[NDArray[uint8], dict(shape=(None, 2), order=C)]

(n, 2) uint8: [r, k] is the ContinuousCollisionType value of link slot k (0 CCType_None, 1 CCType_Time0, 2 CCType_Time1, 3 CCType_Between); ContinuousCollisionType(int(v)) gives the enum.

cc_transform property

Python
cc_transform: Annotated[NDArray[float64], dict(shape=(None, 2, 4, 4), order=C)]

(n, 2, 4, 4) float64, homogeneous, translation in m: [r, k] is the world end pose of the cast of link slot k (identity when slot k was not cast).

Python
link_index: Annotated[NDArray[int32], dict(shape=(None, 2), order=C)]

(n, 2) int32: links[link_index[r, k]] is link_ids[k] of result r.

Python
links: tuple[LinkId, ...]

The distinct links of the results, in order of first appearance (row by row, slot 0 before slot 1). A new tuple per read.

__repr__

Python
__repr__() -> str

ContactResultHeldError

Bases: BufferError

A ContactResultVector call would reallocate or destroy its elements while Python holds a reference to one (x = v[i]).

ContactResultVector

List of ContactResult. v[i] is a reference into the vector: v[i].distance = d writes through. While Python holds such a reference, append, clear and ContactResultMap.flattenMoveResults(v) raise ContactResultHeldError and leave v unchanged; delete the reference, or hold a copy (copy.copy(v[i])), first.

__init__

Python
__init__() -> None

__len__

Python
__len__() -> int

__getitem__

Python
__getitem__(index: int) -> ContactResult

Reference to the element at the index (write-through), kept valid by refusing reallocation while it is held.

append

Python
append(item: ContactResult) -> None

Append a copy of item; raises ContactResultHeldError while an element is held.

clear

Python
clear() -> None

Remove every element; raises ContactResultHeldError while an element is held.

to_arrays

Python
to_arrays() -> ContactArrays

Every result as one ContactArrays: row r of each array is result r.

Rows follow this container's order: ContactResultMap.flattenCopyResults() order for a map, element order for a vector. Each array is a new C-contiguous copy that owns its buffer: it stays valid after clear(), and writing to it does not change the results. For n results it costs one pass in C++ instead of one Python object per field read.

TransformCountMismatchError

Bases: ValueError

setCollisionObjectsTransform(ids, transforms) got a different number of ids than (K, 4, 4) transforms.

EmptyContactResultsError

Bases: ValueError

A ContactResultMap vector overload got an empty ContactResultVector.

ContactResultMap

__hash__ class-attribute instance-attribute

Python
__hash__: None = None

__init__

Python
__init__() -> None

count

Python
count() -> int

size

Python
size() -> int

empty

Python
empty() -> bool

clear

Python
clear() -> None

release

Python
release() -> None

getSummary

Python
getSummary() -> str

flattenCopyResults

Python
flattenCopyResults() -> ContactResultVector

to_arrays

Python
to_arrays() -> ContactArrays

Every result as one ContactArrays: row r of each array is result r.

Rows follow this container's order: ContactResultMap.flattenCopyResults() order for a map, element order for a vector. Each array is a new C-contiguous copy that owns its buffer: it stays valid after clear(), and writing to it does not change the results. For n results it costs one pass in C++ instead of one Python object per field read.

flattenMoveResults

Python
flattenMoveResults(results: ContactResultVector) -> None

Move every result into results (cleared first); raises ContactResultHeldError, before moving anything, while an element of results is held.

__len__

Python
__len__() -> int

at

Python
at(key: LinkIdPair | tuple[str, str]) -> ContactResultVector

Copy of the results stored under key; raises KeyError when it is absent.

getContainer

Python
getContainer() -> dict[tesseract_robotics.common.LinkIdPair, ContactResultVector]

Copy of the underlying map, keyed by LinkIdPair.

__iter__

Python
__iter__() -> Iterator[tuple[tesseract_robotics.common.LinkIdPair, ContactResultVector]]

Iterate over (key, ContactResultVector) pairs, like C++ begin()/end(); a dict iterates keys only. Keys kept by clear() are included with empty vectors.

shrinkToFit

Python
shrinkToFit() -> None

filter

Python
filter(fn: Callable[[LinkIdPair | tuple[str, str], ContactResultVector], None]) -> None

Call fn(key, results) for every pair; what results holds when fn returns replaces the pair's results (clear it to drop them). results is a copy: one kept past the call no longer edits the map.

addInterpolatedCollisionResults

Python
addInterpolatedCollisionResults(sub_segment_results: ContactResultMap, sub_segment_index: int, sub_segment_last_index: int, active_link_ids: Set[LinkId | str], segment_dt: float, discrete: bool, filter: Callable[[LinkIdPair | tuple[str, str], ContactResultVector], None] | None = None) -> None

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

ContactTrajectorySubstepResults

contacts property writable

Python
contacts: ContactResultMap

substep property writable

Python
substep: int

state0 property writable

Python
state0: Annotated[NDArray[float64], dict(shape=(None,), order=C)]

state1 property writable

Python
state1: Annotated[NDArray[float64], dict(shape=(None,), order=C)]

__bool__

Python
__bool__() -> bool

addContact

Python
addContact(substep_number: int, start_substate: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], end_substate: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], new_contacts: ContactResultMap) -> None

numContacts

Python
numContacts() -> int

worstCollision

Python
worstCollision() -> ContactResultVector

ContactTrajectoryStepResults

substeps property writable

Python
substeps: list[ContactTrajectorySubstepResults]

step property writable

Python
step: int

state0 property writable

Python
state0: Annotated[NDArray[float64], dict(shape=(None,), order=C)]

state1 property writable

Python
state1: Annotated[NDArray[float64], dict(shape=(None,), order=C)]

total_substeps property writable

Python
total_substeps: int

__bool__

Python
__bool__() -> bool

addContact

Python
addContact(step_number: int, substep_number: int, num_substeps: int, start_state: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], end_state: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], start_substate: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], end_substate: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], contacts: ContactResultMap) -> None

resize

Python
resize(num_substeps: int) -> None

numSubsteps

Python
numSubsteps() -> int

numContacts

Python
numContacts() -> int

worstSubstep

Python
worstSubstep() -> ContactTrajectorySubstepResults

worstCollision

Python
worstCollision() -> ContactResultVector

mostCollisionsSubstep

Python
mostCollisionsSubstep() -> ContactTrajectorySubstepResults

ContactTrajectoryResults

steps property writable

Python
steps: list[ContactTrajectoryStepResults]

joint_ids property writable

Python
joint_ids: list[JointId]

total_steps property writable

Python
total_steps: int

__bool__

Python
__bool__() -> bool

addContact

Python
addContact(step_number: int, substep_number: int, num_substeps: int, start_state: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], end_state: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], start_substate: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], end_substate: Annotated[NDArray[float64], dict(shape=(None,), order=C)] | Sequence[float], contacts: ContactResultMap) -> None

resize

Python
resize(num_steps: int) -> None

numSteps

Python
numSteps() -> int

numContacts

Python
numContacts() -> int

worstStep

Python
worstStep() -> ContactTrajectoryStepResults

worstCollision

Python
worstCollision() -> ContactResultVector

mostCollisionsStep

Python
mostCollisionsStep() -> ContactTrajectoryStepResults

trajectoryCollisionResultsTable

Python
trajectoryCollisionResultsTable() -> str
Python
collisionFrequencyPerLink() -> str

condensedSummary

Python
condensedSummary() -> str

ContactResultValidator

Approves or rejects contact results: subclass and implement __call__(result) -> bool.

__init__

Python
__init__() -> None

__call__

Python
__call__(result: ContactResult) -> bool

ContactRequest

type property writable

Python
type: ContactTestType

calculate_penetration property writable

Python
calculate_penetration: bool

calculate_distance property writable

Python
calculate_distance: bool

contact_limit property writable

Python
contact_limit: int

is_valid property writable

Python
is_valid: ContactResultValidator | None

Validator called on each contact; return False to reject it. None disables validation.

__hash__ class-attribute instance-attribute

Python
__hash__: None = None

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

ContactManagerConfig

default_margin property writable

Python
default_margin: float | None

pair_margin_override_type property writable

Python
pair_margin_override_type: CollisionMarginPairOverrideType

pair_margin_data property writable

Python
pair_margin_data: CollisionMarginPairData

acm property writable

Python
acm: AllowedCollisionMatrix

acm_override_type property writable

Python
acm_override_type: ACMOverrideType

modify_object_enabled property writable

Python
modify_object_enabled: dict[str, bool]

__hash__ class-attribute instance-attribute

Python
__hash__: None = None

incrementMargins

Python
incrementMargins(increment: float) -> None

scaleMargins

Python
scaleMargins(scale: float) -> None

validate

Python
validate() -> None

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

CollisionCheckConfig

contact_request property writable

Python
contact_request: ContactRequest

type property writable

Python
type: CollisionEvaluatorType

longest_valid_segment_length property writable

Python
longest_valid_segment_length: float

check_program_mode property writable

Python
check_program_mode: CollisionCheckProgramType

exit_condition property writable

Python
exit_condition: CollisionCheckExitType

__hash__ class-attribute instance-attribute

Python
__hash__: None = None

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

CollisionObjectSpec

A single collision object's definition, for addCollisionObjects.

id property writable

Python
id: LinkId

mask_id property writable

Python
mask_id: int

shapes property writable

Python
shapes: list[Geometry]

shape_poses property writable

Python
shape_poses: list[Isometry3d]

enabled property writable

Python
enabled: bool

DiscreteContactManager

getName

Python
getName() -> str

hasCollisionObject

Python
hasCollisionObject(name: LinkId | str) -> bool

removeCollisionObject

Python
removeCollisionObject(name: LinkId | str) -> bool

enableCollisionObject

Python
enableCollisionObject(name: LinkId | str) -> bool

disableCollisionObject

Python
disableCollisionObject(name: LinkId | str) -> bool

isCollisionObjectEnabled

Python
isCollisionObjectEnabled(name: LinkId | str) -> bool

getCollisionObjects

Python
getCollisionObjects() -> list[tesseract_robotics.common.LinkId]

setActiveCollisionObjects

Python
setActiveCollisionObjects(ids: Sequence[LinkId | str]) -> None

getActiveCollisionObjects

Python
getActiveCollisionObjects() -> set[tesseract_robotics.common.LinkId]

setDefaultCollisionMargin

Python
setDefaultCollisionMargin(default_collision_margin: float) -> None

setCollisionMarginPair

Python
setCollisionMarginPair(name1: LinkId | str, name2: LinkId | str, collision_margin: float) -> None

setCollisionMarginData

Python
setCollisionMarginData(collision_margin_data: CollisionMarginData) -> None

setCollisionMarginPairData

Python
setCollisionMarginPairData(pair_margin_data: CollisionMarginPairData, override_type: CollisionMarginPairOverrideType = tesseract_robotics.common.CollisionMarginPairOverrideType.REPLACE) -> None

incrementCollisionMargin

Python
incrementCollisionMargin(increment: float) -> None

setContactAllowedValidator

Python
setContactAllowedValidator(validator: ContactAllowedValidator) -> None

getContactAllowedValidator

Python
getContactAllowedValidator() -> tesseract_robotics.common.ContactAllowedValidator

applyContactManagerConfig

Python
applyContactManagerConfig(config: ContactManagerConfig) -> None

getCollisionMarginData

Python
getCollisionMarginData() -> tesseract_robotics.common.CollisionMarginData

addCollisionObject

Python
addCollisionObject(name: LinkId | str, mask_id: int, shapes: Sequence[Geometry], shape_poses: Sequence[Isometry3d], enabled: bool = True) -> bool

getCollisionObjectGeometries

Python
getCollisionObjectGeometries(name: LinkId | str) -> list[tesseract_robotics.geometry.Geometry]

getCollisionObjectGeometriesTransforms

Python
getCollisionObjectGeometriesTransforms(name: LinkId | str) -> list[tesseract_robotics.common.Isometry3d]

contactTest

Python
contactTest(collisions: ContactResultMap, request: ContactRequest) -> None

clone

Python
clone() -> DiscreteContactManager

An independent copy; it keeps this object alive (gh-72).

addCollisionObjects

Python
addCollisionObjects(objects: Sequence[CollisionObjectSpec]) -> bool

Add the objects in order, as repeated addCollisionObject calls; a repeated id: the last entry decides. False if any failed; the rest are still added.

removeCollisionObjects

Python
removeCollisionObjects(ids: Sequence[LinkId | str]) -> bool

Remove the objects; False if any id was absent (the present ones are still removed).

getCollisionObjectsTransform

Python
getCollisionObjectsTransform(id: LinkId | str) -> tesseract_robotics.common.Isometry3d

The object's world transform; raises IndexError for an id the manager does not hold.

ContinuousContactManager

getName

Python
getName() -> str

hasCollisionObject

Python
hasCollisionObject(name: LinkId | str) -> bool

removeCollisionObject

Python
removeCollisionObject(name: LinkId | str) -> bool

enableCollisionObject

Python
enableCollisionObject(name: LinkId | str) -> bool

disableCollisionObject

Python
disableCollisionObject(name: LinkId | str) -> bool

isCollisionObjectEnabled

Python
isCollisionObjectEnabled(name: LinkId | str) -> bool

addCollisionObject

Python
addCollisionObject(name: LinkId | str, mask_id: int, shapes: Sequence[Geometry], shape_poses: Sequence[Isometry3d], enabled: bool = True) -> bool

getCollisionObjectGeometries

Python
getCollisionObjectGeometries(name: LinkId | str) -> list[tesseract_robotics.geometry.Geometry]

getCollisionObjectGeometriesTransforms

Python
getCollisionObjectGeometriesTransforms(name: LinkId | str) -> list[tesseract_robotics.common.Isometry3d]

getCollisionObjects

Python
getCollisionObjects() -> list[tesseract_robotics.common.LinkId]

setActiveCollisionObjects

Python
setActiveCollisionObjects(ids: Sequence[LinkId | str]) -> None

getActiveCollisionObjects

Python
getActiveCollisionObjects() -> set[tesseract_robotics.common.LinkId]

setCollisionMarginData

Python
setCollisionMarginData(collision_margin_data: CollisionMarginData) -> None

getCollisionMarginData

Python
getCollisionMarginData() -> tesseract_robotics.common.CollisionMarginData

setDefaultCollisionMargin

Python
setDefaultCollisionMargin(default_collision_margin: float) -> None

setCollisionMarginPair

Python
setCollisionMarginPair(name1: LinkId | str, name2: LinkId | str, collision_margin: float) -> None

setCollisionMarginPairData

Python
setCollisionMarginPairData(pair_margin_data: CollisionMarginPairData, override_type: CollisionMarginPairOverrideType = tesseract_robotics.common.CollisionMarginPairOverrideType.REPLACE) -> None

incrementCollisionMargin

Python
incrementCollisionMargin(increment: float) -> None

setContactAllowedValidator

Python
setContactAllowedValidator(validator: ContactAllowedValidator) -> None

getContactAllowedValidator

Python
getContactAllowedValidator() -> tesseract_robotics.common.ContactAllowedValidator

applyContactManagerConfig

Python
applyContactManagerConfig(config: ContactManagerConfig) -> None

contactTest

Python
contactTest(collisions: ContactResultMap, request: ContactRequest) -> None

clone

Python
clone() -> ContinuousContactManager

An independent copy; it keeps this object alive (gh-72).

addCollisionObjects

Python
addCollisionObjects(objects: Sequence[CollisionObjectSpec]) -> bool

Add the objects in order, as repeated addCollisionObject calls; a repeated id: the last entry decides. False if any failed; the rest are still added.

removeCollisionObjects

Python
removeCollisionObjects(ids: Sequence[LinkId | str]) -> bool

Remove the objects; False if any id was absent (the present ones are still removed).

getCollisionObjectsTransform

Python
getCollisionObjectsTransform(id: LinkId | str) -> tesseract_robotics.common.Isometry3d

The object's world transform; raises IndexError for an id the manager does not hold.

ImplicitSDFShape

Callback representation of a signed-distance shape in world coordinates.

distance property writable

Python
distance: Callable[[Annotated[NDArray[float64], dict(shape=3, order=C)]], float]

Signed distance at a world point (negative inside)

gradient property writable

Python
gradient: Callable[[Annotated[NDArray[float64], dict(shape=3, order=C)]], Annotated[NDArray[float64], dict(shape=3, order=C)]]

Gradient of distance at a world point

aabb property writable

Python
aabb: tuple[Annotated[NDArray[float64], dict(shape=3, order=C)], Annotated[NDArray[float64], dict(shape=3, order=C)]]

World axis-aligned bounds of the region searched for contacts, as (min, max)

__init__

Python
__init__() -> None

isValid

Python
isValid() -> bool

Whether the shape has all data the solver needs

ImplicitSDFCollisionConfig

Settings of the multi-start implicit SDF collision solver.

initial_sample_count property writable

Python
initial_sample_count: int

max_iterations property writable

Python
max_iterations: int

max_contacts property writable

Python
max_contacts: int

contact_margin property writable

Python
contact_margin: float

minimum_step property writable

Python
minimum_step: float

duplicate_tolerance property writable

Python
duplicate_tolerance: float

__init__

Python
__init__() -> None

ImplicitSDFContact

A contact between two implicit shapes.

distance property writable

Python
distance: float

point property writable

Python
point: Annotated[NDArray[float64], dict(shape=3, order=C)]

normal property writable

Python
normal: Annotated[NDArray[float64], dict(shape=3, order=C)]

nearest_points property writable

Python
nearest_points: list[Annotated[NDArray[float64], dict(shape=3, order=C)]]

__init__

Python
__init__() -> None

ContactManagersPluginFactory

addSearchPath

Python
addSearchPath(path: str) -> None

getSearchPaths

Python
getSearchPaths() -> list[str]

clearSearchPaths

Python
clearSearchPaths() -> None

addSearchLibrary

Python
addSearchLibrary(library_name: str) -> None

getSearchLibraries

Python
getSearchLibraries() -> list[str]

clearSearchLibraries

Python
clearSearchLibraries() -> None

addDiscreteContactManagerPlugin

Python
addDiscreteContactManagerPlugin(name: str, plugin_info: PluginInfo) -> None

getDiscreteContactManagerPlugins

Python
getDiscreteContactManagerPlugins() -> dict[str, tesseract_robotics.common.PluginInfo]

removeDiscreteContactManagerPlugin

Python
removeDiscreteContactManagerPlugin(name: str) -> None

setDefaultDiscreteContactManagerPlugin

Python
setDefaultDiscreteContactManagerPlugin(name: str) -> None

hasDiscreteContactManagerPlugins

Python
hasDiscreteContactManagerPlugins() -> bool

getDefaultDiscreteContactManagerPlugin

Python
getDefaultDiscreteContactManagerPlugin() -> str

addContinuousContactManagerPlugin

Python
addContinuousContactManagerPlugin(name: str, plugin_info: PluginInfo) -> None

getContinuousContactManagerPlugins

Python
getContinuousContactManagerPlugins() -> dict[str, tesseract_robotics.common.PluginInfo]

removeContinuousContactManagerPlugin

Python
removeContinuousContactManagerPlugin(name: str) -> None

setDefaultContinuousContactManagerPlugin

Python
setDefaultContinuousContactManagerPlugin(name: str) -> None

hasContinuousContactManagerPlugins

Python
hasContinuousContactManagerPlugins() -> bool

getDefaultContinuousContactManagerPlugin

Python
getDefaultContinuousContactManagerPlugin() -> str

saveConfig

Python
saveConfig(file_path: str | PathLike) -> None

getConfig

Python
getConfig() -> str

The factory configuration as a YAML document string.

ConvexHullError

Bases: RuntimeError

createConvexHull failed: Bullet could not apply the requested shrink.

MalformedFacesError

Bases: ValueError

A faces array has a count running past its end or an index outside the vertices.

NonTriangleFaceError

Bases: ValueError

ConvexDecomposition.compute got a face that is not a triangle (count != 3).

FillMode

Bases: Enum

FLOOD_FILL class-attribute instance-attribute

Python
FLOOD_FILL = 0

SURFACE_ONLY class-attribute instance-attribute

Python
SURFACE_ONLY = 1

RAYCAST_FILL class-attribute instance-attribute

Python
RAYCAST_FILL = 2

VHACDParameters

max_convex_hulls property writable

Python
max_convex_hulls: int

resolution property writable

Python
resolution: int

minimum_volume_percent_error_allowed property writable

Python
minimum_volume_percent_error_allowed: float

max_recursion_depth property writable

Python
max_recursion_depth: int

shrinkwrap property writable

Python
shrinkwrap: bool

fill_mode property writable

Python
fill_mode: FillMode

max_num_vertices_per_ch property writable

Python
max_num_vertices_per_ch: int

async_ACD property writable

Python
async_ACD: bool

min_edge_length property writable

Python
min_edge_length: int

find_best_plane property writable

Python
find_best_plane: bool

__init__

Python
__init__() -> None

print

Python
print() -> None

Print the parameters to stdout.

ConvexDecomposition

compute

Python
compute(vertices: Sequence[Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float]], faces: Annotated[NDArray[int32], dict(shape=(None,), order=C)] | Sequence[int], verbose: bool = True) -> list[tesseract_robotics.geometry.ConvexMesh]

Split a triangle mesh into convex hulls. faces is a flat array of [3, i0, i1, i2] per triangle. Raises NonTriangleFaceError for any other count, MalformedFacesError for a count running past the end or an index outside vertices.

ConvexDecompositionVHACD

collideImplicitSDF

Python
collideImplicitSDF(shape0: ImplicitSDFShape, shape1: ImplicitSDFShape, config: ImplicitSDFCollisionConfig = ...) -> list[ImplicitSDFContact]

Contacts between two implicit shapes, within config.contact_margin.

makeImplicitSDFShape

Python
makeImplicitSDFShape(geometry: Geometry, pose: Isometry3d) -> ImplicitSDFShape

World-coordinate implicit shape of a box, sphere, cylinder, cone, capsule or SDF geometry; an invalid shape (isValid() False) for other geometry. The shape's callables keep the geometry alive.

makeConvexMesh

Python
makeConvexMesh(mesh: Mesh) -> tesseract_robotics.geometry.ConvexMesh

Create a ConvexMesh from a Mesh using bullet's convex hull algorithm.

createConvexHull

Python
createConvexHull(input: Sequence[Annotated[NDArray[float64], dict(shape=3, order=C)] | Sequence[float]], shrink: float = -1.0, shrink_clamp: float = -1.0) -> tuple[int, list[Annotated[NDArray[numpy.float64], dict(shape=3, order=C)]], Annotated[NDArray[numpy.int32], dict(shape=(None,), order=C)]]

Convex hull of a point set (Bullet). Returns (n_faces, vertices, faces); faces is a flat array of [count, i0, i1, ...] per face. shrink > 0 moves each face inwards by that amount; shrink_clamp > 0 caps it at shrink_clamp times the hull's inner radius. Raises ConvexHullError when the shrink cannot be applied.