One of the difficulties with displaying a round earth in two dimensions is that, unlike a 3D representation that provides a continuous surface, a 2D representation must have a start and an end. While the earth must be divided along a line of longitude to "flatten" it for display in two dimensions (usually at 180º east/west longitude), a map in your ArcGIS Maps SDK for Kotlin app can still wraparound the edges to provide a continuous display when panning east or west.
Enable or disable wraparound
By default, a map view attempts to wrap your map for a continuous experience as the user pans 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 all the following requirements are met.
- The map's spatial reference covers the world. It's common for the full extent of a wraparound map to cover the world, but it is not required.
- The map's spatial reference supports panning horizontally over the antimeridian, indicated by a
truevalue for theSpatialReference.isPannableproperty. Pannable spatial references include WGS 84 (WKID=4326) and Web Mercator (WKID=102113, 102100, or 3857). All tiled layers in the map must also use 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 any of these requirements are not met, attempting to enable wraparound will fail silently (without alerting you through an error message).
The following example toggles the current wraparound mode for the map view. If the mode is currently enabled, it is changed to disabled. If it is currently disabled, it is changed to enabled: the map view will now provide wraparound behavior, provided that the map being displayed supports wraparound. See Enable or disable wraparound for the requirements a map must meet to support wraparound.
// Toggle the wraparound setting for the map view.
if (wrapAroundMode == WrapAroundMode.EnabledWhenSupported) {
// If wraparound mode is currently enabled, disable it.
wrapAroundMode = WrapAroundMode.Disabled
} else {
// If wraparound mode is currently disabled, enable it.
wrapAroundMode = WrapAroundMode.EnabledWhenSupported
// With the mode enabled, check if the map view can now provide wraparound behavior.
if (mapViewProxy.isWrapAroundEnabled == false) {
// If the map view still cannot provide wraparound behavior,
// then the map being displayed doesn't support wraparound.
logInfo("mapView.isWrapAroundEnabled == false. Could not enable wraparound.")
}
}
Coordinates in wraparound mode
To better understand map navigation with wraparound, visualize a map as being composed of frames. The initial full extent of a wraparound-enabled map is frame 0. Assuming the map is in 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 pan the map eastwards until you pass 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 geometries that may contain hypothetical coordinates if wraparound is enabled:
- The map's bounding geometry or center point, returned as properties of the
Viewpoint - Point locations on the map, converted from screen coordinates to map coordinates
- Geometries drawn on the display by the user (using
GeometryEditor, for example)
Normalize geometries
The process of converting a geometry to contain only real coordinate values is called normalization. Geometries that contain hypothetical values are not acceptable as inputs to spatial queries, projection, geocoding services, routing services, or for storage in a geodatabase. Rather than trying to determine if a complex shape contains hypothetical coordinate values, it's best practice to always normalize geometry returned from the map when wraparound is enabled.
You can normalize geometries using GeometryEngine.normalizeCentralMeridian().
val currentViewpointGeometry = viewpoint.targetGeometry
var currentExtent: Envelope = currentViewpointGeometry.extent
val normalizedViewpointGeometry: Geometry = if (mapViewProxy.isWrapAroundEnabled == true) {
GeometryEngine.normalizeCentralMeridian(currentViewpointGeometry)
?: return logErr("The normalizeCentralMeridian() method returned null.")
} else {
return
}
currentExtent = normalizedViewpointGeometry.extent