Crate nalgebra [] [src]

nalgebra

nalgebra is a low-dimensional 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.

An on-line version of this documentation is available here.

Using nalgebra

All the functionality of nalgebra is grouped in one place: the root module nalgebra::. This module re-exports everything and includes free functions for all traits methods doing out-of-place modifications.

  • You can import the whole prelude using:
use nalgebra::*;

The preferred way to use nalgebra is to import types and traits explicitly, and call free-functions using the na:: prefix:

extern crate nalgebra as na;
use na::{Vec3, Rot3, Rotation};

fn main() {
    let     a = Vec3::new(1.0f64, 1.0, 1.0);
    let mut b = Rot3::new(na::zero());

    b.append_rotation_mut(&a);

    assert!(na::approx_eq(&na::rotation(&b), &a));
}

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:

  • Vectors with static sizes: Vec0, Vec1, Vec2, Vec3, Vec4, Vec5, Vec6.
  • Points with static sizes: Pnt0, Pnt1, Pnt2, Pnt3, Pnt4, Pnt5, Pnt6.
  • Square matrices with static sizes: Mat1, Mat2, Mat3, Mat4, Mat5, Mat6.
  • Rotation matrices: Rot2, Rot3, Rot4.
  • Quaternions: Quat, UnitQuat.
  • Isometries: Iso2, Iso3, Iso4.
  • 3D projections for computer graphics: Persp3, PerspMat3, Ortho3, OrthoMat3.
  • Dynamically sized vector: DVec.
  • Dynamically sized (square or rectangular) matrix: DMat.
  • A few methods for data analysis: Cov, Mean.
  • Almost one trait per functionality: useful for generic programming.
  • Operator overloading using multidispatch.

nalgebra in use

Here are some projects using nalgebra. Feel free to add your project to this list if you happen to use nalgebra!

  • nphysics: a real-time physics engine.
  • ncollide: a collision detection library.
  • kiss3d: a minimalistic graphics engine.
  • nrays: a ray tracer.

Macros

assert_approx_eq!

Asserts approximate equality of two values with the ApproxEq trait.

assert_approx_eq_eps!

Asserts approximate equality within a given tolerance of two values with the ApproxEq trait.

assert_approx_eq_ulps!

Asserts approximate equality within a given tolerance of two values with the ApproxEq trait, with tolerance specified in ULPs.

Structs

DMat

Matrix with dimensions unknown at compile-time.

DVec

Heap allocated, dynamically sized vector.

DVec1

Stack-allocated, dynamically sized vector with a maximum size of 1.

DVec2

Stack-allocated, dynamically sized vector with a maximum size of 2.

DVec3

Stack-allocated, dynamically sized vector with a maximum size of 3.

DVec4

Stack-allocated, dynamically sized vector with a maximum size of 4.

DVec5

Stack-allocated, dynamically sized vector with a maximum size of 5.

DVec6

Stack-allocated, dynamically sized vector with a maximum size of 6.

Identity

Special identity matrix. All its operation are no-ops.

Iso2

Two dimensional isometry.

Iso3

Three dimensional isometry.

Iso4

Four dimensional isometry.

Mat1

Square matrix of dimension 1.

Mat2

Square matrix of dimension 2.

Mat3

Square matrix of dimension 3.

Mat4

Square matrix of dimension 4.

Mat5

Square matrix of dimension 5.

Mat6

Square matrix of dimension 6.

Ortho3

A 3D orthographic projection stored without any matrix.

OrthoMat3

A 3D orthographic projection stored as a 4D matrix.

Persp3

A 3D perspective projection stored without any matrix.

PerspMat3

A 3D perspective projection stored as a 4D matrix.

Pnt0

Point of dimension 0.

Pnt1

Point of dimension 1.

Pnt2

Point of dimension 2.

Pnt3

Point of dimension 3.

Pnt4

Point of dimension 4.

Pnt5

Point of dimension 5.

Pnt6

Point of dimension 6.

Quat

A quaternion.

Rot2

Two dimensional rotation matrix.

Rot3

Three dimensional rotation matrix.

Rot4

Four dimensional rotation matrix.

UnitQuat

A unit quaternion that can represent a 3D rotation.

Vec0

Vector of dimension 0.

Vec1

Vector of dimension 1.

Vec2

Vector of dimension 2.

Vec3

Vector of dimension 3.

Vec4

Vector of dimension 4.

Vec5

Vector of dimension 5.

Vec6

Vector of dimension 6.

Enums

POrdering

Result of a partial ordering.

Traits

Absolute

Trait of objects having an absolute value. This is useful if the object does not have the same type as its absolute value.

AbsoluteRotate

Composition of a rotation and an absolute value.

ApproxEq

Trait for testing approximate equality

Axpy

Trait of objects implementing the y = ax + y operation.

BaseFloat

Basic floating-point number numeric trait.

BaseNum

Basic integral numeric trait.

Basis

Traits of objects which can form a basis (typically vectors).

Bounded

Types that have maximum and minimum value.

Cast

Traits of objects which can be created from an object of type T.

Col

Trait to access columns of a matrix or vector.

ColSlice

Trait to access part of a column of a matrix

Cov

Trait for computing the covariance of a set of data.

Cross

Trait of elements having a cross product.

CrossMatrix

Trait of elements having a cross product operation which can be expressed as a matrix.

Det

Trait of objects having a determinant. Typically used by square matrices.

Diag

Trait to get the diagonal of square matrices.

Dim

Trait of objects having a spacial dimension known at compile time.

Dot

Traits of objects having a dot product.

EigenQR

Trait for computing the eigenvector and eigenvalues of a square matrix usin the QR algorithm.

Eye

Trait for constructing the identity matrix

FloatPnt

Trait of points with components implementing the BaseFloat trait.

FloatVec

Trait of vector with components implementing the BaseFloat trait.

FromHomogeneous

Traits of objects which can be build from an homogeneous coordinate form.

Indexable

This is a workaround of current Rust limitations.

Inv

Trait of objects having an inverse. Typically used to implement matrix inverse.

Iterable

This is a workaround of current Rust limitations.

IterableMut

This is a workaround of current Rust limitations.

Mat

Trait of matrices.

Mean

Trait for computing the covariance of a set of data.

Norm

Traits of objects having an euclidian norm.

NumPnt

Trait grouping most common operations on points.

NumVec

Trait grouping most common operations on vectors.

Orig

The zero element of a vector space, seen as an element of its embeding affine space.

Outer

Traits of objects having an outer product.

POrd

Pointwise ordering operations.

PntAsVec

Trait that relates a point of an affine space to a vector of the associated vector space.

Repeat

Trait for constructiong an object repeating a value.

Rotate

Trait of objects able to rotate other objects.

Rotation

Trait of object which can represent a rotation, and to which new rotations can be appended. A rotation is assumed to be an isometry without translation and without reflexion.

RotationMatrix

Trait of transformation having a rotation extractable as a rotation matrix. This can typically be implemented by quaternions to convert them to a rotation matrix.

RotationTo

Trait of object that can be rotated to be superimposed with another one of the same nature.

RotationWithTranslation

Various composition of rotation and translation.

Row

Trait to access rows of a matrix or a vector.

RowSlice

Trait to access part of a row of a matrix

Shape

The shape of an indexable object.

SquareMat

Trait implemented by square matrices.

ToHomogeneous

Traits of objects which can be put in homogeneous coordinates form.

Transform

Trait of objects able to transform other objects.

Transformation

Trait of object which represent a transformation, and to which new transformations can be appended.

Translate

Trait of objects able to translate other objects. This is typically implemented by vectors to translate points.

Translation

Trait of object which represent a translation, and to wich new translation can be appended.

Transpose

Trait of objects which can be transposed.

UniformSphereSample

Trait of vectors able to sample a unit sphere.

Functions

abs

Computes a component-wise absolute value.

absolute_rotate

Applies a rotation using the absolute values of its components.

angle_between

Computes the angle of the rotation needed to transfom a to b.

append_rotation

Applies the rotation v to a copy of m.

append_rotation_wrt_center

Rotates a copy of m by amount using m.translation() as the pivot point.

append_rotation_wrt_point

Rotates a copy of m by amount using center as the pivot point.

append_transformation

Gets a transformed copy of m.

append_translation

Applies the translation v to a copy of m.

approx_eq

Tests approximate equality.

approx_eq_eps

Tests approximate equality using a custom epsilon.

canonical_basis

Computes the canonical basis for a given dimension.

canonical_basis_element

Gets the (0-based) i-th element of the canonical basis of V.

cast

Converts an object from one type to another.

center

Returns the center of two points.

cholesky

Cholesky decomposition G of a square symmetric positive definite matrix A, such that A = G * GT

clamp

Change the input value to ensure it is on the range [min, max].

cov

Computes the covariance of a set of observations.

cross

Computes the cross product of two vectors.

cross_matrix

Given a vector, computes the matrix which, when multiplied by another vector, computes a cross product.

det

Computes the determinant of a square matrix.

diag

Gets the diagonal of a square matrix.

dim

Gets the dimension an object lives in.

dist

Returns the distance between two points.

dot

Computes the dot product of two vectors.

eigen_qr

Computes the eigenvalues and eigenvectors of a square matrix usin the QR algorithm.

from_homogeneous

Converts a matrix or vector from homogeneous coordinates.

householder_matrix

Get the householder matrix corresponding to a reflexion to the hyperplane defined by vec. It can be a reflexion contained in a subspace.

identity

Create a special identity object.

inf

Returns the infimum of a and b.

inv

Gets an inverted copy of a matrix.

inv_rotate

Applies an inverse rotation to a vector.

inv_rotation

Gets the inverse rotation applicable by m.

inv_transform

Applies an inverse transformation to a vector.

inv_transformation

Gets the inverse transformation applicable by m.

inv_translate

Applies an inverse translation to a point.

inv_translation

Gets the inverse translation applicable by m.

is_zero

Tests is a value is iqual to zero.

max

Same as cmp::max.

mean

Computes the mean of a set of observations.

min

Same as cmp::min.

new_identity

Construct the identity matrix for a given dimension

norm

Computes the L2 norm of a vector.

normalize

Gets the normalized version of a vector.

one

Create a one-valued value.

orig

Returns the trivial origin of an affine space.

orthonormal_subspace_basis

Computes the basis of the orthonormal subspace of a given vector.

outer

Computes the outer product of two vectors.

partial_clamp

Clamp value between min and max. Returns None if value is not comparable to min or max.

partial_cmp

Compare a and b using a partial ordering relation.

partial_ge

Returns true iff a and b are comparable and a >= b.

partial_gt

Returns true iff a and b are comparable and a > b.

partial_le

Returns true iff a and b are comparable and a <= b.

partial_lt

Returns true iff a and b are comparable and a < b.

partial_max

Return the maximum of a and b if they are comparable.

partial_min

Return the minimum of a and b if they are comparable.

prepend_rotation

Pre-applies the rotation v to a copy of m.

qr

QR decomposition using Householder reflections.

repeat

Create an object by repeating a value.

rotate

Applies a rotation to a vector.

rotation

Gets the rotation applicable by m.

rotation_between

Computes the rotation needed to transform a to b.

sample_sphere

Samples the unit sphere living on the dimension as the samples types.

shape

Gets the indexable range of an object.

sqdist

Returns the squared distance between two points.

sqnorm

Computes the squared L2 norm of a vector.

sup

Returns the supremum of a and b.

to_homogeneous

Converts a matrix or vector to homogeneous coordinates.

to_rot_mat

Builds a rotation matrix from r.

transform

Applies a transformation to a vector.

transformation

Gets the transformation applicable by m.

translate

Applies a translation to a point.

translation

Gets the translation applicable by m.

transpose

Gets a transposed copy of a matrix.

zero

Create a zero-valued value.