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