Wraparound maps

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 Java app can still wraparound the edges to provide a continuous display when panning east or west.

A world map with wraparound mode enabled for continuous east-west panning

Enable or disable wraparound

By default, a attempts to wrap your 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.

  1. The map's covers the world. It's common for the full of a wraparound map to cover the world, but it is not required.
  2. The map's supports panning horizontally over the antimeridian, indicated by a true value for the SpatialReference.isPannable() property. Pannable spatial references include WGS 84 (WKID=4326) and Web Mercator (WKID=102113, 102100, or 3857). All tiled in the map must also use one of these spatial references. , however, can be in any spatial reference because they are capable of reprojecting their data.
  3. 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 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. Wraparound behavior is disabled if it is currently enabled. If it is disabled, an attempt is made to enable wraparound if it is supported.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
// Toggle the wraparound setting for the map view.
if (mapView.getWrapAroundMode() == WrapAroundMode.ENABLE_WHEN_SUPPORTED) {
    //Disable wraparound if currently enabled.
    mapView.setWrapAroundMode(WrapAroundMode.DISABLED);

} else {
    // If it's disabled, attempt  to enable wraparound mode.
    mapView.setWrapAroundMode(WrapAroundMode.ENABLE_WHEN_SUPPORTED);

    // Check if wraparound is now enabled.
    if (!mapView.isWrapAroundEnabled()) {
        // If wraparound is not now enabled, it is not supported.
        new Alert(Alert.AlertType.ERROR, "Unable to enable wrap around");
    }
}

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 , frame 0 has X 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.

Example of a 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 geometries that may contain hypothetical 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 to contain only real coordinate values is called normalization. Geometries that contain hypothetical values are not acceptable as inputs to spatial queries, , , , or for storage in a . 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().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
// If wraparound is enabled, normalize the geometry (in case all or part is outside of frame 0).
if (mapView.isWrapAroundEnabled()) {
    extent = GeometryEngine.normalizeCentralMeridian(mapView.getVisibleArea());
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close