viam.spatialmath

Pythonic spatial-math types backed by the shared Rust FFI (libviam_rust_utils).

Results are parity-tested against Go rdk/spatialmath using golden vectors.

Angle convention — ALL angles in these classes are in radians. Euler angles follow the Z-Y’-X’’ (yaw → pitch → roll) intrinsic convention.

Proto bridge — the from_proto / to_proto / from_pose / to_pose class methods convert to and from the Viam protobuf API, which uses degrees. Those methods handle the conversion automatically; callers should not pre-convert.

Classes

AxisAngle — axis-angle representation (axis x/y/z + theta in radians)
Axis — NamedTuple(x, y, z) returned by AxisAngle.axis
EulerAngles — roll, pitch, yaw in radians (Z-Y’-X’’ order)
OrientationVector — orientation vector (ox, oy, oz + theta in radians)
Quaternion — unit quaternion (w, x, y, z)
RotationMatrix — 3×3 rotation matrix
Vector3 — 3-D Cartesian vector (x, y, z)

Submodules

Classes

`Axis`
`AxisAngle`	Axis-angle (axis x/y/z, theta) backed by the spatialmath FFI.
`EulerAngles`	Euler angles (roll, pitch, yaw; Z-Y'-X" order) backed by the spatialmath FFI.
`OrientationVector`	An orientation vector (o_x, o_y, o_z, theta) backed by the spatialmath FFI.
`Quaternion`	A quaternion (w, i, j, k) backed by the rust-utils spatialmath FFI.
`RotationMatrix`	A 3x3 rotation matrix backed by the spatialmath FFI.
`Vector3`	A 3-vector backed by the rust-utils spatialmath FFI.

Package Contents

class viam.spatialmath.Axis[source]

Bases: NamedTuple

x: float

y: float

z: float

class viam.spatialmath.AxisAngle(x: float, y: float, z: float, theta: float)[source]

Axis-angle (axis x/y/z, theta) backed by the spatialmath FFI.

__slots__ = ('_handle', '__weakref__')

property axis: Axis

property theta: float

to_quaternion()[source]

__repr__() → str[source]

class viam.spatialmath.EulerAngles(roll: float, pitch: float, yaw: float)[source]

Euler angles (roll, pitch, yaw; Z-Y’-X” order) backed by the spatialmath FFI.

__slots__ = ('_handle', '__weakref__')

property roll: float

property pitch: float

property yaw: float

to_quaternion()[source]

__repr__() → str[source]

class viam.spatialmath.OrientationVector(o_x: float, o_y: float, o_z: float, theta: float)[source]

An orientation vector (o_x, o_y, o_z, theta) backed by the spatialmath FFI.

theta is in RADIANS for this class. The proto bridge converts to/from the proto’s degrees.

__slots__ = ('_handle', '__weakref__')

classmethod from_proto(proto: viam.proto.common.Orientation) → OrientationVector[source]

to_proto() → viam.proto.common.Orientation[source]

property o_x: float

property o_y: float

property o_z: float

property theta: float

to_quaternion()[source]

__repr__() → str[source]

class viam.spatialmath.Quaternion(w: float, i: float, j: float, k: float)[source]

A quaternion (w, i, j, k) backed by the rust-utils spatialmath FFI.

__slots__ = ('_handle', '__weakref__')

classmethod from_imaginary_vector(real: float, imag: viam.spatialmath.vector3.Vector3) → Quaternion[source]

property w: float

property i: float

property j: float

property k: float

property imaginary_vector: viam.spatialmath.vector3.Vector3

__mul__(other: Quaternion) → Quaternion[source]

__add__(other: Quaternion) → Quaternion[source]

__sub__(other: Quaternion) → Quaternion[source]

conjugate() → Quaternion[source]

scaled(factor: float) → Quaternion[source]

normalized() → Quaternion[source]

normalize() → None[source]: Normalize this quaternion in place.

rotate_vector(v: viam.spatialmath.vector3.Vector3) → viam.spatialmath.vector3.Vector3[source]

classmethod from_pose(pose) → Quaternion[source]

to_pose(x: float, y: float, z: float)[source]

to_orientation_vector()[source]

to_euler_angles()[source]

to_axis_angle()[source]

to_rotation_matrix()[source]

__repr__() → str[source]

class viam.spatialmath.RotationMatrix(elements: Sequence[float])[source]

A 3x3 rotation matrix backed by the spatialmath FFI.

elements is a 9-value list following Go rdk/spatialmath’s row-major rotation-matrix convention (elements[3*row + col]). Construction and readback are both raw pass-throughs of the underlying nalgebra buffer, so they are mutually consistent by construction; that this raw buffer coincides with rdk’s row-major convention is an empirical fact pinned by the golden parity tests (it is not a general column-major/row-major identity).