Skip to content

achenPDFTron/transformation-matrix-fork

BranchesTags

Repository files navigation

Informally forked and modified from https://github.com/achenPDFTron/transformation-matrix-fork Adjusted webpack and babel so that it creates minified file that works in IE11.

transformation-matrix

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

chrvadala Test 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@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.<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.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
  • 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.5- Upgrades deps; Deprecates NodeJS 8; Adds NodeJs 14 support
  • 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

Some projects using transformation-matrix

Contributors

About

fork and modification of https://github.com/chrvadala/transformation-matrix to make it build properly in IE11

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Sponsor this project

Packages

No packages published

Contributors 14

Languages