Spatial references are important, and for someone new to GIS, they can appear complicated. Spatial references ensure that spatial data for different layers or sources can be integrated for accurate viewing or analysis. When you combine layers with different spatial references for viewing or analysis, ArcGIS Runtime SDKs attempt to handle this disparity for you by setting defaults and requesting data in the appropriate spatial reference from services where possible. But sometimes, you'll need to know about spatial references to get things working. Whether it's to align data together, make your map look right, improve accuracy, or just make a layer show up, understanding the basics of spatial references can be critical.
Spatial references can be referred to by a well-known ID (WKID). Some common WKIDs are mentioned in the text below; for a more complete description, see Spatial reference and transformation specifications in this topic.
Why spatial references are important
To integrate spatial data together into a map or during analysis, ArcGIS Runtime must know where things are located on the earth's surface. To do this it uses coordinates. Coordinates are associated with 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 be in different units (degrees minutes seconds, decimal degrees or meters) or they can be based on different types of models. To move coordinates from one coordinate system to another, mathematical transformations are used. A spatial reference provides all of this information, along with parameters such as the desired level of precision, in a way so that spatial data can be viewed and analyzed together.
For more detailed information on these topics, see What are map projections? in the ArcGIS help.
A note on setting spatial references
In the API, a spatial reference class represents a coordinate system. It contains a coordinate system and helper methods to access and use it. The spatial reference class is associated with several other API classes that need a coordinate system to function. For example, layers have an associated spatial reference. Some task parameters, such as those for the Query task and the Local Routing task, are spatial reference objects.
Coordinate systems and projections
The models used for coordinate systems are split into two main categories, geographic and projected:
- Geographic coordinate systems (GCSs) use a three-dimensional spherical (or 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 planar (two-dimensional), Cartesian, or "flat." Unlike a GCS, a projected coordinate system has constant lengths, angles, and areas across the two dimensions. PCSs use a geographic coordinate system and then distort data so it can be represented on a flat surface for use in a printed map or on a screen. Coordinates are identified by x,y coordinates on a grid. ArcGIS Online, Google, and OpenStreetMap basemaps use the same projected coordinate system named Web Mercator Auxiliary Sphere (WKID=3857).
You may come across a third coordinate system, a local coordinate system, which is 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
Add layers to the MapView
When ArcGIS Runtime renders a map, it needs to draw all the data in the same spatial reference so that the data lines up. When you create a MapView, the spatial reference of the first layer you add is used as the spatial reference of the entire map; this is typically the basemap.
When you add additional layers to your map (MapView), you may need to request them in the same spatial reference your MapView 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.
Graphic layers don't support on-the-fly reprojection of data; ArcGIS Runtime renders these layers client-side. On-the-fly reprojection of graphics layers could require intensive processing that would slow down the MapView rendering time. When you add a graphics layer to your MapView, you must ensure its spatial reference is the same as that defined on the MapView (typically set by the basemap layer). You also need to ensure that individual graphics added to your graphics layer have coordinates in the matching spatial reference; otherwise, the graphics may not show up on the map.
Feature layers from feature services
When using a feature service table backed by an ArcGIS for Server feature service, the server supports reprojection. When a Service Feature Table is to be added to a MapView, be sure to set its spatial reference based on the MapView's spatial reference before you initialize the table. This will ensure the data is requested from the server in the correct spatial reference. When using the ArcGIS feature layer, when this is added to the MapView, ArcGIS Runtime automatically determines the correct spatial reference and requests data from the feature service accordingly.
Feature layers from geodatabase feature tables
Your tables in the geodatabase must 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 not supported. If you're using the desktop workflow, 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 SyncTaskParameters before you generate the geodatabase. For details on the desktop and server workflows, see Offline patterns in this guide's "Create an offline map" topic.
FeatureLayers from shapefiles FeatureTables and GeoPackagesFeatureTables
Your tables in the geodatabase need to be in the same spatial references as the map you are adding them to; on-the-fly reprojection of data from these tables is not supported.
If these are ArcGIS for Server map services, then the server supports reprojection on the fly. When you add an ArcGISDynamicMapService to the MapView, ArcGIS Runtime automatically asks for the map image in the correct spatial reference for you (based on the MapView's spatial reference). WMS map services, a type of dynamic map service, support a limited set of spatial references, so you should set the spatial reference on a WMSLayer before you add it to the MapView.
TiledLayers are precached layers. At the time of caching, a spatial reference is used and is therefore predefined. It's typically not possible to request TiledLayers in a different spatial reference from that defined in the service (unless the server supports doing this on the fly; most do not). If an ArcGIS Tiled Layer is added to a MapView in a different spatial reference, it cannot be drawn as a tiled layer.
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. You can use the geometry engine to ensure coordinates are converted correctly before they're added to a layer. For more information about the geometry engine, see Geometry operations.
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 or correct. Likewise, it's meaningless to compare two geometry objects 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 objects together, if those objects each have a spatial reference, they should have the same spatial reference.
For more information on analysis through geometry operations, see Geometry operations.
Convert from one spatial reference to another
When using the geometry engine to convert from one spatial reference to another, the in and out spatial references must be specified. You can also specify the transformation you want to use. For details, see Projecting to different spatial references in "Geometry operations."
Spatial reference and transformation specifications
To define a spatial reference, you can use either a WKID (sometimes also known as spatial reference ID or SRID) or a full-text definition referred to as well-known text (WKT). WKIDs are defined by standards bodies or organizations. 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. WKTs are full-text definitions of all of the parameters that specify a spatial reference (as mentioned above). To learn which WKIDs are supported and look at their WKT definitions, see the following: