0
# Interactive Maps
1

2
Comprehensive interactive mapping functionality with multiple backend support. Leafmap automatically selects the appropriate backend based on the runtime environment and provides a consistent API across all backends.
3

4
## Capabilities
5

6
### Map Creation and Configuration
7

8
Create interactive maps with customizable center, zoom, and basemap settings. The Map class provides the foundation for all interactive mapping functionality.
9

10
```python { .api }
11
class Map:
12
    def __init__(self, center=[20, 0], zoom=2, basemap='HYBRID', **kwargs):
13
        """
14
        Create an interactive map.
15
        
16
        Args:
17
            center (list): Map center as [latitude, longitude]
18
            zoom (int): Initial zoom level (1-20)
19
            basemap (str): Base map provider name
20
            **kwargs: Backend-specific options
21
        """
22
    
23
    def add_basemap(self, basemap='HYBRID', show=True, **kwargs):
24
        """
25
        Add a basemap to the map.
26
        
27
        Args:
28
            basemap (str): Basemap provider name or custom definition
29
            show (bool): Whether to show the basemap immediately
30
            **kwargs: Basemap-specific options
31
        """
32
    
33
    def add_layer_control(self, position='topright', **kwargs):
34
        """
35
        Add a layer control widget to toggle layers.
36
        
37
        Args:
38
            position (str): Control position ('topright', 'topleft', 'bottomright', 'bottomleft')
39
            **kwargs: Control-specific options
40
        """
41
    
42
    def add_fullscreen_control(self, **kwargs):
43
        """
44
        Add a fullscreen control button.
45
        
46
        Args:
47
            **kwargs: Control-specific options
48
        """
49
    
50
    def set_center(self, lon, lat, zoom=None):
51
        """
52
        Center map at specific coordinates.
53
        
54
        Args:
55
            lon (float): Longitude coordinate
56
            lat (float): Latitude coordinate  
57
            zoom (int): Optional zoom level
58
        """
59
    
60
    def zoom_to_bounds(self, bounds):
61
        """
62
        Zoom map to fit bounding box.
63
        
64
        Args:
65
            bounds (list): Bounding box [minx, miny, maxx, maxy]
66
        """
67
    
68
    def find_layer(self, name):
69
        """
70
        Find layer by name.
71
        
72
        Args:
73
            name (str): Layer name to search for
74
            
75
        Returns:
76
            Layer object or None if not found
77
        """
78
    
79
    def get_layer_names(self):
80
        """
81
        Get list of all layer names.
82
        
83
        Returns:
84
            list: Layer names
85
        """
86
```
87

88
### Layer Management
89

90
Add and manage various layer types including tiles, WMS, WMTS, vector tiles, and PMTiles with comprehensive styling and interaction options.
91

92
```python { .api }
93
def add_layer(self, layer, **kwargs):
94
    """
95
    Add a generic layer to the map.
96
    
97
    Args:
98
        layer: Layer object (backend-specific)
99
        **kwargs: Layer-specific options
100
    """
101

102
def add_tile_layer(self, url, name='Untitled', attribution='', **kwargs):
103
    """
104
    Add an XYZ tile layer.
105
    
106
    Args:
107
        url (str): Tile URL template with {x}, {y}, {z} placeholders
108
        name (str): Layer name for display
109
        attribution (str): Attribution text
110
        **kwargs: Tile layer options (opacity, etc.)
111
    """
112

113
def add_wms_layer(self, url, layers, name='Untitled', **kwargs):
114
    """
115
    Add a WMS layer.
116
    
117
    Args:
118
        url (str): WMS service URL
119
        layers (str): Comma-separated layer names
120
        name (str): Layer name for display
121
        **kwargs: WMS-specific options (format, transparent, etc.)
122
    """
123

124
def add_wmts_layer(self, url, layer, **kwargs):
125
    """
126
    Add a WMTS layer.
127
    
128
    Args:
129
        url (str): WMTS service URL
130
        layer (str): Layer identifier
131
        **kwargs: WMTS-specific options
132
    """
133

134
def add_vector_tile(self, url, **kwargs):
135
    """
136
    Add a vector tile layer.
137
    
138
    Args:
139
        url (str): Vector tile URL template
140
        **kwargs: Vector tile styling options
141
    """
142

143
def add_pmtiles(self, url, **kwargs):
144
    """
145
    Add a PMTiles layer.
146
    
147
    Args:
148
        url (str): PMTiles file URL
149
        **kwargs: PMTiles-specific options
150
    """
151
```
152

153
### Interactive Features
154

155
Add interactive elements including markers, drawing tools, measurement tools, and custom controls for enhanced user interaction.
156

157
```python { .api }
158
def add_markers(self, markers, **kwargs):
159
    """
160
    Add point markers to the map.
161
    
162
    Args:
163
        markers (list): List of marker coordinates [[lat, lon], ...]
164
        **kwargs: Marker styling options (color, size, popup, etc.)
165
    """
166

167
def add_circle_markers_from_xy(self, data, x, y, **kwargs):
168
    """
169
    Add circle markers from coordinate data.
170
    
171
    Args:
172
        data: DataFrame or similar with coordinate columns
173
        x (str): Column name for longitude/x coordinates
174
        y (str): Column name for latitude/y coordinates
175
        **kwargs: Circle marker options (radius, color, etc.)
176
    """
177

178
def add_draw_control(self, **kwargs):
179
    """
180
    Add drawing tools for interactive geometry creation.
181
    
182
    Args:
183
        **kwargs: Drawing control options (draw_options, edit_options, etc.)
184
    """
185

186
def add_measure_control(self, **kwargs):
187
    """
188
    Add measurement tools for distance and area calculation.
189
    
190
    Args:
191
        **kwargs: Measurement control options
192
    """
193

194
def add_toolbar(self, **kwargs):
195
    """
196
    Add a custom toolbar with various tools.
197
    
198
    Args:
199
        **kwargs: Toolbar configuration options
200
    """
201
```
202

203
### Map Comparison and Split Views
204

205
Create side-by-side map comparisons and split views for data comparison and analysis.
206

207
```python { .api }
208
def split_map(self, left_layer=None, right_layer=None, **kwargs):
209
    """
210
    Create a split-screen map comparison.
211
    
212
    Args:
213
        left_layer: Layer for left side of comparison
214
        right_layer: Layer for right side of comparison
215
        **kwargs: Split map options (add_close_button, etc.)
216
    """
217

218
def linked_maps(self, rows=2, cols=2, **kwargs):
219
    """
220
    Create linked maps that pan and zoom together.
221
    
222
    Args:
223
        rows (int): Number of map rows
224
        cols (int): Number of map columns
225
        **kwargs: Linked map options
226
    """
227
```
228

229
### Export and Output
230

231
Export maps to various formats including HTML, images, and integration with web frameworks.
232

233
```python { .api }
234
def to_html(self, filename=None, **kwargs):
235
    """
236
    Export map to HTML file.
237
    
238
    Args:
239
        filename (str): Output HTML file path
240
        **kwargs: Export options (title, width, height, etc.)
241
        
242
    Returns:
243
        str: HTML content if filename is None
244
    """
245

246
def to_image(self, filename=None, **kwargs):
247
    """
248
    Export map to image file.
249
    
250
    Args:
251
        filename (str): Output image file path
252
        **kwargs: Image export options (width, height, dpi, etc.)
253
        
254
    Returns:
255
        bytes: Image data if filename is None
256
    """
257

258
def to_streamlit(self, **kwargs):
259
    """
260
    Convert map for Streamlit display.
261
    
262
    Args:
263
        **kwargs: Streamlit-specific options
264
        
265
    Returns:
266
        streamlit component
267
    """
268

269
def save_draw_features(self, filename, **kwargs):
270
    """
271
    Save drawn features to file.
272
    
273
    Args:
274
        filename (str): Output file path
275
        **kwargs: Save options (format, crs, etc.)
276
    """
277
```
278

279
## Backend-Specific Classes
280

281
### IPyleaflet Backend (leafmap.leafmap.Map)
282

283
The default backend for standard Jupyter environments, providing full-featured interactive mapping with extensive widget support.
284

285
```python { .api }
286
import leafmap.leafmap as leafmap
287

288
# Full API with 222 methods including:
289
# - Complete layer management
290
# - Interactive widgets and controls  
291
# - Advanced analysis tools
292
# - Export capabilities
293
```
294

295
### Folium Backend (leafmap.foliumap.Map)
296

297
Optimized for restricted environments like Google Colab and marimo, providing core mapping functionality with HTML-based output.
298

299
```python { .api }
300
import leafmap.foliumap as leafmap
301

302
# 149 methods with focus on:
303
# - Core mapping functionality
304
# - HTML export compatibility
305
# - Colab/marimo optimization
306
```
307

308
### MapLibre GL JS Backend (leafmap.maplibregl.Map)
309

310
Advanced WebGL-based mapping with 3D capabilities and high-performance rendering.
311

312
```python { .api }
313
import leafmap.maplibregl as leafmap
314

315
# 179 methods including:
316
# - 3D terrain visualization
317
# - WebGL acceleration
318
# - Advanced styling with JSON
319
# - Custom UI widgets
320
```
321

322
### Plotly Backend (leafmap.plotlymap.Map)
323

324
Statistical mapping and dashboard creation with interactive plotting capabilities.
325

326
```python { .api }
327
import leafmap.plotlymap as leafmap
328

329
# 50+ methods focused on:
330
# - Statistical visualization
331
# - Dashboard integration
332
# - Interactive plotting
333
```
334

335
### Other Backends
336

337
Additional specialized backends for specific use cases:
338

339
```python { .api }
340
import leafmap.deckgl as leafmap      # GPU-accelerated visualization
341
import leafmap.bokehmap as leafmap    # Server-based applications  
342
import leafmap.kepler as leafmap      # Advanced geospatial visualization
343
import leafmap.heremap as leafmap     # HERE Maps integration
344
import leafmap.mapbox as leafmap      # Custom Mapbox GL JS
345
```
346

347
## Usage Examples
348

349
### Basic Map Creation
350

351
```python
352
import leafmap
353

354
# Create a basic map
355
m = leafmap.Map(center=[37.7749, -122.4194], zoom=10)
356

357
# Add basemap
358
m.add_basemap('SATELLITE')
359

360
# Add layer control
361
m.add_layer_control()
362

363
# Display
364
m
365
```
366

367
### Backend-Specific Usage
368

369
```python
370
# Force specific backend
371
import leafmap.maplibregl as leafmap
372

373
# Create 3D map
374
m = leafmap.Map(
375
    center=[37.7749, -122.4194], 
376
    zoom=10,
377
    pitch=60,
378
    bearing=45
379
)
380

381
# Add 3D terrain
382
m.add_3d_terrain()
383
```
384

385
## Environment Detection
386

387
Leafmap automatically selects backends based on environment:
388

389
- **Standard Jupyter**: ipyleaflet backend (leafmap.leafmap)
390
- **Google Colab**: folium backend (leafmap.foliumap)  
391
- **Marimo**: folium backend (leafmap.foliumap)
392
- **Documentation**: folium backend when USE_MKDOCS is set