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
|
Returns:
Type | Description |
---|---|
geo.transform |
Static Members
-
staticgeo.transform.defs
-
Contains a reference to
proj4.defs
. The functions serves two purposes.- It is a key value mapping of all loaded projection definitions
- 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
, andz
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
, andz
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.onlyInvertedY(srcPrj, tgtPrj){boolean}
-
Return a boolean indicating if the projections only differ in their y coordinate.
Name Type Description srcPrj
string The source projection.
tgtPrj
string The destination projection.
Returns:
Type Description boolean truthy if only the y coordinate is different between projections. -
staticgeo.transform.sphericalDistance(pt1, pt2, gcs, baseGcs, ellipsoid){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 ofb
,f
, orrf
(1 /f
) -- this works with proj4 ellipsoid definitions.Returns:
Type Description number The distance in meters (or whatever units the ellipsoid was specified in. -
staticgeo.transform.transformCoordinates(srcPrj, tgtPrj, coordinates, numberOfComponents){geo.geoPosition|Array.<geo.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
geo.geoPosition | Array.<geo.geoPosition> | Array.<number> An array of coordinate objects. These may be in object or array form, or a flat array.
numberOfComponents
number optional For flat arrays, either 2 or 3.
Returns:
Type Description geo.geoPosition | Array.<geo.geoPosition> | Array.<number> The transformed coordinates. -
staticgeo.transform.transformCoordinatesArray(trans, coordinates, numberOfComponents){Array.<geo.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.<geo.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.<geo.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 ofb
,f
, orrf
(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
andalpha2
, the azimuths at the two points in radians. The result may beundefined
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.