plotlymap module¶
leafmap.plotlymap
¶
Canvas
¶
The widgets.HBox containing the map and a toolbar.
__init__(map, map_min_width='90%', map_max_width='98%', map_refresh=False, **kwargs)
¶
Initialize the Canvas.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
map
|
FigureWidget
|
The map to display. |
required |
map_min_width
|
str
|
The minimum width of the map. Defaults to '90%'. |
'90%'
|
map_max_width
|
str
|
The maximum width of the map. Defaults to '98%'. |
'98%'
|
map_refresh
|
bool
|
Whether to refresh the map when the map is resized. Defaults to False. |
False
|
toolbar_reset()
¶
Reset the toolbar so that no tool is selected.
Map
¶
Bases: FigureWidget
The Map class inherits the Plotly FigureWidget class. More info at https://plotly.com/python/figurewidget.
__init__(center=(20, 0), zoom=1, basemap='open-street-map', height=600, **kwargs)
¶
Initializes a map. More info at https://plotly.com/python/mapbox-layers/
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
center
|
tuple
|
Center of the map. Defaults to (20, 0). |
(20, 0)
|
zoom
|
float
|
Zoom level of the map. Defaults to 1. |
1
|
basemap
|
str
|
Can be one of string from "open-street-map", "carto-positron", "carto-darkmatter", "stamen-terrain", "stamen-toner" or "stamen-watercolor" . Defaults to 'open-street-map'. |
'open-street-map'
|
height
|
int
|
Height of the map. Defaults to 600. |
600
|
add_basemap(basemap='ROADMAP')
¶
Adds a basemap to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
basemap
|
str
|
Can be one of string from basemaps. Defaults to 'ROADMAP'. |
'ROADMAP'
|
add_choropleth_map(data, name=None, z=None, colorscale='Viridis', **kwargs)
¶
Adds a choropleth map to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
str
|
File path to vector data, e.g., https://raw.githubusercontent.com/opengeos/leafmap/master/examples/data/countries.geojson |
required |
name
|
str
|
Name of the layer. Defaults to None. |
None
|
z
|
str
|
Z value of the data. Defaults to None. |
None
|
colorscale
|
str
|
Color scale of the data. Defaults to "Viridis". |
'Viridis'
|
add_cog_layer(url, name='Untitled', attribution='', opacity=1.0, bands=None, titiler_endpoint=None, **kwargs)
¶
Adds a COG TileLayer to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
The URL of the COG tile layer, e.g., 'https://github.com/opengeos/data/releases/download/raster/Libya-2023-07-01.tif' |
required |
name
|
str
|
The layer name to use for the layer. Defaults to 'Untitled'. |
'Untitled'
|
attribution
|
str
|
The attribution to use. Defaults to ''. |
''
|
opacity
|
float
|
The opacity of the layer. Defaults to 1. |
1.0
|
bands
|
list
|
The bands to use. Defaults to None. |
None
|
titiler_endpoint
|
str
|
TiTiler endpoint. Defaults to "https://titiler.opengeos.org". |
None
|
**kwargs
|
Any
|
Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale,
color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/
and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3].
apply a rescaling to multiple bands, use something like |
{}
|
add_controls(controls)
¶
Adds controls to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
controls
|
list
|
List of controls to add, e.g., ['drawline', 'drawopenpath', 'drawclosedpath', 'drawcircle', 'drawrect', 'eraseshape'] See https://bit.ly/33Tmqxr |
required |
add_gdf(gdf, label_col=None, color_col=None, labels=None, opacity=1.0, zoom=None, color_continuous_scale='Viridis', **kwargs)
¶
Adds a GeoDataFrame to the map. Args: gdf (GeoDataFrame): A GeoDataFrame. label_col (str, optional): The column name of locations. Defaults to None. color_col (str, optional): The column name of color. Defaults to None.
add_geojson(data, name, type, color, opacity)
¶
Add layers to the Map
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict
|
Geojson in Dict form |
required |
name
|
str
|
Name for the Layer |
required |
color
|
str
|
Plain name for color (e.g: blue) or color code (e.g: #FF0000) |
required |
opacity
|
float
|
opacity of the layer in Map |
required |
add_geojson_layer(geojson_in, name, color='blue', opacity=1)
¶
Prepare proper and give style for different type of Geometry
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geojson_in
|
str | dict
|
The file path or http URL to the input GeoJSON or a dictionary containing the geojson. |
required |
name
|
str
|
Name for the Layer |
required |
color
|
str
|
Plain name for color (e.g: blue) or color code (e.g: #FF0000) |
'blue'
|
opacity
|
float
|
opacity of the layer in Map |
1
|
add_heatmap(data, latitude='latitude', longitude='longitude', z='value', radius=10, colorscale=None, name='Heat map', **kwargs)
¶
Adds a heat map to the map. Reference: https://plotly.com/python/mapbox-density-heatmaps
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
str | DataFrame
|
File path or HTTP URL to the input file or a . For example, https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv |
required |
latitude
|
str
|
The column name of latitude. Defaults to "latitude". |
'latitude'
|
longitude
|
str
|
The column name of longitude. Defaults to "longitude". |
'longitude'
|
z
|
str
|
The column name of z values. Defaults to "value". |
'value'
|
radius
|
int
|
Radius of each “point” of the heatmap. Defaults to 25. |
10
|
colorscale
|
str
|
Color scale of the data, e.g., Viridis. See https://plotly.com/python/builtin-colorscales. Defaults to None. |
None
|
name
|
str
|
Layer name to use. Defaults to "Heat map". |
'Heat map'
|
add_heatmap_demo(**kwargs)
¶
Adds a heatmap to the map.
add_layer(layer, name=None, **kwargs)
¶
Adds a layer to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
layer
|
graph_objects
|
Layer to add. |
required |
name
|
str
|
Name of the layer. Defaults to None. |
None
|
add_mapbox_layer(style, access_token=None)
¶
Adds a mapbox layer to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
style
|
str | dict
|
Style to add. Can be "basic", "streets", "outdoors", "light", "dark", "satellite", or "satellite-streets". See https://plotly.com/python/mapbox-layers/ and https://docs.mapbox.com/mapbox-gl-js/style-spec/ |
required |
access_token
|
str
|
The Mapbox Access token. It can be set as an environment variable "MAPBOX_TOKEN". Defaults to None. |
None
|
add_mosaic_layer(url, titiler_endpoint=None, name='Mosaic Layer', attribution='', opacity=1.0, **kwargs)
¶
Adds a STAC TileLayer to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
HTTP URL to a MosaicJSON. |
required |
titiler_endpoint
|
str
|
TiTiler endpoint, e.g., "https://titiler.opengeos.org". Defaults to None. |
None
|
name
|
str
|
The layer name to use for the layer. Defaults to 'Mosaic Layer'. |
'Mosaic Layer'
|
attribution
|
str
|
The attribution to use. Defaults to ''. |
''
|
opacity
|
float
|
The opacity of the layer. Defaults to 1. |
1.0
|
add_planet_by_month(year=2016, month=1, api_key=None, token_name='PLANET_API_KEY', name=None, attribution='', opacity=1.0)
¶
Adds Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis/
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
The year of Planet global mosaic, must be >=2016. Defaults to 2016. |
2016
|
month
|
int
|
The month of Planet global mosaic, must be 1-12. Defaults to 1. |
1
|
api_key
|
str
|
The Planet API key. Defaults to None. |
None
|
token_name
|
str
|
The environment variable name of the API key. Defaults to "PLANET_API_KEY". |
'PLANET_API_KEY'
|
name
|
str
|
Name of the layer. Defaults to 'TileLayer'. |
None
|
attribution
|
str
|
The attribution to use. Defaults to "". |
''
|
opacity
|
float
|
The opacity of the layer. Defaults to 1. |
1.0
|
add_planet_by_quarter(year=2016, quarter=1, api_key=None, token_name='PLANET_API_KEY', name=None, attribution='', opacity=1.0)
¶
Adds Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis/
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
The year of Planet global mosaic, must be >=2016. Defaults to 2016. |
2016
|
quarter
|
int
|
The quarter of Planet global mosaic, must be 1-4. Defaults to 1. |
1
|
api_key
|
str
|
The Planet API key. Defaults to None. |
None
|
token_name
|
str
|
The environment variable name of the API key. Defaults to "PLANET_API_KEY". |
'PLANET_API_KEY'
|
name
|
str
|
Name of the layer. Defaults to 'TileLayer'. |
None
|
attribution
|
str
|
The attribution to use. Defaults to "". |
''
|
opacity
|
float
|
The opacity of the layer. Defaults to 1. |
1.0
|
add_scatter_plot_demo(**kwargs)
¶
Adds a scatter plot to the map.
add_stac_layer(url=None, collection=None, items=None, assets=None, bands=None, titiler_endpoint=None, name='STAC Layer', attribution='', opacity=1.0, **kwargs)
¶
Adds a STAC TileLayer to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json |
None
|
collection
|
str
|
The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2. |
None
|
items
|
str
|
The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1. |
None
|
assets
|
str | list
|
The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"]. |
None
|
bands
|
list
|
A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"] |
None
|
titiler_endpoint
|
str
|
TiTiler endpoint, e.g., "https://titiler.opengeos.org", "planetary-computer", "pc". Defaults to None. |
None
|
name
|
str
|
The layer name to use for the layer. Defaults to 'STAC Layer'. |
'STAC Layer'
|
attribution
|
str
|
The attribution to use. Defaults to ''. |
''
|
opacity
|
float
|
The opacity of the layer. Defaults to 1. |
1.0
|
add_tile_layer(url, name='TileLayer', attribution='', opacity=1.0, **kwargs)
¶
Adds a TileLayer to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
The URL of the tile layer. |
required |
name
|
str
|
Name of the layer. Defaults to 'TileLayer'. |
'TileLayer'
|
attribution
|
str
|
The attribution to use. Defaults to "". |
''
|
opacity
|
float
|
The opacity of the layer. Defaults to 1. |
1.0
|
clear_controls()
¶
Removes all controls from the map.
clear_layers(clear_basemap=False)
¶
Clears all layers from the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
clear_basemap
|
bool
|
If True, clears the basemap. Defaults to False. |
False
|
find_layer_index(name)
¶
Finds the index of a layer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the layer to find. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
Index of the layer. |
get_data_layers()
¶
Returns a dictionary of data layers in the map.
Returns:
| Name | Type | Description |
|---|---|---|
dict |
Dict
|
A dictionary of data layers in the map. |
get_layers()
¶
Returns a dictionary of all layers in the map. Returns: dict: A dictionary of all layers in the map.
get_tile_layers()
¶
Returns a dictionary of tile layers in the map.
Returns:
| Name | Type | Description |
|---|---|---|
dict |
Dict
|
A dictionary of tile layers in the map. |
remove_basemap(name)
¶
Removes a basemap from the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the basemap to remove. |
required |
remove_controls(controls)
¶
Removes controls to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
controls
|
list
|
List of controls to remove, e.g., ["zoomin", "zoomout", "toimage", "pan", "resetview"]. See https://bit.ly/3Jk7wkb |
required |
remove_layer(name)
¶
Removes a layer from the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the layer to remove. |
required |
save(file, format=None, width=None, height=None, scale=None, **kwargs)
¶
Convert a map to a static image and write it to a file or writeable object
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
str
|
A string representing a local file path or a writeable object (e.g. a pathlib.Path object or an open file descriptor) |
required |
format
|
str
|
The desired image format. One of png, jpg, jpeg, webp, svg, pdf, eps. Defaults to None. |
None
|
width
|
int
|
The width of the exported image in layout pixels. If the |
None
|
height
|
int
|
The height of the exported image in layout pixels. If the |
None
|
scale
|
int
|
The scale factor to use when exporting the figure. A scale factor larger than 1.0 will increase the image resolution with respect to the figure's layout pixel dimensions. Whereas as scale factor of less than 1.0 will decrease the image resolution.. Defaults to None. |
None
|
set_center(lat, lon, zoom=None)
¶
Sets the center of the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lat
|
float
|
Latitude. |
required |
lon
|
float
|
Longitude. |
required |
zoom
|
int
|
Zoom level of the map. Defaults to None. |
None
|
set_layer_opacity(name, opacity=1)
¶
Sets the visibility of a layer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the layer to set. |
required |
opacity
|
float
|
Opacity of the layer. Defaults to 1. |
1
|
set_layer_visibility(name, show=True)
¶
Sets the visibility of a layer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name of the layer to set. |
required |
show
|
bool
|
If True, shows the layer. Defaults to True. |
True
|
show(toolbar=True, map_min_width='91%', map_max_width='98%', refresh=False, **kwargs)
¶
Shows the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
toolbar
|
bool
|
Whether to show the toolbar. Defaults to True. |
True
|
map_min_width
|
str
|
The minimum width of the map. Defaults to '91%'. |
'91%'
|
map_max_width
|
str
|
The maximum width of the map. Defaults to '98%'. |
'98%'
|
refresh
|
bool
|
Whether to refresh the map when the map is resized. Defaults to False. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
Canvas |
None
|
Map canvas. |
fix_widget_error()
¶
Fix FigureWidget - 'mapbox._derived' Value Error. Adopted from: https://github.com/plotly/plotly.py/issues/2570#issuecomment-738735816