Enable wrap around
In this topic
The world is round. It does not end at the dateline. However, most flat representations of the earth only extend up to 180 east and west longitude. This makes it difficult to visualize areas that span across the dateline, or routes that traverse the Pacific Ocean. It is possible to visualize a world map extending seamlessly beyond the dateline. By enabling wraparound on a map, the eastern and western hemispheres wrap around each other forming a continuous map, giving the impression that the map is endless. Panning a map becomes similar to spinning a globe.
// enable wrap around
The following requirements must be satisfied before enabling wrap around:
- The map's full envelope must cover the 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 wrap around.
To better understand wraparound, it is helpful to visualize a map as being composed of frames. The portion of a map visible when wrap-around 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° and +180º 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 the international dateline, 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.
Longitude values (X coordinates) returned from map methods may be real, within the range of -180º and +180º (when frame 0 is displayed); or they may be hypothetical, less than -180º or greater than +180º (if a different map frame is displayed). Here are some examples of geometries that may contain hypothetical coordinates if wraparound is enabled:
- Map extent, returned from
- Map coordinates, returned from
When geometries contain hypothetical coordinates, normalize them before using them to perform spatial queries, passing them to placefinding or geocoding services, or storing 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
normalizeCentralMeridian method on the
Geometry normalized = GeometryEngine.normalizeCentralMeridian(mMapView.getExtent(), mMapView.getSpatialReference());