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 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 Unreal Engine 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 Unreal Engine uses mathematical transformations to reproject coordinates from one coordinate system to another. A spatial reference often provides all the information needed for reprojection.
Coordinate systems and projections
Spatial 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 and projected.
Geographic coordinate systems
Geographic coordinate systems (GCS) use three-dimensional ellipsoidal surfaces to define locations on the surface of the Earth. Typically, GCS coordinates measure latitude and longitude as angles from the Earth's equatorial plane and prime meridian. For example, the coordinates used for everyday navigation in GPS devices are defined by the GCS WGS84 (WKID: 4326).
- To view spatial data in a global scene, any supported geographic coordinate system can be used.
- Scene layers are reprojected and viewed in the spatial reference of the ArcGIS Map.
- It is recommended that tiled layers be in the same spatial reference as the ArcGIS Map.
- In a local scene, only WGS84 (WKID: 4326) and China Geodetic Coordinate System 2000 can be used; in this case, spatial data is reprojected and viewed in Plate Carrée (WKID: 32662).
Projected coordinate systems
Projected coordinate systems (PCS) can be planar (two-dimensional), Cartesian, or "flat." Unlike a GCS, a PCS has constant lengths, angles, and areas across the two dimensions. A PCS is based on geographic coordinate systems projected onto a flat surface for display. There are various PCS 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. Map coordinates are identified by X, Y coordinates on a grid. Most basemaps from ArcGIS Online, Google, and OpenStreetMap use the same PCS: Web Mercator (Auxiliary Sphere) (WKID: 3857).
- To view spatial data in a global scene, Web Mercator (Auxiliary Sphere) (WKID: 3857) is the only supported projected coordinate system. When adding data in this spatial reference, it is reprojected to WGS84 (WKID: 4326) for viewing on the WGS84 ellipsoid.
- In a local scene, any supported projected coordinate system can be used.
- Scene layers are reprojected and viewed in the spatial reference of the ArcGIS Map.
- It is recommended that tiled layers be in the same spatial reference as the ArcGIS Map.
Vertical coordinate systems
Vertical coordinate systems (VCS) 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" (representing depths below a surface). There are two main types of VCS: ellipsoidal and gravity-related.
Ellipsoidal systems measure height values from a mathematically defined, three-dimensional ellipsoidal surface. Most data collected by Global Navigation Satellite System (GNSS) receivers, (such as GPS), use ellipsoidal heights. Gravity-based systems measure height values from an analytical surface that represents the average sea level. Gravity-based VCS are more commonly used to display and work with 3D data. A spatial reference may or may not have a VCS set. Any VCS may be used with different horizontal coordinate systems provided that the datums are compatible.
Specifying the vertical coordinate system is optional. When the VCS is ellipsoidal, it must share the same datum as the horizontal coordinate system. The datum name, the spheroid name, and the spheroid properties of the two coordinate systems must match exactly. When the VCS is 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. See Datum transformations when there is a difference in the datum that underlies two spatial references.
The following resources related to spatial references in ArcGIS Maps SDK for Unreal Engine 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 Unreal Engine 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 of the ArcGIS Map to be rendered. When you place a game engine object in your scene, it requires a spatial reference combined with its position values to place the object accurately in the scene.
When you add data to the map
The spatial reference of the ArcGIS Map can be specified when creating a map. When it is 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 Unreal Engine renders a map, it draws all the data using the same spatial reference for accuracy. 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.
Multiple layers may have different vertical coordinate systems and the data may not align correctly unless a datum transformation is applied. Layers that do not have a vertical coordinate system are assumed to have a gravity-related vertical coordinate system. Set the ArcGIS Map vertical coordinate system to EGM96 or WGS84 for ArcGIS Maps SDK for Unreal Engine to apply the datum transformation. See Datum transformations when there is a difference in the datum that underlies two spatial references.
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 layers
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 layers
Elevation layers are LERC-encoded tile layers that create the surface and provide base heights for other layers in your scenes. An elevation layer 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 these represent 3D data, the spatial reference determines the height values and their units. The scene layer complies with the Indexed 3D Scene layer (I3S) format.
Tiled layers
Tiled layers are cached layers. At the time of caching, the spatial reference in use is by default 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.