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.<Matrix>: 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

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.<Matrix>`

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.<Matrix> - 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	`Array.<Matrix>`	Array of affine matrix

compose(matrices) ⇒ `Matrix`

Merge multiple matrices into one

Kind: global function
Returns: Matrix - Affine Matrix

Param	Type	Description
matrices	`Array.<Matrix>`	Array of matrix

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

Name		Name	Last commit message	Last commit date
Latest commit History 203 Commits
.github		.github
src		src
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
README.template.hbs		README.template.hbs
babel.config.js		babel.config.js
disclaimer.hbs		disclaimer.hbs
example.js		example.js
index.html		index.html
package.json		package.json
transformation-matrix.d.ts		transformation-matrix.d.ts
webpack-umd.config.js		webpack-umd.config.js
yarn.lock		yarn.lock

License

estollnitz/transformation-matrix

Folders and files

Latest commit

History

Repository files navigation

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.<Matrix>

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

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

applyToPoint(matrix, point) ⇒ `Point`

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

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

fromObject(object) ⇒ `Matrix`

fromString(string) ⇒ `Matrix`

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

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`

Packages