2017-02-13 01:17:09 +08:00
|
|
|
|
/*!
|
|
|
|
|
# nalgebra
|
|
|
|
|
|
|
|
|
|
**nalgebra** is a linear algebra library written for Rust targeting:
|
|
|
|
|
|
|
|
|
|
* General-purpose linear algebra (still lacks a lot of features…)
|
|
|
|
|
* Real time computer graphics.
|
|
|
|
|
* Real time computer physics.
|
|
|
|
|
|
|
|
|
|
## Using **nalgebra**
|
|
|
|
|
You will need the last stable build of the [rust compiler](http://www.rust-lang.org)
|
|
|
|
|
and the official package manager: [cargo](https://github.com/rust-lang/cargo).
|
|
|
|
|
|
|
|
|
|
Simply add the following to your `Cargo.toml` file:
|
|
|
|
|
|
|
|
|
|
```.ignore
|
|
|
|
|
[dependencies]
|
2018-07-20 22:35:57 +08:00
|
|
|
|
nalgebra = "0.16"
|
2017-02-13 01:17:09 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Most useful functionalities of **nalgebra** are grouped in the root module `nalgebra::`.
|
|
|
|
|
|
|
|
|
|
However, the recommended way to use **nalgebra** is to import types and traits
|
|
|
|
|
explicitly, and call free-functions using the `na::` prefix:
|
|
|
|
|
|
|
|
|
|
```.rust
|
|
|
|
|
#[macro_use]
|
|
|
|
|
extern crate approx; // For the macro relative_eq!
|
|
|
|
|
extern crate nalgebra as na;
|
|
|
|
|
use na::{Vector3, Rotation3};
|
|
|
|
|
|
|
|
|
|
fn main() {
|
|
|
|
|
let axis = Vector3::x_axis();
|
|
|
|
|
let angle = 1.57;
|
|
|
|
|
let b = Rotation3::from_axis_angle(&axis, angle);
|
|
|
|
|
|
|
|
|
|
relative_eq!(b.axis().unwrap(), axis);
|
|
|
|
|
relative_eq!(b.angle(), angle);
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
|
**nalgebra** is meant to be a general-purpose, low-dimensional, linear algebra library, with
|
|
|
|
|
an optimized set of tools for computer graphics and physics. Those features include:
|
|
|
|
|
|
|
|
|
|
* A single parametrizable type `Matrix` for vectors, (square or rectangular) matrices, and slices
|
|
|
|
|
with dimensions known either at compile-time (using type-level integers) or at runtime.
|
|
|
|
|
* Matrices and vectors with compile-time sizes are statically allocated while dynamic ones are
|
|
|
|
|
allocated on the heap.
|
|
|
|
|
* Convenient aliases for low-dimensional matrices and vectors: `Vector1` to `Vector6` and
|
2017-08-14 01:53:04 +08:00
|
|
|
|
`Matrix1x1` to `Matrix6x6`, including rectangular matrices like `Matrix2x5`.
|
2017-02-13 01:17:09 +08:00
|
|
|
|
* Points sizes known at compile time, and convenience aliases: `Point1` to `Point6`.
|
|
|
|
|
* Translation (seen as a transformation that composes by multiplication): `Translation2`,
|
|
|
|
|
`Translation3`.
|
|
|
|
|
* Rotation matrices: `Rotation2`, `Rotation3`.
|
|
|
|
|
* Quaternions: `Quaternion`, `UnitQuaternion` (for 3D rotation).
|
|
|
|
|
* Unit complex numbers can be used for 2D rotation: `UnitComplex`.
|
|
|
|
|
* Algebraic entities with a norm equal to one: `Unit<T>`, e.g., `Unit<Vector3<f32>>`.
|
|
|
|
|
* Isometries (translation ⨯ rotation): `Isometry2`, `Isometry3`
|
|
|
|
|
* Similarity transformations (translation ⨯ rotation ⨯ uniform scale): `Similarity2`, `Similarity3`.
|
|
|
|
|
* Affine transformations stored as an homogeneous matrix: `Affine2`, `Affine3`.
|
|
|
|
|
* Projective (i.e. invertible) transformations stored as an homogeneous matrix: `Projective2`,
|
|
|
|
|
`Projective3`.
|
|
|
|
|
* General transformations that does not have to be invertible, stored as an homogeneous matrix:
|
|
|
|
|
`Transform2`, `Transform3`.
|
|
|
|
|
* 3D projections for computer graphics: `Perspective3`, `Orthographic3`.
|
2017-08-14 01:53:04 +08:00
|
|
|
|
* Matrix factorizations: `Cholesky`, `QR`, `LU`, `FullPivLU`, `SVD`, `RealSchur`, `Hessenberg`, `SymmetricEigen`.
|
|
|
|
|
* Insertion and removal of rows of columns of a matrix.
|
2017-02-16 05:04:34 +08:00
|
|
|
|
* Implements traits from the [alga](https://crates.io/crates/alga) crate for
|
2017-02-13 01:17:09 +08:00
|
|
|
|
generic programming.
|
|
|
|
|
*/
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
// #![feature(plugin)]
|
|
|
|
|
//
|
|
|
|
|
// #![plugin(clippy)]
|
2017-02-13 01:17:09 +08:00
|
|
|
|
|
|
|
|
|
#![deny(non_camel_case_types)]
|
|
|
|
|
#![deny(unused_parens)]
|
|
|
|
|
#![deny(non_upper_case_globals)]
|
|
|
|
|
#![deny(unused_qualifications)]
|
|
|
|
|
#![deny(unused_results)]
|
2018-02-02 19:26:40 +08:00
|
|
|
|
#![deny(missing_docs)]
|
2018-05-07 05:28:34 +08:00
|
|
|
|
#![warn(incoherent_fundamental_impls)]
|
2018-10-16 17:46:13 +08:00
|
|
|
|
#![doc(html_favicon_url = "http://nalgebra.org/img/favicon.ico",
|
|
|
|
|
html_root_url = "http://nalgebra.org/rustdoc")]
|
2018-05-19 23:15:15 +08:00
|
|
|
|
#![cfg_attr(not(feature = "std"), no_std)]
|
2018-05-24 23:17:34 +08:00
|
|
|
|
#![cfg_attr(all(feature = "alloc", not(feature = "std")), feature(alloc))]
|
2016-08-30 03:16:15 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
#[cfg(feature = "arbitrary")]
|
|
|
|
|
extern crate quickcheck;
|
2017-08-14 20:32:02 +08:00
|
|
|
|
|
2017-02-16 05:04:34 +08:00
|
|
|
|
#[cfg(feature = "serde")]
|
2017-02-13 01:17:09 +08:00
|
|
|
|
extern crate serde;
|
2017-02-16 05:04:34 +08:00
|
|
|
|
#[cfg(feature = "serde")]
|
2017-02-13 01:17:09 +08:00
|
|
|
|
#[macro_use]
|
|
|
|
|
extern crate serde_derive;
|
2017-08-14 20:32:02 +08:00
|
|
|
|
|
2017-09-18 20:31:17 +08:00
|
|
|
|
#[cfg(feature = "abomonation-serialize")]
|
2017-08-14 18:07:06 +08:00
|
|
|
|
extern crate abomonation;
|
2017-08-14 20:32:02 +08:00
|
|
|
|
|
2017-07-25 23:04:12 +08:00
|
|
|
|
#[cfg(feature = "mint")]
|
|
|
|
|
extern crate mint;
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
#[macro_use]
|
|
|
|
|
extern crate approx;
|
|
|
|
|
extern crate generic_array;
|
2018-05-19 23:15:15 +08:00
|
|
|
|
#[cfg(feature = "std")]
|
2017-08-03 01:37:44 +08:00
|
|
|
|
extern crate matrixmultiply;
|
2018-02-02 19:26:35 +08:00
|
|
|
|
extern crate num_complex;
|
|
|
|
|
extern crate num_traits as num;
|
|
|
|
|
extern crate rand;
|
|
|
|
|
extern crate typenum;
|
2016-08-30 03:16:15 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
extern crate alga;
|
2016-08-30 03:16:15 +08:00
|
|
|
|
|
2018-05-24 23:17:34 +08:00
|
|
|
|
#[cfg(all(feature = "alloc", not(feature = "std")))]
|
|
|
|
|
extern crate alloc;
|
|
|
|
|
|
2018-05-19 23:15:15 +08:00
|
|
|
|
#[cfg(not(feature = "std"))]
|
|
|
|
|
extern crate core as std;
|
|
|
|
|
|
|
|
|
|
pub mod base;
|
2017-08-03 01:37:44 +08:00
|
|
|
|
#[cfg(feature = "debug")]
|
|
|
|
|
pub mod debug;
|
2018-04-27 13:53:08 +08:00
|
|
|
|
pub mod geometry;
|
|
|
|
|
pub mod linalg;
|
2013-10-06 22:54:09 +08:00
|
|
|
|
|
2018-05-19 23:15:15 +08:00
|
|
|
|
#[cfg(feature = "std")]
|
|
|
|
|
#[deprecated(
|
2018-09-26 11:50:41 +08:00
|
|
|
|
note = "The 'core' module is being renamed to 'base' to avoid conflicts with the 'core' crate."
|
2018-05-19 23:15:15 +08:00
|
|
|
|
)]
|
|
|
|
|
pub use base as core;
|
|
|
|
|
pub use base::*;
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub use geometry::*;
|
2018-04-27 13:53:08 +08:00
|
|
|
|
pub use linalg::*;
|
2013-10-06 22:54:09 +08:00
|
|
|
|
|
2018-02-02 19:26:35 +08:00
|
|
|
|
use std::cmp::{self, Ordering, PartialOrd};
|
2013-10-14 16:22:32 +08:00
|
|
|
|
|
2018-05-19 23:15:15 +08:00
|
|
|
|
use alga::general::{
|
|
|
|
|
Additive, AdditiveGroup, Identity, Inverse, JoinSemilattice, Lattice, MeetSemilattice,
|
|
|
|
|
Multiplicative, SupersetOf,
|
|
|
|
|
};
|
2016-12-05 05:44:42 +08:00
|
|
|
|
use alga::linear::SquareMatrix as AlgaSquareMatrix;
|
2018-02-02 19:26:35 +08:00
|
|
|
|
use alga::linear::{EuclideanSpace, FiniteDimVectorSpace, InnerSpace, NormedSpace};
|
2018-04-27 13:53:08 +08:00
|
|
|
|
use num::Signed;
|
2017-02-13 01:17:09 +08:00
|
|
|
|
|
2018-02-02 19:26:35 +08:00
|
|
|
|
pub use alga::general::{Id, Real};
|
2017-02-13 01:17:09 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/*
|
|
|
|
|
*
|
|
|
|
|
* Multiplicative identity.
|
|
|
|
|
*
|
|
|
|
|
*/
|
|
|
|
|
/// Gets the ubiquitous multiplicative identity element.
|
|
|
|
|
///
|
|
|
|
|
/// Same as `Id::new()`.
|
|
|
|
|
#[inline]
|
|
|
|
|
pub fn id() -> Id {
|
|
|
|
|
Id::new()
|
|
|
|
|
}
|
2013-10-14 16:22:32 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Gets the multiplicative identity element.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`origin`](../nalgebra/fn.origin.html)
|
|
|
|
|
/// * [`zero`](fn.zero.html)
|
2016-12-05 05:44:42 +08:00
|
|
|
|
#[inline]
|
|
|
|
|
pub fn one<T: Identity<Multiplicative>>() -> T {
|
|
|
|
|
T::identity()
|
|
|
|
|
}
|
2013-10-14 16:22:32 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Gets the additive identity element.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`one`](fn.one.html)
|
|
|
|
|
/// * [`origin`](../nalgebra/fn.origin.html)
|
2016-12-05 05:44:42 +08:00
|
|
|
|
#[inline]
|
|
|
|
|
pub fn zero<T: Identity<Additive>>() -> T {
|
|
|
|
|
T::identity()
|
2013-10-14 16:22:32 +08:00
|
|
|
|
}
|
2013-10-06 22:54:09 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Gets the origin of the given point.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`one`](fn.one.html)
|
|
|
|
|
/// * [`zero`](fn.zero.html)
|
2016-12-05 05:44:42 +08:00
|
|
|
|
#[inline]
|
|
|
|
|
pub fn origin<P: EuclideanSpace>() -> P {
|
|
|
|
|
P::origin()
|
|
|
|
|
}
|
2016-08-30 03:16:15 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/*
|
|
|
|
|
*
|
|
|
|
|
* Dimension
|
|
|
|
|
*
|
|
|
|
|
*/
|
|
|
|
|
/// The dimension of the given algebraic entity seen as a vector space.
|
|
|
|
|
#[inline]
|
|
|
|
|
pub fn dimension<V: FiniteDimVectorSpace>() -> usize {
|
|
|
|
|
V::dimension()
|
|
|
|
|
}
|
2013-10-06 22:54:09 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/*
|
|
|
|
|
*
|
|
|
|
|
* Ordering
|
|
|
|
|
*
|
|
|
|
|
*/
|
|
|
|
|
// XXX: this is very naive and could probably be optimized for specific types.
|
|
|
|
|
// XXX: also, we might just want to use divisions, but assuming `val` is usually not far from `min`
|
|
|
|
|
// or `max`, would it still be more efficient?
|
|
|
|
|
/// Wraps `val` into the range `[min, max]` using modular arithmetics.
|
|
|
|
|
///
|
|
|
|
|
/// The range must not be empty.
|
|
|
|
|
#[inline]
|
|
|
|
|
pub fn wrap<T>(mut val: T, min: T, max: T) -> T
|
2018-10-22 13:00:10 +08:00
|
|
|
|
where T: Copy + PartialOrd + AdditiveGroup {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
assert!(min < max, "Invalid wrapping bounds.");
|
|
|
|
|
let width = max - min;
|
2013-05-15 05:08:29 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
if val < min {
|
|
|
|
|
val += width;
|
2016-03-25 02:37:56 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
while val < min {
|
|
|
|
|
val += width
|
|
|
|
|
}
|
2013-05-15 05:08:29 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
val
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else if val > max {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
val -= width;
|
2015-01-10 08:36:13 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
while val > max {
|
|
|
|
|
val -= width
|
|
|
|
|
}
|
2013-05-15 05:08:29 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
val
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
val
|
|
|
|
|
}
|
|
|
|
|
}
|
2013-09-22 16:58:21 +08:00
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Returns a reference to the input value clamped to the interval `[min, max]`.
|
|
|
|
|
///
|
|
|
|
|
/// In particular:
|
|
|
|
|
/// * If `min < val < max`, this returns `val`.
|
2018-09-24 12:48:42 +08:00
|
|
|
|
/// * If `val <= min`, this returns `min`.
|
|
|
|
|
/// * If `val >= max`, this returns `max`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2014-10-22 01:43:25 +08:00
|
|
|
|
pub fn clamp<T: PartialOrd>(val: T, min: T, max: T) -> T {
|
2014-09-29 01:20:22 +08:00
|
|
|
|
if val > min {
|
|
|
|
|
if val < max {
|
|
|
|
|
val
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2014-09-29 01:20:22 +08:00
|
|
|
|
max
|
|
|
|
|
}
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2014-09-29 01:20:22 +08:00
|
|
|
|
min
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Same as `cmp::max`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2014-09-29 01:20:22 +08:00
|
|
|
|
pub fn max<T: Ord>(a: T, b: T) -> T {
|
|
|
|
|
cmp::max(a, b)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Same as `cmp::min`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2014-09-29 01:20:22 +08:00
|
|
|
|
pub fn min<T: Ord>(a: T, b: T) -> T {
|
|
|
|
|
cmp::min(a, b)
|
|
|
|
|
}
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// The absolute value of `a`.
|
2018-12-11 04:54:54 +08:00
|
|
|
|
///
|
|
|
|
|
/// Deprecated: Use [Matrix::abs] or [Real::abs] instead.
|
|
|
|
|
#[deprecated(note = "use `Matrix::abs` or `Real::abs` instead")]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
#[inline]
|
|
|
|
|
pub fn abs<T: Signed>(a: &T) -> T {
|
|
|
|
|
a.abs()
|
|
|
|
|
}
|
|
|
|
|
|
2014-09-29 01:20:22 +08:00
|
|
|
|
/// Returns the infimum of `a` and `b`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn inf<T: MeetSemilattice>(a: &T, b: &T) -> T {
|
|
|
|
|
a.meet(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Returns the supremum of `a` and `b`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn sup<T: JoinSemilattice>(a: &T, b: &T) -> T {
|
|
|
|
|
a.join(b)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Returns simultaneously the infimum and supremum of `a` and `b`.
|
|
|
|
|
#[inline]
|
|
|
|
|
pub fn inf_sup<T: Lattice>(a: &T, b: &T) -> (T, T) {
|
|
|
|
|
a.meet_join(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Compare `a` and `b` using a partial ordering relation.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_cmp<T: PartialOrd>(a: &T, b: &T) -> Option<Ordering> {
|
|
|
|
|
a.partial_cmp(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Returns `true` iff `a` and `b` are comparable and `a < b`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_lt<T: PartialOrd>(a: &T, b: &T) -> bool {
|
|
|
|
|
a.lt(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Returns `true` iff `a` and `b` are comparable and `a <= b`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_le<T: PartialOrd>(a: &T, b: &T) -> bool {
|
|
|
|
|
a.le(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Returns `true` iff `a` and `b` are comparable and `a > b`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_gt<T: PartialOrd>(a: &T, b: &T) -> bool {
|
|
|
|
|
a.gt(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Returns `true` iff `a` and `b` are comparable and `a >= b`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_ge<T: PartialOrd>(a: &T, b: &T) -> bool {
|
|
|
|
|
a.ge(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Return the minimum of `a` and `b` if they are comparable.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_min<'a, T: PartialOrd>(a: &'a T, b: &'a T) -> Option<&'a T> {
|
|
|
|
|
if let Some(ord) = a.partial_cmp(b) {
|
|
|
|
|
match ord {
|
|
|
|
|
Ordering::Greater => Some(b),
|
2018-02-02 19:26:35 +08:00
|
|
|
|
_ => Some(a),
|
2016-12-05 05:44:42 +08:00
|
|
|
|
}
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
None
|
|
|
|
|
}
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Return the maximum of `a` and `b` if they are comparable.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_max<'a, T: PartialOrd>(a: &'a T, b: &'a T) -> Option<&'a T> {
|
|
|
|
|
if let Some(ord) = a.partial_cmp(b) {
|
|
|
|
|
match ord {
|
|
|
|
|
Ordering::Less => Some(b),
|
2018-02-02 19:26:35 +08:00
|
|
|
|
_ => Some(a),
|
2016-12-05 05:44:42 +08:00
|
|
|
|
}
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
None
|
|
|
|
|
}
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// Clamp `value` between `min` and `max`. Returns `None` if `value` is not comparable to
|
|
|
|
|
/// `min` or `max`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_clamp<'a, T: PartialOrd>(value: &'a T, min: &'a T, max: &'a T) -> Option<&'a T> {
|
|
|
|
|
if let (Some(cmp_min), Some(cmp_max)) = (value.partial_cmp(min), value.partial_cmp(max)) {
|
|
|
|
|
if cmp_min == Ordering::Less {
|
|
|
|
|
Some(min)
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else if cmp_max == Ordering::Greater {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
Some(max)
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
Some(value)
|
|
|
|
|
}
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
None
|
|
|
|
|
}
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Sorts two values in increasing order using a partial ordering.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn partial_sort2<'a, T: PartialOrd>(a: &'a T, b: &'a T) -> Option<(&'a T, &'a T)> {
|
|
|
|
|
if let Some(ord) = a.partial_cmp(b) {
|
|
|
|
|
match ord {
|
|
|
|
|
Ordering::Less => Some((a, b)),
|
2018-02-02 19:26:35 +08:00
|
|
|
|
_ => Some((b, a)),
|
2016-12-05 05:44:42 +08:00
|
|
|
|
}
|
2018-02-02 19:26:35 +08:00
|
|
|
|
} else {
|
2016-12-05 05:44:42 +08:00
|
|
|
|
None
|
|
|
|
|
}
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/*
|
2016-12-05 05:44:42 +08:00
|
|
|
|
* Inverse
|
2014-09-29 01:20:22 +08:00
|
|
|
|
*/
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Tries to gets an inverted copy of a square matrix.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`inverse`](fn.inverse.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn try_inverse<M: AlgaSquareMatrix>(m: &M) -> Option<M> {
|
|
|
|
|
m.try_inverse()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2017-02-13 01:17:09 +08:00
|
|
|
|
/// Computes the multiplicative inverse of an (always invertible) algebraic entity.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`try_inverse`](fn.try_inverse.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn inverse<M: Inverse<Multiplicative>>(m: &M) -> M {
|
|
|
|
|
m.inverse()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/*
|
2016-12-05 05:44:42 +08:00
|
|
|
|
* Inner vector space
|
2014-09-29 01:20:22 +08:00
|
|
|
|
*/
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Computes the dot product of two vectors.
|
2018-12-11 05:10:00 +08:00
|
|
|
|
///
|
|
|
|
|
/// ## Deprecated
|
|
|
|
|
/// Use these methods instead:
|
|
|
|
|
/// - [Matrix::dot]
|
|
|
|
|
/// - [Quaternion::dot]
|
|
|
|
|
///
|
|
|
|
|
/// Or, use [FiniteDimVectorSpace::dot](https://docs.rs/alga/0.7.2/alga/linear/trait.FiniteDimVectorSpace.html#tymethod.dot).
|
|
|
|
|
#[deprecated(note = "use `Matrix::dot` or `Quaternion::dot` instead")]
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn dot<V: FiniteDimVectorSpace>(a: &V, b: &V) -> V::Field {
|
|
|
|
|
a.dot(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2017-02-13 01:17:09 +08:00
|
|
|
|
/// Computes the smallest angle between two vectors.
|
2018-12-11 05:13:36 +08:00
|
|
|
|
///
|
|
|
|
|
/// ## Deprecated
|
|
|
|
|
/// Use [Matrix::angle] instead.
|
|
|
|
|
///
|
|
|
|
|
/// Or, use [InnerSpace::angle](https://docs.rs/alga/0.7.2/alga/linear/trait.InnerSpace.html#method.angle).
|
|
|
|
|
#[deprecated(note = "use `Matrix::angle` instead")]
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn angle<V: InnerSpace>(a: &V, b: &V) -> V::Real {
|
|
|
|
|
a.angle(b)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/*
|
2016-12-05 05:44:42 +08:00
|
|
|
|
* Normed space
|
2014-09-29 01:20:22 +08:00
|
|
|
|
*/
|
|
|
|
|
|
2018-10-08 22:57:11 +08:00
|
|
|
|
/// Computes the L2 (Euclidean) norm of a vector.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`magnitude`](fn.magnitude.html)
|
|
|
|
|
/// * [`magnitude_squared`](fn.magnitude_squared.html)
|
|
|
|
|
/// * [`norm_squared`](fn.norm_squared.html)
|
2018-12-11 05:19:59 +08:00
|
|
|
|
///
|
|
|
|
|
/// # Deprecated
|
|
|
|
|
/// Use these methods instead:
|
2018-12-11 05:24:08 +08:00
|
|
|
|
/// * [Matrix::norm]
|
|
|
|
|
/// * [Quaternion::norm]
|
2018-12-11 05:19:59 +08:00
|
|
|
|
///
|
|
|
|
|
/// Or, use [NormedSpace::norm](https://docs.rs/alga/0.7.2/alga/linear/trait.NormedSpace.html#tymethod.norm).
|
|
|
|
|
#[deprecated(note = "use `Matrix::norm` or `Quaternion::norm` instead")]
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn norm<V: NormedSpace>(v: &V) -> V::Field {
|
|
|
|
|
v.norm()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2018-10-08 22:57:11 +08:00
|
|
|
|
/// Computes the squared L2 (Euclidean) norm of the vector `v`.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`magnitude`](fn.magnitude.html)
|
|
|
|
|
/// * [`magnitude_squared`](fn.magnitude_squared.html)
|
|
|
|
|
/// * [`norm`](fn.norm.html)
|
2018-12-11 05:24:08 +08:00
|
|
|
|
///
|
|
|
|
|
/// # Deprecated
|
|
|
|
|
/// Use these methods instead:
|
|
|
|
|
/// * [Matrix::norm_squared]
|
|
|
|
|
/// * [Quaternion::norm_squared]
|
|
|
|
|
///
|
|
|
|
|
/// Or, use [NormedSpace::norm_squared](https://docs.rs/alga/0.7.2/alga/linear/trait.NormedSpace.html#tymethod.norm_squared).
|
|
|
|
|
#[deprecated(note = "use `Matrix::norm_squared` or `Quaternion::norm_squared` instead")]
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn norm_squared<V: NormedSpace>(v: &V) -> V::Field {
|
|
|
|
|
v.norm_squared()
|
2013-05-19 01:04:03 +08:00
|
|
|
|
}
|
2014-09-29 01:20:22 +08:00
|
|
|
|
|
2018-09-26 17:39:30 +08:00
|
|
|
|
/// A synonym for [`norm`](fn.norm.html), aka length.
|
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`magnitude_squared`](fn.magnitude_squared.html)
|
|
|
|
|
/// * [`norm`](fn.norm.html)
|
|
|
|
|
/// * [`norm_squared`](fn.norm_squared.html)
|
2018-12-11 05:25:13 +08:00
|
|
|
|
///
|
|
|
|
|
/// # Deprecated
|
|
|
|
|
/// Use these methods instead:
|
|
|
|
|
/// * [Matrix::magnitude]
|
|
|
|
|
/// * [Quaternion::magnitude]
|
|
|
|
|
///
|
|
|
|
|
/// Or, use [NormedSpace::norm](https://docs.rs/alga/0.7.2/alga/linear/trait.NormedSpace.html#tymethod.norm).
|
|
|
|
|
#[deprecated(note = "use `Matrix::magnitude` or `Quaternion::magnitude` instead")]
|
2018-09-21 23:25:43 +08:00
|
|
|
|
#[inline]
|
|
|
|
|
pub fn magnitude<V: NormedSpace>(v: &V) -> V::Field {
|
|
|
|
|
v.norm()
|
|
|
|
|
}
|
|
|
|
|
|
2018-09-26 17:39:30 +08:00
|
|
|
|
/// A synonym for [`norm_squared`](fn.norm_squared.html),
|
|
|
|
|
/// aka length squared.
|
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [`magnitude`](fn.magnitude.html)
|
|
|
|
|
/// * [`norm`](fn.norm.html)
|
|
|
|
|
/// * [`norm_squared`](fn.norm_squared.html)
|
2018-12-11 05:26:43 +08:00
|
|
|
|
///
|
|
|
|
|
/// # Deprecated
|
|
|
|
|
/// Use these methods instead:
|
|
|
|
|
/// * [Matrix::magnitude_squared]
|
|
|
|
|
/// * [Quaternion::magnitude_squared]
|
|
|
|
|
///
|
|
|
|
|
/// Or, use [NormedSpace::norm_squared](https://docs.rs/alga/0.7.2/alga/linear/trait.NormedSpace.html#tymethod.norm_squared).
|
|
|
|
|
#[deprecated(note = "use `Matrix::magnitude_squared` or `Quaternion::magnitude_squared` instead")]
|
2018-09-21 23:25:43 +08:00
|
|
|
|
#[inline]
|
|
|
|
|
pub fn magnitude_squared<V: NormedSpace>(v: &V) -> V::Field {
|
|
|
|
|
v.norm_squared()
|
|
|
|
|
}
|
|
|
|
|
|
2017-02-13 01:17:09 +08:00
|
|
|
|
/// Computes the normalized version of the vector `v`.
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn normalize<V: NormedSpace>(v: &V) -> V {
|
|
|
|
|
v.normalize()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2017-02-13 01:17:09 +08:00
|
|
|
|
/// Computes the normalized version of the vector `v` or returns `None` if its norm is smaller than `min_norm`.
|
2016-08-13 03:46:40 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn try_normalize<V: NormedSpace>(v: &V, min_norm: V::Field) -> Option<V> {
|
|
|
|
|
v.try_normalize(min_norm)
|
2016-08-13 03:46:40 +08:00
|
|
|
|
}
|
|
|
|
|
|
2014-09-29 01:20:22 +08:00
|
|
|
|
/*
|
2016-12-05 05:44:42 +08:00
|
|
|
|
*
|
|
|
|
|
* Point operations.
|
|
|
|
|
*
|
2014-09-29 01:20:22 +08:00
|
|
|
|
*/
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// The center of two points.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [distance](fn.distance.html)
|
|
|
|
|
/// * [distance_squared](fn.distance_squared.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn center<P: EuclideanSpace>(p1: &P, p2: &P) -> P {
|
|
|
|
|
P::from_coordinates((p1.coordinates() + p2.coordinates()) * convert(0.5))
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// The distance between two points.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [center](fn.center.html)
|
|
|
|
|
/// * [distance_squared](fn.distance_squared.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn distance<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
|
|
|
|
|
(p2.coordinates() - p1.coordinates()).norm()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// The squared distance between two points.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [center](fn.center.html)
|
|
|
|
|
/// * [distance](fn.distance.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn distance_squared<P: EuclideanSpace>(p1: &P, p2: &P) -> P::Real {
|
|
|
|
|
(p2.coordinates() - p1.coordinates()).norm_squared()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/*
|
2016-12-05 05:44:42 +08:00
|
|
|
|
* Cast
|
2014-09-29 01:20:22 +08:00
|
|
|
|
*/
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Converts an object from one type to an equivalent or more general one.
|
2017-07-29 02:12:07 +08:00
|
|
|
|
///
|
2018-09-26 17:39:30 +08:00
|
|
|
|
/// See also [`try_convert`](fn.try_convert.html) for conversion to more specific types.
|
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [convert_ref](fn.convert_ref.html)
|
|
|
|
|
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
|
|
|
|
|
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
|
|
|
|
|
/// * [try_convert](fn.try_convert.html)
|
|
|
|
|
/// * [try_convert_ref](fn.try_convert_ref.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn convert<From, To: SupersetOf<From>>(t: From) -> To {
|
|
|
|
|
To::from_subset(&t)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Attempts to convert an object to a more specific one.
|
2017-07-29 02:12:07 +08:00
|
|
|
|
///
|
2018-09-26 17:39:30 +08:00
|
|
|
|
/// See also [`convert`](fn.convert.html) for conversion to more general types.
|
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [convert](fn.convert.html)
|
|
|
|
|
/// * [convert_ref](fn.convert_ref.html)
|
|
|
|
|
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
|
|
|
|
|
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
|
|
|
|
|
/// * [try_convert_ref](fn.try_convert_ref.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn try_convert<From: SupersetOf<To>, To>(t: From) -> Option<To> {
|
|
|
|
|
t.to_subset()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2018-09-26 17:39:30 +08:00
|
|
|
|
/// Indicates if [`try_convert`](fn.try_convert.html) will succeed without
|
|
|
|
|
/// actually performing the conversion.
|
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [convert](fn.convert.html)
|
|
|
|
|
/// * [convert_ref](fn.convert_ref.html)
|
|
|
|
|
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
|
|
|
|
|
/// * [try_convert](fn.try_convert.html)
|
|
|
|
|
/// * [try_convert_ref](fn.try_convert_ref.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn is_convertible<From: SupersetOf<To>, To>(t: &From) -> bool {
|
|
|
|
|
t.is_in_subset()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2018-09-26 17:39:30 +08:00
|
|
|
|
/// Use with care! Same as [`try_convert`](fn.try_convert.html) but
|
|
|
|
|
/// without any property checks.
|
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [convert](fn.convert.html)
|
|
|
|
|
/// * [convert_ref](fn.convert_ref.html)
|
|
|
|
|
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
|
|
|
|
|
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
|
|
|
|
|
/// * [try_convert](fn.try_convert.html)
|
|
|
|
|
/// * [try_convert_ref](fn.try_convert_ref.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub unsafe fn convert_unchecked<From: SupersetOf<To>, To>(t: From) -> To {
|
|
|
|
|
t.to_subset_unchecked()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Converts an object from one type to an equivalent or more general one.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [convert](fn.convert.html)
|
|
|
|
|
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
|
|
|
|
|
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
|
|
|
|
|
/// * [try_convert](fn.try_convert.html)
|
|
|
|
|
/// * [try_convert_ref](fn.try_convert_ref.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn convert_ref<From, To: SupersetOf<From>>(t: &From) -> To {
|
|
|
|
|
To::from_subset(t)
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2016-12-05 05:44:42 +08:00
|
|
|
|
/// Attempts to convert an object to a more specific one.
|
2018-09-26 17:39:30 +08:00
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [convert](fn.convert.html)
|
|
|
|
|
/// * [convert_ref](fn.convert_ref.html)
|
|
|
|
|
/// * [convert_ref_unchecked](fn.convert_ref_unchecked.html)
|
|
|
|
|
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
|
|
|
|
|
/// * [try_convert](fn.try_convert.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub fn try_convert_ref<From: SupersetOf<To>, To>(t: &From) -> Option<To> {
|
|
|
|
|
t.to_subset()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2018-09-26 17:39:30 +08:00
|
|
|
|
/// Use with care! Same as [`try_convert`](fn.try_convert.html) but
|
|
|
|
|
/// without any property checks.
|
|
|
|
|
///
|
|
|
|
|
/// # See also:
|
|
|
|
|
///
|
|
|
|
|
/// * [convert](fn.convert.html)
|
|
|
|
|
/// * [convert_ref](fn.convert_ref.html)
|
|
|
|
|
/// * [is_convertible](../nalgebra/fn.is_convertible.html)
|
|
|
|
|
/// * [try_convert](fn.try_convert.html)
|
|
|
|
|
/// * [try_convert_ref](fn.try_convert_ref.html)
|
2016-05-06 21:08:06 +08:00
|
|
|
|
#[inline]
|
2016-12-05 05:44:42 +08:00
|
|
|
|
pub unsafe fn convert_ref_unchecked<From: SupersetOf<To>, To>(t: &From) -> To {
|
|
|
|
|
t.to_subset_unchecked()
|
2014-09-29 01:20:22 +08:00
|
|
|
|
}
|