nalgebra/README.md

[![Build Status](https://travis-ci.org/sebcrozet/nalgebra.svg?branch=master)](https://travis-ci.org/sebcrozet/nalgebra)

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](http://nalgebra.org/doc/nalgebra).

## 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 performing
out-of-place operations.

* You can import the whole prelude using:

```.ignore
use nalgebra::*;
```

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

```.rust
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 predefined static sizes: `Vec1`, `Vec2`, `Vec3`, `Vec4`, `Vec5`, `Vec6`.
* Vector with a user-defined static size: `VecN` (available only with the `generic_sizes` feature).
* Points with static sizes: `Pnt1`, `Pnt2`, `Pnt3`, `Pnt4`, `Pnt5`, `Pnt6`.
* Square matrices with static sizes: `Mat1`, `Mat2`, `Mat3`, `Mat4`, `Mat5`, `Mat6 `.
* Rotation matrices: `Rot2`, `Rot3`
* Quaternions: `Quat`, `UnitQuat`.
* Isometries (translation ⨯ rotation): `Iso2`, `Iso3`
* Similarity transformations (translation ⨯ rotation ⨯ uniform scale): `Sim2`, `Sim3`.
* 3D projections for computer graphics: `Persp3`, `PerspMat3`, `Ortho3`, `OrthoMat3`.
* Dynamically sized heap-allocated vector: `DVec`.
* Dynamically sized stack-allocated vectors with a maximum size: `DVec1` to `DVec6`.
* Dynamically sized heap-allocated (square or rectangular) matrix: `DMat`.
* Linear algebra and data analysis operators: `Cov`, `Mean`, `qr`, `cholesky`.
* Almost one trait per functionality: useful for generic programming.
-												Add Travis badge to the README.

Fix #140.

											
										
										
											2015-07-12 15:35:10 +08:00
+								[![Build Status](https://travis-ci.org/sebcrozet/nalgebra.svg?branch=master)](https://travis-ci.org/sebcrozet/nalgebra)
 								nalgebra
 								========
-												Fix the example on the README.

											
										
										
											2014-01-14 16:52:18 +08:00
-												Add 3D orthogonal and perspective projection structures.

Fix #26.

											
										
										
											2014-10-13 02:21:06 +08:00
+								**nalgebra** is a low-dimensional linear algebra library written for Rust targeting:
-												Huge api change!

Everything changed, hopefully for the best.

* everything is accessible from the `na` module. It re-export
  everything and provides free functions (i-e: na::dot(a, b) instead of
  a.dot(b)) for most functionalities.
* matrix/vector adaptors (Rotmat, Transform) are replaced by plain
  types: Rot{2, 3, 4} for rotation matrices and Iso{2, 3, 4} for
  isometries (rotation + translation).  This old adaptors system was to
  hard to understand and to document.
* each file related to data structures moved to the `structs` folder.
  This makes the doc a lot more readable and make people prefer the
  `na` module instead of individual small modules.
* Because `na` exists now, the modules `structs::vec` and
  `structs::mat` dont re-export anything now.

As a side effect, this makes the documentation more readable.

											
										
										
											2013-10-06 22:54:09 +08:00
-												Add 3D orthogonal and perspective projection structures.

Fix #26.

											
										
										
											2014-10-13 02:21:06 +08:00
+								* general-purpose linear algebra (still lacks a lot of features…).
-												Huge api change!

Everything changed, hopefully for the best.

* everything is accessible from the `na` module. It re-export
  everything and provides free functions (i-e: na::dot(a, b) instead of
  a.dot(b)) for most functionalities.
* matrix/vector adaptors (Rotmat, Transform) are replaced by plain
  types: Rot{2, 3, 4} for rotation matrices and Iso{2, 3, 4} for
  isometries (rotation + translation).  This old adaptors system was to
  hard to understand and to document.
* each file related to data structures moved to the `structs` folder.
  This makes the doc a lot more readable and make people prefer the
  `na` module instead of individual small modules.
* Because `na` exists now, the modules `structs::vec` and
  `structs::mat` dont re-export anything now.

As a side effect, this makes the documentation more readable.

											
										
										
											2013-10-06 22:54:09 +08:00
+								* real time computer graphics.
 								* real time computer physics.
-												Complete the documentation.

											
										
										
											2016-03-25 02:04:01 +08:00
+								An on-line version of this documentation is available [here](http://nalgebra.org/doc/nalgebra).
-												Add a link to the on-line documentation.

											
										
										
											2013-10-08 08:10:35 +08:00
-												Add the "nalgebra in use" part to the readme.

											
										
										
											2013-10-07 01:32:31 +08:00
+								## Using **nalgebra**
-												Complete the documentation.

											
										
										
											2016-03-25 02:04:01 +08:00
+								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 performing
 								out-of-place operations.
-												Huge api change!

Everything changed, hopefully for the best.

* everything is accessible from the `na` module. It re-export
  everything and provides free functions (i-e: na::dot(a, b) instead of
  a.dot(b)) for most functionalities.
* matrix/vector adaptors (Rotmat, Transform) are replaced by plain
  types: Rot{2, 3, 4} for rotation matrices and Iso{2, 3, 4} for
  isometries (rotation + translation).  This old adaptors system was to
  hard to understand and to document.
* each file related to data structures moved to the `structs` folder.
  This makes the doc a lot more readable and make people prefer the
  `na` module instead of individual small modules.
* Because `na` exists now, the modules `structs::vec` and
  `structs::mat` dont re-export anything now.

As a side effect, this makes the documentation more readable.

											
										
										
											2013-10-06 22:54:09 +08:00
-												Fix the example on the README.

											
										
										
											2014-01-14 16:52:18 +08:00
+								* You can import the whole prelude using:
-												Huge api change!

Everything changed, hopefully for the best.

* everything is accessible from the `na` module. It re-export
  everything and provides free functions (i-e: na::dot(a, b) instead of
  a.dot(b)) for most functionalities.
* matrix/vector adaptors (Rotmat, Transform) are replaced by plain
  types: Rot{2, 3, 4} for rotation matrices and Iso{2, 3, 4} for
  isometries (rotation + translation).  This old adaptors system was to
  hard to understand and to document.
* each file related to data structures moved to the `structs` folder.
  This makes the doc a lot more readable and make people prefer the
  `na` module instead of individual small modules.
* Because `na` exists now, the modules `structs::vec` and
  `structs::mat` dont re-export anything now.

As a side effect, this makes the documentation more readable.

											
										
										
											2013-10-06 22:54:09 +08:00
-												Add 3D orthogonal and perspective projection structures.

Fix #26.

											
										
										
											2014-10-13 02:21:06 +08:00
+								```.ignore
 								use nalgebra::*;
-												Huge api change!

Everything changed, hopefully for the best.

* everything is accessible from the `na` module. It re-export
  everything and provides free functions (i-e: na::dot(a, b) instead of
  a.dot(b)) for most functionalities.
* matrix/vector adaptors (Rotmat, Transform) are replaced by plain
  types: Rot{2, 3, 4} for rotation matrices and Iso{2, 3, 4} for
  isometries (rotation + translation).  This old adaptors system was to
  hard to understand and to document.
* each file related to data structures moved to the `structs` folder.
  This makes the doc a lot more readable and make people prefer the
  `na` module instead of individual small modules.
* Because `na` exists now, the modules `structs::vec` and
  `structs::mat` dont re-export anything now.

As a side effect, this makes the documentation more readable.

											
										
										
											2013-10-06 22:54:09 +08:00
+								```
-												Fix the example on the README.

											
										
										
											2014-01-14 16:52:18 +08:00
+								The preferred way to use **nalgebra** is to import types and traits explicitly, and call
-												Remove free-functions alliasing structures constructors.

Those constructors are not idiomatic. Use e.g. `Vec3::new(0, 0, 0)` instead.

											
										
										
											2013-10-14 17:22:38 +08:00
+								free-functions using the `na::` prefix:
 								```.rust
-												Fix the README examples.

											
										
										
											2015-06-06 20:28:34 +08:00
+								extern crate nalgebra as na;
-												Add 3D orthogonal and perspective projection structures.

Fix #26.

											
										
										
											2014-10-13 02:21:06 +08:00
+								use na::{Vec3, Rot3, Rotation};
-												Remove free-functions alliasing structures constructors.

Those constructors are not idiomatic. Use e.g. `Vec3::new(0, 0, 0)` instead.

											
										
										
											2013-10-14 17:22:38 +08:00
 								fn main() {
 								    let     a = Vec3::new(1.0f64, 1.0, 1.0);
 								    let mut b = Rot3::new(na::zero());
-												Fix the README examples.

											
										
										
											2015-06-06 20:28:34 +08:00
+								    b.append_rotation_mut(&a);
-												Remove free-functions alliasing structures constructors.

Those constructors are not idiomatic. Use e.g. `Vec3::new(0, 0, 0)` instead.

											
										
										
											2013-10-14 17:22:38 +08:00
-												Fix the example on the README.

											
										
										
											2014-01-14 16:52:18 +08:00
+								    assert!(na::approx_eq(&na::rotation(&b), &a));
-												Remove free-functions alliasing structures constructors.

Those constructors are not idiomatic. Use e.g. `Vec3::new(0, 0, 0)` instead.

											
										
										
											2013-10-14 17:22:38 +08:00
+								}
 								```
-												Add compilation instructions.
											
										
										
											2013-06-13 22:06:05 +08:00
-												Fix the README examples.

											
										
										
											2015-06-06 20:28:34 +08:00
-												Improve the readme.

											
										
										
											2013-09-28 06:12:18 +08:00
+								## Features
-												Fix typos.

											
										
										
											2014-10-13 14:46:39 +08:00
+								**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:
-												Add compilation instructions.
											
										
										
											2013-06-13 22:06:05 +08:00
-												Remove useless or incomplete structs: `Vec0`, `Pnt0`, `Iso4`, `Rot4`.

											
										
										
											2016-03-25 02:03:44 +08:00
+								* Vectors with predefined static sizes: `Vec1`, `Vec2`, `Vec3`, `Vec4`, `Vec5`, `Vec6`.
-												Feature-gate the `VecN` structure.

`rustc` is has a hard time compiling it from time to time.

											
										
										
											2016-03-25 02:37:56 +08:00
+								* Vector with a user-defined static size: `VecN` (available only with the `generic_sizes` feature).
-												Complete the documentation.

											
										
										
											2016-03-25 02:04:01 +08:00
+								* Points with static sizes: `Pnt1`, `Pnt2`, `Pnt3`, `Pnt4`, `Pnt5`, `Pnt6`.
-												Update to the last Rust.

Also use free-functions on tests.

											
										
										
											2013-10-08 07:22:56 +08:00
+								* Square matrices with static sizes: `Mat1`, `Mat2`, `Mat3`, `Mat4`, `Mat5`, `Mat6 `.
-												Remove useless or incomplete structs: `Vec0`, `Pnt0`, `Iso4`, `Rot4`.

											
										
										
											2016-03-25 02:03:44 +08:00
+								* Rotation matrices: `Rot2`, `Rot3`
-												Add quaternions to the feature list.

											
										
										
											2014-10-15 04:24:10 +08:00
+								* Quaternions: `Quat`, `UnitQuat`.
-												Complete the documentation.

											
										
										
											2016-03-25 02:04:01 +08:00
+								* Isometries (translation ⨯ rotation): `Iso2`, `Iso3`
 								* Similarity transformations (translation ⨯ rotation ⨯ uniform scale): `Sim2`, `Sim3`.
-												Add 3D orthogonal and perspective projection structures.

Fix #26.

											
										
										
											2014-10-13 02:21:06 +08:00
+								* 3D projections for computer graphics: `Persp3`, `PerspMat3`, `Ortho3`, `OrthoMat3`.
-												Add similarity transformations Sim2 and Sim3 (uniform scale followed by a rotation followed by a translation).

											
										
										
											2016-03-25 02:03:40 +08:00
+								* Dynamically sized heap-allocated vector: `DVec`.
 								* Dynamically sized stack-allocated vectors with a maximum size: `DVec1` to `DVec6`.
 								* Dynamically sized heap-allocated (square or rectangular) matrix: `DMat`.
-												Remove useless or incomplete structs: `Vec0`, `Pnt0`, `Iso4`, `Rot4`.

											
										
										
											2016-03-25 02:03:44 +08:00
+								* Linear algebra and data analysis operators: `Cov`, `Mean`, `qr`, `cholesky`.
-												Fix typos on the readme.

											
										
										
											2013-10-07 01:20:39 +08:00
+								* Almost one trait per functionality: useful for generic programming.