Struct SO3 

pub struct SO3 { /* private fields */ }

SO(3) group element - 3×3 real orthogonal matrix with determinant 1

Represents a rotation in 3D space.

Representation

We use Matrix3<f64> from nalgebra to represent the 3×3 rotation matrix.

Constraints

• Orthogonality: R^T R = I
• Determinant: det(R) = 1

Examples

use lie_groups::so3::SO3;
use lie_groups::traits::LieGroup;

// Rotation around Z-axis by π/2
let rot = SO3::rotation_z(std::f64::consts::FRAC_PI_2);

// Verify it's orthogonal
assert!(rot.verify_orthogonality(1e-10));

Implementations

impl SO3

pub fn matrix(&self) -> &Matrix3<f64>

Access the underlying 3×3 orthogonal matrix

pub fn identity() -> Self

Identity element (no rotation)

pub fn rotation_x(angle: f64) -> Self

Rotation around X-axis by angle θ (in radians)

R_x(θ) = [[1, 0, 0], [0, cos(θ), -sin(θ)], [0, sin(θ), cos(θ)]]

pub fn rotation_y(angle: f64) -> Self

Rotation around Y-axis by angle θ (in radians)

R_y(θ) = [[cos(θ), 0, sin(θ)], [0, 1, 0], [-sin(θ), 0, cos(θ)]]

pub fn rotation_z(angle: f64) -> Self

Rotation around Z-axis by angle θ (in radians)

R_z(θ) = [[cos(θ), -sin(θ), 0], [sin(θ), cos(θ), 0], [0, 0, 1]]

pub fn rotation(axis: [f64; 3], angle: f64) -> Self

Rotation around arbitrary axis by angle

Uses Rodrigues’ rotation formula:

R(θ, n̂) = I + sin(θ)[n̂]_× + (1-cos(θ))[n̂]_ײ

where [n̂]_× is the skew-symmetric matrix for axis n̂.

pub fn trace(&self) -> f64

Trace of the rotation matrix: Tr(R) = 1 + 2cos(θ)

pub fn to_matrix(&self) -> [[f64; 3]; 3]

Convert to 3×3 array format

pub fn from_matrix(arr: [[f64; 3]; 3]) -> Self

Create from 3×3 array format

Panics

Does not verify orthogonality. Use verify_orthogonality() after construction.

pub fn verify_orthogonality(&self, tolerance: f64) -> bool

Verify orthogonality: R^T R = I

pub fn inverse(&self) -> Self

Matrix inverse (equals transpose for orthogonal matrices)

pub fn distance_to_identity(&self) -> f64

Distance from identity (rotation angle)

For a rotation matrix R, the angle θ satisfies:

trace(R) = 1 + 2cos(θ)

pub fn interpolate(&self, other: &Self, t: f64) -> Self

Interpolate between two SO(3) elements with proper orthogonalization

Uses linear interpolation of matrix elements followed by Gram-Schmidt orthogonalization to ensure the result stays on SO(3).

Arguments

• other - The target rotation
• t - Interpolation parameter in [0, 1]

Returns

An SO(3) element: self at t=0, other at t=1

Note

This is NOT geodesic interpolation (SLERP). For true geodesic paths, convert to quaternions and use quaternion SLERP. However, this method guarantees the result is always a valid rotation matrix.

pub fn gram_schmidt_orthogonalize(matrix: Matrix3<f64>) -> Self

Orthogonalize a matrix using Gram-Schmidt process

Takes a near-orthogonal matrix and projects it back onto SO(3). This is essential for numerical stability when matrices drift from orthogonality due to floating-point accumulation.

Algorithm

1. Normalize first column
2. Orthogonalize and normalize second column
3. Compute third column as cross product (ensures determinant = 1)

pub fn renormalize(&self) -> Self

Re-normalize a rotation matrix that may have drifted

Use this periodically after many matrix multiplications to prevent numerical drift from accumulating.

pub fn geodesic_distance(&self, other: &Self) -> f64

Geodesic distance between two SO(3) elements

d(R₁, R₂) = ||log(R₁ᵀ R₂)||

This is the rotation angle of the relative rotation R₁ᵀ R₂.

Trait Implementations

impl Clone for SO3

fn clone(&self) -> SO3

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Compact for SO3

SO(3) is compact

The rotation group is diffeomorphic to ℝP³ (real projective 3-space). All rotations are bounded: ||R|| = 1.

impl Debug for SO3

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SO3

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl LieGroup for SO3

const MATRIX_DIM: usize = 3

Matrix dimension in the fundamental representation.

type Algebra = So3Algebra

Associated Lie algebra type.

fn identity() -> Self

The identity element e ∈ G.

fn compose(&self, other: &Self) -> Self

Group composition (multiplication): g₁ · g₂

fn inverse(&self) -> Self

Group inverse: g⁻¹

fn conjugate_transpose(&self) -> Self

Adjoint representation element (for matrix groups: conjugate transpose).

fn adjoint_action(&self, algebra_element: &So3Algebra) -> So3Algebra

Adjoint representation: Ad_g: 𝔤 → 𝔤

fn distance_to_identity(&self) -> f64

Geodesic distance from identity: d(g, e)

fn exp(tangent: &So3Algebra) -> Self

Exponential map: 𝔤 → G

fn log(&self) -> LogResult<So3Algebra>

Logarithm map: G → 𝔤 (inverse of exponential)

fn distance(&self, other: &Self) -> f64

Distance between two group elements: d(g, h)

fn is_near_identity(&self, tolerance: f64) -> bool

Check if this element is approximately the identity.

fn trace_identity() -> f64

Trace of the identity element

fn reorthogonalize(&self) -> Self

Project element back onto the group manifold using Gram-Schmidt orthogonalization.

fn geodesic(&self, other: &Self, t: f64) -> Option<Self>

Geodesic interpolation between two group elements.

impl Mul<&SO3> for &SO3

Group multiplication: R₁ · R₂

type Output = SO3

The resulting type after applying the * operator.

fn mul(self, rhs: &SO3) -> SO3

Performs the * operation.

impl Mul<&SO3> for SO3

type Output = SO3

The resulting type after applying the * operator.

fn mul(self, rhs: &SO3) -> SO3

Performs the * operation.

impl MulAssign<&SO3> for SO3

fn mul_assign(&mut self, rhs: &SO3)

Performs the *= operation.

impl PartialEq for SO3

fn eq(&self, other: &SO3) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl SemiSimple for SO3

SO(3) is semi-simple

impl Simple for SO3

SO(3) is simple

It has no non-trivial normal subgroups (for dimension > 2).

impl StructuralPartialEq for SO3