Skip to content

Conversions

Pure conversion functions between attitude representations.

All functions operate on raw JAX arrays (no class instances) to avoid circular imports between class modules. The classes in quaternion.py, rotation_matrix.py, euler_angle.py, and euler_axis.py call these kernels and wrap the results.

Convention

Quaternion layout is scalar-first: [w, x, y, z] (shape (4,)). Rotation matrix layout is row-major: shape (3, 3). Euler axis is (axis(3,), angle_scalar).

euler_angle_to_quaternion(order_idx, phi, theta, psi)

Convert Euler angles to a quaternion via jax.lax.switch.

Parameters:

Name Type Description Default
order_idx Array

Integer index 0--11 matching EulerAngleOrder.

 required
phi Array

First rotation angle in radians.

 required
theta Array

Second rotation angle in radians.

 required
psi Array

Third rotation angle in radians.

 required

Returns:

Type Description
Array

jnp.ndarray: Quaternion of shape (4,) in scalar-first order.

euler_axis_to_quaternion(axis, angle)

Convert an Euler axis-angle representation to a quaternion.

The axis is used as-is with half-angle trig, then the result is normalized. This matches the brahe Rust convention where Quaternion::new normalizes after construction.

Parameters:

Name Type Description Default
axis Array

Rotation axis vector of shape (3,).

 required
angle Array

Rotation angle in radians (scalar).

 required

Returns:

Type Description
Array

jnp.ndarray: Unit quaternion of shape (4,) in scalar-first order.

quaternion_multiply(q1, q2)

Hamilton product of two quaternions.

Parameters:

Name Type Description Default
q1 Array

First quaternion of shape (4,) in scalar-first order.

 required
q2 Array

Second quaternion of shape (4,) in scalar-first order.

 required

Returns:

Type Description
Array

jnp.ndarray: Product quaternion of shape (4,).

quaternion_slerp(q1, q2, t)

Spherical linear interpolation between two quaternions.

Falls back to linear interpolation when the quaternions are nearly parallel (dot product > 0.9995).

Parameters:

Name Type Description Default
q1 Array

Start quaternion of shape (4,).

 required
q2 Array

End quaternion of shape (4,).

 required
t float | Array

Interpolation parameter in [0, 1].

 required

Returns:

Type Description
Array

jnp.ndarray: Interpolated quaternion of shape (4,).

quaternion_to_euler_axis(q)

Convert a unit quaternion to Euler axis-angle representation.

When the rotation angle is zero the axis is undefined; the default axis [1, 0, 0] is returned.

Parameters:

Name Type Description Default
q Array

Quaternion of shape (4,) in scalar-first order.

 required

Returns:

Name Type Description
tuple Array

(axis, angle) where axis has shape (3,) and
Array

angle is a scalar in radians.

quaternion_to_rotation_matrix(q)

Convert a unit quaternion to a 3x3 rotation matrix.

Uses the bilinear product form (Diebel eq. 125).

Parameters:

Name Type Description Default
q Array

Quaternion array of shape (4,) in scalar-first order [w, x, y, z].

 required

Returns:

Type Description
Array

jnp.ndarray: Rotation matrix of shape (3, 3).

rotation_matrix_to_euler_angle(order_idx, R)

Extract Euler angles from a rotation matrix.

Parameters:

Name Type Description Default
order_idx Array

Integer index 0--11 matching EulerAngleOrder.

 required
R Array

Rotation matrix of shape (3, 3).

 required

Returns:

Type Description
Array

jnp.ndarray: Array [phi, theta, psi] in radians.

rotation_matrix_to_quaternion(R)

Convert a 3x3 rotation matrix to a unit quaternion.

Uses Shepperd's method with jax.lax.switch on argmax for numerical stability and JIT compatibility.

Parameters:

Name Type Description Default
R Array

Rotation matrix of shape (3, 3).

 required

Returns:

Type Description
Array

jnp.ndarray: Quaternion array of shape (4,) in scalar-first order [w, x, y, z].