Welcome to Nudged interface documentation!
The nudged API follows
a functional and immutable paradigm without classes.
Thus all the functions take in and return plain objects and values
such as { x: 1, y: 2 }. The functions never modify the given objects,
never cause side effects, and never memorize previous calls.
In contrast to object-oriented programming, the features are
implemented as pure functions that are grouped
in modules aka namespaces instead of classes.
See the available modules below.
The estimators and related tools are grouped into namespaces. The estimate function and estimators namespace provide the core features for computing transformations between point sets. The point and transform namespaces provide basic tools to work with the geometry and export it to various formats. The analysis provides tools to assess the quality of the estimated transformations and to detect outliers in point pairs.
Contents:
Source: lib/index.js
These tools help you to measure how well the estimated transformation fits the data.
Contents:
Source: analysis/index.js
Compute mean squared error (MSE) of the transformation. MSE is the mean squared distances between the range points and transformed domain points. The MSE is a standard measure for how well the transformation fits the data. The smaller the MSE the better the fit.
Parameters:
Returns:
Source: mse.js
Get an array of residuals. A residual is the distance between a domain point after the given transformation and its associated range point. You can use an array of residuals to detect possible outliers and to build custom analysis methods.
Parameters:
Returns:
Source: residuals.js
Compute the residual sum of squares (RSS) of the transformation. The RSS is the sum of the squared distances between the range points and transformed domain points.
Parameters:
Returns:
Note that the RSS tends to grow linearly with the number of points. If you need an error measure that is independent of the number of points then consider using nudged.analysis.mse instead.
Source: rss.js
Estimates a transformation with the selected estimator and constraints. See nudged.estimators for available estimators.
Parameters:
{ x, y }. Required.{ x, y }. Required.{ x, y }. Optional.Returns:
Internally, this calls the function of the selected estimator.
Therefore, if you desire maximal efficiency instead of flexibility,
use the estimator functions directly via nudged.estimators,
like for example nudged.estimators.R(domain, range, center)
Example:
> const domain = [{ x: 0, y: 0 }, { x: 2, y: 0 }, { x: 1, y: 2 }]
> const range = [{ x: 1, y: 1 }, { x: 1, y: 3 }, { x: -1, y: 2 }]
> const center = { x: 0, y: 0 }
> const tr = nudged.estimate({
estimator: 'SR',
domain: domain,
range: range,
center: center
})
> nudged.transform.getScale(tr)
1.242259
> nudged.transform.getRotation(tr)
1.107148
Source: estimate.js
A collection of estimator functions. Call these directly instead of the general nudged.estimate for a bit more efficiency by saving one function call.
Contents:
Source: estimators/index.js
The trivial estimator; The estimate is always the identity transformation regardless of the given domain and range.
Example:
> nudged.estimators.I(domain, range)
{ a: 1, b: 0, x: 0, y: 0 }
Why this trivial estimator exists? If the estimator type becomes a variable in your application
then it can be convenient to be able to disable estimation by just switching the estimator type to I.
Source: I.js
Estimate translation along a line at the given angle.
Parameters:
Returns:
Source: L.js
Estimate rotation around a fixed center point.
Parameters:
Returns:
Source: R.js
Estimate a scaling around the given center. In other words, estimate a homothety.
Parameters:
Returns:
Source: S.js
Estimate optimal transformation given the domain and the range so that the center point remains fixed. Example use cases: 1) Transform an image that has one corner fixed with a pin. 2) Allow only scale and rotation by fixing the middle of the object.
Parameters:
Returns:
Source: SR.js
Estimate translation that maps domain points close to range points.
Parameters:
Returns:
Source: T.js
Estimate translation with rotation.
Parameters:
Returns:
Source: TR.js
Estimate translation with scaling.
Parameters:
Returns:
Source: TS.js
Estimate a non-reflective similarity transformation. In other words, an affine transformation where translation, positive scaling, and rotation are allowed.
Parameters:
Returns:
Source: TSR.js
Estimate horizontal translation that is a translation along x-axis.
Parameters:
Returns:
Source: X.js
Estimate vertical translation that is a translation along y-axis.
Parameters:
Returns:
Source: Y.js
A set of operators for 2D point objects { x, y }.
Contents:
Source: point/index.js
Test if two points are almost equal within the limit given by the optional tolerance parameter.
Parameters:
0 for strict comparison.Returns:
Example:
> nudged.point.almostEqual({ x: 0, y: 0 }, { x: 0, y: 1.23e-16 })
true
> nudged.point.almostEqual({ x: 0, y: 0 }, { x: 0, y: 0.1 })
false
> nudged.point.almostEqual({ x: 0, y: 0 }, { x: 0, y: 0.1 }, 0.2)
true
Source: almostEqual.js
Create a point object.
Parameters:
Returns:
{ x, y }Source: create.js
The Euclidean distance between two points. Also called the Euclidean norm alias L2-norm.
Parameters:
Returns:
Source: distance.js
Test if the coordinates of two points are strictly equal.
Parameters:
Returns:
Note that strict numerical equality is rarely true in practice because of rounding errors caused by floating point arithmetics. Consider using nudged.point.almostEqual instead.
Source: equal.js
Create a point { x, y } from an array [x, y].
Parameters:
Returns:
Throws:
Source: fromArray.js
Offset a point by scalars dx, dy.
This is equivalent to translation by the vector { x: dx, y: dy }.
Parameters:
Returns:
Source: offset.js
Create a point away from p at the given distance and angle.
Parameters:
Returns:
Example:
> nudged.point.polarOffset({ x: 1, y: 0 }, 5, Math.PI / 2)
{ x: 1, y: 5 }
Source: polarOffset.js
Convert a point { x, y } into a two-element array [x, y].
Parameters:
Returns:
[x, y]Source: toArray.js
Transform a point. The point is first scaled and rotated around origin and then translated. This corresponds to a matrix multiplication Mv where M is a 3x3 transformation matrix and v is a 3x1 augmented 2D vector.
Parameters:
Returns:
Example:
> const tr = nudged.transform.ROT90
> nudged.point.transform({ x: 1, y: 0 }, tr)
{ x: 0, y: 1 }
Source: transform.js
Transform an array of points.
Parameters:
Returns:
Example:
> const tr = nudged.transform.ROT90
> const ps = [{ x: 1, y: 0}, { x: 0, y: 1 }]
> nudged.point.transformMany(ps, tr)
[{ x: 0, y: 1 }, { x: -1, y: 0 }]
Source: transformMany.js
Check if the point is a valid point object.
Valid point objects must have properties x and y that are finite numbers.
Valid point objects are allowed to have custom properties.
Parameters:
Returns:
p is a valid point.Example:
> nudged.point.validate({ x: 1, y: 0 })
true
> nudged.point.validate({ x: 1 })
false
Source: validate.js
Default tolerance to use when coping with floating point arithmetics. JavaScript floating point numbers have 52 bits in mantissa (IEEE-754). That is about 16 base10 digits. Therefore the tolerance should be much larger than 1 * 10^-16. Let say 1 * 10^-10 is a good one.
> nudged.tolerance
0.0000000001
Source: tolerance.js
This namespace provides functions to create and modify transforms.
A transform is a plain object with the structure { a, b, x, y }.
It defines a transformation matrix, and to be exact, an
augmented affine
non-reflective similarity
transformation matrix.
Such transformation matrices are a compact way to represent
translation, rotation, and scaling in a single 3x3 matrix.
The matrix that the transform represents has the following elements:
┌ ┐
│ a -b x │
│ b a y │
│ 0 0 1 │
└ ┘
Contents:
Source: transform/index.js
A prebuilt transform { a: 0.5, b: 0, x: 0, y: 0 }. Scales towards { x: 0, y: 0 } by the factor of 0.5.
Source: transform/index.js
The identity transform { a: 1, b: 0, x: 0, y: 0 }.
It resembles multiplication by 1 in the way that it does not cause any effect.
You can use it as a starting point
to build other transformations. For example:
const I = nudged.transform.IDENTITY
const center = { x: 320, y: 240 }
const angle = Math.PI / 5
const rotation = nudged.transform.rotateBy(I, center, angle)
Source: transform/index.js
A prebuilt transform { a: -1, b: 0, x: 0, y: 0 }. Rotates around { x: 0, y: 0 } by 180 degrees.
Source: transform/index.js
A prebuilt transform { a: 0, b: -1, x: 0, y: 0 }. Rotates around { x: 0, y: 0 } by 270 degrees (= 3/4 turn = 3π/2).
Source: transform/index.js
A prebuilt transform. Rotates around { x: 0, y: 0 } by 45 degrees.
Example:
> const R = nudged.transform.ROT45
> nudged.transform.getRotation(R) * 360 / (2 * Math.PI)
45
> nudged.point.transform({ x: 1, y: 0 }, R)
{ x: 0.7071..., y: 0.7071... }
Source: transform/index.js
A prebuilt transform { a: 0, b: 1, x: 0, y: 0 }. Rotates around { x: 0, y: 0 } by 90 degrees.
Source: transform/index.js
A prebuilt singular transform { a: 0, b: 0, x: 0, y: 0 }.
It resembles multiplication by 0.
Source: transform/index.js
A prebuilt transform { a: 2, b: 0, x: 0, y: 0 }. Scales away from { x: 0, y: 0 } by the factor of 2.
Source: transform/index.js
Are two transforms almost equal? Due to the limitations of floating point precision, most operations have a little numerical error in their results. Two matrices that should be equivalent according to algebra, might not have strictly equivalent elements. Therefore some tolerance is often necessary in practice. See nudged.transform.equal for strict comparison.
Parameters:
0 for strict comparison.Returns:
How the error is computed? For the difference metric, we use a modified L1 norm that values a, b, x, and y equally. If the sum of the differences is smaller or equal to the tolerance, consider the transforms equal.
Source: almostEqual.js
Multiply the transform tr from the right with the given transform ts. In other words, the resulting transform is equivalent to first transforming with ts and then with tr. To put it short, transform the image of ts by tr.
Parameters:
Returns:
Source: compose.js
Create a transform object { a, b, x, y }.
Parameters:
Returns:
Source: create.js
Test that the transforms are strictly equal.
Transforms are strictly equal if every corresponding element is === equal.
Note that in practice, rounding errors of floating point arithmetics often break
strict equality.
For loose equality, see almostEqual.
Parameters:
Returns:
Source: equal.js
Convert a transform represented by an 4-element array [a, b, x, y]
to a transform object { a, b, x, y }.
Compatible with nudged.transform.toArray.
Parameters:
Returns:
Example:
> nudged.transform.fromArray([1, 2, 3, 4])
{ a: 1, b: 2, x: 3, y: 4 }
Source: fromArray.js
Create a nudged.transform object by using scale and rotation in respect of a center point.
Parameters:
Returns:
Example:
> const tr = nudged.transform.fromPolar({ x: 4, y: 2 }, 2, 0)
> const p = { x: 2, y: 1 }
> nudged.point.transform(p, tr)
{ x: 0, y: 0 }
Source: fromPolar.js
Create a transform that rotates around the center by the radians.
Parameters:
Returns:
Example:
> let rot = nudged.transform.fromRotation({ x: 4, y: 2 }, Math.PI / 5)
> rot
{ a: 0.809..., b: 0.587..., x: 1.939..., y: -1.969... }
Source: fromRotation.js
Create a transform that scales in respect of the center point and the scale multiplier. Such transform is called a homothety.
Parameters:
Returns:
Example:
> let x2 = nudged.transform.fromScale({ x: 4, y: 2 }, 2)
> x2
{ a: 2, b: 0, x: -4, y: -2 }
Source: fromScale.js
Create a transform from a string that uses
the CSS transform matrix syntax: matrix(1.0, 2.0, 3.0, 4.0, 5.0, 6.0)
Together with nudged.transform.toString this method makes an easy serialization and deserialization to and from strings.
Note that the function does not yet support other CSS transform functions such as ‘translate’ or ‘perspective’. It might also give unexpected results if the matrix exhibits shear or non-uniform scaling.
Parameters:
Returns:
Throws:
Source: fromString.js
Create a transform that translates { 0, 0 } to the point { x, y }.
Parameters:
Returns:
Example:
> let tl = nudged.transform.fromTranslation({ x: 4, y: 2 })
> tl
{ a: 1, b: 0, x: 4, y: 2 }
Source: fromTranslation.js
Get rotation of the transform in radians. The rotation is measured from the positive x-axis towards the positive y-axis.
Parameters:
Returns:
Example:
> const t = nudged.transform.ROT180
> nudged.transform.getRotation(t)
3.1415...
Source: getRotation.js
Get the scale multiplier of the transformation.
Parameters:
Returns:
Example:
> const t = nudged.transform.HALF
> nudged.transform.getScale(t)
0.5
Source: getScale.js
Get the translating component of the given transform
as a vector { x, y }.
Parameters:
Returns:
Example:
> const t = nudged.transform.ROT45
> nudged.transform.getTranslation(t)
{ x: 0, y: 0 }
Source: getTranslation.js
Compute inversed transform. In other words, find transform X so that TX = XT = I, where T is the given transform.
Parameters:
Throws:
Returns:
Source: inverse.js
Rotate image of the transform by the given radians so that the given center point stays fixed.
Parameters:
Returns:
Source: rotateBy.js
Rotate the image of the transform to the given angle so that the given center point stays fixed. The angle is relative to the x-axis of the domain of the transformation. After the rotation, x-axis of the image and a line at the angle are equal or parallel.
Parameters:
Returns:
Source: rotateTo.js
Scale the image of the transform by the given multiplier so that the given center point stays fixed. The operation is also called homothety.
Parameters:
Returns:
Source: scaleBy.js
Scale the transform tr so that 1) its scale multiplier becomes equal with the given scale, and 2) its image stays fixed at the given center point.
Parameters:
Returns:
Source: scaleTo.js
Represent the transform as a 4-element array. This the array is compatible with nudged.transform.fromArray.
Parameters:
Returns:
[a, b, x, y]Source: toArray.js
Get the similarity transformation matrix in the format common to other APIs, including:
Parameters:
Returns:
{ a, b, c, d, e, f } that represents the matrix below.┌ ┐
│ a c e │
│ b d f │
│ 0 0 1 │
└ ┘
Example:
> nudged.transform.toMatrix(tr)
{ a: 0.48, c: -0.52, e: 205.04,
b: 0.52, d: 0.48, f: 4.83 }
Source: toMatrix.js
Returns: a string of CSS transform-function data type.
Together with nudged.transform.fromString, this method allows serialization to and from strings.
Example:
> let sc = nudged.transform.fromScale({ x: 4, y: 2 }, 2)
> nudged.transform.toString(sc)
'matrix(2.00000000,0.00000000,0.00000000,2.00000000,-4.00000000,-2.00000000)'
The matrix values are fixed to 8 decimals. This prevents bugs caused by the scientific notation e.g. ‘1e-12’. The default JavaScript number-to-string conversion might produce scientific notation with some very large and very small numbers. The scientific notation is not understood by all CSS parsers. We have experienced problems with Safari and Opera. Therefore toString must prevent the scientific notation here and convert to fixed number of decimal places. See SO for further details.
Source: toString.js
Modify transformation so that its image is translated by the given vector. Scale and rotation are kept intact. In other words the resulting transform first applies the given tr and applies an additional translation defined by the given vector.
Parameters:
{ x, y }Returns:
Source: translateBy.js
Modify transformation so that it maps { x: 0, y: 0 } to the given point.
The rotation and scale are kept intact.
Parameters:
Returns:
Source: translateTo.js
Check if the value is a valid, non-singular affine transformation.
A valid non-singular affine transformation must have properties
a, b, x, and y and the sum of a and b must not approach zero.
Parameters:
Returns:
Source: validate.js
Contains the module version string identical to the version tag in package.json. This feature is powered by genversion.
Example:
> nudged.version
'2.3.4'
Source: lib/index.js