Skip to content

tesseract_robotics.scene_graph

Scene graph elements: links, joints, and kinematic tree.

SceneGraph

The kinematic tree structure.

Python
from tesseract_robotics.scene_graph import Joint, JointType, Link, SceneGraph

graph = SceneGraph()
graph.setName("my_robot")

# Add elements: a chain base_link -> link_1 -> ... -> link_4 -> tool0
names = ["base_link", "link_1", "link_2", "link_3", "link_4", "tool0"]
for name in names:
    graph.addLink(Link(name))
for parent, child in zip(names, names[1:]):
    joint = Joint(f"{parent}_to_{child}")
    joint.type = JointType.FIXED
    joint.parent_link_id = parent
    joint.child_link_id = child
    graph.addJoint(joint)

# Query structure
links = graph.getLinks()
joints = graph.getJoints()
root = graph.getRoot()

# Find elements
link = graph.getLink("base_link")
joint = graph.getJoint("base_link_to_link_1")

# Kinematic queries
child_links = graph.getLinkChildrenIds("base_link")
moved_links = graph.getJointChildrenIds("base_link_to_link_1")   # links below the joint
moved_links = graph.getJointChildrenIds(["base_link_to_link_1", "link_1_to_link_2"])  # union, no duplicates, unordered
path = graph.getShortestPath("base_link", "tool0")

# Which listed link each link moves with: a listed link maps itself and every link
# below it, stopping at another listed link; an unknown name raises KeyError
graph.getAdjacencyMap(["link_2", "link_4"])  # {"link_2": "link_2", "link_3": "link_2", "link_4": "link_4", ...}

Allowed collision matrix

getAllowedCollisionMatrix() returns the graph's own matrix, and setAllowedCollisionMatrix(acm) makes the graph keep acm itself, so later edits to acm show up in isCollisionAllowed. setAllowedCollisionMatrix(None) raises TypeError and leaves the matrix in place: upstream would store a null pointer that the next ACM call dereferences.

Python
from tesseract_robotics.common import AllowedCollisionMatrix

acm = AllowedCollisionMatrix()
acm.addAllowedCollision("link_1", "link_2", "adjacent")
graph.setAllowedCollisionMatrix(acm)
graph.isCollisionAllowed(("link_1", "link_2"))  # True

A rigid body in the kinematic tree.

Python
from tesseract_robotics.scene_graph import Link, Visual, Collision
from tesseract_robotics.geometry import Box
from tesseract_robotics.common import Isometry3d

# Create link
link = Link("my_link")

# Add visual geometry
visual = Visual()
visual.geometry = Box(0.1, 0.1, 0.1)
visual.origin = Isometry3d.Identity()
link.addVisual(visual)  # Note: use addVisual(), not visual.append()

# Add collision geometry
collision = Collision()
collision.geometry = Box(0.1, 0.1, 0.1)
collision.origin = Isometry3d.Identity()
link.addCollision(collision)

# Access geometries
visuals = link.visual       # list[Visual]
collisions = link.collision # list[Collision]

# Clear geometries
link.clearVisual()
link.clearCollision()

# Hide the link, or take it out of collision checking (both True by default)
link.visible = False
link.collision_enabled = False

clone() copies visible and collision_enabled, and == compares them. Link stays unhashable: getHash() hashes only the name, while == compares more.

Visual

Visual representation of a link.

Python
from tesseract_robotics.scene_graph import Visual, Material

visual = Visual()
visual.name = "visual_0"
visual.geometry = geometry
visual.origin = transform

# Material (optional)
material = Material("red")  # the name is fixed at construction; getName() reads it
material.color = np.array([1.0, 0.0, 0.0, 1.0])  # RGBA
visual.material = material

Collision

Collision geometry of a link.

Python
from tesseract_robotics.scene_graph import Collision

collision = Collision()
collision.name = "collision_0"
collision.geometry = geometry
collision.origin = transform

Joint

Connection between two links.

Python
from tesseract_robotics.scene_graph import Joint, JointType

joint = Joint("joint_1")
joint.type = JointType.REVOLUTE
joint.parent_link_id = "link_0"
joint.child_link_id = "link_1"
joint.parent_to_joint_origin_transform = Isometry3d.Identity()
joint.axis = np.array([0.0, 0.0, 1.0])  # rotation axis

JointType

Type Description
REVOLUTE Rotational with limits
CONTINUOUS Rotational, no limits
PRISMATIC Linear sliding
FIXED No motion
FLOATING 6-DOF free motion
PLANAR 2D motion in a plane

str() of a joint type is upstream's operator<<, so str(JointType.REVOLUTE) is "Revolute" ("Unknown" for UNKNOWN). .name ("REVOLUTE") and repr() ("JointType.REVOLUTE") are unchanged.

Printing joint values and paths

JointDynamics, JointLimits, JointSafety, JointCalibration, JointMimic and ShortestPath print with upstream's operator<<; the shorter repr() of JointDynamics and JointLimits stays.

Python
from tesseract_robotics.scene_graph import JointLimits

print(JointLimits(-1, 1, 10, 2, 3, 4))
# lower=-1 upper=1 effort=10 velocity=2 acceleration=3 jerk=4

print(graph.getShortestPath("base_link", "tool0"))
# Links:
#   base_link
#   ...
# Joints:
#   ...
# Active Joints:
#   ...

JointLimits

Python
from tesseract_robotics.scene_graph import JointLimits

limits = JointLimits()
limits.lower = -3.14
limits.upper = 3.14
limits.velocity = 2.0
limits.acceleration = 5.0
limits.effort = 100.0

joint.limits = limits

JointDynamics

Python
from tesseract_robotics.scene_graph import JointDynamics

dynamics = JointDynamics()
dynamics.damping = 0.1
dynamics.friction = 0.05

joint.dynamics = dynamics

JointMimic

Python
from tesseract_robotics.scene_graph import JointMimic

mimic = JointMimic()
mimic.joint_id = "joint_1"  # joint to mimic
mimic.multiplier = 1.0
mimic.offset = 0.0

joint.mimic = mimic

Inertial

Mass and inertia properties.

Python
from tesseract_robotics.scene_graph import Inertial

inertial = Inertial()
inertial.origin = Isometry3d.Identity()
inertial.mass = 1.0
inertial.ixx = 0.01
inertial.iyy = 0.01
inertial.izz = 0.01
inertial.ixy = 0.0
inertial.ixz = 0.0
inertial.iyz = 0.0

link.inertial = inertial

SceneState

Current state of the scene graph. The class is bound in state_solver; scene_graph.SceneState is the same object, imported on first access (the state-solver extension imports this module's extension, so an eager re-export would be an import cycle).

Python
from tesseract_robotics.scene_graph import SceneState

state = env.getState()

# Joint positions
positions = state.joints  # dict[str, float]

# Link transforms
transforms = state.link_transforms  # dict[str, Isometry3d]
tcp_pose = transforms["tool0"]

floating_joints, getFloatingJointValues and == are described with the state solver: SceneState.

Reference

tesseract_scene_graph Python bindings

JointType

Bases: Enum

UNKNOWN class-attribute instance-attribute

Python
UNKNOWN = 0

REVOLUTE class-attribute instance-attribute

Python
REVOLUTE = 1

CONTINUOUS class-attribute instance-attribute

Python
CONTINUOUS = 2

PRISMATIC class-attribute instance-attribute

Python
PRISMATIC = 3

FLOATING class-attribute instance-attribute

Python
FLOATING = 4

PLANAR class-attribute instance-attribute

Python
PLANAR = 5

FIXED class-attribute instance-attribute

Python
FIXED = 6

__str__

Python
__str__() -> str

JointDynamics

damping property writable

Python
damping: float

Viscous damping [N·s/m or N·m·s/rad].

friction property writable

Python
friction: float

Static friction [N or N·m].

clear

Python
clear() -> None

Reset to zero.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__str__

Python
__str__() -> str

__repr__

Python
__repr__() -> str

JointLimits

lower property writable

Python
lower: float

Lower position limit [m or rad].

upper property writable

Python
upper: float

Upper position limit [m or rad].

effort property writable

Python
effort: float

Effort limit [N or N·m].

velocity property writable

Python
velocity: float

Velocity limit [m/s or rad/s].

acceleration property writable

Python
acceleration: float

Acceleration limit [m/s² or rad/s²].

jerk property writable

Python
jerk: float

Jerk limit [m/s³ or rad/s³].

clear

Python
clear() -> None

Reset every limit to zero.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__str__

Python
__str__() -> str

__repr__

Python
__repr__() -> str

JointSafety

soft_upper_limit property writable

Python
soft_upper_limit: float

Upper soft limit [m or rad].

soft_lower_limit property writable

Python
soft_lower_limit: float

Lower soft limit [m or rad].

k_position property writable

Python
k_position: float

Position gain of the safety controller.

k_velocity property writable

Python
k_velocity: float

Velocity gain of the safety controller.

clear

Python
clear() -> None

Reset to zero.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__str__

Python
__str__() -> str

JointCalibration

reference_position property writable

Python
reference_position: float

Reference position [m or rad].

rising property writable

Python
rising: float

Rising-edge position [m or rad].

falling property writable

Python
falling: float

Falling-edge position [m or rad].

clear

Python
clear() -> None

Reset to zero.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__str__

Python
__str__() -> str

JointMimic

offset property writable

Python
offset: float

Offset added after the multiplier [m or rad].

multiplier property writable

Python
multiplier: float

Factor applied to the mimicked joint's value.

joint_id property writable

Python
joint_id: JointId

The mimicked joint.

clear

Python
clear() -> None

Reset to offset 0, multiplier 1, no joint.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__str__

Python
__str__() -> str

Joint

type property writable

Python
type: JointType

The joint type.

axis property writable

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

The joint axis, in the joint frame (unit vector).

Python
child_link_id: LinkId

The link this joint moves.

Python
parent_link_id: LinkId

The link this joint is attached to.

parent_to_joint_origin_transform property writable

Python
parent_to_joint_origin_transform: Isometry3d

The joint frame in the parent link's frame.

dynamics property writable

Python
dynamics: JointDynamics

Damping and friction, or None.

limits property writable

Python
limits: JointLimits

Position, velocity, acceleration, jerk and effort limits, or None.

safety property writable

Python
safety: JointSafety

Soft limits, or None.

calibration property writable

Python
calibration: JointCalibration

Calibration edges, or None.

mimic property writable

Python
mimic: JointMimic

The joint this one mimics, or None.

getName

Python
getName() -> str

The joint name.

getId

Python
getId() -> tesseract_robotics.common.JointId

The joint id.

clear

Python
clear() -> None

Reset every field.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

Material

texture_filename property writable

Python
texture_filename: str

Texture image path, or empty.

color property writable

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

RGBA color, each in [0, 1].

getName

Python
getName() -> str

The material name.

getDefaultMaterial staticmethod

Python
getDefaultMaterial() -> Material

The material links without one are drawn with.

clear

Python
clear() -> None

Reset the color and texture.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

Inertial

origin property writable

Python
origin: Isometry3d

The center of mass frame, in the link frame.

mass property writable

Python
mass: float

Mass [kg].

ixx property writable

Python
ixx: float

Inertia tensor entry [kg·m²], in the origin frame.

ixy property writable

Python
ixy: float

Inertia tensor entry [kg·m²], in the origin frame.

ixz property writable

Python
ixz: float

Inertia tensor entry [kg·m²], in the origin frame.

iyy property writable

Python
iyy: float

Inertia tensor entry [kg·m²], in the origin frame.

iyz property writable

Python
iyz: float

Inertia tensor entry [kg·m²], in the origin frame.

izz property writable

Python
izz: float

Inertia tensor entry [kg·m²], in the origin frame.

__init__

Python
__init__() -> None

clear

Python
clear() -> None

Reset to zero mass and inertia.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

Visual

origin property writable

Python
origin: Isometry3d

The geometry's frame, in the link frame.

geometry property writable

Python
geometry: Geometry

The geometry drawn.

material property writable

Python
material: Material

The material, or None for the default.

name property writable

Python
name: str

The visual's name.

__init__

Python
__init__() -> None

clear

Python
clear() -> None

Reset every field.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

Collision

origin property writable

Python
origin: Isometry3d

The geometry's frame, in the link frame.

geometry property writable

Python
geometry: Geometry

The collision geometry.

name property writable

Python
name: str

The collision's name.

__init__

Python
__init__() -> None

clear

Python
clear() -> None

Reset every field.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

inertial property writable

Python
inertial: Inertial

Mass properties, or None.

visual property writable

Python
visual: list[Visual]

The visual elements.

collision property writable

Python
collision: list[Collision]

The collision elements.

visible property writable

Python
visible: bool

Whether the link is visible (link.h:210)

collision_enabled property writable

Python
collision_enabled: bool

Whether the link takes part in collision checking (link.h:213)

getName

Python
getName() -> str

The link name.

getId

Python
getId() -> tesseract_robotics.common.LinkId

The link id.

addVisual

Python
addVisual(visual: Visual) -> None

Add a Visual to this link

addCollision

Python
addCollision(collision: Collision) -> None

Add a Collision to this link

clearVisual

Python
clearVisual() -> None

Clear all Visual elements from this link

clearCollision

Python
clearCollision() -> None

Clear all Collision elements from this link

clear

Python
clear() -> None

Reset every field.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str

ShortestPath

Python
links: list[LinkId]

The links on the path, root to tip.

joints property writable

Python
joints: list[JointId]

The joints on the path, root to tip.

active_joints property writable

Python
active_joints: list[JointId]

The active joints on the path, root to tip.

__init__

Python
__init__() -> None

__str__

Python
__str__() -> str

SceneGraph

__init__

Python
__init__(name: str = '') -> None

clone

Python
clone() -> SceneGraph

A deep copy.

clear

Python
clear() -> None

Remove every link, joint and allowed collision.

setName

Python
setName(name: str) -> None

Set the graph's name.

getName

Python
getName() -> str

The graph's name.

setRoot

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

Make the link name the root; False if unknown.

getRoot

Python
getRoot() -> tesseract_robotics.common.LinkId

The root link id.

Python
getLink(name: LinkId | str) -> Link

The link name (shared), or None.

Python
getLinks() -> list[Link]

Every link (shared).

Python
getLeafLinks() -> list[Link]

The links with no child joint.

Python
removeLink(name: LinkId | str, recursive: bool = False) -> bool

Remove the link name (and its subtree when recursive); False if unknown.

Python
moveLink(joint: Joint) -> bool

Re-attach a link by replacing its parent joint with joint; False on failure.

setLinkVisibility

Python
setLinkVisibility(name: LinkId | str, visibility: bool) -> None

Show or hide the link name.

getLinkVisibility

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

Whether the link name is visible.

setLinkCollisionEnabled

Python
setLinkCollisionEnabled(name: LinkId | str, enabled: bool) -> None

Enable or disable collision checking of the link name.

getLinkCollisionEnabled

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

Whether collision checking of the link name is enabled.

addJoint

Python
addJoint(joint: Joint) -> bool

Add joint between two existing links; False on failure.

getJoint

Python
getJoint(name: JointId | str) -> Joint

The joint name (shared), or None.

removeJoint

Python
removeJoint(name: JointId | str, recursive: bool = False) -> bool

Remove the joint name (and its child subtree when recursive); False if unknown.

moveJoint

Python
moveJoint(name: JointId | str, parent_link: LinkId | str) -> bool

Re-parent the joint name onto parent_link; False on failure.

getJoints

Python
getJoints() -> list[Joint]

Every joint (shared).

getActiveJoints

Python
getActiveJoints() -> list[Joint]

The active (non-fixed, non-mimic) joints.

changeJointOrigin

Python
changeJointOrigin(name: JointId | str, new_origin: Isometry3d) -> bool

Set the origin of the joint name; False if unknown.

changeJointLimits

Python
changeJointLimits(name: JointId | str, limits: JointLimits) -> bool

Replace the limits of the joint name; False if unknown.

changeJointPositionLimits

Python
changeJointPositionLimits(name: JointId | str, lower: float, upper: float) -> bool

Set the position limits of the joint name; False if unknown.

changeJointVelocityLimits

Python
changeJointVelocityLimits(name: JointId | str, limit: float) -> bool

Set the velocity limit of the joint name; False if unknown.

changeJointAccelerationLimits

Python
changeJointAccelerationLimits(name: JointId | str, limit: float) -> bool

Set the acceleration limit of the joint name; False if unknown.

changeJointJerkLimits

Python
changeJointJerkLimits(name: JointId | str, limit: float) -> bool

Set the jerk limit of the joint name; False if unknown.

getJointLimits

Python
getJointLimits(name: JointId | str) -> JointLimits

The limits of the joint name (shared), or None.

clearAllowedCollisions

Python
clearAllowedCollisions() -> None

Remove every allowed collision.

isCollisionAllowed

Python
isCollisionAllowed(pair: LinkIdPair | tuple[str, str]) -> bool

True if the link pair may collide.

getAllowedCollisionMatrix

Python
getAllowedCollisionMatrix() -> tesseract_robotics.common.AllowedCollisionMatrix

Get the allowed collision matrix

setAllowedCollisionMatrix

Python
setAllowedCollisionMatrix(acm: AllowedCollisionMatrix) -> None

Replace the allowed collision matrix. The graph keeps this object: later edits to acm are edits to the graph's matrix, as with getAllowedCollisionMatrix.

Python
getSourceLink(joint_name: JointId | str) -> Link

The parent link of the joint joint_name.

Python
getTargetLink(joint_name: JointId | str) -> Link

The child link of the joint joint_name.

getInboundJoints

Python
getInboundJoints(link_name: LinkId | str) -> list[Joint]

The joints whose child is the link link_name.

getOutboundJoints

Python
getOutboundJoints(link_name: LinkId | str) -> list[Joint]

The joints whose parent is the link link_name.

isAcyclic

Python
isAcyclic() -> bool

True if the graph has no cycle.

isTree

Python
isTree() -> bool

True if the graph is a tree.

isEmpty

Python
isEmpty() -> bool

True if the graph has no link.

getAdjacentLinkIds

Python
getAdjacentLinkIds(id: LinkId | str) -> list[tesseract_robotics.common.LinkId]

The links one joint below id.

getInvAdjacentLinkIds

Python
getInvAdjacentLinkIds(id: LinkId | str) -> list[tesseract_robotics.common.LinkId]

The links one joint above id.

getLinkChildrenIds

Python
getLinkChildrenIds(id: LinkId | str) -> list[tesseract_robotics.common.LinkId]

Every link below id.

getShortestPath

Python
getShortestPath(root: LinkId | str, tip: LinkId | str) -> ShortestPath

The links and joints from root to tip.

getAdjacencyMap

Python
getAdjacencyMap(link_ids: Sequence[LinkId | str]) -> dict[str, tesseract_robotics.common.LinkId]

Map each link that moves with one of link_ids to that link's id (graph.h:499). Each listed link maps itself and every link below it, stopping at another listed link. An unknown id raises KeyError.

saveDOT

Python
saveDOT(path: str) -> None

Write the graph as Graphviz DOT to path.

__eq__

Python
__eq__(other: object) -> bool

__ne__

Python
__ne__(other: object) -> bool

__repr__

Python
__repr__() -> str