coordinatetransformer

The Coordinate Transformer transforms geometries from a source coordinate system to a target coordinate system.

Additionally it can be used to retrieve a list of available coordinate reference systems.

Usage

No configuration is needed. Default values are applied.

To get more details about the API of the CoordinateTransformer, see the following use cases and the API documentation.

Configuration Reference

The following app.json file excerpt shows the configurable default properties of this bundle:

"coordinatetransformer": {
    "CoordinateTransformer": {
        // Enforce use of Proj4js
        "enforceProj4js": false,
        // Enforce async transformation methods
        "useAsyncTransformation": true,
        // custom srs definitions
        "srsDefinitions": {}
    }
}

The following spatial reference systems are preconfigured:

"defaultSrsDefinitions": {
    "EPSG:2056": "+title=Swiss CH1903 / LV95 +proj=somerc +lat_0=46.95240555555556 +lon_0=7.439583333333333 +k_0=1 +x_0=2600000 +y_0=1200000 +ellps=bessel +towgs84=674.374,15.056,405.346,0,0,0,0 +units=m +no_defs",
    "EPSG:4326": "+title=long/lat:WGS84 +proj=longlat +datum=WGS84 +no_defs",
    "EPSG:3857": "+title=WGS 84 / Pseudo-Mercator +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +wktext  +no_defs",
    "EPSG:10732": "+title=${EPSG_10732} +proj=utm +zone=32 +ellps=GRS80 +units=m +no_defs",
    "EPSG:10733": "+title=${EPSG_10733} +proj=utm +zone=33 +ellps=GRS80 +units=m +no_defs",
    "EPSG:25832": "+title=${EPSG_25832} +proj=utm +zone=32 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs",
    "EPSG:25833": "+title=${EPSG_25833} +proj=utm +zone=33 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs",
    "EPSG:31466": "+title=${EPSG_31466} +proj=tmerc +lat_0=0 +lon_0=6 +k=1 +x_0=2500000 +y_0=0 +ellps=bessel +towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7 +units=m +no_defs",
    "EPSG:31467": "+title=${EPSG_31467} +proj=tmerc +lat_0=0 +lon_0=9 +k=1 +x_0=3500000 +y_0=0 +ellps=bessel +towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7 +units=m +no_defs",
    "EPSG:31468": "+title=${EPSG_31468} +proj=tmerc +lat_0=0 +lon_0=12 +k=1 +x_0=4500000 +y_0=0 +ellps=bessel +towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7 +units=m +no_defs",
    "EPSG:31469": "+title=${EPSG_31469} +proj=tmerc +lat_0=0 +lon_0=15 +k=1 +x_0=5500000 +y_0=0 +ellps=bessel +towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7 +units=m +no_defs",
    "EPSG:32632": "+title=${EPSG_32632} +proj=utm +zone=32 +datum=WGS84 +units=m +no_defs",
    "EPSG:32633": "+title=${EPSG_32633} +proj=utm +zone=33 +datum=WGS84 +units=m +no_defs",
    "EPSG:26591": "+title=${EPSG_26591} +proj=tmerc +lat_0=0 +lon_0=-3.45233333333333 +k=0.9996 +x_0=1500000 +y_0=0 +ellps=intl +towgs84=-104.1,-49.1,-9.9,0.971,-2.917,0.714,-11.68 +pm=rome +units=m +no_defs",
    "EPSG:26912": "+title=${EPSG_26912} +proj=utm +zone=12 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs"
}

The list of available spatial reference can be extended with the property srsDefinitions. The following sample adds Pulkovo 1942 as spatial reference system.

"coordinatetransformer": {
    "CoordinateTransformer": {
        "srsDefinitions": {
            "EPSG:2583": "+title=Pulkovo 1942 / 3-degree Gauss-Kruger +proj=tmerc +lat_0=0 +lon_0=24 +k=1 +x_0=500000 +y_0=0 +ellps=krass +towgs84=23.92,-141.27,-80.9,-0,0.35,0.82,-0.12 +units=m +no_defs"
        }
    }
}

The projection configuration string is a Proj4js API specific format. The website epsg.io provides information about spatial reference systems, for example the previously mentioned EPSG:2583.

The title property can be used with every transformation strategy (see next section). The other properties are only interpreted if the Proj4js API strategy is used.

Transformation Strategies

The following transformation strategies are supported:

Name	Description
Projection Engine	The default strategy. It uses the `@arcgis/core/geometry/project` engine to transform geometries. It requires the browser to support Web-Assembly.
Proj4js API	The default fallback for browsers, that do not support the projection engine.

Use Cases

Develop with the CoordinateTransformationService

See the CoordinateTransformer API for a sample on how to use this component in a custom bundle.

Together with the CoordinateTransformer, a ProjectionsStore is provided. For a sample on how to use this component in a custom bundle, see the ProjectionStore API. The store provides access to the configured projections. It returns projection items.

Enforce `Proj4js` transformation strategy

To enforce the use of Proj4js, set enforceProj4js to true.

"coordinatetransformer": {
    "CoordinateTransformer": {
        "enforceProj4js": true
    }
}

This feature is provided for backward compatibility and as fallback for browsers that do not support Web-Assembly.

Disable the asynchronous behavior of the transform methods

By default the transform methods return Promise instances. To enforce a synchronous behavior, set useAsyncTransformation to false.

"coordinatetransformer": {
    "CoordinateTransformer": {
        "useAsyncTransformation": false
    }
}

This feature is provided for backward compatibility. We recommend to prevent its usage and to change failing code.

Provide a custom transformation strategy

It is possible to provide a custom transformation strategy, if the default is not sufficient or special behavior is required. For more details, see the TransformerStrategy API description.

Provide custom transformations to a strategy

A transformation strategy usually transforms between spatial reference systems by applying a default transformation. The default transformation can be overridden by implementing the TransformationProvider interface when using a supporting transformation strategy. The builtin strategy Projection Engine supports custom transformation providers.