0
# Leafmap
1

2
A comprehensive Python package for geospatial analysis and interactive mapping designed specifically for Jupyter environments (Google Colab, Jupyter Notebook, JupyterLab, marimo). Built as a spin-off from the geemap project to serve non-Google Earth Engine users, it provides powerful geospatial capabilities through a minimal-coding approach with multiple backend support.
3

4
## Package Information
5

6
- **Package Name**: leafmap
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install leafmap` or `conda install -c conda-forge leafmap`
10
- **Optional Dependencies**: Various groups for specialized functionality (lidar, raster, vector, ai, sql, apps)
11

12
## Core Imports
13

14
```python
15
import leafmap  # Auto-selects backend based on environment
16
```
17

18
**Backend Selection Logic**: Leafmap automatically selects the appropriate backend:
19
- **Google Colab/Marimo**: Uses folium backend (`leafmap.foliumap`)
20
- **Standard Jupyter**: Uses ipyleaflet backend (`leafmap.leafmap`) 
21
- **Manual Selection**: Import specific backends directly
22

23
Backend-specific imports:
24

25
```python
26
import leafmap.leafmap as leafmap    # ipyleaflet backend (default in Jupyter)
27
import leafmap.foliumap as leafmap   # folium backend (default in Colab/marimo)
28
import leafmap.maplibregl as leafmap # MapLibre GL JS backend
29
import leafmap.plotlymap as leafmap  # Plotly backend
30
import leafmap.deckgl as leafmap     # lonboard/deck.gl backend
31
import leafmap.bokehmap as leafmap   # bokeh backend
32
import leafmap.kepler as leafmap     # kepler.gl backend
33
```
34

35
Utility modules:
36

37
```python
38
from leafmap import common      # Core utility functions
39
from leafmap import basemaps    # Basemap management
40
from leafmap import examples    # Example datasets
41
from leafmap import stac        # STAC catalog functions
42
from leafmap import osm         # OpenStreetMap functions
43
```
44

45
## Basic Usage
46

47
```python
48
import leafmap
49

50
# Create an interactive map (backend auto-selected based on environment)
51
m = leafmap.Map(center=[40, -100], zoom=4)
52

53
# Add a basemap
54
m.add_basemap('OpenTopoMap')
55

56
# Add vector data
57
m.add_vector('path/to/vector.shp', layer_name='Vector Layer')
58

59
# Add raster data
60
m.add_raster('path/to/raster.tif', colormap='terrain', layer_name='Raster Layer')
61

62
# Add online data sources
63
m.add_cog_layer('https://example.com/data.tif', name='COG Layer')
64

65
# Display the map
66
m
67
```
68

69
## Architecture
70

71
Leafmap uses a multi-backend architecture that automatically selects the appropriate mapping framework based on the runtime environment:
72

73
- **Backend Selection**: Automatic detection of Colab, marimo, or standard Jupyter environments
74
- **Map Classes**: Each backend provides a Map class with consistent API but specialized capabilities
75
- **Utility Layer**: Common functions for data processing, analysis, and visualization
76
- **Optional Dependencies**: Modular architecture with optional dependency groups for specialized workflows
77

78
The package integrates with numerous geospatial libraries and services including folium, ipyleaflet, bokeh, kepler.gl, pydeck, plotly, maplibre, WhiteboxTools, and cloud data providers.
79

80
## Capabilities
81

82
### Interactive Map Creation
83

84
Core map functionality with multiple backend support including ipyleaflet, folium, MapLibre GL JS, Plotly, Bokeh, Kepler.gl, HERE Maps, Mapbox, and lonboard. Provides automatic backend selection based on environment.
85

86
```python { .api }
87
class Map:
88
    def __init__(self, center=[20, 0], zoom=2, basemap='HYBRID', **kwargs): ...
89
    def add_basemap(self, basemap='HYBRID', show=True, **kwargs): ...
90
    def add_layer_control(self, position='topright', **kwargs): ...
91
```
92

93
[Interactive Maps](./interactive-maps.md)
94

95
### Data Visualization
96

97
Comprehensive data visualization capabilities for vector and raster data, including shapefiles, GeoJSON, COG, STAC, and various online data sources with customizable styling and interactive features.
98

99
```python { .api }
100
def add_vector(self, filename, layer_name='Untitled', **kwargs): ...
101
def add_raster(self, image, colormap=None, vmin=None, vmax=None, **kwargs): ...
102
def add_cog_layer(self, url, name='Untitled', **kwargs): ...
103
def add_geojson(self, data, layer_name='Untitled', **kwargs): ...
104
```
105

106
[Data Visualization](./data-visualization.md)
107

108
### Geospatial Analysis
109

110
Advanced geospatial analysis tools including zonal statistics, clipping, mosaicking, reprojection, and integration with WhiteboxTools for comprehensive analytical capabilities.
111

112
```python { .api }
113
def zonal_stats(image, zones, stats=['count', 'mean', 'std'], **kwargs): ...
114
def clip_image(image, mask, output=None, **kwargs): ...
115
def mosaic(images, output=None, **kwargs): ...
116
def reproject(image, crs, output=None, **kwargs): ...
117
```
118

119
[Geospatial Analysis](./geospatial-analysis.md)
120

121
### Cloud Data Integration
122

123
Integration with major cloud data providers and services including Microsoft Planetary Computer, Google Earth Engine, NASA datasets, Planet Labs, AWS Open Data, and STAC catalogs.
124

125
```python { .api }
126
def stac_search(collection, bbox, time_range=None, **kwargs): ...
127
def add_stac_layer(self, url, collection, item, **kwargs): ...
128
def get_pc_collections(): ...
129
def nasa_data_search(dataset, **kwargs): ...
130
```
131

132
[Cloud Data Integration](./cloud-data.md)
133

134
### Basemap Management
135

136
Extensive basemap collection with 100+ predefined providers supporting XYZ tiles, WMS services, and custom tile sources with backend-specific optimizations.
137

138
```python { .api }
139
def get_xyz_dict(free_only=True, france=False): ...
140
def xyz_to_leaflet(): ...
141
def search_qms(keyword): ...
142
XYZ_TILES: dict  # Built-in basemap providers (100+ total with xyzservices integration)
143
```
144

145
[Basemap Management](./basemaps.md)
146

147
### File I/O and Data Processing
148

149
Comprehensive file input/output capabilities supporting various geospatial formats, coordinate transformations, and data conversion utilities for seamless data workflows.
150

151
```python { .api }
152
def download_file(url, filename, **kwargs): ...
153
def read_raster(filename, **kwargs): ...
154
def read_vector(filename, **kwargs): ...
155
def csv_to_geojson(filename, **kwargs): ...
156
```
157

158
[File I/O and Data Processing](./file-io.md)
159

160
### OpenStreetMap Integration
161

162
Direct integration with OpenStreetMap data through the Overpass API, enabling querying and visualization of OSM data by address, place, bounding box, or point with tag-based filtering.
163

164
```python { .api }
165
def osm_gdf_from_address(address, tags, **kwargs): ...
166
def osm_gdf_from_bbox(bbox, tags, **kwargs): ...
167
def osm_tags_list(): ...
168
```
169

170
[OpenStreetMap Integration](./osm-integration.md)
171

172
### Statistical Plotting
173

174
Interactive statistical plotting capabilities using Plotly for creating bar charts, line charts, histograms, and pie charts integrated with geospatial data workflows.
175

176
```python { .api }
177
def bar_chart(data, x, y, **kwargs): ...
178
def line_chart(data, x, y, **kwargs): ...
179
def histogram(data, column, **kwargs): ...
180
```
181

182
[Statistical Plotting](./statistical-plotting.md)
183

184
## Package-level Functions
185

186
```python { .api }
187
def view_vector(vector, zoom_to_layer=True, pickable=True, color_column=None, 
188
               color_scheme="Quantiles", color_map=None, color_k=5, 
189
               color_args={}, open_args={}, map_args={}, **kwargs):
190
    """
191
    Quick visualization of vector data using lonboard/deck.gl backend.
192
    
193
    Args:
194
        vector (Union[str, GeoDataFrame]): Path to vector file or GeoDataFrame
195
        zoom_to_layer (bool): Flag to zoom to the added layer
196
        pickable (bool): Flag to enable picking on the added layer
197
        color_column (str): Column to be used for color encoding
198
        color_scheme (str): Color scheme for classification ("Quantiles", "EqualInterval", etc.)
199
        color_map (Union[str, Dict]): Color map for encoding
200
        color_k (int): Number of classes for color encoding
201
        color_args (dict): Additional arguments for assign_continuous_colors()
202
        open_args (dict): Additional arguments for geopandas.read_file()
203
        map_args (dict): Additional arguments for lonboard.Map
204
        **kwargs: Additional arguments for lonboard.Layer.from_geopandas()
205
        
206
    Returns:
207
        lonboard.Map: A lonboard Map object
208
    """
209

210
def view_pmtiles(url, style=None, name=None, tooltip=True, overlay=True, 
211
                control=True, show=True, zoom_to_layer=True, map_args={}, **kwargs):
212
    """
213
    Quick visualization of PMTiles data using folium backend.
214
    
215
    Args:
216
        url (str): URL to PMTiles file
217
        style (str): CSS style to apply to the layer
218
        name (str): Name of the layer
219
        tooltip (bool): Whether to show tooltip when hovering
220
        overlay (bool): Whether the layer should be added as overlay
221
        control (bool): Whether to include layer in layer control
222
        show (bool): Whether the layer should be shown initially
223
        zoom_to_layer (bool): Whether to zoom to layer extent
224
        map_args (dict): Additional arguments for folium.Map
225
        **kwargs: Additional arguments for PMTilesLayer constructor
226
        
227
    Returns:
228
        folium.Map: A folium Map object
229
    """
230
```
231

232
## Common Types
233

234
```python { .api }
235
# Coordinate reference system specification
236
CRS = Union[str, int, pyproj.CRS]
237

238
# Bounding box as [minx, miny, maxx, maxy]
239
BBox = List[float]
240

241
# Coordinate pairs [latitude, longitude] or [y, x]
242
Coordinates = Union[List[float], Tuple[float, float]]
243

244
# Color specification for styling
245
Color = Union[str, Tuple[int, int, int], Tuple[int, int, int, int]]
246

247
# Geometry types supported
248
Geometry = Union[dict, shapely.geometry.base.BaseGeometry]
249

250
# Data source types
251
DataSource = Union[str, pathlib.Path, gpd.GeoDataFrame, dict]
252

253
# Layer objects for different backends
254
Layer = Union[ipyleaflet.Layer, folium.Layer, dict]
255

256
# Style dictionary for vector styling
257
StyleDict = Dict[str, Union[str, int, float, bool]]
258

259
# Tags dictionary for OSM queries
260
OSMTags = Dict[str, Union[str, bool, List[str]]]
261

262
# Map widget options
263
MapOptions = Dict[str, Union[str, int, float, bool, List, Tuple]]
264

265
# Time range specification
266
TimeRange = Union[List[str], Tuple[str, str]]
267

268
# Search results from STAC/catalog queries
269
SearchResults = List[Dict[str, Any]]
270
```