A globe provides a better representation of the earth than a flat map does. In addition to more accurately displaying the shape of the earth, a globe provides seamless interaction with the features it displays. When spinning a globe, for example, it does not stop when it reaches a specific location (longitude). While a flat map has to divide the earth along a line of longitude (usually at 180º east/west), there's no reason why a map displayed on a computer screen can't wraparound to provide a continuous display of features as you pan east or west.
You may hear several different terms to describe the longitude at 180º east/west. While the following terms are not completely analogous, they are often used to refer to this line of longitude: Dateline, International Dateline, and Antimeridian.
Enable or disable wraparound
By default, a map view attempts to wrap your map for a continuous experience as the user pans the map east and west. To disable wraparound behavior for a map view (or to re-enable it), you can set the wraparound mode to the appropriate value. Wraparound can only be applied to a map view if the following requirements are met.
- The map's full extent covers the world.
- The map's spatial reference is WGS 84 (WKID=4326) or Web Mercator (WKID=102113, 102100, or 3857). This means that all tiled layers in the map must belong to one of these spatial references. Dynamic layers, however, can be in any spatial reference because they are capable of reprojecting their data.
- Dynamic layers in the map are based on services from ArcGIS Server 10.0 or higher. Earlier versions of the REST API do not support well-known text (WKT) values for spatial reference, which is required for making dynamic map services support wraparound.
If these requirements are not met, attempting to enable wraparound will fail silently (without raising an error, in other words).
The following example disables wraparound behavior if it is enabled and attempts to enable wraparound if it is not enabled.
mapView->setWrapAroundMode(clicked ? WrapAroundMode::EnabledWhenSupported : WrapAroundMode::Disabled);
To better understand wraparound, it is helpful to visualize a map as being composed of frames. The portion of a map visible when wraparound is not enabled is frame 0. Taking an example of a map with the WGS 84 coordinate system, frame 0 has X coordinates between -180° (west) and +180º (east) longitude.
Adjacent to this frame to the east is frame 1, which extends hypothetically between +180º and +540º longitude. If you have panned across the map eastwards until you have passed 180º, you will be viewing frame 1. Similarly, adjacent to frame 0 to the west is frame -1, which extends hypothetically between -180º and -540º longitude. The series of frames continues infinitely in both directions.
Longitude values (X coordinates) returned from a map may be real: in the range of -180º and +180º (within frame 0 in other words) or they may be hypothetical: less than -180º or greater than +180º (outside of frame 0). Here are some examples of geometries that may contain hypothetical coordinates if wraparound is enabled:
- Map extent, returned from Map::initialViewpoint().
- Map locations, returned from MapView::screenToLocation().
The process of converting a geometry so that it contains only real coordinate values is called normalization. Geometries that contain hypothetical values are not acceptable as inputs to spatial queries, projection, geocoding services, or routing services or for storage in a geodatabase. Because it may be difficult to determine if a complex shape contains hypothetical coordinate values, it's usually more efficient to simply normalize all geometry from the map when wraparound is enabled.
You can normalize geometries using normalizeCentralMeridian on the AGSGeometryEngine class.
Geometry normalizedEnvelope = GeometryEngine::normalizeCentralMeridian(envelope);
The normalized geometry of a map extent that crosses the 180th meridian is a polygon consisting of two rings (split at that meridian).