Awesome Open Source
Awesome Open Source

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
```
```<script src="https://unpkg.com/[email protected]"></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], [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.6 - Adds optional parameter support on `translate(tx)`, `scale(sx)`, `rotate(angle, cx, cy)`
• 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.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.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.6- Upgrades deps; Fixes fromTransformAttribute function #84

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

Contributors

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (70,860
matrix (149
zoom (75
scale (71
translate (65
transform (48