pysepal.mapping.sepal_map.SepalMap#

class pysepal.mapping.sepal_map.SepalMap(*args, **kwargs)[source]#

Custom Map object design to build application.

The SepalMap class inherits from ipyleaflet.Map. It can thus be initialized with all its parameter. The map will fall back to CartoDB.DarkMatter map that well fits with the rest of the sepal_ui layout. Numerous methods have been added in the class to help you deal with your workflow implementation. It can natively display raster from .tif files and files and ee objects using methods that have the same signature as the GEE JavaScripts console.

Parameters:

basemaps (List[str]) – the basemaps used as background in the map. If multiple selection, they will be displayed as layers.
dc (GeomanDrawControl | None) – whether or not the drawing control should be displayed. default to false
vinspector (bool) – Add value inspector to map, useful to inspect pixel values. default to false
gee (bool) – whether or not to use the ee binding. If False none of the earthengine display functionalities can be used. default to True
statebar (bool) – whether or not to display the Statebar in the map
theme_toggle (ThemeToggle) – deprecated ThemeToggle source. Use theme_state instead.
theme_state (ThemeState | None) – shared theme state for Solara apps
gee_session (optional) – a custom EESession object to do gee requests. default to None (deprecated in favor of gee_interface)
gee_interface (GEEInterface | None) – a shared GEEInterface instance. If provided, takes precedence over gee_session
fullscreen (bool) – whether or not to display the map in full screen. default to False
kwargs (optional) – any parameter from a ipyleaflet.Map. if set, ‘ee_initialize’ will be overwritten.
map_id (str)

Raises:

ValueError – if both gee_session and gee_interface are provided

Added in version 3.0.0: Added gee_interface parameter for sharing GEEInterface instances across components.

Attributes

`canvas_height_px`	Canvas height in px, pushed from the frontend.
`canvas_width_px`	Canvas width in px, pushed from the frontend.
`dc`	The drawing control of the map
`gee`	Either the map will use ee binding or not
`state`	The statebar to inform the user about tile loading
`v_inspector`	The value inspector of the map
`viewport_inset_bottom`	Bottom overlay height in px.
`viewport_inset_left`	Left overlay width in px.
`viewport_inset_right`	Right overlay width in px.

Methods

`__init__`	Custom Map object design to build application.
`addLayer`	Customized add_layer method designed for EE objects.
`add_basemap`	Adds a basemap to the map.
`add_colorbar`	Add a colorbar to the map.
`add_ee_layer`	Customized add_layer method designed for EE objects.
`add_ee_layer_async`	Customized add_layer method designed for EE objects.
`add_layer`	Add layer and use a default style for the GeoJSON inputs.
`add_legend`	Creates and adds a custom legend as widget control to the map.
`add_raster`	Adds a local raster dataset to the map.
`bind_theme_state`	Bind the map to a shared theme state.
`centerObject`	Get the proper zoom to the given ee geometry.
`find_layer`	Search a layer by name or index.
`fit_bounds`	Abstract method to fit the map to the given bounds.
`getScale`	Returns the approximate pixel scale of the current map view, in meters.
`get_basemap_list`	Get the complete list of available basemaps.
`get_scale`	Returns the approximate pixel scale of the current map view, in meters.
`hide_dc`	Hide the drawing control of the map.
`remove_all`	Remove all the layers from the maps.
`remove_layer`	Remove a layer based on a key.
`setCenter`	Centers the map view at a given coordinates with the given zoom level.
`set_center`	Centers the map view at a given coordinates with the given zoom level.
`show_dc`	Show the drawing control on the map.
`zoom_bounds`	Adapt the zoom to the given bounds.
`zoom_ee_object`	Get the proper zoom to the given ee geometry.
`zoom_raster`	Adapt the zoom to the given LocalLayer.

SepalMap.__init__(basemaps=[], dc=False, vinspector=False, gee=True, statebar=False, theme_toggle=None, theme_state=None, gee_session=None, gee_interface=None, fullscreen=False, map_id='', **kwargs)[source]#

Custom Map object design to build application.

Parameters:

basemaps (List[str]) – the basemaps used as background in the map. If multiple selection, they will be displayed as layers.
dc (bool) – whether or not the drawing control should be displayed. default to false
vinspector (bool) – Add value inspector to map, useful to inspect pixel values. default to false
gee (bool) – whether or not to use the ee binding. If False none of the earthengine display functionalities can be used. default to True
statebar (bool) – whether or not to display the Statebar in the map
theme_toggle (ThemeToggle | None) – deprecated ThemeToggle source. Use theme_state instead.
theme_state (ThemeState | None) – shared theme state for Solara apps
gee_session (optional) – a custom EESession object to do gee requests. default to None (deprecated in favor of gee_interface)
gee_interface (GEEInterface | None) – a shared GEEInterface instance. If provided, takes precedence over gee_session
fullscreen (bool) – whether or not to display the map in full screen. default to False
kwargs (optional) – any parameter from a ipyleaflet.Map. if set, ‘ee_initialize’ will be overwritten.
map_id (str)

Raises:

ValueError – if both gee_session and gee_interface are provided

Return type:

None

Added in version 3.0.0: Added gee_interface parameter for sharing GEEInterface instances across components.

SepalMap.addLayer(ee_object, vis_params={}, name='', shown=True, opacity=1.0, viz_name='', key='', use_map_vis=True, autocenter=False)#

Customized add_layer method designed for EE objects.

Copy the addLayer method from geemap to read and guess the vizaulization parameters the same way as in SEPAL recipes. If the vizparams are empty and visualization metadata exist, SepalMap will use them automatically.

Parameters:

ee_object (ComputedObject) – the ee OBject to draw on the map
vis_params (dict) – the visualization parameters set as in GEE
name (str) – the name of the layer
shown (bool) – either to show the layer or not, default to true (it is bugged in ipyleaflet)
opacity (float) – the opcity of the layer from 0 to 1, default to 1.
viz_name (str) – the name of the vizaulization you want to use. default to the first one if existing
key (str) – the unequivocal key of the layer. by default use a normalized str of the layer name
use_map_vis (bool) – whether or not to use the map visualization parameters. default to True
autocenter (bool) – whether or not to center the map on the layer. default to False

Return type:

None

SepalMap.add_basemap(basemap='HYBRID')[source]#

Adds a basemap to the map.

Parameters:: basemap (str) – Can be one of string from basemaps. Defaults to ‘HYBRID’.
Return type:: None

SepalMap.add_colorbar(colors, cmap='viridis', vmin=0.0, vmax=1.0, index=[], categorical=False, step=0, transparent_bg=False, position='bottomright', layer_name='', **kwargs)[source]#

Add a colorbar to the map.

Parameters:

colors (list) – The set of colors to be used for interpolation. Colors can be provided in the form: * tuples of RGBA ints between 0 and 255 (e.g: (255, 255, 0) or (255, 255, 0, 255)) * tuples of RGBA floats between 0. and 1. (e.g: (1.,1.,0.) or (1., 1., 0., 1.)) * HTML-like string (e.g: “#ffff00) * a color name or shortcut (e.g: “y” or “yellow”)
cmap (str) – a matplotlib colormap default to viridis
vmin (float) – The minimal value for the colormap. Values lower than vmin will be bound directly to colors[0].. Defaults to 0.
vmax (float) – The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1]. Defaults to 1.0.
index (list) – The values corresponding to each color. It has to be sorted, and have the same length as colors. If None, a regular grid between vmin and vmax is created. Defaults to None.
categorical (bool, optional) – Whether or not to create a categorical colormap. Defaults to False.
step (int) – The step to split the LinearColormap into a StepColormap. Defaults to None.
position (str) – The position for the colormap widget. Defaults to “bottomright”.
layer_name (str) – Layer name of the colorbar to be associated with. Defaults to None.
kwargs – any other argument of the colorbar object from matplotlib
transparent_bg (bool)

Return type:

None

SepalMap.add_ee_layer(ee_object, vis_params={}, name='', shown=True, opacity=1.0, viz_name='', key='', use_map_vis=True, autocenter=False)[source]#

Customized add_layer method designed for EE objects.

Parameters:

ee_object (ComputedObject) – the ee OBject to draw on the map
vis_params (dict) – the visualization parameters set as in GEE
name (str) – the name of the layer
shown (bool) – either to show the layer or not, default to true (it is bugged in ipyleaflet)
opacity (float) – the opcity of the layer from 0 to 1, default to 1.
viz_name (str) – the name of the vizaulization you want to use. default to the first one if existing
key (str) – the unequivocal key of the layer. by default use a normalized str of the layer name
use_map_vis (bool) – whether or not to use the map visualization parameters. default to True
autocenter (bool) – whether or not to center the map on the layer. default to False

Return type:

None

async SepalMap.add_ee_layer_async(ee_object, vis_params={}, name='', shown=True, opacity=1.0, viz_name='', key='', use_map_vis=True, autocenter=False)[source]#

Customized add_layer method designed for EE objects.

Parameters:

ee_object (ComputedObject) – the ee OBject to draw on the map
vis_params (dict) – the visualization parameters set as in GEE
name (str) – the name of the layer
shown (bool) – either to show the layer or not, default to true (it is bugged in ipyleaflet)
opacity (float) – the opcity of the layer from 0 to 1, default to 1.
viz_name (str) – the name of the vizaulization you want to use. default to the first one if existing
key (str) – the unequivocal key of the layer. by default use a normalized str of the layer name
use_map_vis (bool) – whether or not to use the map visualization parameters. default to True
autocenter (bool) – whether or not to center the map on the layer. default to False

Return type:

None

SepalMap.add_layer(layer, hover=False, key='')[source]#

Add layer and use a default style for the GeoJSON inputs.

Remove existing layer if already on the map.

Parameters:

layer (Layer) – any layer type from ipyleaflet
hover (bool) – whether to use the default hover style or not.
key (str) – the unequivocal key of the layer. by default use a normalized str of the layer name

Return type:

None

SepalMap.add_legend(title='Legend', legend_dict={}, position='bottomright', vertical=True)[source]#

Creates and adds a custom legend as widget control to the map.

Parameters:

title (str) – Title of the legend. Defaults to ‘Legend’.
legend_dict (dict) – dictionary with key as label name and value as color
position (str) – the position (corners) of the legend on the map
vertical (bool) – vertical or horizoal position of the legend

Return type:

None

SepalMap.add_raster(image, bands=None, layer_name='Layer_llc', colormap='inferno', opacity=1.0, fit_bounds=True, key='')[source]#

Adds a local raster dataset to the map.

If used on a cloud platform (or distant jupyter), this method won’t know where the entry point of the client is set and will thus fail to display the image. Please follow instructions from https://localtileserver.banesullivan.com/installation/remote-jupyter.html and set up the LOCALTILESERVER_CLIENT_PREFIX environment variable.

Parameters:

image (str | Path) – The image file path.
bands (list | int | None) – The image bands to use. It can be either a number (e.g., 1) or a list (e.g., [3, 2, 1]). Defaults to None.
layer_name (str) – The layer name to use for the raster. Defaults to None. If a layer is already using this name 3 random letter will be added
colormap (str | Colormap) – The name of the colormap to use for the raster, such as ‘gray’ and ‘terrain’. More can be found at https://matplotlib.org/3.1.0/tutorials/colors/colormaps.html. Defaults to inferno.
opacity (float) – the opacity of the layer, default 1.0.
key (str) – the unequivocal key of the layer. by default use a normalized str of the layer name
fit_bounds (bool) – Whether or not we should fit the map to the image bounds. Default to True.

Returns:

the local tile layer embedding the raster member (to be used with other tools of sepal-ui)

Return type:

TileLayer

SepalMap.bind_theme_state(theme_state)[source]#

Bind the map to a shared theme state.

Parameters:: theme_state (ThemeState | None)
Return type:: None

SepalMap.centerObject(item, zoom_out=1)#

Get the proper zoom to the given ee geometry.

Parameters:

item (ComputedObject) – the geometry to zoom on
zoom_out (int) – Zoom out the bounding zoom

Return type:

Self

SepalMap.find_layer(key, base=False, none_ok=False)[source]#

Search a layer by name or index.

Parameters:

key (Layer | str | int) – the layer name, the layer key, the index or directly the layer
base (bool) – either the basemaps should be included in the search or not. default to false
none_ok (bool) – if True the function will not raise error if no layer is found. Default to False

Returns:

The first layer using the same name or index else None

Return type:

TileLayer

SepalMap.fit_bounds(bounds)[source]#: Abstract method to fit the map to the given bounds.

SepalMap.getScale()#

Returns the approximate pixel scale of the current map view, in meters.

Reference: https://blogs.bing.com/maps/2006/02/25/map-control-zoom-levels-gt-resolution.

Returns:: Map resolution in meters.
Return type:: float

static SepalMap.get_basemap_list()[source]#

Get the complete list of available basemaps.

This function is intending for development use It give the list of all the available basemaps for SepalMap object.

Returns:: The list of the basemap names
Return type:: List[str]

SepalMap.get_scale()[source]#

Returns the approximate pixel scale of the current map view, in meters.

Reference: https://blogs.bing.com/maps/2006/02/25/map-control-zoom-levels-gt-resolution.

Returns:: Map resolution in meters.
Return type:: float

SepalMap.hide_dc()[source]#

Hide the drawing control of the map.

Returns:: Self for method chaining
Return type:: Self

SepalMap.remove_all(base=False, keep_names=None)[source]#

Remove all the layers from the maps.

If base is set to True, the basemaps are removed as well.

Parameters:

base (bool) – whether or not the basemaps should be removed, default to False
keep_names (list[str] | None) – if set, will keep the layers with these names

Return type:

None

SepalMap.remove_layer(key, base=False, none_ok=False)[source]#

Remove a layer based on a key.

The key can be, a Layer object, the name of a layer or the index in the layer list.

Parameters:

key (Layer | int | str) – the key to find the layer to delete
base (bool) – either the basemaps should be included in the search or not. default t false
none_ok (bool) – if True the function will not raise error if no layer is found. Default to False

Return type:

None

SepalMap.setCenter(lon, lat, zoom=-1)#

Centers the map view at a given coordinates with the given zoom level.

Parameters:

lon (float) – The longitude of the center, in degrees.
lat (float) – The latitude of the center, in degrees.
zoom (int) – The zoom level, from 1 to 24. Defaults to None.

Return type:

None

SepalMap.set_center(lon, lat, zoom=-1)[source]#

Centers the map view at a given coordinates with the given zoom level.

Parameters:

lon (float) – The longitude of the center, in degrees.
lat (float) – The latitude of the center, in degrees.
zoom (int) – The zoom level, from 1 to 24. Defaults to None.

Return type:

None

SepalMap.show_dc()[source]#

Show the drawing control on the map.

Returns:: Self for method chaining
Return type:: Self

SepalMap.zoom_bounds(bounds, zoom_out=1)[source]#

Adapt the zoom to the given bounds. and center the image.

Parameters:

bounds (Sequence[float]) – coordinates corners as minx, miny, maxx, maxy in EPSG:4326
zoom_out (int) – Zoom out the bounding zoom

Return type:

Self

SepalMap.zoom_ee_object(item, zoom_out=1)[source]#

Get the proper zoom to the given ee geometry.

Parameters:

item (ComputedObject) – the geometry to zoom on
zoom_out (int) – Zoom out the bounding zoom

Return type:

Self

SepalMap.zoom_raster(layer, zoom_out=1)[source]#

Adapt the zoom to the given LocalLayer.

The localLayer need to come from the add_raster method to embed the image name.

Parameters:

layer (LocalTileLayer) – the localTile layer to zoom on. it needs to embed the “raster” member
zoom_out (int) – Zoom out the bounding zoom

Return type:

Self