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 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.

1. 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.
2. The map's spatial reference 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 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.
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 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.

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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
        // Toggle the wraparound setting for the map view.
        if (mapView.wrapAroundMode == WrapAroundMode.EnabledWhenSupported) {
            // If wraparound mode is currently enabled, disable it.
            mapView.wrapAroundMode = WrapAroundMode.Disabled
        } else {
            // If wraparound mode is currently disabled, enable it.
            mapView.wrapAroundMode = WrapAroundMode.EnabledWhenSupported
            // With the mode enabled, check if the map view can now provide wraparound behavior.
            if (!mapView.isWrapAroundEnabled) {
                // 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().

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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
        val currentViewpoint = mapView.getCurrentViewpoint(ViewpointType.BoundingGeometry)
        val currentViewpointGeometry = currentViewpoint?.targetGeometry ?: return
        var currentExtent: Envelope = currentViewpointGeometry.extent

        var normalizedViewpointGeometryOuterScope: Geometry? = null
        if (mapView.isWrapAroundEnabled) {
            val normalizedViewpointGeometry = GeometryEngine.normalizeCentralMeridian(currentViewpointGeometry)
                ?: return logErr("The normalizeCentralMeridian() method returned null.")

            currentExtent = normalizedViewpointGeometry.extent

        }