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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
//!
//! geomath is a general purpose maths framework that aims to provide efficient real-time tools for the
//! following domains:
//!
//! * Linear algebra
//! * Computational Geometry
//! * Computer Graphics and Vision
//! * Physics and Kinematics simulation
//! * Numerical simulation
//!
//! It relies on a vast API that consists on various traits each specifying a math property.
//! It provides most of the common abstraction used in the above domains :
//! * 2D, 3D, 4D matrices, trajectories and points
//! * 2D, 3D, 4D, 6D vectors
//!
//! The implementation benefits from many optimizations allowed when working with small dimensions :
//! * Straight forward code
//! * Hand-optimized operations
//! * Fully stack allocated
//!
//! However, it still uncomplete and other features and improvements are planned,
//! take a look at the [GitHub developement branch](https://github.com/samiBendou/geomath) for more details.
//!
//! # Get started
//! If you already familiar with linear algebra libraries, you can easily get started since the
//! API is really straight forward,
//! basic vector space operations are implemented as operators and do not need any traits.
//! Other operations can be imported with the prelude.
//!
//! ## Basic principles
//! Some simple conventions have been choosed either to gain clarity or performance :
//! * Vectors are columns matrices when operating with a matrix
//! * Vectors cartesian coordinates are accessible using `vector.i` syntax with `i` the name of the coordinate
//! * Matrices components can be accessed using `matrix.ij` where `i` is the row index and `j` the column index
//! * Rows and columns are indexed with `x`, `y`, `z`, ... starting with `x`
//! * Vectors of size N can be left multiplied by matrices of size N+1
//!
//! **Note :** When left-multiplying a vector of size N with a matrix of size N+1 the vector is seen as an homogeneous
//! vector (ie. vector of size N) with added component at 1.
//! It's a way to perfrom efficient multiplications with transformation matrices.
//!
//! ### Example
//! ```
//! use geomath::matrix;
//! let m = matrix::consts::EYE_2;
//! assert_eq!(m.xx, 1.);
//! assert_eq!(m.xy, 0.);
//! assert_eq!(m.yx, 0.);
//! assert_eq!(m.yy, 1.);
//! ```
//!
//! ### Multiply assign
//! The multiply assign operator between matrices and vectors reverses the order of the operands
//! which means `u *= m` computes in fact `u = m * u`. This allows faster assign multiply implementation.
//!
//! ## The prelude
//! As said above, the prelude contains the traits specifications, it is split in a root and 2 modules :
//! ```
//! use geomath::prelude::*; // most of the traits
//! use geomath::prelude::coordinates::*; // coordinates systems and transformations
//! use geomath::prelude::transforms::*; // matrix transforms (translations, rotations, ...)
//! ```
//!
//! ## Constants
//! Instead of providing static generators for unit vectors and identity matrices, these
//! are hard coded as constants :
//! ```
//! use geomath::vector;
//! let u = vector::consts::EX_3; // unit vector in the positive x (1, 0, 0)
//! let v = vector::consts::N_EZ_3; // unit vector in the negative z direction (0, 0, -1)
//! let w = vector::consts::ZEROS_3; // zero vector of 3D space (0, 0, 0)
//! ```
//! **Note :** All the modules have a `consts` submodule.
//!
//! However if you are more familiar with the generators, you can still do :
//! ```
//! use geomath::prelude::Initializer;
//! use geomath::vector::Vector3;
//! let u = Vector3::zeros(); // zero vector of 3D space (0, 0, 0)
//! let v = Vector3::ones(); // one vector of 3D space (1, 1, 1)
//! ```
//!
//! ## Short constructors
//! To construct a vector a matrix, you can use short constructors :
//! ```
//! use geomath::vector::vec3;
//! use geomath::matrix::mat2;
//! let u = vec3(2., 3., 5.);
//! let m = mat2(1., 2., 3., 4.); // ordered by rows, from left to right
//! ```
//!
//! ## Metric space features
//! The metric space fetuares for vectors and matrices can be either computed using methods or operators :
//! ```
//! use geomath::vector;
//! use geomath::prelude::*;
//! let u = vector::consts::EX_3;
//! let v = vector::consts::N_EZ_3;
//! assert_eq!(u % v, u.distance(&v));
//! assert_eq!(u | v, u.dot(&v));
//! assert_eq!(!u, u.magnitude());
//! ```
/// Vector structures and documentation
/// Matrix structures and documentation
/// Point structures and documentation
/// Trajectory structures and documentation
/// Prelude traits and documentation
/// Macros mentioned bellow