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@1"></script>

Data Model

A Transformation Matrix is defined as an 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 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 ]

Live Demo

available at 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, 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

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

API

applyToPoint(matrix, point) ⇒ Object | Array

Calculate a point transformed with an affine matrix

Kind: global function
Returns: Object | Array - Point

applyToPoints(matrix, points) ⇒ array

Calculate an array of points transformed with an affine matrix

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

fromString(string) ⇒ Object

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

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

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

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

isAffineMatrix(object) ⇒ boolean

Check if the object contain an affine matrix

Kind: global function

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

Calculate a rotation matrix

Kind: global function
Returns: Object - Affine matrix *

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

Calculate a rotation matrix with a DEG angle

Kind: global function
Returns: Object - Affine matrix

scale(sx, [sy]) ⇒ Object

Calculate a scaling matrix

Kind: global function
Returns: Object - Affine matrix

shear(shx, shy) ⇒ Object

Calculate a shear matrix

Kind: global function
Returns: Object - Affine matrix

skew(ax, ay) ⇒ Object

Calculate a skew matrix

Kind: global function
Returns: Object - Affine matrix

skewDEG(ax, ay) ⇒ Object

Calculate a skew matrix using DEG angles

Kind: global function
Returns: Object - Affine matrix

smoothMatrix(m, [precision]) ⇒ Object

Rounds all elements of the given matrix using the given precision

Kind: global function
Returns: Object - the rounded matrix

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)

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)

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)

transform(...matrices) ⇒ Object

Merge multiple matrices into one

Kind: global function
Returns: Object - Affine matrix

compose(...matrices) ⇒ Object

Merge multiple matrices into one (alias of transform)

Kind: global function
Returns: Object - Affine matrix

translate(tx, [ty]) ⇒ Object

Calculate a translate matrix

Kind: global function
Returns: Object - Affine matrix