vector-traits 0.6.0

Rust traits for 2D and 3D vector types.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

[![crates.io](https://img.shields.io/crates/v/vector-traits.svg)](https://crates.io/crates/vector-traits)
[![Documentation](https://docs.rs/vector-traits/badge.svg)](https://docs.rs/vector-traits)
[![Workflow](https://ci.codeberg.org/api/badges/12855/status.svg)](https://ci.codeberg.org/repos/12855)
![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
[![dependency status](https://deps.rs/crate/vector-traits/0.6.0/status.svg)](https://deps.rs/crate/vector-traits/0.6.0)
![license](https://img.shields.io/crates/l/vector-traits)
[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/eadf)

# 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.

```rust
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);
```

## 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:

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

## Documentation

For detailed documentation, visit [docs.rs/vector-traits](https://docs.rs/vector-traits).

## Contributing

We welcome contributions from the community.
Feel free to submit pull requests or report issues on our GitHub repository.
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.

### Minimum Supported Rust Version (MSRV)

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

## License

Licensed under either of

* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)
  or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT)
  or http://opensource.org/licenses/MIT)

at your option.