Spatial references

A spatial reference is a characteristic of a geometry that identifies how its coordinates relate to real-world space. It is important for ensuring 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.

Why spatial references are important

To integrate spatial data together into a map or when performing analysis, ArcGIS Runtime 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 (degrees minutes seconds, decimal degrees, or meters) and they can be based on different types of models. ArcGIS Runtime 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

Coordinate systems are split into categories: geographic, projected, and local:

  • 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).
  • 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).
  • Local coordinate systems 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.

When you need to know about spatial references

When you use layers with different spatial references for viewing or analysis, ArcGIS Runtime automatically reprojects geometries or requesting data in the appropriate spatial reference from services where possible and appropriate. Nevertheless, occasionally you'll need to know about how spatial references are used.

Add layers to the map

When you create a map, the spatial reference of the first layer you add is used as the spatial reference used by the entire map; this is typically the basemap. When ArcGIS Runtime renders a map, it draws all the data using the same spatial reference so that the data lines up properly.

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 is using. Whether or not you must request this depends on what type of layer you’re adding. The following sections describe layer types as they relate to setting your map’s spatial reference.

Graphics overlays

Graphics overlays support on-the-fly reprojection of graphics. On-the-fly reprojection requires extra processing that could slow down the map view rendering time. When you add a graphic to a graphics overlay, it is best if the geometry in the graphic has the same spatial reference as the map. You can explicitly convert geometries to the required spatial reference.

Feature layers from feature services

When using a feature service table created from a feature service from ArcGIS Online or ArcGIS Enterprise, the service supports reprojection. When initialized, the table and its associated feature layer will automatically be set to the same spatial reference as the map. This ensures the data is requested from the service in the correct coordinates, without the need to explicitly define the spatial reference for the feature table. ArcGIS Runtime determines the correct spatial reference and requests data from the feature service accordingly.

Feature layers from geodatabase feature tables

Your tables in the geodatabase do not need be in the same spatial references as the map you are adding them to, because on-the-fly reprojection of data from these tables is supported. However reprojection comes with a cost in drawing performance, and avoiding reprojection can help maximize performance. To control the spatial reference of your tables, ensure the ArcMap map frame is using the desired spatial reference before you run the create runtime content tool. If you're using the services workflow, set the desired spatial reference in the parameters used to generate the geodatabase. For details on the desktop and services workflows, see the guide topic Create an offline map.

Dynamic map service layers

If these are ArcGIS Online or ArcGIS Enterprise map services, then the server supports reprojection on the fly. When you add an ArcGIS dynamic map service layer to the map, ArcGIS Runtime automatically asks for the map image in the correct spatial reference for you (based on the map's spatial reference).

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.

Raster layers

Raster layers support on-the-fly datum transformation and reprojection. For more information on using raster layers in your app, see Add raster data.

Edit data

When creating new features from coordinates, the coordinate values must match the spatial reference for the layer; otherwise, the features will not show up in the correct location on the map.

Perform analysis

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, 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 a 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.

Convert geometries from one spatial reference to another

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 Projection, topological, and other operations in the Geometries 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. In contrast, WKT text describes of all of the parameters of a spatial reference. To see a list of supported WKIDs and their WKT definitions for geographic coordinate systems, projected coordinate systems, and transformations, see Coordinate systems and transformations.

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

Geographic transformations

Geographic transformations are functions used to transform coordinates between spatial references that have different datums. The 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. Using the most suitable transformation ensures the best possible accuracy for the reprojection. Different transformations are suitable for different geographical areas.

Esri's Projection Engine is used for geographic transformations and supports many predefined geographic transformations. There is not a defined transformation from every spatial reference to every other—such a collection would be very large. Therefore, each geographic transformation is usually 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. The list of supported WKIDs (in PDF format at Geographic transformations) includes a transformation from every supported datum to the datum named World Geodetic System 1984 (WGS84). 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 datum 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.

Datum transformations can be mathematically defined by specific equations (equation-based transformations), or may rely on external supporting files (grid-based transformations). Exactly how coordinates should be transformed is defined by agencies such as the US National Geodetic Survey, and then identified by a WKID integer number and WKT text string definition, similarly to how spatial references are identified.

As a developer, you can rely on ArcGIS Runtime to choose a default geographic transformation for you, resulting in accurate coordinate reprojection. Or in some situations, you may use a geographic transformation of your own choosing. You may specify a geographic transformation each time you use the geometry engine (the GeometryEngine class) to project a geometry, or you can override the default geographic transformation used by your app through a JSON configuration file. You can even request a list of suitable transformations from the transformation catalog (the TransformationCatalog class) for a given pair of spatial references and optionally a given geographic area, and choose one of those. If you have even more specialized needs, you can create a custom transformation using WKT.

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.

Note:
These Projection Engine data files are available for download from the downloads page on developers.arcgis.com (requires you to log in).

The data files should reside in a location specified in the transformation catalog's Projection Engine location. There is no default location set by this API. If you set the Projection Engine location (call the setProjectionEngineLocation method) , you must do so early in your app before using other API calls that use the Projection Engine.

The code below sets the path to the directory containing Projection Engine files on the local file system, and checks for failure. An exception may be thrown if the path does not exist.

// Get the expected location of the projection engine files.
File peDataDirectory = new File(rootDirectory, "/ArcGIS/samples/PEData");

try {
  TransformationCatalog.setProjectionEngineDirectory(peDataDirectory.getAbsolutePath());
  showPEDirectorySuccessMessage();

} catch (ArcGISRuntimeException agsEx) {
  // If there was an error in setting the projection engine directory, the location may not exist, or if
  // permissions have not been correctly set, the location cannot be accessed.  Equation-based transformations can still be used, but grid-based transformations will not
  // be usable.
  showPEDirectoryFailureMessage(agsEx);
}

Use default transformations

A common use case is to transform a geometry, creating a new geometry that uses the same spatial reference as the map. The geometry engine's project method internally uses the best overall geographic transformation available by default without you needing to specify one. Using the transformation catalog you can find out which geographic transformation is used by default when projecting between any two spatial references.

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 a null pointer.

Use the getTransformation method to find which transformation is used by default when projecting data between two SpatialReferences.

DatumTransformation defaultTransform = TransformationCatalog.getTransformation(inputSr, outputSr);

Customize default transformations

There may be cases where you want to specify your own default geographic transformations. This would happen when the defaults chosen by ArcGIS Runtime are not suitable to your needs but you do not want to write code to specify the geographic transformation every time you need to use a one. To change any defaults, create a JSON file named gtdefaults_overrides.json and place it in the location returned from the transformation catalog method projectionEngineLocation.

Note:

You must set projectionEngineLocation early in your app before using other API calls that use the Projection Engine. There is no default location set by this API.

Note:

Changing the JSON file will have no effect on running apps. To use this file in your app, you must change it before running your app.

The file's content looks like the following:

{ "geogtran" : [
   [   3819,   3906,   3817,    0,   3962,    1 ],
   [   3819,   4075,   3817,    0,   4077,    1 ],
   [   3819,   4156,   3817,    0,  15965,    1 ],
   [   3819,   4178,   3817,    0,  15996,    1 ],
   [   3819,   4179,   3817,    0,  15995,    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" datum.
  2. The WKID of the "to" datum.
  3. The WKID of the first datum transformation.
  4. Whether to use the first datum transformation as-is (0) or use its inverse (1).
  5. The WKID of the second datum transformations WKID (or 0 if this is a single-step geographic transformation).
  6. Whether to use the second datum transformation as-is (0) or use its inverse (1). (0 if this is a single-step geographic transformation).

ArcGIS Runtime checks whether a geographic transformation defined in this file is useable before attempting to use it. If it is not, the geographic transformation for that datum pair uses the previous default.

Choose a transformation from a list

From the transformation catalog, you can retrieve a list of geographic transformations useable between two spatial references. The getTransformationsBySuitability method returns a list of geographic 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 code below gets the 'from' and 'to' SpatialReferences to retrieve a list of transformations, optionally passing in an Envelope.

// Get the input and output spatial references required.
SpatialReference toSr = mArcGISMap.getSpatialReference();
SpatialReference fromSr = mOriginalGeometry.getSpatialReference();

// Get the list of transformations applicable to the input and output spatial references. Check if list
// should account for the map's extent when ordering the list of transformations by suitability.
List<DatumTransformation> transformationsBySuitability;
if (mUseExtentForSuitability) {
  transformationsBySuitability = TransformationCatalog.getTransformationsBySuitability(fromSr, toSr,
      mMapView.getVisibleArea().getExtent());

} else {
  transformationsBySuitability = TransformationCatalog.getTransformationsBySuitability(fromSr, toSr);
}

// Update user interface with list of transformations to show to user
updateTransformsList(transformationsBySuitability);

The list returned from getTransformationsBySuitability may include grid-based transformations whose supporting files are not on the local file system. You can identify these cases using the isMissingProjectionEngineFiles method on the geographic transformation step object (the GeographicTransformationStep class). Your app could go so far as informing the user about precisely which files are missing, or even automatically download the missing files from a known location. Retrieve the list of required files using the getProjectionEngineFilenames method of the geographic transformation step object.

Note:
See a sample app Transforms By Suitability that demonstrates this workflow.

Consider the work area extent

Your work area may be small and located where the best geographic 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 geographic transformation for your specific work area. Use the overloads of the transformation catalog's getTransformation and getTransformationsBySuitability methods to pass in the extent for which you'll be transforming geometries, as shown in the previous code..

Create a custom transformation

Some users adjust the components of a geographic 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 geographic transformation object by passing in a text string containing your custom transformation expressed in WKT format. The resulting geographic transformation will have a WKID of zero. Before using a custom transformation that requires Projection Engine files, make sure that those files are present and the Projection Engine location has been set.

The code below sets the path to the directory containing Projection Engine files on the local file system, and checks for failure. An exception may be thrown if the path does not exist.

// Define a well-known text string containing the definition of the transformation
String WKT = "GEOGTRAN[\"Custom_Lisbon_To_Lisbon\"," +
    "GEOGCS[\"GCS_Lisbon_Lisbon\",DATUM[\"D_Lisbon\",SPHEROID[\"International_1924\",6378388.0,297.0]],PRIMEM[\"Lisbon\",-9.131906111111112],UNIT[\"Degree\",0.0174532925199433]]," +
    "GEOGCS[\"GCS_Lisbon\",DATUM[\"D_Lisbon\",SPHEROID[\"International_1924\",6378388.0,297.0]],PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]]," +
    "METHOD[\"Longitude_Rotation\"]]";
GeographicTransformationStep step = GeographicTransformationStep.create(WKT);
GeographicTransformation customTransformation = GeographicTransformation.create(step);

Related topics