vector-traits 0.6.2

Rust traits for 2D and 3D vector types.
Documentation

crates.io Documentation Workflow Coverage dependency status license

vector-traits

vector-traits is a Rust crate designed to provide a 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

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

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.

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![/* your glam::Vec2 data */];
let convex_hull = point_cloud.convex_hull();

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

Supported Vector Implementations

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

  • glam::Vec2,glam::DVec2,glam::Vec3,glam::Vec3A and glam::DVec3
  • cgmath::Vector2 and cgmath::Vector3 (for f32 and f64)
  • nalgebra::Vector2 and nalgebra::Vector3 (for f32 and f64)
  • macaw::Vec2,macaw::DVec2,macaw::Vec3,macaw::Vec3A and macaw::DVec3 (macaw can't be combined with glam)

Usage

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

[dependencies]
# Enable only the features you need to minimize dependencies
vector-traits = { version = "0.6.2", features = ["glam", "cgmath", "nalgebra"] }

Documentation

For detailed documentation, visit docs.rs/vector-traits.

Minimum Supported Rust Version (MSRV)

The minimum supported version of Rust for vector-traits is 1.87.0.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.