Tranformation Matrix APIs

February 10, 2025 · View on GitHub

Functions

applyToPoint(matrix, point) ⇒ Point: Calculate a point transformed with an affine matrix
applyToPoints(matrix, points) ⇒ Array.<Point>: Calculate an array of points transformed with an affine matrix
decomposeTSR(matrix, flipX, flipY) ⇒ Transform: Decompose a matrix into translation, scaling and rotation components, optionally take horizontal and vertical flip in to consideration. Note this function decomposes a matrix in rotation -> scaling -> translation order. I.e. for certain translation T {tx, ty}, rotation R and scaling S { sx, sy }, it's only true for: decomposeTSR(compose(T, S, R)) === { translate: T, rotation: R, scale: S } composing in a different order may yield a different decomposition result.
flipX() ⇒ Matrix: Tranformation matrix that mirrors on x-axis
flipY() ⇒ Matrix: Tranformation matrix that mirrors on y-axis
flipOrigin() ⇒ Matrix: Tranformation matrix that mirrors on origin
fromDefinition(definitionOrArrayOfDefinition) ⇒ Array.<Matrix>: Converts array of matrix descriptor to array of matrix
fromOneMovingPoint(startingPoint, endingPoint): Calculate a transformation matrix from a point that starts from A to A' This approach can be associated to a pointer that moves on a device
fromTwoMovingPoints(startingPoint1, startingPoint2, endingPoint1, endingPoint2): Calculate a transformation matrix about two points that move from positions A and B to A' and B' This approach can be associated to a two finger gesture on a touch device
fromObject(object) ⇒ Matrix: Extract an affine matrix from an object that contains a,b,c,d,e,f keys Any value could be a float or a string that contains a float
fromString(string) ⇒ Matrix: Parse a string formatted as matrix(a,b,c,d,e,f)
~~fromStringLegacy(string) ⇒ Matrix~~: Parse a string formatted as matrix(a,b,c,d,e,f) - Legacy implementation of fromString(matrix); Read this PR for details https://github.com/chrvadala/transformation-matrix/pull/107
fromTransformAttribute(transformString) ⇒ Array.<MatrixDescriptor>: Parser for SVG Trasform Attribute http://www.w3.org/TR/SVG/coords.html#TransformAttribute
fromTriangles(t1, t2) ⇒ Matrix: Returns a matrix that transforms a triangle t1 into another triangle t2, or throws an exception if it is impossible.
identity() ⇒ Matrix: Identity matrix
inverse(matrix) ⇒ Matrix: Calculate a matrix that is the inverse of the provided matrix
isAffineMatrix(object) ⇒ boolean: Check if the object contain an affine matrix
rotate(angle, [cx], [cy]) ⇒ Matrix: Calculate a rotation matrix
rotateDEG(angle, [cx], [cy]) ⇒ Matrix: Calculate a rotation matrix with a DEG angle
scale(sx, [sy], [cx], [cy]) ⇒ Matrix: Calculate a scaling matrix
shear(shx, shy) ⇒ Matrix: Calculate a shear matrix
skew(ax, ay) ⇒ Matrix: Calculate a skew matrix
skewDEG(ax, ay) ⇒ Matrix: Calculate a skew matrix using DEG angles
smoothMatrix(matrix, [precision]) ⇒ Matrix: Rounds all elements of the given matrix using the given precision
toCSS(matrix) ⇒ string: Serialize an affine matrix to a string that can be used with CSS or SVG
toSVG(matrix) ⇒ string: Serialize an affine matrix to a string that can be used with CSS or SVG
toString(matrix) ⇒ string: Serialize an affine matrix to a string that can be used with CSS or SVG
transform(matrices) ⇒ Matrix: Merge multiple matrices into one
compose(matrices) ⇒ Matrix: Merge multiple matrices into one
translate(tx, [ty]) ⇒ Matrix: Calculate a translate matrix

Data Model

A transformation Matrix is defined as a Plain Object with 6 keys: a, b, c, d, e and f.

const matrix = {
a: 1, c: 0, e: 0,
b: 0, d: 1, f: 0
}

A Point can be defined in two different ways:

as Plain Object, with inside two keys: x and y

const point = { x: 24, y: 42 }

as Array, with two items in the form [x, y]

const point = [ 24, 42 ]

Specs

applyToPoint(matrix, point) ⇒ `Point`

Calculate a point transformed with an affine matrix

Kind: global function
Returns: Point - Point

Param	Type	Description
matrix	`Matrix`	Affine Matrix
point	`Point`	Point

applyToPoints(matrix, points) ⇒ `Array.<Point>`

Calculate an array of points transformed with an affine matrix

Kind: global function
Returns: Array.<Point> - Array of point

Param	Type	Description
matrix	`Matrix`	Affine Matrix
points	`Array.<Point>`	Array of point

decomposeTSR(matrix, flipX, flipY) ⇒ `Transform`

Decompose a matrix into translation, scaling and rotation components, optionally take horizontal and vertical flip in to consideration. Note this function decomposes a matrix in rotation -> scaling -> translation order. I.e. for certain translation T {tx, ty}, rotation R and scaling S { sx, sy }, it's only true for: decomposeTSR(compose(T, S, R)) === { translate: T, rotation: R, scale: S } composing in a different order may yield a different decomposition result.

Kind: global function
Returns: Transform - A transform object consisted by its translation, scaling and rotation components.

Param	Type	Description
matrix	`Matrix`	Affine Matrix
flipX	`boolean`	Whether the matrix contains vertical flip, i.e. mirrors on x-axis
flipY	`boolean`	Whether the matrix contains horizontal flip, i.e. mirrors on y-axis

flipX() ⇒ `Matrix`

Tranformation matrix that mirrors on x-axis

Kind: global function
Returns: Matrix - Affine Matrix

flipY() ⇒ `Matrix`

Tranformation matrix that mirrors on y-axis

Kind: global function
Returns: Matrix - Affine Matrix

flipOrigin() ⇒ `Matrix`

Tranformation matrix that mirrors on origin

Kind: global function
Returns: Matrix - Affine Matrix

fromDefinition(definitionOrArrayOfDefinition) ⇒ `Array.<Matrix>`

Converts array of matrix descriptor to array of matrix

Kind: global function
Returns: Array.<Matrix> - Array of matrix

Param	Type	Description
definitionOrArrayOfDefinition	`Array.<Object>`	Array of object describing the matrix

Example

> fromDefinition([
 { type: 'matrix', a:1, b:2, c:3, d:4, e:5, f:6 },
 { type: 'translate', tx: 10, ty: 20 },
 { type: 'scale', sx: 2, sy: 4 },
 { type: 'rotate', angle: 90, cx: 50, cy: 25 },
 { type: 'skewX', angle: 45 },
 { type: 'skewY',  angle: 45 },
 { type: 'shear', shx: 10, shy: 20}
])

[
 { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 },
 { a: 1, c: 0, e: 10, b: 0, d: 1, f: 20 },
 { a: 2, c: 0, e: 0, b: 0, d: 4, f: 0 },
 { a: 6.123, c: -1, e: 0, b: 1, d: 6.123, f: 0 },
 { a: 1, c: 0.99.., e: 0, b: 0, d: 1, f: 0 },
 { a: 1, c: 0, e: 0, b: 0.99, d: 1, f: 0 },
 { a: 1, c: 10, e: 0, b: 20, d: 1, f: 0 }
]

fromOneMovingPoint(startingPoint, endingPoint)

Calculate a transformation matrix from a point that starts from A to A' This approach can be associated to a pointer that moves on a device

Kind: global function

Param	Type	Description
startingPoint	`Point`	Starting point (A)
endingPoint	`Point`	Ending point (A')

fromTwoMovingPoints(startingPoint1, startingPoint2, endingPoint1, endingPoint2)

Calculate a transformation matrix about two points that move from positions A and B to A' and B' This approach can be associated to a two finger gesture on a touch device

Kind: global function

Param	Type	Description
startingPoint1	`Point`	Starting Point (A)
startingPoint2	`Point`	Starting Point (B)
endingPoint1	`Point`	Ending point (A')
endingPoint2	`Point`	Ending Point (B')

fromObject(object) ⇒ `Matrix`

Extract an affine matrix from an object that contains a,b,c,d,e,f keys Any value could be a float or a string that contains a float

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
object	`Object`	Object that contains a,b,c,d,e,f keys

fromString(string) ⇒ `Matrix`

Parse a string formatted as matrix(a,b,c,d,e,f)

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
string	`string`	String with an affine matrix

Example

> fromString('matrix(1,2,3,4,5,6)')
{a: 1, b: 2, c: 3, d: 4, c: 5, e: 6}

fromStringLegacy(string) ⇒ `Matrix`

Deprecated

Parse a string formatted as matrix(a,b,c,d,e,f) - Legacy implementation of fromString(matrix); Read this PR for details https://github.com/chrvadala/transformation-matrix/pull/107

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
string	`string`	String with an affine matrix

Example

> fromStringLegacy('matrix(1,2,3,4,5,6)')
{a: 1, b: 2, c: 3, d: 4, c: 5, e: 6}

fromTransformAttribute(transformString) ⇒ `Array.<MatrixDescriptor>`

Parser for SVG Trasform Attribute http://www.w3.org/TR/SVG/coords.html#TransformAttribute

Kind: global function
Returns: Array.<MatrixDescriptor> - Array of MatrixDescriptor

Param	Type	Description
transformString	`string`	Transform string as defined by w3 Consortium

Example

> fromTransformAttribute('translate(-10,-10) scale(2,2) translate(10,10)')
[
 { type: 'translate', tx: -10, ty: -10},
 { type: 'scale', sx: 2, sy: 2 },
 { type: 'translate', tx: 10, ty: 10}
]

> compose(fromDefinition(fromTransformAttribute('translate(-10, -10) scale(10, 10)')))
{ a: 10, c: 0, e: -10, b: 0, d: 10, f: -10 }

fromTriangles(t1, t2) ⇒ `Matrix`

Returns a matrix that transforms a triangle t1 into another triangle t2, or throws an exception if it is impossible.

Kind: global function
Returns: Matrix - Matrix which transforms t1 to t2
Throws:

Exception if the matrix becomes not invertible

Param	Type	Description
t1	`Array.<Point>`	Array of points containing the three points for the first triangle
t2	`Array.<Point>`	Array of points containing the three points for the second triangle

identity() ⇒ `Matrix`

Identity matrix

Kind: global function
Returns: Matrix - Affine Matrix

inverse(matrix) ⇒ `Matrix`

Calculate a matrix that is the inverse of the provided matrix

Kind: global function
Returns: Matrix - Inverted Affine Matrix

Param	Type	Description
matrix	`Matrix`	Affine Matrix

isAffineMatrix(object) ⇒ `boolean`

Check if the object contain an affine matrix

Kind: global function
Returns: boolean - True if is an object and contains an affine matrix

Param	Type	Description
object	`Object`	Generic Plain Object

rotate(angle, [cx], [cy]) ⇒ `Matrix`

Calculate a rotation matrix

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
angle	`number`	Angle in radians
[cx]	`number`	If (cx,cy) are supplied the rotate is about this point
[cy]	`number`	If (cx,cy) are supplied the rotate is about this point

rotateDEG(angle, [cx], [cy]) ⇒ `Matrix`

Calculate a rotation matrix with a DEG angle

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
angle	`number`	Angle in degree
[cx]	`number`	If (cx,cy) are supplied the rotate is about this point
[cy]	`number`	If (cx,cy) are supplied the rotate is about this point

scale(sx, [sy], [cx], [cy]) ⇒ `Matrix`

Calculate a scaling matrix

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Default	Description
sx	`number`		Scaling on axis x
[sy]	`number`	`sx`	Scaling on axis y (default sx)
[cx]	`number`		If (cx,cy) are supplied the scaling is about this point
[cy]	`number`		If (cx,cy) are supplied the scaling is about this point

shear(shx, shy) ⇒ `Matrix`

Calculate a shear matrix

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
shx	`number`	Shear on axis x
shy	`number`	Shear on axis y

skew(ax, ay) ⇒ `Matrix`

Calculate a skew matrix

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
ax	`number`	Skew on axis x
ay	`number`	Skew on axis y

skewDEG(ax, ay) ⇒ `Matrix`

Calculate a skew matrix using DEG angles

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
ax	`number`	Skew on axis x
ay	`number`	Skew on axis y

smoothMatrix(matrix, [precision]) ⇒ `Matrix`

Rounds all elements of the given matrix using the given precision

Kind: global function
Returns: Matrix - The rounded Affine Matrix

Param	Type	Description
matrix	`Matrix`	An affine matrix to round
[precision]	`number`	A precision to use for Math.round. Defaults to 10000000000 (meaning which rounds to the 10th digit after the comma).

toCSS(matrix) ⇒ `string`

Serialize an affine matrix to a string that can be used with CSS or SVG

Kind: global function
Returns: string - String that contains an affine matrix formatted as matrix(a,b,c,d,e,f)

Param	Type	Description
matrix	`Matrix`	Affine Matrix

toSVG(matrix) ⇒ `string`

Serialize an affine matrix to a string that can be used with CSS or SVG

Kind: global function
Returns: string - String that contains an affine matrix formatted as matrix(a,b,c,d,e,f)

Param	Type	Description
matrix	`Matrix`	Affine Matrix

toString(matrix) ⇒ `string`

Serialize an affine matrix to a string that can be used with CSS or SVG

Kind: global function
Returns: string - String that contains an affine matrix formatted as matrix(a,b,c,d,e,f)

Param	Type	Description
matrix	`Matrix`	Affine Matrix

transform(matrices) ⇒ `Matrix`

Merge multiple matrices into one

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
matrices	`Matrix` \| `Array.<Matrix>`	Matrices listed as separate parameters or in an array

compose(matrices) ⇒ `Matrix`

Merge multiple matrices into one

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
matrices	`Matrix` \| `Array.<Matrix>`	Matrices listed as separate parameters or in an array

translate(tx, [ty]) ⇒ `Matrix`

Calculate a translate matrix

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Default	Description
tx	`number`		Translation on axis x
[ty]	`number`	`0`	Translation on axis y