map_widgets module¶
Various ipywidgets that can be added to a map.
Basemap (HBox)
¶
Widget for selecting a basemap.
Source code in geemap/map_widgets.py
@Theme.apply
class Basemap(ipywidgets.HBox):
"""Widget for selecting a basemap."""
def __init__(self, basemaps: List[str], value: str):
"""Creates a widget for selecting a basemap.
Args:
basemaps (list): The list of basemap names to make available for selection.
value (str): The default value from basemaps to select.
"""
self.on_close = None
self.on_basemap_changed = None
self._dropdown = ipywidgets.Dropdown(
options=list(basemaps),
value=value,
layout=ipywidgets.Layout(width="200px"),
)
self._dropdown.observe(self._on_dropdown_click, "value")
close_button = ipywidgets.Button(
icon="times",
tooltip="Close the basemap widget",
button_style="primary",
layout=ipywidgets.Layout(width="32px"),
)
close_button.on_click(self._on_close_click)
super().__init__([self._dropdown, close_button])
def _on_dropdown_click(self, change: dict) -> None:
"""Handles the dropdown value change event.
Args:
change (dict): The change event dictionary.
"""
if self.on_basemap_changed and change["new"]:
self.on_basemap_changed(self._dropdown.value)
def cleanup(self) -> None:
"""Cleans up the widget by calling the on_close callback if set."""
if self.on_close:
self.on_close()
def _on_close_click(self, _) -> None:
"""Handles the close button click event."""
self.cleanup()
__init__(self, basemaps, value)
special
¶
Creates a widget for selecting a basemap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
basemaps |
list |
The list of basemap names to make available for selection. |
required |
value |
str |
The default value from basemaps to select. |
required |
Source code in geemap/map_widgets.py
def __init__(self, basemaps: List[str], value: str):
"""Creates a widget for selecting a basemap.
Args:
basemaps (list): The list of basemap names to make available for selection.
value (str): The default value from basemaps to select.
"""
self.on_close = None
self.on_basemap_changed = None
self._dropdown = ipywidgets.Dropdown(
options=list(basemaps),
value=value,
layout=ipywidgets.Layout(width="200px"),
)
self._dropdown.observe(self._on_dropdown_click, "value")
close_button = ipywidgets.Button(
icon="times",
tooltip="Close the basemap widget",
button_style="primary",
layout=ipywidgets.Layout(width="32px"),
)
close_button.on_click(self._on_close_click)
super().__init__([self._dropdown, close_button])
cleanup(self)
¶
Cleans up the widget by calling the on_close callback if set.
Source code in geemap/map_widgets.py
def cleanup(self) -> None:
"""Cleans up the widget by calling the on_close callback if set."""
if self.on_close:
self.on_close()
Colorbar (Output)
¶
A matplotlib colorbar widget that can be added to the map.
Source code in geemap/map_widgets.py
@Theme.apply
class Colorbar(ipywidgets.Output):
"""A matplotlib colorbar widget that can be added to the map."""
def __init__(
self,
vis_params: Optional[Union[Dict[str, Any], list, tuple]] = None,
cmap: str = "gray",
discrete: bool = False,
label: Optional[str] = None,
orientation: str = "horizontal",
transparent_bg: bool = False,
font_size: int = 9,
axis_off: bool = False,
max_width: Optional[str] = None,
**kwargs: Any,
):
"""Add a matplotlib colorbar to the map.
Args:
vis_params (dict): Visualization parameters as a dictionary. See
https://developers.google.com/earth-engine/guides/image_visualization # noqa
for options.
cmap (str, optional): Matplotlib colormap. Defaults to "gray". See
https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py # noqa
for options.
discrete (bool, optional): Whether to create a discrete colorbar.
Defaults to False.
label (str, optional): Label for the colorbar. Defaults to None.
orientation (str, optional): Orientation of the colorbar, such as
"vertical" and "horizontal". Defaults to "horizontal".
transparent_bg (bool, optional): Whether to use transparent
background. Defaults to False.
font_size (int, optional): Font size for the colorbar. Defaults
to 9.
axis_off (bool, optional): Whether to turn off the axis. Defaults
to False.
max_width (str, optional): Maximum width of the colorbar in pixels.
Defaults to None.
Raises:
TypeError: If the vis_params is not a dictionary.
ValueError: If the orientation is not either horizontal or vertical.
ValueError: If the provided min value is not convertible to float.
ValueError: If the provided max value is not convertible to float.
ValueError: If the provided opacity value is not convertible to float.
ValueError: If cmap or palette is not provided.
"""
import matplotlib # pylint: disable=import-outside-toplevel
import numpy # pylint: disable=import-outside-toplevel
if max_width is None:
if orientation == "horizontal":
max_width = "270px"
else:
max_width = "100px"
if isinstance(vis_params, (list, tuple)):
vis_params = {"palette": list(vis_params)}
elif not vis_params:
vis_params = {}
if not isinstance(vis_params, dict):
raise TypeError("The vis_params must be a dictionary.")
if isinstance(kwargs.get("colors"), (list, tuple)):
vis_params["palette"] = list(kwargs["colors"])
width, height = self._get_dimensions(orientation, kwargs)
vmin = vis_params.get("min", kwargs.pop("vmin", 0))
try:
vmin = float(vmin)
except ValueError as err:
raise ValueError("The provided min value must be scalar type.")
vmax = vis_params.get("max", kwargs.pop("vmax", 1))
try:
vmax = float(vmax)
except ValueError as err:
raise ValueError("The provided max value must be scalar type.")
alpha = vis_params.get("opacity", kwargs.pop("alpha", 1))
try:
alpha = float(alpha)
except ValueError as err:
raise ValueError("opacity or alpha value must be scalar type.")
if "palette" in vis_params.keys():
hexcodes = coreutils.to_hex_colors(
coreutils.check_cmap(vis_params["palette"])
)
if discrete:
cmap = matplotlib.colors.ListedColormap(hexcodes)
linspace = numpy.linspace(vmin, vmax, cmap.N + 1)
norm = matplotlib.colors.BoundaryNorm(linspace, cmap.N)
else:
cmap = matplotlib.colors.LinearSegmentedColormap.from_list(
"custom", hexcodes, N=256
)
norm = matplotlib.colors.Normalize(vmin=vmin, vmax=vmax)
elif cmap:
cmap = matplotlib.pyplot.get_cmap(cmap)
norm = matplotlib.colors.Normalize(vmin=vmin, vmax=vmax)
else:
raise ValueError(
'cmap keyword or "palette" key in vis_params must be provided.'
)
fig, ax = matplotlib.pyplot.subplots(figsize=(width, height))
cb = matplotlib.colorbar.ColorbarBase(
ax,
norm=norm,
alpha=alpha,
cmap=cmap,
orientation=orientation,
**kwargs,
)
label = label or vis_params.get("bands") or kwargs.pop("caption", None)
if label:
cb.set_label(label, fontsize=font_size)
if axis_off:
ax.set_axis_off()
ax.tick_params(labelsize=font_size)
# Set the background color to transparent.
if transparent_bg:
fig.patch.set_alpha(0.0)
super().__init__(layout=ipywidgets.Layout(width=max_width))
with self:
self.outputs = ()
matplotlib.pyplot.show()
def _get_dimensions(
self, orientation: str, kwargs: Dict[str, Any]
) -> Tuple[float, float]:
"""Get the dimensions of the colorbar based on orientation.
Args:
orientation (str): Orientation of the colorbar.
kwargs (Dict[str, Any]): Additional keyword arguments.
Returns:
Tuple[float, float]: Width and height of the colorbar.
Raises:
ValueError: If the orientation is not either horizontal or vertical.
"""
default_dims = {"horizontal": (3.0, 0.3), "vertical": (0.3, 3.0)}
if orientation in default_dims:
default = default_dims[orientation]
return (
kwargs.get("width", default[0]),
kwargs.get("height", default[1]),
)
raise ValueError(
f"orientation must be one of [{', '.join(default_dims.keys())}]."
)
__init__(self, vis_params=None, cmap='gray', discrete=False, label=None, orientation='horizontal', transparent_bg=False, font_size=9, axis_off=False, max_width=None, **kwargs)
special
¶
Add a matplotlib colorbar to the map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vis_params |
dict |
Visualization parameters as a dictionary. See https://developers.google.com/earth-engine/guides/image_visualization # noqa for options. |
None |
cmap |
str |
Matplotlib colormap. Defaults to "gray". See https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py # noqa for options. |
'gray' |
discrete |
bool |
Whether to create a discrete colorbar. Defaults to False. |
False |
label |
str |
Label for the colorbar. Defaults to None. |
None |
orientation |
str |
Orientation of the colorbar, such as "vertical" and "horizontal". Defaults to "horizontal". |
'horizontal' |
transparent_bg |
bool |
Whether to use transparent background. Defaults to False. |
False |
font_size |
int |
Font size for the colorbar. Defaults to 9. |
9 |
axis_off |
bool |
Whether to turn off the axis. Defaults to False. |
False |
max_width |
str |
Maximum width of the colorbar in pixels. Defaults to None. |
None |
Exceptions:
| Type | Description |
|---|---|
TypeError |
If the vis_params is not a dictionary. |
ValueError |
If the orientation is not either horizontal or vertical. |
ValueError |
If the provided min value is not convertible to float. |
ValueError |
If the provided max value is not convertible to float. |
ValueError |
If the provided opacity value is not convertible to float. |
ValueError |
If cmap or palette is not provided. |
Source code in geemap/map_widgets.py
def __init__(
self,
vis_params: Optional[Union[Dict[str, Any], list, tuple]] = None,
cmap: str = "gray",
discrete: bool = False,
label: Optional[str] = None,
orientation: str = "horizontal",
transparent_bg: bool = False,
font_size: int = 9,
axis_off: bool = False,
max_width: Optional[str] = None,
**kwargs: Any,
):
"""Add a matplotlib colorbar to the map.
Args:
vis_params (dict): Visualization parameters as a dictionary. See
https://developers.google.com/earth-engine/guides/image_visualization # noqa
for options.
cmap (str, optional): Matplotlib colormap. Defaults to "gray". See
https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py # noqa
for options.
discrete (bool, optional): Whether to create a discrete colorbar.
Defaults to False.
label (str, optional): Label for the colorbar. Defaults to None.
orientation (str, optional): Orientation of the colorbar, such as
"vertical" and "horizontal". Defaults to "horizontal".
transparent_bg (bool, optional): Whether to use transparent
background. Defaults to False.
font_size (int, optional): Font size for the colorbar. Defaults
to 9.
axis_off (bool, optional): Whether to turn off the axis. Defaults
to False.
max_width (str, optional): Maximum width of the colorbar in pixels.
Defaults to None.
Raises:
TypeError: If the vis_params is not a dictionary.
ValueError: If the orientation is not either horizontal or vertical.
ValueError: If the provided min value is not convertible to float.
ValueError: If the provided max value is not convertible to float.
ValueError: If the provided opacity value is not convertible to float.
ValueError: If cmap or palette is not provided.
"""
import matplotlib # pylint: disable=import-outside-toplevel
import numpy # pylint: disable=import-outside-toplevel
if max_width is None:
if orientation == "horizontal":
max_width = "270px"
else:
max_width = "100px"
if isinstance(vis_params, (list, tuple)):
vis_params = {"palette": list(vis_params)}
elif not vis_params:
vis_params = {}
if not isinstance(vis_params, dict):
raise TypeError("The vis_params must be a dictionary.")
if isinstance(kwargs.get("colors"), (list, tuple)):
vis_params["palette"] = list(kwargs["colors"])
width, height = self._get_dimensions(orientation, kwargs)
vmin = vis_params.get("min", kwargs.pop("vmin", 0))
try:
vmin = float(vmin)
except ValueError as err:
raise ValueError("The provided min value must be scalar type.")
vmax = vis_params.get("max", kwargs.pop("vmax", 1))
try:
vmax = float(vmax)
except ValueError as err:
raise ValueError("The provided max value must be scalar type.")
alpha = vis_params.get("opacity", kwargs.pop("alpha", 1))
try:
alpha = float(alpha)
except ValueError as err:
raise ValueError("opacity or alpha value must be scalar type.")
if "palette" in vis_params.keys():
hexcodes = coreutils.to_hex_colors(
coreutils.check_cmap(vis_params["palette"])
)
if discrete:
cmap = matplotlib.colors.ListedColormap(hexcodes)
linspace = numpy.linspace(vmin, vmax, cmap.N + 1)
norm = matplotlib.colors.BoundaryNorm(linspace, cmap.N)
else:
cmap = matplotlib.colors.LinearSegmentedColormap.from_list(
"custom", hexcodes, N=256
)
norm = matplotlib.colors.Normalize(vmin=vmin, vmax=vmax)
elif cmap:
cmap = matplotlib.pyplot.get_cmap(cmap)
norm = matplotlib.colors.Normalize(vmin=vmin, vmax=vmax)
else:
raise ValueError(
'cmap keyword or "palette" key in vis_params must be provided.'
)
fig, ax = matplotlib.pyplot.subplots(figsize=(width, height))
cb = matplotlib.colorbar.ColorbarBase(
ax,
norm=norm,
alpha=alpha,
cmap=cmap,
orientation=orientation,
**kwargs,
)
label = label or vis_params.get("bands") or kwargs.pop("caption", None)
if label:
cb.set_label(label, fontsize=font_size)
if axis_off:
ax.set_axis_off()
ax.tick_params(labelsize=font_size)
# Set the background color to transparent.
if transparent_bg:
fig.patch.set_alpha(0.0)
super().__init__(layout=ipywidgets.Layout(width=max_width))
with self:
self.outputs = ()
matplotlib.pyplot.show()
Inspector (VBox)
¶
Inspector widget for Earth Engine data.
Source code in geemap/map_widgets.py
@Theme.apply
class Inspector(ipywidgets.VBox):
"""Inspector widget for Earth Engine data."""
def __init__(
self,
host_map: "geemap.Map",
names: Optional[Union[str, List[str]]] = None,
visible: bool = True,
decimals: int = 2,
opened: bool = True,
show_close_button: bool = True,
):
"""Creates an Inspector widget for Earth Engine data.
Args:
host_map (geemap.Map): The map to add the inspector widget to.
names (list, optional): The list of layer names to be inspected.
Defaults to None.
visible (bool, optional): Whether to inspect visible layers only.
Defaults to True.
decimals (int, optional): The number of decimal places to round the
values. Defaults to 2.
opened (bool, optional): Whether the inspector is opened. Defaults
to True.
show_close_button (bool, optional): Whether to show the close
button. Defaults to True.
"""
self._host_map = host_map
if not host_map:
raise ValueError("Must pass a valid map when creating an inspector.")
self._names = names
self._visible = visible
self._decimals = decimals
self._opened = opened
self.on_close = None
self._expand_point_tree = False
self._expand_pixels_tree = True
self._expand_objects_tree = False
host_map.default_style = {"cursor": "crosshair"}
left_padded_square = ipywidgets.Layout(
width="28px", height="28px", padding="0px 0px 0px 4px"
)
self.toolbar_button = ipywidgets.ToggleButton(
value=opened, tooltip="Inspector", icon="info", layout=left_padded_square
)
self.toolbar_button.observe(self._on_toolbar_btn_click, "value")
close_button = ipywidgets.ToggleButton(
value=False,
tooltip="Close the tool",
icon="times",
button_style="primary",
layout=left_padded_square,
)
close_button.observe(self._on_close_btn_click, "value")
point_checkbox = self._create_checkbox("Point", self._expand_point_tree)
pixels_checkbox = self._create_checkbox("Pixels", self._expand_pixels_tree)
objects_checkbox = self._create_checkbox("Objects", self._expand_objects_tree)
point_checkbox.observe(self._on_point_checkbox_changed, "value")
pixels_checkbox.observe(self._on_pixels_checkbox_changed, "value")
objects_checkbox.observe(self._on_objects_checkbox_changed, "value")
self.inspector_checks = ipywidgets.HBox(
children=[
ipywidgets.Label(
"Expand", layout=ipywidgets.Layout(padding="0px 8px 0px 4px")
),
point_checkbox,
pixels_checkbox,
objects_checkbox,
]
)
if show_close_button:
self.toolbar_header = ipywidgets.HBox(
children=[close_button, self.toolbar_button]
)
else:
self.toolbar_header = ipywidgets.HBox(children=[self.toolbar_button])
self.tree_output = ipywidgets.VBox(
children=[],
layout=ipywidgets.Layout(
max_width="600px", max_height="300px", overflow="auto", display="block"
),
)
self._clear_inspector_output()
host_map.on_interaction(self._on_map_interaction)
self.toolbar_button.value = opened
super().__init__(
children=[self.toolbar_header, self.inspector_checks, self.tree_output]
)
def cleanup(self):
"""Removes the widget from the map and performs cleanup."""
if self._host_map:
self._host_map.default_style = {"cursor": "default"}
self._host_map.on_interaction(self._on_map_interaction, remove=True)
if self.on_close is not None:
self.on_close()
def _create_checkbox(self, title: str, checked: bool) -> ipywidgets.Checkbox:
"""Creates a checkbox widget.
Args:
title (str): The title of the checkbox.
checked (bool): Whether the checkbox is checked.
Returns:
ipywidgets.Checkbox: The created checkbox widget.
"""
layout = ipywidgets.Layout(width="auto", padding="0px 6px 0px 0px")
return ipywidgets.Checkbox(
description=title, indent=False, value=checked, layout=layout
)
def _on_map_interaction(self, **kwargs: Any) -> None:
"""Handles map interaction events.
Args:
**kwargs (Any): The interaction event arguments.
"""
latlon = kwargs.get("coordinates")
if kwargs.get("type") == "click":
self._on_map_click(latlon)
def _on_map_click(self, latlon: List[float]) -> None:
"""Handles map click events.
Args:
latlon (List[float]): The latitude and longitude of the click event.
"""
if self.toolbar_button.value:
self._host_map.default_style = {"cursor": "wait"}
self._clear_inspector_output()
nodes = [self._point_info(latlon)]
pixels_node = self._pixels_info(latlon)
if pixels_node.nodes:
nodes.append(pixels_node)
objects_node = self._objects_info(latlon)
if objects_node.nodes:
nodes.append(objects_node)
self.tree_output.children = [ipytree.Tree(nodes=nodes)]
self._host_map.default_style = {"cursor": "crosshair"}
def _clear_inspector_output(self) -> None:
"""Clears the inspector output."""
self.tree_output.children = []
self.children = []
self.children = [self.toolbar_header, self.inspector_checks, self.tree_output]
def _on_point_checkbox_changed(self, change: Dict[str, Any]) -> None:
"""Handles changes to the point checkbox.
Args:
change (Dict[str, Any]): The change event arguments.
"""
self._expand_point_tree = change["new"]
def _on_pixels_checkbox_changed(self, change: Dict[str, Any]) -> None:
"""Handles changes to the pixels checkbox.
Args:
change (Dict[str, Any]): The change event arguments.
"""
self._expand_pixels_tree = change["new"]
def _on_objects_checkbox_changed(self, change: Dict[str, Any]) -> None:
"""Handles changes to the objects checkbox.
Args:
change (Dict[str, Any]): The change event arguments.
"""
self._expand_objects_tree = change["new"]
def _on_toolbar_btn_click(self, change: Dict[str, Any]) -> None:
"""Handles toolbar button click events.
Args:
change (Dict[str, Any]): The change event arguments.
"""
if change["new"]:
self._host_map.default_style = {"cursor": "crosshair"}
self.children = [
self.toolbar_header,
self.inspector_checks,
self.tree_output,
]
self._clear_inspector_output()
else:
self.children = [self.toolbar_button]
self._host_map.default_style = {"cursor": "default"}
def _on_close_btn_click(self, change: Dict[str, Any]) -> None:
"""Handles close button click events.
Args:
change (Dict[str, Any]): The change event arguments.
"""
if change["new"]:
self.cleanup()
def _get_visible_map_layers(self) -> Dict[str, Any]:
"""Gets the visible map layers.
Returns:
Dict[str, Any]: A dictionary of visible map layers.
"""
layers = {}
if self._names is not None:
names = [names] if isinstance(names, str) else self._names
for name in names:
if name in self._host_map.ee_layers:
layers[name] = self._host_map.ee_layers[name]
else:
layers = self._host_map.ee_layers
return {k: v for k, v in layers.items() if v["ee_layer"].visible}
def _root_node(
self, title: str, nodes: List[ipytree.Node], **kwargs: Any
) -> ipytree.Node:
"""Creates a root node for the tree.
Args:
title (str): The title of the root node.
nodes (List[ipytree.Node]): The child nodes of the root node.
**kwargs (Any): Additional keyword arguments.
Returns:
ipytree.Node: The created root node.
"""
return ipytree.Node(
title,
icon="archive",
nodes=nodes,
open_icon="plus-square",
open_icon_style="success",
close_icon="minus-square",
close_icon_style="info",
**kwargs,
)
def _point_info(self, latlon: List[float]) -> ipytree.Node:
"""Gets information about a point.
Args:
latlon (List[float]): The latitude and longitude of the point.
Returns:
ipytree.Node: The node containing the point information.
"""
scale = self._host_map.get_scale()
label = (
f"Point ({latlon[1]:.{self._decimals}f}, "
+ f"{latlon[0]:.{self._decimals}f}) at {int(scale)}m/px"
)
nodes = [
ipytree.Node(f"Longitude: {latlon[1]}"),
ipytree.Node(f"Latitude: {latlon[0]}"),
ipytree.Node(f"Zoom Level: {self._host_map.zoom}"),
ipytree.Node(f"Scale (approx. m/px): {scale}"),
]
return self._root_node(label, nodes, opened=self._expand_point_tree)
def _query_point(
self, latlon: List[float], ee_object: ee.ComputedObject
) -> Optional[Dict[str, Any]]:
"""Queries a point on the map.
Args:
latlon (List[float]): The latitude and longitude of the point.
ee_object (ee.ComputedObject): The Earth Engine object to query.
Returns:
Optional[Dict[str, Any]]: The query result.
"""
point = ee.Geometry.Point(latlon[::-1])
scale = self._host_map.get_scale()
if isinstance(ee_object, ee.ImageCollection):
ee_object = ee_object.mosaic()
if isinstance(ee_object, ee.Image):
return ee_object.reduceRegion(ee.Reducer.first(), point, scale).getInfo()
return None
def _pixels_info(self, latlon: List[float]) -> ipytree.Node:
"""Gets information about pixels at a point.
Args:
latlon (List[float]): The latitude and longitude of the point.
Returns:
ipytree.Node: The node containing the pixels information.
"""
if not self._visible:
return self._root_node("Pixels", [])
layers = self._get_visible_map_layers()
nodes = []
for layer_name, layer in layers.items():
ee_object = layer["ee_object"]
pixel = self._query_point(latlon, ee_object)
if not pixel:
continue
pluralized_band = "band" if len(pixel) == 1 else "bands"
ee_obj_type = ee_object.__class__.__name__
label = f"{layer_name}: {ee_obj_type} ({len(pixel)} {pluralized_band})"
layer_node = ipytree.Node(label, opened=self._expand_pixels_tree)
for key, value in sorted(pixel.items()):
if isinstance(value, float):
value = round(value, self._decimals)
layer_node.add_node(ipytree.Node(f"{key}: {value}", icon="file"))
nodes.append(layer_node)
return self._root_node("Pixels", nodes)
def _get_bbox(self, latlon: List[float]) -> ee.Geometry.BBox:
"""Gets a bounding box around a point.
Args:
latlon (List[float]): The latitude and longitude of the point.
Returns:
ee.Geometry.BBox: The bounding box around the point.
"""
lat, lon = latlon
delta = 0.005
return ee.Geometry.BBox(lon - delta, lat - delta, lon + delta, lat + delta)
def _objects_info(self, latlon: List[float]) -> ipytree.Node:
"""Gets information about objects at a point.
Args:
latlon (List[float]): The latitude and longitude of the point.
Returns:
ipytree.Node: The node containing the objects information.
"""
if not self._visible:
return self._root_node("Objects", [])
layers = self._get_visible_map_layers()
point = ee.Geometry.Point(latlon[::-1])
nodes = []
for layer_name, layer in layers.items():
ee_object = layer["ee_object"]
if isinstance(ee_object, ee.FeatureCollection):
geom = ee.Feature(ee_object.first()).geometry()
bbox = self._get_bbox(latlon)
is_point = ee.Algorithms.If(
geom.type().compareTo(ee.String("Point")), point, bbox
)
ee_object = ee_object.filterBounds(is_point).first()
tree_node = coreutils.get_info(
ee_object, layer_name, self._expand_objects_tree, True
)
if tree_node:
nodes.append(tree_node)
return self._root_node("Objects", nodes)
__init__(self, host_map, names=None, visible=True, decimals=2, opened=True, show_close_button=True)
special
¶
Creates an Inspector widget for Earth Engine data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host_map |
geemap.Map |
The map to add the inspector widget to. |
required |
names |
list |
The list of layer names to be inspected. Defaults to None. |
None |
visible |
bool |
Whether to inspect visible layers only. Defaults to True. |
True |
decimals |
int |
The number of decimal places to round the values. Defaults to 2. |
2 |
opened |
bool |
Whether the inspector is opened. Defaults to True. |
True |
show_close_button |
bool |
Whether to show the close button. Defaults to True. |
True |
Source code in geemap/map_widgets.py
def __init__(
self,
host_map: "geemap.Map",
names: Optional[Union[str, List[str]]] = None,
visible: bool = True,
decimals: int = 2,
opened: bool = True,
show_close_button: bool = True,
):
"""Creates an Inspector widget for Earth Engine data.
Args:
host_map (geemap.Map): The map to add the inspector widget to.
names (list, optional): The list of layer names to be inspected.
Defaults to None.
visible (bool, optional): Whether to inspect visible layers only.
Defaults to True.
decimals (int, optional): The number of decimal places to round the
values. Defaults to 2.
opened (bool, optional): Whether the inspector is opened. Defaults
to True.
show_close_button (bool, optional): Whether to show the close
button. Defaults to True.
"""
self._host_map = host_map
if not host_map:
raise ValueError("Must pass a valid map when creating an inspector.")
self._names = names
self._visible = visible
self._decimals = decimals
self._opened = opened
self.on_close = None
self._expand_point_tree = False
self._expand_pixels_tree = True
self._expand_objects_tree = False
host_map.default_style = {"cursor": "crosshair"}
left_padded_square = ipywidgets.Layout(
width="28px", height="28px", padding="0px 0px 0px 4px"
)
self.toolbar_button = ipywidgets.ToggleButton(
value=opened, tooltip="Inspector", icon="info", layout=left_padded_square
)
self.toolbar_button.observe(self._on_toolbar_btn_click, "value")
close_button = ipywidgets.ToggleButton(
value=False,
tooltip="Close the tool",
icon="times",
button_style="primary",
layout=left_padded_square,
)
close_button.observe(self._on_close_btn_click, "value")
point_checkbox = self._create_checkbox("Point", self._expand_point_tree)
pixels_checkbox = self._create_checkbox("Pixels", self._expand_pixels_tree)
objects_checkbox = self._create_checkbox("Objects", self._expand_objects_tree)
point_checkbox.observe(self._on_point_checkbox_changed, "value")
pixels_checkbox.observe(self._on_pixels_checkbox_changed, "value")
objects_checkbox.observe(self._on_objects_checkbox_changed, "value")
self.inspector_checks = ipywidgets.HBox(
children=[
ipywidgets.Label(
"Expand", layout=ipywidgets.Layout(padding="0px 8px 0px 4px")
),
point_checkbox,
pixels_checkbox,
objects_checkbox,
]
)
if show_close_button:
self.toolbar_header = ipywidgets.HBox(
children=[close_button, self.toolbar_button]
)
else:
self.toolbar_header = ipywidgets.HBox(children=[self.toolbar_button])
self.tree_output = ipywidgets.VBox(
children=[],
layout=ipywidgets.Layout(
max_width="600px", max_height="300px", overflow="auto", display="block"
),
)
self._clear_inspector_output()
host_map.on_interaction(self._on_map_interaction)
self.toolbar_button.value = opened
super().__init__(
children=[self.toolbar_header, self.inspector_checks, self.tree_output]
)
cleanup(self)
¶
Removes the widget from the map and performs cleanup.
Source code in geemap/map_widgets.py
def cleanup(self):
"""Removes the widget from the map and performs cleanup."""
if self._host_map:
self._host_map.default_style = {"cursor": "default"}
self._host_map.on_interaction(self._on_map_interaction, remove=True)
if self.on_close is not None:
self.on_close()
LayerEditor (VBox)
¶
Widget for displaying and editing layer visualization properties.
Source code in geemap/map_widgets.py
@Theme.apply
class LayerEditor(ipywidgets.VBox):
"""Widget for displaying and editing layer visualization properties."""
def __init__(self, host_map: "geemap.Map", layer_dict: Optional[Dict[str, Any]]):
"""Initializes a layer editor widget.
Args:
host_map (geemap.Map): The geemap.Map object.
layer_dict (Optional[Dict[str, Any]]): The layer object to edit.
"""
self.on_close = None
self._host_map = host_map
if not host_map:
raise ValueError(
f"Must pass a valid map when creating a {self.__class__.__name__} widget."
)
self._toggle_button = ipywidgets.ToggleButton(
value=True,
tooltip="Layer editor",
icon="gear",
layout=ipywidgets.Layout(
width="28px", height="28px", padding="0px 0 0 3px"
),
)
self._toggle_button.observe(self._on_toggle_click, "value")
self._close_button = ipywidgets.Button(
tooltip="Close the vis params dialog",
icon="times",
button_style="primary",
layout=ipywidgets.Layout(width="28px", height="28px", padding="0"),
)
self._close_button.on_click(self._on_close_click)
layout = ipywidgets.Layout(width="95px")
self._import_button = ipywidgets.Button(
description="Import",
button_style="primary",
tooltip="Import vis params to notebook",
layout=layout,
)
self._apply_button = ipywidgets.Button(
description="Apply", tooltip="Apply vis params to the layer", layout=layout
)
self._import_button.on_click(self._on_import_click)
self._apply_button.on_click(self._on_apply_click)
self._label = ipywidgets.Label(
value="Layer name",
layout=ipywidgets.Layout(max_width="250px", padding="1px 8px 0 4px"),
)
self._embedded_widget = ipywidgets.Label(value="Vis params are uneditable")
if layer_dict is not None:
self._ee_object = layer_dict["ee_object"]
if isinstance(self._ee_object, (ee.Feature, ee.Geometry)):
self._ee_object = ee.FeatureCollection(self._ee_object)
self._ee_layer = layer_dict["ee_layer"]
self._label.value = self._ee_layer.name
if isinstance(self._ee_object, ee.FeatureCollection):
self._embedded_widget = _VectorLayerEditor(
host_map=host_map, layer_dict=layer_dict
)
elif isinstance(self._ee_object, ee.Image):
self._embedded_widget = _RasterLayerEditor(
host_map=host_map, layer_dict=layer_dict
)
super().__init__(children=[])
self._on_toggle_click({"new": True})
def _on_toggle_click(self, change: Dict[str, Any]) -> None:
"""Handles the toggle button click event.
Args:
change (Dict[str, Any]): The change event arguments.
"""
if change["new"]:
self.children = [
ipywidgets.HBox([self._close_button, self._toggle_button, self._label]),
self._embedded_widget,
ipywidgets.HBox([self._import_button, self._apply_button]),
]
else:
self.children = [
ipywidgets.HBox([self._close_button, self._toggle_button, self._label]),
]
def _on_import_click(self, _) -> None:
"""Handles the import button click event."""
self._embedded_widget.on_import_click()
def _on_apply_click(self, _) -> None:
"""Handles the apply button click event."""
self._embedded_widget.on_apply_click()
def _on_close_click(self, _) -> None:
"""Handles the close button click event."""
if self.on_close:
self.on_close()
__init__(self, host_map, layer_dict)
special
¶
Initializes a layer editor widget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host_map |
geemap.Map |
The geemap.Map object. |
required |
layer_dict |
Optional[Dict[str, Any]] |
The layer object to edit. |
required |
Source code in geemap/map_widgets.py
def __init__(self, host_map: "geemap.Map", layer_dict: Optional[Dict[str, Any]]):
"""Initializes a layer editor widget.
Args:
host_map (geemap.Map): The geemap.Map object.
layer_dict (Optional[Dict[str, Any]]): The layer object to edit.
"""
self.on_close = None
self._host_map = host_map
if not host_map:
raise ValueError(
f"Must pass a valid map when creating a {self.__class__.__name__} widget."
)
self._toggle_button = ipywidgets.ToggleButton(
value=True,
tooltip="Layer editor",
icon="gear",
layout=ipywidgets.Layout(
width="28px", height="28px", padding="0px 0 0 3px"
),
)
self._toggle_button.observe(self._on_toggle_click, "value")
self._close_button = ipywidgets.Button(
tooltip="Close the vis params dialog",
icon="times",
button_style="primary",
layout=ipywidgets.Layout(width="28px", height="28px", padding="0"),
)
self._close_button.on_click(self._on_close_click)
layout = ipywidgets.Layout(width="95px")
self._import_button = ipywidgets.Button(
description="Import",
button_style="primary",
tooltip="Import vis params to notebook",
layout=layout,
)
self._apply_button = ipywidgets.Button(
description="Apply", tooltip="Apply vis params to the layer", layout=layout
)
self._import_button.on_click(self._on_import_click)
self._apply_button.on_click(self._on_apply_click)
self._label = ipywidgets.Label(
value="Layer name",
layout=ipywidgets.Layout(max_width="250px", padding="1px 8px 0 4px"),
)
self._embedded_widget = ipywidgets.Label(value="Vis params are uneditable")
if layer_dict is not None:
self._ee_object = layer_dict["ee_object"]
if isinstance(self._ee_object, (ee.Feature, ee.Geometry)):
self._ee_object = ee.FeatureCollection(self._ee_object)
self._ee_layer = layer_dict["ee_layer"]
self._label.value = self._ee_layer.name
if isinstance(self._ee_object, ee.FeatureCollection):
self._embedded_widget = _VectorLayerEditor(
host_map=host_map, layer_dict=layer_dict
)
elif isinstance(self._ee_object, ee.Image):
self._embedded_widget = _RasterLayerEditor(
host_map=host_map, layer_dict=layer_dict
)
super().__init__(children=[])
self._on_toggle_click({"new": True})
LayerManager (VBox)
¶
A layer manager widget for managing map layers.
Source code in geemap/map_widgets.py
@Theme.apply
class LayerManager(ipywidgets.VBox):
"""A layer manager widget for managing map layers."""
def __init__(self, host_map: "geemap.Map"):
"""Initializes a layer manager widget.
Args:
host_map (geemap.Map): The geemap.Map object.
"""
self._host_map = host_map
if not host_map:
raise ValueError("Must pass a valid map when creating a layer manager.")
self._collapse_button = ipywidgets.ToggleButton(
value=False,
tooltip="Layer Manager",
icon="server",
layout=ipywidgets.Layout(
width="28px", height="28px", padding="0px 0px 0px 4px"
),
)
self._close_button = ipywidgets.Button(
tooltip="Close the tool",
icon="times",
button_style="primary",
layout=ipywidgets.Layout(width="28px", height="28px", padding="0px"),
)
self._toolbar_header = ipywidgets.HBox(
children=[self._close_button, self._collapse_button]
)
self._toolbar_footer = ipywidgets.VBox(children=[])
self._collapse_button.observe(self._on_collapse_click, "value")
self._close_button.on_click(self._on_close_click)
self.on_close = None
self.on_open_vis = None
self.collapsed = False
self.header_hidden = False
self.close_button_hidden = False
super().__init__([self._toolbar_header, self._toolbar_footer])
@property
def collapsed(self) -> bool:
"""bool: Whether the layer manager is collapsed."""
return not self._collapse_button.value
@collapsed.setter
def collapsed(self, value: bool) -> None:
self._collapse_button.value = not value
@property
def header_hidden(self) -> bool:
"""bool: Whether the header is hidden."""
return self._toolbar_header.layout.display == "none"
@header_hidden.setter
def header_hidden(self, value: bool) -> None:
self._toolbar_header.layout.display = "none" if value else "block"
@property
def close_button_hidden(self) -> bool:
"""bool: Whether the close button is hidden."""
return self._close_button.style.display == "none"
@close_button_hidden.setter
def close_button_hidden(self, value: bool) -> None:
self._close_button.style.display = "none" if value else "inline-block"
def refresh_layers(self) -> None:
"""Recreates all the layer widgets."""
toggle_all_layout = ipywidgets.Layout(
height="18px", width="30ex", padding="0px 4px 25px 4px"
)
toggle_all_checkbox = ipywidgets.Checkbox(
value=False,
description="All layers on/off",
indent=False,
layout=toggle_all_layout,
)
toggle_all_checkbox.observe(self._on_all_layers_visibility_toggled, "value")
layer_rows = []
# non_basemap_layers = self._host_map.layers[1:] # Skip the basemap.
for layer in self._host_map.layers:
layer_rows.append(self._render_layer_row(layer))
self._toolbar_footer.children = [toggle_all_checkbox] + layer_rows
def _on_close_click(self, _) -> None:
"""Handles the close button click event."""
if self.on_close:
self.on_close()
def _on_collapse_click(self, change: Dict[str, Any]) -> None:
"""Handles the collapse button click event.
Args:
change (Dict[str, Any]): The change event arguments.
"""
if change["new"]:
self.refresh_layers()
self.children = [self._toolbar_header, self._toolbar_footer]
else:
self.children = [self._collapse_button]
def _render_layer_row(self, layer: Any) -> ipywidgets.HBox:
"""Renders a row for a layer.
Args:
layer (Any): The layer to render.
Returns:
ipywidgets.HBox: The rendered layer row.
"""
visibility_checkbox = ipywidgets.Checkbox(
value=self._compute_layer_visibility(layer),
description=layer.name,
indent=False,
layout=ipywidgets.Layout(height="18px", width="140px"),
)
visibility_checkbox.observe(
lambda change: self._on_layer_visibility_changed(change, layer), "value"
)
opacity_slider = ipywidgets.FloatSlider(
value=self._compute_layer_opacity(layer),
min=0,
max=1,
step=0.01,
readout=False,
layout=ipywidgets.Layout(width="70px", padding="0px 3px 0px 0px"),
)
opacity_slider.observe(
lambda change: self._on_layer_opacity_changed(change, layer), "value"
)
settings_button = ipywidgets.Button(
icon="gear",
layout=ipywidgets.Layout(width="25px", height="25px", padding="0px"),
tooltip=layer.name,
)
settings_button.on_click(self._on_layer_settings_click)
spinner = ipywidgets.Button(
icon="times",
layout=ipywidgets.Layout(width="25px", height="25px", padding="0px"),
tooltip="Loaded",
)
def loading_change(change):
if change["new"]:
spinner.tooltip = "Loading ..."
spinner.icon = "spinner spin lg"
else:
spinner.tooltip = "Loaded"
spinner.icon = "times"
layer.observe(loading_change, "loading")
spinner_event = ipyevents.Event(
source=spinner, watched_events=["mouseenter", "mouseleave"]
)
def handle_spinner_event(event):
if event["type"] == "mouseenter":
spinner.icon = "times"
elif event["type"] == "mouseleave":
if hasattr(layer, "loading") and layer.loading:
spinner.icon = "spinner spin lg"
else:
spinner.icon = "times"
spinner_event.on_dom_event(handle_spinner_event)
def remove_layer_click(_):
self._on_layer_remove_click(layer)
spinner.on_click(remove_layer_click)
return ipywidgets.HBox(
[
visibility_checkbox,
opacity_slider,
settings_button,
spinner,
],
layout=ipywidgets.Layout(padding="0px 4px 0px 4px"),
)
def _find_layer_row_index(self, layer: Any) -> int:
"""Finds the index of a layer row.
Args:
layer (Any): The layer to find.
Returns:
int: The index of the layer row.
"""
for index, child in enumerate(self._toolbar_footer.children[1:]):
if child.children[0].description == layer.name:
return index + 1
return -1
def _remove_confirm_widget(self) -> None:
"""Removes the confirm widget."""
for index, child in enumerate(self._toolbar_footer.children[1:]):
if child.children[0].value == "Remove layer?":
self._toolbar_footer.children = (
self._toolbar_footer.children[: index + 1]
+ self._toolbar_footer.children[index + 2 :]
)
break
def _on_layer_remove_click(self, layer: Any) -> None:
"""Handles the layer remove click event.
Args:
layer (Any): The layer to remove.
"""
self._remove_confirm_widget()
label = ipywidgets.Label(
"Remove layer?",
layout=ipywidgets.Layout(padding="0px 4px 0px 4px"),
)
yes_button = ipywidgets.Button(
description="Yes",
button_style="primary",
)
yes_button.layout.width = "86px"
no_button = ipywidgets.Button(
description="No",
button_style="primary",
)
no_button.layout.width = "86px"
confirm_widget = ipywidgets.HBox(
[label, yes_button, no_button], layout=ipywidgets.Layout(width="284px")
)
layer_row_index = self._find_layer_row_index(layer)
self._toolbar_footer.children = (
list(self._toolbar_footer.children[: layer_row_index + 1])
+ [confirm_widget]
+ list(self._toolbar_footer.children[layer_row_index + 1 :])
)
def on_yes_button_click(_):
self._host_map.remove_layer(layer)
self._remove_confirm_widget()
yes_button.on_click(on_yes_button_click)
def on_no_button_click(_):
self._remove_confirm_widget()
no_button.on_click(on_no_button_click)
def _compute_layer_opacity(self, layer: Any) -> float:
"""Computes the opacity of a layer.
Args:
layer (Any): The layer to compute the opacity for.
Returns:
float: The opacity of the layer.
"""
if layer in self._host_map.geojson_layers:
opacity = layer.style.get("opacity", 1.0)
fill_opacity = layer.style.get("fillOpacity", 1.0)
return max(opacity, fill_opacity)
return layer.opacity if hasattr(layer, "opacity") else 1.0
def _compute_layer_visibility(self, layer: Any) -> bool:
"""Computes the visibility of a layer.
Args:
layer (Any): The layer to compute the visibility for.
Returns:
bool: The visibility of the layer.
"""
return layer.visible if hasattr(layer, "visible") else True
def _on_layer_settings_click(self, button: ipywidgets.Button) -> None:
"""Handles the layer settings click event.
Args:
button (ipywidgets.Button): The button that was clicked.
"""
if self.on_open_vis:
self.on_open_vis(button.tooltip)
def _on_all_layers_visibility_toggled(self, change: Dict[str, Any]) -> None:
"""Handles the all layers visibility toggled event.
Args:
change (Dict[str, Any]): The change event arguments.
"""
checkboxes = [
row.children[0] for row in self._toolbar_footer.children[1:]
] # Skip the all on/off checkbox.
for checkbox in checkboxes:
checkbox.value = change["new"]
def _on_layer_opacity_changed(self, change: Dict[str, Any], layer: Any) -> None:
"""Handles the layer opacity changed event.
Args:
change (Dict[str, Any]): The change event arguments.
layer (Any): The layer to change the opacity for.
"""
if layer in self._host_map.geojson_layers:
# For non-TileLayer, use layer.style.opacity and layer.style.fillOpacity.
layer.style.update({"opacity": change["new"], "fillOpacity": change["new"]})
elif hasattr(layer, "opacity"):
layer.opacity = change["new"]
def _on_layer_visibility_changed(self, change: Dict[str, Any], layer: Any) -> None:
"""Handles the layer visibility changed event.
Args:
change (Dict[str, Any]): The change event arguments.
layer (Any): The layer to change the visibility for.
"""
if hasattr(layer, "visible"):
layer.visible = change["new"]
layer_name = change["owner"].description
if layer_name not in self._host_map.ee_layers:
return
layer_dict = self._host_map.ee_layers[layer_name]
for attachment_name in ["legend", "colorbar"]:
attachment = layer_dict.get(attachment_name, None)
attachment_on_map = attachment in self._host_map.controls
if change["new"] and not attachment_on_map:
try:
self._host_map.add(attachment)
except:
from ipyleaflet import WidgetControl
widget = attachment.widget
position = attachment.position
control = WidgetControl(widget=widget, position=position)
self._host_map.add(control)
layer_dict["colorbar"] = control
elif not change["new"] and attachment_on_map:
self._host_map.remove_control(attachment)
close_button_hidden: bool
property
writable
¶
collapsed: bool
property
writable
¶
header_hidden: bool
property
writable
¶
__init__(self, host_map)
special
¶
Initializes a layer manager widget.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host_map |
geemap.Map |
The geemap.Map object. |
required |
Source code in geemap/map_widgets.py
def __init__(self, host_map: "geemap.Map"):
"""Initializes a layer manager widget.
Args:
host_map (geemap.Map): The geemap.Map object.
"""
self._host_map = host_map
if not host_map:
raise ValueError("Must pass a valid map when creating a layer manager.")
self._collapse_button = ipywidgets.ToggleButton(
value=False,
tooltip="Layer Manager",
icon="server",
layout=ipywidgets.Layout(
width="28px", height="28px", padding="0px 0px 0px 4px"
),
)
self._close_button = ipywidgets.Button(
tooltip="Close the tool",
icon="times",
button_style="primary",
layout=ipywidgets.Layout(width="28px", height="28px", padding="0px"),
)
self._toolbar_header = ipywidgets.HBox(
children=[self._close_button, self._collapse_button]
)
self._toolbar_footer = ipywidgets.VBox(children=[])
self._collapse_button.observe(self._on_collapse_click, "value")
self._close_button.on_click(self._on_close_click)
self.on_close = None
self.on_open_vis = None
self.collapsed = False
self.header_hidden = False
self.close_button_hidden = False
super().__init__([self._toolbar_header, self._toolbar_footer])
refresh_layers(self)
¶
Recreates all the layer widgets.
Source code in geemap/map_widgets.py
def refresh_layers(self) -> None:
"""Recreates all the layer widgets."""
toggle_all_layout = ipywidgets.Layout(
height="18px", width="30ex", padding="0px 4px 25px 4px"
)
toggle_all_checkbox = ipywidgets.Checkbox(
value=False,
description="All layers on/off",
indent=False,
layout=toggle_all_layout,
)
toggle_all_checkbox.observe(self._on_all_layers_visibility_toggled, "value")
layer_rows = []
# non_basemap_layers = self._host_map.layers[1:] # Skip the basemap.
for layer in self._host_map.layers:
layer_rows.append(self._render_layer_row(layer))
self._toolbar_footer.children = [toggle_all_checkbox] + layer_rows
Legend (VBox)
¶
A legend widget that can be added to the map.
Source code in geemap/map_widgets.py
@Theme.apply
class Legend(ipywidgets.VBox):
"""A legend widget that can be added to the map."""
ALLOWED_POSITIONS = ["topleft", "topright", "bottomleft", "bottomright"]
DEFAULT_COLORS = ["#8DD3C7", "#FFFFB3", "#BEBADA", "#FB8072", "#80B1D3"]
DEFAULT_KEYS = ["One", "Two", "Three", "Four", "etc"]
DEFAULT_MAX_HEIGHT = "400px"
DEFAULT_MAX_WIDTH = "300px"
def __init__(
self,
title: str = "Legend",
legend_dict: Optional[Dict[str, str]] = None,
keys: Optional[List[str]] = None,
colors: Optional[List[Union[str, tuple]]] = None,
position: str = "bottomright",
builtin_legend: Optional[str] = None,
add_header: bool = True,
widget_args: Optional[Dict[str, Any]] = None,
**kwargs: Any,
):
"""Adds a customized legend to the map.
Args:
title (str, optional): Title of the legend. Defaults to 'Legend'.
legend_dict (dict, optional): A dictionary containing legend items
as keys and color as values. If provided, keys and colors will
be ignored. Defaults to None.
keys (list, optional): A list of legend keys. Defaults to None.
colors (list, optional): A list of legend colors. Defaults to None.
position (str, optional): Position of the legend. Defaults to
'bottomright'.
builtin_legend (str, optional): Name of the builtin legend to add
to the map. Defaults to None.
add_header (bool, optional): Whether the legend can be closed or
not. Defaults to True.
widget_args (dict, optional): Additional arguments passed to the
widget_template() function. Defaults to {}.
Raises:
TypeError: If the keys are not a list.
TypeError: If the colors are not list.
TypeError: If the colors are not a list of tuples.
ValueError: If the legend template does not exist.
ValueError: If a rgb value cannot to be converted to hex.
ValueError: If the keys and colors are not the same length.
ValueError: If the builtin_legend is not allowed.
ValueError: If the position is not allowed.
"""
import os # pylint: disable=import-outside-toplevel
import pkg_resources # pylint: disable=import-outside-toplevel
from .legends import builtin_legends # pylint: disable=import-outside-toplevel
if not widget_args:
widget_args = {}
pkg_dir = os.path.dirname(
pkg_resources.resource_filename("geemap", "geemap.py")
)
legend_template = os.path.join(pkg_dir, "data/template/legend.html")
if not os.path.exists(legend_template):
raise ValueError("The legend template does not exist.")
if legend_dict is not None:
if not isinstance(legend_dict, dict):
raise TypeError("The legend dict must be a dictionary.")
else:
keys = list(legend_dict.keys())
colors = list(legend_dict.values())
if all(isinstance(item, tuple) for item in colors):
colors = Legend.__convert_rgb_colors_to_hex(colors)
if "labels" in kwargs:
keys = kwargs["labels"]
kwargs.pop("labels")
if keys is not None:
if not isinstance(keys, list):
raise TypeError("The legend keys must be a list.")
else:
keys = Legend.DEFAULT_KEYS
if colors is not None:
if not isinstance(colors, list):
raise TypeError("The legend colors must be a list.")
elif all(isinstance(item, tuple) for item in colors):
colors = Legend.__convert_rgb_colors_to_hex(colors)
elif all((item.startswith("#") and len(item) == 7) for item in colors):
pass
elif all((len(item) == 6) for item in colors):
pass
else:
raise TypeError("The legend colors must be a list of tuples.")
else:
colors = Legend.DEFAULT_COLORS
if len(keys) != len(colors):
raise ValueError("The legend keys and colors must be the same length.")
allowed_builtin_legends = builtin_legends.keys()
if builtin_legend is not None:
builtin_legend_allowed = Legend.__check_if_allowed(
builtin_legend, "builtin legend", allowed_builtin_legends
)
if builtin_legend_allowed:
legend_dict = builtin_legends[builtin_legend]
keys = list(legend_dict.keys())
colors = list(legend_dict.values())
if all(isinstance(item, tuple) for item in colors):
colors = Legend.__convert_rgb_colors_to_hex(colors)
Legend.__check_if_allowed(position, "position", Legend.ALLOWED_POSITIONS)
header = []
footer = []
content = Legend.__create_legend_items(keys, colors)
with open(legend_template) as f:
lines = f.readlines()
lines[3] = lines[3].replace("Legend", title)
header = lines[:6]
footer = lines[11:]
legend_html = header + content + footer
legend_text = "".join(legend_html)
legend_output = ipywidgets.Output(layout=Legend.__create_layout(**kwargs))
legend_widget = ipywidgets.HTML(value=legend_text)
if add_header:
if "show_close_button" not in widget_args:
widget_args["show_close_button"] = False
if "widget_icon" not in widget_args:
widget_args["widget_icon"] = "bars"
legend_output_widget = coreutils.widget_template(
legend_output,
position=position,
display_widget=legend_widget,
**widget_args,
)
else:
legend_output_widget = legend_widget
super().__init__(children=[legend_output_widget])
legend_output.clear_output()
with legend_output:
display(legend_widget)
def __check_if_allowed(
value: str, value_name: str, allowed_list: List[str]
) -> bool:
"""Checks if a value is allowed.
Args:
value (str): The value to check.
value_name (str): The name of the value.
allowed_list (List[str]): The list of allowed values.
Returns:
bool: True if the value is allowed, otherwise raises a ValueError.
Raises:
ValueError: If the value is not allowed.
"""
if value not in allowed_list:
raise ValueError(
"The "
+ value_name
+ " must be one of the following: {}.".format(", ".join(allowed_list))
)
return True
def __convert_rgb_colors_to_hex(colors: List[tuple]) -> List[str]:
"""Converts a list of RGB colors to hex.
Args:
colors (List[tuple]): A list of RGB color tuples.
Returns:
List[str]: A list of hex color strings.
Raises:
ValueError: If unable to convert an RGB value to hex.
"""
try:
return [coreutils.rgb_to_hex(x) for x in colors]
except:
raise ValueError("Unable to convert rgb value to hex.")
def __create_legend_items(keys: List[str], colors: List[str]) -> List[str]:
"""Creates HTML legend items.
Args:
keys (List[str]): A list of legend keys.
colors (List[str]): A list of legend colors.
Returns:
List[str]: A list of HTML strings for the legend items.
"""
legend_items = []
for index, key in enumerate(keys):
color = colors[index]
if not color.startswith("#"):
color = "#" + color
item = "<li><span style='background:{};'></span>{}</li>\n".format(
color, key
)
legend_items.append(item)
return legend_items
def __create_layout(**kwargs: Any) -> Dict[str, Optional[str]]:
"""Creates the layout for the legend.
Args:
**kwargs (Any): Additional keyword arguments for layout properties.
Returns:
Dict[str, Optional[str]]: A dictionary of layout properties.
"""
height = Legend.__create_layout_property("height", None, **kwargs)
min_height = Legend.__create_layout_property("min_height", None, **kwargs)
if height is None:
max_height = Legend.DEFAULT_MAX_HEIGHT
else:
max_height = Legend.__create_layout_property("max_height", None, **kwargs)
width = Legend.__create_layout_property("width", None, **kwargs)
if "min_width" not in kwargs:
min_width = None
if width is None:
max_width = Legend.DEFAULT_MAX_WIDTH
else:
max_width = Legend.__create_layout_property(
"max_width", Legend.DEFAULT_MAX_WIDTH, **kwargs
)
return {
"height": height,
"max_height": max_height,
"max_width": max_width,
"min_height": min_height,
"min_width": min_width,
"overflow": "scroll",
"width": width,
}
def __create_layout_property(name, default_value, **kwargs):
return default_value if name not in kwargs else kwargs[name]
__init__(self, title='Legend', legend_dict=None, keys=None, colors=None, position='bottomright', builtin_legend=None, add_header=True, widget_args=None, **kwargs)
special
¶
Adds a customized legend to the map.
Args: title (str, optional): Title of the legend. Defaults to 'Legend'. legend_dict (dict, optional): A dictionary containing legend items as keys and color as values. If provided, keys and colors will be ignored. Defaults to None. keys (list, optional): A list of legend keys. Defaults to None. colors (list, optional): A list of legend colors. Defaults to None. position (str, optional): Position of the legend. Defaults to 'bottomright'. builtin_legend (str, optional): Name of the builtin legend to add to the map. Defaults to None. add_header (bool, optional): Whether the legend can be closed or not. Defaults to True. widget_args (dict, optional): Additional arguments passed to the widget_template() function. Defaults to {}.
Exceptions:
| Type | Description |
|---|---|
TypeError |
If the keys are not a list. |
TypeError |
If the colors are not list. |
TypeError |
If the colors are not a list of tuples. |
ValueError |
If the legend template does not exist. |
ValueError |
If a rgb value cannot to be converted to hex. |
ValueError |
If the keys and colors are not the same length. |
ValueError |
If the builtin_legend is not allowed. |
ValueError |
If the position is not allowed. |
Source code in geemap/map_widgets.py
def __init__(
self,
title: str = "Legend",
legend_dict: Optional[Dict[str, str]] = None,
keys: Optional[List[str]] = None,
colors: Optional[List[Union[str, tuple]]] = None,
position: str = "bottomright",
builtin_legend: Optional[str] = None,
add_header: bool = True,
widget_args: Optional[Dict[str, Any]] = None,
**kwargs: Any,
):
"""Adds a customized legend to the map.
Args:
title (str, optional): Title of the legend. Defaults to 'Legend'.
legend_dict (dict, optional): A dictionary containing legend items
as keys and color as values. If provided, keys and colors will
be ignored. Defaults to None.
keys (list, optional): A list of legend keys. Defaults to None.
colors (list, optional): A list of legend colors. Defaults to None.
position (str, optional): Position of the legend. Defaults to
'bottomright'.
builtin_legend (str, optional): Name of the builtin legend to add
to the map. Defaults to None.
add_header (bool, optional): Whether the legend can be closed or
not. Defaults to True.
widget_args (dict, optional): Additional arguments passed to the
widget_template() function. Defaults to {}.
Raises:
TypeError: If the keys are not a list.
TypeError: If the colors are not list.
TypeError: If the colors are not a list of tuples.
ValueError: If the legend template does not exist.
ValueError: If a rgb value cannot to be converted to hex.
ValueError: If the keys and colors are not the same length.
ValueError: If the builtin_legend is not allowed.
ValueError: If the position is not allowed.
"""
import os # pylint: disable=import-outside-toplevel
import pkg_resources # pylint: disable=import-outside-toplevel
from .legends import builtin_legends # pylint: disable=import-outside-toplevel
if not widget_args:
widget_args = {}
pkg_dir = os.path.dirname(
pkg_resources.resource_filename("geemap", "geemap.py")
)
legend_template = os.path.join(pkg_dir, "data/template/legend.html")
if not os.path.exists(legend_template):
raise ValueError("The legend template does not exist.")
if legend_dict is not None:
if not isinstance(legend_dict, dict):
raise TypeError("The legend dict must be a dictionary.")
else:
keys = list(legend_dict.keys())
colors = list(legend_dict.values())
if all(isinstance(item, tuple) for item in colors):
colors = Legend.__convert_rgb_colors_to_hex(colors)
if "labels" in kwargs:
keys = kwargs["labels"]
kwargs.pop("labels")
if keys is not None:
if not isinstance(keys, list):
raise TypeError("The legend keys must be a list.")
else:
keys = Legend.DEFAULT_KEYS
if colors is not None:
if not isinstance(colors, list):
raise TypeError("The legend colors must be a list.")
elif all(isinstance(item, tuple) for item in colors):
colors = Legend.__convert_rgb_colors_to_hex(colors)
elif all((item.startswith("#") and len(item) == 7) for item in colors):
pass
elif all((len(item) == 6) for item in colors):
pass
else:
raise TypeError("The legend colors must be a list of tuples.")
else:
colors = Legend.DEFAULT_COLORS
if len(keys) != len(colors):
raise ValueError("The legend keys and colors must be the same length.")
allowed_builtin_legends = builtin_legends.keys()
if builtin_legend is not None:
builtin_legend_allowed = Legend.__check_if_allowed(
builtin_legend, "builtin legend", allowed_builtin_legends
)
if builtin_legend_allowed:
legend_dict = builtin_legends[builtin_legend]
keys = list(legend_dict.keys())
colors = list(legend_dict.values())
if all(isinstance(item, tuple) for item in colors):
colors = Legend.__convert_rgb_colors_to_hex(colors)
Legend.__check_if_allowed(position, "position", Legend.ALLOWED_POSITIONS)
header = []
footer = []
content = Legend.__create_legend_items(keys, colors)
with open(legend_template) as f:
lines = f.readlines()
lines[3] = lines[3].replace("Legend", title)
header = lines[:6]
footer = lines[11:]
legend_html = header + content + footer
legend_text = "".join(legend_html)
legend_output = ipywidgets.Output(layout=Legend.__create_layout(**kwargs))
legend_widget = ipywidgets.HTML(value=legend_text)
if add_header:
if "show_close_button" not in widget_args:
widget_args["show_close_button"] = False
if "widget_icon" not in widget_args:
widget_args["widget_icon"] = "bars"
legend_output_widget = coreutils.widget_template(
legend_output,
position=position,
display_widget=legend_widget,
**widget_args,
)
else:
legend_output_widget = legend_widget
super().__init__(children=[legend_output_widget])
legend_output.clear_output()
with legend_output:
display(legend_widget)
Theme
¶
Applies dynamic theme in Colab, otherwise light.
Source code in geemap/map_widgets.py
class Theme:
"""Applies dynamic theme in Colab, otherwise light."""
current_theme = "colab" if coreutils.in_colab_shell() else "light"
@staticmethod
def apply(cls: Any) -> Any:
"""Applies the theme to the given class.
Args:
cls (Any): The class to which the theme will be applied.
Returns:
Any: The class with the applied theme.
"""
original_init = cls.__init__
@functools.wraps(cls.__init__)
def wrapper(self, *args, **kwargs):
original_init(self, *args, **kwargs)
self.add_class("geemap-{}".format(Theme.current_theme))
cls.__init__ = wrapper
return cls
apply(cls)
staticmethod
¶
Applies the theme to the given class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cls |
Any |
The class to which the theme will be applied. |
required |
Returns:
| Type | Description |
|---|---|
Any |
The class with the applied theme. |
Source code in geemap/map_widgets.py
@staticmethod
def apply(cls: Any) -> Any:
"""Applies the theme to the given class.
Args:
cls (Any): The class to which the theme will be applied.
Returns:
Any: The class with the applied theme.
"""
original_init = cls.__init__
@functools.wraps(cls.__init__)
def wrapper(self, *args, **kwargs):
original_init(self, *args, **kwargs)
self.add_class("geemap-{}".format(Theme.current_theme))
cls.__init__ = wrapper
return cls