@allmaps/transform
Advanced tools
This module serves to transform points, lines, polygons and other spatial features from a cartesian (x, y) source plane to a destination plane. It does this using a set of control points, who's coordinates are known in both planes, and a specific transformation algorithm.
It is used in @allmaps/render and @allmaps/tileserver, two packages where we produce a georeferenced image by triangulating a IIIF image and drawing these triangles on a map in a specific new location, with the triangle's new vertex location computed by the transformer of this package. The transformer is constructed from control points in the annotation and transforms points from the resource coordinate space of a IIIF Resource to the geo coordinate space of an interactive map.
Care was taken to make this module usable and useful outside of the Allmaps context as well! Feel free to incorporate it in your project.
This package exports the GcpTransformer class. Its instances (called transformers) are built from a set of Ground Control Points (GCPs) and a specified transformation type. Using these, a forward and backward transformation can be built that maps arbitrary points in one plane to the corresponding points in the other plane. The transformer has dedicated functions that use this transformation to transform points and more complex geometries like line strings and polygons.
The transformation algorithms of this package correspond to those of GDAL and the results are (nearly) identical. See the tests for details.
For a little history: this library started out as a JavaScript port of gdaltransform (as described in this notebook) and initially only implemented polynomial transformations of order 1. Later Thin Plate Spline transformations were added (see this notebook) amongst other transformations, which lead to a refactoring using the ml-matrix library. This library is used for creating and solving the linear systems of equations that are at the heart of each of each of these transformations.
GCPs can be supplied as an array of objects containing source and destination coordinates:
type TransformGcp = {
source: [number, number]
destination: [number, number]
}
Or you can supply an array of objects containing resource and geo coordinates. This is the format used in Georeference Annotations:
type Gcp = {
resource: [number, number],
geo: [number, number]
}
| Type | Options | Description | Properties | Minimum number of GCPs |
|---|---|---|---|---|
helmert | Helmert transformation or 'similarity transformation' | Preserves shape and angle | 2 | |
polynomial (default) | order: 1 | First order polynomial transformation | Preserves lines and parallelism | 3 |
polynomial | order: 2 | Second order polynomial transformation | Some bending flexibility | 6 |
polynomial | order: 3 | Third order polynomial transformation | More bending flexibility | 10 |
thinPlateSpline | Thin Plate Spline transformation or 'rubber sheeting' (with affine part) | Exact, smooth (see this notebook) | 3 | |
projective | Projective or 'perspective' transformation, used for aerial images | Preserves lines and cross-ratios | 4 |
A transformer is build from a set of GCPs and a transformation type. It contains the forward and backward transformation, and has specific methods to apply it to transform geometries forward and backward.
All transformer methods accepts points, line strings as well as polygons, both as simple geometries or GeoJSON geometries. There are, however, separate methods for transforming to simple geometries or to GeoJSON geometries. There are also separate methods for transforming forward or backward.
Hence, the main methods are: transformForward(), transformForwardAsGeojson(), transformBackward() and transformBackwardAsGeojson()
Alternatively the same four methods are available with more expressive term for the Allmaps use case: replacing Forward by ToGeo and Backward by ToResource. E.g.: transformToGeoAsGeojson().
The simple geometries are:
type Point = [number, number]
type LineString = Point[]
type Polygon = Point[][]
// A polygon is an array of rings of at least three points
// Rings are not closed: the first point is not repeated at the end.
// There is no requirement on winding order.
type Geometry = Point | LineString | Polygon
When transforming a line or polygon, it can happen that simply transforming every point is not sufficient. Two factors are at play which may require a more granular transformation: the transformation (which can be non-shape preserving, as is the case with all transformation in this package except for Helmert and 1st degree polynomial) or the geographic nature of the coordinates (where lines are generally meant as 'great arcs' but could be interpreted as lon-lat cartesian lines). An algorithm will therefore recursively add midpoints in each segment (i.e. between two points) to make the line more granular. A midpoint is added at the transformed middle point of the original segment on the condition that the ratio of (the distance between the middle point of the transformed segment and the transformed middle point of the original segment) to the length of the transformed segment, is larger then a given ratio. The following options specify if and with what degree of detail such extra points should be added.
| Option | Description | Default |
|---|---|---|
maxOffsetRatio | Maximum offset ratio (smaller means more midpoints) | 0 |
maxDepth | Maximum recursion depth (higher means more midpoints) | 0 |
sourceIsGeographic | Use geographic distances and midpoints for lon-lat source points | false (true when source is GeoJSON) |
destinationIsGeographic | Use geographic distances and midpoints for lon-lat destination points | false (true when destination is GeoJSON) |
This is an ESM-only module that works in browsers and in Node.js.
Install with npm:
npm install @allmaps/transform
import { GcpTransformer } from '@allmaps/transform'
const transformGcps3 = [
{
source: [518, 991],
destination: [4.9516614, 52.4633102]
},
{
source: [4345, 2357],
destination: [5.0480391, 52.5123762]
},
{
source: [2647, 475],
destination: [4.9702906, 52.5035815]
}
]
const transformer = new GcpTransformer(transformGcps3, 'helmert')
const transformedPoint = transformer.transformForward([100, 100])
// transformedPoint = [4.9385700843392435, 52.46580484503631]
const transformedPoint = transformer.transformBackward([
4.9385700843392435, 52.46580484503631
])
// transformedPoint = [100, 100]
In this example we transform backward, and from a GeoJSON Geometry.
export const transformGcps7 = [
{
source: [0, 0],
destination: [0, 0]
},
{
source: [100, 0],
destination: [20, 0]
},
{
source: [200, 100],
destination: [40, 20]
},
{
source: [200, 200],
destination: [40, 40]
},
{
source: [150, 250],
destination: [40, 100]
},
{
source: [100, 200],
destination: [20, 40]
},
{
source: [0, 100],
destination: [0, 20]
}
]
const transformOptions = {
maxOffsetRatio: 0.001,
maxDepth: 2
}
// We transform backward (from destination to source) and have GeoJSON input.
// Hence `destinationIsGeographic: true` will be set automatically
const transformer = new GcpTransformer(transformGcps7, 'polynomial')
const lineStringGeoJSON = {
type: 'LineString',
coordinates: [
[10, 50],
[50, 50]
]
}
const transformedLineString = transformer.transformBackward(
lineStringGeoJSON,
transformOptions
)
// transformedLineString = [
// [31.06060606060611, 155.30303030303048],
// [80.91200458875993, 165.7903106766409],
// [133.1658635549907, 174.5511756850417],
// [185.89024742146262, 181.22828756380306],
// [237.12121212121218, 185.60606060606085]
// ]
// Notice how the result has two layers of midpoints!
// In a first step the point [133.16, 174.55] is added between the start and end point
// Then [80.91, 165.79] and [185.89, 181.22] are added in between.
In this example we transform to a GeoJSON Geometry.
export const transformGcps6 = [
{
source: [1344, 4098],
destination: [4.4091165, 51.9017125]
},
{
source: [4440, 3441],
destination: [4.5029222, 51.9164451]
},
{
source: [3549, 4403],
destination: [4.4764224, 51.897309]
},
{
source: [1794, 2130],
destination: [4.4199066, 51.9391509]
},
{
source: [3656, 2558],
destination: [4.4775683, 51.9324358]
},
{
source: [2656, 3558],
destination: [4.4572643, 51.9143043]
}
]
const transformOptions = {
maxOffsetRatio: 0.00001,
maxDepth: 1
}
const transformer = new GcpTransformer(transformGcps6, 'thinPlateSpline')
const polygon = [
[
[1000, 1000],
[1000, 2000],
[2000, 2000],
[2000, 1000]
]
]
const transformedPolygonGeoJSON = transformer.transformForwardAsGeojson(
polygon,
transformOptions
)
// const transformedPolygonGeoJSON = {
// type: 'Polygon',
// coordinates: [
// [
// [4.388957777030093, 51.959084191571606],
// [4.390889520773774, 51.94984430356657],
// [4.392938913951547, 51.94062947962427],
// [4.409493277493718, 51.94119110133424],
// [4.425874493300959, 51.94172557475595],
// [4.4230497784967655, 51.950815146974556],
// [4.420666790347598, 51.959985351835975],
// [4.404906205946158, 51.959549039424715],
// [4.388957777030093, 51.959084191571606]
// ]
// ]
// }
A Ground Control Point Transformer, containing a forward and backward transformation and specifying functions to transform geometries using these transformations.
gcps (Array<TransformGcp> | Array<Gcp>) An array of Ground Control Points (GCPs)type TransformationType The transformation type (optional, default 'polynomial')Transforms a Geometry or a GeoJSON geometry forward to a Geometry
input (Geometry | GeojsonGeometry) Geometry or GeoJSON geometry to transformoptions PartialTransformOptions? Transform optionsReturns Geometry Forward transform of input as Geometry
Transforms a Geometry or a GeoJSON geometry forward to a GeoJSON geometry
input (Geometry | GeojsonGeometry) Geometry or GeoJSON geometry to transformoptions PartialTransformOptions? Transform optionsReturns GeojsonGeometry Forward transform of input, as GeoJSON geometry
Transforms a geometry or a GeoJSON geometry backward to a Geometry
input (Geometry | GeojsonGeometry) Geometry or GeoJSON geometry to transformoptions PartialTransformOptions? Transform optionsReturns Geometry backward transform of input, as geometry
Transforms a Geometry or a GeoJSON geometry backward to a GeoJSON geometry
input (Geometry | GeojsonGeometry) Geometry or GeoJSON geometry to transformoptions PartialTransformOptions? Transform optionsReturns GeojsonGeometry backward transform of input, as GeoJSON geometry
Transforms Geometry or GeoJSON geometry forward, as Geometry
input (Geometry | GeojsonGeometry) Input to transformoptions Returns Geometry Forward transform of input, as Geometry
Transforms a Geometry or a GeoJSON geometry forward, to a GeoJSON geometry
input (Geometry | GeojsonGeometry) Input to transformoptions Returns Geometry Forward transform of input, as GeoJSON geometry
Transforms a Geometry or a GeoJSON geometry backward, to a Geometry
input (Geometry | GeojsonGeometry) Input to transformoptions Returns Geometry Backward transform of input, as a Geometry
Transforms a Geometry or a GeoJSON geometry backward, to a GeoJSON geometry
input (Geometry | GeojsonGeometry) Input to transformoptions Returns GeojsonGeometry Backward transform of input, as a GeoJSON geometry
Transforms a SVG geometry forward to a GeoJSON geometry
geometry SvgGeometry SVG geometry to transformtransformOptions Returns GeojsonGeometry Forward transform of input, as a GeoJSON geometry
Transforms a GeoJSON geometry backward to a SVG geometry
geometry GeojsonGeometry GeoJSON geometry to transformtransformOptions Returns SvgGeometry Backward transform of input, as SVG geometry
(x, y) plane to another. Using control points with (longitude, latitude) coordinates will produce a transformation from or to the cartesian plane of an equirectangular projection. (The only semi-exception to this is when using the destinationIsGeographic and sourceIsGeographic parameters - although these consider coordinates as lying on a sphere more than as projection coordinates.)The @allmaps/cli package creates and interface for four specific use cases:
Here are some benchmarks on building and using a transformer, as computed on a 2023 MacBook Air M2.
Creating a transformer (with 10 points) (and transform 1 point)
| Type | Options | Ops/s |
|---|---|---|
helmert | 71338 | |
polynomial | order: 1 | 163419 |
polynomial | order: 2 | 86815 |
polynomial | order: 3 | 33662 |
thinPlateSpline | 27905 | |
projective | 36202 |
Using a transformer (with 10 points) to transform 1 point
| Type | Options | Ops/s |
|---|---|---|
helmert | 27398212 | |
polynomial | order: 1 | 22364872 |
polynomial | order: 2 | 19126410 |
polynomial | order: 3 | 3925102 |
thinPlateSpline | 484141 | |
projective | 22657850 |
See ./bench/index.js.
The benchmark can be run with pnpm run bench.
FAQs
Coordinate transformation functions
The npm package @allmaps/transform receives a total of 200 weekly downloads. As such, @allmaps/transform popularity was classified as not popular.
We found that @allmaps/transform demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.