# Introduction to nalgebra

**nalgebra** is a general-purpose linear algebra library written in Rust. It has an extensive
set of features including vectors, matrices, transformations, factorizations, etc. Because **nalgebra** is used
extensively by Rapier and its API, the goal of this page is to give a very quick introduction to some basic features
of **nalgebra** that you will need to use **Rapier**.

## #

VectorsVectors are matrices with a single column. They are used in **Rapier** to express various quantities like velocities
forces, etc. Whereas **nalgebra** supports vectors of any size, **Rapier** mostly uses 2D and 3D vectors: the `Vector2`

and `Vector3`

type aliases form **nalgebra**.

##### info

Whenever you see the `Vector`

type appearing in the API of Rapier, it means `Vector2`

if you are
using the 2D version of Rapier, or `Vector3`

if you are using the 3D version of Rapier.

##### info

Whenever you see `AngVector`

appearing in the API of Rapier, it means `f32`

(or `f64`

) if you are using the 2D
version of Rapier, or `Vector3`

if you are using the 3D version of Rapier.

There are various ways of creating a vector. They are shown in the example bellow:

- Example 2D
- Example 3D

Accessing the components of a vector can be done by indexing or using its `x,y`

fields:

Accessing the components of a vector can be done by indexing or using its `x,y,z`

fields:

## #

PointsPoints are wrappers around vectors, but with a semantic than vectors. A point can be interpreted as a location in space whereas a vector can be seen as a direction or a displacement between two points. For example a contact between two shapes has contact points (the location of the contact in space) represented as points, and has a contact normal (the direction used to apply forces) represented as a vector.

Points are created/accessed in a way very similar to vectors:

- Example 2D
- Example 3D

##### info

It is possible to access the vector wrapped by a point by accessing its `coords`

field: `pt.coords`

.

## #

IsometriesAn isometry represents a rotation followed by a translation. Isometries are often used within Rapier to represent
the position of a rigid-body or a collider. By **position**, we generally
mean both the translation and the orientation of the rigid-body or collider.

- In 2D, the translational part of an isometry is represented as a
`Vector2`

, and the rotational part is represented as a`UnitComplex`

number (a complex number with a norm equal to 1). - In 3D the translational part of an isometry is represented as a
`Vector3`

, and the rotational part is represented as a`UnitQuaternion`

(a quaternion with a norm equal to 1).

Various ways of constructing an isometry are shown bellow:

- Example 2D
- Example 3D

Isometries can be used to transform points and vectors using multiplication: `isometry * point`

or `isometry * vector`

.

##### warning

Because **points** represent a **location** in space, `isometry * point`

will rotate and translate the point. However,
because **vectors** represent a **direction**, `isometry * vector`

will only rotate the vector (the translation part
of the isometry will be ignored).

## #

Interoperability with glam**glam** is another linear-algebra library written in Rust. It is popular within
the Rust game development community and is used by several popular crates like **Bevy**,
**macroquad**, etc.

It is possible to convert **nalgebra** types from/to **glam** types (using the standard library's `From`

and `Into`

traits)
by enabling one of the conversion cargo features of **nalgebra**:

- The
`convert-glam013`

features will enable conversion from/to**glam 0.13**. - The
`convert-glam014`

features will enable conversion from/to**glam 0.14**. - The
`convert-glam015`

features will enable conversion from/to**glam 0.15**. - The same feature naming conversion will be used for the other supported version of glam.

Here are examples of conversions these features enable:

- Conversion between
`na::Vector2`

and`glam::Vec2`

. - Conversion between
`na::Vector3`

and`glam::Vec3`

. - Conversion between
`na::Point2`

and`glam::Vec2`

. - Conversion between
`na::Point3`

and`glam::Vec3`

. - Conversion between
`na::Isometry2`

and the tuple`(glam::Vec2, f32)`

. - Conversion between
`na::Isometry3`

and the tuple`(glam::Vec3, glam::Quat)`

. - Conversion from
`glam::Vec2`

to`na::Isometry2`

(builds a translation-only isometry). - Conversion from
`glam::Vec3`

to`na::Isometry3`

(builds a translation-only isometry). - Conversion from
`glam::Quat`

to`na::Isometry3`

(builds a rotation-only isometry).