Datum transformation

Datum transformations are used when geometries must be projected from one spatial reference to another when there is a difference in the datum that underlies the two spatial references. The following transformations are supported:

• Horizontal (geographic) and vertical datum transformations
• Ellipsoidal and grid-based transformations

As a developer, you can:

• Obtain the default transformation for the projection.
• Customize the default transformation used by your app through a JSON configuration file.
• Consider the best transformation for a specific work area.
• Choose from a list of suitable transformations from the transformation catalog for a given pair of spatial references and optionally a given geographic area.
• Create a transformation using WKIDs.
• Create a custom transformation using WKT, if you have even more specialized needs.

Horizontal and vertical transformations

Exactly how coordinates should be transformed is defined by agencies such as the US National Geodetic Survey. Esri's Projection Engine supports many predefined transformations, and more than one transformation may be available for a given datum change. Each transformation is identified by a WKID integer number and WKT text string definition, similarly to how spatial references are identified. Transformations vary in accuracy, and using the most suitable transformation for your specific case ensures the best possible accuracy for the reprojection.

Geographic transformations translate horizontal (x,y) coordinates from the geographic coordinate system of the input spatial reference to the geographic coordinate system of the output spatial reference, accounting for the difference in geographic (horizontal) datum. For spatial references with a vertical coordinate system set, vertical transformations translate vertical positions (z-values) from one vertical coordinate system to another, accounting for the difference in vertical datum. Horizontal and vertical transformations can be used together if there is a change in both datums.

Each of the supported predefined transformations and is represented by one or more steps (the GeographicTransformationStep or HorizontalVerticalTransformationStep type) in a transformation (the GeographicTransformation or HorizontalVerticalTransformation type).

Default transformations

When data is reprojected from one spatial reference to another, an internal algorithm uses the best transformation available by default without you needing to specify one.

Using the transformation catalog you can find out which transformation is used by default when projecting between any two spatial references.

The accuracy of each transformation, and the extent of the spatial reference covered, are together used to determine the default transformation. If no transformation is required for the two spatial references (for example, two projected coordinate systems that have the same underlying geographic coordinate system), TransformationCatalog.getTransformation will return null. If both spatial references have a vertical coordinate system, and there is a difference in vertical datum, then a horizontal-vertical transformation is returned; otherwise, a geographic transformation is returned.

The default transformation is also checked to ensure it is usable. For example, a grid-based transformation must have the Projection Engine transformation data files present on the local file system.

Customize default transformations

There may be cases where you want to specify your own default transformations. For example, if you wish to ensure default transformations match those used by an older version of ArcGIS Server or Desktop, or if you otherwise need to ensure a specific transformation is used but it is not feasible to specify a transformation every time you need to use one.

To change geographic transformation defaults, create a JSON file named gtdefaults_overrides.json and place it in the location returned from TransformationCatalog.projectionEngineDirectory.

An example of file content is:

1
2
3
4
5
6
{ "geogtran" : [
   [   3819,   3906,   3817,    0,   3962,    1 ],
   [   3819,   4075,   3817,    0,   4077,    1 ],
   [ 104248, 104896, 108038,    0,      0,    0 ],
   [ 104257, 104896, 108019,    1,      0,    0 ]
]}

This file contains one line per datum pair ("from" and "to"). Only include lines for the default geographic transformations that you want to override. The six columns have the following information.

1. The WKID of the "from" geographic coordinate system.
2. The WKID of the "to" geographic coordinate system.
3. The WKID of the first geographic transformation.
4. Whether to use the first geographic transformation forward (0) or use its inverse (1).
5. The WKID of the second geographic transformations WKID (or 0 if this is a single-step geographic transformation).
6. Whether to use the second geographic transformation forward (0) or use its inverse (1). (0 if this is a single-step geographic transformation).

To change horizontal-vertical transformation defaults, name a JSON file hvtdefaults_overrides.json. An example of the file content is:

1
2
3
4
{ "hvtran" : [
    [ 4326, 3855, 4326, 115700, -110019 ],
    [ 4326, 3855, 4463, 115786, -110019, -4477 ]
]}

The columns have the following information.

1. The WKID of the "from" geographic coordinate system.
2. The WKID of the "from" vertical coordinate system.
3. The WKID of the "to" geographic coordinate system.
4. The WKID of the "to" vertical coordinate system.
5. The WKID of the first horizontal or geographic transformation. Include a minus (-) to use the transformation in the inverse direction. Repeat multiple times to create a multi-step transformation.

A geographic transformation, defined in this file, is checked to determine whether it is usable. If it is not usable, the internal default is used.

Find and apply transformations

From the transformation catalog, you can retrieve a list of transformations usable between two spatial references. The transformationsBySuitability method on the TransformationCatalog returns a list of transformations in descending order by suitability. With this, you could provide your app users with a workflow wherein they are able to choose from a list of suitable transformations.

The list returned from transformationsBySuitability may include grid-based transformations whose supporting files are not found on the local file system. If both spatial references have a vertical coordinate system, and there is a difference in vertical datum, then a list of horizontal-vertical transformations (HorizontalVerticalTransformation) are returned; otherwise, geographic transformations (GeographicTransformation) are returned.

Consider the work area extent

Your work area may be small and located where the default transformation (that is, the best transformation for the entire spatial reference) is not the best for your work area. You may be able to improve accuracy by finding the best transformation for your specific work area. This transformation can then be used, for example, when calling the geometry engine (the GeometryEngine type) to project a geometry.

Use the overloads of the transformation catalog's transformation and transformationsBySuitability methods to pass in the extent for which you'll be transforming geometries.

Project geometries with a specific transformation

A common use case is to project a geometry, creating a new geometry that uses the same spatial reference as the map view or another data source. The project method on the geometry engine (the GeometryEngine type) uses the default transformation without you needing to specify one. Alternatively, you can specify a transformation each time you use the method to project a geometry, for example by passing in a transformation from a list returned from the catalog, or one created by WKID.

Create a specific transformation by WKID

You can create a geographic transformation by passing a WKID to a GeographicTransformationStep, then adding one or more steps to a GeographicTransformation. To account for vertical datum change as well, create a horizontal-vertical transformation by passing in a geographic (horizontal) or vertical transformation WKID to a HorizontalVerticalTransformationStep, then adding one or more steps to a HorizontalVerticalTransformation. This transformation can then be used, for example, when calling the geometry engine (the GeometryEngine type) to project a geometry.

There is not a defined transformation from every geographic datum to every other, and from every vertical datum to every other—such a collection would be very large.

The list of supported WKIDs includes a geographic transformation from every supported geographic (horizontal) datum to the datum named World Geodetic System 1984 (WGS84). Therefore, a geographic transformation is commonly composed of two steps, each step defining a datum transformation and the inverse of another datum transformation. Each geographic transformation step can be constructed from a well-known ID (WKID) that represents a datum transformation. Geographic transformations with more than one step typically go via WGS84, with one forward and one inverse datum transformation chained together to perform the complete geographic transformation. Additionally, there is limited list of geographic transformations directly between two non-WGS84 datums, such as WKID 4461, named NAD_1983_HARN_To_NAD_1983_NSRS2007_1. These may be used to create one-step geographic transformations. For vertical transformations, there is no common intermediate step.

If the transformation is grid-based, you must ensure that the supporting Projection Engine transformation data files are found on the local file system.

Create a custom transformation

Some users adjust the components of a transformation to suit their specific needs. These custom transformations use the existing methods of transformation (Position Vector, Geocentric_Translation, and so on) but have different parameter values than the well-known definitions. Create a custom transformation object by passing in a text string containing your custom transformation expressed in WKT format. The resulting transformation will have a WKID of zero. If the transformation is grid-based, you must ensure that the supporting Projection Engine transformation data files are found on the local file system.