ArcGIS Runtime SDK for macOS

Wraparound maps

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.

World map showing 180 degrees east and west and the International Dateline
Note:

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.

// toggle the wraparound mode for the map view
 if (self.mapView.wrapAroundMode == AGSWrapAroundMode.enabledWhenSupported) {
    //disable wraparound
    self.mapView.wrapAroundMode = AGSWrapAroundMode.disabled
}
else {
    // enable wraparound
    self.mapView.wrapAroundMode = AGSWrapAroundMode.enabledWhenSupported
         // check it is enabled
    if (!self.mapView.isWrapAroundEnabled) {
                 // ... wraparound is not supported
        print("Unable to enable wrap around")
    }
}

Normalize geometries

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.

Wraparound map as a series of frames

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 AGSMapView's currentViewpointWithType method.
  • Map locations, returned from AGSMapView's screenToLocation method.
  • Geometries digitized by a sketch layer

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 normalizeCentralMeridianOfGeometry on the AGSGeometryEngine class.

// if wraparound is enabled, normalize the geometry (in case all or part is outside of frame 0)
if (mapView.isWrapAroundEnabled) {
    geometry = AGSGeometryEngine.normalizeCentralMeridian(of: geometry!)
}

The normalized geometry of a map extent that crosses the 180th meridian is a polygon consisting of two rings (split at that meridian).

Normalized map extent that crosses 180 degrees east/west