Crate vector_traits

Source
Expand description

§Vector-Traits Crate

vector-traits is a Rust crate designed to provide a limited set of traits for abstracting over different vector implementations and scalar types, offering a unified interface for a basic set of vector operations. This crate facilitates seamless transitions between different vector libraries and scalar precisions (e.g., f32 and f64) without requiring significant code modifications.

§Features

  • Abstract over two-dimensional and three-dimensional vectors with GenericVector2 and GenericVector3 traits.
  • Generic scalar trait GenericScalar for flexible scalar type handling.
  • Basic vector traits HasXY and HasXYZ for low-level, custom vector storage types, e.g., FFI types.
  • Seamless transition between different vector libraries like cgmath, glam, and nalgebra.
  • Ability to switch between different scalar types (f32, f64) effortlessly.

§Design Philosophy

This library is designed to be agnostic to whether the underlying type represents a point or a vector. For example, you can compute the distance between two points (v0.distance(v1)) or the magnitude of a vector (v0.magnitude()) regardless of how the underlying library differentiates between points and vectors. This approach simplifies interoperability and allows you to focus on the geometric operations rather than the semantic distinctions.

While some libraries make a deliberate effort to differentiate between points and vectors (e.g., nalgebra and cgmath), this crate intentionally treats them uniformly to provide a consistent and flexible interface. This means that operations like distance, magnitude, and normalize are available on any type that implements the relevant traits, whether it represents a point or a vector in the underlying library.

§Supported Vector Implementations

Currently, the following vector types from cgmath, glam, and nalgebra libraries are supported:

  • glam::Vec2, glam::Vec3, glam::Mat3, glam::Mat4
  • glam::Vec3A, glam::Mat3A (uses newtype wrappers: Vec2A & Mat4A for symmetry)
  • glam::DVec2, glam::DVec3, glam::DMat3, glam::DMat4
  • cgmath::Vector2, cgmath::Vector3
  • nalgebra::Vector2, nalgebra::Vector3

§Usage

Add vector-traits to your Cargo.toml dependencies along with the desired features:

[dependencies]
vector-traits = { version = "0.4.0", features = ["glam", "cgmath", "nalgebra"] }  # only use what you need

§Example

In this example we use the linestring crate, that builds upon these traits, to calculate the convex hull of a Vec of coordinates and an RDP simplified linestring. It does this without any type conversions, but instead uses the specified vector type throughout.

ⓘ
use vector_traits::prelude::GenericVector2;
use linestring::prelude::LineString2;

let point_cloud: Vec<glam::Vec2> = vec![/* your glam::Vec2 data */];
let convex_hull = point_cloud.convex_hull();

let linestring: Vec<nalgebra::Vector2<f64>> = vec![/* your nalgebra::Vector2<f64> data */];
let simplified_linestring = linestring.simplify_rdp(0.001);

§Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

§License

Licensed under either of

at your option.

Re-exports§

pub use approx;
pub use cgmath;
pub use glam;
pub use nalgebra;
pub use num_traits;

Modules§

prelude