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)
• decompose a matrix into translation, scaling and rotation components, with flip decomposition support

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

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

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], [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

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
• 2.3- Adds (cx,cy) on scale function #62; Improves typescript definition #66; Upgrades deps
• 2.4- Improves typescript definition #75
• 2.5- Upgrades deps; Deprecates NodeJS 8; Adds NodeJs 14 support
• 2.6- Upgrades deps; Fixes fromTransformAttribute function #84
• 2.7- Upgrades deps;
• 2.8- Upgrades deps;
• 2.9- Adds flipX(), flipY(), flipOrigin() functions; Deprecates NodeJS 12 and adds NodeJS 16 support; Upgrades deps;
• 2.10 - Adds decomposeTSR() function #88; Upgrades deps;

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 ]

A Transform (used in decomposeTSR) is defined as a Plain Object of the following shape:

interface Transform {
  translate: {
    tx: number,
    ty: number
  },
  rotation: number,
  scale: {
    sx: number,
    sy: number
  }
}

applyToPoint(matrix, point) ⇒ Point

Calculate a point transformed with an affine matrix

Kind: global function
Returns: 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

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.

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

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

fromString(string) ⇒ Matrix

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

Kind: global function
Returns: Matrix - 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

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

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

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

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

Calculate a rotation matrix

Kind: global function
Returns: Matrix - Affine Matrix

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

Calculate a rotation matrix with a DEG angle

Kind: global function
Returns: Matrix - Affine Matrix

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

Calculate a scaling matrix

Kind: global function
Returns: Matrix - Affine Matrix

shear(shx, shy) ⇒ Matrix

Calculate a shear matrix

Kind: global function
Returns: Matrix - Affine Matrix

skew(ax, ay) ⇒ Matrix

Calculate a skew matrix

Kind: global function
Returns: Matrix - Affine Matrix

skewDEG(ax, ay) ⇒ Matrix

Calculate a skew matrix using DEG angles

Kind: global function
Returns: Matrix - Affine Matrix

smoothMatrix(matrix, [precision]) ⇒ Matrix

Rounds all elements of the given matrix using the given precision

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

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)

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)

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)

transform(matrices) ⇒ Matrix

Merge multiple matrices into one

Kind: global function
Returns: Matrix - Affine Matrix

compose(matrices) ⇒ Matrix

Merge multiple matrices into one

Kind: global function
Returns: Matrix - Affine Matrix

translate(tx, [ty]) ⇒ Matrix

Calculate a translate matrix

Kind: global function
Returns: Matrix - Affine Matrix

Some projects using transformation-matrix

• React Planner
• React SVG Pan Zoom
• ngx-graph
• learn-anything
• Others...
• Pull request your project!

Contributors

• chrvadala (author)
• forabi
• nidu (PEG.js descriptor)
• aubergene
• SophiaLi1
• Shuhei-Tsunoda
• antonyRoberts
• mcwebb
• signalwerk
• estollnitz
• rodrigoapereira
• formatlos
• benhjames
• hillin