spatial_operations

Spatial pose and point utilities.

This module defines spatial utility models and transformation helpers for points and poses. It provides typed pose representations, conversion between homogeneous matrices and structured pose models, and point-transformation utilities that work directly with NumPy arrays. The module streamlines common spatial operations used by camera and calibration workflows while preserving a user-friendly API.

Key functionalities include: - Structured 3D pose models for position and Euler-angle orientation. - Conversion between homogeneous transforms and typed pose objects. - Homogeneous-coordinate helpers for batched point transformations. - Utilities for transforming single points and point sets with 4x4 matrices. - Input-shape normalization for robust NumPy-based spatial computations. - Lightweight abstractions optimized for internal camera workflow usage.

class robotblockset.cameras.spatial_operations.Position(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Position in 3D space, all units are in meters.

x: float

y: float

z: float

class robotblockset.cameras.spatial_operations.EulerAngles(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Extrinsic XYZ Euler angles in radians.

roll: float

pitch: float

yaw: float

class robotblockset.cameras.spatial_operations.Pose(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Position and extrinsic XYZ orientation of an object in 3D space.

Position values are expressed in meters and Euler angles in radians. The rotations are about the fixed X, Y, and Z axes of the reference frame.

position_in_meters: Position

rotation_euler_xyz_in_radians: EulerAngles

classmethod from_homogeneous_matrix(matrix: ndarray) → Pose[source]

Construct a pose from a homogeneous transformation matrix.

Parameters:: matrix (HomogeneousMatrixType) – Homogeneous transformation matrix with shape (4, 4).
Returns:: Structured position and Euler-angle representation.
Return type:: Pose

as_homogeneous_matrix() → ndarray[source]

Return the pose as a homogeneous transformation matrix.

Returns:: Homogeneous transformation matrix with shape (4, 4).
Return type:: HomogeneousMatrixType

robotblockset.cameras.spatial_operations.transform_points(homogeneous_transform_matrix: ndarray, points: ArrayLike) → ndarray[source]

Apply a homogeneous transformation to one or more 3D points.

Parameters:

homogeneous_transform_matrix (HomogeneousMatrixType) – Transformation matrix with shape (4, 4).
points (numpy.typing.ArrayLike) – Single 3D point with shape (3,) or point batch with shape (N, 3). Lists, tuples, and NumPy arrays are accepted.

Returns:

Transformed point with shape (3,) if the input was one-dimensional, otherwise a transformed point array with shape (N, 3).

Return type:

Vectors3DType

Raises:

TypeError – If points is not array-like or does not contain real numeric values.
ValueError – If points has an unsupported shape, contains non-finite values, or produces a zero or near-zero homogeneous scale.

Functions

transform_points(...)

Apply a homogeneous transformation to one or more 3D points.

Classes

`EulerAngles`(args, *kwargs)	Extrinsic XYZ Euler angles in radians.
`Pose`(args, *kwargs)	Position and extrinsic XYZ orientation of an object in 3D space.
`Position`(args, *kwargs)	Position in 3D space, all units are in meters.