Enable wraparound

The world is round. It does not end at the date line. However, most flat representations of the earth only extend to 180 east and west longitude. This makes it difficult to visualize areas that span across the date line, or routes that traverse the Pacific Ocean.

With wraparound support, it is possible to visualize a world map extending seamlessly beyond the date line. The eastern and western hemispheres wraparound each other to form a continuous map and give the impression that the map is endless. Panning a map becomes similar to spinning a globe.

Enable wraparound

To enable wraparound, invoke the enableWrapAround method on AGSMapView.



The following requirements must be satisfied before enabling wraparound:

  • The map's full envelope must cover the entire world.
  • The map's spatial reference must be 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, on the other hand, can be in any spatial reference because they are capable of reprojecting their data.
  • Dynamic layers must be based on map services from ArcGIS Server 10.0 or higher. This is because 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 any of these requirements are not satisfied and you try to enable wraparound, the wrapAroundStatus property on AGSMapView indicates wraparound is not supported.

if (mapView.wrapAroundStatus() == .Supported){

Normalize geometries

To better understand wraparound, it is helpful to visualize a map as being composed of frames. The portion of a map between -180 longitude and +180 longitude is frame 0. This frame is regularly visible even when wraparound is not enabled. Adjacent to this frame on the east is frame 1, which extends hypothetically between +180 and +540 longitude. Adjacent to frame 0 on the west is frame -1, which extends hypothetically between -180 and -540 longitude.

Depending on the frame being displayed, longitude values reported by a map may be real (within -180 and +180) or hypothetical (extend beyond -180 or +180). Here are some examples of geometries that may contain hypothetical coordinates:

  • Map's envelope
  • Touch coordinates reported by a map's delegates
  • Geometries digitized by a sketch layer

When geometries contain hypothetical coordinates, normalize them before using them to perform spatial queries or store them in a geodatabase. It is difficult to programmatically check at run-time if geometries contain hypothetical values and need to be normalized or not. It is safer to always normalize geometries when wraparound is enabled.

You can normalize geometries using the normalizeCentralMeridianOfGeometry: method on AGSGeometryEngine.

let poly = AGSpolygon ...
let geometryEngine = AGSGeometryEngine.defaultGeometryEngine()

if (mapView.wrapAroundStatus() == .Enabled){
 let newPoly = geometryEngine.normalizeCentralMeridianOfGeometry(poly)