unilab.utils.geometry

Standalone numpy helpers for coordinate frames and geometry.

Reusable pure-numpy helpers for rotations, coordinate-frame transforms, and geometric conversions. Kept dtype-agnostic and side-effect-free so that env / task / backend code can compose them without carrying task policy inside a shared module. Complements the vectorized quaternion primitives in unilab.utils.rotation.

Functions

np_gravity_z_in_body_from_quat(quat_w)

Z component of world gravity [0, 0, -1] expressed in body frame.

np_normalize_axis(axis)

Return a unit-length copy of a rotation axis vector.

np_quat_angular_velocity_from_pair(quat, ...)

Angular velocity from two consecutive quaternions via axis-angle diff / dt.

np_roll_pitch_from_quat(quat)

Roll and pitch (rad) from a w-first quaternion, computed via rotation-matrix rows.

np_sample_uniform(lower, upper, size[, dtype])

Sample uniformly from [lower, upper] and cast to dtype.

np_sample_uniform_quaternion(num_samples)

Sample uniformly random unit quaternions (w-first) via Shoemake (1992).
unilab.utils.geometry.np_sample_uniform(lower, upper, size, dtype=<class 'numpy.float32'>)[source]

Sample uniformly from [lower, upper] and cast to dtype.

Parameters:
Return type:

ndarray

unilab.utils.geometry.np_normalize_axis(axis)[source]

Return a unit-length copy of a rotation axis vector. Raises on zero norm.

Parameters:

axis (ndarray | tuple[float, ...] | list[float])

Return type:

ndarray

unilab.utils.geometry.np_roll_pitch_from_quat(quat)[source]

Roll and pitch (rad) from a w-first quaternion, computed via rotation-matrix rows.

Supports either (4,) or (..., 4) inputs. Returned arrays match the caller’s leading shape and dtype (no upcast).

Parameters:

quat (ndarray)

Return type:

tuple[ndarray, ndarray]

unilab.utils.geometry.np_gravity_z_in_body_from_quat(quat_w)[source]

Z component of world gravity [0, 0, -1] expressed in body frame.

Equivalent to np_quat_apply_inverse(quat_w, [0, 0, -1])[..., 2] but computed directly from quaternion components to skip the intermediate.

Parameters:

quat_w (ndarray)

Return type:

ndarray

unilab.utils.geometry.np_quat_angular_velocity_from_pair(quat, prev_quat, dt)[source]

Angular velocity from two consecutive quaternions via axis-angle diff / dt.

Parameters:
Return type:

ndarray

unilab.utils.geometry.np_sample_uniform_quaternion(num_samples)[source]

Sample uniformly random unit quaternions (w-first) via Shoemake (1992).

Returns an (num_samples, 4) array in float64 (leaves any downstream dtype conversion to the caller).

Parameters:

num_samples (int)

Return type:

ndarray