API Reference

Class summary

Spatial geometry classes for 3D shapes and scene graph management.

SceneNode([pose, scene_parent, scene_children])	Base class for a node in a scene graph.
SceneGroup([initlist])	An ordered, list-like collection of SceneNode objects (nodes can be nested groups, shapes, or any other SceneNode subclass) that itself behaves like a single SceneNode.
Shape([pose, color, stype, base])	Abstract base class for a renderable 3D shape in a scene graph.
CollisionShape([collision])	Base class for a Shape that also has associated collision geometry, so instances can be used for collision checking (via coal) as well as being rendered in the scene.
CollisionShapeGroup([initlist])	An ordered, list-like collection of CollisionShape (or nested CollisionShapeGroup) objects that itself behaves like a single collision-checkable shape.

The class hierarchy for all Spatial Geometry classes is shown below:

Collision shapes

These are the basic 3D geometric shapes that can be rendered into a scene, and can also be used for collision detection.

Cuboid(scale, **kwargs)	A rectangular prism whose centre is at the local origin.
Sphere(radius, **kwargs)	A sphere whose centre is at the local origin.
Ellipsoid(radii, **kwargs)	An ellipsoid whose centre is at the local origin.
Cylinder(radius, length, **kwargs)	A cylinder whose centre is at the local origin and its axis along the z-axis.
Mesh([filename, scale, color, y_up])	A triangular mesh object.
Box(scale, **kwargs)	Deprecated alias for Cuboid -- a rectangular prism whose centre is at the local origin.

These shapes all inherit from:

• the CollisionShape base class which means they can be used for collision detection, and

• the SceneNode base class which means they can be nodes in a scene graph to allow visualization and animation of complex scenes.

Collision shapes also support the collision operator & which returns True if the two shapes are colliding, and False otherwise. For example:

>>> from spatialgeometry import Cuboid, Sphere
>>> from spatialmath import SE3
>>> 
>>> c = Cuboid(scale=[1, 2, 3])
>>> s1 = Sphere(1, pose=SE3(4, 0, 0))
>>> s2 = Sphere(1, pose=SE3(0, 0, 0))
>>> 
>>> c & s1
False
>>> c & s2
True

class Cuboid(scale: list | ndarray | tuple | set, **kwargs)

Bases: CollisionShape

A rectangular prism whose centre is at the local origin.

Parameters:

• scale – [length, width, height] in metres.

• collision – Whether this shape participates in collision checking.

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

closest_point(shape: CollisionShape, inf_dist: float = 1.0) → tuple[float | None, ndarray | None, ndarray | None]

Return the minimum euclidean distance between self and shape.

Parameters:

• shape – The shape (or CollisionShapeGroup) to compare distance to

• inf_dist – Only return a result when distance < inf_dist

Returns:

(d, p1, p2) — distance and closest points in world frame, or (None, None, None) when the shapes are farther than inf_dist. d is negative when the shapes are penetrating.

Inherited from CollisionShape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

iscollided(shape: CollisionShape) → bool

Return True if self and shape have collided (distance ≤ 0).

Parameters:

shape – The shape (or CollisionShapeGroup) to check against

Inherited from CollisionShape.

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property scale: ndarray

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Sphere(radius: float, **kwargs)

Bases: CollisionShape

A sphere whose centre is at the local origin.

Parameters:

• radius – Radius in metres.

• collision – Whether this shape participates in collision checking.

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

closest_point(shape: CollisionShape, inf_dist: float = 1.0) → tuple[float | None, ndarray | None, ndarray | None]

Return the minimum euclidean distance between self and shape.

Parameters:

• shape – The shape (or CollisionShapeGroup) to compare distance to

• inf_dist – Only return a result when distance < inf_dist

Returns:

(d, p1, p2) — distance and closest points in world frame, or (None, None, None) when the shapes are farther than inf_dist. d is negative when the shapes are penetrating.

Inherited from CollisionShape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

iscollided(shape: CollisionShape) → bool

Return True if self and shape have collided (distance ≤ 0).

Parameters:

shape – The shape (or CollisionShapeGroup) to check against

Inherited from CollisionShape.

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property radius: float

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Cylinder(radius: float, length: float, **kwargs)

Bases: CollisionShape

A cylinder whose centre is at the local origin and its axis along the z-axis.

Parameters:

• radius – Radius in metres.

• length – Total length in metres.

• collision – Whether this shape participates in collision checking.

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

closest_point(shape: CollisionShape, inf_dist: float = 1.0) → tuple[float | None, ndarray | None, ndarray | None]

Return the minimum euclidean distance between self and shape.

Parameters:

• shape – The shape (or CollisionShapeGroup) to compare distance to

• inf_dist – Only return a result when distance < inf_dist

Returns:

(d, p1, p2) — distance and closest points in world frame, or (None, None, None) when the shapes are farther than inf_dist. d is negative when the shapes are penetrating.

Inherited from CollisionShape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

iscollided(shape: CollisionShape) → bool

Return True if self and shape have collided (distance ≤ 0).

Parameters:

shape – The shape (or CollisionShapeGroup) to check against

Inherited from CollisionShape.

property length: float

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property radius: float

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Ellipsoid(radii: list | ndarray | tuple | set, **kwargs)

Bases: CollisionShape

An ellipsoid whose centre is at the local origin.

Parameters:

• radii – Semi-axis lengths along X, Y, Z, in metres. A sphere is the special case radii=[r, r, r] – use Sphere for that, it’s cheaper both to construct and to collision-check.

• collision – Whether this shape participates in collision checking.

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

closest_point(shape: CollisionShape, inf_dist: float = 1.0) → tuple[float | None, ndarray | None, ndarray | None]

Return the minimum euclidean distance between self and shape.

Parameters:

• shape – The shape (or CollisionShapeGroup) to compare distance to

• inf_dist – Only return a result when distance < inf_dist

Returns:

(d, p1, p2) — distance and closest points in world frame, or (None, None, None) when the shapes are farther than inf_dist. d is negative when the shapes are penetrating.

Inherited from CollisionShape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

iscollided(shape: CollisionShape) → bool

Return True if self and shape have collided (distance ≤ 0).

Parameters:

shape – The shape (or CollisionShapeGroup) to check against

Inherited from CollisionShape.

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property radii: ndarray

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Box(scale: list | ndarray | tuple | set, **kwargs)

Bases: Cuboid

Deprecated alias for Cuboid – a rectangular prism whose centre is at the local origin.

Parameters:

• scale – [length, width, height] in metres.

• collision – Whether this shape participates in collision checking.

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

closest_point(shape: CollisionShape, inf_dist: float = 1.0) → tuple[float | None, ndarray | None, ndarray | None]

Return the minimum euclidean distance between self and shape.

Parameters:

• shape – The shape (or CollisionShapeGroup) to compare distance to

• inf_dist – Only return a result when distance < inf_dist

Returns:

(d, p1, p2) — distance and closest points in world frame, or (None, None, None) when the shapes are farther than inf_dist. d is negative when the shapes are penetrating.

Inherited from CollisionShape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

iscollided(shape: CollisionShape) → bool

Return True if self and shape have collided (distance ≤ 0).

Parameters:

shape – The shape (or CollisionShapeGroup) to check against

Inherited from CollisionShape.

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property scale: ndarray

Inherited from Cuboid.

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

Inherited from Cuboid.

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Mesh(filename: str | None = None, scale: list | ndarray | tuple | set | float = [1, 1, 1], color: list | ndarray | tuple | set | None = None, y_up: bool = False, **kwargs)

Bases: CollisionShape

A triangular mesh object.

Parameters:

• filename – Absolute path to the mesh file. Checked for existence at construction (raises FileNotFoundError if missing) – this only confirms the path exists, not that it’s a well-formed or readable mesh file, which is still discovered lazily, the first time the file is actually loaded (see _init_coal() and _local_corners()).

• scale – Scale factor(s) along XYZ axes (default [1, 1, 1]). A single number applies the same scale to all three axes.

• y_up – Set True if the mesh file was authored with +Y as the “up” axis – a common convention in general 3D/graphics tooling – rather than this ecosystem’s +Z-up convention.

• collision – Whether this shape participates in collision checking.

Note

For a Mesh, color is a flat color override applied to every face/vertex. If not given, the renderer uses whatever per-vertex/per-face colors are baked into the mesh file itself, when present.

Unlike the primitive shapes, a mesh’s local origin is not guaranteed to be at its geometric centre – it’s whatever origin the file was authored/exported with, which may be off-centre or even outside the mesh entirely.

Parameters:

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

closest_point(shape: CollisionShape, inf_dist: float = 1.0) → tuple[float | None, ndarray | None, ndarray | None]

Return the minimum euclidean distance between self and shape.

Parameters:

• shape – The shape (or CollisionShapeGroup) to compare distance to

• inf_dist – Only return a result when distance < inf_dist

Returns:

(d, p1, p2) — distance and closest points in world frame, or (None, None, None) when the shapes are farther than inf_dist. d is negative when the shapes are penetrating.

Inherited from CollisionShape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

property filename: str | None

Absolute path to this mesh’s source file, as given to the constructor. There’s no use case for repointing an existing Mesh at a different file – construct a new one instead.

This is a read-only property.

Return type:

str

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

iscollided(shape: CollisionShape) → bool

Return True if self and shape have collided (distance ≤ 0).

Parameters:

shape – The shape (or CollisionShapeGroup) to check against

Inherited from CollisionShape.

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property scale: ndarray

Scale factors along the local X, Y, Z axes. A scalar sets all three axes equally; None resets to [1, 1, 1].

This is a read/write property.

Return type:

ndarray(3)

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

property y_up: bool

True if this mesh file was authored with +Y as “up” and needs the +Y -> +Z correction applied.

This describes a fact about the mesh file itself, fixed at construction – it isn’t live scene state.

This is a read-only property.

Return type:

bool

Shapes

These are the basic 3D geometric shapes that can be rendered into a scene, but they cannot be used for collision detection.

Axes(length[, arrows, radius, linewidth])	A set of 3D axes whose centre is at the local origin.
Arrow(length[, radius, linewidth, ...])	An arrow whose centre is at the local origin, and points in the positive z-direction.
Polyline(points[, radius, linewidth])	A polyline through a sequence of waypoints defined with respect to the local frame of the shape.
Path(points[, radius, linewidth])	Deprecated alias for Polyline -- a polyline through a sequence of waypoints defined with respect to the local frame of the shape.

They all inherit directly from the Shape base class.

class Axes(length: float, arrows: bool = False, radius: float = 0.0, linewidth: float = 1.0, **kwargs)

Bases: Shape

A set of 3D axes whose centre is at the local origin.

Parameters

Parameters:

• length (float) – The length of each axis.

• arrows (bool) – If True, render each axis as a colored Arrow (red/ green/blue for X/Y/Z) instead of a plain line.

• radius (float) – Shaft radius of each arrow. Only used when arrows=True; passed straight through to each constituent Arrow (see Arrow’s own radius/linewidth docs – they are mutually exclusive, radius > 0 takes precedence).

• linewidth (float) – Shaft width in pixels, only used when arrows=True and radius == 0. Passed straight through to each constituent Arrow.

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

property arrows: bool

If True, each axis is rendered as a colored Arrow (red/green/blue for X/Y/Z) instead of a plain line, as set by arrows in the constructor.

This is a read/write property.

Return type:

bool

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

property length: float

The length of each axis, as set by length in the constructor.

This is a read/write property.

Return type:

float

property linewidth: float

Shaft width in pixels, only used when arrows is True and radius is 0. Passed straight through to each constituent Arrow. Set by linewidth in the constructor.

This is a read/write property.

Return type:

float

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property radius: float

Shaft radius of each arrow. Only used when arrows is True; passed straight through to each constituent Arrow (radius and linewidth are mutually exclusive – radius > 0 takes precedence). Set by radius in the constructor.

This is a read/write property.

Return type:

float

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Arrow(length: float, radius: float = 0.0, linewidth: float = 1.0, head_length: float = 0.2, head_radius: float = 0.2, **kwargs)

Bases: Shape

An arrow whose centre is at the local origin, and points in the positive z-direction.

Parameters:

• length – The total length of the arrow.

• radius – The radius of the arrow shaft. If radius is 0, the shaft is rendered as a line instead of a cylinder – see linewidth. radius and linewidth are mutually exclusive: radius > 0 always takes precedence, and linewidth is ignored in that case (a real cylinder mesh has no notion of a pixel width).

• linewidth – Width of the shaft in pixels. Only used when radius == 0.

• head_length – The length of the cone (head of the arrow). This is represented as a fraction of the length. Must be a value between 0 and 1.

• head_radius – The width of the cone (head of the arrow). This is represented as a fraction of the head_length.

The arrow has a cylindrical shaft and a conical head.

Note

This shape cannot be used for collision detection, and is only for visualisation purposes.

Parameters:

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

classmethod FromTo(start: list | ndarray | tuple | set, end: list | ndarray | tuple | set, **kwargs) → Arrow

Construct an Arrow spanning from start to end.

Parameters:

• start – 3-vector, world-frame point the arrow points from

• end – 3-vector, world-frame point the arrow points to

• kwargs – passed through to the constructor (radius, linewidth, head_length, head_radius, color, …)

length and pose are computed from start/end – don’t pass them directly.

Raises:

ValueError – if start and end are the same point (the direction, and therefore the pose, would be undefined)

Return type:

Arrow

property head_length: float

The length of the cone forming the arrow head, as a fraction of length in the range [0, 1]. Set by head_length in the constructor.

This is a read/write property.

Return type:

float

property head_radius: float

The width of the cone forming the arrow head, as a fraction of head_length. Set by head_radius in the constructor.

This is a read/write property.

Return type:

float

property length: float

The total length of the arrow, as set by length in the constructor.

This is a read/write property.

Return type:

float

property linewidth: float

Width of the shaft in pixels. Only used when radius is 0. Set by linewidth in the constructor.

This is a read/write property.

Return type:

float

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property radius: float

The radius of the arrow shaft. If 0, the shaft is rendered as a line instead of a cylinder – see linewidth. radius and linewidth are mutually exclusive: radius > 0 always takes precedence. Set by radius in the constructor.

This is a read/write property.

Return type:

float

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Polyline(points: list | ndarray | tuple | set, radius: float = 0.0, linewidth: float = 1.0, **kwargs)

Bases: Shape

A polyline through a sequence of waypoints defined with respect to the local frame of the shape.

Parameters:

• points (ArrayLike) – waypoints defining the polyline

• radius – tube radius; if 0, rendered as a line instead of a tube – see linewidth. radius and linewidth are mutually exclusive: radius > 0 always takes precedence, and linewidth is ignored in that case (a real tube mesh has no notion of a pixel width).

• linewidth – Width of the line in pixels. Only used when radius == 0.

This shape is used for drawing paths and trajectories in the scene. The line comprises straight segments joining consecutive points, not a smoothed curve.

Note

This shape cannot be used for collision detection, and is only for visualisation purposes.

Parameters:

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

property linewidth: float

Width of the line in pixels. Only used when radius is 0. Set by linewidth in the constructor.

This is a read/write property.

Return type:

float

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property points: ndarray

Return type:

ndarray(3,n)

property radius: float

Tube radius; if 0, rendered as a line instead of a tube – see linewidth. radius and linewidth are mutually exclusive: radius > 0 always takes precedence. Set by radius in the constructor.

This is a read/write property.

Return type:

float

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

Returns the shape’s information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

class Path(points: list | ndarray | tuple | set, radius: float = 0.0, linewidth: float = 1.0, **kwargs)

Bases: Polyline

Deprecated alias for Polyline – a polyline through a sequence of waypoints defined with respect to the local frame of the shape.

Parameters:

• points (ArrayLike) – waypoints defining the polyline

• radius – tube radius; if 0, rendered as a line instead of a tube – see linewidth.

• linewidth – Width of the line in pixels. Only used when radius == 0.

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

property linewidth: float

Width of the line in pixels. Only used when radius is 0. Set by linewidth in the constructor.

This is a read/write property.

Return type:

float

Inherited from Polyline.

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

property points: ndarray

Return type:

ndarray(3,n)

Inherited from Polyline.

property radius: float

Tube radius; if 0, rendered as a line instead of a tube – see linewidth. radius and linewidth are mutually exclusive: radius > 0 always takes precedence. Set by radius in the constructor.

This is a read/write property.

Return type:

float

Inherited from Polyline.

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

Returns the shape’s information in dictionary form

Returns:

All information about the shape

Return type:

dict

Inherited from Polyline.

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.

Scene Graphs

class SceneNode(pose: ndarray | SE3 = array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]), scene_parent: SceneNode | None = None, scene_children: list[SceneNode] | None = None)

Bases: object

Base class for a node in a scene graph.

Subclassed for particular shapes and provides the shape’s pose, a parent/children relationship to other nodes, and the ability to compute its pose in the world frame from the scene graph.

Parameters:

• pose – Local reference frame of this node relative to its parent in the scene graph (or the world frame if it has no parent), defaults to the identity transform.

• scene_parent – Parent node of this node in the scene graph.

• scene_children – Child nodes of this node in the scene graph.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

class SceneGroup(initlist: Iterable[SceneNode] | None = None, **kwargs)

Bases: SceneNode, UserList

An ordered, list-like collection of SceneNode objects (nodes can be nested groups, shapes, or any other SceneNode subclass) that itself behaves like a single SceneNode.

Parameters:

initlist – Initial elements to populate the group with.

A SceneGroup is itself a SceneNode so its elements can be collectively, parented or nested like any other node in the scene graph. This class inherits from collections.UserList so it behaves like a Python list, but it is not a subclass of list so it can be subclassed itself.

Every element’s scene_parent is kept pointing at the group – adding an element (via the constructor, append, extend, insert, or item assignment) sets it, and removing one (remove, pop, clear, del) clears it back to None. This is what makes moving the group move its elements with it.

The reverse holds too, and isn’t just a side effect – append() is nothing more than item.scene_parent = self, so setting any node’s scene_parent to a SceneGroup directly (with no append call at all) equally makes it a member of that group’s list. List membership and scene-graph parentage are the same relationship, not two things kept in sync – there’s no way for them to disagree.

>>> from spatialgeometry import SceneGroup, Cuboid, Sphere
>>> from spatialmath import SE3
>>> group = SceneGroup()
>>> print(len(group))
0
>>> group.append(Cuboid([1,2,3]))
>>> group.append(Sphere(1, pose=SE3.Trans(1,0,0)))
>>> print(len(group))
2

Parameters:

• pose – Local reference frame of this node relative to its parent in the scene graph (or the world frame if it has no parent), defaults to the identity transform.

• scene_parent – Parent node of this node in the scene graph.

• scene_children – Child nodes of this node in the scene graph.

append(item: SceneNode) → None

Add item to the end of the group and set its scene_parent to this group.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

clear() → None

Remove every element from the group, clearing each one’s scene_parent.

copy()

Inherited from UserList.

count(value) → integer -- return number of occurrences of value

Inherited from UserList.

property data: list[SceneNode]

extend(other: Iterable[SceneNode]) → None

Add every element of other to the end of the group, setting each one’s scene_parent to this group.

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

Inherited from UserList.

insert(i: int, item: SceneNode) → None

Insert item at position i and set its scene_parent to this group.

pop(i: int = -1) → SceneNode

Remove and return the element at position i (default: the last one), clearing its scene_parent.

remove(item: SceneNode) → None

Remove item from the group and clear its scene_parent.

reverse()

S.reverse() – reverse IN PLACE

Inherited from UserList.

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

sort(*args, **kwds)

Inherited from UserList.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

class CollisionShapeGroup(initlist: Iterable[CollisionShape] | None = None, **kwargs)

Bases: CollisionShape, UserList

An ordered, list-like collection of CollisionShape (or nested CollisionShapeGroup) objects that itself behaves like a single collision-checkable shape.

Parameters:

• initlist – Initial elements to populate the group with.

• collision – Whether this group participates in collision checking, defaults to True.

Unlike SceneGroup, which admits any SceneNode, a CollisionShapeGroup only accepts CollisionShape or CollisionShapeGroup instances – adding anything else (a plain Shape such as Axes, for instance) raises TypeError.

iscollided()/closest_point() work in every combination of shape-vs-shape, shape-vs-group, group-vs-shape, and group-vs-group, including arbitrarily nested groups – a group checks each of its own elements in turn (delegating to that element’s own iscollided()/closest_point(), which handles the other side being a group itself if needed) and aggregates: any element collided means the group collided; the closest element’s own (d, p1, p2) is the group’s.

A CollisionShapeGroup has no single Coal collision geometry of its own – it is never itself passed to Coal, only iterated – so to_dict() (there is no single dict that could describe a collection) and _init_coal() (there is no single geometry to build) both raise if called directly. Nothing in normal use calls either, since iscollided()/closest_point() never touch self.co.

Every element’s scene_parent is kept pointing at the group, same as SceneGroup – adding an element (via the constructor, append, extend, insert, or item assignment) sets it, and removing one (remove, pop, clear, del) clears it back to None.

>>> from spatialgeometry import CollisionShapeGroup, Cuboid, Sphere
>>> from spatialmath import SE3
>>> group = CollisionShapeGroup()
>>> group.append(Cuboid([1, 1, 1]))
>>> group.append(Sphere(1, pose=SE3.Trans(3, 0, 0)))
>>> len(group)
2

Parameters:

• pose – Local reference frame of the shape, defaults to the identity transform.

• color – Color as (r, g, b) or (r, g, b, a) in [0-1] (or [0-255], auto-normalised), or a matplotlib color name. Defaults to a mid-grey (0.3, 0.3, 0.3, 1.0).

• stype – Shape type identifier used by the renderer/wire protocol (e.g. "cuboid", "mesh") – set by each concrete subclass, not normally passed directly by a caller.

• base – Deprecated alias for pose.

append(item: CollisionShape) → None

Add item to the end of the group and set its scene_parent to this group.

attach(object: SceneNode) → None

Attach a child node

Parameters:

object – the node to attach as a child of this node

Seealso:

attach_to() scene_children()

Inherited from SceneNode.

attach_to(object: SceneNode) → None

Attach this node to a parent node

Parameters:

object – the node to attach this node to, this node will become a child of the parent

Seealso:

attach() scene_parent()

Inherited from SceneNode.

bounds(world: bool = False) → ndarray

Min/max extent of this shape’s axis-aligned bounding box along each axis.

Parameters:

world – See corners().

Return type:

ndarray(3,2)

Inherited from Shape.

clear() → None

Remove every element from the group, clearing each one’s scene_parent.

closest_point(shape: CollisionShape, inf_dist: float = 1.0) → tuple[float | None, ndarray | None, ndarray | None]

Return the minimum euclidean distance between this group and shape – the closest (d, p1, p2) among this group’s own elements.

Parameters:

• shape – The shape (or CollisionShapeGroup) to compare distance to

• inf_dist – Only return a result when distance < inf_dist

Returns:

(d, p1, p2) — distance and closest points in world frame, or (None, None, None) when every element is farther than inf_dist.

property collision: bool

True if this shape is used for collision checking rather than (or as well as) visual rendering, as set by the collision argument of a CollisionShape subclass’ constructor.

This is a read-only property.

Return type:

bool

Inherited from Shape.

property color: tuple[float, float, float, float]

shape.color returns a four length tuple representing (red, green, blue, opacity) where opacity represents transparency. Values returned are in the range [0-1]. See opacity for a convenient way to get/set just this last channel.

Inherited from Shape.

copy() → Shape

Copy of Shape object

Returns:

Shallow copy of Shape object

Return type:

Shape

Inherited from Shape.

corners(world: bool = False) → ndarray

The 8 corners of this shape’s axis-aligned bounding box.

Parameters:

world – If True, apply this shape’s current pose and return the axis-aligned envelope of the posed shape (its corners will move as the shape is re-posed, and a rotated shape’s envelope is generally larger than its own local box – this is not the shape’s true oriented/rotated corners). If False (default), return the corners in the shape’s own local frame, independent of pose – constant unless the shape’s own parameters (radius, scale, …) change.

Return type:

ndarray(3,8)

Inherited from Shape.

count(value) → integer -- return number of occurrences of value

Inherited from UserList.

property data: list[CollisionShape]

extend(other: Iterable[CollisionShape]) → None

Add every element of other to the end of the group, setting each one’s scene_parent to this group.

extents(world: bool = False) → ndarray

Dimensions (width, depth, height) of this shape’s axis-aligned bounding box.

Parameters:

world – See corners().

Return type:

ndarray(3,)

Inherited from Shape.

fk_dict() → dict[str, Any]

fk_dict() outputs shapes pose in dictionary form

Returns:

The shape pose in translation and quternion form

Return type:

dict

Inherited from Shape.

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

Inherited from UserList.

insert(i: int, item: CollisionShape) → None

Insert item at position i and set its scene_parent to this group.

iscollided(shape: CollisionShape) → bool

Return True if any element of this group has collided with shape.

Parameters:

shape – The shape (or CollisionShapeGroup) to check against

property opacity: float

The last channel of color, in [0-1] – 1.0 is fully opaque, 0.0 fully transparent. A convenience for touching just this channel without needing to know or re-specify the current (r, g, b).

Note

“Opacity” here is the same quantity commonly called “alpha” in computer graphics (as in RGBA) – this package uses “opacity” consistently as the public name for it.

This is a read/write property.

Return type:

float

Inherited from Shape.

pop(i: int = -1) → CollisionShape

Remove and return the element at position i (default: the last one), clearing its scene_parent.

remove(item: CollisionShape) → None

Remove item from the group and clear its scene_parent.

reverse()

S.reverse() – reverse IN PLACE

Inherited from UserList.

property scene_children: list[SceneNode]

Return the child nodes of this object in the scene graph.

Setting a new list of children updates each child’s scene_parent to this object, but does not remove this object from any previous parent’s scene_children.

This is a read/write property.

Return type:

list(SceneNode)

Seealso:

scene_parent() attach() attach_to()

Inherited from SceneNode.

property scene_parent: SceneNode | None

Return the parent node of this object in the scene graph.

Setting a new parent adds this object to the new parent’s scene_children.

This is a read/write property.

Return type:

SceneNode | None

Seealso:

scene_children() attach() attach_to()

Inherited from SceneNode.

set_alpha(alpha: float | int) → None

Deprecated – use the opacity property instead.

Inherited from Shape.

sort(*args, **kwds)

Inherited from UserList.

property T: ndarray

Pose of the shape relative to its parent frame in the scene graph (or the world frame if it has no parent), as a 4x4 homogeneous transformation matrix. Set via the pose argument of the constructor.

This is a read/write property. The getter always returns a plain ndarray; the setter also accepts an SE3.

Warning

Because the getter returns an ndarray, in-place operators like shape.T *= delta do an elementwise multiply, not a pose composition, even when delta is an SE3 – use shape.T = shape.T * delta (or shape.T @= delta.A) instead.

Return type:

ndarray(4,4)

Inherited from SceneNode.

to_dict() → dict[str, Any]

to_dict() returns the shapes information in dictionary form

Returns:

All information about the shape

Return type:

dict

tree() → str

Render the whole tree this node lives in as indented text – walks up to the root first (the same root-finding as update()), then renders down from there, with this node marked with a trailing <== so its position in the tree is visible.

Return type:

str

Inherited from SceneNode.

tree_children() → str

Render this node’s own subtree as indented text (one repr() per line), not walking through parents – the same “not through parents” scope as _propagate_scene_children().

Nodes have no .name in this package, so each line is that node’s own repr() (type, constructor params, color, pose) – usually enough to tell siblings apart, since it’s rare for two distinct nodes to share an identical pose as well as everything else.

Return type:

str

Inherited from SceneNode.

update() → None

Recompute the world transform of every node in the scene graph this node belongs to, starting from the root and working down.

Call this after changing any node’s T/pose (or its scene_parent) – nothing propagates automatically. It doesn’t matter which node in the graph you call it on: this always walks up to the root first, then pushes fresh world transforms down through the whole tree, not just this node’s own subtree.

Inherited from SceneNode.

property v: ndarray

Spatial velocity of the shape as a 6-vector: linear velocity v[:3] followed by angular velocity v[3:6]. Used to integrate the shape’s pose between frames, e.g. by Swift.step() when no per-step callback is supplied.

This is a read/write property.

Return type:

ndarray(6)

Inherited from Shape.