Datum transformations

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.

ArcGIS Maps SDK for Unreal Engine API supports:

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

• 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

The standards for how coordinates should be transformed are defined by agencies such as the U.S. 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, similar to how spatial references are identified. Transformations can vary in accuracy, and selecting the most suitable transformation for your specific use 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 can be created with the ArcGIS Maps SDK for Unreal Engine API by one or more steps (the ArcGISGeographicTransformationStep or ArcGISHorizontalVerticalTransformationStep type) in a transformation (the ArcGISGeographicTransformation or ArcGISHorizontalVerticalTransformation type).

Grid-based transformations

Datum transformations can be mathematically defined (equation-based transformations), or may rely on external supporting files (grid-based transformations). Certain Projection Engine data files must be present when you use a grid-based transformation in your app; attempting to use a transformation with missing Projection Engine files will cause an error. The API can detect whether the necessary files are available on the local file system.

The data files should reside in the Projection Engine location specified in the transformation catalog. To set the Projection Engine directory SetProjectionEngineDirectory, you must do so at app startup, before other calls that use the Projection Engine. The Projection Engine data files are available on the Downloads page.

Check for Projection Engine files

If the supporting file for a grid-based transformation cannot be located on the local file system, that transformation cannot be used. This will not happen when relying on the default transformation but can happen if the Projection Engine location is not set, if specific datasets are missing when using a transformation from a list returned by the transformation catalog, or when creating transformations from WKID or WKT.

You can identify such cases using the IsMissingProjectionEngineFiles method on the transformation step object (the ArcGISGeographicTransformationStep or ArcGISHorizontalVerticalTransformationStep type). Your app could include detailed messages for users about precisely which files are missing or even automatically download any missing files from a known location. You can retrieve the list of required files using the ProjectionEngineFilenames method of the transformation step object.

Default transformations

When data is reprojected from one spatial reference to another in ArcGIS Maps SDK for Unreal Engine, an internal algorithm uses the best transformation available by default without requiring that you 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 used together to determine the default transformation. If no transformation is required for the two spatial references (for example, two projected coordinate systems with the same underlying geographic coordinate system), 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.

ArcGIS Maps SDK for Unreal Engine also ensures that the default transformation is usable and available (for example, is not a grid-based transformation that requires files that are missing from the local file system). In this scenario, if the best transformation is grid-based but the necessary files are not present, it is not the best available transformation.

Customize default transformations

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

To change your geographic transformation defaults, create a JSON file named gtdefaults_overrides.json and place it in the location returned from the transformation catalog method ProjectionEngineLocation.

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 transformation 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.

ArcGIS Maps SDK for Unreal Engine checks whether a geographic transformation defined in this file is useable before attempting to use it. If it is not, the internal default is used.

Consider the work area extent

Your work area may be small or otherwise unsuited to the default transformation. You can improve spatial accuracy by finding the best transformation for your specific work area. For example, you may need a transformation that can be used when calling the geometry engine (the ArcGISGeometryEngine type) to project a geometry.

Use the overloads in the transformation catalog's Transformation and TransformationsBySuitability methods to pass in an extent for which you will transform geometries.

Choose a transformation from a list

The transformation catalog provides a list of transformations that can be used between two spatial references. The TransformationsBySuitability method on the ArcGISTransformationCatalog returns the list of transformations ranked in descending order by suitability. With this, you could provide your app users with a workflow from which to choose the most suitable transformations.

The list from TransformationsBySuitability may include grid-based transformations that require supporting files not stored 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 (ArcGISHorizontalVerticalTransformation) is returned; otherwise, a list of geographic transformations (ArcGISGeographicTransformation) is returned.

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 other data source. The Project method on the geometry engine (the ArcGISGeometryEngine type) uses the default transformation without requiring that you 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 the list returned from the catalog or one created by the WKID.

Create a specific transformation by WKID

You can create a geographic transformation by passing a WKID to a ArcGISGeographicTransformationStep, then adding one or more steps to a ArcGISGeographicTransformation. To also account for vertical datum change, create a horizontal-vertical transformation by passing in a geographic (horizontal) or vertical transformation WKID to a ArcGISHorizontalVerticalTransformationStep, then add one or more steps to a ArcGISHorizontalVerticalTransformation. This transformation can then be used, for example, when calling the geometry engine (the ArcGISGeometryEngine type) to project a geometry.

There is not a defined transformation process to convert every geographic datum to every other, or 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 World Geodetic System 1984 (WGS84) datum. 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 follow WGS84, with one forward and one inverse datum transformation chained together to perform the complete geographic transformation. Additionally, there is a limited list of geographic transformations directly between two non-WGS84 datums, such as for WKID 4461: NAD_1983_HARN_To_NAD_1983_NSRS2007_1. You can use these 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 data files can be 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 transformation methods (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 data files can be found on the local file system.