clifford 0.3.0

Clifford is a Rust library for Geometric Algebra (also known as Clifford Algebra), providing tools for 3D rotations, rigid body transformations, and computational geometry. If you're looking for an alternative to quaternions, rotation matrices, or homogeneous coordinates, Geometric Algebra offers a unified, intuitive approach.

Why Geometric Algebra?

Geometric Algebra (GA) unifies vectors, complex numbers, quaternions, and more into a single elegant framework. Instead of juggling matrices, quaternions, and Euler angles, GA gives you:

• Rotors: Like quaternions but they generalize to any dimension
• Motors: Rotation + translation in one composable object (no more 4x4 matrices!)
• Bivectors: Oriented planes that represent rotations naturally
• The geometric product: One operation that subsumes dot and cross products

If you work with robotics, computer graphics, physics simulations, or game development, GA simplifies your math while eliminating edge cases like gimbal lock.

Features

• 15 Specialized Algebras: Complex, Dual, Quaternion, Dual Quaternion, 2D/3D Euclidean, 2D/3D Projective (PGA), 2D/3D Conformal (CGA), 2D/3D Minkowski, 2D Elliptic, Hyperbolic
• Projective Geometric Algebra (PGA) for rigid body transforms (points, lines, planes, motors)
• Conformal Geometric Algebra (CGA) for circles, spheres, and conformal transformations
• Code Generation System (clifford-codegen) for deriving optimized algebraic operations
• Optimized 2D/3D types with zero-cost abstractions
• Interior Products and Projections for computing orthogonal components
• Seamless nalgebra integration for existing codebases
• Rerun visualization (clifford-viz) for debugging and education
• Generic over float types (f32, f64)
• Compile-time dimension checking
• Property-tested correctness with proptest
• WASM support for browser-based applications

Installation

[dependencies]
clifford = "0.3"

Quick Start

3D Rotations with Rotors

Rotors are the GA equivalent of quaternions, but they arise naturally from the geometry:

use clifford::ops::Transform;
use clifford::specialized::euclidean::dim3::{Vector, Bivector, Rotor};
use std::f64::consts::FRAC_PI_2;

// Create a rotation of 90 degrees in the xy-plane (around the z-axis)
let plane = Bivector::unit_xy();
let rotor = Rotor::from_angle_plane(FRAC_PI_2, plane);

// Rotate a vector
let v = Vector::new(1.0, 0.0, 0.0);
let rotated = rotor.transform(&v);

// x-axis is now pointing along y-axis
assert!((rotated.x()).abs() < 1e-10);
assert!((rotated.y() - 1.0).abs() < 1e-10);

Rigid Transforms with PGA Motors

Motors combine rotation and translation into a single object that composes beautifully:

use clifford::specialized::projective::dim3::{Motor, Point};

// Create a motor: translate by (1, 2, 3)
let motor = Motor::from_translation(1.0_f64, 2.0, 3.0);

// Transform a point at the origin
let p = Point::origin();
let transformed = motor.transform_point(&p);

// The origin moved to (1, 2, 3)
assert!((transformed.x() - 1.0).abs() < 1e-10);
assert!((transformed.y() - 2.0).abs() < 1e-10);
assert!((transformed.z() - 3.0).abs() < 1e-10);

Compose motors for complex transforms - rotation then translation, or vice versa:

Motors can also transform lines and planes, making them ideal for robotics and graphics.

2D Geometry

The same patterns work in 2D:

use clifford::ops::Transform;
use clifford::specialized::euclidean::dim2::{Vector, Rotor};
use std::f64::consts::FRAC_PI_2;

let v = Vector::new(1.0, 0.0);
let rotor = Rotor::from_angle(FRAC_PI_2);
let rotated = rotor.transform(&v);

assert!((rotated.x()).abs() < 1e-10);
assert!((rotated.y() - 1.0).abs() < 1e-10);

Working with nalgebra

Already using nalgebra? Clifford integrates seamlessly:

use clifford::specialized::euclidean::dim3::{Vector, Rotor, Bivector};
use nalgebra::{Vector3, UnitQuaternion};

// From nalgebra
let na_vec = Vector3::new(1.0_f64, 2.0, 3.0);
let cliff_vec = Vector::from(na_vec);

// To nalgebra
let back_to_na: Vector3<f64> = cliff_vec.into();

// Quaternions too
let rotor = Rotor::from_angle_plane(0.5, Bivector::unit_xy());
let quat: UnitQuaternion<f64> = rotor.into();

Visualization with Rerun

Debug your geometric algebra computations visually:

cargo run --example rerun_bivector --features rerun-0_28

This shows an animated bivector (parallelogram) with its Hodge dual vector, demonstrating how the wedge product works.

Module Structure

Specialized Algebras

Core Infrastructure

Cargo Features

Note: The nalgebra features are mutually exclusive. Enable only one.

Performance

Clifford is designed for performance:

• Specialized types use fixed-size arrays (no heap allocation)
• Operations are inlined and optimized by LLVM
• Benchmarks show competitive performance with hand-written quaternion code

Run benchmarks yourself:

cargo bench

Learning Resources

New to Geometric Algebra? These resources helped us:

• Geometric Algebra Primer - Jaap Suter's excellent introduction
• Let's Remove Quaternions from Every 3D Engine - Marc ten Bosch on why GA is better
• Siggraph 2019 GA Course - Video introduction
• bivector.net - Community resources and tools

Minimum Supported Rust Version

Clifford requires Rust 1.87.0 or later (edition 2024).

License

MIT License