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 reference is important
To integrate spatial data together into a map or when performing analysis, map coordinates are used to locate things on the Earth's surface. 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. Mathematical transformations are used 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 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 and Google 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.
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 are 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 mean 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.
The following resources related to spatial references are available on the downloads page:
- Coordinate Systems and Transformations Tables
- Projection Engine Data (grid-based transformations and raster spatial reference data)
When you need to know about spatial references
When you use layers with different spatial references, where possible, geometries are automatically reprojected for viewing and data is requested in the appropriate spatial reference. For many use cases, you don't need to be concerned about spatial references. However, it's important to understand how spatial references are used when you:
- Add data to the map
- Edit data
- Perform analysis
- Convert geometries from one spatial reference to another
See the Work with spatial reference topic for more information.
A transformation is the calculation used to convert data from one spatial reference to another. For example, when a layer in a map uses a spatial reference that differs from the spatial reference used by the map itself, a datum transformation must be applied to ensure the data draws in the correct place. See the Datum transformation topic for more information on different types of transformations and how to work with them in your app.
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 necessary parameters of a spatial reference.
Coordinate Systems and Transformations Tables
To see a list of supported WKIDs and their WKT definitions for geographic coordinate systems, projected coordinate systems, vertical coordinate systems, and transformations, download the Coordinate Systems and Transformation Tables from the download area.
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.
Projection Engine data files
The Projection engine data download includes files needed to determine spatial reference information for some raster data and the support files used for grid-based transformations which more accurately project data in your app.
The contents of the Projection Engine data download includes:
- GDAL projection and supporting data files
- Projection Engine grid-based transformation data files
GDAL support files
ArcGIS Maps SDK for Kotlin uses the Geospatial Data Abstraction Library (GDAL) to support working with most raster data formats as well as OGC Web Feature Service (WFS) data. For some raster data, GDAL requires additional files containing coordinate system definitions in order to resolve the spatial reference described in the raster's metadata. The spatial reference is needed to support on-the-fly reprojection when the data is displayed in a map or used for analysis. These support files are in the gdaldata subfolder of the Projection Engine data download.
Projection Engine grid-based transformation data files
Datum transformations are used to convert data between different spatial references and can be either mathematically defined (equation-based transformations), or may rely on external supporting files with more precise information (grid-based transformations). By default, the API will use the best transformation available.
If more accurate results or a specific grid-based transformation are needed, the Projection Engine grid-based transformation files must be present. Attempting to use a grid-based 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.
Download and extract the relevant Projection Engine data zip file from the downloads page, and use TransformationCatalog.projectionEngineDirectory to specify the pedata folder. It will look for the grid-based transformation files located in the geographic and vertical sub-folders.
Check for Projection Engine grid-based transformation data files
If the supporting file for a grid-based transformation cannot be located on the local file system, that transformation cannot be used. This can happen if the Projection Engine directory is not set or specific datasets are missing when using a transformation created from a list returned by the transformation catalog or from a WKID or WKT.
You can identify such cases using the DataTransformation.isMissingProjectionEngineFiles() method on the transformation step object (the Geographic or Horizontal type). 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 from the transformation step object.
