Release 2.1.0

.github/workflows/nudged-ci.yml

@@ -18,4 +18,21 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm install
-      - run: npm test
+      - run: npm run test:lint
+      - run: npm run test:unit
+
+  nudged-type-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run test:types

.gitignore

@@ -29,5 +29,5 @@ package-lock.json
 # OS X Related
 *.DS_Store
 
-# Ignore sketchy generated docs for a while
-# doc/API.md
+# Build files for unpkg.com
+dist

CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.1] - 2024-11-08
+
+### Fixed
+
+- Repair release: include sources in the 'files' of package.json
+
+### Removed
+
+- Remove .npmignore and rely on 'files' alone.
+
+
+## [2.1.0] - 2024-11-08
+
+### Added
+
+- Add TypeScript type declarations `index.d.ts` (#29 #30)
+- Release UMD bundle via Unpkg.com (#32)
+- Add dev dependency: yamdog (#34) and terser (#32)
+- Add navigational links to README
+- Add source code links from API docs to GitHub.
+- Add GitHub Pages for Nudged.
+- Add GitHub action job for testing type declarations.
+
+### Changed
+
+- Generate API docs with yamdog instead of ad-hoc tooling. (#34)
+- Improve documentation all around.
+- Minify standalone builds by default (#32)
+
+### Fixed
+
+- Fix a property name typo in transform.toMatrix documentation.
+
+### Removed
+
+- Remove unused dev dependencies: async, lodash
+
 
 ## [2.0.1] - 2024-10-28
 
@@ -51,6 +88,10 @@ The library switched from object-oriented to pure functional paradigm.
 - *Breaking:* code base uses ES6 syntax instead of ES5.
 - Migrate test suite from `mocha` to `tape`
 
+### Removed
+
+- *Breaking:* remove classes Transform and Point. Use nudged.transform and nudged.point namespaces instead.
+
 ### Migration Tips
 
 - Ensure your environment is compatible with ECMAScript 2015 (ES6)

README.md

@@ -2,6 +2,7 @@
 
 [![NPM Version](https://img.shields.io/npm/v/nudged.svg)](https://www.npmjs.com/package/nudged)
 ![Dependency status](https://img.shields.io/badge/dependencies-none-lightgrey)
+![NPM Type Definitions](https://img.shields.io/npm/types/nudged?color=green)
 [![License](https://img.shields.io/npm/l/nudged)](#license)
 [![GitHub Actions workflow status](https://img.shields.io/github/actions/workflow/status/axelpale/nudged/nudged-ci.yml)](https://github.com/axelpale/nudged/actions/workflows/nudged-ci.yml)
 
@@ -15,26 +16,33 @@
 - [Introduction](#introduction)
 - [Usage](#usage)
 - [Example apps](#example-apps)
-- [API docs](doc/API.md)
+- [API docs](https://axelpale.github.io/nudged/doc/API.html)
 - [For developers](#for-developers)
 - [Acknowledgments](#acknowledgments)
 - [Versioning](#versioning)
 - [Licence](#licence)
 - [See also](#see-also)
+- [GitHub](https://github.com/axelpale/nudged)
 
 
 ## Installation
 
-Install `nudged` with [npm](https://www.npmjs.com/package/nudged) or other compatible package manager. The package comes in two flavors: functional and object oriented.
+Install `nudged` with [npm](https://www.npmjs.com/package/nudged), [yarn](https://classic.yarnpkg.com/en/package/nudged) or other compatible package manager. The package comes in two flavors: functional and object oriented.
 
-Install the functional nudged 2:
+Install the latest, functional nudged:
 
     $ npm install nudged
 
-Install the object-oriented [nudged 1.x](https://github.com/axelpale/nudged/tree/1.x):
+Alternatively, install the object oriented [nudged 1.x](https://github.com/axelpale/nudged/tree/1.x):
 
     $ npm install nudged@1
 
+A standalone UMD bundle is available via [Unpkg CDN](https://www.unpkg.com/) for [email protected] and later:
+
+```
+<script src="https://www.unpkg.com/nudged/dist/nudged.min.js"></script>
+```
+
 Nudged is also available [in Python](https://pypi.python.org/pypi/nudged).
 
 
@@ -47,7 +55,7 @@ _**Image**: Available transformation estimators. Each estimator has an abbreviat
 
 **Mathematically speaking**, Nudged is a set of optimal [least squares estimators](https://en.wikipedia.org/wiki/Least_squares) for the group of nonreflective similarity transformation matrices, also called [Helmert transformations](https://en.wikipedia.org/wiki/Helmert_transformation). Such transformations are [affine transformations](https://en.wikipedia.org/wiki/Affine_transformation) with translation, rotation, and/or uniform scaling, and without reflection or shearing. The estimation has [time complexity](https://en.wikipedia.org/wiki/Time_complexity) of O(*n*), where *n* is the cardinality (size) of the point sets. In other words, Nudged solves a 2D to 2D point set registration problem (alias [Procrustes superimposition](https://en.wikipedia.org/wiki/Procrustes_analysis)) in [linear time](https://en.wikipedia.org/wiki/Time_complexity#Linear_time). The algorithms and their efficiency are thoroughly described in a **M.Sc. thesis** [Advanced algorithms for manipulating 2D objects on touch screens](http://URN.fi/URN:NBN:fi:tty-201605264186).
 
-**The development has been supported** by [Infant Cognition Laboratory](https://www.tuni.fi/en/research/infant-cognition) at [Tampere University](https://www.tuni.fi/en/) where Nudged is used to correct eye tracking data. Yet, the main motivation for Nudged comes from [Tapspace](https://github.com/taataa/tapspace), a zoomable user interface library where smooth and fast scaling by touch is crucial.
+**The development has been supported** by [Infant Cognition Laboratory](https://www.tuni.fi/en/research/infant-cognition) at [Tampere University](https://www.tuni.fi/en/) where Nudged is used to correct eye tracking data. Yet, the main motivation for Nudged comes from [Tapspace.js](https://github.com/taataa/tapspace), a zoomable user interface library where smooth and fast scaling by touch is crucial.
 
 
 ## Usage
@@ -57,11 +65,10 @@ Let `domain` be a set of points, `[{ x, y }, ...]`. Let `range` be the same poin
     const domain = [{ x: 0, y: 2 }, { x: 2, y: 2 }, { x: 1, y: 4 }]
     const range  = [{ x: 4, y: 4 }, { x: 4, y: 2 }, { x: 6, y: 3 }]
 
-<img src="doc/img/nudged-diagram-6-4-domain-range.png" alt="The domain and the range" />
-
+<img src="doc/img/nudged-diagram-6-4-domain-range.png" alt="The domain and the range" /><br>
 _**Figure**: The domain (circles o) and the range (crosses x). The + marks the point {x:0,y:0}._
 
-We would like to find a simple 2D transformation `tran` that simulates T as closely as possible by combining translation, scaling, and rotation. We compute `tran` by calling [nudged.estimate](doc/API.md#nudgedestimate):
+We would like to find a simple 2D transformation `tran` that simulates T as closely as possible by combining translation, scaling, and rotation. We compute `tran` by calling [nudged.estimate](https://axelpale.github.io/nudged/doc/API.html#nudgedestimate):
 
     const tran = nudged.estimate({
       estimator: 'TSR',
@@ -74,37 +81,34 @@ The result is a *transform* object:
     > tran
     { a: 0, b: -1, x: 4, y: 4 }
 
-You can apply `tran` to a point with [point.transform](doc/API.md#nudgedpointtransform):
+You can apply `tran` to a point with [point.transform](https://axelpale.github.io/nudged/doc/API.html#nudgedpointtransform):
 
     > nudged.point.transform({ x: 0, y: 4 }, tran)
     { x: 6, y: 4 }
 
-<img src="doc/img/nudged-diagram-6-7-point-transform.png" alt="A point is being transformed" />
-
+<img src="doc/img/nudged-diagram-6-7-point-transform.png" alt="A point is being transformed" /><br>
 _**Figure**: A point {x:0, y:4} is transformed by the estimated transform._
 
-You can apply `tran` to other geometric shapes as well, for example to correct the orientation based on some sensor data. In the case of HTML image elements, just convert `tran` to a [CSS transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function) string with [transform.toString](doc/API.md#nudgedtransformtostring):
+You can apply `tran` to other geometric shapes as well, for example to correct the orientation based on some sensor data. In the case of HTML image elements, just convert `tran` to a [CSS transform](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function) string with [transform.toString](https://axelpale.github.io/nudged/doc/API.html#nudgedtransformtostring):
 
     > img.style.transform = nudged.transform.toString(tran)
 
-<img src="doc/img/nudged-diagram-10-2-photo-transform.jpg" alt="A photograph is being transformed" />
-
+<img src="doc/img/nudged-diagram-10-2-photo-transform.jpg" alt="A photograph is being transformed" /><br>
 _**Figure**: An HTML image before and after the transform we estimated from the points._
 
-The [nudged.transform](doc/API.md#nudgedtransform) module provides
+The [nudged.transform](https://axelpale.github.io/nudged/doc/API.html#nudgedtransform) module provides
 lots of tools to process transform objects.
 For example, to make a transformation that maps the range back to the domain
-instead of another way around, invert the transform with [transform.inverse](doc/API.md#nudgedtransforminverse):
+instead of another way around, invert the transform with [transform.inverse](https://axelpale.github.io/nudged/doc/API.html#nudgedtransforminverse):
 
     > const inv = nudged.transform.inverse(tran)
     > nudged.point.transform({ x: 6, y: 4 }, inv)
     { x: 0, y: 4 }
 
-<img src="doc/img/nudged-diagram-6-8-transform-inverse.png" alt="A point transformed by the inverse of the estimate." />
-
+<img src="doc/img/nudged-diagram-6-8-transform-inverse.png" alt="A point transformed by the inverse of the estimate." /><br>
 _**Figure**: A point is transformed by the inverse of the estimated transform._
 
-See [nudged.transform](doc/API.md#nudgedtransform) for more tools and details.
+See [nudged.transform](https://axelpale.github.io/nudged/doc/API.html#nudgedtransform) for more tools and details.
 
 ### Set a center point
 
@@ -120,8 +124,7 @@ To estimate scalings and rotations around a fixed point, give an additional `cen
 
 You can think the center point as a nail that keeps an elastic sheet of rubber fixed onto a table. The nail retains its location regardless of how the rubber sheet is rotated or stretched around it.
 
-<img src="doc/img/nudged-diagram-7-4-rotation-around-center.png" alt="A rotation around a fixed center point" />
-
+<img src="doc/img/nudged-diagram-7-4-rotation-around-center.png" alt="A rotation around a fixed center point" /><br>
 _**Figure**: Rotation around a center point (⊕) maps the domain (o) as close to the range (x) as possible. Here the mapped image (●) cannot match the range exactly due to the restriction set by the center point. The + denotes the point {x:0, y:0}._
 
 To test the resulting transform, we can apply it to the center point and observe that the point stays the same.
@@ -138,11 +141,10 @@ To estimate scalings in respect of a center point, as illustrated below, set `es
       center: center
     })
 
-<img src="doc/img/nudged-diagram-8-8-scaling-estimation.png" alt="Scaling about a center point (⊕)" />
-
+<img src="doc/img/nudged-diagram-8-8-scaling-estimation.png" alt="Scaling about a center point (⊕)" /><br>
 _**Figure**: The domain (o) is scaled towards the center point (⊕) so that the resulting image (●) lies as close to the range (x) as possible._
 
-See [estimators.S](doc/API.md#nudgedestimatorss), [estimators.R](doc/API.md#nudgedestimatorss), and [estimators.SR](doc/API.md#nudgedestimatorss) for further details.
+See [estimators.S](https://axelpale.github.io/nudged/doc/API.html#nudgedestimatorss), [estimators.R](https://axelpale.github.io/nudged/doc/API.html#nudgedestimatorss), and [estimators.SR](https://axelpale.github.io/nudged/doc/API.html#nudgedestimatorss) for further details.
 
 ### Analyse the transform
 
@@ -173,11 +175,10 @@ comparing the result to the range:
     > range
     [ { x: 4, y: 4 }, { x: 4, y: 2 }, { x: 6, y: 3 } ]
 
-<img src="doc/img/nudged-diagram-6-6-transform-domain.png" alt="Scaling about a center point (⊕)" />
-
+<img src="doc/img/nudged-diagram-6-6-transform-domain.png" alt="Scaling about a center point (⊕)" /><br>
 _**Figure**: The domain (o) mapped with `tran` (→). The fit is perfect, the image (●) matches the range (x) exactly._
 
-See [nudged.analysis](doc/API.md#nudgedanalysis) for more.
+See [nudged.analysis](https://axelpale.github.io/nudged/doc/API.html#nudgedanalysis) for more.
 
 ### Build transforms
 
@@ -192,8 +193,7 @@ Let us apply `t` to `domain`. The result is illustrated below.
     > nudged.point.transformMany(domain, t)
     [ { x: 3, y: 3.5 }, { x: 4, y: 3.5 }, { x: 3.5, y: 4.5 } ]
 
-<img src="doc/img/nudged-diagram-8-4-scaling-by-half.png" alt="Scaling about a center point (⊕)" />
-
+<img src="doc/img/nudged-diagram-8-4-scaling-by-half.png" alt="Scaling about a center point (⊕)" /><br>
 _**Figure**: Scaling the domain (o) by the factor of 0.5 about the center point (⊕). The resulting image (●) has all distances halved. The + denotes the point {x:0, y:0}._
 
 Then let us modify the transform `t` further. Let `tr` be a transform that combines `t`
@@ -212,12 +212,11 @@ Let us apply the resulting transform to the domain points. The result is illustr
       { x: 5.656..., y: 0.707... }
     ]
 
-<img src="doc/img/nudged-diagram-7-9-combine-rotation.png" alt="A scaling combined with a rotation" />
-
+<img src="doc/img/nudged-diagram-7-9-combine-rotation.png" alt="A scaling combined with a rotation" /><br>
 _**Figure**: A scaling is combined with rotation so that the image of the scaling (grey ●) is further rotated by 90 degrees around a center point (⊕)._
 
 
-Not all transformation need to be built. You can find some prebuilt transforms under [nudged.transform](doc/API.md#nudgedtransform):
+Not all transformation need to be built. You can find some prebuilt transforms under [nudged.transform](https://axelpale.github.io/nudged/doc/API.html#nudgedtransform):
 
     > const p = { x: 4, y: 2 }
     > const X2 = nudged.transform.X2
@@ -230,7 +229,7 @@ Not all transformation need to be built. You can find some prebuilt transforms u
     > nudged.point.transform(p, I)
     { x: 4, y: 2 }
 
-To discover more features and details, see [API](doc/API.md).
+To discover more features and details, see [API](https://axelpale.github.io/nudged/doc/API.html).
 
 ## Example apps
 
@@ -259,7 +258,7 @@ In this [map viewer demo](https://rawgit.com/axelpale/nudged/master/examples/nud
 
 ## API
 
-[The functional 2.x API documentation](doc/API.md).
+[The functional 2.x API documentation](https://axelpale.github.io/nudged/doc/API.html).
 
 [The object-oriented 1.x API documentation](https://github.com/axelpale/nudged/tree/1.x#api)
 
@@ -271,6 +270,7 @@ Nudged source code is located at [GitHub](https://github.com/axelpale/nudged).
 Guidelines:
 
 - Use [ECMAScript 2015](https://en.wikipedia.org/wiki/ECMAScript) syntax with [CommonJS](https://en.wikipedia.org/wiki/CommonJS) module format.
+- TypeScript type declarations go to `index.d.ts`.
 - Follow [Standard](https://standardjs.com/) style:
   - 2 space indent
   - max 80 chars per line
@@ -281,17 +281,24 @@ Guidelines:
 - Minimal run-time type checking
   - Nudged is designed to be a low-level module with high performance.
   - Instead of run-time checks, the geometries provide a dedicated .validate function.
+  - Provide type declarations for compile-time checking.
 - Write rich comments that answer the question "why".
 
-Run lint & unit tests:
+Test for syntax, execution, and types:
+
+    $ npm run test:lint
+    $ npm run test:unit
+    $ npm run test:types
+
+Run all test at once:
 
-    $ npm run test
+    $ npm test
 
 Build example apps:
 
     $ npm run build:examples
 
-Start local server to try out the examples:
+Start local static server to try out the examples:
 
     $ npm start
 
@@ -340,3 +347,5 @@ The nudged source code is open source and free to use. It is released under a [M
 - [Affineplane](https://axelpale.github.io/affineplane/) geometry library is directly compatible with Nudged object interfaces. It provides further tools to transform geometry and manipulate transformations in 2D and 3D.
 - [Tapspace.js](https://github.com/taataa/tapspace) is a toolkit for zoomable user interfaces. Tapspace.js heavily depends on the nudged algorithm in multi-touch recognition, web content layout, and tensor geometry.
 - [Apollonius](https://axelpale.github.io/apollonius/) is another math-heavy geometry package from the author of Nudged. Apollonius considers finding a circle that is simultaneously tangent to three other circles.
+- [A Nudged blog post](https://www.akselipalen.com/2016/07/03/nudged-a-fast-transformation-estimator/)
+- [Nudged GitHub repository](https://github.com/axelpale/nudged)