map_widgets module¶
Various ipywidgets that can be added to a map.
Basemap (AnyWidget)
¶
Widget for selecting a basemap.
Source code in geemap/map_widgets.py
@Theme.apply
class BasemapSelector(anywidget.AnyWidget):
"""Widget for selecting a basemap."""
_esm = pathlib.Path(__file__).parent / "static" / "basemap_selector.js"
# The list of basemap names to make available for selection.
basemaps = traitlets.List([]).tag(sync=True)
# The currently selected basemap value.
value = traitlets.Unicode("").tag(sync=True)
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.
"""
super().__init__()
self.on_close = None
self.on_basemap_changed = None
self.basemaps = basemaps
self.value = value
self._setup_event_listeners()
def _setup_event_listeners(self) -> None:
self.on_msg(self._handle_message_event)
def _handle_message_event(
self, widget: ipywidgets.Widget, content: Dict[str, Any], buffers: List[Any]
) -> None:
del widget, buffers # Unused
if content.get("type") == "click":
msg_id = content.get("id", "")
if msg_id == "close":
self.cleanup()
@traitlets.observe("value")
def _observe_value(self, change: Dict[str, Any]) -> None:
if (value := change.get("new")) is not None and self.on_basemap_changed:
self.on_basemap_changed(value)
def cleanup(self) -> None:
"""Cleans up the widget by calling the on_close callback if set."""
if self.on_close:
self.on_close()
__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.
"""
super().__init__()
self.on_close = None
self.on_basemap_changed = None
self.basemaps = basemaps
self.value = value
self._setup_event_listeners()
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()
BasemapSelector (AnyWidget)
¶
Widget for selecting a basemap.
Source code in geemap/map_widgets.py
@Theme.apply
class BasemapSelector(anywidget.AnyWidget):
"""Widget for selecting a basemap."""
_esm = pathlib.Path(__file__).parent / "static" / "basemap_selector.js"
# The list of basemap names to make available for selection.
basemaps = traitlets.List([]).tag(sync=True)
# The currently selected basemap value.
value = traitlets.Unicode("").tag(sync=True)
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.
"""
super().__init__()
self.on_close = None
self.on_basemap_changed = None
self.basemaps = basemaps
self.value = value
self._setup_event_listeners()
def _setup_event_listeners(self) -> None:
self.on_msg(self._handle_message_event)
def _handle_message_event(
self, widget: ipywidgets.Widget, content: Dict[str, Any], buffers: List[Any]
) -> None:
del widget, buffers # Unused
if content.get("type") == "click":
msg_id = content.get("id", "")
if msg_id == "close":
self.cleanup()
@traitlets.observe("value")
def _observe_value(self, change: Dict[str, Any]) -> None:
if (value := change.get("new")) is not None and self.on_basemap_changed:
self.on_basemap_changed(value)
def cleanup(self) -> None:
"""Cleans up the widget by calling the on_close callback if set."""
if self.on_close:
self.on_close()
__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.
"""
super().__init__()
self.on_close = None
self.on_basemap_changed = None
self.basemaps = basemaps
self.value = value
self._setup_event_listeners()
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 (AnyWidget)
¶
A layer manager widget for geemap.
Source code in geemap/map_widgets.py
@Theme.apply
class LayerManager(anywidget.AnyWidget):
"""A layer manager widget for geemap."""
_esm = pathlib.Path(__file__).parent / "static" / "layer_manager.js"
# Whether all layers should be visible or not. Represented as a checkbox in the UI.
visible = traitlets.Bool(True).tag(sync=True)
# Child widgets in the container. Using a tuple here to force reassignment to update
# the list. When a proper notifying-list trait exists, use that instead.
children = TypedTuple(
trait=traitlets.Instance(ipywidgets.Widget),
help="List of widget children",
).tag(sync=True, **ipywidgets.widget_serialization)
def __init__(self, host_map: "core.MapInterface"):
super().__init__()
self.host_map = host_map
if not host_map:
raise ValueError("Must pass a valid map when creating a layer manager.")
def refresh_layers(self) -> None:
"""Refresh the layers in the layer manager.
Uses the map interface to pull active layers. This function must be called
whenever a layer is added or removed on the map.
"""
self.children = list(map(self._create_row_widget, self.host_map.layers))
def _create_row_widget(self, layer: Any) -> LayerManagerRow:
return LayerManagerRow(self.host_map, layer)
@traitlets.observe("visible")
def _observe_visible(self, change: Dict[str, Any]) -> None:
# When the `visible` property changes, propagate that change to all children.
if (visible := change.get("new")) is not None:
for child in self.children:
child.visible = visible
refresh_layers(self)
¶
Refresh the layers in the layer manager.
Uses the map interface to pull active layers. This function must be called whenever a layer is added or removed on the map.
Source code in geemap/map_widgets.py
def refresh_layers(self) -> None:
"""Refresh the layers in the layer manager.
Uses the map interface to pull active layers. This function must be called
whenever a layer is added or removed on the map.
"""
self.children = list(map(self._create_row_widget, self.host_map.layers))
LayerManagerRow (AnyWidget)
¶
A layer manager row widget for geemap.
Source code in geemap/map_widgets.py
@Theme.apply
class LayerManagerRow(anywidget.AnyWidget):
"""A layer manager row widget for geemap."""
_esm = pathlib.Path(__file__).parent / "static" / "layer_manager_row.js"
name = traitlets.Unicode("").tag(sync=True)
visible = traitlets.Bool(True).tag(sync=True)
opacity = traitlets.Float(1).tag(sync=True)
is_loading = traitlets.Bool(False).tag(sync=True)
def __init__(self, host_map: "core.MapInterface", layer: Any):
super().__init__()
self.host_map = host_map
self.layer = layer
if not host_map or not layer:
raise ValueError(
"Must pass a valid map and layer when creating a layer manager row."
)
self.name = layer.name
self.visible = self._get_layer_visibility()
self.opacity = self._get_layer_opacity()
self.opacity_link: Optional[ipywidgets.widget_link.Link] = None
self.visibility_link: Optional[ipywidgets.widget_link.Link] = None
self._setup_event_listeners()
def _can_set_up_jslink(self, obj: Any, trait: str) -> bool:
return isinstance(obj, ipywidgets.Widget) and hasattr(obj, trait)
def _traitlet_link_type(self) -> Callable[..., Any]:
if coreutils.in_colab_shell():
# TODO: jslink doesn't work in Colab before the layers are added to the map.
# A potential workaround is calling display() on the layer before jslinking.
return ipywidgets.link
return ipywidgets.jslink
def _setup_event_listeners(self) -> None:
self.layer.observe(self._on_layer_loading_changed, "loading")
self.on_msg(self._handle_message_event)
link_func = self._traitlet_link_type()
if self._can_set_up_jslink(self.layer, "opacity"):
self.opacity_link = link_func((self.layer, "opacity"), (self, "opacity"))
if self._can_set_up_jslink(self.layer, "visible"):
self.visibility_link = link_func((self.layer, "visible"), (self, "visible"))
def _on_layer_loading_changed(self, change: Dict[str, Any]) -> None:
self.is_loading = change.get("new", False)
def _handle_message_event(
self, widget: ipywidgets.Widget, content: Dict[str, Any], buffers: List[Any]
) -> None:
del widget, buffers # Unused
if content.get("type") == "click":
self._handle_button_click(content.get("id", ""))
@traitlets.observe("opacity")
def _on_opacity_change(self, change: Dict[str, Any]) -> None:
if self._can_set_up_jslink(self.layer, "opacity"):
return # Return if the opacity is handled by a jslink.
if opacity := change.get("new"):
if self.layer in self.host_map.geojson_layers:
# For GeoJSON layers, use style.opacity and style.fillOpacity.
self.layer.style.update({"opacity": opacity, "fillOpacity": opacity})
def _get_layer_opacity(self) -> float:
if hasattr(self.layer, "opacity"):
return self.layer.opacity
elif self.layer in self.host_map.geojson_layers:
opacity = self.layer.style.get("opacity", 1.0)
fill_opacity = self.layer.style.get("fillOpacity", 1.0)
return max(opacity, fill_opacity)
return 1.0
def _get_layer_visibility(self) -> bool:
if hasattr(self.layer, "visible"):
return self.layer.visible
return True
def _handle_button_click(self, msg_id: str) -> None:
if msg_id == "settings":
self._open_layer_editor()
elif msg_id == "delete":
self._delete_layer()
def _open_layer_editor(self) -> None:
metadata = self.host_map.ee_layers.get(self.name, None)
self.host_map.add("layer_editor", position="bottomright", layer_dict=metadata)
def _delete_layer(self) -> None:
self.host_map.remove_layer(self.layer)
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
TypedTuple (Container)
¶
A trait for a tuple of any length with type-checked elements.
Source code in geemap/map_widgets.py
class TypedTuple(traitlets.Container):
"""A trait for a tuple of any length with type-checked elements."""
klass = tuple
_cast_types = (list,)
klass
¶
Built-in immutable sequence.
If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.
If the argument is a tuple, the return value is the same object.