Javascript isomorphic 2D affine transformations written in ES6 syntax. Manipulate transformation matrices with this totally tested library!
Clone or download
Latest commit 904443e Sep 7, 2018

README.md

transformation-matrix

Javascript isomorphic 2D affine transformations written in ES6 syntax. Manipulate transformation matrices with this totally tested library!

JavaScript Style Guide Build Status Coverage Status npm Downloads Donate

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.

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

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

Some projects using transformation-matrix

Contributors

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

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

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