s6.rendering.visuals

3D/2D scene visuals and helpers built on VisPy.

This module provides small, composable scene graph nodes for common visualizations used in Sense Core:

  • Image planes, 3D polylines, and point markers

  • Camera frustums and simple camera widgets

  • Loading and orienting triangle meshes from external files

  • A lightweight binding system (VisualTree) to connect visuals to values in an application context

Most visuals subclass vispy.scene.Node and implement set_data(...) to update their state from conveniently-typed inputs (s6.schema.Vector3D, NumPy arrays, dictionaries). Camera-related utilities rely on intrinsic/extrinsic parameters compatible with s6.vision.camera.

class s6.rendering.visuals.VisualTreeElement(*args: Any, **kwargs: Any)

Bases: Node, ABC

Base scene node with a simple data-binding contract.

Subclasses implement set_data() to update their visual state from a bound value. Instances can be registered with VisualTree.

abstractmethod set_data(value)

Update the visual based on a bound value.

s6.rendering.visuals.query(value, parts)

Traverse nested mappings/lists using a list of keys.

Parameters:

  • value (Any) – Root object (typically a nested dict/list context).

  • parts (list of str) – Sequence of keys or indices forming a path, e.g., ["camera", "0", "K"].

Returns:

The value at the path, or None if any segment is missing.

Return type:

Any | None

class s6.rendering.visuals.VisualTree

Bases: object

Bind context keys to visuals with optional transforms.

The tree maps one or more dotted keys to a list of (visual, func) pairs. During update(), the first existing key supplies a value, which is optionally transformed by func and passed to VisualTreeElement.set_data().

bind(visual: VisualTreeElement, keys: str | List[str], bind_lambda: Callable[[Any], Any] | None = None)

Bind a visual to one or more context keys.

Parameters:

  • visual (VisualTreeElement) – Target visual to receive updates.

  • keys (str or list of str) – Dotted key(s) to look up in the context (first found wins).

  • bind_lambda (callable, optional) – Transform value -> value before passing to set_data.

update(context)

Update all bound visuals from a context mapping.

Chooses the first available key for each binding, optionally applies its transform, then calls visual.set_data(value).

class s6.rendering.visuals.ProjectionHelper

Bases: object

Convenience functions for camera distortion/undistortion.

static distort_points(norm_points, camera_matrix, distortion_coeffs)

Apply lens distortion to normalized image points.

Parameters:

  • norm_points (ndarray, shape (N, 2)) – Normalized pixel coordinates.

  • camera_matrix (ndarray, shape (3, 3)) – Intrinsic matrix K.

  • distortion_coeffs (ndarray) – Distortion coefficients in OpenCV format.

Returns:

Distorted pixel coordinates.

Return type:

ndarray, shape (N, 2)

static undistort_points(distorted_points, camera_matrix, distortion_coeffs)

Remove lens distortion from pixel coordinates.

Parameters:

  • distorted_points (ndarray, shape (N, 2)) – Distorted pixel coordinates.

  • camera_matrix (ndarray, shape (3, 3)) – Intrinsic matrix K.

  • distortion_coeffs (ndarray) – Distortion coefficients in OpenCV format.

Returns:

Undistorted pixel coordinates.

Return type:

ndarray, shape (N, 2)

class s6.rendering.visuals.LineData(*, points: List[Vector3D])

Bases: BaseModel

Polyline container of 3D points.

points: List[Vector3D]
class s6.rendering.visuals.FrustumData(*, extrinsic: List[List[float]], intrinsic: List[List[float]], distortion: List[float], resolution: Tuple[int, int])

Bases: BaseModel

Camera parameters for rendering a frustum.

extrinsic

4x4 world-to-camera matrix.

Type:

list[list[float]]

intrinsic

3x3 intrinsic matrix K.

Type:

list[list[float]]

distortion

OpenCV distortion coefficients.

Type:

list[float]

resolution

Image resolution (width, height) in pixels.

Type:

(int, int)

extrinsic: List[List[float]]
intrinsic: List[List[float]]
distortion: List[float]
resolution: Tuple[int, int]
class s6.rendering.visuals.Marker3D(*args: Any, **kwargs: Any)

Bases: VisualTreeElement

Solid sphere marker at a 3D position.

set_data(position: Vector3D)

Update sphere translation from a s6.schema.Vector3D.

class s6.rendering.visuals.Image(*args: Any, **kwargs: Any)

Bases: VisualTreeElement

Image plane visual for 2D arrays.

Notes

The image is vertically flipped on assignment to account for VisPy’s coordinate convention.

set_data(value: ndarray)

Set the image data from an (H, W[, C]) NumPy array.

class s6.rendering.visuals.Line3D(*args: Any, **kwargs: Any)

Bases: VisualTreeElement

3D line strip visual from a sequence of points.

set_data(value: List[Vector3D])

Update the polyline from a list of s6.schema.Vector3D.

class s6.rendering.visuals.Frustum3D(*args: Any, **kwargs: Any)

Bases: VisualTreeElement

Frustum wireframe visual with adjustable near/far planes.

update_transform(transform_matrix: ndarray)

Set world transform from a 4x4 matrix (row-major).

static create_frustum(intrinsic_matrix, distortion_coeffs, resolution, near=0.1, far=2.0)

Compute frustum vertices/edges for camera intrinsics and depth range.

Returns:

  • vertices (ndarray, shape (9, 3)) – Camera origin + 4 near-plane corners + 4 far-plane corners.

  • lines (ndarray, shape (M, 2)) – Indices of line segments forming the wireframe.

set_data(value: Dict[str, Any])

Update the frustum from a mapping with extrinsic/intrinsic params.

Expected keys: extrinsic, intrinsic, distortion, resolution.

class s6.rendering.visuals.Camera3D(*args: Any, **kwargs: Any)

Bases: VisualTreeElement

Simple camera widget rendering a frustum and marker at the origin.

update_transform(transform_matrix: ndarray)

Update the transform of the frustum from a 4x4 matrix.

unproject_points(points)

Unproject 2D pixel points to a plane at far depth.

Parameters:

points (ndarray, shape (N, 2)) – Pixel coordinates. Distortion is removed using the provided coefficients.

Returns:

3D points lying on the plane z = far in camera space.

Return type:

ndarray, shape (N, 3)

class s6.rendering.visuals.Frustum(*args: Any, **kwargs: Any)

Bases: VisualTreeElement

Static frustum wireframe visual constructed at init time.

static create_frustum(intrinsic_matrix, distortion_coeffs, resolution, near=0.1, far=2.0)

Compute frustum vertices and connectivity for given camera intrinsics.

class s6.rendering.visuals.Mesh3D(*args: Any, **kwargs: Any)

Bases: VisualTreeElement

Mesh visual loaded from an OBJ file.

Parameters:

  • file (str) – Path to an OBJ file. All meshes in the scene are concatenated.

  • tip_vertex (int) – Index of a representative tip vertex used to auto-orient the mesh when a target direction is provided.

  • parent (vispy.scene.Node, optional) – Parent node in the scene graph.

set_data(value)

Update transform from position or (origin, target) pair.

Parameters:

value (Vector3D or (Vector3D, Vector3D)) –

  • Single vector: set translation to the given position.

  • Pair (origin, target): rotate so the local tip points toward target - origin and translate to origin.

class s6.rendering.visuals.ExternalMeshVisual(*args: Any, **kwargs: Any)

Bases: Node

Load and display a mesh from a file with fixed transform and styling.