transformation-matrix

Javascript isomorphic 2D affine transformations written in ES6 syntax. Manipulate transformation matrices with this totally tested library!

Transformations, i.e. linear invertible automorphisms, are used to map a picture into another one with different size, position and orientation. Given a basis, transformations are represented by means of squared invertible matrices, called transformation matrices. A geometric transformation is defined as a one-to-one mapping of a point space to itself, which preservers some geometric relations of figures. - Geometric Programming for Computer Aided Design

This library allows us to:

generate transformation matrices for the following operations: translation, rotation, scale, shear, skew
merge multiple transformation matrices in a single matrix that is the composition of multiple matrices
work with strings in both directions: parse, render
apply a transformation matrix to point(s)

Usage example (ES6)

import {scale, rotate, translate, compose, applyToPoint} from 'transformation-matrix';
let {scale, rotate, translate, compose, applyToPoint} = window.TransformationMatrix;
let {scale, rotate, translate, compose, applyToPoint} = require('transformation-matrix')

let matrix = compose(
  translate(40,40),
  rotate(Math.PI/2),
  scale(2, 4)
);

applyToPoint(matrix, {x: 42, y: 42});
// { x: -128, y: 124.00000000000001 }

applyToPoint(matrix, [16, 24]);
//  [ -56, 72 ]

Setup

npm install transformation-matrix
# or
yarn add transformation-matrix

<script src="https://unpkg.com/transformation-matrix@2"></script>

Reference

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
fromDefinition(definitionOrArrayOfDefinition) ⇒ Array.<Matrix>: Converts array of matrix descriptor to array of matrix
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)
fromTransformAttribute(transformString) ⇒ Array.<MatrixDescriptor>: Parser for SVG Trasform Attribute http://www.w3.org/TR/SVG/coords.html#TransformAttribute
Warning: This should be considered BETA until it is released a stable version of pegjs.
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]) ⇒ 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

Changelog

0.0 - Preview version
1.0 - First public version
1.1 - Splits lib into different files
1.2 - Adds shear operation
1.3 - Adds umd support
1.4 - Adds typescript definitions
1.5 - Upgrades deps
1.6 - Adds optional parameter support on translate(tx), scale(sx), rotate(angle, cx, cy)
1.7 - Upgrades deps
1.8 - Fixes #12, Adds fromTransformAttribute, Discontinues node 4 support
1.9 - Adds skew(ax, ay), Upgrades deps, Improves fromTransformAttribute
1.10- Updates typescript definitions #15
1.11- Upgrades deps
1.12- Migrates tests on Jest, Integrates standard.js, Upgrades deps
1.13- Adds compose function, Upgrades deps, Exposes skew operation #37
1.14- Adds support for points defined as Array in the form [x, y] #38
1.15- Adds fromTriangle and smoothMatrix functions #41
2.0- Migrates to Babel 7 and updates dependencies; introduces fromDefinition function; breaking changes on fromTransformAttribute function; improves docs
2.1- Upgrades deps; Adds Node.js v12 to CI
2.2- Upgrades deps; Improves typescript definition #66

API

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 ]

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

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 }
]

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}

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

Parser for SVG Trasform Attribute http://www.w3.org/TR/SVG/coords.html#TransformAttribute
Warning: This should be considered BETA until it is released a stable version of pegjs.

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]) ⇒ `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)

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

niwinz / transformation-matrix

transformation-matrix

Usage example (ES6)

Setup

Reference

Functions

Changelog

API

Data Model

applyToPoint(matrix, point) ⇒ `Point`

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

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

fromObject(object) ⇒ `Matrix`

fromString(string) ⇒ `Matrix`

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

fromTriangles(t1, t2) ⇒ `Matrix`

identity() ⇒ `Matrix`

inverse(matrix) ⇒ `Matrix`

isAffineMatrix(object) ⇒ `boolean`

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

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

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

shear(shx, shy) ⇒ `Matrix`

skew(ax, ay) ⇒ `Matrix`

skewDEG(ax, ay) ⇒ `Matrix`

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

toCSS(matrix) ⇒ `string`

toSVG(matrix) ⇒ `string`

toString(matrix) ⇒ `string`

transform(matrices) ⇒ `Matrix`

compose(matrices) ⇒ `Matrix`

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

Some projects using transformation-matrix

Contributors

About

Languages

transformation-matrix

Usage example (ES6)

Setup

Reference

Functions

Changelog

API

Data Model

applyToPoint(matrix, point) ⇒ Point

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

fromDefinition(definitionOrArrayOfDefinition) ⇒ Array.<Matrix>

fromObject(object) ⇒ Matrix

fromString(string) ⇒ Matrix

fromTransformAttribute(transformString) ⇒ Array.<MatrixDescriptor>

fromTriangles(t1, t2) ⇒ Matrix

identity() ⇒ Matrix

inverse(matrix) ⇒ Matrix

isAffineMatrix(object) ⇒ boolean

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

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

scale(sx, [sy]) ⇒ Matrix

shear(shx, shy) ⇒ Matrix

skew(ax, ay) ⇒ Matrix

skewDEG(ax, ay) ⇒ Matrix

smoothMatrix(matrix, [precision]) ⇒ Matrix

toCSS(matrix) ⇒ string

toSVG(matrix) ⇒ string

toString(matrix) ⇒ string

transform(matrices) ⇒ Matrix

compose(matrices) ⇒ Matrix

translate(tx, [ty]) ⇒ Matrix

Some projects using transformation-matrix

Contributors

About

Languages

applyToPoint(matrix, point) ⇒ `Point`

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

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

fromObject(object) ⇒ `Matrix`

fromString(string) ⇒ `Matrix`

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

fromTriangles(t1, t2) ⇒ `Matrix`

identity() ⇒ `Matrix`

inverse(matrix) ⇒ `Matrix`

isAffineMatrix(object) ⇒ `boolean`

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

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

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

shear(shx, shy) ⇒ `Matrix`

skew(ax, ay) ⇒ `Matrix`

skewDEG(ax, ay) ⇒ `Matrix`

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

toCSS(matrix) ⇒ `string`

toSVG(matrix) ⇒ `string`

toString(matrix) ⇒ `string`

transform(matrices) ⇒ `Matrix`

compose(matrices) ⇒ `Matrix`

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