Geometry API

\(SO(3)\)

hatSO3

hatSO3(w: ndarray) -> jnp.ndarray

Map Euclidean vectors to skew-symmetric matrices in \(\mathfrak{so}(3)\).

The hat operator is defined so that matrix multiplication reproduces the three-dimensional cross product:

\[ \widehat{\mathbf{w}} = \begin{bmatrix} 0 & -w_z & w_y \\ w_z & 0 & -w_x \\ -w_y & w_x & 0 \end{bmatrix}, \qquad \widehat{\mathbf{w}}\mathbf{v} = \mathbf{w}\times\mathbf{v}. \]

Parameters:

Name	Type	Description	Default
w	(Array, shape(..., 3))	One vector or a batch of vectors.	required

Returns:

Type	Description
(Array, shape(..., 3, 3))	Skew-symmetric matrices with the same leading batch dimensions and dtype as w.

Notes

The function is compatible with jax.jit, automatic differentiation, and arbitrary leading batch dimensions.

veeSO3

veeSO3(W: ndarray) -> jnp.ndarray

Map matrices in \(\mathfrak{so}(3)\) back to Euclidean vectors.

This is the inverse of hat for a skew-symmetric matrix:

\[ \left( \begin{bmatrix} 0 & -w_z & w_y \\ w_z & 0 & -w_x \\ -w_y & w_x & 0 \end{bmatrix} \right)^\vee = \begin{bmatrix}w_x & w_y & w_z\end{bmatrix}^{T}. \]

Parameters:

Name	Type	Description	Default
W	(Array, shape(..., 3, 3))	One matrix or a batch of matrices. Inputs are assumed to be skew-symmetric; this function does not validate or antisymmetrize them.	required

Returns:

Type	Description
(Array, shape(..., 3))	Vectors formed from entries W[..., 2, 1], W[..., 0, 2], and W[..., 1, 0].

expSO3

expSO3(w: ndarray) -> jnp.ndarray

Evaluate the exponential map from rotation vectors to \(SO(3)\).

For \(\theta=\lVert\mathbf{w}\rVert\) and \(W=\widehat{\mathbf{w}}\), Rodrigues' formula gives

\[ \operatorname{Exp}(\mathbf{w}) = I + \frac{\sin\theta}{\theta}W + \frac{1-\cos\theta}{\theta^2}W^2. \]

The vector direction is the rotation axis and its norm is the rotation angle in radians. Near the identity, series expansions replace the two removable singularities in Rodrigues' formula.

Parameters:

Name	Type	Description	Default
w	(Array, shape(..., 3))	Rotation vectors in radians.	required

Returns:

Type	Description
(Array, shape(..., 3, 3))	Proper rotation matrices with the same leading batch dimensions as w.

Raises:

Type	Description
ValueError	If the trailing shape of w is not (3,).

Notes

The small-angle and general branches remain finite during JAX automatic differentiation, including exactly at w = 0.

logSO3

logSO3(R: ndarray) -> jnp.ndarray

Evaluate the principal logarithm of rotations in \(SO(3)\).

The result \(\mathbf{w}\) satisfies

\[ \operatorname{Exp}(\mathbf{w}) = R, \qquad \lVert\mathbf{w}\rVert \in [0, \pi]. \]

Separate numerical paths are used near the identity and near \(\pi\). The near-identity path avoids differentiating arccos at one, while the near-\(\pi\) path recovers the rotation axis from the symmetric part of R when its skew part becomes too small.

Parameters:

Name	Type	Description	Default
R	(Array, shape(..., 3, 3))	One proper rotation matrix or a batch of proper rotation matrices.	required

Returns:

Type	Description
(Array, shape(..., 3))	Principal rotation vectors with the same leading batch dimensions as R.

Raises:

Type	Description
ValueError	If the trailing shape of R is not (3, 3).

Notes

log assumes that every input belongs to \(SO(3)\) and does not validate orthogonality or determinant. Its value is undefined for an improper or otherwise invalid rotation. Use log_checked for host-side validation or is_proper_rotation inside transformed JAX code.

The principal logarithm is discontinuous at rotations of angle \(\pi\); derivatives should be interpreted on one side of that branch cut.

is_proper_rotation

is_proper_rotation(R: ndarray, atol: float = 1e-06) -> jnp.ndarray

Test whether matrices satisfy the defining conditions of \(SO(3)\).

A matrix is accepted when both

\[ \lVert R^T R-I\rVert_F < \mathtt{atol} \qquad\text{and}\qquad |\det(R)-1| < \mathtt{atol}. \]

Parameters:

Name	Type	Description	Default
R	(Array, shape(..., 3, 3))	Matrices to test.	required
atol	float	Absolute tolerance applied independently to the orthogonality and determinant errors. The default is 1e-6.	1e-06

Returns:

Type	Description
jax.Array, shape (...,), dtype bool	One boolean result for each matrix. A scalar boolean array is returned for a single (3, 3) matrix.

Raises:

Type	Description
ValueError	If the trailing shape of R is not (3, 3).

Notes

Unlike log_checked, this function is suitable for use with jax.jit, jax.vmap, and jax.lax.cond.

logSO3_checked

logSO3_checked(R: ndarray, atol: float = 1e-06) -> jnp.ndarray

Evaluate the principal logarithm after validating membership in \(SO(3)\).

Parameters:

Name	Type	Description	Default
R	(Array, shape(..., 3, 3))	One rotation matrix or a batch of rotation matrices. Every matrix must pass is_proper_rotation.	required
atol	float	Absolute tolerance used for both the orthogonality and determinant checks. The default is 1e-6.	1e-06

Returns:

Type	Description
(Array, shape(..., 3))	Principal rotation vectors returned by log.

Raises:

Type	Description
ValueError	If the input shape is invalid or any input matrix fails validation.

Notes

Validation converts the combined JAX boolean to a Python bool in order to raise a normal exception. Consequently, log_checked is intended for input boundaries, tests, and debugging rather than a JIT-compiled hot path. Use is_proper_rotation when validation must remain inside JAX transformations.

\(SE(3)\)

hatSE3

hatSE3(xi: ndarray) -> jnp.ndarray

Map twists to matrices in \(\mathfrak{se}(3)\).

SympLie orders a twist as \(\boldsymbol{\xi}=[\boldsymbol{\rho}, \boldsymbol{\phi}]\), with translation first and rotation second. The hat operator is

\[ \widehat{\boldsymbol{\xi}} = \begin{bmatrix} \widehat{\boldsymbol{\phi}} & \boldsymbol{\rho} \\ \mathbf{0}^{T} & 0 \end{bmatrix}. \]

Parameters:

Name	Type	Description	Default
xi	(Array, shape(..., 6))	One twist or a batch of twists in [rho, phi] order.	required

Returns:

Type	Description
(Array, shape(..., 4, 4))	Homogeneous Lie-algebra matrices with the same leading batch dimensions and dtype as xi.

Raises:

Type	Description
ValueError	If the trailing shape of xi is not (6,).

veeSE3

veeSE3(X: ndarray) -> jnp.ndarray

Map matrices in \(\mathfrak{se}(3)\) back to twists.

For a matrix

\[ X = \begin{bmatrix} \widehat{\boldsymbol{\phi}} & \boldsymbol{\rho} \\ \mathbf{0}^{T} & 0 \end{bmatrix}, \]

the result is the translation-first twist \([\boldsymbol{\rho},\boldsymbol{\phi}]\).

Parameters:

Name	Type	Description	Default
X	(Array, shape(..., 4, 4))	One Lie-algebra matrix or a batch of matrices. The function assumes the expected \(\mathfrak{se}(3)\) structure and does not validate it.	required

Returns:

Type	Description
(Array, shape(..., 6))	Twists in [rho, phi] order.

Raises:

Type	Description
ValueError	If the trailing shape of X is not (4, 4).

expSE3

expSE3(xi: ndarray) -> jnp.ndarray

Evaluate the exponential map from twists to \(SE(3)\).

For the translation-first twist \(\boldsymbol{\xi}=[\boldsymbol{\rho},\boldsymbol{\phi}]\), SympLie constructs

\[ \operatorname{Exp}(\boldsymbol{\xi}) = \begin{bmatrix} \operatorname{Exp}(\boldsymbol{\phi}) & J_l(\boldsymbol{\phi})\boldsymbol{\rho} \\ \mathbf{0}^{T} & 1 \end{bmatrix}. \]

Parameters:

Name	Type	Description	Default
xi	(Array, shape(..., 6))	Twists in [rho, phi] order. Rotational components are in radians.	required

Returns:

Type	Description
(Array, shape(..., 4, 4))	Homogeneous transformation matrices with the same leading batch dimensions as xi.

Raises:

Type	Description
ValueError	If the trailing shape of xi is not (6,).

Notes

The implementation uses the numerically stable \(SO(3)\) exponential and left Jacobian, including their small-angle paths.

logSE3

logSE3(T: ndarray) -> jnp.ndarray

Evaluate the principal logarithm of transformations in \(SE(3)\).

For

\[ T = \begin{bmatrix}R & \mathbf{p} \\ \mathbf{0}^{T} & 1\end{bmatrix}, \]

the principal twist is

\[ \boldsymbol{\phi}=\operatorname{Log}(R), \qquad \boldsymbol{\rho}=J_l^{-1}(\boldsymbol{\phi})\mathbf{p}, \qquad \boldsymbol{\xi}=[\boldsymbol{\rho},\boldsymbol{\phi}]. \]

Parameters:

Name	Type	Description	Default
T	(Array, shape(..., 4, 4))	One homogeneous transformation or a batch of transformations.	required

Returns:

Type	Description
(Array, shape(..., 6))	Principal translation-first twists. The rotation-vector norm lies in \([0,\pi]\).

Raises:

Type	Description
ValueError	If the trailing shape of T is not (4, 4).

Notes

log assumes that the rotational block is a proper rotation and that the final row has homogeneous-transform structure. It does not validate either condition. The rotational principal-branch behavior and branch cut are inherited from symplie.so3.log.

left_jacobian_SO3

left_jacobian_SO3(phi: ndarray) -> jnp.ndarray

Evaluate the left Jacobian of \(SO(3)\).

For \(\theta=\lVert\boldsymbol{\phi}\rVert\) and \(\Phi=\widehat{\boldsymbol{\phi}}\), the Jacobian is

\[ J_l(\boldsymbol{\phi}) = I + \frac{1-\cos\theta}{\theta^2}\Phi + \frac{\theta-\sin\theta}{\theta^3}\Phi^2. \]

It maps the translational component of an \(\mathfrak{se}(3)\) twist to the translation in the corresponding homogeneous transform.

Parameters:

Name	Type	Description	Default
phi	(Array, shape(..., 3))	Rotation vectors in radians.	required

Returns:

Type	Description
(Array, shape(..., 3, 3))	Left Jacobians with the same leading batch dimensions as phi.

Raises:

Type	Description
ValueError	If the trailing shape of phi is not (3,).

Notes

A series expansion is used near zero. The implementation is compatible with JAX JIT compilation, batching, and automatic differentiation.

left_jacobian_inverse_SO3

left_jacobian_inverse_SO3(phi: ndarray) -> jnp.ndarray

Evaluate the inverse left Jacobian of \(SO(3)\).

For \(\theta=\lVert\boldsymbol{\phi}\rVert\) and \(\Phi=\widehat{\boldsymbol{\phi}}\), the inverse is

\[ J_l^{-1}(\boldsymbol{\phi}) = I - \frac{1}{2}\Phi + \left[ \frac{1}{\theta^2} - \frac{1+\cos\theta}{2\theta\sin\theta} \right]\Phi^2. \]

Parameters:

Name	Type	Description	Default
phi	(Array, shape(..., 3))	Rotation vectors in radians.	required

Returns:

Type	Description
(Array, shape(..., 3, 3))	Inverse left Jacobians with the same leading batch dimensions as phi.

Raises:

Type	Description
ValueError	If the trailing shape of phi is not (3,).

Notes

A series expansion is used near zero. This inverse is used by log to recover the translational twist coordinate.