transformation-matrix

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



Features

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)
- decompose a matrix into translation, scaling and rotation components, with flip decomposition support

Documentation

- How to handle gestures with transformation-matrix
- APIs
- Basic Operations
- identity()
- flipX()
- flipY()
- flipOrigin()
- [rotate(angle, [cx], [cy])](https://github.com/chrvadala/transformation-matrix/blob/main/docs/api.md#rotate)
- [rotateDEG(angle, [cx], [cy])](https://github.com/chrvadala/transformation-matrix/blob/main/docs/api.md#rotateDEG)
- [scale(sx, [sy], [cx], [cy])](https://github.com/chrvadala/transformation-matrix/blob/main/docs/api.md#scale)
- shear(shx, shy)
- skew(ax, ay)
- skewDEG(ax, ay)
- [smoothMatrix(matrix, [precision])](https://github.com/chrvadala/transformation-matrix/blob/main/docs/api.md#smoothMatrix)
- [translate(tx, [ty])](https://github.com/chrvadala/transformation-matrix/blob/main/docs/api.md#translate)
- inverse(matrix)

- Calculate
- fromDefinition(definitionOrArrayOfDefinition)
- fromObject(object)
- fromString(string)
- fromTransformAttribute(transformString)
- fromTriangles(t1, t2)

- Validate
- isAffineMatrix(object)

- Apply
- applyToPoint(matrix, point)
- applyToPoints(matrix, points)

- Stringify
- toCSS(matrix)
- toSVG(matrix)
- toString(matrix)

- Compose
- transform(matrices)
- compose(matrices)

- Decompose
- decomposeTSR(matrix, flipX, flipY)

- Moving points (gestures)
- fromOneMovingPoint (startingPoint, endingPoint)
- fromTwoMovingPoints (startingPoint1, startingPoint2, endingPoint1, endingPoint2)

Install

``sh
npm install transformation-matrix
`
or
`html

`

Example

`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 ]
`

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
- 2.7- Upgrades deps;
- 2.8- Upgrades deps;
- 2.9- Adds flipX(), flipY(), flipOrigin() functions; Deprecates NodeJS 12 and adds NodeJS 16 support; Upgrades deps;
- 2.10 - Adds decomposeTSR() function #88; Upgrades deps;
- 2.11 - Migrates from yarn to npm; Upgrades deps; New APIs documentation; Integrates chrvadala/github-actions;
- 2.12 - Migrates from PEG.js to Peggy #89; Upgrades deps;
- 2.13 - Upgrades deps; Improves typescript definition; Upgrades gh-actions deps;
- 2.14 - Upgrades deps; Adds fromOneMovingPoint and fromTwoMovingPoints` functions #95
- 2.15 - Removes circular dependencies #97; Upgrades gh-actions and deps
- 2.16 - Upgrades deps; Upgrades gh-actions deps;
- 3.0 - Refactors fromString #107 (⚠️ Breaking Changes described here); Upgrades gh-actions and deps;
- 3.1 - Upgrades gh-actions and deps; Deprecates NodeJS 16,18 and adds 22

Contributors

- chrvadala (author)
- forabi
- nidu (PEG.js descriptor)
- aubergene
- SophiaLi1
- Shuhei-Tsunoda
- antonyRoberts
- mcwebb
- signalwerk
- estollnitz
- rodrigoapereira
- formatlos
- benhjames
- hillin
- jedrzejchalubek

Some projects using transformation-matrix

- React Planner
- React SVG Pan Zoom
- ngx-graph
- learn-anything
- react-supergrid
- Others...
- Pull request your project!