Spatial references

A spatial reference is a characteristic of a geometry that identifies how its coordinates relate to real-world space. It is important to ensure that spatial data in different layers, graphic overlays, and feature sets can be used together for accurate viewing or analysis.

Spatial references can be referred to by a Well-Known ID (WKID)—an integer value. Some common WKIDs are mentioned in the text below; for a more complete description, see Spatial reference specifications in this topic. You can also find information about spatial references in ArcGIS Developers documentation.

Why spatial references are important

To integrate spatial data into a map or when performing analysis, ArcGIS Maps SDK for Unity must know where things are located on the Earth's surface and it uses coordinates to do this. Coordinates are expressed with respect to a coordinate system, which is a frame of reference around a model of the Earth's surface. Not all coordinates and their associated coordinate systems are the same; they can use various units (for example degrees minutes seconds, decimal degrees, or meters) and they can be based on different types of models. ArcGIS Maps SDK for Unity uses mathematical transformations to reproject coordinates from one coordinate system to another. A spatial reference provides all the information needed for reprojection.

Coordinate systems and projections

Data is defined in both horizontal and vertical coordinate systems. Horizontal coordinate systems locate data across the surface of the earth and are split into categories, geographic, projected, and local.

Geographic coordinate system

Geographic coordinate systems (GCSs) use a three-dimensional ellipsoidal surface to define locations. The coordinates are based on angles from the center of the Earth to the surface. Typically GCSs use latitude and longitude specified in degrees. The coordinates derived from a GPS device are returned in a GCS named WGS84 (WKID: 4326).

For tiled layers in a global scene, any geographic coordinate systems are supported. In a local scene, WGS84 (WKID: 4326) and China Geodetic Coordinate System 2000 are supported. When you add data with these spatial references to a local scene, it will be converted to Plate Carrée (WKID: 32662) to reproject the data on a planar surface. Scene layers are reprojected to the spatial reference of the ArcGISMap.

Projected coordinate system

Projected coordinate systems (PCSs) are variously described as planar (two-dimensional), Cartesian, or "flat." Unlike a GCS, a PCS has constant lengths, angles, and areas across the two dimensions. PCSs use a geographic coordinate system projected onto a flat surface for display. There are various projections with different desirable characteristics. Some preserve accuracy in particular areas of the Earth, others are better at maintaining the shape of features, while others favor accurate area or distance measurements. Coordinates are identified by X, Y coordinates on a grid. Most basemaps from ArcGIS Online, Google, and OpenStreetMap use the same projected coordinate system named Web Mercator (Auxiliary Sphere) (WKID: 3857).

For tiled layers in a global scene, Web Mercator (Auxiliary Sphere) (WKID: 3857) is the only supported projected coordinate system. When you add data with this spatial reference to the level, it will be converted to WGS84 (WKID: 4326) to reproject the data on an ellipsoid. In a local scene, any projected coordinate systems are supported. Scene layers are reprojected to the spatial reference of the ArcGISMap.

Local coordinate system

Local coordinate systems (LCSs) are often unrelated to any other coordinate system. The origin and the X, Y coordinate units correspond to a local point of reference. Because the relationship of a local coordinate system to another coordinate system cannot be established easily, these are sometimes referred to as unknown coordinate systems. Local coordinate systems are not supported with ArcGIS Maps SDK. Data in a local coordinate system such as CAD data should be converted to a geographic coordinate system or a projected coordinate system.

Vertical coordinate system

Vertical coordinate systems (VCSs) are important when working with 3D data. A VCS defines vertical linear units of measure, the origin of Z values, and whether Z values are "positive up" (representing heights above a surface) or "positive down" (indicating that values are depths below a surface). There are two main types of VCS. Ellipsoidal systems measure Z values from a mathematically defined three-dimensional ellipsoidal surface. Most data collected via Global Navigation Satellite System receivers, for example, GPS, is in an ellipsoidal VCS. Gravity-based systems measure Z values from an analytical surface that represents the average sea level. Gravity-based VCSs are more commonly used to display and work with 3D data. A spatial reference may or may not have a VCS set. Any particular vertical coordinate system may be used with different horizontal coordinate systems.

Specifying the vertical coordinate system is optional. When the vertical coordinate system is ellipsoidal, it must share the same datum as the horizontal coordinate system. The datum name, the spheroid name, and all of the spheroid properties of the two coordinate systems must exactly match. You can specify it by WKID for Z values of a position and the unit depends on the spatial reference specification for local scenes. When it's not specified, the horizontal coordinate system will be used to determine the unit for Z values. For global scenes, the unit for Z values is in meters.

The following resources related to spatial references in ArcGIS Maps SDK for Unity are available on the Downloads page.

• Coordinate Systems and Transformation Tables
• Projection Engine Data

When you need to know about spatial references

When you use scene layers with different spatial references for viewing or analysis, the ArcGIS Maps SDK for Unity automatically reprojects geometries or requests data in the appropriate spatial reference from services where possible and appropriate. However, tile layers in the scene should be in the same spatial reference to be rendered. When you place a game engine object in your scene, it requires a spatial reference together with its position values to place the object accurately in the scene.

When you add data to the map

When you create a map, you can specify the spatial reference in the ArcGIS Map. When it's not specified, the spatial reference of the first layer you load is used as the spatial reference of the entire map; this is typically the basemap. When the ArcGIS Maps SDK for Unity renders a map, it draws all the data using the same spatial reference so that the data lines up properly. If a group of layers is the first layer loaded to a map, the map will use the spatial reference of the first layer in the group of layers.

As you add additional layers to your map, you may need to request those layers from the service in the same spatial reference your map uses. Whether or not you must request this depends on the type of layer you add. The following sections describe layer types as they relate to setting your map's spatial reference.

Basemap layer

Basemap layers can be composed of one or more layers. All the contained tiled layers in a basemap should be in the same spatial reference. See tiled layers on this page for more information.

Elevation layer

Elevation layers are LERC-encoded tile layers to create the surface and provide base heights for other layers in your scenes. It should be in the same spatial reference as other tiled layers. See tiled layers on this page for more information.

Scene Layers

Scene layers are optimized for displaying large amounts of 3D data in a scene. As it represents 3D data, the spatial reference is accounted for the Z values and its unit depends on it. The scene layer complies with the Indexed 3D Scene layer (I3S) format.

Tiled layers

Tiled layers are cached layers. At the time of caching, a spatial reference is used and is therefore predefined for the tiled layer. It's typically not possible to request tiled layers in a different spatial reference from the one defined in the service using that cache (unless the server supports doing this on the fly; most do not). If an ArcGIS tiled layer is added to a map with a different spatial reference from the tiled layer, it cannot be drawn.

When you convert geometries from one spatial reference to another

Geometry objects used for analysis (for example, determining spatial relationships, such as where polygons intersect) require that the spatial reference be known before the analysis is performed. Otherwise, the results may not be accurate. Likewise, it's meaningless to compare two geometries or determine their spatial relationship if they have different spatial references. To display geometry in a map layer, the geometry must have either the same spatial reference as the layer or be projected to the layer's spatial reference. To use two geometries together, they should have the same spatial reference.

When using the geometry engine to convert geometries from one spatial reference to another, the source and destination spatial references must be specified. For details, see the Geometry topic. An appropriate datum transformation is used by default. You can also specify the transformation you want to use. You can also convert strings containing coordinates formatted as latitude and longitude directly to points, and vice-versa. Other types of coordinates such as Universal Transverse Mercator (UTM) and United States National Grid (USNG) are also supported.

Spatial reference specifications

To define a spatial reference, you can use either a Well-Known ID (WKID) integer value or a text string definition referred to as Well-Known Text (WKT). WKIDs are defined by standards bodies or organizations, with each value representing a specific spatial reference. ArcGIS supports a variety of WKIDs, typically those defined by the European Petroleum Survey Group (EPSG) or Esri, as well as a few other commonly used IDs. You can optionally define a vertical coordinate system for a spatial reference, by using a second WKID. In contrast, WKT text describes all of the parameters of a spatial reference.

To see a list of supported WKIDs for geographic coordinate systems, projected coordinate systems, vertical coordinate systems, and transformations, download the Coordinate Systems and Transformation Tables from the Downloads page. For a list of WKIDs and their corresponding WKT definition strings, download the coordinate systems PDFs from the ArcGIS REST APIs documentation.

Linear, angular, and area units can also be defined by WKID or WKT, and are used by many spatial reference and geometry-related API members. These WKIDs are also included in Coordinate Systems and Transformation Tables.

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 Unity 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

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, similar 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 in ArcGIS Maps SDK for Unity 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 location(ProjectionEngineLocation), you must do so at app startup, before other calls that use the Projection Engine.

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 specific datasets are missing when using a transformation from a list returned by the transformation catalog, or when creating transformations from WKID or WKText.

You can identify such cases using the IsMissingProjectionEngineFiles method on the transformation step object (the ArcGISGeographicTransformationStep or ArcGISHorizontalVerticalTransformationStep type). Your app could go so far as informing the user about precisely which files are missing or even automatically downloading the missing files from a known location. 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 Unity, 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), 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 Unity also ensures that the default transformation is usable, that is, is not a grid-based transformation that needs grid files that are missing from the local file system. This means that if the best transformation is grid-based but the necessary files are not present, it will not be the best available transformation.

Customize default transformations

There may be cases where you want to specify your 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 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 Unity 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 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 ArcGISGeometryEngine 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 will be transforming geometries.

Choose a transformation from a list

From the transformation catalog, you can retrieve a list of transformations useable between two spatial references. The TransformationsBySuitability method on the ArcGISTransformationCatalog returns a list of transformations in descending order by suitability. With this, you could provide your app users with a workflow wherein they can 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 (ArcGISHorizontalVerticalTransformation) are returned; otherwise, geographic transformations (ArcGISGeographicTransformation) are 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 another data source. The Project method on the geometry engine (the ArcGISGeometryEngine 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 ArcGISGeographicTransformationStep, then adding one or more steps to a ArcGISGeographicTransformation. 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 ArcGISHorizontalVerticalTransformationStep, then adding 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 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 a 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 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 data files are found on the local file system.