transformation-matrix

What is transformation-matrix?

The 'transformation-matrix' npm package provides a set of utilities for working with 2D affine transformations. It allows you to create, manipulate, and apply transformation matrices for operations such as translation, rotation, scaling, and skewing.

What are transformation-matrix's main functionalities?

Translation

This feature allows you to create a translation matrix that moves points by a specified distance along the x and y axes.

const { translate } = require('transformation-matrix');
const translationMatrix = translate(10, 20);
console.log(translationMatrix);

Rotation

This feature allows you to create a rotation matrix that rotates points by a specified angle in radians.

const { rotate } = require('transformation-matrix');
const rotationMatrix = rotate(Math.PI / 4);
console.log(rotationMatrix);

Scaling

This feature allows you to create a scaling matrix that scales points by specified factors along the x and y axes.

const { scale } = require('transformation-matrix');
const scalingMatrix = scale(2, 3);
console.log(scalingMatrix);

Skewing

This feature allows you to create a skewing matrix that skews points by specified angles along the x and y axes.

const { skew } = require('transformation-matrix');
const skewingMatrix = skew(0.5, 0.3);
console.log(skewingMatrix);

Combining Transformations

This feature allows you to combine multiple transformation matrices into a single matrix.

const { compose, translate, rotate, scale } = require('transformation-matrix');
const combinedMatrix = compose(translate(10, 20), rotate(Math.PI / 4), scale(2, 3));
console.log(combinedMatrix);

Other packages similar to transformation-matrix

gl-matrix

The 'gl-matrix' package is a high-performance matrix and vector library for WebGL. It provides similar functionalities for 2D and 3D transformations, but is more focused on performance and is widely used in graphics programming.

transformation-matrix-js

The 'transformation-matrix-js' package offers similar functionalities for 2D transformations, including translation, rotation, scaling, and skewing. It is a lightweight alternative with a focus on simplicity.

matrix-js

The 'matrix-js' package provides general-purpose matrix operations, including those for 2D transformations. It is more versatile but less specialized compared to 'transformation-matrix'.

README

transformation-matrix

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

Usage example (ES6)

import {scale, rotate, translate, transform, applyToPoint} from 'transformation-matrix';
let {scale, rotate, translate, transform, applyToPoint} = window.TransformationMatrix;
let {scale, rotate, translate, transform, applyToPoint} = require('transformation-matrix')

let matrix = transform(
  translate(40,40),
  rotate(Math.PI/2),
  scale(2, 4)
);
let point = applyToPoint(matrix, {x: 42, y: 42});

Setup

npm install transformation-matrix
# or
yarn add transformation-matrix

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

Live Demo

available at http://chrvadala.github.io/transformation-matrix/

Reference

Functions

applyToPoint(matrix, point) ⇒ Object

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, generateMatrices) ⇒ Object

Parse 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

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

translate(tx, [ty]) ⇒ Object

Calculate a translate matrix

Changelog

• 0.0 - Preview version
• 1.0 - First public version
• 1.1 - Split lib into different files
• 1.2 - Adds shear operation
• 1.3 - Adds umd support
• 1.4 - Adds typescript definitions
• 1.5 - Upgrade deps
• 1.6 - Adds optional parameter support on translate(tx), scale(sx), rotate(angle, cx, cy)
• 1.7 - Upgrade deps
• 1.8 - Fixes #12, Adds fromTransformAttribute, Discontinues node 4 support

Some projects using transformation-matrix

• React Planner
• React SVG Pan Zoom
• Others...
• Pull request your project!

Contributors

• chrvadala (author)
• forabi (TypeScript definitions)
• nidu (PEG.js descriptor)

API

applyToPoint(matrix, point) ⇒ Object

Calculate a point transformed with an affine matrix

Kind: global function
Returns: Object - 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, generateMatrices) ⇒ Object

Parse 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
generateMatrices	boolean

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

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

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