Class: transform

geo. transform

new geo.transform(options){geo.transform}

This purpose of this class is to provide a generic interface for computing coordinate transformations. The interface is taken from proj4js, which also provides the geospatial projection implementation. The interface is intentionally simple to allow for custom, non-geospatial use cases. For further details, see http://proj4js.org/

The default transforms lat/long coordinates into web mercator for use with standard tile sets.

This class is intended to be extended in the future to support 2.5 and 3 dimensional transformations. The forward/inverse methods take optional z values that are ignored in current mapping context, but will in the future perform more general 3D transformations.

Name Type Description
options object

Constructor options

Name Type Description
source string

A proj4 string for the source projection

target string

A proj4 string for the target projection

Returns:
Type Description
geo.transform

Static Members

staticgeo.transform.defs

Contains a reference to proj4.defs. The functions serves two purposes.

  1. It is a key value mapping of all loaded projection definitions
  2. It is a function that will add additional definitions.

See: http://proj4js.org/

Static Methods

staticgeo.transform.affineForward(def, coords){Array.<geo.geoPosition>}

Apply an affine transformation consisting of a translation then a scaling to the given coordinate array. Note, the transformation occurs in place so the input coordinate object are mutated.

Name Type Description
def object
Name Type Description
origin geo.geoPosition

The transformed origin

scale object

The transformed scale factor. This is an object with x, y, and z parameters.

coords Array.<geo.geoPosition>

An array of coordinate objects.

Returns:
Type Description
Array.<geo.geoPosition> The transformed coordinates.

staticgeo.transform.affineInverse(def, coords){Array.<geo.geoPosition>}

Apply an inverse affine transformation which is the inverse to geo.transform.affineForward. Note, the transformation occurs in place so the input coordinate object are mutated.

Name Type Description
def object
Name Type Description
origin geo.geoPosition

The transformed origin

scale object

The transformed scale factor. This is an object with x, y, and z parameters.

coords Array.<geo.geoPosition>

An array of coordinate objects.

Returns:
Type Description
Array.<geo.geoPosition> The transformed coordinates.

staticgeo.transform.lookup(projection){promise}

Look up a projection definition from epsg.io. For the moment, we only handle EPSG codes.

Name Type Description
projection string

A projection alias (e.g. EPSG:4326)

Returns:
Type Description
promise Resolves with the proj4 definition

staticgeo.transform.sphericalDistance(pt1, pt2, gcs, baseGcs, ellipsoid, maxIterations){number}

Compute the distance on the surface on a sphere. The sphere is the major radius of a specified ellipsoid. Altitude is ignored.

Name Type Default Description
pt1 geo.geoPosition

The first point.

pt2 geo.geoPosition

The second point.

gcs string | geo.transform optional

undefined to use the same gcs as the ellipsoid, otherwise the gcs of the points.

baseGcs string | geo.transform 'EPSG:4326' optional

the gcs of the ellipsoid.

ellipsoid object proj4.WGS84 optional

An object with at least a and one of b, f, or rf (1 / f) -- this works with proj4 ellipsoid definitions.

maxIterations number 100 optional

Maximum number of iterations to use to test convergence.

Returns:
Type Description
number The distance in meters (or whatever units the ellipsoid was specified in.

staticgeo.transform.transformCoordinates(srcPrj, tgtPrj, coordinates, numberOfComponents){geoPosition|Array.<geoPosition>|Array.<number>}

Transform an array of coordinates from one projection into another. The transformation may occur in place (modifying the input coordinate array), depending on the input format. The coordinates can be an object with x, y, and (optionally z) or an array of 2 or 3 values, or an array of either of those, or a single flat array with 2 or 3 components per coordinate. Arrays are always modified in place. Individual point objects are not altered; new point objects are returned unless no transform is needed.

Name Type Description
srcPrj string

The source projection.

tgtPrj string

The destination projection.

coordinates geoPosition | Array.<geoPosition> | Array.<number>

An array of coordinate objects. These may be in object or array form, or a flat array.

numberOfComponents number

For flat arrays, either 2 or 3.

Returns:
Type Description
geoPosition | Array.<geoPosition> | Array.<number> The transformed coordinates.

staticgeo.transform.transformCoordinatesArray(trans, coordinates, numberOfComponents){Array.<geoPosition>|Array.<number>}

Transform an array of coordinates from one projection into another. The transformation may occur in place (modifying the input coordinate array), depending on the input format. The coordinates can be an array of 2 or 3 values, or an array of either of those, or a single flat array with 2 or 3 components per coordinate. The array is modified in place.

Name Type Description
trans transform

The transformation object.

coordinates Array.<geoPosition> | Array.<number>

An array of coordinate objects or a flat array.

numberOfComponents number

For flat arrays, either 2 or 3.

Returns:
Type Description
Array.<geoPosition> | Array.<number> The transformed coordinates

staticgeo.transform.transformCoordinatesFlatArray3(srcPrj, tgtPrj, coordinates){Array.<number>}

Transform an array of coordinates from one projection into another. The transformation occurs in place, modifying the input coordinate array. The coordinates are an array of [x0, y0, z0, x1, y1, z1, ...].

Name Type Description
srcPrj string

The source projection.

tgtPrj string

The destination projection. This must not be the same as the source projection.

coordinates Array.<number>

A flat array of values.

Returns:
Type Description
Array.<number> The transformed coordinates.

staticgeo.transform.vincentyDistance(pt1, pt2, gcs, baseGcs, ellipsoid, maxIterations){object}

Compute the Vincenty distance on the surface on an ellipsoid. Altitude is ignored.

Name Type Default Description
pt1 geo.geoPosition

The first point.

pt2 geo.geoPosition

The second point.

gcs string | geo.transform optional

undefined to use the same gcs as the ellipsoid, otherwise the gcs of the points.

baseGcs string | geo.transform 'EPSG:4326' optional

the gcs of the ellipsoid.

ellipsoid object proj4.WGS84 optional

An object with at least a and one of b, f, or rf (1 / f) -- this works with proj4 ellipsoid definitions.

maxIterations number 100 optional

Maximum number of iterations to use to test convergence.

Returns:
Type Description
object An object with distance in meters (or whatever units the ellipsoid was specified in), alpha1 and alpha2, the azimuths at the two points in radians. The result may be undefined if the formula fails to converge, which can happen near antipodal points.

Methods

protectedforward(point){geo.geoPosition|Array.<geo.geoPosition>}

Perform a forward transformation (source -> target) in place.

Name Type Description
point geo.geoPosition | Array.<geo.geoPosition>

The point coordinates or array of points in source coordinates.

Returns:
Type Description
geo.geoPosition | Array.<geo.geoPosition> A point object or array in the target coordinates.

protectedinverse(point){geo.geoPosition|Array.<geo.geoPosition>}

Perform an inverse transformation (target -> source) in place.

Name Type Description
point geo.geoPosition | Array.<geo.geoPosition>

The point coordinates or array of points in target coordinates.

Returns:
Type Description
geo.geoPosition | Array.<geo.geoPosition> A point object or array in the source coordinates.

source(arg){string|this}

Get/Set the source projection.

Name Type Description
arg string optional

The new source projection. If undefined, return the current source projection.

Returns:
Type Description
string | this The current source projection if it was queried, otherwise the current transform object.

target(arg){string|this}

Get/Set the target projection.

Name Type Description
arg string optional

The new target projection. If undefined, return the current target projection.

Returns:
Type Description
string | this The current target projection if it was queried, otherwise the current transform object.

innerparse_projection(value){object}

Parse a projection string. If the projection string includes any of +s[123][123]= or +[xyz]off=, those values are converted into a matrix and removed from the projection string. This allows applying affine transforms as specified in Proj 6.0.0 to be used (excluding toff and tscale). This could can be removed once proj4js supports the affine parameters.

Name Type Description
value string

A proj4 string possibly with affine parameters.

Returns:
Type Description
object An object with a string value 'proj' and optional array values 'matrix' and 'inverse' (either both or neither will be present). The returned matrices are always 16-value arrays if present. The proj value is the proj4 string with the affine parameters removed.