template<class T>
Magnum::Math::Matrix3 class

2D transformation matrix

Template parameters
T Underlying data type

Expands upon a generic Matrix3x3 with functionality for 2D transformations. A 2D transformation matrix consists of a upper-left 2x2 part describing a combined scaling, rotation and shear, and the two top-right components specifying a translation:

\[ \boldsymbol{T} = \begin{pmatrix} \color{m-danger} a_x & \color{m-success} b_x & \color{m-warning} t_x \\ \color{m-danger} a_y & \color{m-success} b_y & \color{m-warning} t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

The $ \color{m-danger} \boldsymbol{a} $ and $ \color{m-success} \boldsymbol{b} $ vectors can be also thought of as the two basis vectors describing the coordinate system the matrix converts to. The bottom row is always $ \begin{pmatrix} \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} $ as, unlike with Matrix4 in 3D, perspective shortening happening along the X or Y axis isn't really a thing.

Usage

See Math type system, Operations with matrices and vectors and 2D and 3D transformations first for an introduction into using transformation matrices.

While it's possible to create the matrix directly from the components, the recommended usage is by creating elementary transformation matrices with translation(), rotation(), scaling(), reflection(), shearingX(), shearingY(), and projection() and multiplying them together to form the final transformation — the rightmost transformation is applied first, leftmost last:

using namespace Math::Literals;

Matrix3 transformation =
    Matrix3::rotation(15.0_degf)*
    Matrix3::translation({100.0f, -30.0f})*
    Matrix3::scaling(Vector2::yScale(2.0f));

Conversely, the transformation parts can be extracted back using the member rotation(), scaling() and their variants, and translation(). The basis vectors can be accessed using right() and up(). Matrices that combine non-uniform scaling and/or shear with rotation can't be trivially decomposed back, for these you might want to consider using Algorithms::qr() or Algorithms::svd().

When a lot of transformations gets composed together over time (for example with a camera movement), a floating-point drift accumulates, causing the rotation part to no longer be orthogonal. This can be accounted for using Algorithms::gramSchmidtOrthonormalizeInPlace() and variants.

Base classes

template<std::size_t size, class T>
class Matrix<T>
Square matrix.

Public static functions

static auto translation(const Vector2<T>& vector) -> Matrix3<T> constexpr
2D translation matrix
static auto scaling(const Vector2<T>& vector) -> Matrix3<T> constexpr
2D scaling matrix
static auto rotation(Rad<T> angle) -> Matrix3<T>
2D rotation matrix
static auto reflection(const Vector2<T>& normal) -> Matrix3<T>
2D reflection matrix
static auto shearingX(T amount) -> Matrix3<T> constexpr
2D shearing matrix along X axis
static auto shearingY(T amount) -> Matrix3<T> constexpr
2D shearing matrix along Y axis
static auto projection(const Vector2<T>& size) -> Matrix3<T>
2D projection matrix
static auto from(const Matrix2x2<T>& rotationScaling, const Vector2<T>& translation) -> Matrix3<T> constexpr
Create matrix from rotation/scaling part and translation part.

Constructors, destructors, conversion operators

Matrix3() constexpr noexcept
Default constructor.
Matrix3(IdentityInitT, T value = T{1}) explicit constexpr noexcept
Construct an identity matrix.
Matrix3(ZeroInitT) explicit constexpr noexcept
Construct a zero-filled matrix.
Matrix3(Magnum::NoInitT) explicit constexpr noexcept
Construct without initializing the contents.
Matrix3(const Vector3<T>& first, const Vector3<T>& second, const Vector3<T>& third) constexpr noexcept
Construct from column vectors.
Matrix3(T value) explicit constexpr noexcept
Construct with one value for all elements.
template<class U>
Matrix3(const RectangularMatrix<3, 3, U>& other) explicit constexpr noexcept
Construct from a matrix of a different type.
template<class U, class V = decltype(Implementation::RectangularMatrixConverter<3, 3, T, U>::from(std::declval<U>()))>
Matrix3(const U& other) explicit constexpr noexcept
Construct a matrix from external representation.
template<std::size_t otherCols, std::size_t otherRows>
Matrix3(IdentityInitT, const RectangularMatrix<otherCols, otherRows, T>& other, T value = T(1)) explicit constexpr noexcept new in Git master
Construct by slicing or expanding a matrix of different size, leaving the rest at identity.
template<std::size_t otherCols, std::size_t otherRows>
Matrix3(ZeroInitT, const RectangularMatrix<otherCols, otherRows, T>& other) explicit constexpr noexcept new in Git master
Construct by slicing or expanding a matrix of different size, leaving the rest at zero.
template<std::size_t otherCols, std::size_t otherRows>
Matrix3(const RectangularMatrix<otherCols, otherRows, T>& other, T value = T(1)) explicit constexpr noexcept new in Git master
Construct by slicing or expanding a matrix of different size.
Matrix3(const RectangularMatrix<3, 3, T>& other) constexpr noexcept
Copy constructor.

Public functions

auto isRigidTransformation() const -> bool
Check whether the matrix represents a rigid transformation.
auto rotationScaling() const -> Matrix2x2<T> constexpr
2D rotation and scaling part of the matrix
auto rotationShear() const -> Matrix2x2<T>
2D rotation and shear part of the matrix
auto rotation() const -> Matrix2x2<T>
2D rotation part of the matrix
auto rotationNormalized() const -> Matrix2x2<T>
2D rotation part of the matrix assuming there is no scaling
auto scalingSquared() const -> Vector2<T>
Non-uniform scaling part of the matrix, squared.
auto scaling() const -> Vector2<T>
Non-uniform scaling part of the matrix.
auto uniformScalingSquared() const -> T
Uniform scaling part of the matrix, squared.
auto uniformScaling() const -> T
Uniform scaling part of the matrix.
auto right() -> Vector2<T>&
Right-pointing 2D vector.
auto right() const -> Vector2<T> constexpr
auto up() -> Vector2<T>&
Up-pointing 2D vector.
auto up() const -> Vector2<T> constexpr
auto translation() -> Vector2<T>&
2D translation part of the matrix
auto translation() const -> Vector2<T> constexpr
auto invertedRigid() const -> Matrix3<T>
Inverted rigid transformation matrix.
auto transformVector(const Vector2<T>& vector) const -> Vector2<T>
Transform a 2D vector with the matrix.
auto transformPoint(const Vector2<T>& vector) const -> Vector2<T>
Transform a 2D point with the matrix.

Function documentation

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::translation(const Vector2<T>& vector) constexpr

2D translation matrix

Parameters
vector Translation vector
\[ \boldsymbol{A} = \begin{pmatrix} 1 & 0 & v_x \\ 0 & 1 & v_y \\ 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::scaling(const Vector2<T>& vector) constexpr

2D scaling matrix

Parameters
vector Scaling vector
\[ \boldsymbol{A} = \begin{pmatrix} v_x & 0 & 0 \\ 0 & v_y & 0 \\ 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::rotation(Rad<T> angle)

2D rotation matrix

Parameters
angle Rotation angle (counterclockwise)
\[ \boldsymbol{A} = \begin{pmatrix} \cos\theta & -\sin\theta & 0 \\ \sin\theta & \cos\theta & 0 \\ 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::reflection(const Vector2<T>& normal)

2D reflection matrix

Parameters
normal Normal of the line through which to reflect

Expects that the normal is normalized. Reflection along axes can be done in a slightly simpler way also using scaling(), e.g. Matrix3::reflection(Vector2::yAxis()) is equivalent to Matrix3::scaling(Vector2::yScale(-1.0f)).

\[ \boldsymbol{A} = \boldsymbol{I} - 2 \boldsymbol{NN}^T ~~~~~ \boldsymbol{N} = \begin{pmatrix} n_x \\ n_y \end{pmatrix} \]

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::shearingX(T amount) constexpr

2D shearing matrix along X axis

Parameters
amount Shearing amount

Y axis remains unchanged.

\[ \boldsymbol{A} = \begin{pmatrix} 1 & v_x & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::shearingY(T amount) constexpr

2D shearing matrix along Y axis

Parameters
amount Shearing amount

X axis remains unchanged.

\[ \boldsymbol{A} = \begin{pmatrix} 1 & 0 & 0 \\ v_y & 1 & 0 \\ 0 & 0 & 1 \end{pmatrix} \]

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::projection(const Vector2<T>& size)

2D projection matrix

Parameters
size Size of the view
\[ \boldsymbol{A} = \begin{pmatrix} \frac{2}{s_x} & 0 & 0 \\ 0 & \frac{2}{s_y} & 0 \\ 0 & 0 & 1 \end{pmatrix} \]

Similar to the classic gluOrtho2D() function, except that the projection is always centered.

template<class T>
static Matrix3<T> Magnum::Math::Matrix3<T>::from(const Matrix2x2<T>& rotationScaling, const Vector2<T>& translation) constexpr

Create matrix from rotation/scaling part and translation part.

Parameters
rotationScaling Rotation/scaling part (upper-left 2x2 matrix)
translation Translation part (first two elements of third column)

template<class T>
Magnum::Math::Matrix3<T>::Matrix3() constexpr noexcept

Default constructor.

Equivalent to Matrix3(IdentityInitT, T).

template<class T>
Magnum::Math::Matrix3<T>::Matrix3(IdentityInitT, T value = T{1}) explicit constexpr noexcept

Construct an identity matrix.

The value allows you to specify value on diagonal.

template<class T>
Magnum::Math::Matrix3<T>::Matrix3(ZeroInitT) explicit constexpr noexcept

Construct a zero-filled matrix.

template<class T> template<class U>
Magnum::Math::Matrix3<T>::Matrix3(const RectangularMatrix<3, 3, U>& other) explicit constexpr noexcept

Construct from a matrix of a different type.

Performs only default casting on the values, no rounding or anything else. Example usage:

Matrix2x2 floatingPoint{Vector2{1.3f, 2.7f}, Vector2{-15.0f, 7.0f}};
Math::Matrix2x2<Byte> integral{floatingPoint}; // {{1, 2}, {-15, 7}}

template<class T> template<std::size_t otherCols, std::size_t otherRows>
Magnum::Math::Matrix3<T>::Matrix3(IdentityInitT, const RectangularMatrix<otherCols, otherRows, T>& other, T value = T(1)) explicit constexpr noexcept new in Git master

Construct by slicing or expanding a matrix of different size, leaving the rest at identity.

If the other matrix has less columns or rows, the corresponding vectors and components are set to either zeros or value on the diagonal.

template<class T> template<std::size_t otherCols, std::size_t otherRows>
Magnum::Math::Matrix3<T>::Matrix3(ZeroInitT, const RectangularMatrix<otherCols, otherRows, T>& other) explicit constexpr noexcept new in Git master

Construct by slicing or expanding a matrix of different size, leaving the rest at zero.

If the other matrix has less columns or rows, the corresponding vectors and components are set to zeros.

template<class T> template<std::size_t otherCols, std::size_t otherRows>
Magnum::Math::Matrix3<T>::Matrix3(const RectangularMatrix<otherCols, otherRows, T>& other, T value = T(1)) explicit constexpr noexcept new in Git master

Construct by slicing or expanding a matrix of different size.

Equivalent to Matrix3(IdentityInitT, const RectangularMatrix<otherCols, otherRows, T>&, T). Note that this default is different from RectangularMatrix, where it's equivalent to the ZeroInit variant instead.

template<class T>
bool Magnum::Math::Matrix3<T>::isRigidTransformation() const

Check whether the matrix represents a rigid transformation.

A rigid transformation consists only of rotation, reflection and translation (i.e., no scaling, skew or projection).

template<class T>
Matrix2x2<T> Magnum::Math::Matrix3<T>::rotationScaling() const constexpr

2D rotation and scaling part of the matrix

Unchanged upper-left 2x2 part of the matrix.

\[ \begin{pmatrix} \color{m-danger} a_x & \color{m-success} b_x & t_x \\ \color{m-danger} a_y & \color{m-success} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

Note that an arbitrary combination of rotation and scaling can also represent shear and reflection. Especially when non-uniform scaling is involved, decomposition of the result into primary linear transformations may have multiple equivalent solutions. See Algorithms::svd() and Algorithms::qr() for further info. See also rotationShear(), rotation() const and scaling() const for extracting further properties.

template<class T>
Matrix2x2<T> Magnum::Math::Matrix3<T>::rotationShear() const

2D rotation and shear part of the matrix

Normalized upper-left 2x2 part of the matrix. Assuming the following matrix, with the upper-left 2x2 part represented by column vectors $ \boldsymbol{a} $ and $ \boldsymbol{b} $ :

\[ \begin{pmatrix} \color{m-danger} a_x & \color{m-success} b_x & t_x \\ \color{m-danger} a_y & \color{m-success} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

the resulting rotation is extracted as:

\[ \boldsymbol{R} = \begin{pmatrix} \cfrac{\boldsymbol{a}}{|\boldsymbol{a}|} & \cfrac{\boldsymbol{b}}{|\boldsymbol{b}|} \end{pmatrix} \]

This function is a counterpart to rotation() const that does not require orthogonal input. See also rotationScaling() and scaling() const for extracting other properties. The Algorithms::svd() and Algorithms::qr() can be used to separate the rotation / shear properties.

template<class T>
Matrix2x2<T> Magnum::Math::Matrix3<T>::rotation() const

2D rotation part of the matrix

Normalized upper-left 2x2 part of the matrix. Expects that the normalized part is orthogonal. Assuming the following matrix, with the upper-left 2x2 part represented by column vectors $ \boldsymbol{a} $ and $ \boldsymbol{b} $ :

\[ \begin{pmatrix} \color{m-warning} a_x & \color{m-warning} b_x & t_x \\ \color{m-warning} a_y & \color{m-warning} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

the resulting rotation is extracted as:

\[ \boldsymbol{R} = \begin{pmatrix} \cfrac{\boldsymbol{a}}{|\boldsymbol{a}|} & \cfrac{\boldsymbol{b}}{|\boldsymbol{b}|} \end{pmatrix} \]

This function is equivalent to rotationShear() but with the added orthogonality requirement. See also rotationScaling() and scaling() const for extracting other properties.

template<class T>
Matrix2x2<T> Magnum::Math::Matrix3<T>::rotationNormalized() const

2D rotation part of the matrix assuming there is no scaling

Similar to rotation(), but expects that the rotation part is orthogonal, saving the extra renormalization. Assuming the following matrix, with the upper-left 2x2 part represented by column vectors $ \boldsymbol{a} $ and $ \boldsymbol{b} $ :

\[ \begin{pmatrix} \color{m-danger} a_x & \color{m-success} b_x & t_x \\ \color{m-danger} a_y & \color{m-success} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

the resulting rotation is extracted as:

\[ \boldsymbol{R} = \begin{pmatrix} \cfrac{\boldsymbol{a}}{|\boldsymbol{a}|} & \cfrac{\boldsymbol{b}}{|\boldsymbol{b}|} \end{pmatrix} = \begin{pmatrix} \boldsymbol{a} & \boldsymbol{b} \end{pmatrix} \]

In particular, for an orthogonal matrix, rotationScaling(), rotationShear(), rotation() const and rotationNormalized() all return the same value.

template<class T>
Vector2<T> Magnum::Math::Matrix3<T>::scalingSquared() const

Non-uniform scaling part of the matrix, squared.

Squared length of vectors in upper-left 2x2 part of the matrix. Faster alternative to scaling() const, because it doesn't calculate the square root. Assuming the following matrix, with the upper-left 2x2 part represented by column vectors $ \boldsymbol{a} $ and $ \boldsymbol{b} $ :

\[ \begin{pmatrix} \color{m-warning} a_x & \color{m-warning} b_x & t_x \\ \color{m-warning} a_y & \color{m-warning} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

the resulting scaling vector, squared, is:

\[ \boldsymbol{s}^2 = \begin{pmatrix} \boldsymbol{a} \cdot \boldsymbol{a} \\ \boldsymbol{b} \cdot \boldsymbol{b} \end{pmatrix} \]

template<class T>
Vector2<T> Magnum::Math::Matrix3<T>::scaling() const

Non-uniform scaling part of the matrix.

Length of vectors in upper-left 2x2 part of the matrix. Use the faster alternative scalingSquared() where possible. Assuming the following matrix, with the upper-left 2x2 part represented by column vectors $ \boldsymbol{a} $ and $ \boldsymbol{b} $ :

\[ \begin{pmatrix} \color{m-warning} a_x & \color{m-warning} b_x & t_x \\ \color{m-warning} a_y & \color{m-warning} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

the resulting scaling vector is:

\[ \boldsymbol{s} = \begin{pmatrix} | \boldsymbol{a} | \\ | \boldsymbol{b} | \end{pmatrix} \]

Note that the returned vector is sign-less and the signs are instead contained in rotation() const / rotationShear() const in order to ensure $ \boldsymbol{R} \boldsymbol{S} = \boldsymbol{M} $ for $ \boldsymbol{R} $ and $ \boldsymbol{S} $ extracted out of $ \boldsymbol{M} $ . The signs can be extracted for example by applying Math::sign() on a diagonal(), but keep in mind that the signs can be negative even for pure rotation matrices.

template<class T>
T Magnum::Math::Matrix3<T>::uniformScalingSquared() const

Uniform scaling part of the matrix, squared.

Squared length of vectors in upper-left 2x2 part of the matrix. Expects that the scaling is the same in all axes. Faster alternative to uniformScaling(), because it doesn't compute the square root. Assuming the following matrix, with the upper-left 2x2 part represented by column vectors $ \boldsymbol{a} $ and $ \boldsymbol{b} $ :

\[ \begin{pmatrix} \color{m-warning} a_x & \color{m-warning} b_x & t_x \\ \color{m-warning} a_y & \color{m-warning} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

the resulting uniform scaling, squared, is:

\[ s^2 = \boldsymbol{a} \cdot \boldsymbol{a} = \boldsymbol{b} \cdot \boldsymbol{b} \]

template<class T>
T Magnum::Math::Matrix3<T>::uniformScaling() const

Uniform scaling part of the matrix.

Length of vectors in upper-left 2x2 part of the matrix. Expects that the scaling is the same in all axes. Use faster alternative uniformScalingSquared() where possible. Assuming the following matrix, with the upper-left 3x3 part represented by column vectors $ \boldsymbol{a} $ and $ \boldsymbol{b} $ :

\[ \begin{pmatrix} \color{m-warning} a_x & \color{m-warning} b_x & t_x \\ \color{m-warning} a_y & \color{m-warning} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

the resulting uniform scaling is:

\[ s = | \boldsymbol{a} | = | \boldsymbol{b} | \]

template<class T>
Vector2<T>& Magnum::Math::Matrix3<T>::right()

Right-pointing 2D vector.

First two elements of first column.

\[ \begin{pmatrix} \color{m-danger} a_x & b_x & t_x \\ \color{m-danger} a_y & b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

template<class T>
Vector2<T> Magnum::Math::Matrix3<T>::right() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Vector2<T>& Magnum::Math::Matrix3<T>::up()

Up-pointing 2D vector.

First two elements of second column.

\[ \begin{pmatrix} a_x & \color{m-success} b_x & t_x \\ a_y & \color{m-success} b_y & t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

template<class T>
Vector2<T> Magnum::Math::Matrix3<T>::up() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Vector2<T>& Magnum::Math::Matrix3<T>::translation()

2D translation part of the matrix

First two elements of third column.

\[ \begin{pmatrix} a_x & b_x & \color{m-warning} t_x \\ a_y & b_y & \color{m-warning} t_y \\ \color{m-dim} 0 & \color{m-dim} 0 & \color{m-dim} 1 \end{pmatrix} \]

template<class T>
Vector2<T> Magnum::Math::Matrix3<T>::translation() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
Matrix3<T> Magnum::Math::Matrix3<T>::invertedRigid() const

Inverted rigid transformation matrix.

Expects that the matrix represents a rigid transformation (i.e., no scaling, skew or projection). Significantly faster than the general algorithm in inverted().

\[ A^{-1} = \begin{pmatrix} (A^{2,2})^T & (A^{2,2})^T \begin{pmatrix} a_{2,0} \\ a_{2,1} \end{pmatrix} \\ \begin{array}{cc} 0 & 0 \end{array} & 1 \end{pmatrix} \]

$ A^{i, j} $ is matrix without i-th row and j-th column, see ij()

template<class T>
Vector2<T> Magnum::Math::Matrix3<T>::transformVector(const Vector2<T>& vector) const

Transform a 2D vector with the matrix.

Unlike in transformPoint(), translation is not involved in the transformation.

\[ \boldsymbol v' = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ 0 \end{pmatrix} \]

template<class T>
Vector2<T> Magnum::Math::Matrix3<T>::transformPoint(const Vector2<T>& vector) const

Transform a 2D point with the matrix.

Unlike in transformVector(), translation is also involved in the transformation.

\[ \boldsymbol v' = \boldsymbol M \begin{pmatrix} v_x \\ v_y \\ 1 \end{pmatrix} \]