sepal_ui.mapping.sepal_map.SepalMap#

class sepal_ui.mapping.sepal_map.SepalMap(**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 (DrawControl | 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
kwargs (optional) – any parameter from a ipyleaflet.Map. if set, ‘ee_initialize’ will be overwritten.

Attributes

`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

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_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.
`centerObject`	Get the proper zoom to the given ee geometry.
`find_layer`	Search a layer by name or index.
`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.
`get_viz_params`	Return the vizual parameters that are set in the metadata of the image.
`hide_dc`	Hide the drawing control of the map.
`remove_all`	Remove all the layers from the maps.
`remove_last_layer`	Remove last added layer from Map.
`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, **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
kwargs (optional) – any parameter from a ipyleaflet.Map. if set, ‘ee_initialize’ will be overwritten.

Return type:

None

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

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

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='')[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

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_mgy', 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.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.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

static SepalMap.get_viz_params(image)[source]#

Return the vizual parameters that are set in the metadata of the image.

Parameters:: image (Image) – the image to analyse
Returns:: The dictionary of the find properties
Return type:: dict

SepalMap.hide_dc()[source]#

Hide the drawing control of the map.

Deprecated since version 2.8.0: use dc methods instead

Return type:: Self

SepalMap.remove_all(base=False)[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
Return type:: None

SepalMap.remove_last_layer(local=False)[source]#

Remove last added layer from Map.

Parameters:: local (bool) – Specify True to only remove local last layers, otherwise will remove every last layer.
Return type:: Self

Deprecated since version 2.8.0: use remove_layer(-1) instead

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.

Deprecated since version 2.8.0: use dc methods instead

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