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])
    • rotateDEG(angle, [cx], [cy])
    • scale(sx, [sy], [cx], [cy])
    • shear(shx, shy)
    • skew(ax, ay)
    • skewDEG(ax, ay)
    • smoothMatrix(matrix, [precision])
    • translate(tx, [ty])
    • 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

npm install transformation-matrix

or

<script src="https://unpkg.com/transformation-matrix@3"></script>

Example

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!