From 780279531060811890d748e5ae7200b86a1a3b02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Vadal=C3=A0?= Date: Fri, 12 Nov 2021 18:37:22 +0100 Subject: [PATCH] upgrades README --- README.md | 344 ++++++++++++++++++++++++-------------------- README.template.hbs | 1 + 2 files changed, 191 insertions(+), 154 deletions(-) diff --git a/README.md b/README.md index 208d060..32aeb85 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,64 @@ - - - - - - - - - - -# transformation-matrix -Javascript isomorphic 2D affine transformations written in ES6 syntax. Manipulate transformation matrices with this totally tested library! - -[![chrvadala](https://img.shields.io/badge/website-chrvadala-orange.svg)](https://chrvadala.github.io) -[![Test](https://github.com/chrvadala/transformation-matrix/workflows/Test/badge.svg)](https://github.com/chrvadala/transformation-matrix/actions) -[![Coverage Status](https://coveralls.io/repos/github/chrvadala/transformation-matrix/badge.svg?branch=master)](https://coveralls.io/github/chrvadala/transformation-matrix?branch=master) -[![npm](https://img.shields.io/npm/v/transformation-matrix.svg?maxAge=2592000?style=plastic)](https://www.npmjs.com/package/transformation-matrix) -[![Downloads](https://img.shields.io/npm/dm/transformation-matrix.svg)](https://www.npmjs.com/package/transformation-matrix) -[![Donate](https://img.shields.io/badge/donate-PayPal-green.svg)](https://www.paypal.me/chrvadala/25) - - -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](https://books.google.it/books?vid=ISBN9780471899426) - -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** - -## Usage example (ES6) -```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 ] -``` - -## Setup -```sh -npm install transformation-matrix -# or -yarn add transformation-matrix -``` -```html - -``` - -# Reference + + + + + + + + + + +# transformation-matrix +Javascript isomorphic 2D affine transformations written in ES6 syntax. Manipulate transformation matrices with this totally tested library! + +[![chrvadala](https://img.shields.io/badge/website-chrvadala-orange.svg)](https://chrvadala.github.io) +[![Test](https://github.com/chrvadala/transformation-matrix/workflows/Test/badge.svg)](https://github.com/chrvadala/transformation-matrix/actions) +[![Coverage Status](https://coveralls.io/repos/github/chrvadala/transformation-matrix/badge.svg?branch=master)](https://coveralls.io/github/chrvadala/transformation-matrix?branch=master) +[![npm](https://img.shields.io/npm/v/transformation-matrix.svg?maxAge=2592000?style=plastic)](https://www.npmjs.com/package/transformation-matrix) +[![Downloads](https://img.shields.io/npm/dm/transformation-matrix.svg)](https://www.npmjs.com/package/transformation-matrix) +[![Donate](https://img.shields.io/badge/donate-PayPal-green.svg)](https://www.paypal.me/chrvadala/25) + + +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](https://books.google.it/books?vid=ISBN9780471899426) + +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** + +## Usage example (ES6) +```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 ] +``` + +## Setup +```sh +npm install transformation-matrix +# or +yarn add transformation-matrix +``` +```html + +``` + +# Reference ## Functions
@@ -152,69 +152,70 @@ Warning: This should be considered BETA until it is released a stable version of
-## 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](https://github.com/chrvadala/transformation-matrix/issues/12), Adds `fromTransformAttribute`, Discontinues node 4 support -- **1.9** - Adds `skew(ax, ay)`, Upgrades deps, Improves `fromTransformAttribute` -- **1.10**- Updates typescript definitions [#15](https://github.com/chrvadala/transformation-matrix/pull/15) -- **1.11**- Upgrades deps -- **1.12**- Migrates tests on [Jest](https://jestjs.io/), Integrates [standard.js](https://standardjs.com/), Upgrades deps -- **1.13**- Adds `compose` function, Upgrades deps, Exposes skew operation [#37](https://github.com/chrvadala/transformation-matrix/pull/37) -- **1.14**- Adds support for points defined as `Array` in the form `[x, y]` [#38](https://github.com/chrvadala/transformation-matrix/pull/38) -- **1.15**- Adds `fromTriangle` and `smoothMatrix` functions [#41](https://github.com/chrvadala/transformation-matrix/issues/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](https://github.com/chrvadala/transformation-matrix/pull/66) -- **2.3**- Adds `(cx,cy)` on `scale` function [#62](https://github.com/chrvadala/transformation-matrix/pull/62); Improves typescript definition [#66](https://github.com/chrvadala/transformation-matrix/pull/67); Upgrades deps -- **2.4**- Improves typescript definition [#75](https://github.com/chrvadala/transformation-matrix/pull/75) -- **2.5**- Upgrades deps; Deprecates NodeJS 8; Adds NodeJs 14 support -- **2.6**- Upgrades deps; Fixes fromTransformAttribute function [#84](https://github.com/chrvadala/transformation-matrix/pull/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; -# API - -## Data Model -A transformation **Matrix** is defined as a `Plain Object` with 6 keys: `a`, `b`, `c`, `d`, `e` and `f`. -```js -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` -```js -const point = { x: 24, y: 42 } -``` -- as `Array`, with two items in the form `[x, y]` -```js -const point = [ 24, 42 ] -``` - -A **Transform** (used in [decomposeTSR](#decomposeTSR)) is defined as a `Plain Object` of the following shape: -```typescript -interface Transform { - translate: { - tx: number, - ty: number - }, - rotation: number, - scale: { - sx: number, - sy: number - } -} -``` - +## 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](https://github.com/chrvadala/transformation-matrix/issues/12), Adds `fromTransformAttribute`, Discontinues node 4 support +- **1.9** - Adds `skew(ax, ay)`, Upgrades deps, Improves `fromTransformAttribute` +- **1.10**- Updates typescript definitions [#15](https://github.com/chrvadala/transformation-matrix/pull/15) +- **1.11**- Upgrades deps +- **1.12**- Migrates tests on [Jest](https://jestjs.io/), Integrates [standard.js](https://standardjs.com/), Upgrades deps +- **1.13**- Adds `compose` function, Upgrades deps, Exposes skew operation [#37](https://github.com/chrvadala/transformation-matrix/pull/37) +- **1.14**- Adds support for points defined as `Array` in the form `[x, y]` [#38](https://github.com/chrvadala/transformation-matrix/pull/38) +- **1.15**- Adds `fromTriangle` and `smoothMatrix` functions [#41](https://github.com/chrvadala/transformation-matrix/issues/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](https://github.com/chrvadala/transformation-matrix/pull/66) +- **2.3**- Adds `(cx,cy)` on `scale` function [#62](https://github.com/chrvadala/transformation-matrix/pull/62); Improves typescript definition [#66](https://github.com/chrvadala/transformation-matrix/pull/67); Upgrades deps +- **2.4**- Improves typescript definition [#75](https://github.com/chrvadala/transformation-matrix/pull/75) +- **2.5**- Upgrades deps; Deprecates NodeJS 8; Adds NodeJs 14 support +- **2.6**- Upgrades deps; Fixes fromTransformAttribute function [#84](https://github.com/chrvadala/transformation-matrix/pull/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](https://github.com/chrvadala/transformation-matrix/pull/88); Upgrades deps; +# API + +## Data Model +A transformation **Matrix** is defined as a `Plain Object` with 6 keys: `a`, `b`, `c`, `d`, `e` and `f`. +```js +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` +```js +const point = { x: 24, y: 42 } +``` +- as `Array`, with two items in the form `[x, y]` +```js +const point = [ 24, 42 ] +``` + +A **Transform** (used in [decomposeTSR](#decomposeTSR)) is defined as a `Plain Object` of the following shape: +```typescript +interface Transform { + translate: { + tx: number, + ty: number + }, + rotation: number, + scale: { + sx: number, + sy: number + } +} +``` + ## applyToPoint(matrix, point) ⇒ Point @@ -244,10 +245,16 @@ Calculate an array of points transformed with an affine matrix ## decomposeTSR(matrix, flipX, flipY) ⇒ Transform -Decompose a matrix into translation, scaling and rotation components, optionally take horizontal and vertical flip in to consideration. Note this function decomposes a matrix in rotation -> scaling -> translation order. I.e. for certain translation T {tx, ty}, rotation R and scaling S { sx, sy }, it's only true for: decomposeTSR(compose(T, S, R)) === { translate: T, rotation: R, scale: S } composing in a different order may yield a different decomposition result. +Decompose a matrix into translation, scaling and rotation components, optionally +take horizontal and vertical flip in to consideration. +Note this function decomposes a matrix in rotation -> scaling -> translation order. I.e. for +certain translation T {tx, ty}, rotation R and scaling S { sx, sy }, it's only true for: + decomposeTSR(compose(T, S, R)) === { translate: T, rotation: R, scale: S } +composing in a different order may yield a different decomposition result. **Kind**: global function -**Returns**: Transform - A transform object consisted by its translation, scaling and rotation components. +**Returns**: Transform - A transform object consisted by its translation, scaling +and rotation components. | Param | Type | Description | | --- | --- | --- | @@ -290,12 +297,31 @@ Converts array of matrix descriptor to array of matrix **Example** ```js -> 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 } ] +> 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 +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 @@ -318,12 +344,14 @@ Parse a string formatted as matrix(a,b,c,d,e,f) **Example** ```js -> fromString('matrix(1,2,3,4,5,6)') {a: 1, b: 2, c: 3, d: 4, c: 5, e: 6} +> 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. +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 @@ -334,7 +362,15 @@ Parser for SVG Trasform Attribute http://www.w3.org/TR/SVG/coords.html#Transform **Example** ```js -> 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 } +> 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 } ``` @@ -552,26 +588,26 @@ Calculate a translate matrix | tx | number | | Translation on axis x | | [ty] | number | 0 | Translation on axis y | -## Some projects using transformation-matrix -- [**React Planner**](https://github.com/cvdlab/react-planner) -- [**React SVG Pan Zoom**](https://github.com/chrvadala/react-svg-pan-zoom) -- [**ngx-graph**](https://github.com/swimlane/ngx-graph) -- [**learn-anything**](https://github.com/learn-anything/learn-anything) -- [**Others...**](https://github.com/chrvadala/transformation-matrix/network/dependents) -- Pull request your project! - -## Contributors -- [chrvadala](https://github.com/chrvadala) (author) -- [forabi](https://github.com/forabi) -- [nidu](https://github.com/nidu) (PEG.js descriptor) -- [aubergene](https://github.com/aubergene) -- [SophiaLi1](https://github.com/SophiaLi1) -- [Shuhei-Tsunoda](https://github.com/Shuhei-Tsunoda) -- [antonyRoberts](https://github.com/antonyRoberts) -- [mcwebb](https://github.com/mcwebb) -- [signalwerk](https://github.com/signalwerk) -- [estollnitz](https://github.com/estollnitz) -- [rodrigoapereira](https://github.com/rodrigoapereira) -- [formatlos](https://github.com/formatlos) -- [benhjames](https://github.com/benhjames) -- [hillin](https://github.com/hillin) +## Some projects using transformation-matrix +- [**React Planner**](https://github.com/cvdlab/react-planner) +- [**React SVG Pan Zoom**](https://github.com/chrvadala/react-svg-pan-zoom) +- [**ngx-graph**](https://github.com/swimlane/ngx-graph) +- [**learn-anything**](https://github.com/learn-anything/learn-anything) +- [**Others...**](https://github.com/chrvadala/transformation-matrix/network/dependents) +- Pull request your project! + +## Contributors +- [chrvadala](https://github.com/chrvadala) (author) +- [forabi](https://github.com/forabi) +- [nidu](https://github.com/nidu) (PEG.js descriptor) +- [aubergene](https://github.com/aubergene) +- [SophiaLi1](https://github.com/SophiaLi1) +- [Shuhei-Tsunoda](https://github.com/Shuhei-Tsunoda) +- [antonyRoberts](https://github.com/antonyRoberts) +- [mcwebb](https://github.com/mcwebb) +- [signalwerk](https://github.com/signalwerk) +- [estollnitz](https://github.com/estollnitz) +- [rodrigoapereira](https://github.com/rodrigoapereira) +- [formatlos](https://github.com/formatlos) +- [benhjames](https://github.com/benhjames) +- [hillin](https://github.com/hillin) diff --git a/README.template.hbs b/README.template.hbs index 81924ec..d92ceea 100644 --- a/README.template.hbs +++ b/README.template.hbs @@ -82,6 +82,7 @@ yarn add transformation-matrix - **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](https://github.com/chrvadala/transformation-matrix/pull/88); Upgrades deps; # API ## Data Model