Matrix transformations made easy.

# Introduction Imagine a HTML element that may have a CSS transform applied. If we want to add 45° of Z-rotation, we have no way to handle this safely in CSS—we’d just risk overwriting an existing transform. So we decide to use JavaScript, and check the current transform... `getComputedStyle(element)` returns the computed styles, and inspecting the `transform` property shows: ```js 'matrix3d(0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)' ``` It’s here we discover that browsers actually use [transformation matrices](https://en.wikipedia.org/wiki/Transformation_matrix) under the hood to describe rotation, translation, scale and shear. This means if we wish to manage CSS transforms with JavaScript (without overwriting existing transformations), we’re stuck working with matrices. **Rematrix** is an easy way to create and combine matrix transformations that work seamlessly with CSS.
# Installation ## Browser A simple and fast way to get started is to include this script on your page: ```html ``` > If you use this method in production, be sure to specify a fixed version number, and use the minified distribution; e.g: `https://unpkg.com/rematrix@0.4.0/dist/rematrix.min.js`. This improves performance, but also prevents library changes from impacting your project. This will create the global variable `Rematrix`. ## Module ```bash npm install rematrix ``` #### CommonJS ```js const Rematrix = require('rematrix'); ``` #### ES2015 ```js import * as Rematrix from 'rematrix'; ```

# Guide ## Creating Transforms Most API methods look a lot like CSS, so for example, in CSS if we would write `transform: rotateZ(45deg)`, we can create the same transformation in JavaScript using Rematrix like this: ```js Rematrix.rotateZ(45) ``` This returns a 45° rotation along the Z-axis, represented as an array of 16 values: ```js [0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] ``` These 16 values represent our **transformation matrix** in [column-major order](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix3d).
## Combining Transforms (Using Multiplication) Where Rematrix really outshines CSS, is the ability to combine transforms — using **matrix multiplication**. We’ll recreate the same 45° rotation along the Z-axis, but using separate matrices this time: ```js var r1 = Rematrix.rotateZ(20); var r2 = Rematrix.rotateZ(25); var product = Rematrix.multiply(r1, r2); ``` Here `product` describes the same array of 16 values (seen above): ```js [0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] ``` #### Better Multiplication (Using Reduce) There’s a good chance we’ll need to multiply quite a few matrices together, so its helpful to store them in an array in order to use `Array.prototype.reduce` to multiply them all in one line: ```js var r1 = Rematrix.rotateZ(20); var r2 = Rematrix.rotateZ(65); var r3 = Rematrix.rotateZ(-40); var product = [r1, r2, r3].reduce(Rematrix.multiply); ``` > Order is very important. For example, rotating 45° along the Z-axis, followed by translating 500 pixels along the Y-axis... is not the same as translating 500 pixels along the Y-axis, followed by rotating 45° along on the Z-axis. ## Preserving Transforms Before applying any of our transforms, we should capture the existing transform of our element using `Rematrix.fromString()`, e.g: ```js var element = document.querySelector('#example'); var style = getComputedStyle(element).transform; var transform = Rematrix.fromString(style); var r1 = Rematrix.rotateZ(20); var r2 = Rematrix.rotateZ(65); var r3 = Rematrix.rotateZ(-40); var product = [transform, r1, r2, r3].reduce(Rematrix.multiply); ``` By passing the computed transform styles to `Rematrix.fromString()`, we create a matrix of the existing transform. We can now factor this into our multiplication. > The existing transformation has been _deliberately_ placed at the start of the array to ensure the computed transform is the foundation for the succeeding transformations. ## Applying Transforms We can turn our matrix into valid CSS using `Rematrix.toString()`, which we can apply to our element’s style, e.g: ```js element.style.transform = Rematrix.toString(product); ``` #### _And that concludes this introduction to Rematrix. Please explore the finished [Live Demo on JSFiddle](https://jsfiddle.net/utoqhkzc/)._

# API Reference * [Rematrix](#module_Rematrix) * [.fromString(source)](#module_Rematrix.fromString) * [.format(source)](#module_Rematrix.format) * [.identity()](#module_Rematrix.identity) * [.inverse(source)](#module_Rematrix.inverse) * [.multiply(m, x)](#module_Rematrix.multiply) * [.perspective(distance)](#module_Rematrix.perspective) * [.rotate(angle)](#module_Rematrix.rotate) * [.rotateX(angle)](#module_Rematrix.rotateX) * [.rotateY(angle)](#module_Rematrix.rotateY) * [.rotateZ(angle)](#module_Rematrix.rotateZ) * [.scale(scalar, [scalarY])](#module_Rematrix.scale) * [.scaleX(scalar)](#module_Rematrix.scaleX) * [.scaleY(scalar)](#module_Rematrix.scaleY) * [.scaleZ(scalar)](#module_Rematrix.scaleZ) * [.skew(angleX, [angleY])](#module_Rematrix.skew) * [.skewX(angle)](#module_Rematrix.skewX) * [.skewY(angle)](#module_Rematrix.skewY) * [.toString(source)](#module_Rematrix.toString) * [.translate(distanceX, [distanceY])](#module_Rematrix.translate) * [.translate3d(distanceX, distanceY, distanceZ)](#module_Rematrix.translate3d) * [.translateX(distance)](#module_Rematrix.translateX) * [.translateY(distance)](#module_Rematrix.translateY) * [.translateZ(distance)](#module_Rematrix.translateZ)
### Rematrix.fromString(source) ⇒ array Attempts to return a 4x4 matrix describing the CSS transform matrix passed in, but will return the identity matrix as a fallback. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ------ | ------------------- | ------------------------------------------- | | source | string | `matrix` or `matrix3d` CSS Transform value. |
### Rematrix.format(source) ⇒ array Transformation matrices in the browser come in two flavors: * `matrix` using 6 values (short) * `matrix3d` using 16 values (long) This utility follows this [conversion guide](https://goo.gl/EJlUQ1) to expand short form matrices to their equivalent long form. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ------ | ------------------ | ------------------------------------------ | | source | array | Accepts both short and long form matrices. |
### Rematrix.identity() ⇒ array Returns a matrix representing no transformation. The product of any matrix multiplied by the identity matrix will be the original matrix. > **Tip:** Similar to how `5 * 1 === 5`, where `1` is the identity. **Kind**: static method of [Rematrix](#module_Rematrix)
### Rematrix.inverse(source) ⇒ array Returns a matrix describing the inverse transformation of the source matrix. The product of any matrix multiplied by its inverse will be the identity matrix. > **Tip:** Similar to how `5 * (1/5) === 1`, where `1/5` is the inverse. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ------ | ------------------ | ------------------------------------------ | | source | array | Accepts both short and long form matrices. |
### Rematrix.multiply(m, x) ⇒ array Returns a 4x4 matrix describing the combined transformations of both arguments. > **Note:** Order is very important. For example, rotating 45° > along the Z-axis, followed by translating 500 pixels along the > Y-axis... is not the same as translating 500 pixels along the > Y-axis, followed by rotating 45° along on the Z-axis. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----- | ------------------ | ------------------------------------------ | | m | array | Accepts both short and long form matrices. | | x | array | Accepts both short and long form matrices. |
### Rematrix.perspective(distance) ⇒ array Returns a 4x4 matrix describing perspective. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | -------- | ------------------- | ------------------- | | distance | number | Measured in pixels. |
### Rematrix.rotate(angle) ⇒ array Returns a 4x4 matrix describing Z-axis rotation. > **Tip:** This is just an alias for `Rematrix.rotateZ` for parity with CSS **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----- | ------------------- | -------------------- | | angle | number | Measured in degrees. |
### Rematrix.rotateX(angle) ⇒ array Returns a 4x4 matrix describing X-axis rotation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----- | ------------------- | -------------------- | | angle | number | Measured in degrees. |
### Rematrix.rotateY(angle) ⇒ array Returns a 4x4 matrix describing Y-axis rotation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----- | ------------------- | -------------------- | | angle | number | Measured in degrees. |
### Rematrix.rotateZ(angle) ⇒ array Returns a 4x4 matrix describing Z-axis rotation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----- | ------------------- | -------------------- | | angle | number | Measured in degrees. |
### Rematrix.scale(scalar, [scalarY]) ⇒ array Returns a 4x4 matrix describing 2D scaling. The first argument is used for both X and Y-axis scaling, unless an optional second argument is provided to explicitly define Y-axis scaling. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | --------- | ------------------- | ------------------- | | scalar | number | Decimal multiplier. | | [scalarY] | number | Decimal multiplier. |
### Rematrix.scaleX(scalar) ⇒ array Returns a 4x4 matrix describing X-axis scaling. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ------ | ------------------- | ------------------- | | scalar | number | Decimal multiplier. |
### Rematrix.scaleY(scalar) ⇒ array Returns a 4x4 matrix describing Y-axis scaling. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ------ | ------------------- | ------------------- | | scalar | number | Decimal multiplier. |
### Rematrix.scaleZ(scalar) ⇒ array Returns a 4x4 matrix describing Z-axis scaling. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ------ | ------------------- | ------------------- | | scalar | number | Decimal multiplier. |
### Rematrix.skew(angleX, [angleY]) ⇒ array Returns a 4x4 matrix describing shear. The first argument defines X-axis shearing, and an optional second argument defines Y-axis shearing. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | -------- | ------------------- | -------------------- | | angleX | number | Measured in degrees. | | [angleY] | number | Measured in degrees. |
### Rematrix.skewX(angle) ⇒ array Returns a 4x4 matrix describing X-axis shear. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----- | ------------------- | -------------------- | | angle | number | Measured in degrees. |
### Rematrix.skewY(angle) ⇒ array Returns a 4x4 matrix describing Y-axis shear. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----- | ------------------- | ------------------- | | angle | number | Measured in degrees |
### Rematrix.toString(source) ⇒ string Returns a CSS Transform property value equivalent to the source matrix. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ------ | ------------------ | ------------------------------------------ | | source | array | Accepts both short and long form matrices. |
### Rematrix.translate(distanceX, [distanceY]) ⇒ array Returns a 4x4 matrix describing 2D translation. The first argument defines X-axis translation, and an optional second argument defines Y-axis translation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | ----------- | ------------------- | ------------------- | | distanceX | number | Measured in pixels. | | [distanceY] | number | Measured in pixels. |
### Rematrix.translate3d(distanceX, distanceY, distanceZ) ⇒ array Returns a 4x4 matrix describing 3D translation. The first argument defines X-axis translation, the second argument defines Y-axis translation, and the third argument defines Z-axis translation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | --------- | ------------------- | ------------------- | | distanceX | number | Measured in pixels. | | distanceY | number | Measured in pixels. | | distanceZ | number | Measured in pixels. |
### Rematrix.translateX(distance) ⇒ array Returns a 4x4 matrix describing X-axis translation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | -------- | ------------------- | ------------------- | | distance | number | Measured in pixels. |
### Rematrix.translateY(distance) ⇒ array Returns a 4x4 matrix describing Y-axis translation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | -------- | ------------------- | ------------------- | | distance | number | Measured in pixels. |
### Rematrix.translateZ(distance) ⇒ array Returns a 4x4 matrix describing Z-axis translation. **Kind**: static method of [Rematrix](#module_Rematrix) | Param | Type | Description | | -------- | ------------------- | ------------------- | | distance | number | Measured in pixels. |

--- Copyright 2019 Julian Lloyd
Open source under the [MIT License](https://github.com/jlmakes/rematrix/blob/master/LICENSE).