# Matrix

An affine transformation matrix performs a linear mapping from 2D coordinates to other 2D coordinates that preserves the “straightness” and “parallelness” of lines.

Such a coordinate transformation can be represented by a 3 row by 3 column matrix with an implied last row of `[ 0 0 1 ]`. This matrix transforms source coordinates `(x, y)` into destination coordinates `(x',y')` by considering them to be a column vector and multiplying the coordinate vector by the matrix according to the following process:

    [ x ]   [ a  c  tx ] [ x ]   [ a * x + c * y + tx ]
    [ y ] = [ b  d  ty ] [ y ] = [ b * x + d * y + ty ]
    [ 1 ]   [ 0  0  1  ] [ 1 ]   [         1          ]

Note the locations of b and c.

This class is optimized for speed and minimizes calculations based on its knowledge of the underlying matrix (as opposed to say simply performing matrix multiplication).

## Constructors

`Matrix()`

Creates a 2D affine transformation matrix that describes the identity transformation.

#### Returns:

- ``Matrix``

`Matrix(a, b, c, d, tx, ty)`

Creates a 2D affine transformation matrix.

#### Parameters:

- `a:` `Number` — the a property of the transform
- `b:` `Number` — the b property of the transform
- `c:` `Number` — the c property of the transform
- `d:` `Number` — the d property of the transform
- `tx:` `Number` — the tx property of the transform
- `ty:` `Number` — the ty property of the transform

#### Returns:

- ``Matrix``

`Matrix(values)`

Creates a 2D affine transformation matrix.

#### Parameters:

- `values:` Array of `Numbers` — the matrix values to initialize this matrix with

#### Returns:

- ``Matrix``

`Matrix(matrix)`

Creates a 2D affine transformation matrix.

#### Parameters:

- `matrix:` `Matrix` — the matrix to copy the values from

#### Returns:

- ``Matrix``

## Properties

`a`

The value that affects the transformation along the x axis when scaling or rotating, positioned at (0, 0) in the transformation matrix.

#### Type:

- `Number`

`b`

The value that affects the transformation along the y axis when rotating or skewing, positioned at (1, 0) in the transformation matrix.

#### Type:

- `Number`

`c`

The value that affects the transformation along the x axis when rotating or skewing, positioned at (0, 1) in the transformation matrix.

#### Type:

- `Number`

`d`

The value that affects the transformation along the y axis when scaling or rotating, positioned at (1, 1) in the transformation matrix.

#### Type:

- `Number`

`tx`

The distance by which to translate along the x axis, positioned at (2, 0) in the transformation matrix.

#### Type:

- `Number`

`ty`

The distance by which to translate along the y axis, positioned at (2, 1) in the transformation matrix.

#### Type:

- `Number`

`values`

The matrix values as an array, in the same sequence as they are passed to `initialize(a, b, c, d, tx, ty)`.

Read only.

#### Type:

- Array of `Numbers`

`translation`

The translation of the matrix as a vector.

Read only.

#### Type:

- `Point`

`scaling`

The scaling values of the matrix, if it can be decomposed.

Read only.

#### Type:

- `Point`

#### See also:

- ``decompose`()`

`rotation`

The rotation angle of the matrix, if it can be decomposed.

Read only.

#### Type:

- `Number`

#### See also:

- ``decompose`()`

## Methods

`set(...values)`

Sets the matrix to the passed values. Note that any sequence of parameters that is supported by the various `Matrix`() constructors also work for calls of `set()`.

#### Parameters:

- `values:` `any value`

#### Returns:

- ``Point``

`clone()`

#### Returns:

- ``Matrix`` — a copy of this transform

`equals(matrix)`

Checks whether the two matrices describe the same transformation.

#### Parameters:

- `matrix:` `Matrix` — the matrix to compare this matrix to

#### Returns:

- ``Boolean`` — `true` if the matrices are equal, `false` otherwise

`toString()`

#### Returns:

- ``String`` — a string representation of this transform

`reset()`

Resets the matrix by setting its values to the ones of the identity matrix that results in no transformation.

`apply([recursively])`

Attempts to apply the matrix to the content of item that it belongs to, meaning its transformation is baked into the item’s content or children.

#### Parameters:

- `recursively:` `Boolean` — controls whether to apply transformations recursively on children — optional, default: `true`

#### Returns:

- ``Boolean`` — `true` if the matrix was applied, `false` otherwise

`translate(point)`

Concatenates this matrix with a translate transformation.

#### Parameters:

- `point:` `Point` — the vector to translate by

#### Returns:

- ``Matrix`` — this affine transform

`translate(dx, dy)`

Concatenates this matrix with a translate transformation.

#### Parameters:

- `dx:` `Number` — the distance to translate in the x direction
- `dy:` `Number` — the distance to translate in the y direction

#### Returns:

- ``Matrix`` — this affine transform

`scale(scale[, center])`

Concatenates this matrix with a scaling transformation.

#### Parameters:

- `scale:` `Number` — the scaling factor
- `center:` `Point` — the center for the scaling transformation — optional

#### Returns:

- ``Matrix`` — this affine transform

`scale(hor, ver[, center])`

Concatenates this matrix with a scaling transformation.

#### Parameters:

- `hor:` `Number` — the horizontal scaling factor
- `ver:` `Number` — the vertical scaling factor
- `center:` `Point` — the center for the scaling transformation — optional

#### Returns:

- ``Matrix`` — this affine transform

`rotate(angle, center)`

Concatenates this matrix with a rotation transformation around an anchor point.

#### Parameters:

- `angle:` `Number` — the angle of rotation measured in degrees
- `center:` `Point` — the anchor point to rotate around

#### Returns:

- ``Matrix`` — this affine transform

`rotate(angle, x, y)`

Concatenates this matrix with a rotation transformation around an anchor point.

#### Parameters:

- `angle:` `Number` — the angle of rotation measured in degrees
- `x:` `Number` — the x coordinate of the anchor point
- `y:` `Number` — the y coordinate of the anchor point

#### Returns:

- ``Matrix`` — this affine transform

`shear(shear[, center])`

Concatenates this matrix with a shear transformation.

#### Parameters:

- `shear:` `Point` — the shear factor in x and y direction
- `center:` `Point` — the center for the shear transformation — optional

#### Returns:

- ``Matrix`` — this affine transform

`shear(hor, ver[, center])`

Concatenates this matrix with a shear transformation.

#### Parameters:

- `hor:` `Number` — the horizontal shear factor
- `ver:` `Number` — the vertical shear factor
- `center:` `Point` — the center for the shear transformation — optional

#### Returns:

- ``Matrix`` — this affine transform

`skew(skew[, center])`

Concatenates this matrix with a skew transformation.

#### Parameters:

- `skew:` `Point` — the skew angles in x and y direction in degrees
- `center:` `Point` — the center for the skew transformation — optional

#### Returns:

- ``Matrix`` — this affine transform

`skew(hor, ver[, center])`

Concatenates this matrix with a skew transformation.

#### Parameters:

- `hor:` `Number` — the horizontal skew angle in degrees
- `ver:` `Number` — the vertical skew angle in degrees
- `center:` `Point` — the center for the skew transformation — optional

#### Returns:

- ``Matrix`` — this affine transform

`append(matrix)`

Appends the specified matrix to this matrix. This is the equivalent of multiplying `(this matrix) * (specified matrix)`.

#### Parameters:

- `matrix:` `Matrix` — the matrix to append

#### Returns:

- ``Matrix`` — this matrix, modified

`prepend(matrix)`

Prepends the specified matrix to this matrix. This is the equivalent of multiplying `(specified matrix) * (this matrix)`.

#### Parameters:

- `matrix:` `Matrix` — the matrix to prepend

#### Returns:

- ``Matrix`` — this matrix, modified

`appended(matrix)`

Returns a new matrix as the result of appending the specified matrix to this matrix. This is the equivalent of multiplying `(this matrix) * (specified matrix)`.

#### Parameters:

- `matrix:` `Matrix` — the matrix to append

#### Returns:

- ``Matrix`` — the newly created matrix

`prepended(matrix)`

Returns a new matrix as the result of prepending the specified matrix to this matrix. This is the equivalent of multiplying `(specified matrix) * (this matrix)`.

#### Parameters:

- `matrix:` `Matrix` — the matrix to prepend

#### Returns:

- ``Matrix`` — the newly created matrix

`invert()`

Inverts the matrix, causing it to perform the opposite transformation. If the matrix is not invertible (in which case `isSingular`() returns true), `null` is returned.

#### Returns:

- ``Matrix`` — this matrix, or `null`, if the matrix is singular.

`inverted()`

Creates a new matrix that is the inversion of this matrix, causing it to perform the opposite transformation. If the matrix is not invertible (in which case `isSingular`() returns true), `null` is returned.

#### Returns:

- ``Matrix`` — this matrix, or `null`, if the matrix is singular.

`isIdentity()`

#### Returns:

- ``Boolean`` — whether this matrix is the identity matrix

`isInvertible()`

Checks whether the matrix is invertible. A matrix is not invertible if the determinant is 0 or any value is infinite or NaN.

#### Returns:

- ``Boolean`` — whether the matrix is invertible

`isSingular()`

Checks whether the matrix is singular or not. Singular matrices cannot be inverted.

#### Returns:

- ``Boolean`` — whether the matrix is singular

`transform(point)`

Transforms a point and returns the result.

#### Parameters:

- `point:` `Point` — the point to be transformed

#### Returns:

- ``Point`` — the transformed point

`transform(src, dst, count)`

Transforms an array of coordinates by this matrix and stores the results into the destination array, which is also returned.

#### Parameters:

- `src:` Array of `Numbers` — the array containing the source points as x, y value pairs
- `dst:` Array of `Numbers` — the array into which to store the transformed point pairs
- `count:` `Number` — the number of points to transform

#### Returns:

- `Array of `Numbers`` — the dst array, containing the transformed coordinates

`inverseTransform(point)`

Inverse transforms a point and returns the result.

#### Parameters:

- `point:` `Point` — the point to be transformed

#### Returns:

- ``Point``

`decompose()`

Decomposes the affine transformation described by this matrix into `scaling`, `rotation` and `skewing`, and returns an object with these properties.

#### Returns:

- ``Object`` — the decomposed matrix

`applyToContext(ctx)`

Applies this matrix to the specified Canvas Context.

#### Parameters:

- `ctx:` `CanvasRenderingContext2D`