Spatial

Spatial provides TF tree access plus local pose, transform, and geometry types.

Python

Spatial maths and TF wrapper over olo.spatial.v1.Spatial.

Client interfaces

class olo.spatial.Spatial

Bases: object

TF tree access via the Spatial gRPC service.

__init__(session)

Bind to a channel session.

Return type:

None

handle(namespace=None)

Return a namespace-scoped TF frame handle for a robot.

None auto-resolves the unambiguous appliance default. "" or "global" select the global namespace without discovery; bare frame names are not prefixed server-side. For the full TF tree across all robots, use tree() instead.

Return type:

RobotFrames

Parameters:

namespace (str | None)

lookup(target_frame, source_frame, *, at=None, timeout=5.0, robot_namespace=None)

Look up a transform between two TF frames.

target_frame is the frame poses are expressed in; source_frame is the frame being looked up. The returned Transform has frame_id=target_frame and child_frame_id=source_frame.

When robot_namespace is set, bare frame names are resolved server-side for that robot (see RobotFrames).

at selects a historical transform; when omitted the latest value is returned. timeout bounds how long to wait for the transform to become available.

Return type:

Transform

Parameters:

• target_frame (str)

• source_frame (str)

• at (datetime | None)

• timeout (float)

• robot_namespace (str | None)

publish_static(transform, *, timeout=5.0, robot_namespace=None)

Publish a static transform to the TF tree.

The transform is broadcast on /tf_static. frame_id and child_frame_id must be set. When stamp is omitted the server stamps the transform with its current time.

When robot_namespace is set, bare frame ids are resolved server-side for that robot (see RobotFrames).

Return type:

None

Parameters:

• transform (Transform)

• timeout (float)

• robot_namespace (str | None)

subscribe(target_frame, source_frame, *, timeout=None, robot_namespace=None)

Subscribe to transform updates between two frames.

target_frame and source_frame follow the same convention as lookup().

When robot_namespace is set, bare frame names are resolved server-side for that robot (see RobotFrames).

timeout is a deadline for the whole stream, not the wait for the next update: the subscription is terminated with a timeout error once it elapses. Leave it None (the default) for a long-lived subscription and close it via the context manager or close().

Return type:

TransformSubscription

Parameters:

• target_frame (str)

• source_frame (str)

• timeout (float | None)

• robot_namespace (str | None)

subscribe_tree(*, timeout=None)

Subscribe to TF tree updates across the full tree.

Each yield is a materialized FrameTree with current edge poses. Use TreeSubscription.changes() on the returned subscription for raw deltas.

timeout is a deadline for the whole stream, not the wait for the next update. Leave it None (the default) for a long-lived subscription and close it via the context manager or close().

Return type:

TreeSubscription

Parameters:

timeout (float | None)

tree(*, timeout=5.0)

Return the full TF tree across all robots and namespaces.

Return type:

FrameTree

Parameters:

timeout (float)

class olo.spatial.RobotFrames

Bases: object

Namespace-scoped TF frame handle for a robot.

__init__(spatial, namespace)

Bind to a spatial client and normalized robot namespace.

Parameters:

• spatial (Spatial)

• namespace (str)

Return type:

None

base_frame(*, timeout=5.0)

Return the detected base frame for this robot, or None when unknown.

Return type:

str | None

Parameters:

timeout (float)

lookup(target_frame, source_frame, *, at=None, timeout=5.0)

Look up a transform between two frames, resolving bare names for this robot.

Return type:

Transform

Parameters:

• target_frame (str)

• source_frame (str)

• at (datetime | None)

• timeout (float)

publish_static(transform, *, timeout=5.0)

Publish a static transform, resolving bare frame ids for this robot.

Return type:

None

Parameters:

• transform (Transform)

• timeout (float)

subscribe(target_frame, source_frame, *, timeout=None)

Subscribe to transform updates, resolving bare names for this robot.

Return type:

TransformSubscription

Parameters:

• target_frame (str)

• source_frame (str)

• timeout (float | None)

subscribe_tree(*, include_ancestors=False, timeout=None)

Subscribe to TF tree updates for this robot’s subtree.

Return type:

TreeSubscription

Parameters:

• include_ancestors (bool)

• timeout (float | None)

tree(*, include_ancestors=False, timeout=5.0)

Return the robot’s TF subtree as a multi-root tree.

Return type:

FrameTree

Parameters:

• include_ancestors (bool)

• timeout (float)

class olo.spatial.TransformSubscription

Bases: object

Context-managed sync iterator over a Spatial.SubscribeTransform stream.

__init__(stream)

Wrap a SubscribeTransform server stream.

close()

Cancel the stream and mark it closed.

Return type:

None

class olo.spatial.TreeSubscription

Bases: object

Context-managed sync iterator over a Spatial.SubscribeTree stream.

Default iteration yields a materialized FrameTree after each server message. Use changes() for the raw delta view. Only one consumer should iterate a subscription at a time.

__init__(stream, *, namespace='')

Wrap a SubscribeTree server stream.

Parameters:

namespace (str)

Return type:

None

changes()

Iterate raw tree deltas instead of materialized trees.

Return type:

Iterator[TreeDelta]

close()

Cancel the stream and mark it closed.

Return type:

None

class olo.spatial.TreeDelta

Bases: object

Raw tree change batch from a SubscribeTree stream.

__init__(added, updated, root_frames, base_frame, snapshot)

Parameters:

• added (tuple[Transform, ...])

• updated (tuple[Transform, ...])

• root_frames (tuple[str, ...])

• base_frame (str)

• snapshot (bool)

Return type:

None

Types

class olo.spatial.types.Point

Bases: object

Cartesian position in metres.

__init__(x=0.0, y=0.0, z=0.0)

Parameters:

• x (float)

• y (float)

• z (float)

Return type:

None

array()

Return [x, y, z] as a float64 numpy array.

Return type:

ndarray

classmethod from_array(values)

Create a point from an [x, y, z] array-like.

Return type:

Point

Parameters:

values (Sequence[float])

isclose(other, *, tol=1e-09)

Return whether two points are equal within an absolute tolerance.

Return type:

bool

Parameters:

• other (Self)

• tol (float)

class olo.spatial.types.Vector

Bases: object

Cartesian vector in metres.

__init__(x=0.0, y=0.0, z=0.0)

Parameters:

• x (float)

• y (float)

• z (float)

Return type:

None

array()

Return [x, y, z] as a float64 numpy array.

Return type:

ndarray

as_point()

Return a point with the same components.

Return type:

Point

cross(other)

Return the cross product.

Return type:

Vector

Parameters:

other (Vector)

dot(other)

Return the dot product.

Return type:

float

Parameters:

other (Vector)

classmethod from_array(values)

Create a vector from an [x, y, z] array-like.

Return type:

Vector

Parameters:

values (Sequence[float])

classmethod from_point(point)

Create a vector with the same components as a point.

Return type:

Vector

Parameters:

point (Point)

isclose(other, *, tol=1e-09)

Return whether two vectors are equal within an absolute tolerance.

Return type:

bool

Parameters:

• other (Self)

• tol (float)

magnitude()

Return the Euclidean norm.

Return type:

float

normalized()

Return a unit vector.

Return type:

Vector

scale(scalar)

Return this vector scaled by a scalar.

Return type:

Vector

Parameters:

scalar (float)

class olo.spatial.types.Quaternion

Bases: object

Orientation quaternion (xyzw).

__init__(x=0.0, y=0.0, z=0.0, w=1.0)

Parameters:

• x (float)

• y (float)

• z (float)

• w (float)

Return type:

None

array()

Return [x, y, z, w] as a float64 numpy array.

Return type:

ndarray

classmethod from_array(values)

Create a quaternion from an [x, y, z, w] array-like.

Return type:

Quaternion

Parameters:

values (Sequence[float])

classmethod from_axis_angle(axis, angle)

Create a quaternion from an axis-angle rotation.

Return type:

Quaternion

Parameters:

• axis (Sequence[float])

• angle (float)

classmethod from_matrix(matrix)

Create a quaternion from a 3x3 rotation matrix.

Return type:

Quaternion

Parameters:

matrix (ndarray)

classmethod from_rpy(roll, pitch, yaw)

Create a quaternion from roll-pitch-yaw angles (radians, xyz extrinsic).

Return type:

Quaternion

Parameters:

• roll (float)

• pitch (float)

• yaw (float)

classmethod identity()

Return the identity quaternion.

Return type:

Quaternion

isclose(other, *, tol=1e-09)

Return whether two quaternions represent the same rotation within a tolerance.

Return type:

bool

Parameters:

• other (Self)

• tol (float)

matrix()

Return the equivalent 3x3 rotation matrix.

Return type:

ndarray

normalized()

Return a unit quaternion.

Return type:

Quaternion

rotate(vector)

Rotate a vector by this quaternion.

Return type:

Vector

Parameters:

vector (Vector)

to_rpy()

Return roll, pitch, yaw (radians, xyz extrinsic).

Return type:

tuple[float, float, float]

class olo.spatial.types.Pose

Bases: object

A combined 3D position and orientation.

__init__(position=<factory>, orientation=<factory>)

Parameters:

• position (Point)

• orientation (Quaternion)

Return type:

None

apply(point)

Transform a point by this pose.

Return type:

Point

Parameters:

point (Point)

classmethod from_matrix(matrix)

Create a pose from a 4x4 homogeneous transform matrix.

Return type:

Pose

Parameters:

matrix (ndarray)

classmethod from_xy_yaw(x, y, yaw, *, z=0.0)

Create a planar pose from x, y, and yaw (radians).

Return type:

Pose

Parameters:

• x (float)

• y (float)

• yaw (float)

• z (float)

classmethod identity()

Return the identity pose.

Return type:

Pose

inverse()

Return the inverse pose.

Return type:

Pose

isclose(other, *, tol=1e-09)

Return whether two poses are geometrically equal within a tolerance.

Return type:

bool

Parameters:

• other (Self)

• tol (float)

matrix()

Return a 4x4 homogeneous transform matrix.

Return type:

ndarray

project_to_xy(*, z=None)

Return a pose flattened to the XY plane, preserving yaw only.

Return type:

Pose

Parameters:

z (float | None)

rotate(vector)

Rotate a vector by this pose without applying translation.

Return type:

Vector

Parameters:

vector (Vector)

class olo.spatial.types.Transform

Bases: object

Rigid transform, optionally stamped with TF frame metadata.

__init__(translation=<factory>, rotation=<factory>, frame_id='', child_frame_id='', stamp=None)

Parameters:

• translation (Vector)

• rotation (Quaternion)

• frame_id (str)

• child_frame_id (str)

• stamp (datetime | None)

Return type:

None

apply(point)

Transform a point by this transform.

Return type:

Point

Parameters:

point (Point)

as_pose()

Drop frame metadata and return the equivalent pose.

Return type:

Pose

classmethod from_matrix(matrix, *, frame_id='', child_frame_id='', stamp=None)

Create a transform from a 4x4 homogeneous transform matrix.

Return type:

Transform

Parameters:

• matrix (ndarray)

• frame_id (str)

• child_frame_id (str)

• stamp (datetime | None)

classmethod identity()

Return the identity transform.

Return type:

Transform

inverse()

Return the inverse transform (frame ids are swapped).

Return type:

Transform

isclose(other, *, tol=1e-09)

Return whether two transforms have equal geometry within a tolerance.

Return type:

bool

Parameters:

• other (Self)

• tol (float)

matrix()

Return a 4x4 homogeneous transform matrix.

Return type:

ndarray

rotate(vector)

Rotate a vector by this transform without applying translation.

Return type:

Vector

Parameters:

vector (Vector)

class olo.spatial.types.Twist

Bases: object

Linear and angular velocity vectors.

__init__(linear=<factory>, angular=<factory>)

Parameters:

• linear (Vector)

• angular (Vector)

Return type:

None

isclose(other, *, tol=1e-09)

Return whether two twists are equal within an absolute tolerance.

Return type:

bool

Parameters:

• other (Self)

• tol (float)

class olo.spatial.types.FrameInfo

Bases: object

A frame in the TF tree.

__init__(name, parent='', transform=None)

Parameters:

• name (str)

• parent (str)

• transform (Transform | None)

Return type:

None

class olo.spatial.types.FrameTreeNode

Bases: object

A node in a robot-scoped TF subtree.

__init__(frame_id, relative_name, transform=None, children=())

Parameters:

• frame_id (str)

• relative_name (str)

• transform (Transform | None)

• children (tuple[FrameTreeNode, ...])

Return type:

None

class olo.spatial.types.FrameTree

Bases: tuple[FrameTreeNode, …]

A TF tree; may have multiple roots when subtrees are disconnected.

flatten()

Flatten the tree into FrameInfo entries (child -> parent).

Return type:

list[FrameInfo]

TypeScript

Import from olo/spatial:

The TypeScript surface mirrors the Python module: method names are camelCase, keyword arguments become an options object with millisecond timeouts, and Python’s * operator maps to multiply().

Client interfaces

• Spatial — TF tree access: lookup(), tree(), handle(), subscribe(), subscribeTree(), and publishStatic().

• RobotFrames — namespace-scoped TF frame handle (created via client.spatial.handle()), plus baseFrame().

• TransformSubscription — async iterable transform stream.

• TreeSubscription — async iterable tree stream; yields materialized FrameTree snapshots, or raw deltas via changes().

• TreeDelta — raw tree change batch (added / updated).

Types

• Point — Cartesian position in metres.

• Vector — Cartesian vector in metres with dot/cross, normalization, and magnitude clamping.

• Quaternion — orientation (xyzw) with RPY, axis-angle, matrix constructors, and vector rotation.

• Pose — position plus orientation; matrix(), inverse(), apply(), rotate(), and multiply().

• Transform — rigid transform with optional TF frame metadata and stamp; composition validates frame chaining.

• Twist — linear and angular velocity vectors.

• FrameInfo — flattened frame entry.

• FrameTreeNode — node in a TF subtree.

• FrameTree — multi-root tree with flatten() and a tree-shaped toString().