# transformation-matrix Javascript isomorphic 2D affine transformations written in ES6 syntax. Manipulate transformation matrices with this totally tested library! [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard.js-brightgreen.svg)](https://standardjs.com) [![Build Status](https://travis-ci.org/chrvadala/transformation-matrix.svg?branch=master)](https://travis-ci.org/chrvadala/transformation-matrix) [![Coverage Status](https://coveralls.io/repos/github/chrvadala/transformation-matrix/badge.svg?branch=master)](https://coveralls.io/github/chrvadala/transformation-matrix?branch=master) [![npm](https://img.shields.io/npm/v/transformation-matrix.svg?maxAge=2592000?style=plastic)](https://www.npmjs.com/package/transformation-matrix) [![Downloads](https://img.shields.io/npm/dm/transformation-matrix.svg)](https://www.npmjs.com/package/transformation-matrix) [![Donate](https://img.shields.io/badge/donate-PayPal-green.svg)](https://www.paypal.me/chrvadala/25) 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](https://books.google.it/books?vid=ISBN9780471899426) 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) ```js 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 ```sh npm install transformation-matrix # or yarn add transformation-matrix ``` ```html ``` ## Data Model A **Transformation Matrix** is defined as an `Object` with 6 keys: `a`, `b`, `c`, `d`, `e` and `f`. ```js const matrix = { a: 1, c: 0, e: 0, b: 0, d: 1, f: 0 } ``` A **Point** can be defined in two different ways: - as `Object`, with inside two keys: `x` and `y` ```js const point = { x: 24, y: 42 } ``` - as `Array`, with two items in the form `[x, y]` ```js const point = [ 24, 42 ] ``` ## Live Demo available at [http://chrvadala.github.io/transformation-matrix/](http://chrvadala.github.io/transformation-matrix/) # Reference ## Functions
applyToPoint(matrix, point)Object | Array

Calculate a point transformed with an affine matrix

applyToPoints(matrix, points)array

Calculate an array of points transformed with an affine matrix

fromObject(object)Object

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

fromString(string)Object

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

fromTransformAttribute(transformString)Object

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)Object

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

identity()Object

Identity matrix

inverse(matrix)Object

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])Object

Calculate a rotation matrix

rotateDEG(angle, [cx], [cy])Object

Calculate a rotation matrix with a DEG angle

scale(sx, [sy])Object

Calculate a scaling matrix

shear(shx, shy)Object

Calculate a shear matrix

skew(ax, ay)Object

Calculate a skew matrix

skewDEG(ax, ay)Object

Calculate a skew matrix using DEG angles

smoothMatrix(m, [precision])Object

Rounds all elements of the given matrix using the given precision

toCSS(matrix)string

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

toSVG(matrix)string

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

toString(matrix)string

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

transform(...matrices)Object

Merge multiple matrices into one

compose(...matrices)Object

Merge multiple matrices into one (alias of transform)

translate(tx, [ty])Object

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](https://github.com/chrvadala/transformation-matrix/issues/12), Adds `fromTransformAttribute`, Discontinues node 4 support - **1.9** - Adds `skew(ax, ay)`, Upgrades deps, Improves `fromTransformAttribute` - **1.10**- Updates typescript definitions [#15](https://github.com/chrvadala/transformation-matrix/pull/15) - **1.11**- Upgrades deps - **1.12**- Migrates tests on [Jest](https://jestjs.io/), Integrates [standard.js](https://standardjs.com/), Upgrades deps - **1.13**- Adds `compose` function, Upgrades deps, Exposes skew operation [#37](https://github.com/chrvadala/transformation-matrix/pull/37) - **1.14**- Adds support for points defined as `Array` in the form `[x, y]` [#38](https://github.com/chrvadala/transformation-matrix/pull/38) - **1.15**- Adds `fromTriangle` and `smoothMatrix` functions [#41](https://github.com/chrvadala/transformation-matrix/issues/41) ## Some projects using transformation-matrix - [**React Planner**](https://github.com/cvdlab/react-planner) - [**React SVG Pan Zoom**](https://github.com/chrvadala/react-svg-pan-zoom) - [**ngx-graph**](https://github.com/swimlane/ngx-graph) - [**learn-anything**](https://github.com/learn-anything/learn-anything) - [**Others...**](https://github.com/chrvadala/transformation-matrix/network/dependents) - Pull request your project! ## Contributors - [chrvadala](https://github.com/chrvadala) (author) - [forabi](https://github.com/forabi) - [nidu](https://github.com/nidu) (PEG.js descriptor) - [aubergene](https://github.com/aubergene) - [SophiaLi1](https://github.com/SophiaLi1) # API ## applyToPoint(matrix, point) ⇒ Object \| Array Calculate a point transformed with an affine matrix **Kind**: global function **Returns**: Object \| Array - Point | Param | Description | | --- | --- | | matrix | Affine matrix | | point | Point | ## applyToPoints(matrix, points) ⇒ array Calculate an array of points transformed with an affine matrix **Kind**: global function **Returns**: array - Array of points | Param | Description | | --- | --- | | matrix | Affine matrix | | points | Array of points | ## fromObject(object) ⇒ Object Extract an affine matrix from an object that contains a,b,c,d,e,f keys Each value could be a float or a string that contains a float **Kind**: global function **Returns**: Object - } | Param | | --- | | object | ## fromString(string) ⇒ Object Parse a string matrix formatted as matrix(a,b,c,d,e,f) **Kind**: global function **Returns**: Object - Affine matrix | Param | Description | | --- | --- | | string | String with a matrix | ## fromTransformAttribute(transformString) ⇒ Object 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**: Object - Parsed matrices | Param | Description | | --- | --- | | transformString | string | ## fromTriangles(t1, t2) ⇒ Object Returns a matrix that transforms a triangle t1 into another triangle t2, or throws an exception if it is impossible. **Kind**: global function **Returns**: Object - Affine matrix which transforms t1 to t2 **Throws**: - Exception if the matrix becomes not invertible | Param | Type | Description | | --- | --- | --- | | t1 | Array.<{x: number, y: number}> \| Array.<Array.<number>> | an array of points containing the three points for the first triangle | | t2 | Array.<{x: number, y: number}> \| Array.<Array.<number>> | an array of points containing the three points for the second triangle | ## identity() ⇒ Object Identity matrix **Kind**: global function **Returns**: Object - Affine matrix ## inverse(matrix) ⇒ Object Calculate a matrix that is the inverse of the provided matrix **Kind**: global function **Returns**: Object - Affine matrix | Param | Description | | --- | --- | | matrix | Affine matrix | ## isAffineMatrix(object) ⇒ boolean Check if the object contain an affine matrix **Kind**: global function | Param | | --- | | object | ## rotate(angle, [cx], [cy]) ⇒ Object Calculate a rotation matrix **Kind**: global function **Returns**: Object - Affine matrix * | Param | Description | | --- | --- | | angle | Angle in radians | | [cx] | If (cx,cy) are supplied the rotate is about this point | | [cy] | If (cx,cy) are supplied the rotate is about this point | ## rotateDEG(angle, [cx], [cy]) ⇒ Object Calculate a rotation matrix with a DEG angle **Kind**: global function **Returns**: Object - Affine matrix | Param | Description | | --- | --- | | angle | Angle in degree | | [cx] | If (cx,cy) are supplied the rotate is about this point | | [cy] | If (cx,cy) are supplied the rotate is about this point | ## scale(sx, [sy]) ⇒ Object Calculate a scaling matrix **Kind**: global function **Returns**: Object - Affine matrix | Param | Default | Description | | --- | --- | --- | | sx | | Scaling on axis x | | [sy] | sx | Scaling on axis y (default sx) | ## shear(shx, shy) ⇒ Object Calculate a shear matrix **Kind**: global function **Returns**: Object - Affine matrix | Param | Description | | --- | --- | | shx | Shear on axis x | | shy | Shear on axis y | ## skew(ax, ay) ⇒ Object Calculate a skew matrix **Kind**: global function **Returns**: Object - Affine matrix | Param | Description | | --- | --- | | ax | Skew on axis x | | ay | Skew on axis y | ## skewDEG(ax, ay) ⇒ Object Calculate a skew matrix using DEG angles **Kind**: global function **Returns**: Object - Affine matrix | Param | Description | | --- | --- | | ax | Skew on axis x | | ay | Skew on axis y | ## smoothMatrix(m, [precision]) ⇒ Object Rounds all elements of the given matrix using the given precision **Kind**: global function **Returns**: Object - the rounded matrix | Param | Type | Description | | --- | --- | --- | | m | Object | a matrix to round | | [precision] | | a precision to use for Math.round. Defaults to 10000000000 (meaning which rounds to the 10th digit after the comma). | ## toCSS(matrix) ⇒ string Serialize the matrix to a string that can be used with CSS or SVG **Kind**: global function **Returns**: string - String that contains a matrix formatted as matrix(a,b,c,d,e,f) | Param | Description | | --- | --- | | matrix | Affine matrix | ## toSVG(matrix) ⇒ string Serialize the matrix to a string that can be used with CSS or SVG **Kind**: global function **Returns**: string - String that contains a matrix formatted as matrix(a,b,c,d,e,f) | Param | Description | | --- | --- | | matrix | Affine matrix | ## toString(matrix) ⇒ string Serialize the matrix to a string that can be used with CSS or SVG **Kind**: global function **Returns**: string - String that contains a matrix formatted as matrix(a,b,c,d,e,f) | Param | Description | | --- | --- | | matrix | Affine matrix | ## transform(...matrices) ⇒ Object Merge multiple matrices into one **Kind**: global function **Returns**: Object - Affine matrix | Param | Type | Description | | --- | --- | --- | | ...matrices | object | list of matrices | ## compose(...matrices) ⇒ Object Merge multiple matrices into one (alias of `transform`) **Kind**: global function **Returns**: Object - Affine matrix | Param | Type | Description | | --- | --- | --- | | ...matrices | object | list of matrices | ## translate(tx, [ty]) ⇒ Object Calculate a translate matrix **Kind**: global function **Returns**: Object - Affine matrix | Param | Default | Description | | --- | --- | --- | | tx | | Translation on axis x | | [ty] | 0 | Translation on axis y |