Theon is a Rust library that abstracts Euclidean spaces and integrates with various crates and types in the Rust ecosystem. Theon can be used by libraries to avoid choosing specific math or linear algebra crates on behalf of their dependents.

Geometric Traits

Theon provides geometric traits that model Euclidean spaces. These traits are not always mathematically rigorous, but this allows them to be implemented for many types. APIs are designed for computations in lower dimensional Euclidean spaces, but traits and types are generic with respect to dimension.

Integrations

Theon provides optional implementations for commonly used crates in the Rust ecosystem, including glam and ultraviolet. These implementations can be enabled using Cargo features.

Feature	Default	Crate	Support
geometry-cgmath	No	cgmath	Complete¹
geometry-glam	No	glam	Complete¹
geometry-mint	No	mint	Partial
geometry-nalgebra	Yes	nalgebra	Complete¹
geometry-ultraviolet	No	ultraviolet	Partial²

Integrated crates are re-exported in the integration module. Because a given version of Theon implements traits for specific versions of integrated crates, care must be taken to align these versions. Dependent crates can either use the re-exported crates provided by Theon with no direct dependency or ensure that the version of a supported crate resolves to the same version for which Theon implements its traits.

[1]: Because Theon is still in its initial development phase, complete does not necessarily mean that all traits and features are implemented, but instead that all traits and features can be feasibly supported and are implemented for common use cases.

[2]: Importantly, traits and features are not yet implemented for SIMD types like Wec3.

Spatial Queries

Geometric queries can be performed using any types that implement the appropriate geometric traits.

use nalgebra::Point2;
use theon::adjunct::Converged;
use theon::query::{Aabb, Intersection, Ray, Unit};
use theon::space::EuclideanSpace;

type E2 = Point2<f64>;

let aabb = Aabb::<E2> {
    origin: EuclideanSpace::origin(),
    extent: Converged::converged(1.0),
};
let ray = Ray::<E2> {
    origin: EuclideanSpace::from_xy(-1.0, 0.5),
    direction: Unit::x(),
};
assert_eq!(Some((1.0, 2.0)), ray.intersection(&aabb));
assert_eq!(None, ray.reverse().intersection(&aabb));

In the above example, it is possible to replace the E2 type definition with types from cgmath, glam, or any other type that implements EuclideanSpace, etc.

LAPACK

Some queries require solving linear systems of arbitrary and non-trivial size. To support these queries, the lapack feature depends on ndarray and LAPACK libraries. For example, Plane::from_points is enabled by the lapack feature and computes a best-fit plane using a singular value decomposition.

The lapack feature only supports Linux at this time.