geemap module

Main module for interactive mapping using Google Earth Engine Python API and ipyleaflet. Keep in mind that Earth Engine functions use both camel case and snake case, such as setOptions(), setCenter(), centerObject(), addLayer(). ipyleaflet functions use snake case, such as add_tile_layer(), add_wms_layer(), add_minimap().

EEFoliumTileLayer

Bases: TileLayer

A Folium raster TileLayer that shows an EE object.

Source code in geemap/ee_tile_layers.py

class EEFoliumTileLayer(folium.raster_layers.TileLayer):
    """A Folium raster TileLayer that shows an EE object."""

    def __init__(
        self,
        ee_object: Union[
            ee.Geometry, ee.Feature, ee.FeatureCollection, ee.Image, ee.ImageCollection
        ],
        vis_params: Optional[Dict[str, Any]] = None,
        name: str = "Layer untitled",
        shown: bool = True,
        opacity: float = 1.0,
        **kwargs: Any,
    ):
        """Initialize the folium tile layer.

        Args:
            ee_object (Union[ee.Geometry, ee.Feature, ee.FeatureCollection,
                ee.Image, ee.ImageCollection]): The object to add to the map.
            vis_params (Optional[Dict[str, Any]]): The visualization parameters.
                Defaults to None.
            name (str, optional): The name of the layer. Defaults to 'Layer untitled'.
            shown (bool, optional): A flag indicating whether the layer should
                be on by default. Defaults to True.
            opacity (float, optional): The layer's opacity represented as a
                number between 0 and 1. Defaults to 1.
        """
        self.url_format = _get_tile_url_format(
            ee_object, _validate_vis_params(vis_params)
        )
        super().__init__(
            tiles=self.url_format,
            attr="Google Earth Engine",
            name=name,
            overlay=True,
            control=True,
            show=shown,
            opacity=opacity,
            max_zoom=24,
            **kwargs,
        )

__init__(ee_object, vis_params=None, name='Layer untitled', shown=True, opacity=1.0, **kwargs)

Initialize the folium tile layer.

Parameters:

Name	Type	Description	Default
vis_params	Optional[Dict[str, Any]]	The visualization parameters. Defaults to None.	None
name	str	The name of the layer. Defaults to 'Layer untitled'.	'Layer untitled'
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
opacity	float	The layer's opacity represented as a number between 0 and 1. Defaults to 1.	1.0

Source code in geemap/ee_tile_layers.py

def __init__(
    self,
    ee_object: Union[
        ee.Geometry, ee.Feature, ee.FeatureCollection, ee.Image, ee.ImageCollection
    ],
    vis_params: Optional[Dict[str, Any]] = None,
    name: str = "Layer untitled",
    shown: bool = True,
    opacity: float = 1.0,
    **kwargs: Any,
):
    """Initialize the folium tile layer.

    Args:
        ee_object (Union[ee.Geometry, ee.Feature, ee.FeatureCollection,
            ee.Image, ee.ImageCollection]): The object to add to the map.
        vis_params (Optional[Dict[str, Any]]): The visualization parameters.
            Defaults to None.
        name (str, optional): The name of the layer. Defaults to 'Layer untitled'.
        shown (bool, optional): A flag indicating whether the layer should
            be on by default. Defaults to True.
        opacity (float, optional): The layer's opacity represented as a
            number between 0 and 1. Defaults to 1.
    """
    self.url_format = _get_tile_url_format(
        ee_object, _validate_vis_params(vis_params)
    )
    super().__init__(
        tiles=self.url_format,
        attr="Google Earth Engine",
        name=name,
        overlay=True,
        control=True,
        show=shown,
        opacity=opacity,
        max_zoom=24,
        **kwargs,
    )

EELeafletTileLayer

Bases: TileLayer

An ipyleaflet TileLayer that shows an EE object.

Source code in geemap/ee_tile_layers.py

class EELeafletTileLayer(ipyleaflet.TileLayer):
    """An ipyleaflet TileLayer that shows an EE object."""

    EE_TYPES = (
        ee.Geometry,
        ee.Feature,
        ee.FeatureCollection,
        ee.Image,
        ee.ImageCollection,
    )

    def __init__(
        self,
        ee_object: Union[
            ee.Geometry, ee.Feature, ee.FeatureCollection, ee.Image, ee.ImageCollection
        ],
        vis_params: Optional[Dict[str, Any]] = None,
        name: str = "Layer untitled",
        shown: bool = True,
        opacity: float = 1.0,
        **kwargs: Any,
    ):
        """Initialize the ipyleaflet tile layer.

        Args:
            ee_object (Union[ee.Geometry, ee.Feature, ee.FeatureCollection,
                ee.Image, ee.ImageCollection]): The object to add to the map.
            vis_params (Optional[Dict[str, Any]]): The visualization parameters.
                Defaults to None.
            name (str, optional): The name of the layer. Defaults to 'Layer untitled'.
            shown (bool, optional): A flag indicating whether the layer should
                be on by default. Defaults to True.
            opacity (float, optional): The layer's opacity represented as a
                number between 0 and 1. Defaults to 1.
        """
        self._ee_object = ee_object
        self.url_format = _get_tile_url_format(
            ee_object, _validate_vis_params(vis_params)
        )
        super().__init__(
            url=self.url_format,
            attribution="Google Earth Engine",
            name=name,
            opacity=opacity,
            visible=shown,
            max_zoom=24,
            **kwargs,
        )

    @lru_cache()
    def _calculate_vis_stats(
        self,
        *,
        bounds: Union[ee.Geometry, ee.Feature, ee.FeatureCollection],
        bands: Tuple[str, ...],
    ) -> Tuple[float, float, float, float]:
        """Calculate stats used for visualization parameters.

        Stats are calculated consistently with the Code Editor visualization parameters,
        and are cached to avoid recomputing for the same bounds and bands.

        Args:
            bounds (Union[ee.Geometry, ee.Feature, ee.FeatureCollection]): The
                bounds to sample.
            bands (Tuple[str, ...]): The bands to sample.

        Returns:
            Tuple[float, float, float, float]: The minimum, maximum, standard
                deviation, and mean values across the specified bands.
        """
        stat_reducer = (
            ee.Reducer.minMax()
            .combine(ee.Reducer.mean().unweighted(), sharedInputs=True)
            .combine(ee.Reducer.stdDev(), sharedInputs=True)
        )

        stats = (
            self._ee_object.select(bands)
            .reduceRegion(
                reducer=stat_reducer,
                geometry=bounds,
                bestEffort=True,
                maxPixels=10_000,
                crs="SR-ORG:6627",
                scale=1,
            )
            .getInfo()
        )

        mins, maxs, stds, means = [
            {v for k, v in stats.items() if k.endswith(stat) and v is not None}
            for stat in ("_min", "_max", "_stdDev", "_mean")
        ]
        if any(len(vals) == 0 for vals in (mins, maxs, stds, means)):
            raise ValueError("No unmasked pixels were sampled.")

        min_val = min(mins)
        max_val = max(maxs)
        std_dev = sum(stds) / len(stds)
        mean = sum(means) / len(means)

        return (min_val, max_val, std_dev, mean)

    def calculate_vis_minmax(
        self,
        *,
        bounds: Union[ee.Geometry, ee.Feature, ee.FeatureCollection],
        bands: Optional[List[str]] = None,
        percent: Optional[float] = None,
        sigma: Optional[float] = None,
    ) -> Tuple[float, float]:
        """Calculate the min and max clip values for visualization.

        Args:
            bounds (Union[ee.Geometry, ee.Feature, ee.FeatureCollection]): The bounds to sample.
            bands (Optional[List[str]]): The bands to sample. If None, all bands are used.
            percent (Optional[float]): The percent to use when stretching.
            sigma (Optional[float]): The number of standard deviations to use when stretching.

        Returns:
            Tuple[float, float]: The minimum and maximum values to clip to.
        """
        bands = self._ee_object.bandNames() if bands is None else tuple(bands)
        try:
            min_val, max_val, std, mean = self._calculate_vis_stats(
                bounds=bounds, bands=bands
            )
        except ValueError:
            return (0, 0)

        if sigma is not None:
            stretch_min = mean - sigma * std
            stretch_max = mean + sigma * std
        elif percent is not None:
            x = (max_val - min_val) * (1 - percent)
            stretch_min = min_val + x
            stretch_max = max_val - x
        else:
            stretch_min = min_val
            stretch_max = max_val

        return (stretch_min, stretch_max)

__init__(ee_object, vis_params=None, name='Layer untitled', shown=True, opacity=1.0, **kwargs)

Initialize the ipyleaflet tile layer.

Parameters:

Name	Type	Description	Default
vis_params	Optional[Dict[str, Any]]	The visualization parameters. Defaults to None.	None
name	str	The name of the layer. Defaults to 'Layer untitled'.	'Layer untitled'
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
opacity	float	The layer's opacity represented as a number between 0 and 1. Defaults to 1.	1.0

Source code in geemap/ee_tile_layers.py

def __init__(
    self,
    ee_object: Union[
        ee.Geometry, ee.Feature, ee.FeatureCollection, ee.Image, ee.ImageCollection
    ],
    vis_params: Optional[Dict[str, Any]] = None,
    name: str = "Layer untitled",
    shown: bool = True,
    opacity: float = 1.0,
    **kwargs: Any,
):
    """Initialize the ipyleaflet tile layer.

    Args:
        ee_object (Union[ee.Geometry, ee.Feature, ee.FeatureCollection,
            ee.Image, ee.ImageCollection]): The object to add to the map.
        vis_params (Optional[Dict[str, Any]]): The visualization parameters.
            Defaults to None.
        name (str, optional): The name of the layer. Defaults to 'Layer untitled'.
        shown (bool, optional): A flag indicating whether the layer should
            be on by default. Defaults to True.
        opacity (float, optional): The layer's opacity represented as a
            number between 0 and 1. Defaults to 1.
    """
    self._ee_object = ee_object
    self.url_format = _get_tile_url_format(
        ee_object, _validate_vis_params(vis_params)
    )
    super().__init__(
        url=self.url_format,
        attribution="Google Earth Engine",
        name=name,
        opacity=opacity,
        visible=shown,
        max_zoom=24,
        **kwargs,
    )

calculate_vis_minmax(*, bounds, bands=None, percent=None, sigma=None)

Calculate the min and max clip values for visualization.

Parameters:

Name	Type	Description	Default
bounds	Union[Geometry, Feature, FeatureCollection]	The bounds to sample.	required
bands	Optional[List[str]]	The bands to sample. If None, all bands are used.	None
percent	Optional[float]	The percent to use when stretching.	None
sigma	Optional[float]	The number of standard deviations to use when stretching.	None

Returns:

Type	Description
Tuple[float, float]	Tuple[float, float]: The minimum and maximum values to clip to.

Source code in geemap/ee_tile_layers.py

def calculate_vis_minmax(
    self,
    *,
    bounds: Union[ee.Geometry, ee.Feature, ee.FeatureCollection],
    bands: Optional[List[str]] = None,
    percent: Optional[float] = None,
    sigma: Optional[float] = None,
) -> Tuple[float, float]:
    """Calculate the min and max clip values for visualization.

    Args:
        bounds (Union[ee.Geometry, ee.Feature, ee.FeatureCollection]): The bounds to sample.
        bands (Optional[List[str]]): The bands to sample. If None, all bands are used.
        percent (Optional[float]): The percent to use when stretching.
        sigma (Optional[float]): The number of standard deviations to use when stretching.

    Returns:
        Tuple[float, float]: The minimum and maximum values to clip to.
    """
    bands = self._ee_object.bandNames() if bands is None else tuple(bands)
    try:
        min_val, max_val, std, mean = self._calculate_vis_stats(
            bounds=bounds, bands=bands
        )
    except ValueError:
        return (0, 0)

    if sigma is not None:
        stretch_min = mean - sigma * std
        stretch_max = mean + sigma * std
    elif percent is not None:
        x = (max_val - min_val) * (1 - percent)
        stretch_min = min_val + x
        stretch_max = max_val - x
    else:
        stretch_min = min_val
        stretch_max = max_val

    return (stretch_min, stretch_max)

ImageOverlay

Bases: ImageOverlay

ImageOverlay class.

Parameters:

Name	Type	Description	Default
url	str	http URL or local file path to the image.	required
bounds	tuple	bounding box of the image in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).	required
name	str	The name of the layer.	required

Source code in geemap/geemap.py

class ImageOverlay(ipyleaflet.ImageOverlay):
    """ImageOverlay class.

    Args:
        url (str): http URL or local file path to the image.
        bounds (tuple): bounding box of the image in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).
        name (str): The name of the layer.
    """

    def __init__(self, **kwargs):
        from base64 import b64encode
        from PIL import Image, ImageSequence
        from io import BytesIO

        try:
            url = kwargs.get("url")
            if not url.startswith("http"):
                url = os.path.abspath(url)
                if not os.path.exists(url):
                    raise FileNotFoundError("The provided file does not exist.")

                ext = os.path.splitext(url)[1][1:]  # file extension
                image = Image.open(url)

                f = BytesIO()
                if ext.lower() == "gif":
                    frames = []
                    # Loop over each frame in the animated image
                    for frame in ImageSequence.Iterator(image):
                        frame = frame.convert("RGBA")
                        b = BytesIO()
                        frame.save(b, format="gif")
                        frame = Image.open(b)
                        frames.append(frame)
                    frames[0].save(
                        f,
                        format="GIF",
                        save_all=True,
                        append_images=frames[1:],
                        loop=0,
                    )
                else:
                    image.save(f, ext)

                data = b64encode(f.getvalue())
                data = data.decode("ascii")
                url = "data:image/{};base64,".format(ext) + data
                kwargs["url"] = url
        except Exception as e:
            raise Exception(e)

        super().__init__(**kwargs)

Map

Bases: Map

The Map class inherits the core Map class. The arguments you can pass to the Map initialization can be found at https://ipyleaflet.readthedocs.io/en/latest/map_and_basemaps/map.html. By default, the Map will use OpenStreetMap as the basemap.

Returns:

Name	Type	Description
object		ipyleaflet map object.

Source code in geemap/geemap.py

class Map(core.Map):
    """The Map class inherits the core Map class. The arguments you can pass to the Map initialization
        can be found at https://ipyleaflet.readthedocs.io/en/latest/map_and_basemaps/map.html.
        By default, the Map will use OpenStreetMap as the basemap.

    Returns:
        object: ipyleaflet map object.
    """

    # Map attributes for drawing features
    @property
    def draw_control(self) -> Any:
        """Gets the draw control.

        Returns:
            Any: The draw control.
        """
        return self.get_draw_control()

    @property
    def draw_control_lite(self) -> Any:
        """Gets the lite version of the draw control.

        Returns:
            Any: The lite draw control.
        """
        return self.get_draw_control()

    @property
    def draw_features(self) -> List[Any]:
        """Gets the drawn features.

        Returns:
            List[Any]: The list of drawn features.
        """
        return self._draw_control.features if self._draw_control else []

    @property
    def draw_last_feature(self) -> Optional[Any]:
        """Gets the last drawn feature.

        Returns:
            Optional[Any]: The last drawn feature.
        """
        return self._draw_control.last_feature if self._draw_control else None

    @property
    def draw_layer(self) -> Optional[Any]:
        """Gets the draw layer.

        Returns:
            Optional[Any]: The draw layer.
        """
        return self._draw_control.layer if self._draw_control else None

    @property
    def user_roi(self) -> Optional[Any]:
        """Gets the user region of interest.

        Returns:
            Optional[Any]: The user region of interest.
        """
        return self._draw_control.last_geometry if self._draw_control else None

    @property
    def user_rois(self) -> Optional[Any]:
        """Gets the user regions of interest.

        Returns:
            Optional[Any]: The user regions of interest.
        """
        return self._draw_control.collection if self._draw_control else None

    def __init__(self, **kwargs):
        """Initialize a map object. The following additional parameters can be
            passed in addition to the ipyleaflet.Map parameters:

        Args:
            ee_initialize (bool, optional): Whether or not to initialize ee. Defaults to True.
            center (list, optional): Center of the map (lat, lon). Defaults to [20, 0].
            zoom (int, optional): Zoom level of the map. Defaults to 2.
            height (str, optional): Height of the map. Defaults to "600px".
            width (str, optional): Width of the map. Defaults to "100%".
            basemap (str, optional): Name of the basemap to add to the map.
                Defaults to "ROADMAP". Other options include "ROADMAP", "SATELLITE", "TERRAIN".
            add_google_map (bool, optional): Whether to add Google Maps to the map. Defaults to True.
            sandbox_path (str, optional): The path to a sandbox folder for voila web app. Defaults to None.
            lite_mode (bool, optional): Whether to enable lite mode, which only displays
                zoom control on the map. Defaults to False.
            data_ctrl (bool, optional): Deprecated: use search_ctrl instead.
            zoom_ctrl (bool, optional): Whether to add the zoom control to the map. Defaults to True.
            fullscreen_ctrl (bool, optional): Whether to add the fullscreen control to the map. Defaults to True.
            search_ctrl (bool, optional): Whether to add the search control to the map. Defaults to True.
            draw_ctrl (bool, optional): Whether to add the draw control to the map. Defaults to True.
            scale_ctrl (bool, optional): Whether to add the scale control to the map. Defaults to True.
            measure_ctrl (bool, optional): Whether to add the measure control to the map. Defaults to True.
            toolbar_ctrl (bool, optional): Whether to add the toolbar control to the map. Defaults to True.
            layer_ctrl (bool, optional): Whether to add the layer control to the map. Defaults to False.
            attribution_ctrl (bool, optional): Whether to add the attribution control to the map. Defaults to True.
            **kwargs: Additional keyword arguments for ipyleaflet.Map.
        """
        warnings.filterwarnings("ignore")

        if isinstance(kwargs.get("height"), int):
            kwargs["height"] = str(kwargs["height"]) + "px"
        if isinstance(kwargs.get("width"), int):
            kwargs["width"] = str(kwargs["width"]) + "px"

        if "max_zoom" not in kwargs:
            kwargs["max_zoom"] = 24

        self._xyz_dict = get_xyz_dict()

        self.baseclass = "ipyleaflet"
        self._USER_AGENT_PREFIX = "geemap"
        self.kwargs = kwargs
        super().__init__(**kwargs)
        self._var_name = "Map"  # The Map variable name for converting JS to Python

        if kwargs.get("height"):
            self.layout.height = kwargs.get("height")

        # sandbox path for Voila app to restrict access to system directories.
        if "sandbox_path" not in kwargs:
            self.sandbox_path = None
        else:
            if os.path.exists(os.path.abspath(kwargs["sandbox_path"])):
                self.sandbox_path = kwargs["sandbox_path"]
            else:
                print("The sandbox path is invalid.")
                self.sandbox_path = None

        # Add Google Maps as the default basemap
        if kwargs.get("add_google_map", False):
            self.add_basemap("ROADMAP")

        # ipyleaflet built-in layer control
        self.layer_control = None

        if "ee_initialize" not in kwargs:
            kwargs["ee_initialize"] = True

        # Default reducer to use
        if kwargs["ee_initialize"]:
            self.roi_reducer = ee.Reducer.mean()
        self.roi_reducer_scale = None

    def _control_config(self) -> Dict[str, List[str]]:
        """Configures the map controls based on the provided arguments.

        Returns:
            Dict[str, List[str]]: The configuration of map controls.
        """
        if self.kwargs.get("lite_mode"):
            return {"topleft": ["zoom_control"]}

        topleft = []
        bottomleft = []
        topright = []
        bottomright = []

        for control in ["search_ctrl", "zoom_ctrl", "fullscreen_ctrl", "draw_ctrl"]:
            if self.kwargs.get(control, True):
                topleft.append(control)

        for control in ["scale_ctrl", "measure_ctrl"]:
            if self.kwargs.get(control, True):
                bottomleft.append(control)

        for control in ["toolbar_ctrl"]:
            if self.kwargs.get(control, True):
                topright.append("layer_manager")
                topright.append(control)

        for control in ["attribution_control"]:
            if self.kwargs.get(control, True):
                bottomright.append(control)

        return {
            "topleft": topleft,
            "bottomleft": bottomleft,
            "topright": topright,
            "bottomright": bottomright,
        }

    @property
    def ee_layer_names(self) -> List[str]:
        """Gets the names of the EE layers.

        Returns:
            List[str]: The names of the EE layers.
        """
        warnings.warn(
            "ee_layer_names is deprecated. Use ee_layers.keys() instead.",
            DeprecationWarning,
        )
        return list(self.ee_layers.keys())

    @property
    def ee_layer_dict(self) -> Dict[str, Any]:
        """Gets the dictionary of EE layers.

        Returns:
            Dict[str, Any]: The dictionary of EE layers.
        """
        warnings.warn(
            "ee_layer_dict is deprecated. Use ee_layers instead.", DeprecationWarning
        )
        return self.ee_layers

    @property
    def ee_raster_layer_names(self) -> List[str]:
        """Gets the names of the EE raster layers.

        Returns:
            List[str]: The names of the EE raster layers.
        """
        warnings.warn(
            "ee_raster_layer_names is deprecated. Use self.ee_raster_layers.keys() instead.",
            DeprecationWarning,
        )
        return list(self.ee_raster_layers.keys())

    @property
    def ee_vector_layer_names(self) -> List[str]:
        """Gets the names of the EE vector layers.

        Returns:
            List[str]: The names of the EE vector layers.
        """
        warnings.warn(
            "ee_vector_layer_names is deprecated. Use self.ee_vector_layers.keys() instead.",
            DeprecationWarning,
        )
        return list(self.ee_vector_layers.keys())

    @property
    def ee_raster_layers(self) -> Dict[str, Any]:
        """Gets the dictionary of EE raster layers.

        Returns:
            Dict[str, Any]: The dictionary of EE raster layers.
        """
        return dict(filter(self._raster_filter, self.ee_layers.items()))

    @property
    def ee_vector_layers(self) -> Dict[str, Any]:
        """Gets the dictionary of EE vector layers.

        Returns:
            Dict[str, Any]: The dictionary of EE vector layers.
        """
        return dict(filter(self._vector_filter, self.ee_layers.items()))

    def _raster_filter(self, pair: Tuple[str, Dict[str, Any]]) -> bool:
        """Filters the raster layers.

        Args:
            pair (Tuple[str, Dict[str, Any]]): The layer pair to filter.

        Returns:
            bool: True if the layer is a raster layer, False otherwise.
        """
        return isinstance(pair[1]["ee_object"], (ee.Image, ee.ImageCollection))

    def _vector_filter(self, pair: Tuple[str, Dict[str, Any]]) -> bool:
        """Filters the vector layers.

        Args:
            pair (Tuple[str, Dict[str, Any]]): The layer pair to filter.

        Returns:
            bool: True if the layer is a vector layer, False otherwise.
        """
        return isinstance(
            pair[1]["ee_object"], (ee.Geometry, ee.Feature, ee.FeatureCollection)
        )

    def add(
        self, obj: Union[str, Any], position: str = "topright", **kwargs: Any
    ) -> None:
        """Adds a layer or control to the map.

        Args:
            obj (Union[str, Any]): The layer or control to add to the map.
            position (str, optional): The position of the control on the map. Defaults to "topright".
            **kwargs: Additional keyword arguments.
        """
        if isinstance(obj, str):
            basemap = check_basemap(obj)
            if basemap in basemaps.keys():
                super().add(get_basemap(basemap))
                return

        if not isinstance(obj, str):
            super().add(obj, position=position, **kwargs)
            return

        obj = obj.lower()

        backward_compatibilities = {
            "zoom_ctrl": "zoom_control",
            "fullscreen_ctrl": "fullscreen_control",
            "scale_ctrl": "scale_control",
            "toolbar_ctrl": "toolbar",
            "draw_ctrl": "draw_control",
            "data_ctrl": "search_control",
            "search_ctrl": "search_control",
        }
        obj = backward_compatibilities.get(obj, obj)
        if obj == "measure_ctrl":
            measure = ipyleaflet.MeasureControl(
                position=position,
                active_color="orange",
                primary_length_unit="kilometers",
            )
            self.add(measure, position=position)
        elif obj == "layer_ctrl":
            layer_control = ipyleaflet.LayersControl(position=position)
            self.add(layer_control, position=position)
        else:
            super().add(obj, position=position, **kwargs)

    def add_controls(
        self, controls: Union[List[Any], Any], position: str = "topleft"
    ) -> None:
        """Adds a list of controls to the map.

        Args:
            controls (Union[List[Any], Any]): A list of controls or a single
                control to add to the map.
            position (str, optional): The position of the controls on the map.
                Defaults to "topleft".
        """
        if not isinstance(controls, list):
            controls = [controls]
        for control in controls:
            self.add(control, position)

    def set_options(self, mapTypeId: str = "HYBRID", **kwargs: Any) -> None:
        """Adds Google basemap and controls to the ipyleaflet map.

        Args:
            mapTypeId (str, optional): A mapTypeId to set the basemap to. Can be
                one of "ROADMAP", "SATELLITE", "HYBRID" or "TERRAIN" to select
                one of the standard Google Maps API map types. Defaults to 'HYBRID'.
            **kwargs: Additional keyword arguments.
        """

        try:
            self.add(mapTypeId)
        except Exception:
            raise ValueError(
                'Google basemaps can only be one of "ROADMAP", "SATELLITE", "HYBRID" or "TERRAIN".'
            )

    setOptions = set_options

    def add_ee_layer(
        self,
        ee_object: Union[
            ee.FeatureCollection, ee.Feature, ee.Image, ee.ImageCollection
        ],
        vis_params: Optional[Dict[str, Any]] = None,
        name: Optional[str] = None,
        shown: bool = True,
        opacity: float = 1.0,
    ) -> None:
        """Adds a given EE object to the map as a layer.

        Args:
            ee_object (Union[ee.FeatureCollection, ee.Feature, ee.Image, ee.ImageCollection]):
                The object to add to the map.
            vis_params (Optional[Dict[str, Any]], optional): The visualization parameters.
                Defaults to {}.
            name (Optional[str], optional): The name of the layer. Defaults to 'Layer N'.
            shown (bool, optional): A flag indicating whether the layer should be on by
                default. Defaults to True.
            opacity (float, optional): The layer's opacity represented as a number
                between 0 and 1. Defaults to 1.
        """
        has_plot_dropdown = (
            hasattr(self, "_plot_dropdown_widget")
            and self._plot_dropdown_widget is not None
        )

        ee_layer = self.ee_layers.get(name, {})
        layer = ee_layer.get("ee_layer", None)
        if layer is not None:
            if isinstance(ee_layer["ee_object"], (ee.Image, ee.ImageCollection)):
                if has_plot_dropdown:
                    self._plot_dropdown_widget.options = list(
                        self.ee_raster_layers.keys()
                    )

        super().add_layer(ee_object, vis_params, name, shown, opacity)

        if isinstance(ee_object, (ee.Image, ee.ImageCollection)):
            if has_plot_dropdown:
                self._plot_dropdown_widget.options = list(self.ee_raster_layers.keys())

        tile_layer = self.ee_layers.get(name, {}).get("ee_layer", None)
        if tile_layer:
            arc_add_layer(tile_layer.url_format, name, shown, opacity)

    addLayer = add_ee_layer

    def remove_ee_layer(self, name: str) -> None:
        """Removes an Earth Engine layer.

        Args:
            name (str): The name of the Earth Engine layer to remove.
        """
        if name in self.ee_layers:
            ee_layer = self.ee_layers[name]["ee_layer"]
            self.ee_layers.pop(name, None)
            if ee_layer in self.layers:
                self.remove_layer(ee_layer)

    def set_center(self, lon: float, lat: float, zoom: Optional[int] = None) -> None:
        """Centers the map view at a given coordinates with the given zoom level.

        Args:
            lon (float): The longitude of the center, in degrees.
            lat (float): The latitude of the center, in degrees.
            zoom (Optional[int], optional): The zoom level, from 1 to 24. Defaults to None.
        """
        super().set_center(lon, lat, zoom)
        if is_arcpy():
            arc_zoom_to_extent(lon, lat, lon, lat)

    setCenter = set_center

    def center_object(
        self,
        ee_object: Union[ee.Element, ee.Geometry],
        zoom: Optional[int] = None,
        max_error: float = 0.001,
    ) -> None:
        """Centers the map view on a given object.

        Args:
            ee_object (Union[ee.Element, ee.Geometry]): An Earth Engine object to
                center on a geometry, image or feature.
            zoom (Optional[int], optional): The zoom level, from 1 to 24. Defaults to None.
            max_error (float, optional): The maximum error for the geometry. Defaults to 0.001.
        """
        super().center_object(ee_object=ee_object, zoom=zoom, max_error=max_error)
        if is_arcpy():
            bds = self.bounds
            arc_zoom_to_extent(bds[0][1], bds[0][0], bds[1][1], bds[1][0])

    centerObject = center_object

    def zoom_to_bounds(
        self, bounds: Union[List[float], Tuple[float, float, float, float]]
    ) -> None:
        """Zooms to a bounding box in the form of [minx, miny, maxx, maxy].

        Args:
            bounds (Union[List[float], Tuple[float, float, float, float]]): A
                list/tuple containing minx, miny, maxx, maxy values for the bounds.
        """
        #  The ipyleaflet fit_bounds method takes lat/lon bounds in the form [[south, west], [north, east]].
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

    def get_scale(self) -> float:
        """Returns the approximate pixel scale of the current map view, in meters.

        Returns:
            float: Map resolution in meters.
        """
        return super().get_scale()

    getScale = get_scale

    def add_basemap(
        self,
        basemap: Optional[str] = "ROADMAP",
        show: Optional[bool] = True,
        **kwargs: Any,
    ) -> None:
        """Adds a basemap to the map.

        Args:
            basemap (Optional[str], optional): Can be one of the strings from basemaps.
                Defaults to 'ROADMAP'.
            show (Optional[bool], optional): Whether the basemap is visible or not.
                Defaults to True.
            **kwargs: Additional keyword arguments for the TileLayer.
        """
        import xyzservices

        try:
            layer_names = self.get_layer_names()

            if isinstance(basemap, str):
                for map_name, tile_provider in self._available_basemaps.items():
                    if basemap.upper() == map_name.upper():
                        basemap = tile_provider
                        break

            if isinstance(basemap, xyzservices.TileProvider):
                name = basemap.name
                url = basemap.build_url()
                attribution = basemap.attribution
                if "max_zoom" in basemap.keys():
                    max_zoom = basemap["max_zoom"]
                else:
                    max_zoom = 30
                layer = ipyleaflet.TileLayer(
                    url=url,
                    name=name,
                    max_zoom=max_zoom,
                    attribution=attribution,
                    visible=show,
                    **kwargs,
                )
                self.add(layer)
                arc_add_layer(url, name)
            elif basemap in basemaps and basemaps[basemap].name not in layer_names:
                self.add(basemap)
                self.layers[-1].visible = show
                arc_add_layer(basemaps[basemap].url, basemap)
            elif basemap in basemaps and basemaps[basemap].name in layer_names:
                print(f"{basemap} has been already added before.")
            elif basemap.startswith("http"):
                self.add_tile_layer(url=basemap, shown=show, **kwargs)
            else:
                print(
                    "Basemap can only be one of the following:\n  {}".format(
                        "\n  ".join(basemaps.keys())
                    )
                )

        except Exception as e:
            raise ValueError(
                "Basemap can only be one of the following:\n  {}".format(
                    "\n  ".join(basemaps.keys())
                )
            )

    def get_layer_names(self) -> List[str]:
        """Gets layer names as a list.

        Returns:
            List[str]: A list of layer names.
        """
        layer_names = []

        for layer in list(self.layers):
            if len(layer.name) > 0:
                layer_names.append(layer.name)

        return layer_names

    def find_layer(self, name: str) -> Optional[ipyleaflet.Layer]:
        """Finds a layer by name.

        Args:
            name (str): Name of the layer to find.

        Returns:
            Optional[ipyleaflet.Layer]: The ipyleaflet layer object if found, else None.
        """
        layers = self.layers

        for layer in layers:
            if layer.name == name:
                return layer

        return None

    def show_layer(self, name: str, show: bool = True) -> None:
        """Shows or hides a layer on the map.

        Args:
            name (str): Name of the layer to show/hide.
            show (bool, optional): Whether to show or hide the layer. Defaults to True.
        """
        layer = self.find_layer(name)

        if layer is not None:
            layer.visible = show

    def find_layer_index(self, name: str) -> int:
        """Finds the index of a layer by name.

        Args:
            name (str): Name of the layer to find.

        Returns:
            int: Index of the layer with the specified name, or -1 if not found.
        """
        layers = self.layers

        for index, layer in enumerate(layers):
            if layer.name == name:
                return index

        return -1

    def layer_opacity(self, name: str, opacity: float = 1.0) -> None:
        """Changes the opacity of a layer.

        Args:
            name (str): The name of the layer to change opacity.
            opacity (float, optional): The opacity value to set. Defaults to 1.0.
        """
        layer = self.find_layer(name)
        try:
            layer.opacity = opacity
        except Exception as e:
            raise Exception(e)

    def add_tile_layer(
        self,
        url: str = "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
        name: str = "Untitled",
        attribution: str = "",
        opacity: float = 1.0,
        shown: bool = True,
        **kwargs: Any,
    ) -> None:
        """Adds a TileLayer to the map.

        Args:
            url (str, optional): The URL of the tile layer. Defaults to
                'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'.
            name (str, optional): The layer name to use for the layer. Defaults to 'Untitled'.
            attribution (str, optional): The attribution to use. Defaults to ''.
            opacity (float, optional): The opacity of the layer. Defaults to 1.0.
            shown (bool, optional): A flag indicating whether the layer should
                be on by default. Defaults to True.
        """

        if "max_zoom" not in kwargs:
            kwargs["max_zoom"] = 100
        if "max_native_zoom" not in kwargs:
            kwargs["max_native_zoom"] = 100

        try:
            tile_layer = ipyleaflet.TileLayer(
                url=url,
                name=name,
                attribution=attribution,
                opacity=opacity,
                visible=shown,
                **kwargs,
            )
            self.add(tile_layer)

        except Exception as e:
            print("Failed to add the specified TileLayer.")
            raise Exception(e)

    def set_plot_options(
        self,
        add_marker_cluster: bool = False,
        sample_scale: Optional[float] = None,
        plot_type: Optional[str] = None,
        overlay: bool = False,
        position: str = "bottomright",
        min_width: Optional[int] = None,
        max_width: Optional[int] = None,
        min_height: Optional[int] = None,
        max_height: Optional[int] = None,
        **kwargs: Any,
    ) -> None:
        """Sets plotting options.

        Args:
            add_marker_cluster (bool, optional): Whether to add a marker cluster.
                Defaults to False.
            sample_scale (float, optional):  A nominal scale in meters of the
                projection to sample in . Defaults to None.
            plot_type (str, optional): The plot type can be one of "None", "bar",
                "scatter" or "hist". Defaults to None.
            overlay (bool, optional): Whether to overlay plotted lines on the figure.
                Defaults to False.
            position (str, optional): Position of the control, can be ‘bottomleft’,
                ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
            min_width (int, optional): Min width of the widget (in pixels),
                if None it will respect the content size. Defaults to None.
            max_width (int, optional): Max width of the widget (in pixels),
                if None it will respect the content size. Defaults to None.
            min_height (int, optional): Min height of the widget (in pixels),
                if None it will respect the content size. Defaults to None.
            max_height (int, optional): Max height of the widget (in pixels),
                if None it will respect the content size. Defaults to None.

        """
        plot_options_dict = {}
        plot_options_dict["add_marker_cluster"] = add_marker_cluster
        plot_options_dict["sample_scale"] = sample_scale
        plot_options_dict["plot_type"] = plot_type
        plot_options_dict["overlay"] = overlay
        plot_options_dict["position"] = position
        plot_options_dict["min_width"] = min_width
        plot_options_dict["max_width"] = max_width
        plot_options_dict["min_height"] = min_height
        plot_options_dict["max_height"] = max_height

        for key in kwargs:
            plot_options_dict[key] = kwargs[key]

        self._plot_options = plot_options_dict

        if not hasattr(self, "_plot_marker_cluster"):
            self._plot_marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")

        if add_marker_cluster and (self._plot_marker_cluster not in self.layers):
            self.add(self._plot_marker_cluster)

    def plot(
        self,
        x: Union[List[float], Any],
        y: Union[List[float], Any],
        plot_type: Optional[str] = None,
        overlay: bool = False,
        position: str = "bottomright",
        min_width: Optional[int] = None,
        max_width: Optional[int] = None,
        min_height: Optional[int] = None,
        max_height: Optional[int] = None,
        **kwargs: Any,
    ) -> None:
        """Creates a plot based on x-array and y-array data.

        Args:
            x (numpy.ndarray or list): The x-coordinates of the plotted line.
            y (numpy.ndarray or list): The y-coordinates of the plotted line.
            plot_type (str, optional): The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.
            overlay (bool, optional): Whether to overlay plotted lines on the figure. Defaults to False.
            position (str, optional): Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
            min_width (int, optional): Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
            max_width (int, optional): Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
            min_height (int, optional): Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
            max_height (int, optional): Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

        """
        if hasattr(self, "_plot_widget") and self._plot_widget is not None:
            plot_widget = self._plot_widget
        else:
            plot_widget = widgets.Output(
                layout={"border": "1px solid black", "max_width": "500px"}
            )
            plot_control = ipyleaflet.WidgetControl(
                widget=plot_widget,
                position=position,
                min_width=min_width,
                max_width=max_width,
                min_height=min_height,
                max_height=max_height,
            )
            self._plot_widget = plot_widget
            self._plot_control = plot_control
            self.add(plot_control)

        if max_width is None:
            max_width = 500
        if max_height is None:
            max_height = 300

        if (plot_type is None) and ("markers" not in kwargs):
            kwargs["markers"] = "circle"

        with plot_widget:
            try:
                fig = plt.figure(1, **kwargs)
                if max_width is not None:
                    fig.layout.width = str(max_width) + "px"
                if max_height is not None:
                    fig.layout.height = str(max_height) + "px"

                plot_widget.outputs = ()
                if not overlay:
                    plt.clear()

                if plot_type is None:
                    if "marker" not in kwargs:
                        kwargs["marker"] = "circle"
                    plt.plot(x, y, **kwargs)
                elif plot_type == "bar":
                    plt.bar(x, y, **kwargs)
                elif plot_type == "scatter":
                    plt.scatter(x, y, **kwargs)
                elif plot_type == "hist":
                    plt.hist(y, **kwargs)
                plt.show()

            except Exception as e:
                print("Failed to create plot.")
                raise Exception(e)

    def add_layer_control(self, position: str = "topright") -> None:
        """Adds a layer control to the map.

        Args:
            position (str, optional): The position of the layer control on the map.
                Defaults to "topright".
        """
        if self.layer_control is None:
            layer_control = ipyleaflet.LayersControl(position=position)
            self.add(layer_control)

    addLayerControl = add_layer_control

    def add_legend(
        self,
        title: str = "Legend",
        legend_dict: Optional[Dict[str, str]] = None,
        keys: Optional[List[str]] = None,
        colors: Optional[List[str]] = None,
        position: str = "bottomright",
        builtin_legend: Optional[str] = None,
        layer_name: Optional[str] = None,
        add_header: bool = True,
        widget_args: Dict[str, Any] = {},
        **kwargs: Any,
    ) -> None:
        """Adds a customized basemap 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.
            layer_name (str, optional): The associated layer for the legend.
                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 {}.
        """
        try:
            legend = self._add_legend(
                title,
                legend_dict,
                keys,
                colors,
                position,
                builtin_legend,
                layer_name,
                add_header,
                widget_args,
                **kwargs,
            )
            self._legend = legend
            if not hasattr(self, "legends"):
                self.legends = [legend]
            else:
                self.legends.append(legend)
        except Exception as e:
            raise Exception(e)

    def add_colorbar(
        self,
        vis_params: Optional[Dict[str, Any]] = None,
        cmap: str = "gray",
        discrete: bool = False,
        label: Optional[str] = None,
        orientation: str = "horizontal",
        position: str = "bottomright",
        transparent_bg: bool = False,
        layer_name: Optional[str] = None,
        font_size: int = 9,
        axis_off: bool = False,
        max_width: Optional[str] = None,
        **kwargs: Any,
    ) -> None:
        """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 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 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".
            position (str, optional): Position of the colorbar on the map. It can be one of: topleft, topright, bottomleft, and bottomright. Defaults to "bottomright".
            transparent_bg (bool, optional): Whether to use transparent background. Defaults to False.
            layer_name (str, optional): The layer name associated with the colorbar. Defaults to None.
            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.
            TypeError: If the provided min value is not scalar type.
            TypeError: If the provided max value is not scalar type.
            TypeError: If the provided opacity value is not scalar type.
            TypeError: If cmap or palette is not provided.
        """

        colorbar = self._add_colorbar(
            vis_params,
            cmap,
            discrete,
            label,
            orientation,
            position,
            transparent_bg,
            layer_name,
            font_size,
            axis_off,
            max_width,
            **kwargs,
        )
        self._colorbar = colorbar
        if not hasattr(self, "colorbars"):
            self.colorbars = [colorbar]
        else:
            self.colorbars.append(colorbar)

    def remove_colorbar(self) -> None:
        """Removes the colorbar from the map."""
        if hasattr(self, "_colorbar") and self._colorbar is not None:
            self.remove_control(self._colorbar)

    def remove_colorbars(self) -> None:
        """Removes all colorbars from the map."""
        for layer in self.ee_layers.values():
            if widget := layer.pop("colorbar", None):
                self.remove(widget)
        if hasattr(self, "colorbars"):
            for colorbar in self.colorbars:
                if colorbar in self.controls:
                    self.remove_control(colorbar)

    def remove_legend(self) -> None:
        """Removes the legend from the map."""
        if hasattr(self, "_legend") and self._legend is not None:
            if self._legend in self.controls:
                self.remove_control(self._legend)

    def remove_legends(self) -> None:
        """Removes all legends from the map."""
        for layer in self.ee_layers.values():
            if widget := layer.pop("legend", None):
                self.remove(widget)
        if hasattr(self, "legends"):
            for legend in self.legends:
                if legend in self.controls:
                    self.remove_control(legend)

    def create_vis_widget(self, layer_dict: Dict[str, Any]) -> None:
        """Creates a GUI for changing layer visualization parameters interactively.

        Args:
            layer_dict (Dict[str, Any]): A dictionary containing information about
                the layer. It is an element from Map.ee_layers.
        """
        self._add_layer_editor(position="topright", layer_dict=layer_dict)

    def add_inspector(
        self,
        names: Optional[Union[str, List[str]]] = None,
        visible: bool = True,
        decimals: int = 2,
        position: str = "topright",
        opened: bool = True,
        show_close_button: bool = True,
    ) -> None:
        """Add the Inspector GUI to the map.

        Args:
            names (str | list, optional): The names of the layers to be included. 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 coordinates. Defaults to 2.
            position (str, optional): The position of the Inspector GUI. Defaults to "topright".
            opened (bool, optional): Whether the control is opened. Defaults to True.
        """
        super()._add_inspector(
            position,
            names=names,
            visible=visible,
            decimals=decimals,
            opened=opened,
            show_close_button=show_close_button,
        )

    def add_layer_manager(
        self,
        position: str = "topright",
        opened: bool = True,
        show_close_button: bool = True,
    ) -> None:
        """Add the Layer Manager to the map.

        Args:
            position (str, optional): The position of the Layer Manager. Defaults to "topright".
            opened (bool, optional): Whether the control is opened. Defaults to True.
            show_close_button (bool, optional): Whether to show the close button. Defaults to True.
        """
        super()._add_layer_manager(position)
        if layer_manager := self._layer_manager:
            layer_manager.collapsed = not opened
            layer_manager.close_button_hidden = not show_close_button

    def _on_basemap_changed(self, basemap_name: str) -> None:
        """Handles the event when the basemap is changed.

        Args:
            basemap_name (str): The name of the new basemap.
        """
        if basemap_name not in self.get_layer_names():
            self.add_basemap(basemap_name)
            if basemap_name in self._xyz_dict:
                if "bounds" in self._xyz_dict[basemap_name]:
                    bounds = self._xyz_dict[basemap_name]["bounds"]
                    bounds = [bounds[0][1], bounds[0][0], bounds[1][1], bounds[1][0]]
                    self.zoom_to_bounds(bounds)

    def add_basemap_widget(self, position: str = "topright") -> None:
        """Add the Basemap GUI to the map.

        Args:
            position (str, optional): The position of the Basemap GUI. Defaults to "topright".
        """
        super()._add_basemap_selector(position=position)

    def add_draw_control(self, position: str = "topleft") -> None:
        """Add a draw control to the map.

        Args:
            position (str, optional): The position of the draw control. Defaults to "topleft".
        """
        super().add("draw_control", position=position)

    def add_draw_control_lite(self, position: str = "topleft") -> None:
        """Add a lite version draw control to the map for the plotting tool.

        Args:
            position (str, optional): The position of the draw control. Defaults to "topleft".
        """
        super().add(
            "draw_control",
            position=position,
            marker={},
            rectangle={"shapeOptions": {"color": "#3388ff"}},
            circle={"shapeOptions": {"color": "#3388ff"}},
            circlemarker={},
            polyline={},
            polygon={},
            edit=False,
            remove=False,
        )

    def add_toolbar(self, position: str = "topright", **kwargs: Any) -> None:
        """Add a toolbar to the map.

        Args:
            position (str, optional): The position of the toolbar. Defaults to "topright".
            **kwargs: Additional keyword arguments.
        """
        self.add("toolbar", position, **kwargs)

    def _toolbar_main_tools(self) -> Any:
        """Gets the main tools for the toolbar.

        Returns:
            Any: The main tools for the toolbar.
        """
        return toolbar.main_tools

    def _toolbar_extra_tools(self) -> Any:
        """Gets the extra tools for the toolbar.

        Returns:
            Any: The extra tools for the toolbar.
        """
        return toolbar.extra_tools

    def add_plot_gui(self, position: str = "topright", **kwargs: Any) -> None:
        """Adds the plot widget to the map.

        Args:
            position (str, optional): Position of the widget. Defaults to "topright".
            **kwargs: Additional keyword arguments.
        """
        from .toolbar import ee_plot_gui

        ee_plot_gui(self, position, **kwargs)

    def add_gui(
        self,
        name: str,
        position: str = "topright",
        opened: bool = True,
        show_close_button: bool = True,
        **kwargs: Any,
    ) -> None:
        """Add a GUI to the map.

        Args:
            name (str): The name of the GUI. Options include "layer_manager",
                "inspector", "plot", and "timelapse".
            position (str, optional): The position of the GUI. Defaults to "topright".
            opened (bool, optional): Whether the GUI is opened. Defaults to True.
            show_close_button (bool, optional): Whether to show the close button.
                Defaults to True.
            **kwargs: Additional keyword arguments.
        """
        name = name.lower()
        if name == "layer_manager":
            self.add_layer_manager(position, opened, show_close_button, **kwargs)
        elif name == "inspector":
            self.add_inspector(
                position=position,
                opened=opened,
                show_close_button=show_close_button,
                **kwargs,
            )
        elif name == "plot":
            self.add_plot_gui(position, **kwargs)
        elif name == "timelapse":
            from .toolbar import timelapse_gui

            timelapse_gui(self, **kwargs)

    # ******************************************************************************#
    # The classes and functions above are the core features of the geemap package.  #
    # The Earth Engine team and the geemap community will maintain these features.  #
    # ******************************************************************************#

    # ******************************************************************************#
    # The classes and functions below are the extra features of the geemap package. #
    # The geemap community will maintain these features.                            #
    # ******************************************************************************#

    def draw_layer_on_top(self):
        """Move user-drawn feature layer to the top of all layers."""
        draw_layer_index = self.find_layer_index(name="Drawn Features")
        if draw_layer_index > -1 and draw_layer_index < (len(self.layers) - 1):
            layers = list(self.layers)
            layers = (
                layers[0:draw_layer_index]
                + layers[(draw_layer_index + 1) :]
                + [layers[draw_layer_index]]
            )
            self.layers = layers

    def add_marker(self, location, **kwargs):
        """Adds a marker to the map. More info about marker at https://ipyleaflet.readthedocs.io/en/latest/api_reference/marker.html.

        Args:
            location (list | tuple): The location of the marker in the format of [lat, lng].

            **kwargs: Keyword arguments for the marker.
        """
        if isinstance(location, list):
            location = tuple(location)
        if isinstance(location, tuple):
            marker = ipyleaflet.Marker(location=location, **kwargs)
            self.add(marker)
        else:
            raise TypeError("The location must be a list or a tuple.")

    def add_wms_layer(
        self,
        url,
        layers,
        name=None,
        attribution="",
        format="image/png",
        transparent=True,
        opacity=1.0,
        shown=True,
        **kwargs,
    ):
        """Add a WMS layer to the map.

        Args:
            url (str): The URL of the WMS web service.
            layers (str): Comma-separated list of WMS layers to show.
            name (str, optional): The layer name to use on the layer control. Defaults to None.
            attribution (str, optional): The attribution of the data layer. Defaults to ''.
            format (str, optional): WMS image format (use ‘image/png’ for layers with transparency). Defaults to 'image/png'.
            transparent (bool, optional): If True, the WMS service will return images with transparency. Defaults to True.
            opacity (float, optional): The opacity of the layer. Defaults to 1.0.
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        """

        if name is None:
            name = str(layers)

        try:
            wms_layer = ipyleaflet.WMSLayer(
                url=url,
                layers=layers,
                name=name,
                attribution=attribution,
                format=format,
                transparent=transparent,
                opacity=opacity,
                visible=shown,
                **kwargs,
            )
            self.add(wms_layer)

        except Exception as e:
            print("Failed to add the specified WMS TileLayer.")
            raise Exception(e)

    def zoom_to_me(self, zoom=14, add_marker=True):
        """Zoom to the current device location.

        Args:
            zoom (int, optional): Zoom level. Defaults to 14.
            add_marker (bool, optional): Whether to add a marker of the current device location. Defaults to True.
        """
        lat, lon = get_current_latlon()
        self.set_center(lon, lat, zoom)

        if add_marker:
            marker = ipyleaflet.Marker(
                location=(lat, lon),
                draggable=False,
                name="Device location",
            )
            self.add(marker)

    def zoom_to_gdf(self, gdf):
        """Zooms to the bounding box of a GeoPandas GeoDataFrame.

        Args:
            gdf (GeoDataFrame): A GeoPandas GeoDataFrame.
        """
        bounds = gdf.total_bounds
        self.zoom_to_bounds(bounds)

    def get_bounds(self, asGeoJSON=False):
        """Returns the bounds of the current map view, as a list in the format [west, south, east, north] in degrees.

        Args:
            asGeoJSON (bool, optional): If true, returns map bounds as GeoJSON. Defaults to False.

        Returns:
            list | dict: A list in the format [west, south, east, north] in degrees.
        """
        return super().get_bounds(as_geojson=asGeoJSON)

    def add_cog_layer(
        self,
        url,
        name="Untitled",
        attribution="",
        opacity=1.0,
        shown=True,
        bands=None,
        titiler_endpoint=None,
        **kwargs,
    ):
        """Adds a COG TileLayer to the map.

        Args:
            url (str): The URL of the COG tile layer.
            name (str, optional): The layer name to use for the layer. Defaults to 'Untitled'.
            attribution (str, optional): The attribution to use. Defaults to ''.
            opacity (float, optional): The opacity of the layer. Defaults to 1.
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
            bands (list, optional): A list of bands to use for the layer. Defaults to None.
            titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
            **kwargs: Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale, color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/ and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3]
        """

        tile_url = cog_tile(url, bands, titiler_endpoint, **kwargs)
        bounds = cog_bounds(url, titiler_endpoint)
        self.add_tile_layer(tile_url, name, attribution, opacity, shown)
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

        if not hasattr(self, "cog_layer_dict"):
            self.cog_layer_dict = {}

        params = {
            "url": url,
            "titizer_endpoint": titiler_endpoint,
            "bounds": bounds,
            "type": "COG",
        }
        self.cog_layer_dict[name] = params

    def add_cog_mosaic(self, **kwargs):
        raise NotImplementedError(
            "This function is no longer supported.See https://github.com/giswqs/leafmap/issues/180."
        )

    def add_stac_layer(
        self,
        url=None,
        collection=None,
        item=None,
        assets=None,
        bands=None,
        titiler_endpoint=None,
        name="STAC Layer",
        attribution="",
        opacity=1.0,
        shown=True,
        **kwargs,
    ):
        """Adds a STAC TileLayer to the map.

        Args:
            url (str): HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json
            collection (str): The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.
            item (str): The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.
            assets (str | list): The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"].
            bands (list): A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]
            titiler_endpoint (str, optional): Titiler endpoint, e.g., "https://titiler.xyz", "https://planetarycomputer.microsoft.com/api/data/v1", "planetary-computer", "pc". Defaults to None.
            name (str, optional): The layer name to use for the layer. Defaults to 'STAC Layer'.
            attribution (str, optional): The attribution to use. Defaults to ''.
            opacity (float, optional): The opacity of the layer. Defaults to 1.
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        """
        tile_url = stac_tile(
            url, collection, item, assets, bands, titiler_endpoint, **kwargs
        )
        bounds = stac_bounds(url, collection, item, titiler_endpoint)
        self.add_tile_layer(tile_url, name, attribution, opacity, shown)
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

        if not hasattr(self, "cog_layer_dict"):
            self.cog_layer_dict = {}

        if assets is None and bands is not None:
            assets = bands

        params = {
            "url": url,
            "collection": collection,
            "item": item,
            "assets": assets,
            "bounds": bounds,
            "titiler_endpoint": titiler_endpoint,
            "type": "STAC",
        }

        self.cog_layer_dict[name] = params

    def add_minimap(self, zoom=5, position="bottomright"):
        """Adds a minimap (overview) to the ipyleaflet map.

        Args:
            zoom (int, optional): Initial map zoom level. Defaults to 5.
            position (str, optional): Position of the minimap. Defaults to "bottomright".
        """
        minimap = ipyleaflet.Map(
            zoom_control=False,
            attribution_control=False,
            zoom=zoom,
            center=self.center,
            layers=[get_basemap("ROADMAP")],
        )
        minimap.layout.width = "150px"
        minimap.layout.height = "150px"
        ipyleaflet.link((minimap, "center"), (self, "center"))
        minimap_control = ipyleaflet.WidgetControl(widget=minimap, position=position)
        self.add(minimap_control)

    def marker_cluster(self):
        """Adds a marker cluster to the map and returns a list of ee.Feature, which can be accessed using Map.ee_marker_cluster.

        Returns:
            object: a list of ee.Feature
        """
        coordinates = []
        markers = []
        marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")
        self.last_click = []
        self.all_clicks = []
        self.ee_markers = []
        self.add(marker_cluster)

        def handle_interaction(**kwargs):
            latlon = kwargs.get("coordinates")
            if kwargs.get("type") == "click":
                coordinates.append(latlon)
                geom = ee.Geometry.Point(latlon[1], latlon[0])
                feature = ee.Feature(geom)
                self.ee_markers.append(feature)
                self.last_click = latlon
                self.all_clicks = coordinates
                markers.append(ipyleaflet.Marker(location=latlon))
                marker_cluster.markers = markers
            elif kwargs.get("type") == "mousemove":
                pass

        # cursor style: https://www.w3schools.com/cssref/pr_class_cursor.asp
        self.default_style = {"cursor": "crosshair"}
        self.on_interaction(handle_interaction)

    def plot_demo(
        self,
        iterations=20,
        plot_type=None,
        overlay=False,
        position="bottomright",
        min_width=None,
        max_width=None,
        min_height=None,
        max_height=None,
        **kwargs,
    ):
        """A demo of interactive plotting using random pixel coordinates.

        Args:
            iterations (int, optional): How many iterations to run for the demo. Defaults to 20.
            plot_type (str, optional): The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.
            overlay (bool, optional): Whether to overlay plotted lines on the figure. Defaults to False.
            position (str, optional): Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
            min_width (int, optional): Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
            max_width (int, optional): Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
            min_height (int, optional): Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
            max_height (int, optional): Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.
        """

        import numpy as np
        import time

        if hasattr(self, "random_marker") and self.random_marker is not None:
            self.remove_layer(self.random_marker)

        image = ee.Image("LANDSAT/LE7_TOA_5YEAR/1999_2003").select([0, 1, 2, 3, 4, 6])
        self.addLayer(
            image,
            {"bands": ["B4", "B3", "B2"], "gamma": 1.4},
            "LANDSAT/LE7_TOA_5YEAR/1999_2003",
        )
        self.setCenter(-50.078877, 25.190030, 3)
        band_names = image.bandNames().getInfo()
        # band_count = len(band_names)

        latitudes = np.random.uniform(30, 48, size=iterations)
        longitudes = np.random.uniform(-121, -76, size=iterations)

        marker = ipyleaflet.Marker(location=(0, 0))
        self.random_marker = marker
        self.add(marker)

        for i in range(iterations):
            try:
                coordinate = ee.Geometry.Point([longitudes[i], latitudes[i]])
                dict_values = image.sample(coordinate).first().toDictionary().getInfo()
                band_values = list(dict_values.values())
                title = "{}/{}: Spectral signature at ({}, {})".format(
                    i + 1,
                    iterations,
                    round(latitudes[i], 2),
                    round(longitudes[i], 2),
                )
                marker.location = (latitudes[i], longitudes[i])
                self.plot(
                    band_names,
                    band_values,
                    plot_type=plot_type,
                    overlay=overlay,
                    min_width=min_width,
                    max_width=max_width,
                    min_height=min_height,
                    max_height=max_height,
                    title=title,
                    **kwargs,
                )
                time.sleep(0.3)
            except Exception as e:
                raise Exception(e)

    def plot_raster(
        self,
        ee_object=None,
        sample_scale=None,
        plot_type=None,
        overlay=False,
        position="bottomright",
        min_width=None,
        max_width=None,
        min_height=None,
        max_height=None,
        **kwargs,
    ):
        """Interactive plotting of Earth Engine data by clicking on the map.

        Args:
            ee_object (object, optional): The ee.Image or ee.ImageCollection to sample. Defaults to None.
            sample_scale (float, optional): A nominal scale in meters of the projection to sample in. Defaults to None.
            plot_type (str, optional): The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.
            overlay (bool, optional): Whether to overlay plotted lines on the figure. Defaults to False.
            position (str, optional): Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
            min_width (int, optional): Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
            max_width (int, optional): Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
            min_height (int, optional): Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
            max_height (int, optional): Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

        """
        if hasattr(self, "_plot_control") and self._plot_control is not None:
            del self._plot_widget
            if self._plot_control in self.controls:
                self.remove_control(self._plot_control)

        if hasattr(self, "random_marker") and self.random_marker is not None:
            self.remove_layer(self.random_marker)

        plot_widget = widgets.Output(layout={"border": "1px solid black"})
        plot_control = ipyleaflet.WidgetControl(
            widget=plot_widget,
            position=position,
            min_width=min_width,
            max_width=max_width,
            min_height=min_height,
            max_height=max_height,
        )
        self._plot_widget = plot_widget
        self._plot_control = plot_control
        self.add(plot_control)

        self.default_style = {"cursor": "crosshair"}
        msg = "The plot function can only be used on ee.Image or ee.ImageCollection with more than one band."
        if (ee_object is None) and len(self.ee_raster_layers) > 0:
            ee_object = self.ee_raster_layers.values()[-1]["ee_object"]
            if isinstance(ee_object, ee.ImageCollection):
                ee_object = ee_object.mosaic()
        elif isinstance(ee_object, ee.ImageCollection):
            ee_object = ee_object.mosaic()
        elif not isinstance(ee_object, ee.Image):
            print(msg)
            return

        if sample_scale is None:
            sample_scale = self.getScale()

        if max_width is None:
            max_width = 500

        band_names = ee_object.bandNames().getInfo()

        coordinates = []
        markers = []
        marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")
        self.last_click = []
        self.all_clicks = []
        self.add(marker_cluster)

        def handle_interaction(**kwargs2):
            latlon = kwargs2.get("coordinates")

            if kwargs2.get("type") == "click":
                try:
                    coordinates.append(latlon)
                    self.last_click = latlon
                    self.all_clicks = coordinates
                    markers.append(ipyleaflet.Marker(location=latlon))
                    marker_cluster.markers = markers
                    self.default_style = {"cursor": "wait"}
                    xy = ee.Geometry.Point(latlon[::-1])
                    dict_values = (
                        ee_object.sample(xy, scale=sample_scale)
                        .first()
                        .toDictionary()
                        .getInfo()
                    )
                    band_values = list(dict_values.values())
                    self.plot(
                        band_names,
                        band_values,
                        plot_type=plot_type,
                        overlay=overlay,
                        min_width=min_width,
                        max_width=max_width,
                        min_height=min_height,
                        max_height=max_height,
                        **kwargs,
                    )
                    self.default_style = {"cursor": "crosshair"}
                except Exception as e:
                    if self._plot_widget is not None:
                        with self._plot_widget:
                            self._plot_widget.outputs = ()
                            print("No data for the clicked location.")
                    else:
                        print(e)
                    self.default_style = {"cursor": "crosshair"}

        self.on_interaction(handle_interaction)

    def add_marker_cluster(self, event="click", add_marker=True):
        """Captures user inputs and add markers to the map.

        Args:
            event (str, optional): [description]. Defaults to 'click'.
            add_marker (bool, optional): If True, add markers to the map. Defaults to True.

        Returns:
            object: a marker cluster.
        """
        coordinates = []
        markers = []
        marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")
        self.last_click = []
        self.all_clicks = []
        if add_marker:
            self.add(marker_cluster)

        def handle_interaction(**kwargs):
            latlon = kwargs.get("coordinates")

            if event == "click" and kwargs.get("type") == "click":
                coordinates.append(latlon)
                self.last_click = latlon
                self.all_clicks = coordinates
                if add_marker:
                    markers.append(ipyleaflet.Marker(location=latlon))
                    marker_cluster.markers = markers
            elif kwargs.get("type") == "mousemove":
                pass

        # cursor style: https://www.w3schools.com/cssref/pr_class_cursor.asp
        self.default_style = {"cursor": "crosshair"}
        self.on_interaction(handle_interaction)

    def set_control_visibility(
        self, layerControl=True, fullscreenControl=True, latLngPopup=True
    ):
        """Sets the visibility of the controls on the map.

        Args:
            layerControl (bool, optional): Whether to show the control that allows the user to toggle layers on/off. Defaults to True.
            fullscreenControl (bool, optional): Whether to show the control that allows the user to make the map full-screen. Defaults to True.
            latLngPopup (bool, optional): Whether to show the control that pops up the Lat/lon when the user clicks on the map. Defaults to True.
        """
        pass

    setControlVisibility = set_control_visibility

    def split_map(
        self,
        left_layer="OpenTopoMap",
        right_layer="Esri.WorldTopoMap",
        zoom_control=True,
        fullscreen_control=True,
        layer_control=True,
        add_close_button=False,
        close_button_position="topright",
        left_label=None,
        right_label=None,
        left_position="bottomleft",
        right_position="bottomright",
        widget_layout=None,
        **kwargs,
    ):
        """Adds split map.

        Args:
            left_layer (str, optional): The layer tile layer. Defaults to 'OpenTopoMap'.
            right_layer (str, optional): The right tile layer. Defaults to 'Esri.WorldTopoMap'.
            zoom_control (bool, optional): Whether to show the zoom control. Defaults to True.
            fullscreen_control (bool, optional): Whether to show the full screen control. Defaults to True.
            layer_control (bool, optional): Whether to show the layer control. Defaults to True.
            add_close_button (bool, optional): Whether to add a close button. Defaults to False.
            close_button_position (str, optional): The position of the close button. Defaults to 'topright'.
            left_label (str, optional): The label for the left map. Defaults to None.
            right_label (str, optional): The label for the right map. Defaults to None.
            left_position (str, optional): The position of the left label. Defaults to 'bottomleft'.
            right_position (str, optional): The position of the right label. Defaults to 'bottomright'.
            widget_layout (str, optional): The layout of the label widget, such as ipywidgets.Layout(padding="0px 4px 0px 4px"). Defaults to None.
            kwargs: Other arguments for ipyleaflet.TileLayer.
        """
        if "max_zoom" not in kwargs:
            kwargs["max_zoom"] = 100
        if "max_native_zoom" not in kwargs:
            kwargs["max_native_zoom"] = 100
        try:
            controls = self.controls
            layers = self.layers
            self.clear_controls()

            if zoom_control:
                self.add(ipyleaflet.ZoomControl())
            if fullscreen_control:
                self.add(ipyleaflet.FullScreenControl())

            if left_label is not None:
                left_name = left_label
            else:
                left_name = "Left Layer"

            if right_label is not None:
                right_name = right_label
            else:
                right_name = "Right Layer"

            if "attribution" not in kwargs:
                kwargs["attribution"] = " "

            if left_layer in basemaps.keys():
                left_layer = get_basemap(left_layer)
            elif isinstance(left_layer, str):
                if left_layer.startswith("http") and left_layer.endswith(".tif"):
                    url = cog_tile(left_layer)
                    left_layer = ipyleaflet.TileLayer(
                        url=url,
                        name=left_name,
                        **kwargs,
                    )
                else:
                    left_layer = ipyleaflet.TileLayer(
                        url=left_layer,
                        name=left_name,
                        **kwargs,
                    )
            elif isinstance(left_layer, ipyleaflet.TileLayer):
                pass
            else:
                raise ValueError(
                    f"left_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
                )

            if right_layer in basemaps.keys():
                right_layer = get_basemap(right_layer)
            elif isinstance(right_layer, str):
                if right_layer.startswith("http") and right_layer.endswith(".tif"):
                    url = cog_tile(right_layer)
                    right_layer = ipyleaflet.TileLayer(
                        url=url,
                        name=right_name,
                        **kwargs,
                    )
                else:
                    right_layer = ipyleaflet.TileLayer(
                        url=right_layer,
                        name=right_name,
                        **kwargs,
                    )
            elif isinstance(right_layer, ipyleaflet.TileLayer):
                pass
            else:
                raise ValueError(
                    f"right_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
                )

            control = ipyleaflet.SplitMapControl(
                left_layer=left_layer, right_layer=right_layer
            )

            self.add(control)
            # self.dragging = False

            if left_label is not None:
                if widget_layout is None:
                    widget_layout = widgets.Layout(padding="0px 4px 0px 4px")
                left_widget = widgets.HTML(value=left_label, layout=widget_layout)

                left_control = ipyleaflet.WidgetControl(
                    widget=left_widget, position=left_position
                )
                self.add(left_control)

            if right_label is not None:
                if widget_layout is None:
                    widget_layout = widgets.Layout(padding="0px 4px 0px 4px")
                right_widget = widgets.HTML(value=right_label, layout=widget_layout)
                right_control = ipyleaflet.WidgetControl(
                    widget=right_widget, position=right_position
                )
                self.add(right_control)

            close_button = widgets.ToggleButton(
                value=False,
                tooltip="Close split-panel map",
                icon="times",
                layout=widgets.Layout(
                    height="28px", width="28px", padding="0px 0px 0px 4px"
                ),
            )

            def close_btn_click(change):
                if left_label is not None:
                    self.remove_control(left_control)

                if right_label is not None:
                    self.remove_control(right_control)

                if change["new"]:
                    self.controls = controls
                    self.layers = layers[:-1]
                    self.add(layers[-1])

                # self.dragging = True

            close_button.observe(close_btn_click, "value")
            close_control = ipyleaflet.WidgetControl(
                widget=close_button, position=close_button_position
            )

            if add_close_button:
                self.add(close_control)

            if layer_control:
                self.addLayerControl()

        except Exception as e:
            print("The provided layers are invalid!")
            raise ValueError(e)

    def ts_inspector(
        self,
        left_ts,
        left_names=None,
        left_vis={},
        left_index=0,
        right_ts=None,
        right_names=None,
        right_vis=None,
        right_index=-1,
        width="130px",
        date_format="YYYY-MM-dd",
        add_close_button=False,
        **kwargs,
    ):
        """Creates a split-panel map for inspecting timeseries images.

        Args:
            left_ts (object): An ee.ImageCollection to show on the left panel.
            left_names (list): A list of names to show under the left dropdown.
            left_vis (dict, optional): Visualization parameters for the left layer. Defaults to {}.
            left_index (int, optional): The index of the left layer to show. Defaults to 0.
            right_ts (object): An ee.ImageCollection to show on the right panel.
            right_names (list): A list of names to show under the right dropdown.
            right_vis (dict, optional): Visualization parameters for the right layer. Defaults to {}.
            right_index (int, optional): The index of the right layer to show. Defaults to -1.
            width (str, optional): The width of the dropdown list. Defaults to '130px'.
            date_format (str, optional): The date format to show in the dropdown. Defaults to 'YYYY-MM-dd'.
            add_close_button (bool, optional): Whether to show the close button. Defaults to False.
        """
        controls = self.controls
        layers = self.layers

        if left_names is None:
            left_names = image_dates(left_ts, date_format=date_format).getInfo()

        if right_ts is None:
            right_ts = left_ts

        if right_names is None:
            right_names = left_names

        if right_vis is None:
            right_vis = left_vis

        left_count = int(left_ts.size().getInfo())
        right_count = int(right_ts.size().getInfo())

        if left_count != len(left_names):
            print(
                "The number of images in left_ts must match the number of layer names in left_names."
            )
            return
        if right_count != len(right_names):
            print(
                "The number of images in right_ts must match the number of layer names in right_names."
            )
            return

        left_layer = ipyleaflet.TileLayer(
            url="https://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer/tile/{z}/{y}/{x}",
            attribution="Esri",
            name="Esri.WorldStreetMap",
        )
        right_layer = ipyleaflet.TileLayer(
            url="https://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer/tile/{z}/{y}/{x}",
            attribution="Esri",
            name="Esri.WorldStreetMap",
        )

        self.clear_controls()
        left_dropdown = widgets.Dropdown(options=left_names, value=None)
        right_dropdown = widgets.Dropdown(options=right_names, value=None)
        left_dropdown.layout.max_width = width
        right_dropdown.layout.max_width = width

        left_control = ipyleaflet.WidgetControl(
            widget=left_dropdown, position="topleft"
        )
        right_control = ipyleaflet.WidgetControl(
            widget=right_dropdown, position="topright"
        )

        self.add(left_control)
        self.add(right_control)

        self.add(ipyleaflet.ZoomControl(position="topleft"))
        self.add(ipyleaflet.ScaleControl(position="bottomleft"))
        self.add(ipyleaflet.FullScreenControl())

        def left_dropdown_change(change):
            left_dropdown_index = left_dropdown.index
            if left_dropdown_index is not None and left_dropdown_index >= 0:
                try:
                    if isinstance(left_ts, ee.ImageCollection):
                        left_image = left_ts.toList(left_ts.size()).get(
                            left_dropdown_index
                        )
                    elif isinstance(left_ts, ee.List):
                        left_image = left_ts.get(left_dropdown_index)
                    else:
                        print("The left_ts argument must be an ImageCollection.")
                        return

                    if isinstance(left_image, ee.ImageCollection):
                        left_image = ee.Image(left_image.mosaic())
                    elif isinstance(left_image, ee.Image):
                        pass
                    else:
                        left_image = ee.Image(left_image)

                    left_image = EELeafletTileLayer(
                        left_image, left_vis, left_names[left_dropdown_index]
                    )
                    left_layer.url = left_image.url
                except Exception as e:
                    print(e)
                    return

        left_dropdown.observe(left_dropdown_change, names="value")

        def right_dropdown_change(change):
            right_dropdown_index = right_dropdown.index
            if right_dropdown_index is not None and right_dropdown_index >= 0:
                try:
                    if isinstance(right_ts, ee.ImageCollection):
                        right_image = right_ts.toList(left_ts.size()).get(
                            right_dropdown_index
                        )
                    elif isinstance(right_ts, ee.List):
                        right_image = right_ts.get(right_dropdown_index)
                    else:
                        print("The left_ts argument must be an ImageCollection.")
                        return

                    if isinstance(right_image, ee.ImageCollection):
                        right_image = ee.Image(right_image.mosaic())
                    elif isinstance(right_image, ee.Image):
                        pass
                    else:
                        right_image = ee.Image(right_image)

                    right_image = EELeafletTileLayer(
                        right_image,
                        right_vis,
                        right_names[right_dropdown_index],
                    )
                    right_layer.url = right_image.url
                except Exception as e:
                    print(e)
                    return

        right_dropdown.observe(right_dropdown_change, names="value")

        if left_index is not None:
            left_dropdown.value = left_names[left_index]
        if right_index is not None:
            right_dropdown.value = right_names[right_index]

        close_button = widgets.ToggleButton(
            value=False,
            tooltip="Close the tool",
            icon="times",
            # button_style="primary",
            layout=widgets.Layout(
                height="28px", width="28px", padding="0px 0px 0px 4px"
            ),
        )

        def close_btn_click(change):
            if change["new"]:
                self.controls = controls
                self.clear_layers()
                self.layers = layers

        close_button.observe(close_btn_click, "value")
        close_control = ipyleaflet.WidgetControl(
            widget=close_button, position="bottomright"
        )

        try:
            split_control = ipyleaflet.SplitMapControl(
                left_layer=left_layer, right_layer=right_layer
            )
            self.add(split_control)
            # self.dragging = False

            if add_close_button:
                self.add(close_control)

        except Exception as e:
            raise Exception(e)

    def basemap_demo(self):
        """A demo for using geemap basemaps."""
        self.add_basemap_widget()

    def add_colorbar_branca(
        self,
        colors,
        vmin=0,
        vmax=1.0,
        index=None,
        caption="",
        categorical=False,
        step=None,
        height="45px",
        transparent_bg=False,
        position="bottomright",
        layer_name=None,
        **kwargs,
    ):
        """Add a branca colorbar to the map.

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

        """
        from branca.colormap import LinearColormap

        output = widgets.Output()
        output.layout.height = height

        if "width" in kwargs:
            output.layout.width = kwargs["width"]

        if isinstance(colors, Box):
            try:
                colors = list(colors["default"])
            except Exception as e:
                print("The provided color list is invalid.")
                raise Exception(e)

        if all(len(color) == 6 for color in colors):
            colors = ["#" + color for color in colors]

        colormap = LinearColormap(
            colors=colors, index=index, vmin=vmin, vmax=vmax, caption=caption
        )

        if categorical:
            if step is not None:
                colormap = colormap.to_step(step)
            elif index is not None:
                colormap = colormap.to_step(len(index) - 1)
            else:
                colormap = colormap.to_step(3)

        colormap_ctrl = ipyleaflet.WidgetControl(
            widget=output,
            position=position,
            transparent_bg=transparent_bg,
            **kwargs,
        )
        with output:
            output.outputs = ()
            display(colormap)

        self._colorbar = colormap_ctrl
        self.add(colormap_ctrl)

        if not hasattr(self, "colorbars"):
            self.colorbars = [colormap_ctrl]
        else:
            self.colorbars.append(colormap_ctrl)

        if layer_name in self.ee_layers:
            self.ee_layers[layer_name]["colorbar"] = colormap_ctrl

    def image_overlay(self, url, bounds, name):
        """Overlays an image from the Internet or locally on the map.

        Args:
            url (str): http URL or local file path to the image.
            bounds (tuple): bounding box of the image in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).
            name (str): name of the layer to show on the layer control.
        """
        from base64 import b64encode
        from io import BytesIO

        from PIL import Image, ImageSequence

        try:
            if not url.startswith("http"):
                if not os.path.exists(url):
                    print("The provided file does not exist.")
                    return

                ext = os.path.splitext(url)[1][1:]  # file extension
                image = Image.open(url)

                f = BytesIO()
                if ext.lower() == "gif":
                    frames = []
                    # Loop over each frame in the animated image
                    for frame in ImageSequence.Iterator(image):
                        frame = frame.convert("RGBA")
                        b = BytesIO()
                        frame.save(b, format="gif")
                        frame = Image.open(b)
                        frames.append(frame)
                    frames[0].save(
                        f,
                        format="GIF",
                        save_all=True,
                        append_images=frames[1:],
                        loop=0,
                    )
                else:
                    image.save(f, ext)

                data = b64encode(f.getvalue())
                data = data.decode("ascii")
                url = "data:image/{};base64,".format(ext) + data
            img = ipyleaflet.ImageOverlay(url=url, bounds=bounds, name=name)
            self.add(img)
        except Exception as e:
            print(e)

    def video_overlay(self, url, bounds, name="Video"):
        """Overlays a video from the Internet on the map.

        Args:
            url (str): http URL of the video, such as "https://www.mapbox.com/bites/00188/patricia_nasa.webm"
            bounds (tuple): bounding box of the video in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).
            name (str): name of the layer to show on the layer control.
        """
        try:
            video = ipyleaflet.VideoOverlay(url=url, bounds=bounds, name=name)
            self.add(video)
        except Exception as e:
            print(e)

    def add_landsat_ts_gif(
        self,
        layer_name="Timelapse",
        roi=None,
        label=None,
        start_year=1984,
        end_year=2021,
        start_date="06-10",
        end_date="09-20",
        bands=["NIR", "Red", "Green"],
        vis_params=None,
        dimensions=768,
        frames_per_second=10,
        font_size=30,
        font_color="white",
        add_progress_bar=True,
        progress_bar_color="white",
        progress_bar_height=5,
        out_gif=None,
        download=False,
        apply_fmask=True,
        nd_bands=None,
        nd_threshold=0,
        nd_palette=["black", "blue"],
    ):
        """Adds a Landsat timelapse to the map.

        Args:
            layer_name (str, optional): Layer name to show under the layer control. Defaults to 'Timelapse'.
            roi (object, optional): Region of interest to create the timelapse. Defaults to None.
            label (str, optional): A label to show on the GIF, such as place name. Defaults to None.
            start_year (int, optional): Starting year for the timelapse. Defaults to 1984.
            end_year (int, optional): Ending year for the timelapse. Defaults to 2021.
            start_date (str, optional): Starting date (month-day) each year for filtering ImageCollection. Defaults to '06-10'.
            end_date (str, optional): Ending date (month-day) each year for filtering ImageCollection. Defaults to '09-20'.
            bands (list, optional): Three bands selected from ['Blue', 'Green', 'Red', 'NIR', 'SWIR1', 'SWIR2', 'pixel_qa']. Defaults to ['NIR', 'Red', 'Green'].
            vis_params (dict, optional): Visualization parameters. Defaults to None.
            dimensions (int, optional): a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.
            frames_per_second (int, optional): Animation speed. Defaults to 10.
            font_size (int, optional): Font size of the animated text and label. Defaults to 30.
            font_color (str, optional): Font color of the animated text and label. Defaults to 'black'.
            add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF. Defaults to True.
            progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
            progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
            out_gif (str, optional): File path to the output animated GIF. Defaults to None.
            download (bool, optional): Whether to download the gif. Defaults to False.
            apply_fmask (bool, optional): Whether to apply Fmask (Function of mask) for automated clouds, cloud shadows, snow, and water masking.
            nd_bands (list, optional): A list of names specifying the bands to use, e.g., ['Green', 'SWIR1']. The normalized difference is computed as (first − second) / (first + second). Note that negative input values are forced to 0 so that the result is confined to the range (-1, 1).
            nd_threshold (float, optional): The threshold for extracting pixels from the normalized difference band.
            nd_palette (str, optional): The color palette to use for displaying the normalized difference band.

        """
        try:
            if roi is None:
                if self.draw_last_feature is not None:
                    feature = self.draw_last_feature
                    roi = feature.geometry()
                else:
                    roi = ee.Geometry.Polygon(
                        [
                            [
                                [-115.471773, 35.892718],
                                [-115.471773, 36.409454],
                                [-114.271283, 36.409454],
                                [-114.271283, 35.892718],
                                [-115.471773, 35.892718],
                            ]
                        ],
                        None,
                        False,
                    )
            elif isinstance(roi, ee.Feature) or isinstance(roi, ee.FeatureCollection):
                roi = roi.geometry()
            elif isinstance(roi, ee.Geometry):
                pass
            else:
                print("The provided roi is invalid. It must be an ee.Geometry")
                return

            geojson = ee_to_geojson(roi)
            bounds = minimum_bounding_box(geojson)
            geojson = adjust_longitude(geojson)
            roi = ee.Geometry(geojson)

            in_gif = landsat_timelapse(
                roi=roi,
                out_gif=out_gif,
                start_year=start_year,
                end_year=end_year,
                start_date=start_date,
                end_date=end_date,
                bands=bands,
                vis_params=vis_params,
                dimensions=dimensions,
                frames_per_second=frames_per_second,
                apply_fmask=apply_fmask,
                nd_bands=nd_bands,
                nd_threshold=nd_threshold,
                nd_palette=nd_palette,
                font_size=font_size,
                font_color=font_color,
                progress_bar_color=progress_bar_color,
                progress_bar_height=progress_bar_height,
            )
            in_nd_gif = in_gif.replace(".gif", "_nd.gif")

            if nd_bands is not None:
                add_text_to_gif(
                    in_nd_gif,
                    in_nd_gif,
                    xy=("2%", "2%"),
                    text_sequence=start_year,
                    font_size=font_size,
                    font_color=font_color,
                    duration=int(1000 / frames_per_second),
                    add_progress_bar=add_progress_bar,
                    progress_bar_color=progress_bar_color,
                    progress_bar_height=progress_bar_height,
                )

            if label is not None:
                add_text_to_gif(
                    in_gif,
                    in_gif,
                    xy=("2%", "90%"),
                    text_sequence=label,
                    font_size=font_size,
                    font_color=font_color,
                    duration=int(1000 / frames_per_second),
                    add_progress_bar=add_progress_bar,
                    progress_bar_color=progress_bar_color,
                    progress_bar_height=progress_bar_height,
                )
                # if nd_bands is not None:
                #     add_text_to_gif(in_nd_gif, in_nd_gif, xy=('2%', '90%'), text_sequence=label,
                #                     font_size=font_size, font_color=font_color, duration=int(1000 / frames_per_second), add_progress_bar=add_progress_bar, progress_bar_color=progress_bar_color, progress_bar_height=progress_bar_height)

            if is_tool("ffmpeg"):
                reduce_gif_size(in_gif)
                if nd_bands is not None:
                    reduce_gif_size(in_nd_gif)

            print("Adding GIF to the map ...")
            self.image_overlay(url=in_gif, bounds=bounds, name=layer_name)
            if nd_bands is not None:
                self.image_overlay(
                    url=in_nd_gif, bounds=bounds, name=layer_name + " ND"
                )
            print("The timelapse has been added to the map.")

            if download:
                link = create_download_link(
                    in_gif,
                    title="Click here to download the Landsat timelapse: ",
                )
                display(link)
                if nd_bands is not None:
                    link2 = create_download_link(
                        in_nd_gif,
                        title="Click here to download the Normalized Difference Index timelapse: ",
                    )
                    display(link2)

        except Exception as e:
            raise Exception(e)

    def to_html(
        self,
        filename=None,
        title="My Map",
        width="100%",
        height="880px",
        add_layer_control=True,
        **kwargs,
    ):
        """Saves the map as an HTML file.

        Args:
            filename (str, optional): The output file path to the HTML file.
            title (str, optional): The title of the HTML file. Defaults to 'My Map'.
            width (str, optional): The width of the map in pixels or percentage. Defaults to '100%'.
            height (str, optional): The height of the map in pixels. Defaults to '880px'.
            add_layer_control (bool, optional): Whether to add the LayersControl. Defaults to True.

        """
        try:
            save = True
            if filename is not None:
                if not filename.endswith(".html"):
                    raise ValueError("The output file extension must be html.")
                filename = os.path.abspath(filename)
                out_dir = os.path.dirname(filename)
                if not os.path.exists(out_dir):
                    os.makedirs(out_dir)
            else:
                filename = os.path.abspath(random_string() + ".html")
                save = False

            if add_layer_control and self.layer_control is None:
                layer_control = ipyleaflet.LayersControl(position="topright")
                self.layer_control = layer_control
                self.add(layer_control)

            before_width = self.layout.width
            before_height = self.layout.height

            if not isinstance(width, str):
                print("width must be a string.")
                return
            elif width.endswith("px") or width.endswith("%"):
                pass
            else:
                print("width must end with px or %")
                return

            if not isinstance(height, str):
                print("height must be a string.")
                return
            elif not height.endswith("px"):
                print("height must end with px")
                return

            self.layout.width = width
            self.layout.height = height

            self.save(filename, title=title, **kwargs)

            self.layout.width = before_width
            self.layout.height = before_height

            if not save:
                out_html = ""
                with open(filename) as f:
                    lines = f.readlines()
                    out_html = "".join(lines)
                os.remove(filename)
                return out_html

        except Exception as e:
            raise Exception(e)

    def to_image(self, filename=None, monitor=1):
        """Saves the map as a PNG or JPG image.

        Args:
            filename (str, optional): The output file path to the image. Defaults to None.
            monitor (int, optional): The monitor to take the screenshot. Defaults to 1.
        """
        self.screenshot = None

        if filename is None:
            filename = os.path.join(os.getcwd(), "my_map.png")

        if filename.endswith(".png") or filename.endswith(".jpg"):
            pass
        else:
            print("The output file must be a PNG or JPG image.")
            return

        work_dir = os.path.dirname(filename)
        if not os.path.exists(work_dir):
            os.makedirs(work_dir)

        screenshot = screen_capture(filename, monitor)
        self.screenshot = screenshot

    def toolbar_reset(self):
        """Reset the toolbar so that no tool is selected."""
        if hasattr(self, "_toolbar"):
            self._toolbar.reset()

    def add_raster(
        self,
        source,
        indexes=None,
        colormap=None,
        vmin=None,
        vmax=None,
        nodata=None,
        attribution=None,
        layer_name="Raster",
        zoom_to_layer=True,
        visible=True,
        array_args={},
        **kwargs,
    ):
        """Add a local raster dataset to the map.
            If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and
            if the raster does not render properly, try installing jupyter-server-proxy using `pip install jupyter-server-proxy`,
            then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

            import os
            os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = 'proxy/{port}'

        Args:
            source (str): The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
            indexes (int, optional): The band(s) to use. Band indexing starts at 1. Defaults to None.
            colormap (str, optional): The name of the colormap from `matplotlib` to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.
            vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
            vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
            nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
            attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
            layer_name (str, optional): The layer name to use. Defaults to 'Raster'.
            zoom_to_layer (bool, optional): Whether to zoom to the extent of the layer. Defaults to True.
            visible (bool, optional): Whether the layer is visible. Defaults to True.
            array_args (dict, optional): Additional arguments to pass to `array_to_memory_file` when reading the raster. Defaults to {}.
        """
        import numpy as np
        import xarray as xr

        if isinstance(source, np.ndarray) or isinstance(source, xr.DataArray):
            source = array_to_image(source, **array_args)

        tile_layer, tile_client = get_local_tile_layer(
            source,
            indexes=indexes,
            colormap=colormap,
            vmin=vmin,
            vmax=vmax,
            nodata=nodata,
            attribution=attribution,
            layer_name=layer_name,
            return_client=True,
            **kwargs,
        )
        tile_layer.visible = visible

        self.add(tile_layer)
        bounds = tile_client.bounds()  # [ymin, ymax, xmin, xmax]
        bounds = (
            bounds[2],
            bounds[0],
            bounds[3],
            bounds[1],
        )  # [minx, miny, maxx, maxy]
        if zoom_to_layer:
            self.zoom_to_bounds(bounds)

        arc_add_layer(tile_layer.url, layer_name, True, 1.0)
        if zoom_to_layer:
            arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

        if not hasattr(self, "cog_layer_dict"):
            self.cog_layer_dict = {}
        params = {
            "tile_layer": tile_layer,
            "tile_client": tile_client,
            "indexes": indexes,
            "band_names": tile_client.band_names,
            "bounds": bounds,
            "type": "LOCAL",
        }
        self.cog_layer_dict[layer_name] = params

    def add_remote_tile(
        self,
        source,
        band=None,
        palette=None,
        vmin=None,
        vmax=None,
        nodata=None,
        attribution=None,
        layer_name=None,
        **kwargs,
    ):
        """Add a remote Cloud Optimized GeoTIFF (COG) to the map.

        Args:
            source (str): The path to the remote Cloud Optimized GeoTIFF.
            band (int, optional): The band to use. Band indexing starts at 1. Defaults to None.
            palette (str, optional): The name of the color palette from `palettable` to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
            vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
            vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
            nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
            attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
            layer_name (str, optional): The layer name to use. Defaults to None.
        """
        if isinstance(source, str) and source.startswith("http"):
            self.add_raster(
                source,
                band=band,
                palette=palette,
                vmin=vmin,
                vmax=vmax,
                nodata=nodata,
                attribution=attribution,
                layer_name=layer_name,
                **kwargs,
            )
        else:
            raise Exception("The source must be a URL.")

    def remove_draw_control(self):
        """Removes the draw control from the map"""
        self.remove("draw_control")

    def remove_drawn_features(self):
        """Removes user-drawn geometries from the map"""
        if self._draw_control is not None:
            self._draw_control.reset()
        if "Drawn Features" in self.ee_layers:
            self.ee_layers.pop("Drawn Features")

    def remove_last_drawn(self):
        """Removes last user-drawn geometry from the map"""
        if self._draw_control is not None:
            if self._draw_control.count == 1:
                self.remove_drawn_features()
            elif self._draw_control.count:
                self._draw_control.remove_geometry(self._draw_control.geometries[-1])
                if hasattr(self, "_chart_values"):
                    self._chart_values = self._chart_values[:-1]
                if hasattr(self, "_chart_points"):
                    self._chart_points = self._chart_points[:-1]
                # self._chart_labels = None

    def extract_values_to_points(self, filename):
        """Exports pixel values to a csv file based on user-drawn geometries.

        Args:
            filename (str): The output file path to the csv file or shapefile.
        """
        import csv

        filename = os.path.abspath(filename)
        allowed_formats = ["csv", "shp"]
        ext = filename[-3:]

        if ext not in allowed_formats:
            print(
                "The output file must be one of the following: {}".format(
                    ", ".join(allowed_formats)
                )
            )
            return

        out_dir = os.path.dirname(filename)
        out_csv = filename[:-3] + "csv"
        out_shp = filename[:-3] + "shp"
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)

        count = len(self._chart_points)
        out_list = []
        if count > 0:
            header = ["id", "latitude", "longitude"] + self._chart_labels
            out_list.append(header)

            for i in range(0, count):
                id = i + 1
                line = [id] + self._chart_points[i] + self._chart_values[i]
                out_list.append(line)

            with open(out_csv, "w", newline="") as f:
                writer = csv.writer(f)
                writer.writerows(out_list)

            if ext == "csv":
                print(f"The csv file has been saved to: {out_csv}")
            else:
                csv_to_shp(out_csv, out_shp)
                print(f"The shapefile has been saved to: {out_shp}")

    def add_styled_vector(
        self,
        ee_object,
        column,
        palette,
        layer_name="Untitled",
        shown=True,
        opacity=1.0,
        **kwargs,
    ):
        """Adds a styled vector to the map.

        Args:
            ee_object (object): An ee.FeatureCollection.
            column (str): The column name to use for styling.
            palette (list | dict): The palette (e.g., list of colors or a dict containing label and color pairs) to use for styling.
            layer_name (str, optional): The name to be used for the new layer. Defaults to "Untitled".
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
            opacity (float, optional): The opacity of the layer. Defaults to 1.0.
        """
        if isinstance(palette, str):
            from .colormaps import get_palette

            count = ee_object.size().getInfo()
            palette = get_palette(palette, count)

        styled_vector = vector_styling(ee_object, column, palette, **kwargs)
        self.addLayer(
            styled_vector.style(**{"styleProperty": "style"}),
            {},
            layer_name,
            shown,
            opacity,
        )

    def add_shp(
        self,
        in_shp,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
        encoding="utf-8",
    ):
        """Adds a shapefile to the map.

        Args:
            in_shp (str): The input file path to the shapefile.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
            encoding (str, optional): The encoding of the shapefile. Defaults to "utf-8".

        Raises:
            FileNotFoundError: The provided shapefile could not be found.
        """
        in_shp = os.path.abspath(in_shp)
        if not os.path.exists(in_shp):
            raise FileNotFoundError("The provided shapefile could not be found.")

        geojson = shp_to_geojson(in_shp)
        self.add_geojson(
            geojson,
            layer_name,
            style,
            hover_style,
            style_callback,
            fill_colors,
            info_mode,
            encoding,
        )

    add_shapefile = add_shp

    def add_geojson(
        self,
        in_geojson,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
        encoding="utf-8",
    ):
        """Adds a GeoJSON file to the map.

        Args:
            in_geojson (str | dict): The file path or http URL to the input GeoJSON or a dictionary containing the geojson.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
            encoding (str, optional): The encoding of the GeoJSON file. Defaults to "utf-8".

        Raises:
            FileNotFoundError: The provided GeoJSON file could not be found.
        """
        import json
        import random
        import requests
        import warnings

        warnings.filterwarnings("ignore")

        style_callback_only = False

        if len(style) == 0 and style_callback is not None:
            style_callback_only = True

        try:
            if isinstance(in_geojson, str):
                if in_geojson.startswith("http"):
                    in_geojson = github_raw_url(in_geojson)
                    data = requests.get(in_geojson).json()
                else:
                    in_geojson = os.path.abspath(in_geojson)
                    if not os.path.exists(in_geojson):
                        raise FileNotFoundError(
                            "The provided GeoJSON file could not be found."
                        )

                    with open(in_geojson, encoding=encoding) as f:
                        data = json.load(f)
            elif isinstance(in_geojson, dict):
                data = in_geojson
            else:
                raise TypeError("The input geojson must be a type of str or dict.")
        except Exception as e:
            raise Exception(e)

        if not style:
            style = {
                # "stroke": True,
                "color": "#000000",
                "weight": 1,
                "opacity": 1,
                # "fill": True,
                # "fillColor": "#ffffff",
                "fillOpacity": 0.1,
                # "dashArray": "9"
                # "clickable": True,
            }
        elif "weight" not in style:
            style["weight"] = 1

        if not hover_style:
            hover_style = {"weight": style["weight"] + 1, "fillOpacity": 0.5}

        def random_color(feature):
            return {
                "color": "black",
                "fillColor": random.choice(fill_colors),
            }

        toolbar_button = widgets.ToggleButton(
            value=True,
            tooltip="Toolbar",
            icon="info",
            layout=widgets.Layout(
                width="28px", height="28px", padding="0px 0px 0px 4px"
            ),
        )

        close_button = widgets.ToggleButton(
            value=False,
            tooltip="Close the tool",
            icon="times",
            # button_style="primary",
            layout=widgets.Layout(
                height="28px", width="28px", padding="0px 0px 0px 4px"
            ),
        )

        html = widgets.HTML()
        html.layout.margin = "0px 10px 0px 10px"
        html.layout.max_height = "250px"
        html.layout.max_width = "250px"

        output_widget = widgets.VBox(
            [widgets.HBox([toolbar_button, close_button]), html]
        )
        info_control = ipyleaflet.WidgetControl(
            widget=output_widget, position="bottomright"
        )

        if info_mode in ["on_hover", "on_click"]:
            self.add(info_control)

        def toolbar_btn_click(change):
            if change["new"]:
                close_button.value = False
                output_widget.children = [
                    widgets.VBox([widgets.HBox([toolbar_button, close_button]), html])
                ]
            else:
                output_widget.children = [widgets.HBox([toolbar_button, close_button])]

        toolbar_button.observe(toolbar_btn_click, "value")

        def close_btn_click(change):
            if change["new"]:
                toolbar_button.value = False
                if info_control in self.controls:
                    self.remove_control(info_control)
                output_widget.close()

        close_button.observe(close_btn_click, "value")

        def update_html(feature, **kwargs):
            value = [
                "<b>{}: </b>{}<br>".format(prop, feature["properties"][prop])
                for prop in feature["properties"].keys()
            ][:-1]

            value = """{}""".format("".join(value))
            html.value = value

        if style_callback is None:
            style_callback = random_color

        if style_callback_only:
            geojson = ipyleaflet.GeoJSON(
                data=data,
                hover_style=hover_style,
                style_callback=style_callback,
                name=layer_name,
            )
        else:
            geojson = ipyleaflet.GeoJSON(
                data=data,
                style=style,
                hover_style=hover_style,
                style_callback=style_callback,
                name=layer_name,
            )

        if info_mode == "on_hover":
            geojson.on_hover(update_html)
        elif info_mode == "on_click":
            geojson.on_click(update_html)

        self.add(geojson)
        self.geojson_layers.append(geojson)

        if not hasattr(self, "json_layer_dict"):
            self.json_layer_dict = {}

        params = {
            "data": geojson,
            "style": style,
            "hover_style": hover_style,
            "style_callback": style_callback,
        }
        self.json_layer_dict[layer_name] = params

    def add_kml(
        self,
        in_kml,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds a GeoJSON file to the map.

        Args:
            in_kml (str): The input file path to the KML.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        Raises:
            FileNotFoundError: The provided KML file could not be found.
        """

        if isinstance(in_kml, str) and in_kml.startswith("http"):
            in_kml = github_raw_url(in_kml)
            in_kml = download_file(in_kml)

        in_kml = os.path.abspath(in_kml)
        if not os.path.exists(in_kml):
            raise FileNotFoundError("The provided KML file could not be found.")
        self.add_vector(
            in_kml,
            layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )

    def add_vector(
        self,
        filename,
        layer_name="Untitled",
        to_ee=False,
        bbox=None,
        mask=None,
        rows=None,
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
        encoding="utf-8",
        **kwargs,
    ):
        """Adds any geopandas-supported vector dataset to the map.

        Args:
            filename (str): Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO).
            layer_name (str, optional): The layer name to use. Defaults to "Untitled".
            to_ee (bool, optional): Whether to convert the GeoJSON to ee.FeatureCollection. Defaults to False.
            bbox (tuple | GeoDataFrame or GeoSeries | shapely Geometry, optional): Filter features by given bounding box, GeoSeries, GeoDataFrame or a shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with mask. Defaults to None.
            mask (dict | GeoDataFrame or GeoSeries | shapely Geometry, optional): Filter for features that intersect with the given dict-like geojson geometry, GeoSeries, GeoDataFrame or shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with bbox. Defaults to None.
            rows (int or slice, optional): Load in specific rows by passing an integer (first n rows) or a slice() object.. Defaults to None.
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
            encoding (str, optional): The encoding to use to read the file. Defaults to "utf-8".

        """
        if not filename.startswith("http"):
            filename = os.path.abspath(filename)
        else:
            filename = github_raw_url(filename)
        if to_ee:
            fc = vector_to_ee(
                filename,
                bbox=bbox,
                mask=mask,
                rows=rows,
                geodesic=True,
                **kwargs,
            )

            self.addLayer(fc, {}, layer_name)
        else:
            ext = os.path.splitext(filename)[1].lower()
            if ext == ".shp":
                self.add_shapefile(
                    filename,
                    layer_name,
                    style,
                    hover_style,
                    style_callback,
                    fill_colors,
                    info_mode,
                    encoding,
                )
            elif ext in [".json", ".geojson"]:
                self.add_geojson(
                    filename,
                    layer_name,
                    style,
                    hover_style,
                    style_callback,
                    fill_colors,
                    info_mode,
                    encoding,
                )
            else:
                geojson = vector_to_geojson(
                    filename,
                    bbox=bbox,
                    mask=mask,
                    rows=rows,
                    epsg="4326",
                    **kwargs,
                )

                self.add_geojson(
                    geojson,
                    layer_name,
                    style,
                    hover_style,
                    style_callback,
                    fill_colors,
                    info_mode,
                    encoding,
                )

    def add_osm(
        self,
        query,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
        which_result=None,
        by_osmid=False,
        buffer_dist=None,
        to_ee=False,
        geodesic=True,
    ):
        """Adds OSM data to the map.

        Args:
            query (str | dict | list): Query string(s) or structured dict(s) to geocode.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
            which_result (INT, optional): Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
            by_osmid (bool, optional): If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
            buffer_dist (float, optional): Distance to buffer around the place geometry, in meters. Defaults to None.
            to_ee (bool, optional): Whether to convert the csv to an ee.FeatureCollection.
            geodesic (bool, optional): Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected.

        """
        gdf = osm_to_gdf(
            query, which_result=which_result, by_osmid=by_osmid, buffer_dist=buffer_dist
        )
        geojson = gdf.__geo_interface__

        if to_ee:
            fc = geojson_to_ee(geojson, geodesic=geodesic)
            self.addLayer(fc, {}, layer_name)
            self.zoomToObject(fc)
        else:
            self.add_geojson(
                geojson,
                layer_name=layer_name,
                style=style,
                hover_style=hover_style,
                style_callback=style_callback,
                fill_colors=fill_colors,
                info_mode=info_mode,
            )
            bounds = gdf.bounds.iloc[0]
            self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

    def add_osm_from_geocode(
        self,
        query,
        which_result=None,
        by_osmid=False,
        buffer_dist=None,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds OSM data of place(s) by name or ID to the map.

        Args:
            query (str | dict | list): Query string(s) or structured dict(s) to geocode.
            which_result (int, optional): Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
            by_osmid (bool, optional): If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
            buffer_dist (float, optional): Distance to buffer around the place geometry, in meters. Defaults to None.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        """
        from .osm import osm_gdf_from_geocode

        gdf = osm_gdf_from_geocode(
            query, which_result=which_result, by_osmid=by_osmid, buffer_dist=buffer_dist
        )
        geojson = gdf.__geo_interface__

        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        self.zoom_to_gdf(gdf)

    def add_osm_from_address(
        self,
        address,
        tags,
        dist=1000,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds OSM entities within some distance N, S, E, W of address to the map.

        Args:
            address (str): The address to geocode and use as the central point around which to get the geometries.
            tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
            dist (int, optional): Distance in meters. Defaults to 1000.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        """
        from .osm import osm_gdf_from_address

        gdf = osm_gdf_from_address(address, tags, dist)
        geojson = gdf.__geo_interface__

        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        self.zoom_to_gdf(gdf)

    def add_osm_from_place(
        self,
        query,
        tags,
        which_result=None,
        buffer_dist=None,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds OSM entities within boundaries of geocodable place(s) to the map.

        Args:
            query (str | dict | list): Query string(s) or structured dict(s) to geocode.
            tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
            which_result (int, optional): Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
            buffer_dist (float, optional): Distance to buffer around the place geometry, in meters. Defaults to None.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        """
        from .osm import osm_gdf_from_place

        gdf = osm_gdf_from_place(query, tags, which_result, buffer_dist)
        geojson = gdf.__geo_interface__

        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        self.zoom_to_gdf(gdf)

    def add_osm_from_point(
        self,
        center_point,
        tags,
        dist=1000,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds OSM entities within some distance N, S, E, W of a point to the map.

        Args:
            center_point (tuple): The (lat, lng) center point around which to get the geometries.
            tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
            dist (int, optional): Distance in meters. Defaults to 1000.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        """
        from .osm import osm_gdf_from_point

        gdf = osm_gdf_from_point(center_point, tags, dist)
        geojson = gdf.__geo_interface__

        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        self.zoom_to_gdf(gdf)

    def add_osm_from_polygon(
        self,
        polygon,
        tags,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds OSM entities within boundaries of a (multi)polygon to the map.

        Args:
            polygon (shapely.geometry.Polygon | shapely.geometry.MultiPolygon): Geographic boundaries to fetch geometries within
            tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        """
        from .osm import osm_gdf_from_polygon

        gdf = osm_gdf_from_polygon(polygon, tags)
        geojson = gdf.__geo_interface__

        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        self.zoom_to_gdf(gdf)

    def add_osm_from_bbox(
        self,
        north,
        south,
        east,
        west,
        tags,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds OSM entities within a N, S, E, W bounding box to the map.


        Args:
            north (float): Northern latitude of bounding box.
            south (float): Southern latitude of bounding box.
            east (float): Eastern longitude of bounding box.
            west (float): Western longitude of bounding box.
            tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        """
        from .osm import osm_gdf_from_bbox

        gdf = osm_gdf_from_bbox(north, south, east, west, tags)
        geojson = gdf.__geo_interface__

        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        self.zoom_to_gdf(gdf)

    def add_osm_from_view(
        self,
        tags,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
    ):
        """Adds OSM entities within the current map view to the map.

        Args:
            tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

        """
        from .osm import osm_gdf_from_bbox

        bounds = self.bounds
        if len(bounds) == 0:
            bounds = (
                (40.74824858675827, -73.98933637940563),
                (40.75068694343106, -73.98364473187601),
            )
        north, south, east, west = (
            bounds[1][0],
            bounds[0][0],
            bounds[1][1],
            bounds[0][1],
        )

        gdf = osm_gdf_from_bbox(north, south, east, west, tags)
        geojson = gdf.__geo_interface__

        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        self.zoom_to_gdf(gdf)

    def add_gdf(
        self,
        gdf,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
        zoom_to_layer=True,
        encoding="utf-8",
    ):
        """Adds a GeoDataFrame to the map.

        Args:
            gdf (GeoDataFrame): A GeoPandas GeoDataFrame.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
            zoom_to_layer (bool, optional): Whether to zoom to the layer.
            encoding (str, optional): The encoding of the GeoDataFrame. Defaults to "utf-8".
        """

        data = gdf_to_geojson(gdf, epsg="4326")

        self.add_geojson(
            data,
            layer_name,
            style,
            hover_style,
            style_callback,
            fill_colors,
            info_mode,
            encoding,
        )

        if zoom_to_layer:
            import numpy as np

            bounds = gdf.to_crs(epsg="4326").bounds
            west = np.min(bounds["minx"])
            south = np.min(bounds["miny"])
            east = np.max(bounds["maxx"])
            north = np.max(bounds["maxy"])
            self.fit_bounds([[south, east], [north, west]])

    def add_gdf_from_postgis(
        self,
        sql,
        con,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=["black"],
        info_mode="on_hover",
        zoom_to_layer=True,
        **kwargs,
    ):
        """Reads a PostGIS database and returns data as a GeoDataFrame to be added to the map.

        Args:
            sql (str): SQL query to execute in selecting entries from database, or name of the table to read from the database.
            con (sqlalchemy.engine.Engine): Active connection to the database to query.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
            zoom_to_layer (bool, optional): Whether to zoom to the layer.
        """
        gdf = read_postgis(sql, con, **kwargs)
        gdf = gdf.to_crs("epsg:4326")
        self.add_gdf(
            gdf,
            layer_name,
            style,
            hover_style,
            style_callback,
            fill_colors,
            info_mode,
            zoom_to_layer,
        )

    def add_time_slider(
        self,
        ee_object,
        vis_params={},
        region=None,
        layer_name="Time series",
        labels=None,
        time_interval=1,
        position="bottomright",
        slider_length="150px",
        date_format="YYYY-MM-dd",
        opacity=1.0,
        **kwargs,
    ):
        """Adds a time slider to the map.

        Args:
            ee_object (ee.Image | ee.ImageCollection): The Image or ImageCollection to visualize.
            vis_params (dict, optional): Visualization parameters to use for visualizing image. Defaults to {}.
            region (ee.Geometry | ee.FeatureCollection): The region to visualize.
            layer_name (str, optional): The layer name to be used. Defaults to "Time series".
            labels (list, optional): The list of labels to be used for the time series. Defaults to None.
            time_interval (int, optional): Time interval in seconds. Defaults to 1.
            position (str, optional): Position to place the time slider, can be any of ['topleft', 'topright', 'bottomleft', 'bottomright']. Defaults to "bottomright".
            slider_length (str, optional): Length of the time slider. Defaults to "150px".
            date_format (str, optional): The date format to use. Defaults to 'YYYY-MM-dd'.
            opacity (float, optional): The opacity of layers. Defaults to 1.0.

        Raises:
            TypeError: If the ee_object is not ee.Image | ee.ImageCollection.
        """
        import threading

        if isinstance(ee_object, ee.Image):
            if region is not None:
                if isinstance(region, ee.Geometry):
                    ee_object = ee_object.clip(region)
                elif isinstance(region, ee.FeatureCollection):
                    ee_object = ee_object.clipToCollection(region)
            if layer_name not in self.ee_layers:
                self.addLayer(ee_object, {}, layer_name, False, opacity)
            band_names = ee_object.bandNames()
            ee_object = ee.ImageCollection(
                ee_object.bandNames().map(lambda b: ee_object.select([b]))
            )

            if labels is not None:
                if len(labels) != int(ee_object.size().getInfo()):
                    raise ValueError(
                        "The length of labels must be equal to the number of bands in the image."
                    )
            else:
                labels = band_names.getInfo()

        elif isinstance(ee_object, ee.ImageCollection):
            if region is not None:
                if isinstance(region, ee.Geometry):
                    ee_object = ee_object.map(lambda img: img.clip(region))
                elif isinstance(region, ee.FeatureCollection):
                    ee_object = ee_object.map(lambda img: img.clipToCollection(region))

            if labels is not None:
                if len(labels) != int(ee_object.size().getInfo()):
                    raise ValueError(
                        "The length of labels must be equal to the number of images in the ImageCollection."
                    )
            else:
                labels = (
                    ee_object.aggregate_array("system:time_start")
                    .map(lambda d: ee.Date(d).format(date_format))
                    .getInfo()
                )
        else:
            raise TypeError("The ee_object must be an ee.Image or ee.ImageCollection")

        # if labels is not None:
        #     size = len(labels)
        # else:
        #     size = ee_object.size().getInfo()
        #     labels = [str(i) for i in range(1, size + 1)]

        first = ee.Image(ee_object.first())

        if layer_name not in self.ee_layers:
            self.addLayer(ee_object.toBands(), {}, layer_name, False, opacity)
        self.addLayer(first, vis_params, "Image X", True, opacity)

        slider = widgets.IntSlider(
            min=1,
            max=len(labels),
            readout=False,
            continuous_update=False,
            layout=widgets.Layout(width=slider_length),
        )
        label = widgets.Label(
            value=labels[0], layout=widgets.Layout(padding="0px 5px 0px 5px")
        )

        play_btn = widgets.Button(
            icon="play",
            tooltip="Play the time slider",
            button_style="primary",
            layout=widgets.Layout(width="32px"),
        )

        pause_btn = widgets.Button(
            icon="pause",
            tooltip="Pause the time slider",
            button_style="primary",
            layout=widgets.Layout(width="32px"),
        )

        close_btn = widgets.Button(
            icon="times",
            tooltip="Close the time slider",
            button_style="primary",
            layout=widgets.Layout(width="32px"),
        )

        play_chk = widgets.Checkbox(value=False)

        slider_widget = widgets.HBox([slider, label, play_btn, pause_btn, close_btn])

        def play_click(b):
            import time

            play_chk.value = True

            def work(slider):
                while play_chk.value:
                    if slider.value < len(labels):
                        slider.value += 1
                    else:
                        slider.value = 1
                    time.sleep(time_interval)

            thread = threading.Thread(target=work, args=(slider,))
            thread.start()

        def pause_click(b):
            play_chk.value = False

        play_btn.on_click(play_click)
        pause_btn.on_click(pause_click)

        def slider_changed(change):
            self.default_style = {"cursor": "wait"}
            index = slider.value - 1
            label.value = labels[index]
            image = ee.Image(ee_object.toList(ee_object.size()).get(index))
            if layer_name not in self.ee_layers:
                self.addLayer(ee_object.toBands(), {}, layer_name, False, opacity)
            self.addLayer(image, vis_params, "Image X", True, opacity)
            self.default_style = {"cursor": "default"}

        slider.observe(slider_changed, "value")

        def close_click(b):
            play_chk.value = False
            self.toolbar_reset()
            self.remove_ee_layer("Image X")
            self.remove_ee_layer(layer_name)

            if self.slider_ctrl is not None and self.slider_ctrl in self.controls:
                self.remove_control(self.slider_ctrl)
            slider_widget.close()

        close_btn.on_click(close_click)

        slider_ctrl = ipyleaflet.WidgetControl(widget=slider_widget, position=position)
        self.add(slider_ctrl)
        self.slider_ctrl = slider_ctrl

    def add_xy_data(
        self,
        in_csv,
        x="longitude",
        y="latitude",
        label=None,
        layer_name="Marker cluster",
        to_ee=False,
    ):
        """Adds points from a CSV file containing lat/lon information and display data on the map.

        Args:
            in_csv (str): The file path to the input CSV file.
            x (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
            y (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
            label (str, optional): The name of the column containing label information to used for marker popup. Defaults to None.
            layer_name (str, optional): The layer name to use. Defaults to "Marker cluster".
            to_ee (bool, optional): Whether to convert the csv to an ee.FeatureCollection.

        Raises:
            FileNotFoundError: The specified input csv does not exist.
            ValueError: The specified x column does not exist.
            ValueError: The specified y column does not exist.
            ValueError: The specified label column does not exist.
        """
        import pandas as pd

        if not in_csv.startswith("http") and (not os.path.exists(in_csv)):
            raise FileNotFoundError("The specified input csv does not exist.")

        df = pd.read_csv(in_csv)
        col_names = df.columns.values.tolist()

        if x not in col_names:
            raise ValueError(f"x must be one of the following: {', '.join(col_names)}")

        if y not in col_names:
            raise ValueError(f"y must be one of the following: {', '.join(col_names)}")

        if label is not None and (label not in col_names):
            raise ValueError(
                f"label must be one of the following: {', '.join(col_names)}"
            )

        self.default_style = {"cursor": "wait"}

        if to_ee:
            fc = csv_to_ee(in_csv, latitude=y, longitude=x)
            self.addLayer(fc, {}, layer_name)

        else:
            points = list(zip(df[y], df[x]))

            if label is not None:
                labels = df[label]
                markers = [
                    ipyleaflet.Marker(
                        location=point,
                        draggable=False,
                        popup=widgets.HTML(str(labels[index])),
                    )
                    for index, point in enumerate(points)
                ]
            else:
                markers = [
                    ipyleaflet.Marker(location=point, draggable=False)
                    for point in points
                ]

            marker_cluster = ipyleaflet.MarkerCluster(markers=markers, name=layer_name)
            self.add(marker_cluster)

        self.default_style = {"cursor": "default"}

    def add_points_from_xy(
        self,
        data,
        x="longitude",
        y="latitude",
        popup=None,
        layer_name="Marker Cluster",
        color_column=None,
        marker_colors=None,
        icon_colors=["white"],
        icon_names=["info"],
        spin=False,
        add_legend=True,
        **kwargs,
    ):
        """Adds a marker cluster to the map.

        Args:
            data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
            x (str, optional): The column name for the x values. Defaults to "longitude".
            y (str, optional): The column name for the y values. Defaults to "latitude".
            popup (list, optional): A list of column names to be used as the popup. Defaults to None.
            layer_name (str, optional): The name of the layer. Defaults to "Marker Cluster".
            color_column (str, optional): The column name for the color values. Defaults to None.
            marker_colors (list, optional): A list of colors to be used for the markers. Defaults to None.
            icon_colors (list, optional): A list of colors to be used for the icons. Defaults to ['white'].
            icon_names (list, optional): A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons. Defaults to ['info'].
            spin (bool, optional): If True, the icon will spin. Defaults to False.
            add_legend (bool, optional): If True, a legend will be added to the map. Defaults to True.

        """
        import pandas as pd

        data = github_raw_url(data)

        color_options = [
            "red",
            "blue",
            "green",
            "purple",
            "orange",
            "darkred",
            "lightred",
            "beige",
            "darkblue",
            "darkgreen",
            "cadetblue",
            "darkpurple",
            "white",
            "pink",
            "lightblue",
            "lightgreen",
            "gray",
            "black",
            "lightgray",
        ]

        if isinstance(data, pd.DataFrame):
            df = data
        elif not data.startswith("http") and (not os.path.exists(data)):
            raise FileNotFoundError("The specified input csv does not exist.")
        else:
            df = pd.read_csv(data)

        df = points_from_xy(df, x, y)

        col_names = df.columns.values.tolist()

        if color_column is not None and color_column not in col_names:
            raise ValueError(
                f"The color column {color_column} does not exist in the dataframe."
            )

        if color_column is not None:
            items = list(set(df[color_column]))

        else:
            items = None

        if color_column is not None and marker_colors is None:
            if len(items) > len(color_options):
                raise ValueError(
                    f"The number of unique values in the color column {color_column} is greater than the number of available colors."
                )
            else:
                marker_colors = color_options[: len(items)]
        elif color_column is not None and marker_colors is not None:
            if len(items) != len(marker_colors):
                raise ValueError(
                    f"The number of unique values in the color column {color_column} is not equal to the number of available colors."
                )

        if items is not None:
            if len(icon_colors) == 1:
                icon_colors = icon_colors * len(items)
            elif len(items) != len(icon_colors):
                raise ValueError(
                    f"The number of unique values in the color column {color_column} is not equal to the number of available colors."
                )

            if len(icon_names) == 1:
                icon_names = icon_names * len(items)
            elif len(items) != len(icon_names):
                raise ValueError(
                    f"The number of unique values in the color column {color_column} is not equal to the number of available colors."
                )

        if "geometry" in col_names:
            col_names.remove("geometry")

        if popup is not None:
            if isinstance(popup, str) and (popup not in col_names):
                raise ValueError(
                    f"popup must be one of the following: {', '.join(col_names)}"
                )
            elif isinstance(popup, list) and (
                not all(item in col_names for item in popup)
            ):
                raise ValueError(
                    f"All popup items must be select from: {', '.join(col_names)}"
                )
        else:
            popup = col_names

        df["x"] = df.geometry.x
        df["y"] = df.geometry.y

        points = list(zip(df["y"], df["x"]))

        if popup is not None:
            if isinstance(popup, str):
                labels = df[popup]

                markers = []
                for index, point in enumerate(points):
                    if items is not None:
                        marker_color = marker_colors[
                            items.index(df[color_column][index])
                        ]
                        icon_name = icon_names[items.index(df[color_column][index])]
                        icon_color = icon_colors[items.index(df[color_column][index])]
                        marker_icon = ipyleaflet.AwesomeIcon(
                            name=icon_name,
                            marker_color=marker_color,
                            icon_color=icon_color,
                            spin=spin,
                        )
                    else:
                        marker_icon = None

                    marker = ipyleaflet.Marker(
                        location=point,
                        draggable=False,
                        popup=widgets.HTML(str(labels[index])),
                        icon=marker_icon,
                    )
                    markers.append(marker)

            elif isinstance(popup, list):
                labels = []
                for i in range(len(points)):
                    label = ""
                    for item in popup:
                        label = (
                            label
                            + "<b>"
                            + str(item)
                            + "</b>"
                            + ": "
                            + str(df[item][i])
                            + "<br>"
                        )
                    labels.append(label)
                df["popup"] = labels

                markers = []
                for index, point in enumerate(points):
                    if items is not None:
                        marker_color = marker_colors[
                            items.index(df[color_column][index])
                        ]
                        icon_name = icon_names[items.index(df[color_column][index])]
                        icon_color = icon_colors[items.index(df[color_column][index])]
                        marker_icon = ipyleaflet.AwesomeIcon(
                            name=icon_name,
                            marker_color=marker_color,
                            icon_color=icon_color,
                            spin=spin,
                        )
                    else:
                        marker_icon = None

                    marker = ipyleaflet.Marker(
                        location=point,
                        draggable=False,
                        popup=widgets.HTML(labels[index]),
                        icon=marker_icon,
                    )
                    markers.append(marker)

        else:
            markers = []
            for point in points:
                if items is not None:
                    marker_color = marker_colors[items.index(df[color_column][index])]
                    icon_name = icon_names[items.index(df[color_column][index])]
                    icon_color = icon_colors[items.index(df[color_column][index])]
                    marker_icon = ipyleaflet.AwesomeIcon(
                        name=icon_name,
                        marker_color=marker_color,
                        icon_color=icon_color,
                        spin=spin,
                    )
                else:
                    marker_icon = None

                marker = ipyleaflet.Marker(
                    location=point, draggable=False, icon=marker_icon
                )
                markers.append(marker)

        marker_cluster = ipyleaflet.MarkerCluster(markers=markers, name=layer_name)
        self.add(marker_cluster)

        if items is not None and add_legend:
            marker_colors = [check_color(c) for c in marker_colors]
            self.add_legend(
                title=color_column.title(), colors=marker_colors, keys=items
            )

        self.default_style = {"cursor": "default"}

    def add_circle_markers_from_xy(
        self,
        data,
        x="longitude",
        y="latitude",
        radius=10,
        popup=None,
        **kwargs,
    ):
        """Adds a marker cluster to the map. For a list of options, see https://ipyleaflet.readthedocs.io/en/latest/api_reference/circle_marker.html

        Args:
            data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
            x (str, optional): The column name for the x values. Defaults to "longitude".
            y (str, optional): The column name for the y values. Defaults to "latitude".
            radius (int, optional): The radius of the circle. Defaults to 10.
            popup (list, optional): A list of column names to be used as the popup. Defaults to None.

        """
        import pandas as pd

        data = github_raw_url(data)

        if isinstance(data, pd.DataFrame):
            df = data
        elif not data.startswith("http") and (not os.path.exists(data)):
            raise FileNotFoundError("The specified input csv does not exist.")
        else:
            df = pd.read_csv(data)

        col_names = df.columns.values.tolist()

        if popup is None:
            popup = col_names

        if not isinstance(popup, list):
            popup = [popup]

        if x not in col_names:
            raise ValueError(f"x must be one of the following: {', '.join(col_names)}")

        if y not in col_names:
            raise ValueError(f"y must be one of the following: {', '.join(col_names)}")

        for row in df.itertuples():
            html = ""
            for p in popup:
                html = html + "<b>" + p + "</b>" + ": " + str(getattr(row, p)) + "<br>"
            popup_html = widgets.HTML(html)

            marker = ipyleaflet.CircleMarker(
                location=[getattr(row, y), getattr(row, x)],
                radius=radius,
                popup=popup_html,
                **kwargs,
            )
            super().add(marker)

    def add_planet_by_month(
        self, year=2016, month=1, name=None, api_key=None, token_name="PLANET_API_KEY"
    ):
        """Adds a Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

        Args:
            year (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
            month (int, optional): The month of Planet global mosaic, must be 1-12. Defaults to 1.
            name (str, optional): The layer name to use. Defaults to None.
            api_key (str, optional): The Planet API key. Defaults to None.
            token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
        """
        layer = planet_tile_by_month(year, month, name, api_key, token_name)
        self.add(layer)

    def add_planet_by_quarter(
        self, year=2016, quarter=1, name=None, api_key=None, token_name="PLANET_API_KEY"
    ):
        """Adds a Planet global mosaic by quarter to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

        Args:
            year (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
            quarter (int, optional): The quarter of Planet global mosaic, must be 1-12. Defaults to 1.
            name (str, optional): The layer name to use. Defaults to None.
            api_key (str, optional): The Planet API key. Defaults to None.
            token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
        """
        layer = planet_tile_by_quarter(year, quarter, name, api_key, token_name)
        self.add(layer)

    def to_streamlit(self, width=None, height=600, scrolling=False, **kwargs):
        """Renders map figure in a Streamlit app.

        Args:
            width (int, optional): Width of the map. Defaults to None.
            height (int, optional): Height of the map. Defaults to 600.
            responsive (bool, optional): Whether to make the map responsive. Defaults to True.
            scrolling (bool, optional): If True, show a scrollbar when the content is larger than the iframe. Otherwise, do not show a scrollbar. Defaults to False.

        Returns:
            streamlit.components: components.html object.
        """

        try:
            import streamlit.components.v1 as components

            # if responsive:
            #     make_map_responsive = """
            #     <style>
            #     [title~="st.iframe"] { width: 100%}
            #     </style>
            #     """
            #     st.markdown(make_map_responsive, unsafe_allow_html=True)
            return components.html(
                self.to_html(), width=width, height=height, scrolling=scrolling
            )

        except Exception as e:
            raise Exception(e)

    def add_point_layer(
        self, filename, popup=None, layer_name="Marker Cluster", **kwargs
    ):
        """Adds a point layer to the map with a popup attribute.

        Args:
            filename (str): str, http url, path object or file-like object. Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO)
            popup (str | list, optional): Column name(s) to be used for popup. Defaults to None.
            layer_name (str, optional): A layer name to use. Defaults to "Marker Cluster".

        Raises:
            ValueError: If the specified column name does not exist.
            ValueError: If the specified column names do not exist.
        """
        import warnings

        warnings.filterwarnings("ignore")
        check_package(name="geopandas", URL="https://geopandas.org")
        import geopandas as gpd

        self.default_style = {"cursor": "wait"}

        if not filename.startswith("http"):
            filename = os.path.abspath(filename)
        gdf = gpd.read_file(filename, **kwargs)
        df = gdf.to_crs(epsg="4326")
        col_names = df.columns.values.tolist()
        if popup is not None:
            if isinstance(popup, str) and (popup not in col_names):
                raise ValueError(
                    f"popup must be one of the following: {', '.join(col_names)}"
                )
            elif isinstance(popup, list) and (
                not all(item in col_names for item in popup)
            ):
                raise ValueError(
                    f"All popup items must be select from: {', '.join(col_names)}"
                )

        df["x"] = df.geometry.x
        df["y"] = df.geometry.y

        points = list(zip(df["y"], df["x"]))

        if popup is not None:
            if isinstance(popup, str):
                labels = df[popup]
                markers = [
                    ipyleaflet.Marker(
                        location=point,
                        draggable=False,
                        popup=widgets.HTML(str(labels[index])),
                    )
                    for index, point in enumerate(points)
                ]
            elif isinstance(popup, list):
                labels = []
                for i in range(len(points)):
                    label = ""
                    for item in popup:
                        label = label + str(item) + ": " + str(df[item][i]) + "<br>"
                    labels.append(label)
                df["popup"] = labels

                markers = [
                    ipyleaflet.Marker(
                        location=point,
                        draggable=False,
                        popup=widgets.HTML(labels[index]),
                    )
                    for index, point in enumerate(points)
                ]

        else:
            markers = [
                ipyleaflet.Marker(location=point, draggable=False) for point in points
            ]

        marker_cluster = ipyleaflet.MarkerCluster(markers=markers, name=layer_name)
        self.add(marker_cluster)

        self.default_style = {"cursor": "default"}

    def add_census_data(self, wms, layer, census_dict=None, **kwargs):
        """Adds a census data layer to the map.

        Args:
            wms (str): The wms to use. For example, "Current", "ACS 2021", "Census 2020".  See the complete list at https://tigerweb.geo.census.gov/tigerwebmain/TIGERweb_wms.html
            layer (str): The layer name to add to the map.
            census_dict (dict, optional): A dictionary containing census data. Defaults to None. It can be obtained from the get_census_dict() function.
        """

        try:
            if census_dict is None:
                census_dict = get_census_dict()

            if wms not in census_dict.keys():
                raise ValueError(
                    f"The provided WMS is invalid. It must be one of {census_dict.keys()}"
                )

            layers = census_dict[wms]["layers"]
            if layer not in layers:
                raise ValueError(
                    f"The layer name is not valid. It must be one of {layers}"
                )

            url = census_dict[wms]["url"]
            if "name" not in kwargs:
                kwargs["name"] = layer
            if "attribution" not in kwargs:
                kwargs["attribution"] = "U.S. Census Bureau"
            if "format" not in kwargs:
                kwargs["format"] = "image/png"
            if "transparent" not in kwargs:
                kwargs["transparent"] = True

            self.add_wms_layer(url, layer, **kwargs)

        except Exception as e:
            raise Exception(e)

    def add_xyz_service(self, provider, **kwargs):
        """Add a XYZ tile layer to the map.

        Args:
            provider (str): A tile layer name starts with xyz or qms. For example, xyz.OpenTopoMap,

        Raises:
            ValueError: The provider is not valid. It must start with xyz or qms.
        """
        import xyzservices.providers as xyz
        from xyzservices import TileProvider

        if provider.startswith("xyz"):
            name = provider[4:]
            xyz_provider = xyz.flatten()[name]
            url = xyz_provider.build_url()
            attribution = xyz_provider.attribution
            if attribution.strip() == "":
                attribution = " "
            self.add_tile_layer(url, name, attribution)
        elif provider.startswith("qms"):
            name = provider[4:]
            qms_provider = TileProvider.from_qms(name)
            url = qms_provider.build_url()
            attribution = qms_provider.attribution
            if attribution.strip() == "":
                attribution = " "
            self.add_tile_layer(url, name, attribution)
        else:
            raise ValueError(
                f"The provider {provider} is not valid. It must start with xyz or qms."
            )

    def add_heatmap(
        self,
        data,
        latitude="latitude",
        longitude="longitude",
        value="value",
        name="Heat map",
        radius=25,
        **kwargs,
    ):
        """Adds a heat map to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/heatmap.html

        Args:
            data (str | list | pd.DataFrame): File path or HTTP URL to the input file or a list of data points in the format of [[x1, y1, z1], [x2, y2, z2]]. For example, https://raw.githubusercontent.com/giswqs/leafmap/master/examples/data/world_cities.csv
            latitude (str, optional): The column name of latitude. Defaults to "latitude".
            longitude (str, optional): The column name of longitude. Defaults to "longitude".
            value (str, optional): The column name of values. Defaults to "value".
            name (str, optional): Layer name to use. Defaults to "Heat map".
            radius (int, optional): Radius of each “point” of the heatmap. Defaults to 25.

        Raises:
            ValueError: If data is not a list.
        """
        import pandas as pd
        from ipyleaflet import Heatmap

        try:
            if isinstance(data, str):
                df = pd.read_csv(data)
                data = df[[latitude, longitude, value]].values.tolist()
            elif isinstance(data, pd.DataFrame):
                data = data[[latitude, longitude, value]].values.tolist()
            elif isinstance(data, list):
                pass
            else:
                raise ValueError("data must be a list, a DataFrame, or a file path.")

            heatmap = Heatmap(locations=data, radius=radius, name=name, **kwargs)
            self.add(heatmap)

        except Exception as e:
            raise Exception(e)

    def add_labels(
        self,
        data,
        column,
        font_size="12pt",
        font_color="black",
        font_family="arial",
        font_weight="normal",
        x="longitude",
        y="latitude",
        draggable=True,
        layer_name="Labels",
        **kwargs,
    ):
        """Adds a label layer to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/divicon.html

        Args:
            data (pd.DataFrame | ee.FeatureCollection): The input data to label.
            column (str): The column name of the data to label.
            font_size (str, optional): The font size of the labels. Defaults to "12pt".
            font_color (str, optional): The font color of the labels. Defaults to "black".
            font_family (str, optional): The font family of the labels. Defaults to "arial".
            font_weight (str, optional): The font weight of the labels, can be normal, bold. Defaults to "normal".
            x (str, optional): The column name of the longitude. Defaults to "longitude".
            y (str, optional): The column name of the latitude. Defaults to "latitude".
            draggable (bool, optional): Whether the labels are draggable. Defaults to True.
            layer_name (str, optional): Layer name to use. Defaults to "Labels".

        """
        import warnings
        import pandas as pd

        warnings.filterwarnings("ignore")

        if isinstance(data, ee.FeatureCollection):
            centroids = vector_centroids(data)
            df = ee_to_df(centroids)
        elif isinstance(data, pd.DataFrame):
            df = data
        elif isinstance(data, str):
            ext = os.path.splitext(data)[1]
            if ext == ".csv":
                df = pd.read_csv(data)
            elif ext in [".geojson", ".json", ".shp", ".gpkg"]:
                try:
                    import geopandas as gpd

                    df = gpd.read_file(data)
                    df[x] = df.centroid.x
                    df[y] = df.centroid.y
                except Exception as _:
                    print("geopandas is required to read geojson.")
                    return

        else:
            raise ValueError("data must be a DataFrame or an ee.FeatureCollection.")

        if column not in df.columns:
            raise ValueError(f"column must be one of {', '.join(df.columns)}.")
        if x not in df.columns:
            raise ValueError(f"column must be one of {', '.join(df.columns)}.")
        if y not in df.columns:
            raise ValueError(f"column must be one of {', '.join(df.columns)}.")

        try:
            size = int(font_size.replace("pt", ""))
        except:
            raise ValueError("font_size must be something like '10pt'")

        labels = []
        for index in df.index:
            html = f'<div style="font-size: {font_size};color:{font_color};font-family:{font_family};font-weight: {font_weight}">{df[column][index]}</div>'
            marker = ipyleaflet.Marker(
                location=[df[y][index], df[x][index]],
                icon=ipyleaflet.DivIcon(
                    icon_size=(1, 1),
                    icon_anchor=(size, size),
                    html=html,
                    **kwargs,
                ),
                draggable=draggable,
            )
            labels.append(marker)
        layer_group = ipyleaflet.LayerGroup(layers=labels, name=layer_name)
        self.add(layer_group)
        self.labels = layer_group

    def remove_labels(self):
        """Removes all labels from the map."""
        if hasattr(self, "labels"):
            self.remove_layer(self.labels)
            delattr(self, "labels")

    def add_netcdf(
        self,
        filename,
        variables=None,
        palette=None,
        vmin=None,
        vmax=None,
        nodata=None,
        attribution=None,
        layer_name="NetCDF layer",
        shift_lon=True,
        lat="lat",
        lon="lon",
        **kwargs,
    ):
        """Generate an ipyleaflet/folium TileLayer from a netCDF file.
            If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer),
            try adding to following two lines to the beginning of the notebook if the raster does not render properly.

            import os
            os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = f'{os.environ['JUPYTERHUB_SERVICE_PREFIX'].lstrip('/')}/proxy/{{port}}'

        Args:
            filename (str): File path or HTTP URL to the netCDF file.
            variables (int, optional): The variable/band names to extract data from the netCDF file. Defaults to None. If None, all variables will be extracted.
            port (str, optional): The port to use for the server. Defaults to "default".
            palette (str, optional): The name of the color palette from `palettable` to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
            vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
            vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
            nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
            attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
            layer_name (str, optional): The layer name to use. Defaults to "netCDF layer".
            shift_lon (bool, optional): Flag to shift longitude values from [0, 360] to the range [-180, 180]. Defaults to True.
            lat (str, optional): Name of the latitude variable. Defaults to 'lat'.
            lon (str, optional): Name of the longitude variable. Defaults to 'lon'.
        """

        tif, vars = netcdf_to_tif(
            filename, shift_lon=shift_lon, lat=lat, lon=lon, return_vars=True
        )

        if variables is None:
            if len(vars) >= 3:
                band_idx = [1, 2, 3]
            else:
                band_idx = [1]
        else:
            if not set(variables).issubset(set(vars)):
                raise ValueError(f"The variables must be a subset of {vars}.")
            else:
                band_idx = [vars.index(v) + 1 for v in variables]

        self.add_raster(
            tif,
            band=band_idx,
            palette=palette,
            vmin=vmin,
            vmax=vmax,
            nodata=nodata,
            attribution=attribution,
            layer_name=layer_name,
            **kwargs,
        )

    def add_velocity(
        self,
        data,
        zonal_speed,
        meridional_speed,
        latitude_dimension="lat",
        longitude_dimension="lon",
        level_dimension="lev",
        level_index=0,
        time_index=0,
        velocity_scale=0.01,
        max_velocity=20,
        display_options={},
        name="Velocity",
    ):
        """Add a velocity layer to the map.

        Args:
            data (str | xr.Dataset): The data to use for the velocity layer. It can be a file path to a NetCDF file or an xarray Dataset.
            zonal_speed (str): Name of the zonal speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.
            meridional_speed (str): Name of the meridional speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.
            latitude_dimension (str, optional): Name of the latitude dimension in the dataset. Defaults to 'lat'.
            longitude_dimension (str, optional): Name of the longitude dimension in the dataset. Defaults to 'lon'.
            level_dimension (str, optional): Name of the level dimension in the dataset. Defaults to 'lev'.
            level_index (int, optional): The index of the level dimension to display. Defaults to 0.
            time_index (int, optional): The index of the time dimension to display. Defaults to 0.
            velocity_scale (float, optional): The scale of the velocity. Defaults to 0.01.
            max_velocity (int, optional): The maximum velocity to display. Defaults to 20.
            display_options (dict, optional): The display options for the velocity layer. Defaults to {}. See https://bit.ly/3uf8t6w.
            name (str, optional): Layer name to use . Defaults to 'Velocity'.

        Raises:
            ImportError: If the xarray package is not installed.
            ValueError: If the data is not a NetCDF file or an xarray Dataset.
        """
        try:
            import xarray as xr
            from ipyleaflet.velocity import Velocity
        except ImportError:
            raise ImportError(
                "The xarray package is required to add a velocity layer. "
                "Please install it with `pip install xarray`."
            )

        if isinstance(data, str):
            if data.startswith("http"):
                data = download_file(data)
            ds = xr.open_dataset(data)

        elif isinstance(data, xr.Dataset):
            ds = data
        else:
            raise ValueError("The data must be a file path or xarray dataset.")

        coords = list(ds.coords.keys())

        # Rasterio does not handle time or levels. So we must drop them
        if "time" in coords:
            ds = ds.isel(time=time_index, drop=True)

        params = {level_dimension: level_index}
        if level_dimension in coords:
            ds = ds.isel(drop=True, **params)

        wind = Velocity(
            data=ds,
            zonal_speed=zonal_speed,
            meridional_speed=meridional_speed,
            latitude_dimension=latitude_dimension,
            longitude_dimension=longitude_dimension,
            velocity_scale=velocity_scale,
            max_velocity=max_velocity,
            display_options=display_options,
            name=name,
        )
        self.add(wind)

    def add_data(
        self,
        data,
        column,
        colors=None,
        labels=None,
        cmap=None,
        scheme="Quantiles",
        k=5,
        add_legend=True,
        legend_title=None,
        legend_kwds=None,
        classification_kwds=None,
        layer_name="Untitled",
        style=None,
        hover_style=None,
        style_callback=None,
        info_mode="on_hover",
        encoding="utf-8",
        **kwargs,
    ):
        """Add vector data to the map with a variety of classification schemes.

        Args:
            data (str | pd.DataFrame | gpd.GeoDataFrame): The data to classify. It can be a filepath to a vector dataset, a pandas dataframe, or a geopandas geodataframe.
            column (str): The column to classify.
            cmap (str, optional): The name of a colormap recognized by matplotlib. Defaults to None.
            colors (list, optional): A list of colors to use for the classification. Defaults to None.
            labels (list, optional): A list of labels to use for the legend. Defaults to None.
            scheme (str, optional): Name of a choropleth classification scheme (requires mapclassify).
                Name of a choropleth classification scheme (requires mapclassify).
                A mapclassify.MapClassifier object will be used
                under the hood. Supported are all schemes provided by mapclassify (e.g.
                'BoxPlot', 'EqualInterval', 'FisherJenks', 'FisherJenksSampled',
                'HeadTailBreaks', 'JenksCaspall', 'JenksCaspallForced',
                'JenksCaspallSampled', 'MaxP', 'MaximumBreaks',
                'NaturalBreaks', 'Quantiles', 'Percentiles', 'StdMean',
                'UserDefined'). Arguments can be passed in classification_kwds.
            k (int, optional): Number of classes (ignored if scheme is None or if column is categorical). Default to 5.
            legend_kwds (dict, optional): Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or `matplotlib.pyplot.colorbar`. Defaults to None.
                Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or
                Additional accepted keywords when `scheme` is specified:
                fmt : string
                    A formatting specification for the bin edges of the classes in the
                    legend. For example, to have no decimals: ``{"fmt": "{:.0f}"}``.
                labels : list-like
                    A list of legend labels to override the auto-generated labblels.
                    Needs to have the same number of elements as the number of
                    classes (`k`).
                interval : boolean (default False)
                    An option to control brackets from mapclassify legend.
                    If True, open/closed interval brackets are shown in the legend.
            classification_kwds (dict, optional): Keyword arguments to pass to mapclassify. Defaults to None.
            layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
            style (dict, optional): A dictionary specifying the style to be used. Defaults to None.
                style is a dictionary of the following form:
                    style = {
                    "stroke": False,
                    "color": "#ff0000",
                    "weight": 1,
                    "opacity": 1,
                    "fill": True,
                    "fillColor": "#ffffff",
                    "fillOpacity": 1.0,
                    "dashArray": "9"
                    "clickable": True,
                }
            hover_style (dict, optional): Hover style dictionary. Defaults to {}.
                hover_style is a dictionary of the following form:
                    hover_style = {"weight": style["weight"] + 1, "fillOpacity": 0.5}
            style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
                style_callback is a function that takes the feature as argument and should return a dictionary of the following form:
                style_callback = lambda feat: {"fillColor": feat["properties"]["color"]}
            info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
            encoding (str, optional): The encoding of the GeoJSON file. Defaults to "utf-8".
        """

        gdf, legend_dict = classify(
            data=data,
            column=column,
            cmap=cmap,
            colors=colors,
            labels=labels,
            scheme=scheme,
            k=k,
            legend_kwds=legend_kwds,
            classification_kwds=classification_kwds,
        )

        if legend_title is None:
            legend_title = column

        if style is None:
            style = {
                # "stroke": False,
                # "color": "#ff0000",
                "weight": 1,
                "opacity": 1,
                # "fill": True,
                # "fillColor": "#ffffff",
                "fillOpacity": 1.0,
                # "dashArray": "9"
                # "clickable": True,
            }
            if colors is not None:
                style["color"] = "#000000"

        if hover_style is None:
            hover_style = {"weight": style["weight"] + 1, "fillOpacity": 0.5}

        if style_callback is None:
            style_callback = lambda feat: {"fillColor": feat["properties"]["color"]}

        self.add_gdf(
            gdf,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            info_mode=info_mode,
            encoding=encoding,
            **kwargs,
        )
        if add_legend:
            self.add_legend(title=legend_title, legend_dict=legend_dict)

    def user_roi_coords(self, decimals=4):
        """Return the bounding box of the ROI as a list of coordinates.

        Args:
            decimals (int, optional): Number of decimals to round the coordinates to. Defaults to 4.
        """
        return bbox_coords(self.user_roi, decimals=decimals)

    def add_widget(
        self,
        content,
        position="bottomright",
        add_header=False,
        opened=True,
        show_close_button=True,
        widget_icon="gear",
        close_button_icon="times",
        widget_args={},
        close_button_args={},
        display_widget=None,
        **kwargs,
    ):
        """Add a widget (e.g., text, HTML, figure) to the map.

        Args:
            content (str | ipywidgets.Widget | object): The widget to add.
            position (str, optional): The position of the widget. Defaults to "bottomright".
            add_header (bool, optional): Whether to add a header with close buttons to the widget. Defaults to False.
            opened (bool, optional): Whether to open the toolbar. Defaults to True.
            show_close_button (bool, optional): Whether to show the close button. Defaults to True.
            widget_icon (str, optional): The icon name for the toolbar button. Defaults to 'gear'.
            close_button_icon (str, optional): The icon name for the close button. Defaults to "times".
            widget_args (dict, optional): Additional arguments to pass to the toolbar button. Defaults to {}.
            close_button_args (dict, optional): Additional arguments to pass to the close button. Defaults to {}.
            display_widget (ipywidgets.Widget, optional): The widget to be displayed when the toolbar is clicked.
            **kwargs: Additional arguments to pass to the HTML or Output widgets
        """

        allowed_positions = ["topleft", "topright", "bottomleft", "bottomright"]

        if position not in allowed_positions:
            raise Exception(f"position must be one of {allowed_positions}")

        if "layout" not in kwargs:
            kwargs["layout"] = widgets.Layout(padding="0px 4px 0px 4px")
        try:
            if add_header:
                if isinstance(content, str):
                    widget = widgets.HTML(value=content, **kwargs)
                else:
                    widget = content

                widget_template(
                    widget,
                    opened,
                    show_close_button,
                    widget_icon,
                    close_button_icon,
                    widget_args,
                    close_button_args,
                    display_widget,
                    self,
                    position,
                )
            else:
                if isinstance(content, str):
                    widget = widgets.HTML(value=content, **kwargs)
                else:
                    widget = widgets.Output(**kwargs)
                    with widget:
                        display(content)
                control = ipyleaflet.WidgetControl(widget=widget, position=position)
                self.add(control)

        except Exception as e:
            raise Exception(f"Error adding widget: {e}")

    def add_image(self, image, position="bottomright", **kwargs):
        """Add an image to the map.

        Args:
            image (str | ipywidgets.Image): The image to add.
            position (str, optional): The position of the image, can be one of "topleft",
                "topright", "bottomleft", "bottomright". Defaults to "bottomright".

        """

        if isinstance(image, str):
            if image.startswith("http"):
                image = widgets.Image(value=requests.get(image).content, **kwargs)
            elif os.path.exists(image):
                with open(image, "rb") as f:
                    image = widgets.Image(value=f.read(), **kwargs)
        elif isinstance(image, widgets.Image):
            pass
        else:
            raise Exception("Invalid image")

        self.add_widget(image, position=position, **kwargs)

    def add_html(self, html, position="bottomright", **kwargs):
        """Add HTML to the map.

        Args:
            html (str): The HTML to add.
            position (str, optional): The position of the HTML, can be one of "topleft",
                "topright", "bottomleft", "bottomright". Defaults to "bottomright".
        """
        self.add_widget(html, position=position, **kwargs)

    def add_text(
        self,
        text,
        fontsize=20,
        fontcolor="black",
        bold=False,
        padding="5px",
        background=True,
        bg_color="white",
        border_radius="5px",
        position="bottomright",
        **kwargs,
    ):
        """Add text to the map.

        Args:
            text (str): The text to add.
            fontsize (int, optional): The font size. Defaults to 20.
            fontcolor (str, optional): The font color. Defaults to "black".
            bold (bool, optional): Whether to use bold font. Defaults to False.
            padding (str, optional): The padding. Defaults to "5px".
            background (bool, optional): Whether to use background. Defaults to True.
            bg_color (str, optional): The background color. Defaults to "white".
            border_radius (str, optional): The border radius. Defaults to "5px".
            position (str, optional): The position of the widget. Defaults to "bottomright".
        """

        if background:
            text = f"""<div style="font-size: {fontsize}px; color: {fontcolor}; font-weight: {'bold' if bold else 'normal'};
            padding: {padding}; background-color: {bg_color};
            border-radius: {border_radius};">{text}</div>"""
        else:
            text = f"""<div style="font-size: {fontsize}px; color: {fontcolor}; font-weight: {'bold' if bold else 'normal'};
            padding: {padding};">{text}</div>"""

        self.add_html(text, position=position, **kwargs)

    def to_gradio(self, width="100%", height="500px", **kwargs):
        """Converts the map to an HTML string that can be used in Gradio. Removes unsupported elements, such as
            attribution and any code blocks containing functions. See https://github.com/gradio-app/gradio/issues/3190

        Args:
            width (str, optional): The width of the map. Defaults to '100%'.
            height (str, optional): The height of the map. Defaults to '500px'.

        Returns:
            str: The HTML string to use in Gradio.
        """

        print(
            "The ipyleaflet plotting backend does not support this function. Please use the folium backend instead."
        )

    def add_search_control(
        self,
        marker=None,
        url=None,
        zoom=5,
        property_name="display_name",
        position="topleft",
    ):
        """Add a search control to the map.

        Args:
            marker (ipyleaflet.Marker, optional): The marker to use. Defaults to None.
            url (str, optional): The URL to use for the search. Defaults to None.
            zoom (int, optional): The zoom level to use. Defaults to 5.
            property_name (str, optional): The property name to use. Defaults to "display_name".
            position (str, optional): The position of the widget. Defaults to "topleft".
        """
        if marker is None:
            marker = ipyleaflet.Marker(
                icon=ipyleaflet.AwesomeIcon(
                    name="check", marker_color="green", icon_color="darkgreen"
                )
            )

        if url is None:
            url = "https://nominatim.openstreetmap.org/search?format=json&q={s}"
        search = ipyleaflet.SearchControl(
            position=position,
            url=url,
            zoom=zoom,
            property_name=property_name,
            marker=marker,
        )
        self.add(search)

    def layer_to_image(
        self,
        layer_name: str,
        output: Optional[str] = None,
        crs: str = "EPSG:3857",
        scale: Optional[int] = None,
        region: Optional[ee.Geometry] = None,
        vis_params: Optional[Dict] = None,
        **kwargs: Any,
    ) -> None:
        """
        Converts a specific layer from Earth Engine to an image file.

        Args:
            layer_name (str): The name of the layer to convert.
            output (str): The output file path for the image. Defaults to None.
            crs (str, optional): The coordinate reference system (CRS) of the output image. Defaults to "EPSG:3857".
            scale (int, optional): The scale of the output image. Defaults to None.
            region (ee.Geometry, optional): The region of interest for the conversion. Defaults to None.
            vis_params (dict, optional): The visualization parameters. Defaults to None.
            **kwargs: Additional keyword arguments to pass to the `download_ee_image` function.

        Returns:
            None
        """

        if region is None:
            b = self.bounds
            west, south, east, north = b[0][1], b[0][0], b[1][1], b[1][0]
            region = ee.Geometry.BBox(west, south, east, north)

        if scale is None:
            scale = int(self.get_scale())

        if layer_name not in self.ee_layers.keys():
            raise ValueError(f"Layer {layer_name} does not exist.")

        if output is None:
            output = layer_name + ".tif"

        layer = self.ee_layers[layer_name]
        ee_object = layer["ee_object"]

        if vis_params is None:
            vis_params = layer["vis_params"]

        image = ee_object.visualize(**vis_params)
        if not output.endswith(".tif"):
            geotiff = output + ".tif"
        else:
            geotiff = output
        download_ee_image(image, geotiff, region, crs=crs, scale=scale, **kwargs)

        if not output.endswith(".tif"):
            geotiff_to_image(geotiff, output)
            os.remove(geotiff)

draw_control property

Gets the draw control.

Returns:

Name	Type	Description
Any	Any	The draw control.

draw_control_lite property

Gets the lite version of the draw control.

Returns:

Name	Type	Description
Any	Any	The lite draw control.

draw_features property

Gets the drawn features.

Returns:

Type	Description
List[Any]	List[Any]: The list of drawn features.

draw_last_feature property

Gets the last drawn feature.

Returns:

Type	Description
Optional[Any]	Optional[Any]: The last drawn feature.

draw_layer property

Gets the draw layer.

Returns:

Type	Description
Optional[Any]	Optional[Any]: The draw layer.

ee_layer_dict property

Gets the dictionary of EE layers.

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: The dictionary of EE layers.

ee_layer_names property

Gets the names of the EE layers.

Returns:

Type	Description
List[str]	List[str]: The names of the EE layers.

ee_raster_layer_names property

Gets the names of the EE raster layers.

Returns:

Type	Description
List[str]	List[str]: The names of the EE raster layers.

ee_raster_layers property

Gets the dictionary of EE raster layers.

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: The dictionary of EE raster layers.

ee_vector_layer_names property

Gets the names of the EE vector layers.

Returns:

Type	Description
List[str]	List[str]: The names of the EE vector layers.

ee_vector_layers property

Gets the dictionary of EE vector layers.

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: The dictionary of EE vector layers.

user_roi property

Gets the user region of interest.

Returns:

Type	Description
Optional[Any]	Optional[Any]: The user region of interest.

user_rois property

Gets the user regions of interest.

Returns:

Type	Description
Optional[Any]	Optional[Any]: The user regions of interest.

__init__(**kwargs)

Initialize a map object. The following additional parameters can be passed in addition to the ipyleaflet.Map parameters:

Parameters:

Name	Type	Description	Default
ee_initialize	bool	Whether or not to initialize ee. Defaults to True.	required
center	list	Center of the map (lat, lon). Defaults to [20, 0].	required
zoom	int	Zoom level of the map. Defaults to 2.	required
height	str	Height of the map. Defaults to "600px".	required
width	str	Width of the map. Defaults to "100%".	required
basemap	str	Name of the basemap to add to the map. Defaults to "ROADMAP". Other options include "ROADMAP", "SATELLITE", "TERRAIN".	required
add_google_map	bool	Whether to add Google Maps to the map. Defaults to True.	required
sandbox_path	str	The path to a sandbox folder for voila web app. Defaults to None.	required
lite_mode	bool	Whether to enable lite mode, which only displays zoom control on the map. Defaults to False.	required
data_ctrl	bool		required
zoom_ctrl	bool	Whether to add the zoom control to the map. Defaults to True.	required
fullscreen_ctrl	bool	Whether to add the fullscreen control to the map. Defaults to True.	required
search_ctrl	bool	Whether to add the search control to the map. Defaults to True.	required
draw_ctrl	bool	Whether to add the draw control to the map. Defaults to True.	required
scale_ctrl	bool	Whether to add the scale control to the map. Defaults to True.	required
measure_ctrl	bool	Whether to add the measure control to the map. Defaults to True.	required
toolbar_ctrl	bool	Whether to add the toolbar control to the map. Defaults to True.	required
layer_ctrl	bool	Whether to add the layer control to the map. Defaults to False.	required
attribution_ctrl	bool	Whether to add the attribution control to the map. Defaults to True.	required
**kwargs		Additional keyword arguments for ipyleaflet.Map.	{}

Source code in geemap/geemap.py

def __init__(self, **kwargs):
    """Initialize a map object. The following additional parameters can be
        passed in addition to the ipyleaflet.Map parameters:

    Args:
        ee_initialize (bool, optional): Whether or not to initialize ee. Defaults to True.
        center (list, optional): Center of the map (lat, lon). Defaults to [20, 0].
        zoom (int, optional): Zoom level of the map. Defaults to 2.
        height (str, optional): Height of the map. Defaults to "600px".
        width (str, optional): Width of the map. Defaults to "100%".
        basemap (str, optional): Name of the basemap to add to the map.
            Defaults to "ROADMAP". Other options include "ROADMAP", "SATELLITE", "TERRAIN".
        add_google_map (bool, optional): Whether to add Google Maps to the map. Defaults to True.
        sandbox_path (str, optional): The path to a sandbox folder for voila web app. Defaults to None.
        lite_mode (bool, optional): Whether to enable lite mode, which only displays
            zoom control on the map. Defaults to False.
        data_ctrl (bool, optional): Deprecated: use search_ctrl instead.
        zoom_ctrl (bool, optional): Whether to add the zoom control to the map. Defaults to True.
        fullscreen_ctrl (bool, optional): Whether to add the fullscreen control to the map. Defaults to True.
        search_ctrl (bool, optional): Whether to add the search control to the map. Defaults to True.
        draw_ctrl (bool, optional): Whether to add the draw control to the map. Defaults to True.
        scale_ctrl (bool, optional): Whether to add the scale control to the map. Defaults to True.
        measure_ctrl (bool, optional): Whether to add the measure control to the map. Defaults to True.
        toolbar_ctrl (bool, optional): Whether to add the toolbar control to the map. Defaults to True.
        layer_ctrl (bool, optional): Whether to add the layer control to the map. Defaults to False.
        attribution_ctrl (bool, optional): Whether to add the attribution control to the map. Defaults to True.
        **kwargs: Additional keyword arguments for ipyleaflet.Map.
    """
    warnings.filterwarnings("ignore")

    if isinstance(kwargs.get("height"), int):
        kwargs["height"] = str(kwargs["height"]) + "px"
    if isinstance(kwargs.get("width"), int):
        kwargs["width"] = str(kwargs["width"]) + "px"

    if "max_zoom" not in kwargs:
        kwargs["max_zoom"] = 24

    self._xyz_dict = get_xyz_dict()

    self.baseclass = "ipyleaflet"
    self._USER_AGENT_PREFIX = "geemap"
    self.kwargs = kwargs
    super().__init__(**kwargs)
    self._var_name = "Map"  # The Map variable name for converting JS to Python

    if kwargs.get("height"):
        self.layout.height = kwargs.get("height")

    # sandbox path for Voila app to restrict access to system directories.
    if "sandbox_path" not in kwargs:
        self.sandbox_path = None
    else:
        if os.path.exists(os.path.abspath(kwargs["sandbox_path"])):
            self.sandbox_path = kwargs["sandbox_path"]
        else:
            print("The sandbox path is invalid.")
            self.sandbox_path = None

    # Add Google Maps as the default basemap
    if kwargs.get("add_google_map", False):
        self.add_basemap("ROADMAP")

    # ipyleaflet built-in layer control
    self.layer_control = None

    if "ee_initialize" not in kwargs:
        kwargs["ee_initialize"] = True

    # Default reducer to use
    if kwargs["ee_initialize"]:
        self.roi_reducer = ee.Reducer.mean()
    self.roi_reducer_scale = None

add(obj, position='topright', **kwargs)

Adds a layer or control to the map.

Parameters:

Name	Type	Description	Default
obj	Union[str, Any]	The layer or control to add to the map.	required
position	str	The position of the control on the map. Defaults to "topright".	'topright'
**kwargs	Any	Additional keyword arguments.	{}

Source code in geemap/geemap.py

def add(
    self, obj: Union[str, Any], position: str = "topright", **kwargs: Any
) -> None:
    """Adds a layer or control to the map.

    Args:
        obj (Union[str, Any]): The layer or control to add to the map.
        position (str, optional): The position of the control on the map. Defaults to "topright".
        **kwargs: Additional keyword arguments.
    """
    if isinstance(obj, str):
        basemap = check_basemap(obj)
        if basemap in basemaps.keys():
            super().add(get_basemap(basemap))
            return

    if not isinstance(obj, str):
        super().add(obj, position=position, **kwargs)
        return

    obj = obj.lower()

    backward_compatibilities = {
        "zoom_ctrl": "zoom_control",
        "fullscreen_ctrl": "fullscreen_control",
        "scale_ctrl": "scale_control",
        "toolbar_ctrl": "toolbar",
        "draw_ctrl": "draw_control",
        "data_ctrl": "search_control",
        "search_ctrl": "search_control",
    }
    obj = backward_compatibilities.get(obj, obj)
    if obj == "measure_ctrl":
        measure = ipyleaflet.MeasureControl(
            position=position,
            active_color="orange",
            primary_length_unit="kilometers",
        )
        self.add(measure, position=position)
    elif obj == "layer_ctrl":
        layer_control = ipyleaflet.LayersControl(position=position)
        self.add(layer_control, position=position)
    else:
        super().add(obj, position=position, **kwargs)

add_basemap(basemap='ROADMAP', show=True, **kwargs)

Adds a basemap to the map.

Parameters:

Name	Type	Description	Default
basemap	Optional[str]	Can be one of the strings from basemaps. Defaults to 'ROADMAP'.	'ROADMAP'
show	Optional[bool]	Whether the basemap is visible or not. Defaults to True.	True
**kwargs	Any	Additional keyword arguments for the TileLayer.	{}

Source code in geemap/geemap.py

def add_basemap(
    self,
    basemap: Optional[str] = "ROADMAP",
    show: Optional[bool] = True,
    **kwargs: Any,
) -> None:
    """Adds a basemap to the map.

    Args:
        basemap (Optional[str], optional): Can be one of the strings from basemaps.
            Defaults to 'ROADMAP'.
        show (Optional[bool], optional): Whether the basemap is visible or not.
            Defaults to True.
        **kwargs: Additional keyword arguments for the TileLayer.
    """
    import xyzservices

    try:
        layer_names = self.get_layer_names()

        if isinstance(basemap, str):
            for map_name, tile_provider in self._available_basemaps.items():
                if basemap.upper() == map_name.upper():
                    basemap = tile_provider
                    break

        if isinstance(basemap, xyzservices.TileProvider):
            name = basemap.name
            url = basemap.build_url()
            attribution = basemap.attribution
            if "max_zoom" in basemap.keys():
                max_zoom = basemap["max_zoom"]
            else:
                max_zoom = 30
            layer = ipyleaflet.TileLayer(
                url=url,
                name=name,
                max_zoom=max_zoom,
                attribution=attribution,
                visible=show,
                **kwargs,
            )
            self.add(layer)
            arc_add_layer(url, name)
        elif basemap in basemaps and basemaps[basemap].name not in layer_names:
            self.add(basemap)
            self.layers[-1].visible = show
            arc_add_layer(basemaps[basemap].url, basemap)
        elif basemap in basemaps and basemaps[basemap].name in layer_names:
            print(f"{basemap} has been already added before.")
        elif basemap.startswith("http"):
            self.add_tile_layer(url=basemap, shown=show, **kwargs)
        else:
            print(
                "Basemap can only be one of the following:\n  {}".format(
                    "\n  ".join(basemaps.keys())
                )
            )

    except Exception as e:
        raise ValueError(
            "Basemap can only be one of the following:\n  {}".format(
                "\n  ".join(basemaps.keys())
            )
        )

add_basemap_widget(position='topright')

Add the Basemap GUI to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the Basemap GUI. Defaults to "topright".	'topright'

Source code in geemap/geemap.py

def add_basemap_widget(self, position: str = "topright") -> None:
    """Add the Basemap GUI to the map.

    Args:
        position (str, optional): The position of the Basemap GUI. Defaults to "topright".
    """
    super()._add_basemap_selector(position=position)

add_census_data(wms, layer, census_dict=None, **kwargs)

Adds a census data layer to the map.

Parameters:

Name	Type	Description	Default
wms	str	The wms to use. For example, "Current", "ACS 2021", "Census 2020". See the complete list at https://tigerweb.geo.census.gov/tigerwebmain/TIGERweb_wms.html	required
layer	str	The layer name to add to the map.	required
census_dict	dict	A dictionary containing census data. Defaults to None. It can be obtained from the get_census_dict() function.	None

Source code in geemap/geemap.py

def add_census_data(self, wms, layer, census_dict=None, **kwargs):
    """Adds a census data layer to the map.

    Args:
        wms (str): The wms to use. For example, "Current", "ACS 2021", "Census 2020".  See the complete list at https://tigerweb.geo.census.gov/tigerwebmain/TIGERweb_wms.html
        layer (str): The layer name to add to the map.
        census_dict (dict, optional): A dictionary containing census data. Defaults to None. It can be obtained from the get_census_dict() function.
    """

    try:
        if census_dict is None:
            census_dict = get_census_dict()

        if wms not in census_dict.keys():
            raise ValueError(
                f"The provided WMS is invalid. It must be one of {census_dict.keys()}"
            )

        layers = census_dict[wms]["layers"]
        if layer not in layers:
            raise ValueError(
                f"The layer name is not valid. It must be one of {layers}"
            )

        url = census_dict[wms]["url"]
        if "name" not in kwargs:
            kwargs["name"] = layer
        if "attribution" not in kwargs:
            kwargs["attribution"] = "U.S. Census Bureau"
        if "format" not in kwargs:
            kwargs["format"] = "image/png"
        if "transparent" not in kwargs:
            kwargs["transparent"] = True

        self.add_wms_layer(url, layer, **kwargs)

    except Exception as e:
        raise Exception(e)

add_circle_markers_from_xy(data, x='longitude', y='latitude', radius=10, popup=None, **kwargs)

Adds a marker cluster to the map. For a list of options, see https://ipyleaflet.readthedocs.io/en/latest/api_reference/circle_marker.html

Parameters:

Name	Type	Description	Default
data	str | DataFrame	A csv or Pandas DataFrame containing x, y, z values.	required
x	str	The column name for the x values. Defaults to "longitude".	'longitude'
y	str	The column name for the y values. Defaults to "latitude".	'latitude'
radius	int	The radius of the circle. Defaults to 10.	10
popup	list	A list of column names to be used as the popup. Defaults to None.	None

Source code in geemap/geemap.py

def add_circle_markers_from_xy(
    self,
    data,
    x="longitude",
    y="latitude",
    radius=10,
    popup=None,
    **kwargs,
):
    """Adds a marker cluster to the map. For a list of options, see https://ipyleaflet.readthedocs.io/en/latest/api_reference/circle_marker.html

    Args:
        data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
        x (str, optional): The column name for the x values. Defaults to "longitude".
        y (str, optional): The column name for the y values. Defaults to "latitude".
        radius (int, optional): The radius of the circle. Defaults to 10.
        popup (list, optional): A list of column names to be used as the popup. Defaults to None.

    """
    import pandas as pd

    data = github_raw_url(data)

    if isinstance(data, pd.DataFrame):
        df = data
    elif not data.startswith("http") and (not os.path.exists(data)):
        raise FileNotFoundError("The specified input csv does not exist.")
    else:
        df = pd.read_csv(data)

    col_names = df.columns.values.tolist()

    if popup is None:
        popup = col_names

    if not isinstance(popup, list):
        popup = [popup]

    if x not in col_names:
        raise ValueError(f"x must be one of the following: {', '.join(col_names)}")

    if y not in col_names:
        raise ValueError(f"y must be one of the following: {', '.join(col_names)}")

    for row in df.itertuples():
        html = ""
        for p in popup:
            html = html + "<b>" + p + "</b>" + ": " + str(getattr(row, p)) + "<br>"
        popup_html = widgets.HTML(html)

        marker = ipyleaflet.CircleMarker(
            location=[getattr(row, y), getattr(row, x)],
            radius=radius,
            popup=popup_html,
            **kwargs,
        )
        super().add(marker)

add_cog_layer(url, name='Untitled', attribution='', opacity=1.0, shown=True, bands=None, titiler_endpoint=None, **kwargs)

Adds a COG TileLayer to the map.

Parameters:

Name	Type	Description	Default
url	str	The URL of the COG tile layer.	required
name	str	The layer name to use for the layer. Defaults to 'Untitled'.	'Untitled'
attribution	str	The attribution to use. Defaults to ''.	''
opacity	float	The opacity of the layer. Defaults to 1.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
bands	list	A list of bands to use for the layer. Defaults to None.	None
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
**kwargs		Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale, color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/ and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3]	{}

Source code in geemap/geemap.py

def add_cog_layer(
    self,
    url,
    name="Untitled",
    attribution="",
    opacity=1.0,
    shown=True,
    bands=None,
    titiler_endpoint=None,
    **kwargs,
):
    """Adds a COG TileLayer to the map.

    Args:
        url (str): The URL of the COG tile layer.
        name (str, optional): The layer name to use for the layer. Defaults to 'Untitled'.
        attribution (str, optional): The attribution to use. Defaults to ''.
        opacity (float, optional): The opacity of the layer. Defaults to 1.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        bands (list, optional): A list of bands to use for the layer. Defaults to None.
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        **kwargs: Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale, color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/ and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3]
    """

    tile_url = cog_tile(url, bands, titiler_endpoint, **kwargs)
    bounds = cog_bounds(url, titiler_endpoint)
    self.add_tile_layer(tile_url, name, attribution, opacity, shown)
    self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

    if not hasattr(self, "cog_layer_dict"):
        self.cog_layer_dict = {}

    params = {
        "url": url,
        "titizer_endpoint": titiler_endpoint,
        "bounds": bounds,
        "type": "COG",
    }
    self.cog_layer_dict[name] = params

add_colorbar(vis_params=None, cmap='gray', discrete=False, label=None, orientation='horizontal', position='bottomright', transparent_bg=False, layer_name=None, font_size=9, axis_off=False, max_width=None, **kwargs)

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 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 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'
position	str	Position of the colorbar on the map. It can be one of: topleft, topright, bottomleft, and bottomright. Defaults to "bottomright".	'bottomright'
transparent_bg	bool	Whether to use transparent background. Defaults to False.	False
layer_name	str	The layer name associated with the colorbar. Defaults to None.	None
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

Raises:

Type	Description
TypeError	If the vis_params is not a dictionary.
ValueError	If the orientation is not either horizontal or vertical.
TypeError	If the provided min value is not scalar type.
TypeError	If the provided max value is not scalar type.
TypeError	If the provided opacity value is not scalar type.
TypeError	If cmap or palette is not provided.

Source code in geemap/geemap.py

def add_colorbar(
    self,
    vis_params: Optional[Dict[str, Any]] = None,
    cmap: str = "gray",
    discrete: bool = False,
    label: Optional[str] = None,
    orientation: str = "horizontal",
    position: str = "bottomright",
    transparent_bg: bool = False,
    layer_name: Optional[str] = None,
    font_size: int = 9,
    axis_off: bool = False,
    max_width: Optional[str] = None,
    **kwargs: Any,
) -> None:
    """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 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 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".
        position (str, optional): Position of the colorbar on the map. It can be one of: topleft, topright, bottomleft, and bottomright. Defaults to "bottomright".
        transparent_bg (bool, optional): Whether to use transparent background. Defaults to False.
        layer_name (str, optional): The layer name associated with the colorbar. Defaults to None.
        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.
        TypeError: If the provided min value is not scalar type.
        TypeError: If the provided max value is not scalar type.
        TypeError: If the provided opacity value is not scalar type.
        TypeError: If cmap or palette is not provided.
    """

    colorbar = self._add_colorbar(
        vis_params,
        cmap,
        discrete,
        label,
        orientation,
        position,
        transparent_bg,
        layer_name,
        font_size,
        axis_off,
        max_width,
        **kwargs,
    )
    self._colorbar = colorbar
    if not hasattr(self, "colorbars"):
        self.colorbars = [colorbar]
    else:
        self.colorbars.append(colorbar)

add_colorbar_branca(colors, vmin=0, vmax=1.0, index=None, caption='', categorical=False, step=None, height='45px', transparent_bg=False, position='bottomright', layer_name=None, **kwargs)

Add a branca colorbar to the map.

Parameters:

Name	Type	Description	Default
colors	list	The set of colors to be used for interpolation. Colors can be provided in the form: * tuples of RGBA ints between 0 and 255 (e.g: (255, 255, 0) or (255, 255, 0, 255)) * tuples of RGBA floats between 0. and 1. (e.g: (1.,1.,0.) or (1., 1., 0., 1.)) * HTML-like string (e.g: “#ffff00) * a color name or shortcut (e.g: “y” or “yellow”)	required
vmin	int	The minimal value for the colormap. Values lower than vmin will be bound directly to colors[0].. Defaults to 0.	0
vmax	float	The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1]. Defaults to 1.0.	1.0
index	list	The values corresponding to each color. It has to be sorted, and have the same length as colors. If None, a regular grid between vmin and vmax is created.. Defaults to None.	None
caption	str	The caption for the colormap. Defaults to "".	''
categorical	bool	Whether or not to create a categorical colormap. Defaults to False.	False
step	int	The step to split the LinearColormap into a StepColormap. Defaults to None.	None
height	str	The height of the colormap widget. Defaults to "45px".	'45px'
transparent_bg	bool	Whether to use transparent background for the colormap widget. Defaults to True.	False
position	str	The position for the colormap widget. Defaults to "bottomright".	'bottomright'
layer_name	str	Layer name of the colorbar to be associated with. Defaults to None.	None

Source code in geemap/geemap.py

def add_colorbar_branca(
    self,
    colors,
    vmin=0,
    vmax=1.0,
    index=None,
    caption="",
    categorical=False,
    step=None,
    height="45px",
    transparent_bg=False,
    position="bottomright",
    layer_name=None,
    **kwargs,
):
    """Add a branca colorbar to the map.

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

    """
    from branca.colormap import LinearColormap

    output = widgets.Output()
    output.layout.height = height

    if "width" in kwargs:
        output.layout.width = kwargs["width"]

    if isinstance(colors, Box):
        try:
            colors = list(colors["default"])
        except Exception as e:
            print("The provided color list is invalid.")
            raise Exception(e)

    if all(len(color) == 6 for color in colors):
        colors = ["#" + color for color in colors]

    colormap = LinearColormap(
        colors=colors, index=index, vmin=vmin, vmax=vmax, caption=caption
    )

    if categorical:
        if step is not None:
            colormap = colormap.to_step(step)
        elif index is not None:
            colormap = colormap.to_step(len(index) - 1)
        else:
            colormap = colormap.to_step(3)

    colormap_ctrl = ipyleaflet.WidgetControl(
        widget=output,
        position=position,
        transparent_bg=transparent_bg,
        **kwargs,
    )
    with output:
        output.outputs = ()
        display(colormap)

    self._colorbar = colormap_ctrl
    self.add(colormap_ctrl)

    if not hasattr(self, "colorbars"):
        self.colorbars = [colormap_ctrl]
    else:
        self.colorbars.append(colormap_ctrl)

    if layer_name in self.ee_layers:
        self.ee_layers[layer_name]["colorbar"] = colormap_ctrl

add_controls(controls, position='topleft')

Adds a list of controls to the map.

Parameters:

Name	Type	Description	Default
controls	Union[List[Any], Any]	A list of controls or a single control to add to the map.	required
position	str	The position of the controls on the map. Defaults to "topleft".	'topleft'

Source code in geemap/geemap.py

def add_controls(
    self, controls: Union[List[Any], Any], position: str = "topleft"
) -> None:
    """Adds a list of controls to the map.

    Args:
        controls (Union[List[Any], Any]): A list of controls or a single
            control to add to the map.
        position (str, optional): The position of the controls on the map.
            Defaults to "topleft".
    """
    if not isinstance(controls, list):
        controls = [controls]
    for control in controls:
        self.add(control, position)

add_data(data, column, colors=None, labels=None, cmap=None, scheme='Quantiles', k=5, add_legend=True, legend_title=None, legend_kwds=None, classification_kwds=None, layer_name='Untitled', style=None, hover_style=None, style_callback=None, info_mode='on_hover', encoding='utf-8', **kwargs)

Add vector data to the map with a variety of classification schemes.

Parameters:

Name	Type	Description	Default
data	str | DataFrame | GeoDataFrame	The data to classify. It can be a filepath to a vector dataset, a pandas dataframe, or a geopandas geodataframe.	required
column	str	The column to classify.	required
cmap	str	The name of a colormap recognized by matplotlib. Defaults to None.	None
colors	list	A list of colors to use for the classification. Defaults to None.	None
labels	list	A list of labels to use for the legend. Defaults to None.	None
scheme	str	Name of a choropleth classification scheme (requires mapclassify). Name of a choropleth classification scheme (requires mapclassify). A mapclassify.MapClassifier object will be used under the hood. Supported are all schemes provided by mapclassify (e.g. 'BoxPlot', 'EqualInterval', 'FisherJenks', 'FisherJenksSampled', 'HeadTailBreaks', 'JenksCaspall', 'JenksCaspallForced', 'JenksCaspallSampled', 'MaxP', 'MaximumBreaks', 'NaturalBreaks', 'Quantiles', 'Percentiles', 'StdMean', 'UserDefined'). Arguments can be passed in classification_kwds.	'Quantiles'
k	int	Number of classes (ignored if scheme is None or if column is categorical). Default to 5.	5
legend_kwds	dict	Keyword arguments to pass to :func:matplotlib.pyplot.legend or matplotlib.pyplot.colorbar. Defaults to None. Keyword arguments to pass to :func:matplotlib.pyplot.legend or Additional accepted keywords when scheme is specified: fmt : string A formatting specification for the bin edges of the classes in the legend. For example, to have no decimals: {"fmt": "{:.0f}"}. labels : list-like A list of legend labels to override the auto-generated labblels. Needs to have the same number of elements as the number of classes (k). interval : boolean (default False) An option to control brackets from mapclassify legend. If True, open/closed interval brackets are shown in the legend.	None
classification_kwds	dict	Keyword arguments to pass to mapclassify. Defaults to None.	None
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to None. style is a dictionary of the following form: style = { "stroke": False, "color": "#ff0000", "weight": 1, "opacity": 1, "fill": True, "fillColor": "#ffffff", "fillOpacity": 1.0, "dashArray": "9" "clickable": True, }	None
hover_style	dict	Hover style dictionary. Defaults to {}. hover_style is a dictionary of the following form: hover_style = {"weight": style["weight"] + 1, "fillOpacity": 0.5}	None
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None. style_callback is a function that takes the feature as argument and should return a dictionary of the following form: style_callback = lambda feat: {"fillColor": feat["properties"]["color"]}	None
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'
encoding	str	The encoding of the GeoJSON file. Defaults to "utf-8".	'utf-8'

Source code in geemap/geemap.py

def add_data(
    self,
    data,
    column,
    colors=None,
    labels=None,
    cmap=None,
    scheme="Quantiles",
    k=5,
    add_legend=True,
    legend_title=None,
    legend_kwds=None,
    classification_kwds=None,
    layer_name="Untitled",
    style=None,
    hover_style=None,
    style_callback=None,
    info_mode="on_hover",
    encoding="utf-8",
    **kwargs,
):
    """Add vector data to the map with a variety of classification schemes.

    Args:
        data (str | pd.DataFrame | gpd.GeoDataFrame): The data to classify. It can be a filepath to a vector dataset, a pandas dataframe, or a geopandas geodataframe.
        column (str): The column to classify.
        cmap (str, optional): The name of a colormap recognized by matplotlib. Defaults to None.
        colors (list, optional): A list of colors to use for the classification. Defaults to None.
        labels (list, optional): A list of labels to use for the legend. Defaults to None.
        scheme (str, optional): Name of a choropleth classification scheme (requires mapclassify).
            Name of a choropleth classification scheme (requires mapclassify).
            A mapclassify.MapClassifier object will be used
            under the hood. Supported are all schemes provided by mapclassify (e.g.
            'BoxPlot', 'EqualInterval', 'FisherJenks', 'FisherJenksSampled',
            'HeadTailBreaks', 'JenksCaspall', 'JenksCaspallForced',
            'JenksCaspallSampled', 'MaxP', 'MaximumBreaks',
            'NaturalBreaks', 'Quantiles', 'Percentiles', 'StdMean',
            'UserDefined'). Arguments can be passed in classification_kwds.
        k (int, optional): Number of classes (ignored if scheme is None or if column is categorical). Default to 5.
        legend_kwds (dict, optional): Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or `matplotlib.pyplot.colorbar`. Defaults to None.
            Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or
            Additional accepted keywords when `scheme` is specified:
            fmt : string
                A formatting specification for the bin edges of the classes in the
                legend. For example, to have no decimals: ``{"fmt": "{:.0f}"}``.
            labels : list-like
                A list of legend labels to override the auto-generated labblels.
                Needs to have the same number of elements as the number of
                classes (`k`).
            interval : boolean (default False)
                An option to control brackets from mapclassify legend.
                If True, open/closed interval brackets are shown in the legend.
        classification_kwds (dict, optional): Keyword arguments to pass to mapclassify. Defaults to None.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to None.
            style is a dictionary of the following form:
                style = {
                "stroke": False,
                "color": "#ff0000",
                "weight": 1,
                "opacity": 1,
                "fill": True,
                "fillColor": "#ffffff",
                "fillOpacity": 1.0,
                "dashArray": "9"
                "clickable": True,
            }
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
            hover_style is a dictionary of the following form:
                hover_style = {"weight": style["weight"] + 1, "fillOpacity": 0.5}
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
            style_callback is a function that takes the feature as argument and should return a dictionary of the following form:
            style_callback = lambda feat: {"fillColor": feat["properties"]["color"]}
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
        encoding (str, optional): The encoding of the GeoJSON file. Defaults to "utf-8".
    """

    gdf, legend_dict = classify(
        data=data,
        column=column,
        cmap=cmap,
        colors=colors,
        labels=labels,
        scheme=scheme,
        k=k,
        legend_kwds=legend_kwds,
        classification_kwds=classification_kwds,
    )

    if legend_title is None:
        legend_title = column

    if style is None:
        style = {
            # "stroke": False,
            # "color": "#ff0000",
            "weight": 1,
            "opacity": 1,
            # "fill": True,
            # "fillColor": "#ffffff",
            "fillOpacity": 1.0,
            # "dashArray": "9"
            # "clickable": True,
        }
        if colors is not None:
            style["color"] = "#000000"

    if hover_style is None:
        hover_style = {"weight": style["weight"] + 1, "fillOpacity": 0.5}

    if style_callback is None:
        style_callback = lambda feat: {"fillColor": feat["properties"]["color"]}

    self.add_gdf(
        gdf,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        info_mode=info_mode,
        encoding=encoding,
        **kwargs,
    )
    if add_legend:
        self.add_legend(title=legend_title, legend_dict=legend_dict)

add_draw_control(position='topleft')

Add a draw control to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the draw control. Defaults to "topleft".	'topleft'

Source code in geemap/geemap.py

def add_draw_control(self, position: str = "topleft") -> None:
    """Add a draw control to the map.

    Args:
        position (str, optional): The position of the draw control. Defaults to "topleft".
    """
    super().add("draw_control", position=position)

add_draw_control_lite(position='topleft')

Add a lite version draw control to the map for the plotting tool.

Parameters:

Name	Type	Description	Default
position	str	The position of the draw control. Defaults to "topleft".	'topleft'

Source code in geemap/geemap.py

def add_draw_control_lite(self, position: str = "topleft") -> None:
    """Add a lite version draw control to the map for the plotting tool.

    Args:
        position (str, optional): The position of the draw control. Defaults to "topleft".
    """
    super().add(
        "draw_control",
        position=position,
        marker={},
        rectangle={"shapeOptions": {"color": "#3388ff"}},
        circle={"shapeOptions": {"color": "#3388ff"}},
        circlemarker={},
        polyline={},
        polygon={},
        edit=False,
        remove=False,
    )

add_ee_layer(ee_object, vis_params=None, name=None, shown=True, opacity=1.0)

Adds a given EE object to the map as a layer.

Parameters:

Name	Type	Description	Default
ee_object	Union[FeatureCollection, Feature, Image, ImageCollection]	The object to add to the map.	required
vis_params	Optional[Dict[str, Any]]	The visualization parameters. Defaults to {}.	None
name	Optional[str]	The name of the layer. Defaults to 'Layer N'.	None
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
opacity	float	The layer's opacity represented as a number between 0 and 1. Defaults to 1.	1.0

Source code in geemap/geemap.py

def add_ee_layer(
    self,
    ee_object: Union[
        ee.FeatureCollection, ee.Feature, ee.Image, ee.ImageCollection
    ],
    vis_params: Optional[Dict[str, Any]] = None,
    name: Optional[str] = None,
    shown: bool = True,
    opacity: float = 1.0,
) -> None:
    """Adds a given EE object to the map as a layer.

    Args:
        ee_object (Union[ee.FeatureCollection, ee.Feature, ee.Image, ee.ImageCollection]):
            The object to add to the map.
        vis_params (Optional[Dict[str, Any]], optional): The visualization parameters.
            Defaults to {}.
        name (Optional[str], optional): The name of the layer. Defaults to 'Layer N'.
        shown (bool, optional): A flag indicating whether the layer should be on by
            default. Defaults to True.
        opacity (float, optional): The layer's opacity represented as a number
            between 0 and 1. Defaults to 1.
    """
    has_plot_dropdown = (
        hasattr(self, "_plot_dropdown_widget")
        and self._plot_dropdown_widget is not None
    )

    ee_layer = self.ee_layers.get(name, {})
    layer = ee_layer.get("ee_layer", None)
    if layer is not None:
        if isinstance(ee_layer["ee_object"], (ee.Image, ee.ImageCollection)):
            if has_plot_dropdown:
                self._plot_dropdown_widget.options = list(
                    self.ee_raster_layers.keys()
                )

    super().add_layer(ee_object, vis_params, name, shown, opacity)

    if isinstance(ee_object, (ee.Image, ee.ImageCollection)):
        if has_plot_dropdown:
            self._plot_dropdown_widget.options = list(self.ee_raster_layers.keys())

    tile_layer = self.ee_layers.get(name, {}).get("ee_layer", None)
    if tile_layer:
        arc_add_layer(tile_layer.url_format, name, shown, opacity)

add_gdf(gdf, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', zoom_to_layer=True, encoding='utf-8')

Adds a GeoDataFrame to the map.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoPandas GeoDataFrame.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'
zoom_to_layer	bool	Whether to zoom to the layer.	True
encoding	str	The encoding of the GeoDataFrame. Defaults to "utf-8".	'utf-8'

Source code in geemap/geemap.py

def add_gdf(
    self,
    gdf,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
    zoom_to_layer=True,
    encoding="utf-8",
):
    """Adds a GeoDataFrame to the map.

    Args:
        gdf (GeoDataFrame): A GeoPandas GeoDataFrame.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
        zoom_to_layer (bool, optional): Whether to zoom to the layer.
        encoding (str, optional): The encoding of the GeoDataFrame. Defaults to "utf-8".
    """

    data = gdf_to_geojson(gdf, epsg="4326")

    self.add_geojson(
        data,
        layer_name,
        style,
        hover_style,
        style_callback,
        fill_colors,
        info_mode,
        encoding,
    )

    if zoom_to_layer:
        import numpy as np

        bounds = gdf.to_crs(epsg="4326").bounds
        west = np.min(bounds["minx"])
        south = np.min(bounds["miny"])
        east = np.max(bounds["maxx"])
        north = np.max(bounds["maxy"])
        self.fit_bounds([[south, east], [north, west]])

add_gdf_from_postgis(sql, con, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', zoom_to_layer=True, **kwargs)

Reads a PostGIS database and returns data as a GeoDataFrame to be added to the map.

Parameters:

Name	Type	Description	Default
sql	str	SQL query to execute in selecting entries from database, or name of the table to read from the database.	required
con	Engine	Active connection to the database to query.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'
zoom_to_layer	bool	Whether to zoom to the layer.	True

Source code in geemap/geemap.py

def add_gdf_from_postgis(
    self,
    sql,
    con,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
    zoom_to_layer=True,
    **kwargs,
):
    """Reads a PostGIS database and returns data as a GeoDataFrame to be added to the map.

    Args:
        sql (str): SQL query to execute in selecting entries from database, or name of the table to read from the database.
        con (sqlalchemy.engine.Engine): Active connection to the database to query.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
        zoom_to_layer (bool, optional): Whether to zoom to the layer.
    """
    gdf = read_postgis(sql, con, **kwargs)
    gdf = gdf.to_crs("epsg:4326")
    self.add_gdf(
        gdf,
        layer_name,
        style,
        hover_style,
        style_callback,
        fill_colors,
        info_mode,
        zoom_to_layer,
    )

add_geojson(in_geojson, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', encoding='utf-8')

Adds a GeoJSON file to the map.

Parameters:

Name	Type	Description	Default
in_geojson	str | dict	The file path or http URL to the input GeoJSON or a dictionary containing the geojson.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'
encoding	str	The encoding of the GeoJSON file. Defaults to "utf-8".	'utf-8'

Raises:

Type	Description
FileNotFoundError	The provided GeoJSON file could not be found.

Source code in geemap/geemap.py

def add_geojson(
    self,
    in_geojson,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
    encoding="utf-8",
):
    """Adds a GeoJSON file to the map.

    Args:
        in_geojson (str | dict): The file path or http URL to the input GeoJSON or a dictionary containing the geojson.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
        encoding (str, optional): The encoding of the GeoJSON file. Defaults to "utf-8".

    Raises:
        FileNotFoundError: The provided GeoJSON file could not be found.
    """
    import json
    import random
    import requests
    import warnings

    warnings.filterwarnings("ignore")

    style_callback_only = False

    if len(style) == 0 and style_callback is not None:
        style_callback_only = True

    try:
        if isinstance(in_geojson, str):
            if in_geojson.startswith("http"):
                in_geojson = github_raw_url(in_geojson)
                data = requests.get(in_geojson).json()
            else:
                in_geojson = os.path.abspath(in_geojson)
                if not os.path.exists(in_geojson):
                    raise FileNotFoundError(
                        "The provided GeoJSON file could not be found."
                    )

                with open(in_geojson, encoding=encoding) as f:
                    data = json.load(f)
        elif isinstance(in_geojson, dict):
            data = in_geojson
        else:
            raise TypeError("The input geojson must be a type of str or dict.")
    except Exception as e:
        raise Exception(e)

    if not style:
        style = {
            # "stroke": True,
            "color": "#000000",
            "weight": 1,
            "opacity": 1,
            # "fill": True,
            # "fillColor": "#ffffff",
            "fillOpacity": 0.1,
            # "dashArray": "9"
            # "clickable": True,
        }
    elif "weight" not in style:
        style["weight"] = 1

    if not hover_style:
        hover_style = {"weight": style["weight"] + 1, "fillOpacity": 0.5}

    def random_color(feature):
        return {
            "color": "black",
            "fillColor": random.choice(fill_colors),
        }

    toolbar_button = widgets.ToggleButton(
        value=True,
        tooltip="Toolbar",
        icon="info",
        layout=widgets.Layout(
            width="28px", height="28px", padding="0px 0px 0px 4px"
        ),
    )

    close_button = widgets.ToggleButton(
        value=False,
        tooltip="Close the tool",
        icon="times",
        # button_style="primary",
        layout=widgets.Layout(
            height="28px", width="28px", padding="0px 0px 0px 4px"
        ),
    )

    html = widgets.HTML()
    html.layout.margin = "0px 10px 0px 10px"
    html.layout.max_height = "250px"
    html.layout.max_width = "250px"

    output_widget = widgets.VBox(
        [widgets.HBox([toolbar_button, close_button]), html]
    )
    info_control = ipyleaflet.WidgetControl(
        widget=output_widget, position="bottomright"
    )

    if info_mode in ["on_hover", "on_click"]:
        self.add(info_control)

    def toolbar_btn_click(change):
        if change["new"]:
            close_button.value = False
            output_widget.children = [
                widgets.VBox([widgets.HBox([toolbar_button, close_button]), html])
            ]
        else:
            output_widget.children = [widgets.HBox([toolbar_button, close_button])]

    toolbar_button.observe(toolbar_btn_click, "value")

    def close_btn_click(change):
        if change["new"]:
            toolbar_button.value = False
            if info_control in self.controls:
                self.remove_control(info_control)
            output_widget.close()

    close_button.observe(close_btn_click, "value")

    def update_html(feature, **kwargs):
        value = [
            "<b>{}: </b>{}<br>".format(prop, feature["properties"][prop])
            for prop in feature["properties"].keys()
        ][:-1]

        value = """{}""".format("".join(value))
        html.value = value

    if style_callback is None:
        style_callback = random_color

    if style_callback_only:
        geojson = ipyleaflet.GeoJSON(
            data=data,
            hover_style=hover_style,
            style_callback=style_callback,
            name=layer_name,
        )
    else:
        geojson = ipyleaflet.GeoJSON(
            data=data,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            name=layer_name,
        )

    if info_mode == "on_hover":
        geojson.on_hover(update_html)
    elif info_mode == "on_click":
        geojson.on_click(update_html)

    self.add(geojson)
    self.geojson_layers.append(geojson)

    if not hasattr(self, "json_layer_dict"):
        self.json_layer_dict = {}

    params = {
        "data": geojson,
        "style": style,
        "hover_style": hover_style,
        "style_callback": style_callback,
    }
    self.json_layer_dict[layer_name] = params

add_gui(name, position='topright', opened=True, show_close_button=True, **kwargs)

Add a GUI to the map.

Parameters:

Name	Type	Description	Default
name	str	The name of the GUI. Options include "layer_manager", "inspector", "plot", and "timelapse".	required
position	str	The position of the GUI. Defaults to "topright".	'topright'
opened	bool	Whether the GUI is opened. Defaults to True.	True
show_close_button	bool	Whether to show the close button. Defaults to True.	True
**kwargs	Any	Additional keyword arguments.	{}

Source code in geemap/geemap.py

def add_gui(
    self,
    name: str,
    position: str = "topright",
    opened: bool = True,
    show_close_button: bool = True,
    **kwargs: Any,
) -> None:
    """Add a GUI to the map.

    Args:
        name (str): The name of the GUI. Options include "layer_manager",
            "inspector", "plot", and "timelapse".
        position (str, optional): The position of the GUI. Defaults to "topright".
        opened (bool, optional): Whether the GUI is opened. Defaults to True.
        show_close_button (bool, optional): Whether to show the close button.
            Defaults to True.
        **kwargs: Additional keyword arguments.
    """
    name = name.lower()
    if name == "layer_manager":
        self.add_layer_manager(position, opened, show_close_button, **kwargs)
    elif name == "inspector":
        self.add_inspector(
            position=position,
            opened=opened,
            show_close_button=show_close_button,
            **kwargs,
        )
    elif name == "plot":
        self.add_plot_gui(position, **kwargs)
    elif name == "timelapse":
        from .toolbar import timelapse_gui

        timelapse_gui(self, **kwargs)

add_heatmap(data, latitude='latitude', longitude='longitude', value='value', name='Heat map', radius=25, **kwargs)

Adds a heat map to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/heatmap.html

Parameters:

Name	Type	Description	Default
data	str | list | DataFrame	File path or HTTP URL to the input file or a list of data points in the format of [[x1, y1, z1], [x2, y2, z2]]. For example, https://raw.githubusercontent.com/giswqs/leafmap/master/examples/data/world_cities.csv	required
latitude	str	The column name of latitude. Defaults to "latitude".	'latitude'
longitude	str	The column name of longitude. Defaults to "longitude".	'longitude'
value	str	The column name of values. Defaults to "value".	'value'
name	str	Layer name to use. Defaults to "Heat map".	'Heat map'
radius	int	Radius of each “point” of the heatmap. Defaults to 25.	25

Raises:

Type	Description
ValueError	If data is not a list.

Source code in geemap/geemap.py

def add_heatmap(
    self,
    data,
    latitude="latitude",
    longitude="longitude",
    value="value",
    name="Heat map",
    radius=25,
    **kwargs,
):
    """Adds a heat map to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/heatmap.html

    Args:
        data (str | list | pd.DataFrame): File path or HTTP URL to the input file or a list of data points in the format of [[x1, y1, z1], [x2, y2, z2]]. For example, https://raw.githubusercontent.com/giswqs/leafmap/master/examples/data/world_cities.csv
        latitude (str, optional): The column name of latitude. Defaults to "latitude".
        longitude (str, optional): The column name of longitude. Defaults to "longitude".
        value (str, optional): The column name of values. Defaults to "value".
        name (str, optional): Layer name to use. Defaults to "Heat map".
        radius (int, optional): Radius of each “point” of the heatmap. Defaults to 25.

    Raises:
        ValueError: If data is not a list.
    """
    import pandas as pd
    from ipyleaflet import Heatmap

    try:
        if isinstance(data, str):
            df = pd.read_csv(data)
            data = df[[latitude, longitude, value]].values.tolist()
        elif isinstance(data, pd.DataFrame):
            data = data[[latitude, longitude, value]].values.tolist()
        elif isinstance(data, list):
            pass
        else:
            raise ValueError("data must be a list, a DataFrame, or a file path.")

        heatmap = Heatmap(locations=data, radius=radius, name=name, **kwargs)
        self.add(heatmap)

    except Exception as e:
        raise Exception(e)

add_html(html, position='bottomright', **kwargs)

Add HTML to the map.

Parameters:

Name	Type	Description	Default
html	str	The HTML to add.	required
position	str	The position of the HTML, can be one of "topleft", "topright", "bottomleft", "bottomright". Defaults to "bottomright".	'bottomright'

Source code in geemap/geemap.py

def add_html(self, html, position="bottomright", **kwargs):
    """Add HTML to the map.

    Args:
        html (str): The HTML to add.
        position (str, optional): The position of the HTML, can be one of "topleft",
            "topright", "bottomleft", "bottomright". Defaults to "bottomright".
    """
    self.add_widget(html, position=position, **kwargs)

add_image(image, position='bottomright', **kwargs)

Add an image to the map.

Parameters:

Name	Type	Description	Default
image	str | Image	The image to add.	required
position	str	The position of the image, can be one of "topleft", "topright", "bottomleft", "bottomright". Defaults to "bottomright".	'bottomright'

Source code in geemap/geemap.py

def add_image(self, image, position="bottomright", **kwargs):
    """Add an image to the map.

    Args:
        image (str | ipywidgets.Image): The image to add.
        position (str, optional): The position of the image, can be one of "topleft",
            "topright", "bottomleft", "bottomright". Defaults to "bottomright".

    """

    if isinstance(image, str):
        if image.startswith("http"):
            image = widgets.Image(value=requests.get(image).content, **kwargs)
        elif os.path.exists(image):
            with open(image, "rb") as f:
                image = widgets.Image(value=f.read(), **kwargs)
    elif isinstance(image, widgets.Image):
        pass
    else:
        raise Exception("Invalid image")

    self.add_widget(image, position=position, **kwargs)

add_inspector(names=None, visible=True, decimals=2, position='topright', opened=True, show_close_button=True)

Add the Inspector GUI to the map.

Parameters:

Name	Type	Description	Default
names	str | list	The names of the layers to be included. 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 coordinates. Defaults to 2.	2
position	str	The position of the Inspector GUI. Defaults to "topright".	'topright'
opened	bool	Whether the control is opened. Defaults to True.	True

Source code in geemap/geemap.py

def add_inspector(
    self,
    names: Optional[Union[str, List[str]]] = None,
    visible: bool = True,
    decimals: int = 2,
    position: str = "topright",
    opened: bool = True,
    show_close_button: bool = True,
) -> None:
    """Add the Inspector GUI to the map.

    Args:
        names (str | list, optional): The names of the layers to be included. 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 coordinates. Defaults to 2.
        position (str, optional): The position of the Inspector GUI. Defaults to "topright".
        opened (bool, optional): Whether the control is opened. Defaults to True.
    """
    super()._add_inspector(
        position,
        names=names,
        visible=visible,
        decimals=decimals,
        opened=opened,
        show_close_button=show_close_button,
    )

add_kml(in_kml, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds a GeoJSON file to the map.

Parameters:

Name	Type	Description	Default
in_kml	str	The input file path to the KML.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Raises:

Type	Description
FileNotFoundError	The provided KML file could not be found.

Source code in geemap/geemap.py

def add_kml(
    self,
    in_kml,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds a GeoJSON file to the map.

    Args:
        in_kml (str): The input file path to the KML.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    Raises:
        FileNotFoundError: The provided KML file could not be found.
    """

    if isinstance(in_kml, str) and in_kml.startswith("http"):
        in_kml = github_raw_url(in_kml)
        in_kml = download_file(in_kml)

    in_kml = os.path.abspath(in_kml)
    if not os.path.exists(in_kml):
        raise FileNotFoundError("The provided KML file could not be found.")
    self.add_vector(
        in_kml,
        layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )

add_labels(data, column, font_size='12pt', font_color='black', font_family='arial', font_weight='normal', x='longitude', y='latitude', draggable=True, layer_name='Labels', **kwargs)

Adds a label layer to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/divicon.html

Parameters:

Name	Type	Description	Default
data	DataFrame | FeatureCollection	The input data to label.	required
column	str	The column name of the data to label.	required
font_size	str	The font size of the labels. Defaults to "12pt".	'12pt'
font_color	str	The font color of the labels. Defaults to "black".	'black'
font_family	str	The font family of the labels. Defaults to "arial".	'arial'
font_weight	str	The font weight of the labels, can be normal, bold. Defaults to "normal".	'normal'
x	str	The column name of the longitude. Defaults to "longitude".	'longitude'
y	str	The column name of the latitude. Defaults to "latitude".	'latitude'
draggable	bool	Whether the labels are draggable. Defaults to True.	True
layer_name	str	Layer name to use. Defaults to "Labels".	'Labels'

Source code in geemap/geemap.py

def add_labels(
    self,
    data,
    column,
    font_size="12pt",
    font_color="black",
    font_family="arial",
    font_weight="normal",
    x="longitude",
    y="latitude",
    draggable=True,
    layer_name="Labels",
    **kwargs,
):
    """Adds a label layer to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/divicon.html

    Args:
        data (pd.DataFrame | ee.FeatureCollection): The input data to label.
        column (str): The column name of the data to label.
        font_size (str, optional): The font size of the labels. Defaults to "12pt".
        font_color (str, optional): The font color of the labels. Defaults to "black".
        font_family (str, optional): The font family of the labels. Defaults to "arial".
        font_weight (str, optional): The font weight of the labels, can be normal, bold. Defaults to "normal".
        x (str, optional): The column name of the longitude. Defaults to "longitude".
        y (str, optional): The column name of the latitude. Defaults to "latitude".
        draggable (bool, optional): Whether the labels are draggable. Defaults to True.
        layer_name (str, optional): Layer name to use. Defaults to "Labels".

    """
    import warnings
    import pandas as pd

    warnings.filterwarnings("ignore")

    if isinstance(data, ee.FeatureCollection):
        centroids = vector_centroids(data)
        df = ee_to_df(centroids)
    elif isinstance(data, pd.DataFrame):
        df = data
    elif isinstance(data, str):
        ext = os.path.splitext(data)[1]
        if ext == ".csv":
            df = pd.read_csv(data)
        elif ext in [".geojson", ".json", ".shp", ".gpkg"]:
            try:
                import geopandas as gpd

                df = gpd.read_file(data)
                df[x] = df.centroid.x
                df[y] = df.centroid.y
            except Exception as _:
                print("geopandas is required to read geojson.")
                return

    else:
        raise ValueError("data must be a DataFrame or an ee.FeatureCollection.")

    if column not in df.columns:
        raise ValueError(f"column must be one of {', '.join(df.columns)}.")
    if x not in df.columns:
        raise ValueError(f"column must be one of {', '.join(df.columns)}.")
    if y not in df.columns:
        raise ValueError(f"column must be one of {', '.join(df.columns)}.")

    try:
        size = int(font_size.replace("pt", ""))
    except:
        raise ValueError("font_size must be something like '10pt'")

    labels = []
    for index in df.index:
        html = f'<div style="font-size: {font_size};color:{font_color};font-family:{font_family};font-weight: {font_weight}">{df[column][index]}</div>'
        marker = ipyleaflet.Marker(
            location=[df[y][index], df[x][index]],
            icon=ipyleaflet.DivIcon(
                icon_size=(1, 1),
                icon_anchor=(size, size),
                html=html,
                **kwargs,
            ),
            draggable=draggable,
        )
        labels.append(marker)
    layer_group = ipyleaflet.LayerGroup(layers=labels, name=layer_name)
    self.add(layer_group)
    self.labels = layer_group

add_landsat_ts_gif(layer_name='Timelapse', roi=None, label=None, start_year=1984, end_year=2021, start_date='06-10', end_date='09-20', bands=['NIR', 'Red', 'Green'], vis_params=None, dimensions=768, frames_per_second=10, font_size=30, font_color='white', add_progress_bar=True, progress_bar_color='white', progress_bar_height=5, out_gif=None, download=False, apply_fmask=True, nd_bands=None, nd_threshold=0, nd_palette=['black', 'blue'])

Adds a Landsat timelapse to the map.

Parameters:

Name	Type	Description	Default
layer_name	str	Layer name to show under the layer control. Defaults to 'Timelapse'.	'Timelapse'
roi	object	Region of interest to create the timelapse. Defaults to None.	None
label	str	A label to show on the GIF, such as place name. Defaults to None.	None
start_year	int	Starting year for the timelapse. Defaults to 1984.	1984
end_year	int	Ending year for the timelapse. Defaults to 2021.	2021
start_date	str	Starting date (month-day) each year for filtering ImageCollection. Defaults to '06-10'.	'06-10'
end_date	str	Ending date (month-day) each year for filtering ImageCollection. Defaults to '09-20'.	'09-20'
bands	list	Three bands selected from ['Blue', 'Green', 'Red', 'NIR', 'SWIR1', 'SWIR2', 'pixel_qa']. Defaults to ['NIR', 'Red', 'Green'].	['NIR', 'Red', 'Green']
vis_params	dict	Visualization parameters. Defaults to None.	None
dimensions	int	a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.	768
frames_per_second	int	Animation speed. Defaults to 10.	10
font_size	int	Font size of the animated text and label. Defaults to 30.	30
font_color	str	Font color of the animated text and label. Defaults to 'black'.	'white'
add_progress_bar	bool	Whether to add a progress bar at the bottom of the GIF. Defaults to True.	True
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'white'
progress_bar_height	int	Height of the progress bar. Defaults to 5.	5
out_gif	str	File path to the output animated GIF. Defaults to None.	None
download	bool	Whether to download the gif. Defaults to False.	False
apply_fmask	bool	Whether to apply Fmask (Function of mask) for automated clouds, cloud shadows, snow, and water masking.	True
nd_bands	list	A list of names specifying the bands to use, e.g., ['Green', 'SWIR1']. The normalized difference is computed as (first − second) / (first + second). Note that negative input values are forced to 0 so that the result is confined to the range (-1, 1).	None
nd_threshold	float	The threshold for extracting pixels from the normalized difference band.	0
nd_palette	str	The color palette to use for displaying the normalized difference band.	['black', 'blue']

Source code in geemap/geemap.py

def add_landsat_ts_gif(
    self,
    layer_name="Timelapse",
    roi=None,
    label=None,
    start_year=1984,
    end_year=2021,
    start_date="06-10",
    end_date="09-20",
    bands=["NIR", "Red", "Green"],
    vis_params=None,
    dimensions=768,
    frames_per_second=10,
    font_size=30,
    font_color="white",
    add_progress_bar=True,
    progress_bar_color="white",
    progress_bar_height=5,
    out_gif=None,
    download=False,
    apply_fmask=True,
    nd_bands=None,
    nd_threshold=0,
    nd_palette=["black", "blue"],
):
    """Adds a Landsat timelapse to the map.

    Args:
        layer_name (str, optional): Layer name to show under the layer control. Defaults to 'Timelapse'.
        roi (object, optional): Region of interest to create the timelapse. Defaults to None.
        label (str, optional): A label to show on the GIF, such as place name. Defaults to None.
        start_year (int, optional): Starting year for the timelapse. Defaults to 1984.
        end_year (int, optional): Ending year for the timelapse. Defaults to 2021.
        start_date (str, optional): Starting date (month-day) each year for filtering ImageCollection. Defaults to '06-10'.
        end_date (str, optional): Ending date (month-day) each year for filtering ImageCollection. Defaults to '09-20'.
        bands (list, optional): Three bands selected from ['Blue', 'Green', 'Red', 'NIR', 'SWIR1', 'SWIR2', 'pixel_qa']. Defaults to ['NIR', 'Red', 'Green'].
        vis_params (dict, optional): Visualization parameters. Defaults to None.
        dimensions (int, optional): a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.
        frames_per_second (int, optional): Animation speed. Defaults to 10.
        font_size (int, optional): Font size of the animated text and label. Defaults to 30.
        font_color (str, optional): Font color of the animated text and label. Defaults to 'black'.
        add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF. Defaults to True.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
        out_gif (str, optional): File path to the output animated GIF. Defaults to None.
        download (bool, optional): Whether to download the gif. Defaults to False.
        apply_fmask (bool, optional): Whether to apply Fmask (Function of mask) for automated clouds, cloud shadows, snow, and water masking.
        nd_bands (list, optional): A list of names specifying the bands to use, e.g., ['Green', 'SWIR1']. The normalized difference is computed as (first − second) / (first + second). Note that negative input values are forced to 0 so that the result is confined to the range (-1, 1).
        nd_threshold (float, optional): The threshold for extracting pixels from the normalized difference band.
        nd_palette (str, optional): The color palette to use for displaying the normalized difference band.

    """
    try:
        if roi is None:
            if self.draw_last_feature is not None:
                feature = self.draw_last_feature
                roi = feature.geometry()
            else:
                roi = ee.Geometry.Polygon(
                    [
                        [
                            [-115.471773, 35.892718],
                            [-115.471773, 36.409454],
                            [-114.271283, 36.409454],
                            [-114.271283, 35.892718],
                            [-115.471773, 35.892718],
                        ]
                    ],
                    None,
                    False,
                )
        elif isinstance(roi, ee.Feature) or isinstance(roi, ee.FeatureCollection):
            roi = roi.geometry()
        elif isinstance(roi, ee.Geometry):
            pass
        else:
            print("The provided roi is invalid. It must be an ee.Geometry")
            return

        geojson = ee_to_geojson(roi)
        bounds = minimum_bounding_box(geojson)
        geojson = adjust_longitude(geojson)
        roi = ee.Geometry(geojson)

        in_gif = landsat_timelapse(
            roi=roi,
            out_gif=out_gif,
            start_year=start_year,
            end_year=end_year,
            start_date=start_date,
            end_date=end_date,
            bands=bands,
            vis_params=vis_params,
            dimensions=dimensions,
            frames_per_second=frames_per_second,
            apply_fmask=apply_fmask,
            nd_bands=nd_bands,
            nd_threshold=nd_threshold,
            nd_palette=nd_palette,
            font_size=font_size,
            font_color=font_color,
            progress_bar_color=progress_bar_color,
            progress_bar_height=progress_bar_height,
        )
        in_nd_gif = in_gif.replace(".gif", "_nd.gif")

        if nd_bands is not None:
            add_text_to_gif(
                in_nd_gif,
                in_nd_gif,
                xy=("2%", "2%"),
                text_sequence=start_year,
                font_size=font_size,
                font_color=font_color,
                duration=int(1000 / frames_per_second),
                add_progress_bar=add_progress_bar,
                progress_bar_color=progress_bar_color,
                progress_bar_height=progress_bar_height,
            )

        if label is not None:
            add_text_to_gif(
                in_gif,
                in_gif,
                xy=("2%", "90%"),
                text_sequence=label,
                font_size=font_size,
                font_color=font_color,
                duration=int(1000 / frames_per_second),
                add_progress_bar=add_progress_bar,
                progress_bar_color=progress_bar_color,
                progress_bar_height=progress_bar_height,
            )
            # if nd_bands is not None:
            #     add_text_to_gif(in_nd_gif, in_nd_gif, xy=('2%', '90%'), text_sequence=label,
            #                     font_size=font_size, font_color=font_color, duration=int(1000 / frames_per_second), add_progress_bar=add_progress_bar, progress_bar_color=progress_bar_color, progress_bar_height=progress_bar_height)

        if is_tool("ffmpeg"):
            reduce_gif_size(in_gif)
            if nd_bands is not None:
                reduce_gif_size(in_nd_gif)

        print("Adding GIF to the map ...")
        self.image_overlay(url=in_gif, bounds=bounds, name=layer_name)
        if nd_bands is not None:
            self.image_overlay(
                url=in_nd_gif, bounds=bounds, name=layer_name + " ND"
            )
        print("The timelapse has been added to the map.")

        if download:
            link = create_download_link(
                in_gif,
                title="Click here to download the Landsat timelapse: ",
            )
            display(link)
            if nd_bands is not None:
                link2 = create_download_link(
                    in_nd_gif,
                    title="Click here to download the Normalized Difference Index timelapse: ",
                )
                display(link2)

    except Exception as e:
        raise Exception(e)

add_layer_control(position='topright')

Adds a layer control to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the layer control on the map. Defaults to "topright".	'topright'

Source code in geemap/geemap.py

def add_layer_control(self, position: str = "topright") -> None:
    """Adds a layer control to the map.

    Args:
        position (str, optional): The position of the layer control on the map.
            Defaults to "topright".
    """
    if self.layer_control is None:
        layer_control = ipyleaflet.LayersControl(position=position)
        self.add(layer_control)

add_layer_manager(position='topright', opened=True, show_close_button=True)

Add the Layer Manager to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the Layer Manager. Defaults to "topright".	'topright'
opened	bool	Whether the control is opened. Defaults to True.	True
show_close_button	bool	Whether to show the close button. Defaults to True.	True

Source code in geemap/geemap.py

def add_layer_manager(
    self,
    position: str = "topright",
    opened: bool = True,
    show_close_button: bool = True,
) -> None:
    """Add the Layer Manager to the map.

    Args:
        position (str, optional): The position of the Layer Manager. Defaults to "topright".
        opened (bool, optional): Whether the control is opened. Defaults to True.
        show_close_button (bool, optional): Whether to show the close button. Defaults to True.
    """
    super()._add_layer_manager(position)
    if layer_manager := self._layer_manager:
        layer_manager.collapsed = not opened
        layer_manager.close_button_hidden = not show_close_button

add_legend(title='Legend', legend_dict=None, keys=None, colors=None, position='bottomright', builtin_legend=None, layer_name=None, add_header=True, widget_args={}, **kwargs)

Adds a customized basemap to the map.

Parameters:

Name	Type	Description	Default
title	str	Title of the legend. Defaults to 'Legend'.	'Legend'
legend_dict	dict	A dictionary containing legend items as keys and color as values. If provided, keys and colors will be ignored. Defaults to None.	None
keys	list	A list of legend keys. Defaults to None.	None
colors	list	A list of legend colors. Defaults to None.	None
position	str	Position of the legend. Defaults to 'bottomright'.	'bottomright'
builtin_legend	str	Name of the builtin legend to add to the map. Defaults to None.	None
layer_name	str	The associated layer for the legend. Defaults to None.	None
add_header	bool	Whether the legend can be closed or not. Defaults to True.	True
widget_args	dict	Additional arguments passed to the widget_template() function. Defaults to {}.	{}

Source code in geemap/geemap.py

def add_legend(
    self,
    title: str = "Legend",
    legend_dict: Optional[Dict[str, str]] = None,
    keys: Optional[List[str]] = None,
    colors: Optional[List[str]] = None,
    position: str = "bottomright",
    builtin_legend: Optional[str] = None,
    layer_name: Optional[str] = None,
    add_header: bool = True,
    widget_args: Dict[str, Any] = {},
    **kwargs: Any,
) -> None:
    """Adds a customized basemap 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.
        layer_name (str, optional): The associated layer for the legend.
            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 {}.
    """
    try:
        legend = self._add_legend(
            title,
            legend_dict,
            keys,
            colors,
            position,
            builtin_legend,
            layer_name,
            add_header,
            widget_args,
            **kwargs,
        )
        self._legend = legend
        if not hasattr(self, "legends"):
            self.legends = [legend]
        else:
            self.legends.append(legend)
    except Exception as e:
        raise Exception(e)

add_marker(location, **kwargs)

Adds a marker to the map. More info about marker at https://ipyleaflet.readthedocs.io/en/latest/api_reference/marker.html.

Parameters:

Name	Type	Description	Default
location	list | tuple	The location of the marker in the format of [lat, lng].	required
**kwargs		Keyword arguments for the marker.	{}

Source code in geemap/geemap.py

def add_marker(self, location, **kwargs):
    """Adds a marker to the map. More info about marker at https://ipyleaflet.readthedocs.io/en/latest/api_reference/marker.html.

    Args:
        location (list | tuple): The location of the marker in the format of [lat, lng].

        **kwargs: Keyword arguments for the marker.
    """
    if isinstance(location, list):
        location = tuple(location)
    if isinstance(location, tuple):
        marker = ipyleaflet.Marker(location=location, **kwargs)
        self.add(marker)
    else:
        raise TypeError("The location must be a list or a tuple.")

add_marker_cluster(event='click', add_marker=True)

Captures user inputs and add markers to the map.

Parameters:

Name	Type	Description	Default
event	str	[description]. Defaults to 'click'.	'click'
add_marker	bool	If True, add markers to the map. Defaults to True.	True

Returns:

Name	Type	Description
object		a marker cluster.

Source code in geemap/geemap.py

def add_marker_cluster(self, event="click", add_marker=True):
    """Captures user inputs and add markers to the map.

    Args:
        event (str, optional): [description]. Defaults to 'click'.
        add_marker (bool, optional): If True, add markers to the map. Defaults to True.

    Returns:
        object: a marker cluster.
    """
    coordinates = []
    markers = []
    marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")
    self.last_click = []
    self.all_clicks = []
    if add_marker:
        self.add(marker_cluster)

    def handle_interaction(**kwargs):
        latlon = kwargs.get("coordinates")

        if event == "click" and kwargs.get("type") == "click":
            coordinates.append(latlon)
            self.last_click = latlon
            self.all_clicks = coordinates
            if add_marker:
                markers.append(ipyleaflet.Marker(location=latlon))
                marker_cluster.markers = markers
        elif kwargs.get("type") == "mousemove":
            pass

    # cursor style: https://www.w3schools.com/cssref/pr_class_cursor.asp
    self.default_style = {"cursor": "crosshair"}
    self.on_interaction(handle_interaction)

add_minimap(zoom=5, position='bottomright')

Adds a minimap (overview) to the ipyleaflet map.

Parameters:

Name	Type	Description	Default
zoom	int	Initial map zoom level. Defaults to 5.	5
position	str	Position of the minimap. Defaults to "bottomright".	'bottomright'

Source code in geemap/geemap.py

def add_minimap(self, zoom=5, position="bottomright"):
    """Adds a minimap (overview) to the ipyleaflet map.

    Args:
        zoom (int, optional): Initial map zoom level. Defaults to 5.
        position (str, optional): Position of the minimap. Defaults to "bottomright".
    """
    minimap = ipyleaflet.Map(
        zoom_control=False,
        attribution_control=False,
        zoom=zoom,
        center=self.center,
        layers=[get_basemap("ROADMAP")],
    )
    minimap.layout.width = "150px"
    minimap.layout.height = "150px"
    ipyleaflet.link((minimap, "center"), (self, "center"))
    minimap_control = ipyleaflet.WidgetControl(widget=minimap, position=position)
    self.add(minimap_control)

add_netcdf(filename, variables=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='NetCDF layer', shift_lon=True, lat='lat', lon='lon', **kwargs)

Generate an ipyleaflet/folium TileLayer from a netCDF file. If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer), try adding to following two lines to the beginning of the notebook if the raster does not render properly.

import os
os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = f'{os.environ['JUPYTERHUB_SERVICE_PREFIX'].lstrip('/')}/proxy/{{port}}'

Parameters:

Name	Type	Description	Default
filename	str	File path or HTTP URL to the netCDF file.	required
variables	int	The variable/band names to extract data from the netCDF file. Defaults to None. If None, all variables will be extracted.	None
port	str	The port to use for the server. Defaults to "default".	required
palette	str	The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale	None
vmin	float	The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
vmax	float	The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
nodata	float	The value from the band to use to interpret as not valid data. Defaults to None.	None
attribution	str	Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.	None
layer_name	str	The layer name to use. Defaults to "netCDF layer".	'NetCDF layer'
shift_lon	bool	Flag to shift longitude values from [0, 360] to the range [-180, 180]. Defaults to True.	True
lat	str	Name of the latitude variable. Defaults to 'lat'.	'lat'
lon	str	Name of the longitude variable. Defaults to 'lon'.	'lon'

Source code in geemap/geemap.py

def add_netcdf(
    self,
    filename,
    variables=None,
    palette=None,
    vmin=None,
    vmax=None,
    nodata=None,
    attribution=None,
    layer_name="NetCDF layer",
    shift_lon=True,
    lat="lat",
    lon="lon",
    **kwargs,
):
    """Generate an ipyleaflet/folium TileLayer from a netCDF file.
        If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer),
        try adding to following two lines to the beginning of the notebook if the raster does not render properly.

        import os
        os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = f'{os.environ['JUPYTERHUB_SERVICE_PREFIX'].lstrip('/')}/proxy/{{port}}'

    Args:
        filename (str): File path or HTTP URL to the netCDF file.
        variables (int, optional): The variable/band names to extract data from the netCDF file. Defaults to None. If None, all variables will be extracted.
        port (str, optional): The port to use for the server. Defaults to "default".
        palette (str, optional): The name of the color palette from `palettable` to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
        vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
        vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
        nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
        attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
        layer_name (str, optional): The layer name to use. Defaults to "netCDF layer".
        shift_lon (bool, optional): Flag to shift longitude values from [0, 360] to the range [-180, 180]. Defaults to True.
        lat (str, optional): Name of the latitude variable. Defaults to 'lat'.
        lon (str, optional): Name of the longitude variable. Defaults to 'lon'.
    """

    tif, vars = netcdf_to_tif(
        filename, shift_lon=shift_lon, lat=lat, lon=lon, return_vars=True
    )

    if variables is None:
        if len(vars) >= 3:
            band_idx = [1, 2, 3]
        else:
            band_idx = [1]
    else:
        if not set(variables).issubset(set(vars)):
            raise ValueError(f"The variables must be a subset of {vars}.")
        else:
            band_idx = [vars.index(v) + 1 for v in variables]

    self.add_raster(
        tif,
        band=band_idx,
        palette=palette,
        vmin=vmin,
        vmax=vmax,
        nodata=nodata,
        attribution=attribution,
        layer_name=layer_name,
        **kwargs,
    )

add_osm(query, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', which_result=None, by_osmid=False, buffer_dist=None, to_ee=False, geodesic=True)

Adds OSM data to the map.

Parameters:

Name	Type	Description	Default
query	str | dict | list	Query string(s) or structured dict(s) to geocode.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'
which_result	INT	Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.	None
by_osmid	bool	If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.	False
buffer_dist	float	Distance to buffer around the place geometry, in meters. Defaults to None.	None
to_ee	bool	Whether to convert the csv to an ee.FeatureCollection.	False
geodesic	bool	Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected.	True

Source code in geemap/geemap.py

def add_osm(
    self,
    query,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
    which_result=None,
    by_osmid=False,
    buffer_dist=None,
    to_ee=False,
    geodesic=True,
):
    """Adds OSM data to the map.

    Args:
        query (str | dict | list): Query string(s) or structured dict(s) to geocode.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
        which_result (INT, optional): Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
        by_osmid (bool, optional): If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
        buffer_dist (float, optional): Distance to buffer around the place geometry, in meters. Defaults to None.
        to_ee (bool, optional): Whether to convert the csv to an ee.FeatureCollection.
        geodesic (bool, optional): Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected.

    """
    gdf = osm_to_gdf(
        query, which_result=which_result, by_osmid=by_osmid, buffer_dist=buffer_dist
    )
    geojson = gdf.__geo_interface__

    if to_ee:
        fc = geojson_to_ee(geojson, geodesic=geodesic)
        self.addLayer(fc, {}, layer_name)
        self.zoomToObject(fc)
    else:
        self.add_geojson(
            geojson,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
        )
        bounds = gdf.bounds.iloc[0]
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

add_osm_from_address(address, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds OSM entities within some distance N, S, E, W of address to the map.

Parameters:

Name	Type	Description	Default
address	str	The address to geocode and use as the central point around which to get the geometries.	required
tags	dict	Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.	required
dist	int	Distance in meters. Defaults to 1000.	1000
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Source code in geemap/geemap.py

def add_osm_from_address(
    self,
    address,
    tags,
    dist=1000,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds OSM entities within some distance N, S, E, W of address to the map.

    Args:
        address (str): The address to geocode and use as the central point around which to get the geometries.
        tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
        dist (int, optional): Distance in meters. Defaults to 1000.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    """
    from .osm import osm_gdf_from_address

    gdf = osm_gdf_from_address(address, tags, dist)
    geojson = gdf.__geo_interface__

    self.add_geojson(
        geojson,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )
    self.zoom_to_gdf(gdf)

add_osm_from_bbox(north, south, east, west, tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds OSM entities within a N, S, E, W bounding box to the map.

Parameters:

Name	Type	Description	Default
north	float	Northern latitude of bounding box.	required
south	float	Southern latitude of bounding box.	required
east	float	Eastern longitude of bounding box.	required
west	float	Western longitude of bounding box.	required
tags	dict	Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Source code in geemap/geemap.py

def add_osm_from_bbox(
    self,
    north,
    south,
    east,
    west,
    tags,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds OSM entities within a N, S, E, W bounding box to the map.


    Args:
        north (float): Northern latitude of bounding box.
        south (float): Southern latitude of bounding box.
        east (float): Eastern longitude of bounding box.
        west (float): Western longitude of bounding box.
        tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    """
    from .osm import osm_gdf_from_bbox

    gdf = osm_gdf_from_bbox(north, south, east, west, tags)
    geojson = gdf.__geo_interface__

    self.add_geojson(
        geojson,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )
    self.zoom_to_gdf(gdf)

add_osm_from_geocode(query, which_result=None, by_osmid=False, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds OSM data of place(s) by name or ID to the map.

Parameters:

Name	Type	Description	Default
query	str | dict | list	Query string(s) or structured dict(s) to geocode.	required
which_result	int	Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.	None
by_osmid	bool	If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.	False
buffer_dist	float	Distance to buffer around the place geometry, in meters. Defaults to None.	None
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Source code in geemap/geemap.py

def add_osm_from_geocode(
    self,
    query,
    which_result=None,
    by_osmid=False,
    buffer_dist=None,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds OSM data of place(s) by name or ID to the map.

    Args:
        query (str | dict | list): Query string(s) or structured dict(s) to geocode.
        which_result (int, optional): Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
        by_osmid (bool, optional): If True, handle query as an OSM ID for lookup rather than text search. Defaults to False.
        buffer_dist (float, optional): Distance to buffer around the place geometry, in meters. Defaults to None.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    """
    from .osm import osm_gdf_from_geocode

    gdf = osm_gdf_from_geocode(
        query, which_result=which_result, by_osmid=by_osmid, buffer_dist=buffer_dist
    )
    geojson = gdf.__geo_interface__

    self.add_geojson(
        geojson,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )
    self.zoom_to_gdf(gdf)

add_osm_from_place(query, tags, which_result=None, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds OSM entities within boundaries of geocodable place(s) to the map.

Parameters:

Name	Type	Description	Default
query	str | dict | list	Query string(s) or structured dict(s) to geocode.	required
tags	dict	Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.	required
which_result	int	Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.	None
buffer_dist	float	Distance to buffer around the place geometry, in meters. Defaults to None.	None
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Source code in geemap/geemap.py

def add_osm_from_place(
    self,
    query,
    tags,
    which_result=None,
    buffer_dist=None,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds OSM entities within boundaries of geocodable place(s) to the map.

    Args:
        query (str | dict | list): Query string(s) or structured dict(s) to geocode.
        tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
        which_result (int, optional): Which geocoding result to use. if None, auto-select the first (Multi)Polygon or raise an error if OSM doesn't return one. to get the top match regardless of geometry type, set which_result=1. Defaults to None.
        buffer_dist (float, optional): Distance to buffer around the place geometry, in meters. Defaults to None.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    """
    from .osm import osm_gdf_from_place

    gdf = osm_gdf_from_place(query, tags, which_result, buffer_dist)
    geojson = gdf.__geo_interface__

    self.add_geojson(
        geojson,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )
    self.zoom_to_gdf(gdf)

add_osm_from_point(center_point, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds OSM entities within some distance N, S, E, W of a point to the map.

Parameters:

Name	Type	Description	Default
center_point	tuple	The (lat, lng) center point around which to get the geometries.	required
tags	dict	Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.	required
dist	int	Distance in meters. Defaults to 1000.	1000
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Source code in geemap/geemap.py

def add_osm_from_point(
    self,
    center_point,
    tags,
    dist=1000,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds OSM entities within some distance N, S, E, W of a point to the map.

    Args:
        center_point (tuple): The (lat, lng) center point around which to get the geometries.
        tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
        dist (int, optional): Distance in meters. Defaults to 1000.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    """
    from .osm import osm_gdf_from_point

    gdf = osm_gdf_from_point(center_point, tags, dist)
    geojson = gdf.__geo_interface__

    self.add_geojson(
        geojson,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )
    self.zoom_to_gdf(gdf)

add_osm_from_polygon(polygon, tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds OSM entities within boundaries of a (multi)polygon to the map.

Parameters:

Name	Type	Description	Default
polygon	Polygon | MultiPolygon	Geographic boundaries to fetch geometries within	required
tags	dict	Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Source code in geemap/geemap.py

def add_osm_from_polygon(
    self,
    polygon,
    tags,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds OSM entities within boundaries of a (multi)polygon to the map.

    Args:
        polygon (shapely.geometry.Polygon | shapely.geometry.MultiPolygon): Geographic boundaries to fetch geometries within
        tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    """
    from .osm import osm_gdf_from_polygon

    gdf = osm_gdf_from_polygon(polygon, tags)
    geojson = gdf.__geo_interface__

    self.add_geojson(
        geojson,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )
    self.zoom_to_gdf(gdf)

add_osm_from_view(tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover')

Adds OSM entities within the current map view to the map.

Parameters:

Name	Type	Description	Default
tags	dict	Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'

Source code in geemap/geemap.py

def add_osm_from_view(
    self,
    tags,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
):
    """Adds OSM entities within the current map view to the map.

    Args:
        tags (dict): Dict of tags used for finding objects in the selected area. Results returned are the union, not intersection of each individual tag. Each result matches at least one given tag. The dict keys should be OSM tags, (e.g., building, landuse, highway, etc) and the dict values should be either True to retrieve all items with the given tag, or a string to get a single tag-value combination, or a list of strings to get multiple values for the given tag. For example, tags = {‘building’: True} would return all building footprints in the area. tags = {‘amenity’:True, ‘landuse’:[‘retail’,’commercial’], ‘highway’:’bus_stop’} would return all amenities, landuse=retail, landuse=commercial, and highway=bus_stop.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".

    """
    from .osm import osm_gdf_from_bbox

    bounds = self.bounds
    if len(bounds) == 0:
        bounds = (
            (40.74824858675827, -73.98933637940563),
            (40.75068694343106, -73.98364473187601),
        )
    north, south, east, west = (
        bounds[1][0],
        bounds[0][0],
        bounds[1][1],
        bounds[0][1],
    )

    gdf = osm_gdf_from_bbox(north, south, east, west, tags)
    geojson = gdf.__geo_interface__

    self.add_geojson(
        geojson,
        layer_name=layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
    )
    self.zoom_to_gdf(gdf)

add_planet_by_month(year=2016, month=1, name=None, api_key=None, token_name='PLANET_API_KEY')

Adds a Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

Name	Type	Description	Default
year	int	The year of Planet global mosaic, must be >=2016. Defaults to 2016.	2016
month	int	The month of Planet global mosaic, must be 1-12. Defaults to 1.	1
name	str	The layer name to use. Defaults to None.	None
api_key	str	The Planet API key. Defaults to None.	None
token_name	str	The environment variable name of the API key. Defaults to "PLANET_API_KEY".	'PLANET_API_KEY'

Source code in geemap/geemap.py

def add_planet_by_month(
    self, year=2016, month=1, name=None, api_key=None, token_name="PLANET_API_KEY"
):
    """Adds a Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

    Args:
        year (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
        month (int, optional): The month of Planet global mosaic, must be 1-12. Defaults to 1.
        name (str, optional): The layer name to use. Defaults to None.
        api_key (str, optional): The Planet API key. Defaults to None.
        token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
    """
    layer = planet_tile_by_month(year, month, name, api_key, token_name)
    self.add(layer)

add_planet_by_quarter(year=2016, quarter=1, name=None, api_key=None, token_name='PLANET_API_KEY')

Adds a Planet global mosaic by quarter to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

Name	Type	Description	Default
year	int	The year of Planet global mosaic, must be >=2016. Defaults to 2016.	2016
quarter	int	The quarter of Planet global mosaic, must be 1-12. Defaults to 1.	1
name	str	The layer name to use. Defaults to None.	None
api_key	str	The Planet API key. Defaults to None.	None
token_name	str	The environment variable name of the API key. Defaults to "PLANET_API_KEY".	'PLANET_API_KEY'

Source code in geemap/geemap.py

def add_planet_by_quarter(
    self, year=2016, quarter=1, name=None, api_key=None, token_name="PLANET_API_KEY"
):
    """Adds a Planet global mosaic by quarter to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

    Args:
        year (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
        quarter (int, optional): The quarter of Planet global mosaic, must be 1-12. Defaults to 1.
        name (str, optional): The layer name to use. Defaults to None.
        api_key (str, optional): The Planet API key. Defaults to None.
        token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
    """
    layer = planet_tile_by_quarter(year, quarter, name, api_key, token_name)
    self.add(layer)

add_plot_gui(position='topright', **kwargs)

Adds the plot widget to the map.

Parameters:

Name	Type	Description	Default
position	str	Position of the widget. Defaults to "topright".	'topright'
**kwargs	Any	Additional keyword arguments.	{}

Source code in geemap/geemap.py

def add_plot_gui(self, position: str = "topright", **kwargs: Any) -> None:
    """Adds the plot widget to the map.

    Args:
        position (str, optional): Position of the widget. Defaults to "topright".
        **kwargs: Additional keyword arguments.
    """
    from .toolbar import ee_plot_gui

    ee_plot_gui(self, position, **kwargs)

add_point_layer(filename, popup=None, layer_name='Marker Cluster', **kwargs)

Adds a point layer to the map with a popup attribute.

Parameters:

Name	Type	Description	Default
filename	str	str, http url, path object or file-like object. Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO)	required
popup	str | list	Column name(s) to be used for popup. Defaults to None.	None
layer_name	str	A layer name to use. Defaults to "Marker Cluster".	'Marker Cluster'

Raises:

Type	Description
ValueError	If the specified column name does not exist.
ValueError	If the specified column names do not exist.

Source code in geemap/geemap.py

def add_point_layer(
    self, filename, popup=None, layer_name="Marker Cluster", **kwargs
):
    """Adds a point layer to the map with a popup attribute.

    Args:
        filename (str): str, http url, path object or file-like object. Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO)
        popup (str | list, optional): Column name(s) to be used for popup. Defaults to None.
        layer_name (str, optional): A layer name to use. Defaults to "Marker Cluster".

    Raises:
        ValueError: If the specified column name does not exist.
        ValueError: If the specified column names do not exist.
    """
    import warnings

    warnings.filterwarnings("ignore")
    check_package(name="geopandas", URL="https://geopandas.org")
    import geopandas as gpd

    self.default_style = {"cursor": "wait"}

    if not filename.startswith("http"):
        filename = os.path.abspath(filename)
    gdf = gpd.read_file(filename, **kwargs)
    df = gdf.to_crs(epsg="4326")
    col_names = df.columns.values.tolist()
    if popup is not None:
        if isinstance(popup, str) and (popup not in col_names):
            raise ValueError(
                f"popup must be one of the following: {', '.join(col_names)}"
            )
        elif isinstance(popup, list) and (
            not all(item in col_names for item in popup)
        ):
            raise ValueError(
                f"All popup items must be select from: {', '.join(col_names)}"
            )

    df["x"] = df.geometry.x
    df["y"] = df.geometry.y

    points = list(zip(df["y"], df["x"]))

    if popup is not None:
        if isinstance(popup, str):
            labels = df[popup]
            markers = [
                ipyleaflet.Marker(
                    location=point,
                    draggable=False,
                    popup=widgets.HTML(str(labels[index])),
                )
                for index, point in enumerate(points)
            ]
        elif isinstance(popup, list):
            labels = []
            for i in range(len(points)):
                label = ""
                for item in popup:
                    label = label + str(item) + ": " + str(df[item][i]) + "<br>"
                labels.append(label)
            df["popup"] = labels

            markers = [
                ipyleaflet.Marker(
                    location=point,
                    draggable=False,
                    popup=widgets.HTML(labels[index]),
                )
                for index, point in enumerate(points)
            ]

    else:
        markers = [
            ipyleaflet.Marker(location=point, draggable=False) for point in points
        ]

    marker_cluster = ipyleaflet.MarkerCluster(markers=markers, name=layer_name)
    self.add(marker_cluster)

    self.default_style = {"cursor": "default"}

add_points_from_xy(data, x='longitude', y='latitude', popup=None, layer_name='Marker Cluster', color_column=None, marker_colors=None, icon_colors=['white'], icon_names=['info'], spin=False, add_legend=True, **kwargs)

Adds a marker cluster to the map.

Parameters:

Name	Type	Description	Default
data	str | DataFrame	A csv or Pandas DataFrame containing x, y, z values.	required
x	str	The column name for the x values. Defaults to "longitude".	'longitude'
y	str	The column name for the y values. Defaults to "latitude".	'latitude'
popup	list	A list of column names to be used as the popup. Defaults to None.	None
layer_name	str	The name of the layer. Defaults to "Marker Cluster".	'Marker Cluster'
color_column	str	The column name for the color values. Defaults to None.	None
marker_colors	list	A list of colors to be used for the markers. Defaults to None.	None
icon_colors	list	A list of colors to be used for the icons. Defaults to ['white'].	['white']
icon_names	list	A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons. Defaults to ['info'].	['info']
spin	bool	If True, the icon will spin. Defaults to False.	False
add_legend	bool	If True, a legend will be added to the map. Defaults to True.	True

Source code in geemap/geemap.py

def add_points_from_xy(
    self,
    data,
    x="longitude",
    y="latitude",
    popup=None,
    layer_name="Marker Cluster",
    color_column=None,
    marker_colors=None,
    icon_colors=["white"],
    icon_names=["info"],
    spin=False,
    add_legend=True,
    **kwargs,
):
    """Adds a marker cluster to the map.

    Args:
        data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
        x (str, optional): The column name for the x values. Defaults to "longitude".
        y (str, optional): The column name for the y values. Defaults to "latitude".
        popup (list, optional): A list of column names to be used as the popup. Defaults to None.
        layer_name (str, optional): The name of the layer. Defaults to "Marker Cluster".
        color_column (str, optional): The column name for the color values. Defaults to None.
        marker_colors (list, optional): A list of colors to be used for the markers. Defaults to None.
        icon_colors (list, optional): A list of colors to be used for the icons. Defaults to ['white'].
        icon_names (list, optional): A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons. Defaults to ['info'].
        spin (bool, optional): If True, the icon will spin. Defaults to False.
        add_legend (bool, optional): If True, a legend will be added to the map. Defaults to True.

    """
    import pandas as pd

    data = github_raw_url(data)

    color_options = [
        "red",
        "blue",
        "green",
        "purple",
        "orange",
        "darkred",
        "lightred",
        "beige",
        "darkblue",
        "darkgreen",
        "cadetblue",
        "darkpurple",
        "white",
        "pink",
        "lightblue",
        "lightgreen",
        "gray",
        "black",
        "lightgray",
    ]

    if isinstance(data, pd.DataFrame):
        df = data
    elif not data.startswith("http") and (not os.path.exists(data)):
        raise FileNotFoundError("The specified input csv does not exist.")
    else:
        df = pd.read_csv(data)

    df = points_from_xy(df, x, y)

    col_names = df.columns.values.tolist()

    if color_column is not None and color_column not in col_names:
        raise ValueError(
            f"The color column {color_column} does not exist in the dataframe."
        )

    if color_column is not None:
        items = list(set(df[color_column]))

    else:
        items = None

    if color_column is not None and marker_colors is None:
        if len(items) > len(color_options):
            raise ValueError(
                f"The number of unique values in the color column {color_column} is greater than the number of available colors."
            )
        else:
            marker_colors = color_options[: len(items)]
    elif color_column is not None and marker_colors is not None:
        if len(items) != len(marker_colors):
            raise ValueError(
                f"The number of unique values in the color column {color_column} is not equal to the number of available colors."
            )

    if items is not None:
        if len(icon_colors) == 1:
            icon_colors = icon_colors * len(items)
        elif len(items) != len(icon_colors):
            raise ValueError(
                f"The number of unique values in the color column {color_column} is not equal to the number of available colors."
            )

        if len(icon_names) == 1:
            icon_names = icon_names * len(items)
        elif len(items) != len(icon_names):
            raise ValueError(
                f"The number of unique values in the color column {color_column} is not equal to the number of available colors."
            )

    if "geometry" in col_names:
        col_names.remove("geometry")

    if popup is not None:
        if isinstance(popup, str) and (popup not in col_names):
            raise ValueError(
                f"popup must be one of the following: {', '.join(col_names)}"
            )
        elif isinstance(popup, list) and (
            not all(item in col_names for item in popup)
        ):
            raise ValueError(
                f"All popup items must be select from: {', '.join(col_names)}"
            )
    else:
        popup = col_names

    df["x"] = df.geometry.x
    df["y"] = df.geometry.y

    points = list(zip(df["y"], df["x"]))

    if popup is not None:
        if isinstance(popup, str):
            labels = df[popup]

            markers = []
            for index, point in enumerate(points):
                if items is not None:
                    marker_color = marker_colors[
                        items.index(df[color_column][index])
                    ]
                    icon_name = icon_names[items.index(df[color_column][index])]
                    icon_color = icon_colors[items.index(df[color_column][index])]
                    marker_icon = ipyleaflet.AwesomeIcon(
                        name=icon_name,
                        marker_color=marker_color,
                        icon_color=icon_color,
                        spin=spin,
                    )
                else:
                    marker_icon = None

                marker = ipyleaflet.Marker(
                    location=point,
                    draggable=False,
                    popup=widgets.HTML(str(labels[index])),
                    icon=marker_icon,
                )
                markers.append(marker)

        elif isinstance(popup, list):
            labels = []
            for i in range(len(points)):
                label = ""
                for item in popup:
                    label = (
                        label
                        + "<b>"
                        + str(item)
                        + "</b>"
                        + ": "
                        + str(df[item][i])
                        + "<br>"
                    )
                labels.append(label)
            df["popup"] = labels

            markers = []
            for index, point in enumerate(points):
                if items is not None:
                    marker_color = marker_colors[
                        items.index(df[color_column][index])
                    ]
                    icon_name = icon_names[items.index(df[color_column][index])]
                    icon_color = icon_colors[items.index(df[color_column][index])]
                    marker_icon = ipyleaflet.AwesomeIcon(
                        name=icon_name,
                        marker_color=marker_color,
                        icon_color=icon_color,
                        spin=spin,
                    )
                else:
                    marker_icon = None

                marker = ipyleaflet.Marker(
                    location=point,
                    draggable=False,
                    popup=widgets.HTML(labels[index]),
                    icon=marker_icon,
                )
                markers.append(marker)

    else:
        markers = []
        for point in points:
            if items is not None:
                marker_color = marker_colors[items.index(df[color_column][index])]
                icon_name = icon_names[items.index(df[color_column][index])]
                icon_color = icon_colors[items.index(df[color_column][index])]
                marker_icon = ipyleaflet.AwesomeIcon(
                    name=icon_name,
                    marker_color=marker_color,
                    icon_color=icon_color,
                    spin=spin,
                )
            else:
                marker_icon = None

            marker = ipyleaflet.Marker(
                location=point, draggable=False, icon=marker_icon
            )
            markers.append(marker)

    marker_cluster = ipyleaflet.MarkerCluster(markers=markers, name=layer_name)
    self.add(marker_cluster)

    if items is not None and add_legend:
        marker_colors = [check_color(c) for c in marker_colors]
        self.add_legend(
            title=color_column.title(), colors=marker_colors, keys=items
        )

    self.default_style = {"cursor": "default"}

add_raster(source, indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Raster', zoom_to_layer=True, visible=True, array_args={}, **kwargs)

Add a local raster dataset to the map. If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and if the raster does not render properly, try installing jupyter-server-proxy using pip install jupyter-server-proxy, then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

import os
os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = 'proxy/{port}'

Parameters:

Name	Type	Description	Default
source	str	The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.	required
indexes	int	The band(s) to use. Band indexing starts at 1. Defaults to None.	None
colormap	str	The name of the colormap from matplotlib to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.	None
vmin	float	The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
vmax	float	The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
nodata	float	The value from the band to use to interpret as not valid data. Defaults to None.	None
attribution	str	Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.	None
layer_name	str	The layer name to use. Defaults to 'Raster'.	'Raster'
zoom_to_layer	bool	Whether to zoom to the extent of the layer. Defaults to True.	True
visible	bool	Whether the layer is visible. Defaults to True.	True
array_args	dict	Additional arguments to pass to array_to_memory_file when reading the raster. Defaults to {}.	{}

Source code in geemap/geemap.py

def add_raster(
    self,
    source,
    indexes=None,
    colormap=None,
    vmin=None,
    vmax=None,
    nodata=None,
    attribution=None,
    layer_name="Raster",
    zoom_to_layer=True,
    visible=True,
    array_args={},
    **kwargs,
):
    """Add a local raster dataset to the map.
        If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and
        if the raster does not render properly, try installing jupyter-server-proxy using `pip install jupyter-server-proxy`,
        then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

        import os
        os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = 'proxy/{port}'

    Args:
        source (str): The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
        indexes (int, optional): The band(s) to use. Band indexing starts at 1. Defaults to None.
        colormap (str, optional): The name of the colormap from `matplotlib` to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.
        vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
        vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
        nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
        attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
        layer_name (str, optional): The layer name to use. Defaults to 'Raster'.
        zoom_to_layer (bool, optional): Whether to zoom to the extent of the layer. Defaults to True.
        visible (bool, optional): Whether the layer is visible. Defaults to True.
        array_args (dict, optional): Additional arguments to pass to `array_to_memory_file` when reading the raster. Defaults to {}.
    """
    import numpy as np
    import xarray as xr

    if isinstance(source, np.ndarray) or isinstance(source, xr.DataArray):
        source = array_to_image(source, **array_args)

    tile_layer, tile_client = get_local_tile_layer(
        source,
        indexes=indexes,
        colormap=colormap,
        vmin=vmin,
        vmax=vmax,
        nodata=nodata,
        attribution=attribution,
        layer_name=layer_name,
        return_client=True,
        **kwargs,
    )
    tile_layer.visible = visible

    self.add(tile_layer)
    bounds = tile_client.bounds()  # [ymin, ymax, xmin, xmax]
    bounds = (
        bounds[2],
        bounds[0],
        bounds[3],
        bounds[1],
    )  # [minx, miny, maxx, maxy]
    if zoom_to_layer:
        self.zoom_to_bounds(bounds)

    arc_add_layer(tile_layer.url, layer_name, True, 1.0)
    if zoom_to_layer:
        arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

    if not hasattr(self, "cog_layer_dict"):
        self.cog_layer_dict = {}
    params = {
        "tile_layer": tile_layer,
        "tile_client": tile_client,
        "indexes": indexes,
        "band_names": tile_client.band_names,
        "bounds": bounds,
        "type": "LOCAL",
    }
    self.cog_layer_dict[layer_name] = params

add_remote_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name=None, **kwargs)

Add a remote Cloud Optimized GeoTIFF (COG) to the map.

Parameters:

Name	Type	Description	Default
source	str	The path to the remote Cloud Optimized GeoTIFF.	required
band	int	The band to use. Band indexing starts at 1. Defaults to None.	None
palette	str	The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale	None
vmin	float	The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
vmax	float	The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
nodata	float	The value from the band to use to interpret as not valid data. Defaults to None.	None
attribution	str	Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.	None
layer_name	str	The layer name to use. Defaults to None.	None

Source code in geemap/geemap.py

def add_remote_tile(
    self,
    source,
    band=None,
    palette=None,
    vmin=None,
    vmax=None,
    nodata=None,
    attribution=None,
    layer_name=None,
    **kwargs,
):
    """Add a remote Cloud Optimized GeoTIFF (COG) to the map.

    Args:
        source (str): The path to the remote Cloud Optimized GeoTIFF.
        band (int, optional): The band to use. Band indexing starts at 1. Defaults to None.
        palette (str, optional): The name of the color palette from `palettable` to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale
        vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
        vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
        nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
        attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
        layer_name (str, optional): The layer name to use. Defaults to None.
    """
    if isinstance(source, str) and source.startswith("http"):
        self.add_raster(
            source,
            band=band,
            palette=palette,
            vmin=vmin,
            vmax=vmax,
            nodata=nodata,
            attribution=attribution,
            layer_name=layer_name,
            **kwargs,
        )
    else:
        raise Exception("The source must be a URL.")

add_search_control(marker=None, url=None, zoom=5, property_name='display_name', position='topleft')

Add a search control to the map.

Parameters:

Name	Type	Description	Default
marker	Marker	The marker to use. Defaults to None.	None
url	str	The URL to use for the search. Defaults to None.	None
zoom	int	The zoom level to use. Defaults to 5.	5
property_name	str	The property name to use. Defaults to "display_name".	'display_name'
position	str	The position of the widget. Defaults to "topleft".	'topleft'

Source code in geemap/geemap.py

def add_search_control(
    self,
    marker=None,
    url=None,
    zoom=5,
    property_name="display_name",
    position="topleft",
):
    """Add a search control to the map.

    Args:
        marker (ipyleaflet.Marker, optional): The marker to use. Defaults to None.
        url (str, optional): The URL to use for the search. Defaults to None.
        zoom (int, optional): The zoom level to use. Defaults to 5.
        property_name (str, optional): The property name to use. Defaults to "display_name".
        position (str, optional): The position of the widget. Defaults to "topleft".
    """
    if marker is None:
        marker = ipyleaflet.Marker(
            icon=ipyleaflet.AwesomeIcon(
                name="check", marker_color="green", icon_color="darkgreen"
            )
        )

    if url is None:
        url = "https://nominatim.openstreetmap.org/search?format=json&q={s}"
    search = ipyleaflet.SearchControl(
        position=position,
        url=url,
        zoom=zoom,
        property_name=property_name,
        marker=marker,
    )
    self.add(search)

add_shp(in_shp, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', encoding='utf-8')

Adds a shapefile to the map.

Parameters:

Name	Type	Description	Default
in_shp	str	The input file path to the shapefile.	required
layer_name	str	The layer name to be used.. Defaults to "Untitled".	'Untitled'
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'
encoding	str	The encoding of the shapefile. Defaults to "utf-8".	'utf-8'

Raises:

Type	Description
FileNotFoundError	The provided shapefile could not be found.

Source code in geemap/geemap.py

def add_shp(
    self,
    in_shp,
    layer_name="Untitled",
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
    encoding="utf-8",
):
    """Adds a shapefile to the map.

    Args:
        in_shp (str): The input file path to the shapefile.
        layer_name (str, optional): The layer name to be used.. Defaults to "Untitled".
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
        encoding (str, optional): The encoding of the shapefile. Defaults to "utf-8".

    Raises:
        FileNotFoundError: The provided shapefile could not be found.
    """
    in_shp = os.path.abspath(in_shp)
    if not os.path.exists(in_shp):
        raise FileNotFoundError("The provided shapefile could not be found.")

    geojson = shp_to_geojson(in_shp)
    self.add_geojson(
        geojson,
        layer_name,
        style,
        hover_style,
        style_callback,
        fill_colors,
        info_mode,
        encoding,
    )

add_stac_layer(url=None, collection=None, item=None, assets=None, bands=None, titiler_endpoint=None, name='STAC Layer', attribution='', opacity=1.0, shown=True, **kwargs)

Adds a STAC TileLayer to the map.

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json	None
collection	str	The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.	None
item	str	The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.	None
assets	str | list	The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"].	None
bands	list	A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]	None
titiler_endpoint	str	Titiler endpoint, e.g., "https://titiler.xyz", "https://planetarycomputer.microsoft.com/api/data/v1", "planetary-computer", "pc". Defaults to None.	None
name	str	The layer name to use for the layer. Defaults to 'STAC Layer'.	'STAC Layer'
attribution	str	The attribution to use. Defaults to ''.	''
opacity	float	The opacity of the layer. Defaults to 1.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True

Source code in geemap/geemap.py

def add_stac_layer(
    self,
    url=None,
    collection=None,
    item=None,
    assets=None,
    bands=None,
    titiler_endpoint=None,
    name="STAC Layer",
    attribution="",
    opacity=1.0,
    shown=True,
    **kwargs,
):
    """Adds a STAC TileLayer to the map.

    Args:
        url (str): HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json
        collection (str): The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.
        item (str): The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.
        assets (str | list): The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"].
        bands (list): A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]
        titiler_endpoint (str, optional): Titiler endpoint, e.g., "https://titiler.xyz", "https://planetarycomputer.microsoft.com/api/data/v1", "planetary-computer", "pc". Defaults to None.
        name (str, optional): The layer name to use for the layer. Defaults to 'STAC Layer'.
        attribution (str, optional): The attribution to use. Defaults to ''.
        opacity (float, optional): The opacity of the layer. Defaults to 1.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
    """
    tile_url = stac_tile(
        url, collection, item, assets, bands, titiler_endpoint, **kwargs
    )
    bounds = stac_bounds(url, collection, item, titiler_endpoint)
    self.add_tile_layer(tile_url, name, attribution, opacity, shown)
    self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

    if not hasattr(self, "cog_layer_dict"):
        self.cog_layer_dict = {}

    if assets is None and bands is not None:
        assets = bands

    params = {
        "url": url,
        "collection": collection,
        "item": item,
        "assets": assets,
        "bounds": bounds,
        "titiler_endpoint": titiler_endpoint,
        "type": "STAC",
    }

    self.cog_layer_dict[name] = params

add_styled_vector(ee_object, column, palette, layer_name='Untitled', shown=True, opacity=1.0, **kwargs)

Adds a styled vector to the map.

Parameters:

Name	Type	Description	Default
ee_object	object	An ee.FeatureCollection.	required
column	str	The column name to use for styling.	required
palette	list | dict	The palette (e.g., list of colors or a dict containing label and color pairs) to use for styling.	required
layer_name	str	The name to be used for the new layer. Defaults to "Untitled".	'Untitled'
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
opacity	float	The opacity of the layer. Defaults to 1.0.	1.0

Source code in geemap/geemap.py

def add_styled_vector(
    self,
    ee_object,
    column,
    palette,
    layer_name="Untitled",
    shown=True,
    opacity=1.0,
    **kwargs,
):
    """Adds a styled vector to the map.

    Args:
        ee_object (object): An ee.FeatureCollection.
        column (str): The column name to use for styling.
        palette (list | dict): The palette (e.g., list of colors or a dict containing label and color pairs) to use for styling.
        layer_name (str, optional): The name to be used for the new layer. Defaults to "Untitled".
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        opacity (float, optional): The opacity of the layer. Defaults to 1.0.
    """
    if isinstance(palette, str):
        from .colormaps import get_palette

        count = ee_object.size().getInfo()
        palette = get_palette(palette, count)

    styled_vector = vector_styling(ee_object, column, palette, **kwargs)
    self.addLayer(
        styled_vector.style(**{"styleProperty": "style"}),
        {},
        layer_name,
        shown,
        opacity,
    )

add_text(text, fontsize=20, fontcolor='black', bold=False, padding='5px', background=True, bg_color='white', border_radius='5px', position='bottomright', **kwargs)

Add text to the map.

Parameters:

Name	Type	Description	Default
text	str	The text to add.	required
fontsize	int	The font size. Defaults to 20.	20
fontcolor	str	The font color. Defaults to "black".	'black'
bold	bool	Whether to use bold font. Defaults to False.	False
padding	str	The padding. Defaults to "5px".	'5px'
background	bool	Whether to use background. Defaults to True.	True
bg_color	str	The background color. Defaults to "white".	'white'
border_radius	str	The border radius. Defaults to "5px".	'5px'
position	str	The position of the widget. Defaults to "bottomright".	'bottomright'

Source code in geemap/geemap.py

def add_text(
    self,
    text,
    fontsize=20,
    fontcolor="black",
    bold=False,
    padding="5px",
    background=True,
    bg_color="white",
    border_radius="5px",
    position="bottomright",
    **kwargs,
):
    """Add text to the map.

    Args:
        text (str): The text to add.
        fontsize (int, optional): The font size. Defaults to 20.
        fontcolor (str, optional): The font color. Defaults to "black".
        bold (bool, optional): Whether to use bold font. Defaults to False.
        padding (str, optional): The padding. Defaults to "5px".
        background (bool, optional): Whether to use background. Defaults to True.
        bg_color (str, optional): The background color. Defaults to "white".
        border_radius (str, optional): The border radius. Defaults to "5px".
        position (str, optional): The position of the widget. Defaults to "bottomright".
    """

    if background:
        text = f"""<div style="font-size: {fontsize}px; color: {fontcolor}; font-weight: {'bold' if bold else 'normal'};
        padding: {padding}; background-color: {bg_color};
        border-radius: {border_radius};">{text}</div>"""
    else:
        text = f"""<div style="font-size: {fontsize}px; color: {fontcolor}; font-weight: {'bold' if bold else 'normal'};
        padding: {padding};">{text}</div>"""

    self.add_html(text, position=position, **kwargs)

add_tile_layer(url='https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', name='Untitled', attribution='', opacity=1.0, shown=True, **kwargs)

Adds a TileLayer to the map.

Parameters:

Name	Type	Description	Default
url	str	The URL of the tile layer. Defaults to 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'.	'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
name	str	The layer name to use for the layer. Defaults to 'Untitled'.	'Untitled'
attribution	str	The attribution to use. Defaults to ''.	''
opacity	float	The opacity of the layer. Defaults to 1.0.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True

Source code in geemap/geemap.py

def add_tile_layer(
    self,
    url: str = "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
    name: str = "Untitled",
    attribution: str = "",
    opacity: float = 1.0,
    shown: bool = True,
    **kwargs: Any,
) -> None:
    """Adds a TileLayer to the map.

    Args:
        url (str, optional): The URL of the tile layer. Defaults to
            'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'.
        name (str, optional): The layer name to use for the layer. Defaults to 'Untitled'.
        attribution (str, optional): The attribution to use. Defaults to ''.
        opacity (float, optional): The opacity of the layer. Defaults to 1.0.
        shown (bool, optional): A flag indicating whether the layer should
            be on by default. Defaults to True.
    """

    if "max_zoom" not in kwargs:
        kwargs["max_zoom"] = 100
    if "max_native_zoom" not in kwargs:
        kwargs["max_native_zoom"] = 100

    try:
        tile_layer = ipyleaflet.TileLayer(
            url=url,
            name=name,
            attribution=attribution,
            opacity=opacity,
            visible=shown,
            **kwargs,
        )
        self.add(tile_layer)

    except Exception as e:
        print("Failed to add the specified TileLayer.")
        raise Exception(e)

add_time_slider(ee_object, vis_params={}, region=None, layer_name='Time series', labels=None, time_interval=1, position='bottomright', slider_length='150px', date_format='YYYY-MM-dd', opacity=1.0, **kwargs)

Adds a time slider to the map.

Parameters:

Name	Type	Description	Default
ee_object	Image | ImageCollection	The Image or ImageCollection to visualize.	required
vis_params	dict	Visualization parameters to use for visualizing image. Defaults to {}.	{}
region	Geometry | FeatureCollection	The region to visualize.	None
layer_name	str	The layer name to be used. Defaults to "Time series".	'Time series'
labels	list	The list of labels to be used for the time series. Defaults to None.	None
time_interval	int	Time interval in seconds. Defaults to 1.	1
position	str	Position to place the time slider, can be any of ['topleft', 'topright', 'bottomleft', 'bottomright']. Defaults to "bottomright".	'bottomright'
slider_length	str	Length of the time slider. Defaults to "150px".	'150px'
date_format	str	The date format to use. Defaults to 'YYYY-MM-dd'.	'YYYY-MM-dd'
opacity	float	The opacity of layers. Defaults to 1.0.	1.0

Raises:

Type	Description
TypeError	If the ee_object is not ee.Image | ee.ImageCollection.

Source code in geemap/geemap.py

def add_time_slider(
    self,
    ee_object,
    vis_params={},
    region=None,
    layer_name="Time series",
    labels=None,
    time_interval=1,
    position="bottomright",
    slider_length="150px",
    date_format="YYYY-MM-dd",
    opacity=1.0,
    **kwargs,
):
    """Adds a time slider to the map.

    Args:
        ee_object (ee.Image | ee.ImageCollection): The Image or ImageCollection to visualize.
        vis_params (dict, optional): Visualization parameters to use for visualizing image. Defaults to {}.
        region (ee.Geometry | ee.FeatureCollection): The region to visualize.
        layer_name (str, optional): The layer name to be used. Defaults to "Time series".
        labels (list, optional): The list of labels to be used for the time series. Defaults to None.
        time_interval (int, optional): Time interval in seconds. Defaults to 1.
        position (str, optional): Position to place the time slider, can be any of ['topleft', 'topright', 'bottomleft', 'bottomright']. Defaults to "bottomright".
        slider_length (str, optional): Length of the time slider. Defaults to "150px".
        date_format (str, optional): The date format to use. Defaults to 'YYYY-MM-dd'.
        opacity (float, optional): The opacity of layers. Defaults to 1.0.

    Raises:
        TypeError: If the ee_object is not ee.Image | ee.ImageCollection.
    """
    import threading

    if isinstance(ee_object, ee.Image):
        if region is not None:
            if isinstance(region, ee.Geometry):
                ee_object = ee_object.clip(region)
            elif isinstance(region, ee.FeatureCollection):
                ee_object = ee_object.clipToCollection(region)
        if layer_name not in self.ee_layers:
            self.addLayer(ee_object, {}, layer_name, False, opacity)
        band_names = ee_object.bandNames()
        ee_object = ee.ImageCollection(
            ee_object.bandNames().map(lambda b: ee_object.select([b]))
        )

        if labels is not None:
            if len(labels) != int(ee_object.size().getInfo()):
                raise ValueError(
                    "The length of labels must be equal to the number of bands in the image."
                )
        else:
            labels = band_names.getInfo()

    elif isinstance(ee_object, ee.ImageCollection):
        if region is not None:
            if isinstance(region, ee.Geometry):
                ee_object = ee_object.map(lambda img: img.clip(region))
            elif isinstance(region, ee.FeatureCollection):
                ee_object = ee_object.map(lambda img: img.clipToCollection(region))

        if labels is not None:
            if len(labels) != int(ee_object.size().getInfo()):
                raise ValueError(
                    "The length of labels must be equal to the number of images in the ImageCollection."
                )
        else:
            labels = (
                ee_object.aggregate_array("system:time_start")
                .map(lambda d: ee.Date(d).format(date_format))
                .getInfo()
            )
    else:
        raise TypeError("The ee_object must be an ee.Image or ee.ImageCollection")

    # if labels is not None:
    #     size = len(labels)
    # else:
    #     size = ee_object.size().getInfo()
    #     labels = [str(i) for i in range(1, size + 1)]

    first = ee.Image(ee_object.first())

    if layer_name not in self.ee_layers:
        self.addLayer(ee_object.toBands(), {}, layer_name, False, opacity)
    self.addLayer(first, vis_params, "Image X", True, opacity)

    slider = widgets.IntSlider(
        min=1,
        max=len(labels),
        readout=False,
        continuous_update=False,
        layout=widgets.Layout(width=slider_length),
    )
    label = widgets.Label(
        value=labels[0], layout=widgets.Layout(padding="0px 5px 0px 5px")
    )

    play_btn = widgets.Button(
        icon="play",
        tooltip="Play the time slider",
        button_style="primary",
        layout=widgets.Layout(width="32px"),
    )

    pause_btn = widgets.Button(
        icon="pause",
        tooltip="Pause the time slider",
        button_style="primary",
        layout=widgets.Layout(width="32px"),
    )

    close_btn = widgets.Button(
        icon="times",
        tooltip="Close the time slider",
        button_style="primary",
        layout=widgets.Layout(width="32px"),
    )

    play_chk = widgets.Checkbox(value=False)

    slider_widget = widgets.HBox([slider, label, play_btn, pause_btn, close_btn])

    def play_click(b):
        import time

        play_chk.value = True

        def work(slider):
            while play_chk.value:
                if slider.value < len(labels):
                    slider.value += 1
                else:
                    slider.value = 1
                time.sleep(time_interval)

        thread = threading.Thread(target=work, args=(slider,))
        thread.start()

    def pause_click(b):
        play_chk.value = False

    play_btn.on_click(play_click)
    pause_btn.on_click(pause_click)

    def slider_changed(change):
        self.default_style = {"cursor": "wait"}
        index = slider.value - 1
        label.value = labels[index]
        image = ee.Image(ee_object.toList(ee_object.size()).get(index))
        if layer_name not in self.ee_layers:
            self.addLayer(ee_object.toBands(), {}, layer_name, False, opacity)
        self.addLayer(image, vis_params, "Image X", True, opacity)
        self.default_style = {"cursor": "default"}

    slider.observe(slider_changed, "value")

    def close_click(b):
        play_chk.value = False
        self.toolbar_reset()
        self.remove_ee_layer("Image X")
        self.remove_ee_layer(layer_name)

        if self.slider_ctrl is not None and self.slider_ctrl in self.controls:
            self.remove_control(self.slider_ctrl)
        slider_widget.close()

    close_btn.on_click(close_click)

    slider_ctrl = ipyleaflet.WidgetControl(widget=slider_widget, position=position)
    self.add(slider_ctrl)
    self.slider_ctrl = slider_ctrl

add_toolbar(position='topright', **kwargs)

Add a toolbar to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the toolbar. Defaults to "topright".	'topright'
**kwargs	Any	Additional keyword arguments.	{}

Source code in geemap/geemap.py

def add_toolbar(self, position: str = "topright", **kwargs: Any) -> None:
    """Add a toolbar to the map.

    Args:
        position (str, optional): The position of the toolbar. Defaults to "topright".
        **kwargs: Additional keyword arguments.
    """
    self.add("toolbar", position, **kwargs)

add_vector(filename, layer_name='Untitled', to_ee=False, bbox=None, mask=None, rows=None, style={}, hover_style={}, style_callback=None, fill_colors=['black'], info_mode='on_hover', encoding='utf-8', **kwargs)

Adds any geopandas-supported vector dataset to the map.

Parameters:

Name	Type	Description	Default
filename	str	Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO).	required
layer_name	str	The layer name to use. Defaults to "Untitled".	'Untitled'
to_ee	bool	Whether to convert the GeoJSON to ee.FeatureCollection. Defaults to False.	False
bbox	tuple | GeoDataFrame or GeoSeries | shapely Geometry	Filter features by given bounding box, GeoSeries, GeoDataFrame or a shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with mask. Defaults to None.	None
mask	dict | GeoDataFrame or GeoSeries | shapely Geometry	Filter for features that intersect with the given dict-like geojson geometry, GeoSeries, GeoDataFrame or shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with bbox. Defaults to None.	None
rows	int or slice	Load in specific rows by passing an integer (first n rows) or a slice() object.. Defaults to None.	None
style	dict	A dictionary specifying the style to be used. Defaults to {}.	{}
hover_style	dict	Hover style dictionary. Defaults to {}.	{}
style_callback	function	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.	None
fill_colors	list	The random colors to use for filling polygons. Defaults to ["black"].	['black']
info_mode	str	Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".	'on_hover'
encoding	str	The encoding to use to read the file. Defaults to "utf-8".	'utf-8'

Source code in geemap/geemap.py

def add_vector(
    self,
    filename,
    layer_name="Untitled",
    to_ee=False,
    bbox=None,
    mask=None,
    rows=None,
    style={},
    hover_style={},
    style_callback=None,
    fill_colors=["black"],
    info_mode="on_hover",
    encoding="utf-8",
    **kwargs,
):
    """Adds any geopandas-supported vector dataset to the map.

    Args:
        filename (str): Either the absolute or relative path to the file or URL to be opened, or any object with a read() method (such as an open file or StringIO).
        layer_name (str, optional): The layer name to use. Defaults to "Untitled".
        to_ee (bool, optional): Whether to convert the GeoJSON to ee.FeatureCollection. Defaults to False.
        bbox (tuple | GeoDataFrame or GeoSeries | shapely Geometry, optional): Filter features by given bounding box, GeoSeries, GeoDataFrame or a shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with mask. Defaults to None.
        mask (dict | GeoDataFrame or GeoSeries | shapely Geometry, optional): Filter for features that intersect with the given dict-like geojson geometry, GeoSeries, GeoDataFrame or shapely geometry. CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame. Cannot be used with bbox. Defaults to None.
        rows (int or slice, optional): Load in specific rows by passing an integer (first n rows) or a slice() object.. Defaults to None.
        style (dict, optional): A dictionary specifying the style to be used. Defaults to {}.
        hover_style (dict, optional): Hover style dictionary. Defaults to {}.
        style_callback (function, optional): Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. Defaults to None.
        fill_colors (list, optional): The random colors to use for filling polygons. Defaults to ["black"].
        info_mode (str, optional): Displays the attributes by either on_hover or on_click. Any value other than "on_hover" or "on_click" will be treated as None. Defaults to "on_hover".
        encoding (str, optional): The encoding to use to read the file. Defaults to "utf-8".

    """
    if not filename.startswith("http"):
        filename = os.path.abspath(filename)
    else:
        filename = github_raw_url(filename)
    if to_ee:
        fc = vector_to_ee(
            filename,
            bbox=bbox,
            mask=mask,
            rows=rows,
            geodesic=True,
            **kwargs,
        )

        self.addLayer(fc, {}, layer_name)
    else:
        ext = os.path.splitext(filename)[1].lower()
        if ext == ".shp":
            self.add_shapefile(
                filename,
                layer_name,
                style,
                hover_style,
                style_callback,
                fill_colors,
                info_mode,
                encoding,
            )
        elif ext in [".json", ".geojson"]:
            self.add_geojson(
                filename,
                layer_name,
                style,
                hover_style,
                style_callback,
                fill_colors,
                info_mode,
                encoding,
            )
        else:
            geojson = vector_to_geojson(
                filename,
                bbox=bbox,
                mask=mask,
                rows=rows,
                epsg="4326",
                **kwargs,
            )

            self.add_geojson(
                geojson,
                layer_name,
                style,
                hover_style,
                style_callback,
                fill_colors,
                info_mode,
                encoding,
            )

add_velocity(data, zonal_speed, meridional_speed, latitude_dimension='lat', longitude_dimension='lon', level_dimension='lev', level_index=0, time_index=0, velocity_scale=0.01, max_velocity=20, display_options={}, name='Velocity')

Add a velocity layer to the map.

Parameters:

Name	Type	Description	Default
data	str | Dataset	The data to use for the velocity layer. It can be a file path to a NetCDF file or an xarray Dataset.	required
zonal_speed	str	Name of the zonal speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.	required
meridional_speed	str	Name of the meridional speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.	required
latitude_dimension	str	Name of the latitude dimension in the dataset. Defaults to 'lat'.	'lat'
longitude_dimension	str	Name of the longitude dimension in the dataset. Defaults to 'lon'.	'lon'
level_dimension	str	Name of the level dimension in the dataset. Defaults to 'lev'.	'lev'
level_index	int	The index of the level dimension to display. Defaults to 0.	0
time_index	int	The index of the time dimension to display. Defaults to 0.	0
velocity_scale	float	The scale of the velocity. Defaults to 0.01.	0.01
max_velocity	int	The maximum velocity to display. Defaults to 20.	20
display_options	dict	The display options for the velocity layer. Defaults to {}. See https://bit.ly/3uf8t6w.	{}
name	str	Layer name to use . Defaults to 'Velocity'.	'Velocity'

Raises:

Type	Description
ImportError	If the xarray package is not installed.
ValueError	If the data is not a NetCDF file or an xarray Dataset.

Source code in geemap/geemap.py

def add_velocity(
    self,
    data,
    zonal_speed,
    meridional_speed,
    latitude_dimension="lat",
    longitude_dimension="lon",
    level_dimension="lev",
    level_index=0,
    time_index=0,
    velocity_scale=0.01,
    max_velocity=20,
    display_options={},
    name="Velocity",
):
    """Add a velocity layer to the map.

    Args:
        data (str | xr.Dataset): The data to use for the velocity layer. It can be a file path to a NetCDF file or an xarray Dataset.
        zonal_speed (str): Name of the zonal speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.
        meridional_speed (str): Name of the meridional speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.
        latitude_dimension (str, optional): Name of the latitude dimension in the dataset. Defaults to 'lat'.
        longitude_dimension (str, optional): Name of the longitude dimension in the dataset. Defaults to 'lon'.
        level_dimension (str, optional): Name of the level dimension in the dataset. Defaults to 'lev'.
        level_index (int, optional): The index of the level dimension to display. Defaults to 0.
        time_index (int, optional): The index of the time dimension to display. Defaults to 0.
        velocity_scale (float, optional): The scale of the velocity. Defaults to 0.01.
        max_velocity (int, optional): The maximum velocity to display. Defaults to 20.
        display_options (dict, optional): The display options for the velocity layer. Defaults to {}. See https://bit.ly/3uf8t6w.
        name (str, optional): Layer name to use . Defaults to 'Velocity'.

    Raises:
        ImportError: If the xarray package is not installed.
        ValueError: If the data is not a NetCDF file or an xarray Dataset.
    """
    try:
        import xarray as xr
        from ipyleaflet.velocity import Velocity
    except ImportError:
        raise ImportError(
            "The xarray package is required to add a velocity layer. "
            "Please install it with `pip install xarray`."
        )

    if isinstance(data, str):
        if data.startswith("http"):
            data = download_file(data)
        ds = xr.open_dataset(data)

    elif isinstance(data, xr.Dataset):
        ds = data
    else:
        raise ValueError("The data must be a file path or xarray dataset.")

    coords = list(ds.coords.keys())

    # Rasterio does not handle time or levels. So we must drop them
    if "time" in coords:
        ds = ds.isel(time=time_index, drop=True)

    params = {level_dimension: level_index}
    if level_dimension in coords:
        ds = ds.isel(drop=True, **params)

    wind = Velocity(
        data=ds,
        zonal_speed=zonal_speed,
        meridional_speed=meridional_speed,
        latitude_dimension=latitude_dimension,
        longitude_dimension=longitude_dimension,
        velocity_scale=velocity_scale,
        max_velocity=max_velocity,
        display_options=display_options,
        name=name,
    )
    self.add(wind)

add_widget(content, position='bottomright', add_header=False, opened=True, show_close_button=True, widget_icon='gear', close_button_icon='times', widget_args={}, close_button_args={}, display_widget=None, **kwargs)

Add a widget (e.g., text, HTML, figure) to the map.

Parameters:

Name	Type	Description	Default
content	str | Widget | object	The widget to add.	required
position	str	The position of the widget. Defaults to "bottomright".	'bottomright'
add_header	bool	Whether to add a header with close buttons to the widget. Defaults to False.	False
opened	bool	Whether to open the toolbar. Defaults to True.	True
show_close_button	bool	Whether to show the close button. Defaults to True.	True
widget_icon	str	The icon name for the toolbar button. Defaults to 'gear'.	'gear'
close_button_icon	str	The icon name for the close button. Defaults to "times".	'times'
widget_args	dict	Additional arguments to pass to the toolbar button. Defaults to {}.	{}
close_button_args	dict	Additional arguments to pass to the close button. Defaults to {}.	{}
display_widget	Widget	The widget to be displayed when the toolbar is clicked.	None
**kwargs		Additional arguments to pass to the HTML or Output widgets	{}

Source code in geemap/geemap.py

def add_widget(
    self,
    content,
    position="bottomright",
    add_header=False,
    opened=True,
    show_close_button=True,
    widget_icon="gear",
    close_button_icon="times",
    widget_args={},
    close_button_args={},
    display_widget=None,
    **kwargs,
):
    """Add a widget (e.g., text, HTML, figure) to the map.

    Args:
        content (str | ipywidgets.Widget | object): The widget to add.
        position (str, optional): The position of the widget. Defaults to "bottomright".
        add_header (bool, optional): Whether to add a header with close buttons to the widget. Defaults to False.
        opened (bool, optional): Whether to open the toolbar. Defaults to True.
        show_close_button (bool, optional): Whether to show the close button. Defaults to True.
        widget_icon (str, optional): The icon name for the toolbar button. Defaults to 'gear'.
        close_button_icon (str, optional): The icon name for the close button. Defaults to "times".
        widget_args (dict, optional): Additional arguments to pass to the toolbar button. Defaults to {}.
        close_button_args (dict, optional): Additional arguments to pass to the close button. Defaults to {}.
        display_widget (ipywidgets.Widget, optional): The widget to be displayed when the toolbar is clicked.
        **kwargs: Additional arguments to pass to the HTML or Output widgets
    """

    allowed_positions = ["topleft", "topright", "bottomleft", "bottomright"]

    if position not in allowed_positions:
        raise Exception(f"position must be one of {allowed_positions}")

    if "layout" not in kwargs:
        kwargs["layout"] = widgets.Layout(padding="0px 4px 0px 4px")
    try:
        if add_header:
            if isinstance(content, str):
                widget = widgets.HTML(value=content, **kwargs)
            else:
                widget = content

            widget_template(
                widget,
                opened,
                show_close_button,
                widget_icon,
                close_button_icon,
                widget_args,
                close_button_args,
                display_widget,
                self,
                position,
            )
        else:
            if isinstance(content, str):
                widget = widgets.HTML(value=content, **kwargs)
            else:
                widget = widgets.Output(**kwargs)
                with widget:
                    display(content)
            control = ipyleaflet.WidgetControl(widget=widget, position=position)
            self.add(control)

    except Exception as e:
        raise Exception(f"Error adding widget: {e}")

add_wms_layer(url, layers, name=None, attribution='', format='image/png', transparent=True, opacity=1.0, shown=True, **kwargs)

Add a WMS layer to the map.

Parameters:

Name	Type	Description	Default
url	str	The URL of the WMS web service.	required
layers	str	Comma-separated list of WMS layers to show.	required
name	str	The layer name to use on the layer control. Defaults to None.	None
attribution	str	The attribution of the data layer. Defaults to ''.	''
format	str	WMS image format (use ‘image/png’ for layers with transparency). Defaults to 'image/png'.	'image/png'
transparent	bool	If True, the WMS service will return images with transparency. Defaults to True.	True
opacity	float	The opacity of the layer. Defaults to 1.0.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True

Source code in geemap/geemap.py

def add_wms_layer(
    self,
    url,
    layers,
    name=None,
    attribution="",
    format="image/png",
    transparent=True,
    opacity=1.0,
    shown=True,
    **kwargs,
):
    """Add a WMS layer to the map.

    Args:
        url (str): The URL of the WMS web service.
        layers (str): Comma-separated list of WMS layers to show.
        name (str, optional): The layer name to use on the layer control. Defaults to None.
        attribution (str, optional): The attribution of the data layer. Defaults to ''.
        format (str, optional): WMS image format (use ‘image/png’ for layers with transparency). Defaults to 'image/png'.
        transparent (bool, optional): If True, the WMS service will return images with transparency. Defaults to True.
        opacity (float, optional): The opacity of the layer. Defaults to 1.0.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
    """

    if name is None:
        name = str(layers)

    try:
        wms_layer = ipyleaflet.WMSLayer(
            url=url,
            layers=layers,
            name=name,
            attribution=attribution,
            format=format,
            transparent=transparent,
            opacity=opacity,
            visible=shown,
            **kwargs,
        )
        self.add(wms_layer)

    except Exception as e:
        print("Failed to add the specified WMS TileLayer.")
        raise Exception(e)

add_xy_data(in_csv, x='longitude', y='latitude', label=None, layer_name='Marker cluster', to_ee=False)

Adds points from a CSV file containing lat/lon information and display data on the map.

Parameters:

Name	Type	Description	Default
in_csv	str	The file path to the input CSV file.	required
x	str	The name of the column containing longitude coordinates. Defaults to "longitude".	'longitude'
y	str	The name of the column containing latitude coordinates. Defaults to "latitude".	'latitude'
label	str	The name of the column containing label information to used for marker popup. Defaults to None.	None
layer_name	str	The layer name to use. Defaults to "Marker cluster".	'Marker cluster'
to_ee	bool	Whether to convert the csv to an ee.FeatureCollection.	False

Raises:

Type	Description
FileNotFoundError	The specified input csv does not exist.
ValueError	The specified x column does not exist.
ValueError	The specified y column does not exist.
ValueError	The specified label column does not exist.

Source code in geemap/geemap.py

def add_xy_data(
    self,
    in_csv,
    x="longitude",
    y="latitude",
    label=None,
    layer_name="Marker cluster",
    to_ee=False,
):
    """Adds points from a CSV file containing lat/lon information and display data on the map.

    Args:
        in_csv (str): The file path to the input CSV file.
        x (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
        y (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
        label (str, optional): The name of the column containing label information to used for marker popup. Defaults to None.
        layer_name (str, optional): The layer name to use. Defaults to "Marker cluster".
        to_ee (bool, optional): Whether to convert the csv to an ee.FeatureCollection.

    Raises:
        FileNotFoundError: The specified input csv does not exist.
        ValueError: The specified x column does not exist.
        ValueError: The specified y column does not exist.
        ValueError: The specified label column does not exist.
    """
    import pandas as pd

    if not in_csv.startswith("http") and (not os.path.exists(in_csv)):
        raise FileNotFoundError("The specified input csv does not exist.")

    df = pd.read_csv(in_csv)
    col_names = df.columns.values.tolist()

    if x not in col_names:
        raise ValueError(f"x must be one of the following: {', '.join(col_names)}")

    if y not in col_names:
        raise ValueError(f"y must be one of the following: {', '.join(col_names)}")

    if label is not None and (label not in col_names):
        raise ValueError(
            f"label must be one of the following: {', '.join(col_names)}"
        )

    self.default_style = {"cursor": "wait"}

    if to_ee:
        fc = csv_to_ee(in_csv, latitude=y, longitude=x)
        self.addLayer(fc, {}, layer_name)

    else:
        points = list(zip(df[y], df[x]))

        if label is not None:
            labels = df[label]
            markers = [
                ipyleaflet.Marker(
                    location=point,
                    draggable=False,
                    popup=widgets.HTML(str(labels[index])),
                )
                for index, point in enumerate(points)
            ]
        else:
            markers = [
                ipyleaflet.Marker(location=point, draggable=False)
                for point in points
            ]

        marker_cluster = ipyleaflet.MarkerCluster(markers=markers, name=layer_name)
        self.add(marker_cluster)

    self.default_style = {"cursor": "default"}

add_xyz_service(provider, **kwargs)

Add a XYZ tile layer to the map.

Parameters:

Name	Type	Description	Default
provider	str	A tile layer name starts with xyz or qms. For example, xyz.OpenTopoMap,	required

Raises:

Type	Description
ValueError	The provider is not valid. It must start with xyz or qms.

Source code in geemap/geemap.py

def add_xyz_service(self, provider, **kwargs):
    """Add a XYZ tile layer to the map.

    Args:
        provider (str): A tile layer name starts with xyz or qms. For example, xyz.OpenTopoMap,

    Raises:
        ValueError: The provider is not valid. It must start with xyz or qms.
    """
    import xyzservices.providers as xyz
    from xyzservices import TileProvider

    if provider.startswith("xyz"):
        name = provider[4:]
        xyz_provider = xyz.flatten()[name]
        url = xyz_provider.build_url()
        attribution = xyz_provider.attribution
        if attribution.strip() == "":
            attribution = " "
        self.add_tile_layer(url, name, attribution)
    elif provider.startswith("qms"):
        name = provider[4:]
        qms_provider = TileProvider.from_qms(name)
        url = qms_provider.build_url()
        attribution = qms_provider.attribution
        if attribution.strip() == "":
            attribution = " "
        self.add_tile_layer(url, name, attribution)
    else:
        raise ValueError(
            f"The provider {provider} is not valid. It must start with xyz or qms."
        )

basemap_demo()

A demo for using geemap basemaps.

Source code in geemap/geemap.py

def basemap_demo(self):
    """A demo for using geemap basemaps."""
    self.add_basemap_widget()

center_object(ee_object, zoom=None, max_error=0.001)

Centers the map view on a given object.

Parameters:

Name	Type	Description	Default
ee_object	Union[Element, Geometry]	An Earth Engine object to center on a geometry, image or feature.	required
zoom	Optional[int]	The zoom level, from 1 to 24. Defaults to None.	None
max_error	float	The maximum error for the geometry. Defaults to 0.001.	0.001

Source code in geemap/geemap.py

def center_object(
    self,
    ee_object: Union[ee.Element, ee.Geometry],
    zoom: Optional[int] = None,
    max_error: float = 0.001,
) -> None:
    """Centers the map view on a given object.

    Args:
        ee_object (Union[ee.Element, ee.Geometry]): An Earth Engine object to
            center on a geometry, image or feature.
        zoom (Optional[int], optional): The zoom level, from 1 to 24. Defaults to None.
        max_error (float, optional): The maximum error for the geometry. Defaults to 0.001.
    """
    super().center_object(ee_object=ee_object, zoom=zoom, max_error=max_error)
    if is_arcpy():
        bds = self.bounds
        arc_zoom_to_extent(bds[0][1], bds[0][0], bds[1][1], bds[1][0])

create_vis_widget(layer_dict)

Creates a GUI for changing layer visualization parameters interactively.

Parameters:

Name	Type	Description	Default
layer_dict	Dict[str, Any]	A dictionary containing information about the layer. It is an element from Map.ee_layers.	required

Source code in geemap/geemap.py

def create_vis_widget(self, layer_dict: Dict[str, Any]) -> None:
    """Creates a GUI for changing layer visualization parameters interactively.

    Args:
        layer_dict (Dict[str, Any]): A dictionary containing information about
            the layer. It is an element from Map.ee_layers.
    """
    self._add_layer_editor(position="topright", layer_dict=layer_dict)

draw_layer_on_top()

Move user-drawn feature layer to the top of all layers.

Source code in geemap/geemap.py

def draw_layer_on_top(self):
    """Move user-drawn feature layer to the top of all layers."""
    draw_layer_index = self.find_layer_index(name="Drawn Features")
    if draw_layer_index > -1 and draw_layer_index < (len(self.layers) - 1):
        layers = list(self.layers)
        layers = (
            layers[0:draw_layer_index]
            + layers[(draw_layer_index + 1) :]
            + [layers[draw_layer_index]]
        )
        self.layers = layers

extract_values_to_points(filename)

Exports pixel values to a csv file based on user-drawn geometries.

Parameters:

Name	Type	Description	Default
filename	str	The output file path to the csv file or shapefile.	required

Source code in geemap/geemap.py

def extract_values_to_points(self, filename):
    """Exports pixel values to a csv file based on user-drawn geometries.

    Args:
        filename (str): The output file path to the csv file or shapefile.
    """
    import csv

    filename = os.path.abspath(filename)
    allowed_formats = ["csv", "shp"]
    ext = filename[-3:]

    if ext not in allowed_formats:
        print(
            "The output file must be one of the following: {}".format(
                ", ".join(allowed_formats)
            )
        )
        return

    out_dir = os.path.dirname(filename)
    out_csv = filename[:-3] + "csv"
    out_shp = filename[:-3] + "shp"
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    count = len(self._chart_points)
    out_list = []
    if count > 0:
        header = ["id", "latitude", "longitude"] + self._chart_labels
        out_list.append(header)

        for i in range(0, count):
            id = i + 1
            line = [id] + self._chart_points[i] + self._chart_values[i]
            out_list.append(line)

        with open(out_csv, "w", newline="") as f:
            writer = csv.writer(f)
            writer.writerows(out_list)

        if ext == "csv":
            print(f"The csv file has been saved to: {out_csv}")
        else:
            csv_to_shp(out_csv, out_shp)
            print(f"The shapefile has been saved to: {out_shp}")

find_layer(name)

Finds a layer by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the layer to find.	required

Returns:

Type	Description
Optional[Layer]	Optional[ipyleaflet.Layer]: The ipyleaflet layer object if found, else None.

Source code in geemap/geemap.py

def find_layer(self, name: str) -> Optional[ipyleaflet.Layer]:
    """Finds a layer by name.

    Args:
        name (str): Name of the layer to find.

    Returns:
        Optional[ipyleaflet.Layer]: The ipyleaflet layer object if found, else None.
    """
    layers = self.layers

    for layer in layers:
        if layer.name == name:
            return layer

    return None

find_layer_index(name)

Finds the index of a layer by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the layer to find.	required

Returns:

Name	Type	Description
int	int	Index of the layer with the specified name, or -1 if not found.

Source code in geemap/geemap.py

def find_layer_index(self, name: str) -> int:
    """Finds the index of a layer by name.

    Args:
        name (str): Name of the layer to find.

    Returns:
        int: Index of the layer with the specified name, or -1 if not found.
    """
    layers = self.layers

    for index, layer in enumerate(layers):
        if layer.name == name:
            return index

    return -1

get_bounds(asGeoJSON=False)

Returns the bounds of the current map view, as a list in the format [west, south, east, north] in degrees.

Parameters:

Name	Type	Description	Default
asGeoJSON	bool	If true, returns map bounds as GeoJSON. Defaults to False.	False

Returns:

Type	Description
	list | dict: A list in the format [west, south, east, north] in degrees.

Source code in geemap/geemap.py

def get_bounds(self, asGeoJSON=False):
    """Returns the bounds of the current map view, as a list in the format [west, south, east, north] in degrees.

    Args:
        asGeoJSON (bool, optional): If true, returns map bounds as GeoJSON. Defaults to False.

    Returns:
        list | dict: A list in the format [west, south, east, north] in degrees.
    """
    return super().get_bounds(as_geojson=asGeoJSON)

get_layer_names()

Gets layer names as a list.

Returns:

Type	Description
List[str]	List[str]: A list of layer names.

Source code in geemap/geemap.py

def get_layer_names(self) -> List[str]:
    """Gets layer names as a list.

    Returns:
        List[str]: A list of layer names.
    """
    layer_names = []

    for layer in list(self.layers):
        if len(layer.name) > 0:
            layer_names.append(layer.name)

    return layer_names

get_scale()

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

Returns:

Name	Type	Description
float	float	Map resolution in meters.

Source code in geemap/geemap.py

def get_scale(self) -> float:
    """Returns the approximate pixel scale of the current map view, in meters.

    Returns:
        float: Map resolution in meters.
    """
    return super().get_scale()

image_overlay(url, bounds, name)

Overlays an image from the Internet or locally on the map.

Parameters:

Name	Type	Description	Default
url	str	http URL or local file path to the image.	required
bounds	tuple	bounding box of the image in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).	required
name	str	name of the layer to show on the layer control.	required

Source code in geemap/geemap.py

def image_overlay(self, url, bounds, name):
    """Overlays an image from the Internet or locally on the map.

    Args:
        url (str): http URL or local file path to the image.
        bounds (tuple): bounding box of the image in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).
        name (str): name of the layer to show on the layer control.
    """
    from base64 import b64encode
    from io import BytesIO

    from PIL import Image, ImageSequence

    try:
        if not url.startswith("http"):
            if not os.path.exists(url):
                print("The provided file does not exist.")
                return

            ext = os.path.splitext(url)[1][1:]  # file extension
            image = Image.open(url)

            f = BytesIO()
            if ext.lower() == "gif":
                frames = []
                # Loop over each frame in the animated image
                for frame in ImageSequence.Iterator(image):
                    frame = frame.convert("RGBA")
                    b = BytesIO()
                    frame.save(b, format="gif")
                    frame = Image.open(b)
                    frames.append(frame)
                frames[0].save(
                    f,
                    format="GIF",
                    save_all=True,
                    append_images=frames[1:],
                    loop=0,
                )
            else:
                image.save(f, ext)

            data = b64encode(f.getvalue())
            data = data.decode("ascii")
            url = "data:image/{};base64,".format(ext) + data
        img = ipyleaflet.ImageOverlay(url=url, bounds=bounds, name=name)
        self.add(img)
    except Exception as e:
        print(e)

layer_opacity(name, opacity=1.0)

Changes the opacity of a layer.

Parameters:

Name	Type	Description	Default
name	str	The name of the layer to change opacity.	required
opacity	float	The opacity value to set. Defaults to 1.0.	1.0

Source code in geemap/geemap.py

def layer_opacity(self, name: str, opacity: float = 1.0) -> None:
    """Changes the opacity of a layer.

    Args:
        name (str): The name of the layer to change opacity.
        opacity (float, optional): The opacity value to set. Defaults to 1.0.
    """
    layer = self.find_layer(name)
    try:
        layer.opacity = opacity
    except Exception as e:
        raise Exception(e)

layer_to_image(layer_name, output=None, crs='EPSG:3857', scale=None, region=None, vis_params=None, **kwargs)

Converts a specific layer from Earth Engine to an image file.

Parameters:

Name	Type	Description	Default
layer_name	str	The name of the layer to convert.	required
output	str	The output file path for the image. Defaults to None.	None
crs	str	The coordinate reference system (CRS) of the output image. Defaults to "EPSG:3857".	'EPSG:3857'
scale	int	The scale of the output image. Defaults to None.	None
region	Geometry	The region of interest for the conversion. Defaults to None.	None
vis_params	dict	The visualization parameters. Defaults to None.	None
**kwargs	Any	Additional keyword arguments to pass to the download_ee_image function.	{}

Returns:

Type	Description
None	None

Source code in geemap/geemap.py

def layer_to_image(
    self,
    layer_name: str,
    output: Optional[str] = None,
    crs: str = "EPSG:3857",
    scale: Optional[int] = None,
    region: Optional[ee.Geometry] = None,
    vis_params: Optional[Dict] = None,
    **kwargs: Any,
) -> None:
    """
    Converts a specific layer from Earth Engine to an image file.

    Args:
        layer_name (str): The name of the layer to convert.
        output (str): The output file path for the image. Defaults to None.
        crs (str, optional): The coordinate reference system (CRS) of the output image. Defaults to "EPSG:3857".
        scale (int, optional): The scale of the output image. Defaults to None.
        region (ee.Geometry, optional): The region of interest for the conversion. Defaults to None.
        vis_params (dict, optional): The visualization parameters. Defaults to None.
        **kwargs: Additional keyword arguments to pass to the `download_ee_image` function.

    Returns:
        None
    """

    if region is None:
        b = self.bounds
        west, south, east, north = b[0][1], b[0][0], b[1][1], b[1][0]
        region = ee.Geometry.BBox(west, south, east, north)

    if scale is None:
        scale = int(self.get_scale())

    if layer_name not in self.ee_layers.keys():
        raise ValueError(f"Layer {layer_name} does not exist.")

    if output is None:
        output = layer_name + ".tif"

    layer = self.ee_layers[layer_name]
    ee_object = layer["ee_object"]

    if vis_params is None:
        vis_params = layer["vis_params"]

    image = ee_object.visualize(**vis_params)
    if not output.endswith(".tif"):
        geotiff = output + ".tif"
    else:
        geotiff = output
    download_ee_image(image, geotiff, region, crs=crs, scale=scale, **kwargs)

    if not output.endswith(".tif"):
        geotiff_to_image(geotiff, output)
        os.remove(geotiff)

marker_cluster()

Adds a marker cluster to the map and returns a list of ee.Feature, which can be accessed using Map.ee_marker_cluster.

Returns:

Name	Type	Description
object		a list of ee.Feature

Source code in geemap/geemap.py

def marker_cluster(self):
    """Adds a marker cluster to the map and returns a list of ee.Feature, which can be accessed using Map.ee_marker_cluster.

    Returns:
        object: a list of ee.Feature
    """
    coordinates = []
    markers = []
    marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")
    self.last_click = []
    self.all_clicks = []
    self.ee_markers = []
    self.add(marker_cluster)

    def handle_interaction(**kwargs):
        latlon = kwargs.get("coordinates")
        if kwargs.get("type") == "click":
            coordinates.append(latlon)
            geom = ee.Geometry.Point(latlon[1], latlon[0])
            feature = ee.Feature(geom)
            self.ee_markers.append(feature)
            self.last_click = latlon
            self.all_clicks = coordinates
            markers.append(ipyleaflet.Marker(location=latlon))
            marker_cluster.markers = markers
        elif kwargs.get("type") == "mousemove":
            pass

    # cursor style: https://www.w3schools.com/cssref/pr_class_cursor.asp
    self.default_style = {"cursor": "crosshair"}
    self.on_interaction(handle_interaction)

plot(x, y, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)

Creates a plot based on x-array and y-array data.

Parameters:

Name	Type	Description	Default
x	ndarray or list	The x-coordinates of the plotted line.	required
y	ndarray or list	The y-coordinates of the plotted line.	required
plot_type	str	The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.	None
overlay	bool	Whether to overlay plotted lines on the figure. Defaults to False.	False
position	str	Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.	'bottomright'
min_width	int	Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_width	int	Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
min_height	int	Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_height	int	Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None

Source code in geemap/geemap.py

def plot(
    self,
    x: Union[List[float], Any],
    y: Union[List[float], Any],
    plot_type: Optional[str] = None,
    overlay: bool = False,
    position: str = "bottomright",
    min_width: Optional[int] = None,
    max_width: Optional[int] = None,
    min_height: Optional[int] = None,
    max_height: Optional[int] = None,
    **kwargs: Any,
) -> None:
    """Creates a plot based on x-array and y-array data.

    Args:
        x (numpy.ndarray or list): The x-coordinates of the plotted line.
        y (numpy.ndarray or list): The y-coordinates of the plotted line.
        plot_type (str, optional): The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.
        overlay (bool, optional): Whether to overlay plotted lines on the figure. Defaults to False.
        position (str, optional): Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
        min_width (int, optional): Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
        max_width (int, optional): Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
        min_height (int, optional): Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
        max_height (int, optional): Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

    """
    if hasattr(self, "_plot_widget") and self._plot_widget is not None:
        plot_widget = self._plot_widget
    else:
        plot_widget = widgets.Output(
            layout={"border": "1px solid black", "max_width": "500px"}
        )
        plot_control = ipyleaflet.WidgetControl(
            widget=plot_widget,
            position=position,
            min_width=min_width,
            max_width=max_width,
            min_height=min_height,
            max_height=max_height,
        )
        self._plot_widget = plot_widget
        self._plot_control = plot_control
        self.add(plot_control)

    if max_width is None:
        max_width = 500
    if max_height is None:
        max_height = 300

    if (plot_type is None) and ("markers" not in kwargs):
        kwargs["markers"] = "circle"

    with plot_widget:
        try:
            fig = plt.figure(1, **kwargs)
            if max_width is not None:
                fig.layout.width = str(max_width) + "px"
            if max_height is not None:
                fig.layout.height = str(max_height) + "px"

            plot_widget.outputs = ()
            if not overlay:
                plt.clear()

            if plot_type is None:
                if "marker" not in kwargs:
                    kwargs["marker"] = "circle"
                plt.plot(x, y, **kwargs)
            elif plot_type == "bar":
                plt.bar(x, y, **kwargs)
            elif plot_type == "scatter":
                plt.scatter(x, y, **kwargs)
            elif plot_type == "hist":
                plt.hist(y, **kwargs)
            plt.show()

        except Exception as e:
            print("Failed to create plot.")
            raise Exception(e)

plot_demo(iterations=20, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)

A demo of interactive plotting using random pixel coordinates.

Parameters:

Name	Type	Description	Default
iterations	int	How many iterations to run for the demo. Defaults to 20.	20
plot_type	str	The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.	None
overlay	bool	Whether to overlay plotted lines on the figure. Defaults to False.	False
position	str	Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.	'bottomright'
min_width	int	Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_width	int	Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
min_height	int	Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_height	int	Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None

Source code in geemap/geemap.py

def plot_demo(
    self,
    iterations=20,
    plot_type=None,
    overlay=False,
    position="bottomright",
    min_width=None,
    max_width=None,
    min_height=None,
    max_height=None,
    **kwargs,
):
    """A demo of interactive plotting using random pixel coordinates.

    Args:
        iterations (int, optional): How many iterations to run for the demo. Defaults to 20.
        plot_type (str, optional): The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.
        overlay (bool, optional): Whether to overlay plotted lines on the figure. Defaults to False.
        position (str, optional): Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
        min_width (int, optional): Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
        max_width (int, optional): Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
        min_height (int, optional): Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
        max_height (int, optional): Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.
    """

    import numpy as np
    import time

    if hasattr(self, "random_marker") and self.random_marker is not None:
        self.remove_layer(self.random_marker)

    image = ee.Image("LANDSAT/LE7_TOA_5YEAR/1999_2003").select([0, 1, 2, 3, 4, 6])
    self.addLayer(
        image,
        {"bands": ["B4", "B3", "B2"], "gamma": 1.4},
        "LANDSAT/LE7_TOA_5YEAR/1999_2003",
    )
    self.setCenter(-50.078877, 25.190030, 3)
    band_names = image.bandNames().getInfo()
    # band_count = len(band_names)

    latitudes = np.random.uniform(30, 48, size=iterations)
    longitudes = np.random.uniform(-121, -76, size=iterations)

    marker = ipyleaflet.Marker(location=(0, 0))
    self.random_marker = marker
    self.add(marker)

    for i in range(iterations):
        try:
            coordinate = ee.Geometry.Point([longitudes[i], latitudes[i]])
            dict_values = image.sample(coordinate).first().toDictionary().getInfo()
            band_values = list(dict_values.values())
            title = "{}/{}: Spectral signature at ({}, {})".format(
                i + 1,
                iterations,
                round(latitudes[i], 2),
                round(longitudes[i], 2),
            )
            marker.location = (latitudes[i], longitudes[i])
            self.plot(
                band_names,
                band_values,
                plot_type=plot_type,
                overlay=overlay,
                min_width=min_width,
                max_width=max_width,
                min_height=min_height,
                max_height=max_height,
                title=title,
                **kwargs,
            )
            time.sleep(0.3)
        except Exception as e:
            raise Exception(e)

plot_raster(ee_object=None, sample_scale=None, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)

Interactive plotting of Earth Engine data by clicking on the map.

Parameters:

Name	Type	Description	Default
ee_object	object	The ee.Image or ee.ImageCollection to sample. Defaults to None.	None
sample_scale	float	A nominal scale in meters of the projection to sample in. Defaults to None.	None
plot_type	str	The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.	None
overlay	bool	Whether to overlay plotted lines on the figure. Defaults to False.	False
position	str	Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.	'bottomright'
min_width	int	Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_width	int	Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
min_height	int	Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_height	int	Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None

Source code in geemap/geemap.py

def plot_raster(
    self,
    ee_object=None,
    sample_scale=None,
    plot_type=None,
    overlay=False,
    position="bottomright",
    min_width=None,
    max_width=None,
    min_height=None,
    max_height=None,
    **kwargs,
):
    """Interactive plotting of Earth Engine data by clicking on the map.

    Args:
        ee_object (object, optional): The ee.Image or ee.ImageCollection to sample. Defaults to None.
        sample_scale (float, optional): A nominal scale in meters of the projection to sample in. Defaults to None.
        plot_type (str, optional): The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.
        overlay (bool, optional): Whether to overlay plotted lines on the figure. Defaults to False.
        position (str, optional): Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
        min_width (int, optional): Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.
        max_width (int, optional): Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.
        min_height (int, optional): Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.
        max_height (int, optional): Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.

    """
    if hasattr(self, "_plot_control") and self._plot_control is not None:
        del self._plot_widget
        if self._plot_control in self.controls:
            self.remove_control(self._plot_control)

    if hasattr(self, "random_marker") and self.random_marker is not None:
        self.remove_layer(self.random_marker)

    plot_widget = widgets.Output(layout={"border": "1px solid black"})
    plot_control = ipyleaflet.WidgetControl(
        widget=plot_widget,
        position=position,
        min_width=min_width,
        max_width=max_width,
        min_height=min_height,
        max_height=max_height,
    )
    self._plot_widget = plot_widget
    self._plot_control = plot_control
    self.add(plot_control)

    self.default_style = {"cursor": "crosshair"}
    msg = "The plot function can only be used on ee.Image or ee.ImageCollection with more than one band."
    if (ee_object is None) and len(self.ee_raster_layers) > 0:
        ee_object = self.ee_raster_layers.values()[-1]["ee_object"]
        if isinstance(ee_object, ee.ImageCollection):
            ee_object = ee_object.mosaic()
    elif isinstance(ee_object, ee.ImageCollection):
        ee_object = ee_object.mosaic()
    elif not isinstance(ee_object, ee.Image):
        print(msg)
        return

    if sample_scale is None:
        sample_scale = self.getScale()

    if max_width is None:
        max_width = 500

    band_names = ee_object.bandNames().getInfo()

    coordinates = []
    markers = []
    marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")
    self.last_click = []
    self.all_clicks = []
    self.add(marker_cluster)

    def handle_interaction(**kwargs2):
        latlon = kwargs2.get("coordinates")

        if kwargs2.get("type") == "click":
            try:
                coordinates.append(latlon)
                self.last_click = latlon
                self.all_clicks = coordinates
                markers.append(ipyleaflet.Marker(location=latlon))
                marker_cluster.markers = markers
                self.default_style = {"cursor": "wait"}
                xy = ee.Geometry.Point(latlon[::-1])
                dict_values = (
                    ee_object.sample(xy, scale=sample_scale)
                    .first()
                    .toDictionary()
                    .getInfo()
                )
                band_values = list(dict_values.values())
                self.plot(
                    band_names,
                    band_values,
                    plot_type=plot_type,
                    overlay=overlay,
                    min_width=min_width,
                    max_width=max_width,
                    min_height=min_height,
                    max_height=max_height,
                    **kwargs,
                )
                self.default_style = {"cursor": "crosshair"}
            except Exception as e:
                if self._plot_widget is not None:
                    with self._plot_widget:
                        self._plot_widget.outputs = ()
                        print("No data for the clicked location.")
                else:
                    print(e)
                self.default_style = {"cursor": "crosshair"}

    self.on_interaction(handle_interaction)

remove_colorbar()

Removes the colorbar from the map.

Source code in geemap/geemap.py

def remove_colorbar(self) -> None:
    """Removes the colorbar from the map."""
    if hasattr(self, "_colorbar") and self._colorbar is not None:
        self.remove_control(self._colorbar)

remove_colorbars()

Removes all colorbars from the map.

Source code in geemap/geemap.py

def remove_colorbars(self) -> None:
    """Removes all colorbars from the map."""
    for layer in self.ee_layers.values():
        if widget := layer.pop("colorbar", None):
            self.remove(widget)
    if hasattr(self, "colorbars"):
        for colorbar in self.colorbars:
            if colorbar in self.controls:
                self.remove_control(colorbar)

remove_draw_control()

Removes the draw control from the map

Source code in geemap/geemap.py

def remove_draw_control(self):
    """Removes the draw control from the map"""
    self.remove("draw_control")

remove_drawn_features()

Removes user-drawn geometries from the map

Source code in geemap/geemap.py

def remove_drawn_features(self):
    """Removes user-drawn geometries from the map"""
    if self._draw_control is not None:
        self._draw_control.reset()
    if "Drawn Features" in self.ee_layers:
        self.ee_layers.pop("Drawn Features")

remove_ee_layer(name)

Removes an Earth Engine layer.

Parameters:

Name	Type	Description	Default
name	str	The name of the Earth Engine layer to remove.	required

Source code in geemap/geemap.py

def remove_ee_layer(self, name: str) -> None:
    """Removes an Earth Engine layer.

    Args:
        name (str): The name of the Earth Engine layer to remove.
    """
    if name in self.ee_layers:
        ee_layer = self.ee_layers[name]["ee_layer"]
        self.ee_layers.pop(name, None)
        if ee_layer in self.layers:
            self.remove_layer(ee_layer)

remove_labels()

Removes all labels from the map.

Source code in geemap/geemap.py

def remove_labels(self):
    """Removes all labels from the map."""
    if hasattr(self, "labels"):
        self.remove_layer(self.labels)
        delattr(self, "labels")

remove_last_drawn()

Removes last user-drawn geometry from the map

Source code in geemap/geemap.py

def remove_last_drawn(self):
    """Removes last user-drawn geometry from the map"""
    if self._draw_control is not None:
        if self._draw_control.count == 1:
            self.remove_drawn_features()
        elif self._draw_control.count:
            self._draw_control.remove_geometry(self._draw_control.geometries[-1])
            if hasattr(self, "_chart_values"):
                self._chart_values = self._chart_values[:-1]
            if hasattr(self, "_chart_points"):
                self._chart_points = self._chart_points[:-1]

remove_legend()

Removes the legend from the map.

Source code in geemap/geemap.py

def remove_legend(self) -> None:
    """Removes the legend from the map."""
    if hasattr(self, "_legend") and self._legend is not None:
        if self._legend in self.controls:
            self.remove_control(self._legend)

remove_legends()

Removes all legends from the map.

Source code in geemap/geemap.py

def remove_legends(self) -> None:
    """Removes all legends from the map."""
    for layer in self.ee_layers.values():
        if widget := layer.pop("legend", None):
            self.remove(widget)
    if hasattr(self, "legends"):
        for legend in self.legends:
            if legend in self.controls:
                self.remove_control(legend)

set_center(lon, lat, zoom=None)

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

Parameters:

Name	Type	Description	Default
lon	float	The longitude of the center, in degrees.	required
lat	float	The latitude of the center, in degrees.	required
zoom	Optional[int]	The zoom level, from 1 to 24. Defaults to None.	None

Source code in geemap/geemap.py

def set_center(self, lon: float, lat: float, zoom: Optional[int] = None) -> None:
    """Centers the map view at a given coordinates with the given zoom level.

    Args:
        lon (float): The longitude of the center, in degrees.
        lat (float): The latitude of the center, in degrees.
        zoom (Optional[int], optional): The zoom level, from 1 to 24. Defaults to None.
    """
    super().set_center(lon, lat, zoom)
    if is_arcpy():
        arc_zoom_to_extent(lon, lat, lon, lat)

set_control_visibility(layerControl=True, fullscreenControl=True, latLngPopup=True)

Sets the visibility of the controls on the map.

Parameters:

Name	Type	Description	Default
layerControl	bool	Whether to show the control that allows the user to toggle layers on/off. Defaults to True.	True
fullscreenControl	bool	Whether to show the control that allows the user to make the map full-screen. Defaults to True.	True
latLngPopup	bool	Whether to show the control that pops up the Lat/lon when the user clicks on the map. Defaults to True.	True

Source code in geemap/geemap.py

def set_control_visibility(
    self, layerControl=True, fullscreenControl=True, latLngPopup=True
):
    """Sets the visibility of the controls on the map.

    Args:
        layerControl (bool, optional): Whether to show the control that allows the user to toggle layers on/off. Defaults to True.
        fullscreenControl (bool, optional): Whether to show the control that allows the user to make the map full-screen. Defaults to True.
        latLngPopup (bool, optional): Whether to show the control that pops up the Lat/lon when the user clicks on the map. Defaults to True.
    """
    pass

set_options(mapTypeId='HYBRID', **kwargs)

Adds Google basemap and controls to the ipyleaflet map.

Parameters:

Name	Type	Description	Default
mapTypeId	str	A mapTypeId to set the basemap to. Can be one of "ROADMAP", "SATELLITE", "HYBRID" or "TERRAIN" to select one of the standard Google Maps API map types. Defaults to 'HYBRID'.	'HYBRID'
**kwargs	Any	Additional keyword arguments.	{}

Source code in geemap/geemap.py

def set_options(self, mapTypeId: str = "HYBRID", **kwargs: Any) -> None:
    """Adds Google basemap and controls to the ipyleaflet map.

    Args:
        mapTypeId (str, optional): A mapTypeId to set the basemap to. Can be
            one of "ROADMAP", "SATELLITE", "HYBRID" or "TERRAIN" to select
            one of the standard Google Maps API map types. Defaults to 'HYBRID'.
        **kwargs: Additional keyword arguments.
    """

    try:
        self.add(mapTypeId)
    except Exception:
        raise ValueError(
            'Google basemaps can only be one of "ROADMAP", "SATELLITE", "HYBRID" or "TERRAIN".'
        )

set_plot_options(add_marker_cluster=False, sample_scale=None, plot_type=None, overlay=False, position='bottomright', min_width=None, max_width=None, min_height=None, max_height=None, **kwargs)

Sets plotting options.

Parameters:

Name	Type	Description	Default
add_marker_cluster	bool	Whether to add a marker cluster. Defaults to False.	False
sample_scale	float	A nominal scale in meters of the projection to sample in . Defaults to None.	None
plot_type	str	The plot type can be one of "None", "bar", "scatter" or "hist". Defaults to None.	None
overlay	bool	Whether to overlay plotted lines on the figure. Defaults to False.	False
position	str	Position of the control, can be ‘bottomleft’, ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.	'bottomright'
min_width	int	Min width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_width	int	Max width of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
min_height	int	Min height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None
max_height	int	Max height of the widget (in pixels), if None it will respect the content size. Defaults to None.	None

Source code in geemap/geemap.py

def set_plot_options(
    self,
    add_marker_cluster: bool = False,
    sample_scale: Optional[float] = None,
    plot_type: Optional[str] = None,
    overlay: bool = False,
    position: str = "bottomright",
    min_width: Optional[int] = None,
    max_width: Optional[int] = None,
    min_height: Optional[int] = None,
    max_height: Optional[int] = None,
    **kwargs: Any,
) -> None:
    """Sets plotting options.

    Args:
        add_marker_cluster (bool, optional): Whether to add a marker cluster.
            Defaults to False.
        sample_scale (float, optional):  A nominal scale in meters of the
            projection to sample in . Defaults to None.
        plot_type (str, optional): The plot type can be one of "None", "bar",
            "scatter" or "hist". Defaults to None.
        overlay (bool, optional): Whether to overlay plotted lines on the figure.
            Defaults to False.
        position (str, optional): Position of the control, can be ‘bottomleft’,
            ‘bottomright’, ‘topleft’, or ‘topright’. Defaults to 'bottomright'.
        min_width (int, optional): Min width of the widget (in pixels),
            if None it will respect the content size. Defaults to None.
        max_width (int, optional): Max width of the widget (in pixels),
            if None it will respect the content size. Defaults to None.
        min_height (int, optional): Min height of the widget (in pixels),
            if None it will respect the content size. Defaults to None.
        max_height (int, optional): Max height of the widget (in pixels),
            if None it will respect the content size. Defaults to None.

    """
    plot_options_dict = {}
    plot_options_dict["add_marker_cluster"] = add_marker_cluster
    plot_options_dict["sample_scale"] = sample_scale
    plot_options_dict["plot_type"] = plot_type
    plot_options_dict["overlay"] = overlay
    plot_options_dict["position"] = position
    plot_options_dict["min_width"] = min_width
    plot_options_dict["max_width"] = max_width
    plot_options_dict["min_height"] = min_height
    plot_options_dict["max_height"] = max_height

    for key in kwargs:
        plot_options_dict[key] = kwargs[key]

    self._plot_options = plot_options_dict

    if not hasattr(self, "_plot_marker_cluster"):
        self._plot_marker_cluster = ipyleaflet.MarkerCluster(name="Marker Cluster")

    if add_marker_cluster and (self._plot_marker_cluster not in self.layers):
        self.add(self._plot_marker_cluster)

show_layer(name, show=True)

Shows or hides a layer on the map.

Parameters:

Name	Type	Description	Default
name	str	Name of the layer to show/hide.	required
show	bool	Whether to show or hide the layer. Defaults to True.	True

Source code in geemap/geemap.py

def show_layer(self, name: str, show: bool = True) -> None:
    """Shows or hides a layer on the map.

    Args:
        name (str): Name of the layer to show/hide.
        show (bool, optional): Whether to show or hide the layer. Defaults to True.
    """
    layer = self.find_layer(name)

    if layer is not None:
        layer.visible = show

split_map(left_layer='OpenTopoMap', right_layer='Esri.WorldTopoMap', zoom_control=True, fullscreen_control=True, layer_control=True, add_close_button=False, close_button_position='topright', left_label=None, right_label=None, left_position='bottomleft', right_position='bottomright', widget_layout=None, **kwargs)

Adds split map.

Parameters:

Name	Type	Description	Default
left_layer	str	The layer tile layer. Defaults to 'OpenTopoMap'.	'OpenTopoMap'
right_layer	str	The right tile layer. Defaults to 'Esri.WorldTopoMap'.	'Esri.WorldTopoMap'
zoom_control	bool	Whether to show the zoom control. Defaults to True.	True
fullscreen_control	bool	Whether to show the full screen control. Defaults to True.	True
layer_control	bool	Whether to show the layer control. Defaults to True.	True
add_close_button	bool	Whether to add a close button. Defaults to False.	False
close_button_position	str	The position of the close button. Defaults to 'topright'.	'topright'
left_label	str	The label for the left map. Defaults to None.	None
right_label	str	The label for the right map. Defaults to None.	None
left_position	str	The position of the left label. Defaults to 'bottomleft'.	'bottomleft'
right_position	str	The position of the right label. Defaults to 'bottomright'.	'bottomright'
widget_layout	str	The layout of the label widget, such as ipywidgets.Layout(padding="0px 4px 0px 4px"). Defaults to None.	None
kwargs		Other arguments for ipyleaflet.TileLayer.	{}

Source code in geemap/geemap.py

def split_map(
    self,
    left_layer="OpenTopoMap",
    right_layer="Esri.WorldTopoMap",
    zoom_control=True,
    fullscreen_control=True,
    layer_control=True,
    add_close_button=False,
    close_button_position="topright",
    left_label=None,
    right_label=None,
    left_position="bottomleft",
    right_position="bottomright",
    widget_layout=None,
    **kwargs,
):
    """Adds split map.

    Args:
        left_layer (str, optional): The layer tile layer. Defaults to 'OpenTopoMap'.
        right_layer (str, optional): The right tile layer. Defaults to 'Esri.WorldTopoMap'.
        zoom_control (bool, optional): Whether to show the zoom control. Defaults to True.
        fullscreen_control (bool, optional): Whether to show the full screen control. Defaults to True.
        layer_control (bool, optional): Whether to show the layer control. Defaults to True.
        add_close_button (bool, optional): Whether to add a close button. Defaults to False.
        close_button_position (str, optional): The position of the close button. Defaults to 'topright'.
        left_label (str, optional): The label for the left map. Defaults to None.
        right_label (str, optional): The label for the right map. Defaults to None.
        left_position (str, optional): The position of the left label. Defaults to 'bottomleft'.
        right_position (str, optional): The position of the right label. Defaults to 'bottomright'.
        widget_layout (str, optional): The layout of the label widget, such as ipywidgets.Layout(padding="0px 4px 0px 4px"). Defaults to None.
        kwargs: Other arguments for ipyleaflet.TileLayer.
    """
    if "max_zoom" not in kwargs:
        kwargs["max_zoom"] = 100
    if "max_native_zoom" not in kwargs:
        kwargs["max_native_zoom"] = 100
    try:
        controls = self.controls
        layers = self.layers
        self.clear_controls()

        if zoom_control:
            self.add(ipyleaflet.ZoomControl())
        if fullscreen_control:
            self.add(ipyleaflet.FullScreenControl())

        if left_label is not None:
            left_name = left_label
        else:
            left_name = "Left Layer"

        if right_label is not None:
            right_name = right_label
        else:
            right_name = "Right Layer"

        if "attribution" not in kwargs:
            kwargs["attribution"] = " "

        if left_layer in basemaps.keys():
            left_layer = get_basemap(left_layer)
        elif isinstance(left_layer, str):
            if left_layer.startswith("http") and left_layer.endswith(".tif"):
                url = cog_tile(left_layer)
                left_layer = ipyleaflet.TileLayer(
                    url=url,
                    name=left_name,
                    **kwargs,
                )
            else:
                left_layer = ipyleaflet.TileLayer(
                    url=left_layer,
                    name=left_name,
                    **kwargs,
                )
        elif isinstance(left_layer, ipyleaflet.TileLayer):
            pass
        else:
            raise ValueError(
                f"left_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
            )

        if right_layer in basemaps.keys():
            right_layer = get_basemap(right_layer)
        elif isinstance(right_layer, str):
            if right_layer.startswith("http") and right_layer.endswith(".tif"):
                url = cog_tile(right_layer)
                right_layer = ipyleaflet.TileLayer(
                    url=url,
                    name=right_name,
                    **kwargs,
                )
            else:
                right_layer = ipyleaflet.TileLayer(
                    url=right_layer,
                    name=right_name,
                    **kwargs,
                )
        elif isinstance(right_layer, ipyleaflet.TileLayer):
            pass
        else:
            raise ValueError(
                f"right_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
            )

        control = ipyleaflet.SplitMapControl(
            left_layer=left_layer, right_layer=right_layer
        )

        self.add(control)
        # self.dragging = False

        if left_label is not None:
            if widget_layout is None:
                widget_layout = widgets.Layout(padding="0px 4px 0px 4px")
            left_widget = widgets.HTML(value=left_label, layout=widget_layout)

            left_control = ipyleaflet.WidgetControl(
                widget=left_widget, position=left_position
            )
            self.add(left_control)

        if right_label is not None:
            if widget_layout is None:
                widget_layout = widgets.Layout(padding="0px 4px 0px 4px")
            right_widget = widgets.HTML(value=right_label, layout=widget_layout)
            right_control = ipyleaflet.WidgetControl(
                widget=right_widget, position=right_position
            )
            self.add(right_control)

        close_button = widgets.ToggleButton(
            value=False,
            tooltip="Close split-panel map",
            icon="times",
            layout=widgets.Layout(
                height="28px", width="28px", padding="0px 0px 0px 4px"
            ),
        )

        def close_btn_click(change):
            if left_label is not None:
                self.remove_control(left_control)

            if right_label is not None:
                self.remove_control(right_control)

            if change["new"]:
                self.controls = controls
                self.layers = layers[:-1]
                self.add(layers[-1])

            # self.dragging = True

        close_button.observe(close_btn_click, "value")
        close_control = ipyleaflet.WidgetControl(
            widget=close_button, position=close_button_position
        )

        if add_close_button:
            self.add(close_control)

        if layer_control:
            self.addLayerControl()

    except Exception as e:
        print("The provided layers are invalid!")
        raise ValueError(e)

to_gradio(width='100%', height='500px', **kwargs)

Converts the map to an HTML string that can be used in Gradio. Removes unsupported elements, such as attribution and any code blocks containing functions. See https://github.com/gradio-app/gradio/issues/3190

Parameters:

Name	Type	Description	Default
width	str	The width of the map. Defaults to '100%'.	'100%'
height	str	The height of the map. Defaults to '500px'.	'500px'

Returns:

Name	Type	Description
str		The HTML string to use in Gradio.

Source code in geemap/geemap.py

def to_gradio(self, width="100%", height="500px", **kwargs):
    """Converts the map to an HTML string that can be used in Gradio. Removes unsupported elements, such as
        attribution and any code blocks containing functions. See https://github.com/gradio-app/gradio/issues/3190

    Args:
        width (str, optional): The width of the map. Defaults to '100%'.
        height (str, optional): The height of the map. Defaults to '500px'.

    Returns:
        str: The HTML string to use in Gradio.
    """

    print(
        "The ipyleaflet plotting backend does not support this function. Please use the folium backend instead."
    )

to_html(filename=None, title='My Map', width='100%', height='880px', add_layer_control=True, **kwargs)

Saves the map as an HTML file.

Parameters:

Name	Type	Description	Default
filename	str	The output file path to the HTML file.	None
title	str	The title of the HTML file. Defaults to 'My Map'.	'My Map'
width	str	The width of the map in pixels or percentage. Defaults to '100%'.	'100%'
height	str	The height of the map in pixels. Defaults to '880px'.	'880px'
add_layer_control	bool	Whether to add the LayersControl. Defaults to True.	True

Source code in geemap/geemap.py

def to_html(
    self,
    filename=None,
    title="My Map",
    width="100%",
    height="880px",
    add_layer_control=True,
    **kwargs,
):
    """Saves the map as an HTML file.

    Args:
        filename (str, optional): The output file path to the HTML file.
        title (str, optional): The title of the HTML file. Defaults to 'My Map'.
        width (str, optional): The width of the map in pixels or percentage. Defaults to '100%'.
        height (str, optional): The height of the map in pixels. Defaults to '880px'.
        add_layer_control (bool, optional): Whether to add the LayersControl. Defaults to True.

    """
    try:
        save = True
        if filename is not None:
            if not filename.endswith(".html"):
                raise ValueError("The output file extension must be html.")
            filename = os.path.abspath(filename)
            out_dir = os.path.dirname(filename)
            if not os.path.exists(out_dir):
                os.makedirs(out_dir)
        else:
            filename = os.path.abspath(random_string() + ".html")
            save = False

        if add_layer_control and self.layer_control is None:
            layer_control = ipyleaflet.LayersControl(position="topright")
            self.layer_control = layer_control
            self.add(layer_control)

        before_width = self.layout.width
        before_height = self.layout.height

        if not isinstance(width, str):
            print("width must be a string.")
            return
        elif width.endswith("px") or width.endswith("%"):
            pass
        else:
            print("width must end with px or %")
            return

        if not isinstance(height, str):
            print("height must be a string.")
            return
        elif not height.endswith("px"):
            print("height must end with px")
            return

        self.layout.width = width
        self.layout.height = height

        self.save(filename, title=title, **kwargs)

        self.layout.width = before_width
        self.layout.height = before_height

        if not save:
            out_html = ""
            with open(filename) as f:
                lines = f.readlines()
                out_html = "".join(lines)
            os.remove(filename)
            return out_html

    except Exception as e:
        raise Exception(e)

to_image(filename=None, monitor=1)

Saves the map as a PNG or JPG image.

Parameters:

Name	Type	Description	Default
filename	str	The output file path to the image. Defaults to None.	None
monitor	int	The monitor to take the screenshot. Defaults to 1.	1

Source code in geemap/geemap.py

def to_image(self, filename=None, monitor=1):
    """Saves the map as a PNG or JPG image.

    Args:
        filename (str, optional): The output file path to the image. Defaults to None.
        monitor (int, optional): The monitor to take the screenshot. Defaults to 1.
    """
    self.screenshot = None

    if filename is None:
        filename = os.path.join(os.getcwd(), "my_map.png")

    if filename.endswith(".png") or filename.endswith(".jpg"):
        pass
    else:
        print("The output file must be a PNG or JPG image.")
        return

    work_dir = os.path.dirname(filename)
    if not os.path.exists(work_dir):
        os.makedirs(work_dir)

    screenshot = screen_capture(filename, monitor)
    self.screenshot = screenshot

to_streamlit(width=None, height=600, scrolling=False, **kwargs)

Renders map figure in a Streamlit app.

Parameters:

Name	Type	Description	Default
width	int	Width of the map. Defaults to None.	None
height	int	Height of the map. Defaults to 600.	600
responsive	bool	Whether to make the map responsive. Defaults to True.	required
scrolling	bool	If True, show a scrollbar when the content is larger than the iframe. Otherwise, do not show a scrollbar. Defaults to False.	False

Returns:

Type	Description
	streamlit.components: components.html object.

Source code in geemap/geemap.py

def to_streamlit(self, width=None, height=600, scrolling=False, **kwargs):
    """Renders map figure in a Streamlit app.

    Args:
        width (int, optional): Width of the map. Defaults to None.
        height (int, optional): Height of the map. Defaults to 600.
        responsive (bool, optional): Whether to make the map responsive. Defaults to True.
        scrolling (bool, optional): If True, show a scrollbar when the content is larger than the iframe. Otherwise, do not show a scrollbar. Defaults to False.

    Returns:
        streamlit.components: components.html object.
    """

    try:
        import streamlit.components.v1 as components

        # if responsive:
        #     make_map_responsive = """
        #     <style>
        #     [title~="st.iframe"] { width: 100%}
        #     </style>
        #     """
        #     st.markdown(make_map_responsive, unsafe_allow_html=True)
        return components.html(
            self.to_html(), width=width, height=height, scrolling=scrolling
        )

    except Exception as e:
        raise Exception(e)

toolbar_reset()

Reset the toolbar so that no tool is selected.

Source code in geemap/geemap.py

def toolbar_reset(self):
    """Reset the toolbar so that no tool is selected."""
    if hasattr(self, "_toolbar"):
        self._toolbar.reset()

ts_inspector(left_ts, left_names=None, left_vis={}, left_index=0, right_ts=None, right_names=None, right_vis=None, right_index=-1, width='130px', date_format='YYYY-MM-dd', add_close_button=False, **kwargs)

Creates a split-panel map for inspecting timeseries images.

Parameters:

Name	Type	Description	Default
left_ts	object	An ee.ImageCollection to show on the left panel.	required
left_names	list	A list of names to show under the left dropdown.	None
left_vis	dict	Visualization parameters for the left layer. Defaults to {}.	{}
left_index	int	The index of the left layer to show. Defaults to 0.	0
right_ts	object	An ee.ImageCollection to show on the right panel.	None
right_names	list	A list of names to show under the right dropdown.	None
right_vis	dict	Visualization parameters for the right layer. Defaults to {}.	None
right_index	int	The index of the right layer to show. Defaults to -1.	-1
width	str	The width of the dropdown list. Defaults to '130px'.	'130px'
date_format	str	The date format to show in the dropdown. Defaults to 'YYYY-MM-dd'.	'YYYY-MM-dd'
add_close_button	bool	Whether to show the close button. Defaults to False.	False

Source code in geemap/geemap.py

def ts_inspector(
    self,
    left_ts,
    left_names=None,
    left_vis={},
    left_index=0,
    right_ts=None,
    right_names=None,
    right_vis=None,
    right_index=-1,
    width="130px",
    date_format="YYYY-MM-dd",
    add_close_button=False,
    **kwargs,
):
    """Creates a split-panel map for inspecting timeseries images.

    Args:
        left_ts (object): An ee.ImageCollection to show on the left panel.
        left_names (list): A list of names to show under the left dropdown.
        left_vis (dict, optional): Visualization parameters for the left layer. Defaults to {}.
        left_index (int, optional): The index of the left layer to show. Defaults to 0.
        right_ts (object): An ee.ImageCollection to show on the right panel.
        right_names (list): A list of names to show under the right dropdown.
        right_vis (dict, optional): Visualization parameters for the right layer. Defaults to {}.
        right_index (int, optional): The index of the right layer to show. Defaults to -1.
        width (str, optional): The width of the dropdown list. Defaults to '130px'.
        date_format (str, optional): The date format to show in the dropdown. Defaults to 'YYYY-MM-dd'.
        add_close_button (bool, optional): Whether to show the close button. Defaults to False.
    """
    controls = self.controls
    layers = self.layers

    if left_names is None:
        left_names = image_dates(left_ts, date_format=date_format).getInfo()

    if right_ts is None:
        right_ts = left_ts

    if right_names is None:
        right_names = left_names

    if right_vis is None:
        right_vis = left_vis

    left_count = int(left_ts.size().getInfo())
    right_count = int(right_ts.size().getInfo())

    if left_count != len(left_names):
        print(
            "The number of images in left_ts must match the number of layer names in left_names."
        )
        return
    if right_count != len(right_names):
        print(
            "The number of images in right_ts must match the number of layer names in right_names."
        )
        return

    left_layer = ipyleaflet.TileLayer(
        url="https://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer/tile/{z}/{y}/{x}",
        attribution="Esri",
        name="Esri.WorldStreetMap",
    )
    right_layer = ipyleaflet.TileLayer(
        url="https://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer/tile/{z}/{y}/{x}",
        attribution="Esri",
        name="Esri.WorldStreetMap",
    )

    self.clear_controls()
    left_dropdown = widgets.Dropdown(options=left_names, value=None)
    right_dropdown = widgets.Dropdown(options=right_names, value=None)
    left_dropdown.layout.max_width = width
    right_dropdown.layout.max_width = width

    left_control = ipyleaflet.WidgetControl(
        widget=left_dropdown, position="topleft"
    )
    right_control = ipyleaflet.WidgetControl(
        widget=right_dropdown, position="topright"
    )

    self.add(left_control)
    self.add(right_control)

    self.add(ipyleaflet.ZoomControl(position="topleft"))
    self.add(ipyleaflet.ScaleControl(position="bottomleft"))
    self.add(ipyleaflet.FullScreenControl())

    def left_dropdown_change(change):
        left_dropdown_index = left_dropdown.index
        if left_dropdown_index is not None and left_dropdown_index >= 0:
            try:
                if isinstance(left_ts, ee.ImageCollection):
                    left_image = left_ts.toList(left_ts.size()).get(
                        left_dropdown_index
                    )
                elif isinstance(left_ts, ee.List):
                    left_image = left_ts.get(left_dropdown_index)
                else:
                    print("The left_ts argument must be an ImageCollection.")
                    return

                if isinstance(left_image, ee.ImageCollection):
                    left_image = ee.Image(left_image.mosaic())
                elif isinstance(left_image, ee.Image):
                    pass
                else:
                    left_image = ee.Image(left_image)

                left_image = EELeafletTileLayer(
                    left_image, left_vis, left_names[left_dropdown_index]
                )
                left_layer.url = left_image.url
            except Exception as e:
                print(e)
                return

    left_dropdown.observe(left_dropdown_change, names="value")

    def right_dropdown_change(change):
        right_dropdown_index = right_dropdown.index
        if right_dropdown_index is not None and right_dropdown_index >= 0:
            try:
                if isinstance(right_ts, ee.ImageCollection):
                    right_image = right_ts.toList(left_ts.size()).get(
                        right_dropdown_index
                    )
                elif isinstance(right_ts, ee.List):
                    right_image = right_ts.get(right_dropdown_index)
                else:
                    print("The left_ts argument must be an ImageCollection.")
                    return

                if isinstance(right_image, ee.ImageCollection):
                    right_image = ee.Image(right_image.mosaic())
                elif isinstance(right_image, ee.Image):
                    pass
                else:
                    right_image = ee.Image(right_image)

                right_image = EELeafletTileLayer(
                    right_image,
                    right_vis,
                    right_names[right_dropdown_index],
                )
                right_layer.url = right_image.url
            except Exception as e:
                print(e)
                return

    right_dropdown.observe(right_dropdown_change, names="value")

    if left_index is not None:
        left_dropdown.value = left_names[left_index]
    if right_index is not None:
        right_dropdown.value = right_names[right_index]

    close_button = widgets.ToggleButton(
        value=False,
        tooltip="Close the tool",
        icon="times",
        # button_style="primary",
        layout=widgets.Layout(
            height="28px", width="28px", padding="0px 0px 0px 4px"
        ),
    )

    def close_btn_click(change):
        if change["new"]:
            self.controls = controls
            self.clear_layers()
            self.layers = layers

    close_button.observe(close_btn_click, "value")
    close_control = ipyleaflet.WidgetControl(
        widget=close_button, position="bottomright"
    )

    try:
        split_control = ipyleaflet.SplitMapControl(
            left_layer=left_layer, right_layer=right_layer
        )
        self.add(split_control)
        # self.dragging = False

        if add_close_button:
            self.add(close_control)

    except Exception as e:
        raise Exception(e)

user_roi_coords(decimals=4)

Return the bounding box of the ROI as a list of coordinates.

Parameters:

Name	Type	Description	Default
decimals	int	Number of decimals to round the coordinates to. Defaults to 4.	4

Source code in geemap/geemap.py

def user_roi_coords(self, decimals=4):
    """Return the bounding box of the ROI as a list of coordinates.

    Args:
        decimals (int, optional): Number of decimals to round the coordinates to. Defaults to 4.
    """
    return bbox_coords(self.user_roi, decimals=decimals)

video_overlay(url, bounds, name='Video')

Overlays a video from the Internet on the map.

Parameters:

Name	Type	Description	Default
url	str	http URL of the video, such as "https://www.mapbox.com/bites/00188/patricia_nasa.webm"	required
bounds	tuple	bounding box of the video in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).	required
name	str	name of the layer to show on the layer control.	'Video'

Source code in geemap/geemap.py

def video_overlay(self, url, bounds, name="Video"):
    """Overlays a video from the Internet on the map.

    Args:
        url (str): http URL of the video, such as "https://www.mapbox.com/bites/00188/patricia_nasa.webm"
        bounds (tuple): bounding box of the video in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).
        name (str): name of the layer to show on the layer control.
    """
    try:
        video = ipyleaflet.VideoOverlay(url=url, bounds=bounds, name=name)
        self.add(video)
    except Exception as e:
        print(e)

zoom_to_bounds(bounds)

Zooms to a bounding box in the form of [minx, miny, maxx, maxy].

Parameters:

Name	Type	Description	Default
bounds	Union[List[float], Tuple[float, float, float, float]]	A list/tuple containing minx, miny, maxx, maxy values for the bounds.	required

Source code in geemap/geemap.py

def zoom_to_bounds(
    self, bounds: Union[List[float], Tuple[float, float, float, float]]
) -> None:
    """Zooms to a bounding box in the form of [minx, miny, maxx, maxy].

    Args:
        bounds (Union[List[float], Tuple[float, float, float, float]]): A
            list/tuple containing minx, miny, maxx, maxy values for the bounds.
    """
    #  The ipyleaflet fit_bounds method takes lat/lon bounds in the form [[south, west], [north, east]].
    self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

zoom_to_gdf(gdf)

Zooms to the bounding box of a GeoPandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoPandas GeoDataFrame.	required

Source code in geemap/geemap.py

def zoom_to_gdf(self, gdf):
    """Zooms to the bounding box of a GeoPandas GeoDataFrame.

    Args:
        gdf (GeoDataFrame): A GeoPandas GeoDataFrame.
    """
    bounds = gdf.total_bounds
    self.zoom_to_bounds(bounds)

zoom_to_me(zoom=14, add_marker=True)

Zoom to the current device location.

Parameters:

Name	Type	Description	Default
zoom	int	Zoom level. Defaults to 14.	14
add_marker	bool	Whether to add a marker of the current device location. Defaults to True.	True

Source code in geemap/geemap.py

def zoom_to_me(self, zoom=14, add_marker=True):
    """Zoom to the current device location.

    Args:
        zoom (int, optional): Zoom level. Defaults to 14.
        add_marker (bool, optional): Whether to add a marker of the current device location. Defaults to True.
    """
    lat, lon = get_current_latlon()
    self.set_center(lon, lat, zoom)

    if add_marker:
        marker = ipyleaflet.Marker(
            location=(lat, lon),
            draggable=False,
            name="Device location",
        )
        self.add(marker)

PlanetaryComputerEndpoint

Bases: TitilerEndpoint

This class contains the methods for the Microsoft Planetary Computer endpoint.

Source code in geemap/common.py

class PlanetaryComputerEndpoint(TitilerEndpoint):
    """This class contains the methods for the Microsoft Planetary Computer endpoint."""

    def __init__(
        self,
        endpoint="https://planetarycomputer.microsoft.com/api/data/v1",
        name="item",
        TileMatrixSetId="WebMercatorQuad",
    ):
        """Initialize the PlanetaryComputerEndpoint object.

        Args:
            endpoint (str, optional): The endpoint of the titiler server. Defaults to "https://planetarycomputer.microsoft.com/api/data/v1".
            name (str, optional): The name to be used in the file path. Defaults to "item".
            TileMatrixSetId (str, optional): The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".
        """
        super().__init__(endpoint, name, TileMatrixSetId)

    def url_for_stac_collection(self):
        return f"{self.endpoint}/collection/{self.TileMatrixSetId}/tilejson.json"

    def url_for_collection_assets(self):
        return f"{self.endpoint}/collection/assets"

    def url_for_collection_bounds(self):
        return f"{self.endpoint}/collection/bounds"

    def url_for_collection_info(self):
        return f"{self.endpoint}/collection/info"

    def url_for_collection_info_geojson(self):
        return f"{self.endpoint}/collection/info.geojson"

    def url_for_collection_pixel_value(self, lon, lat):
        return f"{self.endpoint}/collection/point/{lon},{lat}"

    def url_for_collection_wmts(self):
        return f"{self.endpoint}/collection/{self.TileMatrixSetId}/WMTSCapabilities.xml"

    def url_for_collection_lat_lon_assets(self, lng, lat):
        return f"{self.endpoint}/collection/{lng},{lat}/assets"

    def url_for_collection_bbox_assets(self, minx, miny, maxx, maxy):
        return f"{self.endpoint}/collection/{minx},{miny},{maxx},{maxy}/assets"

    def url_for_stac_mosaic(self, searchid):
        return f"{self.endpoint}/mosaic/{searchid}/{self.TileMatrixSetId}/tilejson.json"

    def url_for_mosaic_info(self, searchid):
        return f"{self.endpoint}/mosaic/{searchid}/info"

    def url_for_mosaic_lat_lon_assets(self, searchid, lon, lat):
        return f"{self.endpoint}/mosaic/{searchid}/{lon},{lat}/assets"

__init__(endpoint='https://planetarycomputer.microsoft.com/api/data/v1', name='item', TileMatrixSetId='WebMercatorQuad')

Initialize the PlanetaryComputerEndpoint object.

Parameters:

Name	Type	Description	Default
endpoint	str	The endpoint of the titiler server. Defaults to "https://planetarycomputer.microsoft.com/api/data/v1".	'https://planetarycomputer.microsoft.com/api/data/v1'
name	str	The name to be used in the file path. Defaults to "item".	'item'
TileMatrixSetId	str	The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".	'WebMercatorQuad'

Source code in geemap/common.py

def __init__(
    self,
    endpoint="https://planetarycomputer.microsoft.com/api/data/v1",
    name="item",
    TileMatrixSetId="WebMercatorQuad",
):
    """Initialize the PlanetaryComputerEndpoint object.

    Args:
        endpoint (str, optional): The endpoint of the titiler server. Defaults to "https://planetarycomputer.microsoft.com/api/data/v1".
        name (str, optional): The name to be used in the file path. Defaults to "item".
        TileMatrixSetId (str, optional): The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".
    """
    super().__init__(endpoint, name, TileMatrixSetId)

TitilerEndpoint

This class contains the methods for the titiler endpoint.

Source code in geemap/common.py

class TitilerEndpoint:
    """This class contains the methods for the titiler endpoint."""

    def __init__(
        self,
        endpoint="https://titiler.xyz",
        name="stac",
        TileMatrixSetId="WebMercatorQuad",
    ):
        """Initialize the TitilerEndpoint object.

        Args:
            endpoint (str, optional): The endpoint of the titiler server. Defaults to "https://titiler.xyz".
            name (str, optional): The name to be used in the file path. Defaults to "stac".
            TileMatrixSetId (str, optional): The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".
        """
        self.endpoint = endpoint
        self.name = name
        self.TileMatrixSetId = TileMatrixSetId

    def url_for_stac_item(self):
        return f"{self.endpoint}/{self.name}/{self.TileMatrixSetId}/tilejson.json"

    def url_for_stac_assets(self):
        return f"{self.endpoint}/{self.name}/assets"

    def url_for_stac_bounds(self):
        return f"{self.endpoint}/{self.name}/bounds"

    def url_for_stac_info(self):
        return f"{self.endpoint}/{self.name}/info"

    def url_for_stac_info_geojson(self):
        return f"{self.endpoint}/{self.name}/info.geojson"

    def url_for_stac_statistics(self):
        return f"{self.endpoint}/{self.name}/statistics"

    def url_for_stac_pixel_value(self, lon, lat):
        return f"{self.endpoint}/{self.name}/point/{lon},{lat}"

    def url_for_stac_wmts(self):
        return (
            f"{self.endpoint}/{self.name}/{self.TileMatrixSetId}/WMTSCapabilities.xml"
        )

__init__(endpoint='https://titiler.xyz', name='stac', TileMatrixSetId='WebMercatorQuad')

Initialize the TitilerEndpoint object.

Parameters:

Name	Type	Description	Default
endpoint	str	The endpoint of the titiler server. Defaults to "https://titiler.xyz".	'https://titiler.xyz'
name	str	The name to be used in the file path. Defaults to "stac".	'stac'
TileMatrixSetId	str	The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".	'WebMercatorQuad'

Source code in geemap/common.py

def __init__(
    self,
    endpoint="https://titiler.xyz",
    name="stac",
    TileMatrixSetId="WebMercatorQuad",
):
    """Initialize the TitilerEndpoint object.

    Args:
        endpoint (str, optional): The endpoint of the titiler server. Defaults to "https://titiler.xyz".
        name (str, optional): The name to be used in the file path. Defaults to "stac".
        TileMatrixSetId (str, optional): The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".
    """
    self.endpoint = endpoint
    self.name = name
    self.TileMatrixSetId = TileMatrixSetId

add_crs(filename, epsg)

Add a CRS to a raster dataset.

Parameters:

Name	Type	Description	Default
filename	str	The filename of the raster dataset.	required
epsg	int | str	The EPSG code of the CRS.	required

Source code in geemap/common.py

def add_crs(filename, epsg):
    """Add a CRS to a raster dataset.

    Args:
        filename (str): The filename of the raster dataset.
        epsg (int | str): The EPSG code of the CRS.

    """
    try:
        import rasterio
    except ImportError:
        raise ImportError(
            "rasterio is required for adding a CRS to a raster. Please install it using 'pip install rasterio'."
        )

    if not os.path.exists(filename):
        raise ValueError("filename must exist.")

    if isinstance(epsg, int):
        epsg = f"EPSG:{epsg}"
    elif isinstance(epsg, str):
        epsg = "EPSG:" + epsg
    else:
        raise ValueError("epsg must be an integer or string.")

    crs = rasterio.crs.CRS({"init": epsg})
    with rasterio.open(filename, mode="r+") as src:
        src.crs = crs

add_image_to_gif(in_gif, out_gif, in_image, xy=None, image_size=(80, 80), circle_mask=False)

Adds an image logo to a GIF image.

Parameters:

Name	Type	Description	Default
in_gif	str	Input file path to the GIF image.	required
out_gif	str	Output file path to the GIF image.	required
in_image	str	Input file path to the image.	required
xy	tuple	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	None
image_size	tuple	Resize image. Defaults to (80, 80).	(80, 80)
circle_mask	bool	Whether to apply a circle mask to the image. This only works with non-png images. Defaults to False.	False

Source code in geemap/timelapse.py

def add_image_to_gif(
    in_gif, out_gif, in_image, xy=None, image_size=(80, 80), circle_mask=False
):
    """Adds an image logo to a GIF image.

    Args:
        in_gif (str): Input file path to the GIF image.
        out_gif (str): Output file path to the GIF image.
        in_image (str): Input file path to the image.
        xy (tuple, optional): Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        image_size (tuple, optional): Resize image. Defaults to (80, 80).
        circle_mask (bool, optional): Whether to apply a circle mask to the image. This only works with non-png images. Defaults to False.
    """
    # import io
    import warnings

    from PIL import Image, ImageDraw, ImageSequence

    warnings.simplefilter("ignore")

    in_gif = os.path.abspath(in_gif)

    is_url = False
    if in_image.startswith("http"):
        is_url = True

    if not os.path.exists(in_gif):
        print("The input gif file does not exist.")
        return

    if (not is_url) and (not os.path.exists(in_image)):
        print("The provided logo file does not exist.")
        return

    out_dir = check_dir((os.path.dirname(out_gif)))
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    try:
        gif = Image.open(in_gif)
    except Exception as e:
        print("An error occurred while opening the image.")
        print(e)
        return

    logo_raw_image = None
    try:
        if in_image.startswith("http"):
            logo_raw_image = open_image_from_url(in_image)
        else:
            in_image = os.path.abspath(in_image)
            logo_raw_image = Image.open(in_image)
    except Exception as e:
        print(e)

    logo_raw_size = logo_raw_image.size

    ratio = max(
        logo_raw_size[0] / image_size[0],
        logo_raw_size[1] / image_size[1],
    )
    image_resize = (int(logo_raw_size[0] / ratio), int(logo_raw_size[1] / ratio))
    image_size = min(logo_raw_size[0], image_size[0]), min(
        logo_raw_size[1], image_size[1]
    )

    logo_image = logo_raw_image.convert("RGBA")
    logo_image.thumbnail(image_size, Image.LANCZOS)

    gif_width, gif_height = gif.size
    mask_im = None

    if circle_mask:
        mask_im = Image.new("L", image_size, 0)
        draw = ImageDraw.Draw(mask_im)
        draw.ellipse((0, 0, image_size[0], image_size[1]), fill=255)

    if has_transparency(logo_raw_image):
        mask_im = logo_image.copy()

    if xy is None:
        # default logo location is 5% width and 5% height of the image.
        delta = 10
        xy = (gif_width - image_resize[0] - delta, gif_height - image_resize[1] - delta)
        # xy = (int(0.05 * gif_width), int(0.05 * gif_height))
    elif (xy is not None) and (not isinstance(xy, tuple)) and (len(xy) == 2):
        print("xy must be a tuple, e.g., (10, 10), ('10%', '10%')")
        return
    elif all(isinstance(item, int) for item in xy) and (len(xy) == 2):
        x, y = xy
        if (x > 0) and (x < gif_width) and (y > 0) and (y < gif_height):
            pass
        else:
            print(
                "xy is out of bounds. x must be within [0, {}], and y must be within [0, {}]".format(
                    gif_width, gif_height
                )
            )
            return
    elif all(isinstance(item, str) for item in xy) and (len(xy) == 2):
        x, y = xy
        if ("%" in x) and ("%" in y):
            try:
                x = int(float(x.replace("%", "")) / 100.0 * gif_width)
                y = int(float(y.replace("%", "")) / 100.0 * gif_height)
                xy = (x, y)
            except Exception:
                raise Exception(
                    "The specified xy is invalid. It must be formatted like this ('10%', '10%')"
                )

    else:
        raise Exception(
            "The specified xy is invalid. It must be formatted like this: (10, 10) or ('10%', '10%')"
        )

    try:
        frames = []
        for _, frame in enumerate(ImageSequence.Iterator(gif)):
            frame = frame.convert("RGBA")
            frame.paste(logo_image, xy, mask_im)

            b = io.BytesIO()
            frame.save(b, format="GIF")
            frame = Image.open(b)
            frames.append(frame)

        frames[0].save(out_gif, save_all=True, append_images=frames[1:])
    except Exception as e:
        print(e)

add_overlay(collection, overlay_data, color='black', width=1, opacity=1.0, region=None)

Adds an overlay to an image collection.

Parameters:

Name	Type	Description	Default
collection	ImageCollection	The image collection to add the overlay to.	required
overlay_data	str | Geometry | FeatureCollection	The overlay data to add to the image collection. It can be an HTTP URL to a GeoJSON file.	required
color	str	The color of the overlay. Defaults to 'black'.	'black'
width	int	The width of the overlay. Defaults to 1.	1
opacity	float	The opacity of the overlay. Defaults to 1.0.	1.0
region	Geometry | FeatureCollection	The region of interest to add the overlay to. Defaults to None.	None

Returns:

Type	Description
ImageCollection	ee.ImageCollection: An ImageCollection with the overlay added.

Source code in geemap/timelapse.py

def add_overlay(
    collection: ee.ImageCollection,
    overlay_data: Union[str, ee.Geometry, ee.FeatureCollection],
    color: str = "black",
    width: int = 1,
    opacity: float = 1.0,
    region: Union[ee.Geometry, ee.FeatureCollection] = None,
) -> ee.ImageCollection:
    """Adds an overlay to an image collection.

    Args:
        collection (ee.ImageCollection): The image collection to add the overlay to.
        overlay_data (str | ee.Geometry | ee.FeatureCollection): The overlay data to add to the image collection. It can be an HTTP URL to a GeoJSON file.
        color (str, optional): The color of the overlay. Defaults to 'black'.
        width (int, optional): The width of the overlay. Defaults to 1.
        opacity (float, optional): The opacity of the overlay. Defaults to 1.0.
        region (ee.Geometry | ee.FeatureCollection, optional): The region of interest to add the overlay to. Defaults to None.

    Returns:
        ee.ImageCollection: An ImageCollection with the overlay added.
    """

    # Some common administrative boundaries.
    public_assets = ["continents", "countries", "us_states", "china"]

    if not isinstance(collection, ee.ImageCollection):
        raise Exception("The collection must be an ee.ImageCollection.")

    if not isinstance(overlay_data, ee.FeatureCollection):
        if isinstance(overlay_data, str):
            try:
                if overlay_data.lower() in public_assets:
                    overlay_data = ee.FeatureCollection(
                        f"users/giswqs/public/{overlay_data.lower()}"
                    )
                elif overlay_data.startswith("http") and overlay_data.endswith(
                    ".geojson"
                ):
                    overlay_data = geojson_to_ee(overlay_data)
                else:
                    overlay_data = ee.FeatureCollection(overlay_data)

            except Exception as e:
                print(
                    "The overlay_data must be a valid ee.FeatureCollection, a valid ee.FeatureCollection asset id, or http url to a geojson file."
                )
                raise Exception(e)
        elif isinstance(overlay_data, ee.Feature):
            overlay_data = ee.FeatureCollection([overlay_data])
        elif isinstance(overlay_data, ee.Geometry):
            overlay_data = ee.FeatureCollection([ee.Feature(overlay_data)])
        else:
            raise Exception(
                "The overlay_data must be a valid ee.FeatureCollection or a valid ee.FeatureCollection asset id."
            )

    try:
        if region is not None:
            overlay_data = overlay_data.filterBounds(region)

        empty = ee.Image().byte()
        image = empty.paint(
            **{
                "featureCollection": overlay_data,
                "color": 1,
                "width": width,
            }
        ).visualize(**{"palette": check_color(color), "opacity": opacity})
        blend_col = collection.map(
            lambda img: img.blend(image).set(
                "system:time_start", img.get("system:time_start")
            )
        )
        return blend_col
    except Exception as e:
        print("Error in add_overlay:")
        raise Exception(e)

add_progress_bar_to_gif(in_gif, out_gif, progress_bar_color='blue', progress_bar_height=5, duration=100, loop=0)

Adds a progress bar to a GIF image.

Parameters:

Name	Type	Description	Default
in_gif	str	The file path to the input GIF image.	required
out_gif	str	The file path to the output GIF image.	required
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'blue'
progress_bar_height	int	Height of the progress bar. Defaults to 5.	5
duration	int	controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation.. Defaults to 100.	100
loop	int	controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.	0

Source code in geemap/timelapse.py

def add_progress_bar_to_gif(
    in_gif,
    out_gif,
    progress_bar_color="blue",
    progress_bar_height=5,
    duration=100,
    loop=0,
):
    """Adds a progress bar to a GIF image.

    Args:
        in_gif (str): The file path to the input GIF image.
        out_gif (str): The file path to the output GIF image.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
        duration (int, optional): controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation.. Defaults to 100.
        loop (int, optional): controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.

    """
    import io
    import warnings

    from PIL import Image, ImageDraw, ImageSequence

    warnings.simplefilter("ignore")

    in_gif = os.path.abspath(in_gif)
    out_gif = os.path.abspath(out_gif)

    if not os.path.exists(in_gif):
        print("The input gif file does not exist.")
        return

    if not os.path.exists(os.path.dirname(out_gif)):
        os.makedirs(os.path.dirname(out_gif))

    progress_bar_color = check_color(progress_bar_color)

    try:
        image = Image.open(in_gif)
    except Exception as e:
        raise Exception("An error occurred while opening the gif.")

    count = image.n_frames
    W, H = image.size
    progress_bar_widths = [i * 1.0 / count * W for i in range(1, count + 1)]
    progress_bar_shapes = [
        [(0, H - progress_bar_height), (x, H)] for x in progress_bar_widths
    ]

    try:
        frames = []
        # Loop over each frame in the animated image
        for index, frame in enumerate(ImageSequence.Iterator(image)):
            # Draw the text on the frame
            frame = frame.convert("RGB")
            draw = ImageDraw.Draw(frame)
            # w, h = draw.textsize(text[index])
            draw.rectangle(progress_bar_shapes[index], fill=progress_bar_color)
            del draw

            b = io.BytesIO()
            frame.save(b, format="GIF")
            frame = Image.open(b)

            frames.append(frame)
        # https://www.pythoninformer.com/python-libraries/pillow/creating-animated-gif/
        # Save the frames as a new image

        frames[0].save(
            out_gif,
            save_all=True,
            append_images=frames[1:],
            duration=duration,
            loop=loop,
            optimize=True,
        )
    except Exception as e:
        raise Exception(e)

add_text_to_gif(in_gif, out_gif, xy=None, text_sequence=None, font_type='arial.ttf', font_size=20, font_color='#000000', add_progress_bar=True, progress_bar_color='white', progress_bar_height=5, duration=100, loop=0)

Adds animated text to a GIF image.

Parameters:

Name	Type	Description	Default
in_gif	str	The file path to the input GIF image.	required
out_gif	str	The file path to the output GIF image.	required
xy	tuple	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	None
text_sequence	(int, str, list)	Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.	None
font_type	str	Font type. Defaults to "arial.ttf".	'arial.ttf'
font_size	int	Font size. Defaults to 20.	20
font_color	str	Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff'). Defaults to '#000000'.	'#000000'
add_progress_bar	bool	Whether to add a progress bar at the bottom of the GIF. Defaults to True.	True
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'white'
progress_bar_height	int	Height of the progress bar. Defaults to 5.	5
duration	int	controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation.. Defaults to 100.	100
loop	int	controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.	0

Source code in geemap/timelapse.py

def add_text_to_gif(
    in_gif,
    out_gif,
    xy=None,
    text_sequence=None,
    font_type="arial.ttf",
    font_size=20,
    font_color="#000000",
    add_progress_bar=True,
    progress_bar_color="white",
    progress_bar_height=5,
    duration=100,
    loop=0,
):
    """Adds animated text to a GIF image.

    Args:
        in_gif (str): The file path to the input GIF image.
        out_gif (str): The file path to the output GIF image.
        xy (tuple, optional): Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.
        font_type (str, optional): Font type. Defaults to "arial.ttf".
        font_size (int, optional): Font size. Defaults to 20.
        font_color (str, optional): Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff').  Defaults to '#000000'.
        add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF. Defaults to True.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
        duration (int, optional): controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation.. Defaults to 100.
        loop (int, optional): controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.

    """
    # import io
    import warnings

    import importlib.resources
    from PIL import Image, ImageDraw, ImageFont, ImageSequence

    warnings.simplefilter("ignore")

    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    default_font = os.path.join(pkg_dir, "data/fonts/arial.ttf")

    in_gif = os.path.abspath(in_gif)
    out_gif = os.path.abspath(out_gif)

    if not os.path.exists(in_gif):
        print("The input gif file does not exist.")
        return

    if not os.path.exists(os.path.dirname(out_gif)):
        os.makedirs(os.path.dirname(out_gif))

    if font_type == "arial.ttf":
        font = ImageFont.truetype(default_font, font_size)
    elif font_type == "alibaba.otf":
        default_font = os.path.join(pkg_dir, "data/fonts/alibaba.otf")
        font = ImageFont.truetype(default_font, font_size)
    else:
        try:
            font_list = system_fonts(show_full_path=True)
            font_names = [os.path.basename(f) for f in font_list]
            if (font_type in font_list) or (font_type in font_names):
                font = ImageFont.truetype(font_type, font_size)
            else:
                print(
                    "The specified font type could not be found on your system. Using the default font instead."
                )
                font = ImageFont.truetype(default_font, font_size)
        except Exception as e:
            print(e)
            font = ImageFont.truetype(default_font, font_size)

    color = check_color(font_color)
    progress_bar_color = check_color(progress_bar_color)

    try:
        image = Image.open(in_gif)
    except Exception as e:
        print("An error occurred while opening the gif.")
        print(e)
        return

    count = image.n_frames
    W, H = image.size
    progress_bar_widths = [i * 1.0 / count * W for i in range(1, count + 1)]
    progress_bar_shapes = [
        [(0, H - progress_bar_height), (x, H)] for x in progress_bar_widths
    ]

    if xy is None:
        # default text location is 5% width and 5% height of the image.
        xy = (int(0.05 * W), int(0.05 * H))
    elif (xy is not None) and (not isinstance(xy, tuple)) and (len(xy) == 2):
        print("xy must be a tuple, e.g., (10, 10), ('10%', '10%')")
        return
    elif all(isinstance(item, int) for item in xy) and (len(xy) == 2):
        x, y = xy
        if (x > 0) and (x < W) and (y > 0) and (y < H):
            pass
        else:
            print(
                f"xy is out of bounds. x must be within [0, {W}], and y must be within [0, {H}]"
            )
            return
    elif all(isinstance(item, str) for item in xy) and (len(xy) == 2):
        x, y = xy
        if ("%" in x) and ("%" in y):
            try:
                x = int(float(x.replace("%", "")) / 100.0 * W)
                y = int(float(y.replace("%", "")) / 100.0 * H)
                xy = (x, y)
            except Exception:
                raise Exception(
                    "The specified xy is invalid. It must be formatted like this ('10%', '10%')"
                )
    else:
        print(
            "The specified xy is invalid. It must be formatted like this: (10, 10) or ('10%', '10%')"
        )
        return

    if text_sequence is None:
        text = [str(x) for x in range(1, count + 1)]
    elif isinstance(text_sequence, int):
        text = [str(x) for x in range(text_sequence, text_sequence + count + 1)]
    elif isinstance(text_sequence, str):
        try:
            text_sequence = int(text_sequence)
            text = [str(x) for x in range(text_sequence, text_sequence + count + 1)]
        except Exception:
            text = [text_sequence] * count
    elif isinstance(text_sequence, list) and len(text_sequence) != count:
        print(
            f"The length of the text sequence must be equal to the number ({count}) of frames in the gif."
        )
        return
    else:
        text = [str(x) for x in text_sequence]

    try:
        frames = []
        # Loop over each frame in the animated image
        for index, frame in enumerate(ImageSequence.Iterator(image)):
            # Draw the text on the frame
            frame = frame.convert("RGB")
            draw = ImageDraw.Draw(frame)
            # w, h = draw.textsize(text[index])
            draw.text(xy, text[index], font=font, fill=color)
            if add_progress_bar:
                draw.rectangle(progress_bar_shapes[index], fill=progress_bar_color)
            del draw

            b = io.BytesIO()
            frame.save(b, format="GIF")
            frame = Image.open(b)

            frames.append(frame)
        # https://www.pythoninformer.com/python-libraries/pillow/creating-animated-gif/
        # Save the frames as a new image

        frames[0].save(
            out_gif,
            save_all=True,
            append_images=frames[1:],
            duration=duration,
            loop=loop,
            optimize=True,
        )
    except Exception as e:
        print(e)

adjust_longitude(in_fc)

Adjusts longitude if it is less than -180 or greater than 180.

Parameters:

Name	Type	Description	Default
in_fc	dict	The input dictionary containing coordinates.	required

Returns:

Name	Type	Description
dict		A dictionary containing the converted longitudes

Source code in geemap/common.py

def adjust_longitude(in_fc):
    """Adjusts longitude if it is less than -180 or greater than 180.

    Args:
        in_fc (dict): The input dictionary containing coordinates.

    Returns:
        dict: A dictionary containing the converted longitudes
    """
    try:
        keys = in_fc.keys()

        if "geometry" in keys:
            coordinates = in_fc["geometry"]["coordinates"]

            if in_fc["geometry"]["type"] == "Point":
                longitude = coordinates[0]
                if longitude < -180:
                    longitude = 360 + longitude
                elif longitude > 180:
                    longitude = longitude - 360
                in_fc["geometry"]["coordinates"][0] = longitude

            elif in_fc["geometry"]["type"] == "Polygon":
                for index1, item in enumerate(coordinates):
                    for index2, element in enumerate(item):
                        longitude = element[0]
                        if longitude < -180:
                            longitude = 360 + longitude
                        elif longitude > 180:
                            longitude = longitude - 360
                        in_fc["geometry"]["coordinates"][index1][index2][0] = longitude

            elif in_fc["geometry"]["type"] == "LineString":
                for index, element in enumerate(coordinates):
                    longitude = element[0]
                    if longitude < -180:
                        longitude = 360 + longitude
                    elif longitude > 180:
                        longitude = longitude - 360
                    in_fc["geometry"]["coordinates"][index][0] = longitude

        elif "type" in keys:
            coordinates = in_fc["coordinates"]

            if in_fc["type"] == "Point":
                longitude = coordinates[0]
                if longitude < -180:
                    longitude = 360 + longitude
                elif longitude > 180:
                    longitude = longitude - 360
                in_fc["coordinates"][0] = longitude

            elif in_fc["type"] == "Polygon":
                for index1, item in enumerate(coordinates):
                    for index2, element in enumerate(item):
                        longitude = element[0]
                        if longitude < -180:
                            longitude = 360 + longitude
                        elif longitude > 180:
                            longitude = longitude - 360
                        in_fc["coordinates"][index1][index2][0] = longitude

            elif in_fc["type"] == "LineString":
                for index, element in enumerate(coordinates):
                    longitude = element[0]
                    if longitude < -180:
                        longitude = 360 + longitude
                    elif longitude > 180:
                        longitude = longitude - 360
                    in_fc["coordinates"][index][0] = longitude

        return in_fc

    except Exception as e:
        print(e)
        return None

annual_NAIP(year, region)

Create an NAIP mosaic of a specified year for a specified region.

Parameters:

Name	Type	Description	Default
year	int	The specified year to create the mosaic for.	required
region	object	ee.Geometry	required

Returns:

Name	Type	Description
object		ee.Image

Source code in geemap/common.py

def annual_NAIP(year, region):
    """Create an NAIP mosaic of a specified year for a specified region.

    Args:
        year (int): The specified year to create the mosaic for.
        region (object): ee.Geometry

    Returns:
        object: ee.Image
    """

    start_date = ee.Date.fromYMD(year, 1, 1)
    end_date = ee.Date.fromYMD(year, 12, 31)
    collection = (
        ee.ImageCollection("USDA/NAIP/DOQQ")
        .filterDate(start_date, end_date)
        .filterBounds(region)
    )

    time_start = ee.Date(
        ee.List(collection.aggregate_array("system:time_start")).sort().get(0)
    )
    time_end = ee.Date(
        ee.List(collection.aggregate_array("system:time_end")).sort().get(-1)
    )
    image = ee.Image(collection.mosaic().clip(region))
    NDWI = ee.Image(image).normalizedDifference(["G", "N"]).select(["nd"], ["ndwi"])
    NDVI = ee.Image(image).normalizedDifference(["N", "R"]).select(["nd"], ["ndvi"])
    image = image.addBands(NDWI)
    image = image.addBands(NDVI)
    return image.set({"system:time_start": time_start, "system:time_end": time_end})

api_docs()

Open a browser and navigate to the geemap API documentation.

Source code in geemap/common.py

def api_docs():
    """Open a browser and navigate to the geemap API documentation."""
    import webbrowser

    url = "https://geemap.org/geemap"
    webbrowser.open_new_tab(url)

arc_active_map()

Get the active map in ArcGIS Pro.

Returns:

Type	Description
	arcpy.Map: The active map in ArcGIS Pro.

Source code in geemap/common.py

def arc_active_map():
    """Get the active map in ArcGIS Pro.

    Returns:
        arcpy.Map: The active map in ArcGIS Pro.
    """
    if is_arcpy():
        import arcpy

        aprx = arcpy.mp.ArcGISProject("CURRENT")
        m = aprx.activeMap
        return m
    else:
        return None

arc_active_view()

Get the active view in ArcGIS Pro.

Returns:

Type	Description
	arcpy.MapView: The active view in ArcGIS Pro.

Source code in geemap/common.py

def arc_active_view():
    """Get the active view in ArcGIS Pro.

    Returns:
        arcpy.MapView: The active view in ArcGIS Pro.
    """
    if is_arcpy():
        import arcpy

        aprx = arcpy.mp.ArcGISProject("CURRENT")
        view = aprx.activeView
        return view
    else:
        return None

arc_add_layer(url, name=None, shown=True, opacity=1.0)

Add a layer to the active map in ArcGIS Pro.

Parameters:

Name	Type	Description	Default
url	str	The URL of the tile layer to add.	required
name	str	The name of the layer. Defaults to None.	None
shown	bool	Whether the layer is shown. Defaults to True.	True
opacity	float	The opacity of the layer. Defaults to 1.0.	1.0

Source code in geemap/common.py

def arc_add_layer(url, name=None, shown=True, opacity=1.0):
    """Add a layer to the active map in ArcGIS Pro.

    Args:
        url (str): The URL of the tile layer to add.
        name (str, optional): The name of the layer. Defaults to None.
        shown (bool, optional): Whether the layer is shown. Defaults to True.
        opacity (float, optional): The opacity of the layer. Defaults to 1.0.
    """
    if is_arcpy():
        m = arc_active_map()
        if m is not None:
            m.addDataFromPath(url)
            if isinstance(name, str):
                layers = m.listLayers("Tiled service layer")
                if len(layers) > 0:
                    layer = layers[0]
                    layer.name = name
                    layer.visible = shown
                    layer.transparency = 100 - (opacity * 100)

arc_zoom_to_extent(xmin, ymin, xmax, ymax)

Zoom to an extent in ArcGIS Pro.

Parameters:

Name	Type	Description	Default
xmin	float	The minimum x value of the extent.	required
ymin	float	The minimum y value of the extent.	required
xmax	float	The maximum x value of the extent.	required
ymax	float	The maximum y value of the extent.	required

Source code in geemap/common.py

def arc_zoom_to_extent(xmin, ymin, xmax, ymax):
    """Zoom to an extent in ArcGIS Pro.

    Args:
        xmin (float): The minimum x value of the extent.
        ymin (float): The minimum y value of the extent.
        xmax (float): The maximum x value of the extent.
        ymax (float): The maximum y value of the extent.
    """
    if is_arcpy():
        import arcpy

        view = arc_active_view()
        if view is not None:
            view.camera.setExtent(
                arcpy.Extent(
                    xmin,
                    ymin,
                    xmax,
                    ymax,
                    spatial_reference=arcpy.SpatialReference(4326),
                )
            )

array_mean(arr)

Calculates the mean of an array along the given axis.

Parameters:

Name	Type	Description	Default
arr	object	Array to calculate mean.	required

Returns:

Name	Type	Description
object		ee.Number

Source code in geemap/common.py

def array_mean(arr):
    """Calculates the mean of an array along the given axis.

    Args:
        arr (object): Array to calculate mean.

    Returns:
        object: ee.Number
    """
    total = ee.Array(arr).accum(0).get([-1])
    size = arr.length()
    return ee.Number(total.divide(size))

array_sum(arr)

Accumulates elements of an array along the given axis.

Parameters:

Name	Type	Description	Default
arr	object	Array to accumulate.	required

Returns:

Name	Type	Description
object		ee.Number

Source code in geemap/common.py

def array_sum(arr):
    """Accumulates elements of an array along the given axis.

    Args:
        arr (object): Array to accumulate.

    Returns:
        object: ee.Number
    """
    return ee.Array(arr).accum(0).get([-1])

array_to_image(array, output=None, source=None, dtype=None, compress='deflate', transpose=True, cellsize=None, crs=None, driver='COG', **kwargs)

Save a NumPy array as a GeoTIFF using the projection information from an existing GeoTIFF file.

Parameters:

Name	Type	Description	Default
array	ndarray	The NumPy array to be saved as a GeoTIFF.	required
output	str	The path to the output image. If None, a temporary file will be created. Defaults to None.	None
source	str	The path to an existing GeoTIFF file with map projection information. Defaults to None.	None
dtype	dtype	The data type of the output array. Defaults to None.	None
compress	str	The compression method. Can be one of the following: "deflate", "lzw", "packbits", "jpeg". Defaults to "deflate".	'deflate'
transpose	bool	Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.	True
cellsize	float	The resolution of the output image in meters. Defaults to None.	None
crs	str	The CRS of the output image. Defaults to None.	None
driver	str	The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".	'COG'
**kwargs		Additional keyword arguments to be passed to the rasterio.open() function.	{}

Source code in geemap/common.py

def array_to_image(
    array,
    output: str = None,
    source: str = None,
    dtype: str = None,
    compress: str = "deflate",
    transpose: bool = True,
    cellsize: float = None,
    crs: str = None,
    driver: str = "COG",
    **kwargs,
) -> str:
    """Save a NumPy array as a GeoTIFF using the projection information from an existing GeoTIFF file.

    Args:
        array (np.ndarray): The NumPy array to be saved as a GeoTIFF.
        output (str): The path to the output image. If None, a temporary file will be created. Defaults to None.
        source (str, optional): The path to an existing GeoTIFF file with map projection information. Defaults to None.
        dtype (np.dtype, optional): The data type of the output array. Defaults to None.
        compress (str, optional): The compression method. Can be one of the following: "deflate", "lzw", "packbits", "jpeg". Defaults to "deflate".
        transpose (bool, optional): Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.
        cellsize (float, optional): The resolution of the output image in meters. Defaults to None.
        crs (str, optional): The CRS of the output image. Defaults to None.
        driver (str, optional): The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".
        **kwargs: Additional keyword arguments to be passed to the rasterio.open() function.
    """

    import numpy as np
    import rasterio
    import xarray as xr

    if output is None:
        return array_to_memory_file(
            array, source, dtype, compress, transpose, cellsize, crs, driver, **kwargs
        )

    if isinstance(array, xr.DataArray):
        coords = [coord for coord in array.coords]
        if coords[0] == "time":
            x_dim = coords[1]
            y_dim = coords[2]
            if array.dims[0] == "time":
                array = array.isel(time=0)

            array = array.rename({y_dim: "y", x_dim: "x"}).transpose("y", "x")
        array = array.values

    if array.ndim == 3 and transpose:
        array = np.transpose(array, (1, 2, 0))

    out_dir = os.path.dirname(os.path.abspath(output))
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if not output.endswith(".tif"):
        output += ".tif"

    if source is not None:
        with rasterio.open(source) as src:
            crs = src.crs
            transform = src.transform
            if compress is None:
                compress = src.compression
    else:
        if cellsize is None:
            raise ValueError("resolution must be provided if source is not provided")
        if crs is None:
            raise ValueError(
                "crs must be provided if source is not provided, such as EPSG:3857"
            )

        if "transform" not in kwargs:
            # Define the geotransformation parameters
            xmin, ymin, xmax, ymax = (
                0,
                0,
                cellsize * array.shape[1],
                cellsize * array.shape[0],
            )
            transform = rasterio.transform.from_bounds(
                xmin, ymin, xmax, ymax, array.shape[1], array.shape[0]
            )
        else:
            transform = kwargs["transform"]

    if dtype is None:
        # Determine the minimum and maximum values in the array
        min_value = np.min(array)
        max_value = np.max(array)
        # Determine the best dtype for the array
        if min_value >= 0 and max_value <= 1:
            dtype = np.float32
        elif min_value >= 0 and max_value <= 255:
            dtype = np.uint8
        elif min_value >= -128 and max_value <= 127:
            dtype = np.int8
        elif min_value >= 0 and max_value <= 65535:
            dtype = np.uint16
        elif min_value >= -32768 and max_value <= 32767:
            dtype = np.int16
        else:
            dtype = np.float64

    # Convert the array to the best dtype
    array = array.astype(dtype)

    # Define the GeoTIFF metadata
    metadata = {
        "driver": driver,
        "height": array.shape[0],
        "width": array.shape[1],
        "dtype": array.dtype,
        "crs": crs,
        "transform": transform,
    }

    if array.ndim == 2:
        metadata["count"] = 1
    elif array.ndim == 3:
        metadata["count"] = array.shape[2]
    if compress is not None:
        metadata["compress"] = compress

    metadata.update(**kwargs)

    # Create a new GeoTIFF file and write the array to it
    with rasterio.open(output, "w", **metadata) as dst:
        if array.ndim == 2:
            dst.write(array, 1)
        elif array.ndim == 3:
            for i in range(array.shape[2]):
                dst.write(array[:, :, i], i + 1)

array_to_memory_file(array, source=None, dtype=None, compress='deflate', transpose=True, cellsize=None, crs=None, transform=None, driver='COG', **kwargs)

Convert a NumPy array to a memory file.

Parameters:

Name	Type	Description	Default
array	ndarray	The input NumPy array.	required
source	str	Path to the source file to extract metadata from. Defaults to None.	None
dtype	str	The desired data type of the array. Defaults to None.	None
compress	str	The compression method for the output file. Defaults to "deflate".	'deflate'
transpose	bool	Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.	True
cellsize	float	The cell size of the array if source is not provided. Defaults to None.	None
crs	str	The coordinate reference system of the array if source is not provided. Defaults to None.	None
transform	tuple	The affine transformation matrix if source is not provided. Defaults to None.	None
driver	str	The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".	'COG'
**kwargs		Additional keyword arguments to be passed to the rasterio.open() function.	{}

Returns:

Type	Description
	rasterio.DatasetReader: The rasterio dataset reader object for the converted array.

Source code in geemap/common.py

def array_to_memory_file(
    array,
    source: str = None,
    dtype: str = None,
    compress: str = "deflate",
    transpose: bool = True,
    cellsize: float = None,
    crs: str = None,
    transform: tuple = None,
    driver="COG",
    **kwargs,
):
    """Convert a NumPy array to a memory file.

    Args:
        array (numpy.ndarray): The input NumPy array.
        source (str, optional): Path to the source file to extract metadata from. Defaults to None.
        dtype (str, optional): The desired data type of the array. Defaults to None.
        compress (str, optional): The compression method for the output file. Defaults to "deflate".
        transpose (bool, optional): Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.
        cellsize (float, optional): The cell size of the array if source is not provided. Defaults to None.
        crs (str, optional): The coordinate reference system of the array if source is not provided. Defaults to None.
        transform (tuple, optional): The affine transformation matrix if source is not provided. Defaults to None.
        driver (str, optional): The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".
        **kwargs: Additional keyword arguments to be passed to the rasterio.open() function.

    Returns:
        rasterio.DatasetReader: The rasterio dataset reader object for the converted array.
    """
    import rasterio
    import numpy as np
    import xarray as xr

    if isinstance(array, xr.DataArray):
        coords = [coord for coord in array.coords]
        if coords[0] == "time":
            x_dim = coords[1]
            y_dim = coords[2]
            if array.dims[0] == "time":
                array = array.isel(time=0)

            array = array.rename({y_dim: "y", x_dim: "x"}).transpose("y", "x")
        array = array.values

    if array.ndim == 3 and transpose:
        array = np.transpose(array, (1, 2, 0))

    if source is not None:
        with rasterio.open(source) as src:
            crs = src.crs
            transform = src.transform
            if compress is None:
                compress = src.compression
    else:
        if cellsize is None:
            raise ValueError("cellsize must be provided if source is not provided")
        if crs is None:
            raise ValueError(
                "crs must be provided if source is not provided, such as EPSG:3857"
            )

        if "transform" not in kwargs:
            # Define the geotransformation parameters
            xmin, ymin, xmax, ymax = (
                0,
                0,
                cellsize * array.shape[1],
                cellsize * array.shape[0],
            )
            # (west, south, east, north, width, height)
            transform = rasterio.transform.from_bounds(
                xmin, ymin, xmax, ymax, array.shape[1], array.shape[0]
            )
        else:
            transform = kwargs["transform"]

    if dtype is None:
        # Determine the minimum and maximum values in the array
        min_value = np.min(array)
        max_value = np.max(array)
        # Determine the best dtype for the array
        if min_value >= 0 and max_value <= 1:
            dtype = np.float32
        elif min_value >= 0 and max_value <= 255:
            dtype = np.uint8
        elif min_value >= -128 and max_value <= 127:
            dtype = np.int8
        elif min_value >= 0 and max_value <= 65535:
            dtype = np.uint16
        elif min_value >= -32768 and max_value <= 32767:
            dtype = np.int16
        else:
            dtype = np.float64

    # Convert the array to the best dtype
    array = array.astype(dtype)

    # Define the GeoTIFF metadata
    metadata = {
        "driver": driver,
        "height": array.shape[0],
        "width": array.shape[1],
        "dtype": array.dtype,
        "crs": crs,
        "transform": transform,
    }

    if array.ndim == 2:
        metadata["count"] = 1
    elif array.ndim == 3:
        metadata["count"] = array.shape[2]
    if compress is not None:
        metadata["compress"] = compress

    metadata.update(**kwargs)

    # Create a new memory file and write the array to it
    memory_file = rasterio.MemoryFile()
    dst = memory_file.open(**metadata)

    if array.ndim == 2:
        dst.write(array, 1)
    elif array.ndim == 3:
        for i in range(array.shape[2]):
            dst.write(array[:, :, i], i + 1)

    dst.close()

    # Read the dataset from memory
    dataset_reader = rasterio.open(dst.name, mode="r")

    return dataset_reader

bands_to_image_collection(img)

Converts all bands in an image to an image collection.

Parameters:

Name	Type	Description	Default
img	object	The image to convert.	required

Returns:

Name	Type	Description
object		ee.ImageCollection

Source code in geemap/common.py

def bands_to_image_collection(img):
    """Converts all bands in an image to an image collection.

    Args:
        img (object): The image to convert.

    Returns:
        object: ee.ImageCollection
    """
    collection = ee.ImageCollection(img.bandNames().map(lambda b: img.select([b])))
    return collection

bar_chart(data=None, x=None, y=None, color=None, descending=True, sort_column=None, max_rows=None, x_label=None, y_label=None, title=None, legend_title=None, width=None, height=500, layout_args={}, **kwargs)

Create a bar chart with plotly.express,

Parameters:

Name	Type	Description	Default
data		DataFrame | array-like | dict | str (local file path or HTTP URL) This argument needs to be passed for column names (and not keyword names) to be used. Array-like and dict are transformed internally to a pandas DataFrame. Optional: if missing, a DataFrame gets constructed under the hood using the other arguments.	None
x		str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to position marks along the x axis in cartesian coordinates. Either x or y can optionally be a list of column references or array_likes, in which case the data will be treated as if it were 'wide' rather than 'long'.	None
y		str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to position marks along the y axis in cartesian coordinates. Either x or y can optionally be a list of column references or array_likes, in which case the data will be treated as if it were 'wide' rather than 'long'.	None
color		str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign color to marks.	None
descending	bool	Whether to sort the data in descending order. Defaults to True.	True
sort_column	str	The column to sort the data. Defaults to None.	None
max_rows	int	Maximum number of rows to display. Defaults to None.	None
x_label	str	Label for the x axis. Defaults to None.	None
y_label	str	Label for the y axis. Defaults to None.	None
title	str	Title for the plot. Defaults to None.	None
legend_title	str	Title for the legend. Defaults to None.	None
width	int	Width of the plot in pixels. Defaults to None.	None
height	int	Height of the plot in pixels. Defaults to 500.	500
layout_args	dict	Layout arguments for the plot to be passed to fig.update_layout(), such as {'title':'Plot Title', 'title_x':0.5}. Defaults to None.	{}
**kwargs		Any additional arguments to pass to plotly.express.bar(), such as: pattern_shape: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign pattern shapes to marks. facet_row: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign marks to facetted subplots in the vertical direction. facet_col: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign marks to facetted subplots in the horizontal direction. facet_col_wrap: int Maximum number of facet columns. Wraps the column variable at this width, so that the column facets span multiple rows. Ignored if 0, and forced to 0 if facet_row or a marginal is set. facet_row_spacing: float between 0 and 1 Spacing between facet rows, in paper units. Default is 0.03 or 0.0.7 when facet_col_wrap is used. facet_col_spacing: float between 0 and 1 Spacing between facet columns, in paper units Default is 0.02. hover_name: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like appear in bold in the hover tooltip. hover_data: list of str or int, or Series or array-like, or dict Either a list of names of columns in data_frame, or pandas Series, or array_like objects or a dict with column names as keys, with values True (for default formatting) False (in order to remove this column from hover information), or a formatting string, for example ':.3f' or '|%a' or list-like data to appear in the hover tooltip or tuples with a bool or formatting string as first element, and list-like data to appear in hover as second element Values from these columns appear as extra data in the hover tooltip. custom_data: list of str or int, or Series or array-like Either names of columns in data_frame, or pandas Series, or array_like objects Values from these columns are extra data, to be used in widgets or Dash callbacks for example. This data is not user-visible but is included in events emitted by the figure (lasso selection etc.) text: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like appear in the figure as text labels. base: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to position the base of the bar. error_x: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size x-axis error bars. If error_x_minus is None, error bars will be symmetrical, otherwise error_x is used for the positive direction only. error_x_minus: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size x-axis error bars in the negative direction. Ignored if error_x is None. error_y: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size y-axis error bars. If error_y_minus is None, error bars will be symmetrical, otherwise error_y is used for the positive direction only. error_y_minus: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size y-axis error bars in the negative direction. Ignored if error_y is None. animation_frame: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign marks to animation frames. animation_group: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to provide object-constancy across animation frames: rows with matching animation_groups will be treated as if they describe the same object in each frame. category_orders: dict with str keys and list of str values (default {}) By default, in Python 3.6+, the order of categorical values in axes, legends and facets depends on the order in which these values are first encountered in data_frame (and no order is guaranteed by default in Python below 3.6). This parameter is used to force a specific ordering of values per column. The keys of this dict should correspond to column names, and the values should be lists of strings corresponding to the specific display order desired. labels: dict with str keys and str values (default {}) By default, column names are used in the figure for axis titles, legend entries and hovers. This parameter allows this to be overridden. The keys of this dict should correspond to column names, and the values should correspond to the desired label to be displayed. color_discrete_sequence: list of str Strings should define valid CSS-colors. When color is set and the values in the corresponding column are not numeric, values in that column are assigned colors by cycling through color_discrete_sequence in the order described in category_orders, unless the value of color is a key in color_discrete_map. Various useful color sequences are available in the plotly.express.colors submodules, specifically plotly.express.colors.qualitative. color_discrete_map: dict with str keys and str values (default {}) String values should define valid CSS-colors Used to override color_discrete_sequence to assign a specific colors to marks corresponding with specific values. Keys in color_discrete_map should be values in the column denoted by color. Alternatively, if the values of color are valid colors, the string 'identity' may be passed to cause them to be used directly. color_continuous_scale: list of str Strings should define valid CSS-colors This list is used to build a continuous color scale when the column denoted by color contains numeric data. Various useful color scales are available in the plotly.express.colors submodules, specifically plotly.express.colors.sequential, plotly.express.colors.diverging and plotly.express.colors.cyclical. pattern_shape_sequence: list of str Strings should define valid plotly.js patterns-shapes. When pattern_shape is set, values in that column are assigned patterns- shapes by cycling through pattern_shape_sequence in the order described in category_orders, unless the value of pattern_shape is a key in pattern_shape_map. pattern_shape_map: dict with str keys and str values (default {}) Strings values define plotly.js patterns-shapes. Used to override pattern_shape_sequences to assign a specific patterns-shapes to lines corresponding with specific values. Keys in pattern_shape_map should be values in the column denoted by pattern_shape. Alternatively, if the values of pattern_shape are valid patterns-shapes names, the string 'identity' may be passed to cause them to be used directly. range_color: list of two numbers If provided, overrides auto-scaling on the continuous color scale. color_continuous_midpoint: number (default None) If set, computes the bounds of the continuous color scale to have the desired midpoint. Setting this value is recommended when using plotly.express.colors.diverging color scales as the inputs to color_continuous_scale. opacity: float Value between 0 and 1. Sets the opacity for markers. orientation: str, one of 'h' for horizontal or 'v' for vertical. (default 'v' if x and y are provided and both continuous or both categorical, otherwise 'v'('h') if x(y) is categorical and y(x) is continuous, otherwise 'v'('h') if only x(y) is provided) barmode: str (default 'relative') One of 'group', 'overlay' or 'relative' In 'relative' mode, bars are stacked above zero for positive values and below zero for negative values. In 'overlay' mode, bars are drawn on top of one another. In 'group' mode, bars are placed beside each other. log_x: boolean (default False) If True, the x-axis is log-scaled in cartesian coordinates. log_y: boolean (default False) If True, the y-axis is log-scaled in cartesian coordinates. range_x: list of two numbers If provided, overrides auto-scaling on the x-axis in cartesian coordinates. range_y: list of two numbers If provided, overrides auto-scaling on the y-axis in cartesian coordinates. text_auto: bool or string (default False) If True or a string, the x or y or z values will be displayed as text, depending on the orientation A string like '.2f' will be interpreted as a texttemplate numeric formatting directive. template: str or dict or plotly.graph_objects.layout.Template instance The figure template name (must be a key in plotly.io.templates) or definition.	{}

Returns:

Type	Description
	plotly.graph_objs._figure.Figure: A plotly figure object.

Source code in geemap/plot.py

def bar_chart(
    data=None,
    x=None,
    y=None,
    color=None,
    descending=True,
    sort_column=None,
    max_rows=None,
    x_label=None,
    y_label=None,
    title=None,
    legend_title=None,
    width=None,
    height=500,
    layout_args={},
    **kwargs,
):
    """Create a bar chart with plotly.express,

    Args:
        data: DataFrame | array-like | dict | str (local file path or HTTP URL)
            This argument needs to be passed for column names (and not keyword
            names) to be used. Array-like and dict are transformed internally to a
            pandas DataFrame. Optional: if missing, a DataFrame gets constructed
            under the hood using the other arguments.
        x: str or int or Series or array-like
            Either a name of a column in `data_frame`, or a pandas Series or
            array_like object. Values from this column or array_like are used to
            position marks along the x axis in cartesian coordinates. Either `x` or
            `y` can optionally be a list of column references or array_likes,  in
            which case the data will be treated as if it were 'wide' rather than
            'long'.
        y: str or int or Series or array-like
            Either a name of a column in `data_frame`, or a pandas Series or
            array_like object. Values from this column or array_like are used to
            position marks along the y axis in cartesian coordinates. Either `x` or
            `y` can optionally be a list of column references or array_likes,  in
            which case the data will be treated as if it were 'wide' rather than
            'long'.
        color: str or int or Series or array-like
            Either a name of a column in `data_frame`, or a pandas Series or
            array_like object. Values from this column or array_like are used to
            assign color to marks.
        descending (bool, optional): Whether to sort the data in descending order. Defaults to True.
        sort_column (str, optional): The column to sort the data. Defaults to None.
        max_rows (int, optional): Maximum number of rows to display. Defaults to None.
        x_label (str, optional): Label for the x axis. Defaults to None.
        y_label (str, optional): Label for the y axis. Defaults to None.
        title (str, optional): Title for the plot. Defaults to None.
        legend_title (str, optional): Title for the legend. Defaults to None.
        width (int, optional): Width of the plot in pixels. Defaults to None.
        height (int, optional): Height of the plot in pixels. Defaults to 500.
        layout_args (dict, optional): Layout arguments for the plot to be passed to fig.update_layout(),
            such as {'title':'Plot Title', 'title_x':0.5}. Defaults to None.
        **kwargs: Any additional arguments to pass to plotly.express.bar(), such as:

            pattern_shape: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign pattern shapes to marks.
            facet_row: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign marks to facetted subplots in the vertical direction.
            facet_col: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign marks to facetted subplots in the horizontal direction.
            facet_col_wrap: int
                Maximum number of facet columns. Wraps the column variable at this
                width, so that the column facets span multiple rows. Ignored if 0, and
                forced to 0 if `facet_row` or a `marginal` is set.
            facet_row_spacing: float between 0 and 1
                Spacing between facet rows, in paper units. Default is 0.03 or 0.0.7
                when facet_col_wrap is used.
            facet_col_spacing: float between 0 and 1
                Spacing between facet columns, in paper units Default is 0.02.
            hover_name: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like appear in bold
                in the hover tooltip.
            hover_data: list of str or int, or Series or array-like, or dict
                Either a list of names of columns in `data_frame`, or pandas Series, or
                array_like objects or a dict with column names as keys, with values
                True (for default formatting) False (in order to remove this column
                from hover information), or a formatting string, for example ':.3f' or
                '|%a' or list-like data to appear in the hover tooltip or tuples with a
                bool or formatting string as first element, and list-like data to
                appear in hover as second element Values from these columns appear as
                extra data in the hover tooltip.
            custom_data: list of str or int, or Series or array-like
                Either names of columns in `data_frame`, or pandas Series, or
                array_like objects Values from these columns are extra data, to be used
                in widgets or Dash callbacks for example. This data is not user-visible
                but is included in events emitted by the figure (lasso selection etc.)
            text: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like appear in the
                figure as text labels.
            base: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                position the base of the bar.
            error_x: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size x-axis error bars. If `error_x_minus` is `None`, error bars will
                be symmetrical, otherwise `error_x` is used for the positive direction
                only.
            error_x_minus: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size x-axis error bars in the negative direction. Ignored if `error_x`
                is `None`.
            error_y: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size y-axis error bars. If `error_y_minus` is `None`, error bars will
                be symmetrical, otherwise `error_y` is used for the positive direction
                only.
            error_y_minus: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size y-axis error bars in the negative direction. Ignored if `error_y`
                is `None`.
            animation_frame: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign marks to animation frames.
            animation_group: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                provide object-constancy across animation frames: rows with matching
                `animation_group`s will be treated as if they describe the same object
                in each frame.
            category_orders: dict with str keys and list of str values (default `{}`)
                By default, in Python 3.6+, the order of categorical values in axes,
                legends and facets depends on the order in which these values are first
                encountered in `data_frame` (and no order is guaranteed by default in
                Python below 3.6). This parameter is used to force a specific ordering
                of values per column. The keys of this dict should correspond to column
                names, and the values should be lists of strings corresponding to the
                specific display order desired.
            labels: dict with str keys and str values (default `{}`)
                By default, column names are used in the figure for axis titles, legend
                entries and hovers. This parameter allows this to be overridden. The
                keys of this dict should correspond to column names, and the values
                should correspond to the desired label to be displayed.
            color_discrete_sequence: list of str
                Strings should define valid CSS-colors. When `color` is set and the
                values in the corresponding column are not numeric, values in that
                column are assigned colors by cycling through `color_discrete_sequence`
                in the order described in `category_orders`, unless the value of
                `color` is a key in `color_discrete_map`. Various useful color
                sequences are available in the `plotly.express.colors` submodules,
                specifically `plotly.express.colors.qualitative`.
            color_discrete_map: dict with str keys and str values (default `{}`)
                String values should define valid CSS-colors Used to override
                `color_discrete_sequence` to assign a specific colors to marks
                corresponding with specific values. Keys in `color_discrete_map` should
                be values in the column denoted by `color`. Alternatively, if the
                values of `color` are valid colors, the string `'identity'` may be
                passed to cause them to be used directly.
            color_continuous_scale: list of str
                Strings should define valid CSS-colors This list is used to build a
                continuous color scale when the column denoted by `color` contains
                numeric data. Various useful color scales are available in the
                `plotly.express.colors` submodules, specifically
                `plotly.express.colors.sequential`, `plotly.express.colors.diverging`
                and `plotly.express.colors.cyclical`.
            pattern_shape_sequence: list of str
                Strings should define valid plotly.js patterns-shapes. When
                `pattern_shape` is set, values in that column are assigned patterns-
                shapes by cycling through `pattern_shape_sequence` in the order
                described in `category_orders`, unless the value of `pattern_shape` is
                a key in `pattern_shape_map`.
            pattern_shape_map: dict with str keys and str values (default `{}`)
                Strings values define plotly.js patterns-shapes. Used to override
                `pattern_shape_sequences` to assign a specific patterns-shapes to lines
                corresponding with specific values. Keys in `pattern_shape_map` should
                be values in the column denoted by `pattern_shape`. Alternatively, if
                the values of `pattern_shape` are valid patterns-shapes names, the
                string `'identity'` may be passed to cause them to be used directly.
            range_color: list of two numbers
                If provided, overrides auto-scaling on the continuous color scale.
            color_continuous_midpoint: number (default `None`)
                If set, computes the bounds of the continuous color scale to have the
                desired midpoint. Setting this value is recommended when using
                `plotly.express.colors.diverging` color scales as the inputs to
                `color_continuous_scale`.
            opacity: float
                Value between 0 and 1. Sets the opacity for markers.
            orientation: str, one of `'h'` for horizontal or `'v'` for vertical.
                (default `'v'` if `x` and `y` are provided and both continuous or both
                categorical,  otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and
                `y`(`x`) is continuous,  otherwise `'v'`(`'h'`) if only `x`(`y`) is
                provided)
            barmode: str (default `'relative'`)
                One of `'group'`, `'overlay'` or `'relative'` In `'relative'` mode,
                bars are stacked above zero for positive values and below zero for
                negative values. In `'overlay'` mode, bars are drawn on top of one
                another. In `'group'` mode, bars are placed beside each other.
            log_x: boolean (default `False`)
                If `True`, the x-axis is log-scaled in cartesian coordinates.
            log_y: boolean (default `False`)
                If `True`, the y-axis is log-scaled in cartesian coordinates.
            range_x: list of two numbers
                If provided, overrides auto-scaling on the x-axis in cartesian
                coordinates.
            range_y: list of two numbers
                If provided, overrides auto-scaling on the y-axis in cartesian
                coordinates.
            text_auto: bool or string (default `False`)
                If `True` or a string, the x or y or z values will be displayed as
                text, depending on the orientation A string like `'.2f'` will be
                interpreted as a `texttemplate` numeric formatting directive.
            template: str or dict or plotly.graph_objects.layout.Template instance
                The figure template name (must be a key in plotly.io.templates) or
                definition.


    Returns:
        plotly.graph_objs._figure.Figure: A plotly figure object.
    """

    if isinstance(data, str):
        if data.startswith("http"):
            data = github_raw_url(data)
            data = get_direct_url(data)

        try:
            data = pd.read_csv(data)
        except Exception as e:
            raise ValueError(f"Could not read data from {data}. {e}")

    if not isinstance(data, pd.DataFrame):
        raise ValueError(
            "data must be a pandas DataFrame, a string or an ee.FeatureCollection."
        )

    if descending is not None:
        if sort_column is None:
            if isinstance(y, str):
                sort_column = y
            elif isinstance(y, list):
                sort_column = y[0]
        data.sort_values([sort_column, x], ascending=not (descending), inplace=True)
        if "barmode" not in kwargs:
            kwargs["barmode"] = "group"

    if isinstance(max_rows, int):
        data = data.head(max_rows)

    if "labels" in kwargs:
        labels = kwargs["labels"]
        kwargs.pop("labels")
    else:
        labels = {}

    if x_label is not None:
        labels[x] = x_label
    if y_label is not None:
        if isinstance(y, str):
            labels[y] = y_label
        elif isinstance(y, list):
            labels[y[0]] = y_label

    if isinstance(legend_title, str):
        if "legend" not in layout_args:
            layout_args["legend"] = {}
        layout_args["legend"]["title"] = legend_title

    try:
        fig = px.bar(
            data,
            x=x,
            y=y,
            color=color,
            labels=labels,
            title=title,
            width=width,
            height=height,
            **kwargs,
        )

        if isinstance(layout_args, dict):
            fig.update_layout(**layout_args)

        return fig
    except Exception as e:
        raise ValueError(f"Could not create bar plot. {e}")

bbox_coords(geometry, decimals=4)

Get the bounding box coordinates of a geometry.

Parameters:

Name	Type	Description	Default
geometry	Geometry | FeatureCollection	The input geometry.	required
decimals	int	The number of decimals to round to. Defaults to 4.	4

Returns:

Name	Type	Description
list		The bounding box coordinates in the form [west, south, east, north].

Source code in geemap/common.py

def bbox_coords(geometry, decimals=4):
    """Get the bounding box coordinates of a geometry.

    Args:
        geometry (ee.Geometry | ee.FeatureCollection): The input geometry.
        decimals (int, optional): The number of decimals to round to. Defaults to 4.

    Returns:
        list: The bounding box coordinates in the form [west, south, east, north].
    """
    if isinstance(geometry, ee.FeatureCollection):
        geometry = geometry.geometry()

    if geometry is not None:
        if not isinstance(geometry, ee.Geometry):
            raise ValueError("geometry must be an ee.Geometry.")

        coords = geometry.bounds().coordinates().getInfo()[0]
        x = [p[0] for p in coords]
        y = [p[1] for p in coords]
        west = round(min(x), decimals)
        east = round(max(x), decimals)
        south = round(min(y), decimals)
        north = round(max(y), decimals)
        return [west, south, east, north]
    else:
        return None

bbox_to_gdf(bbox, crs='EPSG:4326')

Converts a bounding box to a GeoDataFrame.

Parameters:

Name	Type	Description	Default
bbox	tuple	A bounding box in the form of a tuple (minx, miny, maxx, maxy).	required
crs	str	The coordinate reference system of the bounding box to convert to. Defaults to "EPSG:4326".	'EPSG:4326'

Returns:

Type	Description
	geopandas.GeoDataFrame: A GeoDataFrame containing the bounding box.

Source code in geemap/common.py

def bbox_to_gdf(bbox, crs="EPSG:4326"):
    """Converts a bounding box to a GeoDataFrame.

    Args:
        bbox (tuple): A bounding box in the form of a tuple (minx, miny, maxx, maxy).
        crs (str, optional): The coordinate reference system of the bounding box to convert to. Defaults to "EPSG:4326".

    Returns:
        geopandas.GeoDataFrame: A GeoDataFrame containing the bounding box.
    """
    check_package(name="geopandas", URL="https://geopandas.org")
    from shapely.geometry import box
    import geopandas as gpd

    minx, miny, maxx, maxy = bbox
    geometry = box(minx, miny, maxx, maxy)
    d = {"geometry": [geometry]}
    gdf = gpd.GeoDataFrame(d, crs="EPSG:4326")
    gdf.to_crs(crs=crs, inplace=True)
    return gdf

bbox_to_geojson(bounds)

Convert coordinates of a bounding box to a geojson.

Parameters:

Name	Type	Description	Default
bounds	list	A list of coordinates representing [left, bottom, right, top].	required

Returns:

Name	Type	Description
dict		A geojson feature.

Source code in geemap/common.py

def bbox_to_geojson(bounds):
    """Convert coordinates of a bounding box to a geojson.

    Args:
        bounds (list): A list of coordinates representing [left, bottom, right, top].

    Returns:
        dict: A geojson feature.
    """
    return {
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [bounds[0], bounds[3]],
                    [bounds[0], bounds[1]],
                    [bounds[2], bounds[1]],
                    [bounds[2], bounds[3]],
                    [bounds[0], bounds[3]],
                ]
            ],
        },
        "type": "Feature",
    }

blend(top_layer, bottom_layer=None, top_vis=None, bottom_vis=None, hillshade=True, expression='a*b', **kwargs)

Create a blended image that is a combination of two images, e.g., DEM and hillshade. This function was inspired by Jesse Anderson. See https://github.com/jessjaco/gee-blend.

Parameters:

Name	Type	Description	Default
top_layer	Image	The top layer image, e.g., ee.Image("CGIAR/SRTM90_V4")	required
bottom_layer	Image	The bottom layer image. If not specified, it will use the top layer image.	None
top_vis	dict	The top layer image vis parameters as a dictionary. Defaults to None.	None
bottom_vis	dict	The bottom layer image vis parameters as a dictionary. Defaults to None.	None
hillshade	bool	Flag to use hillshade. Defaults to True.	True
expression	str	The expression to use for the blend. Defaults to 'a*b'.	'a*b'

Returns:

Type	Description
	ee.Image: The blended image.

Source code in geemap/common.py

def blend(
    top_layer,
    bottom_layer=None,
    top_vis=None,
    bottom_vis=None,
    hillshade=True,
    expression="a*b",
    **kwargs,
):
    """Create a blended image that is a combination of two images, e.g., DEM and hillshade. This function was inspired by Jesse Anderson. See https://github.com/jessjaco/gee-blend.

    Args:
        top_layer (ee.Image): The top layer image, e.g., ee.Image("CGIAR/SRTM90_V4")
        bottom_layer (ee.Image, optional): The bottom layer image. If not specified, it will use the top layer image.
        top_vis (dict, optional): The top layer image vis parameters as a dictionary. Defaults to None.
        bottom_vis (dict, optional): The bottom layer image vis parameters as a dictionary. Defaults to None.
        hillshade (bool, optional): Flag to use hillshade. Defaults to True.
        expression (str, optional): The expression to use for the blend. Defaults to 'a*b'.

    Returns:
        ee.Image: The blended image.
    """
    from box import Box

    if not isinstance(top_layer, ee.Image):
        raise ValueError("top_layer must be an ee.Image.")

    if bottom_layer is None:
        bottom_layer = top_layer

    if not isinstance(bottom_layer, ee.Image):
        raise ValueError("bottom_layer must be an ee.Image.")

    if top_vis is not None:
        if not isinstance(top_vis, dict):
            raise ValueError("top_vis must be a dictionary.")
        elif "palette" in top_vis and isinstance(top_vis["palette"], Box):
            try:
                top_vis["palette"] = top_vis["palette"]["default"]
            except Exception as e:
                print("The provided palette is invalid.")
                raise Exception(e)

    if bottom_vis is not None:
        if not isinstance(bottom_vis, dict):
            raise ValueError("top_vis must be a dictionary.")
        elif "palette" in bottom_vis and isinstance(bottom_vis["palette"], Box):
            try:
                bottom_vis["palette"] = bottom_vis["palette"]["default"]
            except Exception as e:
                print("The provided palette is invalid.")
                raise Exception(e)

    if top_vis is None:
        top_bands = top_layer.bandNames().getInfo()
        top_vis = {"bands": top_bands}
        if hillshade:
            top_vis["palette"] = ["006633", "E5FFCC", "662A00", "D8D8D8", "F5F5F5"]
            top_vis["min"] = 0
            top_vis["max"] = 6000

    if bottom_vis is None:
        bottom_bands = bottom_layer.bandNames().getInfo()
        bottom_vis = {"bands": bottom_bands}
        if hillshade:
            bottom_vis["bands"] = ["hillshade"]

    top = top_layer.visualize(**top_vis).divide(255)

    if hillshade:
        bottom = ee.Terrain.hillshade(bottom_layer).visualize(**bottom_vis).divide(255)
    else:
        bottom = bottom_layer.visualize(**bottom_vis).divide(255)

    if "a" not in expression or ("b" not in expression):
        raise ValueError("expression must contain 'a' and 'b'.")

    result = ee.Image().expression(expression, {"a": top, "b": bottom})
    return result

bounds_to_xy_range(bounds)

Convert bounds to x and y range to be used as input to bokeh map.

Parameters:

Name	Type	Description	Default
bounds	list	A list of bounds in the form [(south, west), (north, east)] or [xmin, ymin, xmax, ymax].	required

Returns:

Name	Type	Description
tuple		A tuple of (x_range, y_range).

Source code in geemap/common.py

def bounds_to_xy_range(bounds):
    """Convert bounds to x and y range to be used as input to bokeh map.

    Args:
        bounds (list): A list of bounds in the form [(south, west), (north, east)] or [xmin, ymin, xmax, ymax].

    Returns:
        tuple: A tuple of (x_range, y_range).
    """

    if isinstance(bounds, tuple):
        bounds = list(bounds)
    elif not isinstance(bounds, list):
        raise TypeError("bounds must be a list")

    if len(bounds) == 4:
        west, south, east, north = bounds
    elif len(bounds) == 2:
        south, west = bounds[0]
        north, east = bounds[1]

    xmin, ymin = lnglat_to_meters(west, south)
    xmax, ymax = lnglat_to_meters(east, north)
    x_range = (xmin, xmax)
    y_range = (ymin, ymax)
    return x_range, y_range

build_api_tree(api_dict, output_widget, layout_width='100%')

Builds an Earth Engine API tree view.

Parameters:

Name	Type	Description	Default
api_dict	dict	The dictionary containing information about each Earth Engine API function.	required
output_widget	object	An Output widget.	required
layout_width	str	The percentage width of the widget. Defaults to '100%'.	'100%'

Returns:

Name	Type	Description
tuple		Returns a tuple containing two items: a tree Output widget and a tree dictionary.

Source code in geemap/common.py

def build_api_tree(api_dict, output_widget, layout_width="100%"):
    """Builds an Earth Engine API tree view.

    Args:
        api_dict (dict): The dictionary containing information about each Earth Engine API function.
        output_widget (object): An Output widget.
        layout_width (str, optional): The percentage width of the widget. Defaults to '100%'.

    Returns:
        tuple: Returns a tuple containing two items: a tree Output widget and a tree dictionary.
    """

    warnings.filterwarnings("ignore")

    tree = Tree()
    tree_dict = {}

    names = api_dict.keys()

    def handle_click(event):
        if event["new"]:
            name = event["owner"].name
            values = api_dict[name]

            with output_widget:
                output_widget.outputs = ()
                html_widget = widgets.HTML(value=values["html"])
                display(html_widget)

    for name in names:
        func_list = ee_function_tree(name)
        first = func_list[0]

        if first not in tree_dict.keys():
            tree_dict[first] = Node(first)
            tree_dict[first].opened = False
            tree.add_node(tree_dict[first])

        for index, func in enumerate(func_list):
            if index > 0:
                if func not in tree_dict.keys():
                    node = tree_dict[func_list[index - 1]]
                    node.opened = False
                    tree_dict[func] = Node(func)
                    node.add_node(tree_dict[func])

                    if index == len(func_list) - 1:
                        node = tree_dict[func_list[index]]
                        node.icon = "file"
                        node.observe(handle_click, "selected")

    return tree, tree_dict

build_computed_object_tree(ee_object, layer_name='', opened=False)

Return a tree structure representing an EE object.

The source code was adapted from https://github.com/google/earthengine-jupyter. Credits to Tyler Erickson.

Parameters:

Name	Type	Description	Default
ee_object	Union[FeatureCollection, Image, Geometry, Feature]	The Earth Engine object.	required
layer_name	str	The name of the layer. Defaults to "".	''
opened	bool	Whether to expand the tree. Defaults to False.	False

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: The node representing the Earth Engine object information.

Source code in geemap/coreutils.py

def build_computed_object_tree(
    ee_object: Union[ee.FeatureCollection, ee.Image, ee.Geometry, ee.Feature],
    layer_name: str = "",
    opened: bool = False,
) -> dict[str, Any]:
    """Return a tree structure representing an EE object.

    The source code was adapted from https://github.com/google/earthengine-jupyter.
    Credits to Tyler Erickson.

    Args:
        ee_object (Union[ee.FeatureCollection, ee.Image, ee.Geometry, ee.Feature]):
            The Earth Engine object.
        layer_name (str, optional): The name of the layer. Defaults to "".
        opened (bool, optional): Whether to expand the tree. Defaults to False.

    Returns:
        dict[str, Any]: The node representing the Earth Engine object information.
    """

    # Convert EE object props to dicts. It's easier to traverse the nested structure.
    if isinstance(ee_object, ee.FeatureCollection):
        ee_object = ee_object.map(lambda f: ee.Feature(None, f.toDictionary()))

    layer_info = ee_object.getInfo()
    if not layer_info:
        return {}

    # Strip geometries because they're slow to render as text.
    if "geometry" in layer_info:
        layer_info.pop("geometry")

    # Sort the keys in layer_info and the nested properties.
    if properties := layer_info.get("properties"):
        layer_info["properties"] = dict(sorted(properties.items()))
    ordering_list = ["type", "id", "version", "bands", "properties"]
    layer_info = _order_items(layer_info, ordering_list)

    ee_type = layer_info.get("type", ee_object.__class__.__name__)

    band_info = ""
    if bands := layer_info.get("bands"):
        band_info = f" ({len(bands)} bands)"
    if layer_name:
        layer_name = f"{layer_name}: "

    return new_tree_node(
        f"{layer_name}{ee_type}{band_info}",
        _generate_tree(layer_info, opened),
        expanded=opened,
    )

build_repo_tree(out_dir=None, name='gee_repos')

Builds a repo tree for GEE account.

Parameters:

Name	Type	Description	Default
out_dir	str	The output directory for the repos. Defaults to None.	None
name	str	The output name for the repo directory. Defaults to 'gee_repos'.	'gee_repos'

Returns:

Name	Type	Description
tuple		Returns a tuple containing a tree widget, an output widget, and a tree dictionary containing nodes.

Source code in geemap/common.py

def build_repo_tree(out_dir=None, name="gee_repos"):
    """Builds a repo tree for GEE account.

    Args:
        out_dir (str): The output directory for the repos. Defaults to None.
        name (str, optional): The output name for the repo directory. Defaults to 'gee_repos'.

    Returns:
        tuple: Returns a tuple containing a tree widget, an output widget, and a tree dictionary containing nodes.
    """

    warnings.filterwarnings("ignore")

    if out_dir is None:
        out_dir = os.path.join(os.path.expanduser("~"))

    repo_dir = os.path.join(out_dir, name)
    if not os.path.exists(repo_dir):
        os.makedirs(repo_dir)

    URLs = {
        # 'Owner': 'https://earthengine.googlesource.com/{ee_user_id()}/default',
        "Writer": "",
        "Reader": "https://github.com/gee-community/geemap",
        "Examples": "https://github.com/giswqs/earthengine-py-examples",
        "Archive": "https://earthengine.googlesource.com/EGU2017-EE101",
    }

    user_id = ee_user_id()
    if user_id is not None:
        URLs["Owner"] = f"https://earthengine.googlesource.com/{ee_user_id()}/default"

    path_widget = widgets.Text(placeholder="Enter the link to a Git repository here...")
    path_widget.layout.width = "475px"
    clone_widget = widgets.Button(
        description="Clone",
        button_style="primary",
        tooltip="Clone the repository to folder.",
    )
    info_widget = widgets.HBox()

    groups = ["Owner", "Writer", "Reader", "Examples", "Archive"]
    for group in groups:
        group_dir = os.path.join(repo_dir, group)
        if not os.path.exists(group_dir):
            os.makedirs(group_dir)

    example_dir = os.path.join(repo_dir, "Examples/earthengine-py-examples")
    if not os.path.exists(example_dir):
        clone_github_repo(URLs["Examples"], out_dir=example_dir)

    left_widget, right_widget, tree_dict = file_browser(
        in_dir=repo_dir,
        add_root_node=False,
        search_description="Filter scripts...",
        use_import=True,
        return_sep_widgets=True,
    )
    info_widget.children = [right_widget]

    def handle_folder_click(event):
        if event["new"]:
            url = ""
            selected = event["owner"]
            if selected.name in URLs.keys():
                url = URLs[selected.name]

            path_widget.value = url
            clone_widget.disabled = False
            info_widget.children = [path_widget, clone_widget]
        else:
            info_widget.children = [right_widget]

    for group in groups:
        dirname = os.path.join(repo_dir, group)
        node = tree_dict[dirname]
        node.observe(handle_folder_click, "selected")

    def handle_clone_click(b):
        url = path_widget.value
        default_dir = os.path.join(repo_dir, "Examples")
        if url == "":
            path_widget.value = "Please enter a valid URL to the repository."
        else:
            for group in groups:
                key = os.path.join(repo_dir, group)
                node = tree_dict[key]
                if node.selected:
                    default_dir = key
            try:
                path_widget.value = "Cloning..."
                clone_dir = os.path.join(default_dir, os.path.basename(url))
                if url.find("github.com") != -1:
                    clone_github_repo(url, out_dir=clone_dir)
                elif url.find("googlesource") != -1:
                    clone_google_repo(url, out_dir=clone_dir)
                path_widget.value = "Cloned to {}".format(clone_dir)
                clone_widget.disabled = True
            except Exception as e:
                path_widget.value = (
                    "An error occurred when trying to clone the repository " + str(e)
                )
                clone_widget.disabled = True

    clone_widget.on_click(handle_clone_click)

    return left_widget, info_widget, tree_dict

center_zoom_to_xy_range(center, zoom)

Convert center and zoom to x and y range to be used as input to bokeh map.

Parameters:

Name	Type	Description	Default
center	tuple	A tuple of (latitude, longitude).	required
zoom	int	The zoom level.	required

Returns:

Name	Type	Description
tuple		A tuple of (x_range, y_range).

Source code in geemap/common.py

def center_zoom_to_xy_range(center, zoom):
    """Convert center and zoom to x and y range to be used as input to bokeh map.

    Args:
        center (tuple): A tuple of (latitude, longitude).
        zoom (int): The zoom level.

    Returns:
        tuple: A tuple of (x_range, y_range).
    """

    if isinstance(center, tuple) or isinstance(center, list):
        pass
    else:
        raise TypeError("center must be a tuple or list")

    if not isinstance(zoom, int):
        raise TypeError("zoom must be an integer")

    latitude, longitude = center
    x_range = (-179, 179)
    y_range = (-70, 70)
    x_full_length = x_range[1] - x_range[0]
    y_full_length = y_range[1] - y_range[0]

    x_length = x_full_length / 2 ** (zoom - 2)
    y_length = y_full_length / 2 ** (zoom - 2)

    south = latitude - y_length / 2
    north = latitude + y_length / 2
    west = longitude - x_length / 2
    east = longitude + x_length / 2

    xmin, ymin = lnglat_to_meters(west, south)
    xmax, ymax = lnglat_to_meters(east, north)

    x_range = (xmin, xmax)
    y_range = (ymin, ymax)

    return x_range, y_range

check_basemap(basemap)

Check Google basemaps

Parameters:

Name	Type	Description	Default
basemap	str	The basemap name.	required

Returns:

Name	Type	Description
str		The basemap name.

Source code in geemap/common.py

def check_basemap(basemap):
    """Check Google basemaps

    Args:
        basemap (str): The basemap name.

    Returns:
        str: The basemap name.
    """
    if isinstance(basemap, str):
        map_dict = {
            "ROADMAP": "Google Maps",
            "SATELLITE": "Google Satellite",
            "TERRAIN": "Google Terrain",
            "HYBRID": "Google Hybrid",
        }

        if basemap.upper() in map_dict.keys():
            return map_dict[basemap.upper()]
        else:
            return basemap
    else:
        return basemap

check_cmap(cmap)

Check the colormap and return a list of colors.

Parameters:

Name	Type	Description	Default
cmap	Union[str, List[str], Box]	The colormap to check.	required

Returns:

Type	Description
List[str]	List[str]: A list of colors.

Source code in geemap/coreutils.py

def check_cmap(cmap: Union[str, List[str]]) -> List[str]:
    """Check the colormap and return a list of colors.

    Args:
        cmap (Union[str, List[str], Box]): The colormap to check.

    Returns:
        List[str]: A list of colors.
    """

    from box import Box
    from .colormaps import get_palette

    if isinstance(cmap, str):
        try:
            palette = get_palette(cmap)
            if isinstance(palette, dict):
                palette = palette["default"]
            return palette
        except Exception as e:
            try:
                return check_color(cmap)
            except Exception as e:
                raise Exception(f"{cmap} is not a valid colormap.")
    elif isinstance(cmap, Box):
        return list(cmap["default"])
    elif isinstance(cmap, list) or isinstance(cmap, tuple):
        return cmap
    else:
        raise Exception(f"{cmap} is not a valid colormap.")

check_color(in_color)

Checks the input color and returns the corresponding hex color code.

Parameters:

Name	Type	Description	Default
in_color	str or tuple or list	It can be a string (e.g., 'red', '#ffff00', 'ffff00', 'ff0') or RGB tuple/list (e.g., (255, 127, 0)).	required

Returns:

Name	Type	Description
str	str	A hex color code.

Source code in geemap/coreutils.py

def check_color(in_color: Union[str, Tuple, List]) -> str:
    """Checks the input color and returns the corresponding hex color code.

    Args:
        in_color (str or tuple or list): It can be a string (e.g., 'red', '#ffff00', 'ffff00', 'ff0') or RGB tuple/list (e.g., (255, 127, 0)).

    Returns:
        str: A hex color code.
    """
    from matplotlib import colors

    out_color = "#000000"  # default black color
    # Handle RGB tuple or list
    if isinstance(in_color, (tuple, list)) and len(in_color) == 3:
        # rescale color if necessary
        if all(isinstance(item, int) for item in in_color):
            # Ensure values are floats between 0 and 1 for to_hex
            in_color = [c / 255.0 for c in in_color]
        try:
            return colors.to_hex(in_color)
        except ValueError:
            print(
                f"The provided RGB color ({in_color}) is invalid. Using the default black color."
            )
            return out_color

    # Handle string color input
    elif isinstance(in_color, str):
        try:
            # Try converting directly (handles color names and hex with #)
            return colors.to_hex(in_color)
        except ValueError:
            try:
                # Try again by adding an extra # (handles hex without #)
                return colors.to_hex(f"#{in_color}")
            except ValueError:
                print(
                    f"The provided color string ({in_color}) is invalid. Using the default black color."
                )
                return out_color
    else:
        print(
            f"The provided color type ({type(in_color)}) is invalid. Using the default black color."
        )
        return out_color

check_dir(dir_path, make_dirs=True)

Checks if a directory exists and creates it if it does not.

Parameters:

Name	Type	Description	Default
dir_path	[str	The path to the directory.	required
make_dirs	bool	Whether to create the directory if it does not exist. Defaults to True.	True

Raises:

Type	Description
FileNotFoundError	If the directory could not be found.
TypeError	If the input directory path is not a string.

Returns:

Name	Type	Description
str		The path to the directory.

Source code in geemap/common.py

def check_dir(dir_path, make_dirs=True):
    """Checks if a directory exists and creates it if it does not.

    Args:
        dir_path ([str): The path to the directory.
        make_dirs (bool, optional): Whether to create the directory if it does not exist. Defaults to True.

    Raises:
        FileNotFoundError: If the directory could not be found.
        TypeError: If the input directory path is not a string.

    Returns:
        str: The path to the directory.
    """

    if isinstance(dir_path, str):
        if dir_path.startswith("~"):
            dir_path = os.path.expanduser(dir_path)
        else:
            dir_path = os.path.abspath(dir_path)

        if not os.path.exists(dir_path) and make_dirs:
            os.makedirs(dir_path)

        if os.path.exists(dir_path):
            return dir_path
        else:
            raise FileNotFoundError("The provided directory could not be found.")
    else:
        raise TypeError("The provided directory path must be a string.")

check_file_path(file_path, make_dirs=True)

Gets the absolute file path.

Parameters:

Name	Type	Description	Default
file_path	[str	The path to the file.	required
make_dirs	bool	Whether to create the directory if it does not exist. Defaults to True.	True

Raises:

Type	Description
FileNotFoundError	If the directory could not be found.
TypeError	If the input directory path is not a string.

Returns:

Name	Type	Description
str		The absolute path to the file.

Source code in geemap/common.py

def check_file_path(file_path, make_dirs=True):
    """Gets the absolute file path.

    Args:
        file_path ([str): The path to the file.
        make_dirs (bool, optional): Whether to create the directory if it does not exist. Defaults to True.

    Raises:
        FileNotFoundError: If the directory could not be found.
        TypeError: If the input directory path is not a string.

    Returns:
        str: The absolute path to the file.
    """
    if isinstance(file_path, str):
        if file_path.startswith("~"):
            file_path = os.path.expanduser(file_path)
        else:
            file_path = os.path.abspath(file_path)

        file_dir = os.path.dirname(file_path)
        if not os.path.exists(file_dir) and make_dirs:
            os.makedirs(file_dir)

        return file_path

    else:
        raise TypeError("The provided file path must be a string.")

check_git_install()

Checks if Git is installed.

Returns:

Name	Type	Description
bool		Returns True if Git is installed, otherwise returns False.

Source code in geemap/common.py

def check_git_install():
    """Checks if Git is installed.

    Returns:
        bool: Returns True if Git is installed, otherwise returns False.
    """
    import webbrowser

    cmd = "git --version"
    output = os.popen(cmd).read()

    if "git version" in output:
        return True
    else:
        url = "https://git-scm.com/downloads"
        print(f"Git is not installed. Please download Git from {url} and install it.")
        webbrowser.open_new_tab(url)
        return False

check_html_string(html_string)

Check if an HTML string contains local images and convert them to base64.

Parameters:

Name	Type	Description	Default
html_string	str	The HTML string.	required

Returns:

Name	Type	Description
str		The HTML string with local images converted to base64.

Source code in geemap/common.py

def check_html_string(html_string):
    """Check if an HTML string contains local images and convert them to base64.

    Args:
        html_string (str): The HTML string.

    Returns:
        str: The HTML string with local images converted to base64.
    """
    import re
    import base64

    # Search for img tags with src attribute
    img_regex = r'<img[^>]+src\s*=\s*["\']([^"\':]+)["\'][^>]*>'

    for match in re.findall(img_regex, html_string):
        with open(match, "rb") as img_file:
            img_data = img_file.read()
            base64_data = base64.b64encode(img_data).decode("utf-8")
            html_string = html_string.replace(
                'src="{}"'.format(match),
                'src="data:image/png;base64,' + base64_data + '"',
            )

    return html_string

check_install(package)

Checks whether a package is installed. If not, it will install the package.

Parameters:

Name	Type	Description	Default
package	str	The name of the package to check.	required

Source code in geemap/common.py

def check_install(package):
    """Checks whether a package is installed. If not, it will install the package.

    Args:
        package (str): The name of the package to check.
    """
    import subprocess

    try:
        __import__(package)
        # print('{} is already installed.'.format(package))
    except ImportError:
        print(f"{package} is not installed. Installing ...")
        try:
            subprocess.check_call(["python", "-m", "pip", "install", package])
        except Exception as e:
            print(f"Failed to install {package}")
            print(e)
        print(f"{package} has been installed successfully.")

check_map_functions(input_lines)

Extracts Earth Engine map function

Parameters:

Name	Type	Description	Default
input_lines	list	List of Earth Engine JavaScrips	required

Returns:

Name	Type	Description
list		Output JavaScript with map function

Source code in geemap/conversion.py

def check_map_functions(input_lines):
    """Extracts Earth Engine map function

    Args:
        input_lines (list): List of Earth Engine JavaScrips

    Returns:
        list: Output JavaScript with map function
    """
    output_lines = []
    currentNumOfNestedFuncs = 0
    for index, line in enumerate(input_lines):
        if (
            line.strip().endswith(".map(")
            and input_lines[index + 1].strip().replace(" ", "").startswith("function(")
        ) or (
            line.strip().endswith(".map(function(")
            and input_lines[index + 1].strip().replace(" ", "").endswith("{")
        ):
            input_lines[index + 1] = line + input_lines[index + 1]
            continue

        if (
            ".map(function" in line.replace(" ", "")
            or "returnfunction" in line.replace(" ", "")
            or "function(" in line.replace(" ", "")
        ):
            try:
                bracket_index = line.index("{")
                matching_line_index, matching_char_index = find_matching_bracket(
                    input_lines, index, bracket_index
                )

                func_start_index = line.index("function")
                func_name = "func_" + random_string()
                func_header = line[func_start_index:].replace(
                    "function", "function " + func_name
                )
                output_lines.append("\n")
                output_lines.append(func_header)

                currentNumOfNestedFuncs += 1

                new_lines = input_lines[index + 1 : matching_line_index]

                new_lines = check_map_functions(new_lines)

                for sub_index, tmp_line in enumerate(new_lines):
                    output_lines.append(("    " * currentNumOfNestedFuncs) + tmp_line)
                    if "{" in tmp_line:
                        currentNumOfNestedFuncs += 1
                    if "}" in tmp_line:
                        currentNumOfNestedFuncs -= 1
                    input_lines[index + 1 + sub_index] = ""

                currentNumOfNestedFuncs -= 1

                header_line = line[:func_start_index] + func_name
                header_line = header_line.rstrip()

                func_footer = input_lines[matching_line_index][
                    : matching_char_index + 1
                ]
                output_lines.append(func_footer)

                footer_line = input_lines[matching_line_index][
                    matching_char_index + 1 :
                ].strip()
                if footer_line == ")" or footer_line == ");":
                    header_line = header_line + footer_line
                    footer_line = ""

                input_lines[matching_line_index] = footer_line

                output_lines.append(header_line)
                # output_lines.append(footer_line)
            except Exception as e:
                print(
                    f"An error occurred: {e}. The closing curly bracket could not be found in Line {index+1}: {line}. Please reformat the function definition and make sure that both the opening and closing curly brackets appear on the same line as the function keyword. "
                )
        else:
            output_lines.append(line)

    return output_lines

check_titiler_endpoint(titiler_endpoint=None)

Returns the default titiler endpoint.

Returns:

Name	Type	Description
object		A titiler endpoint.

Source code in geemap/common.py

def check_titiler_endpoint(titiler_endpoint=None):
    """Returns the default titiler endpoint.

    Returns:
        object: A titiler endpoint.
    """
    if titiler_endpoint is None:
        if os.environ.get("TITILER_ENDPOINT") is not None:
            titiler_endpoint = os.environ.get("TITILER_ENDPOINT")

            if titiler_endpoint == "planetary-computer":
                titiler_endpoint = PlanetaryComputerEndpoint()
        else:
            titiler_endpoint = "https://titiler.xyz"
    elif titiler_endpoint in ["planetary-computer", "pc"]:
        titiler_endpoint = PlanetaryComputerEndpoint()

    return titiler_endpoint

classify(data, column, cmap=None, colors=None, labels=None, scheme='Quantiles', k=5, legend_kwds=None, classification_kwds=None)

Classify a dataframe column using a variety of classification schemes.

Parameters:

Name	Type	Description	Default
data	str | DataFrame | GeoDataFrame	The data to classify. It can be a filepath to a vector dataset, a pandas dataframe, or a geopandas geodataframe.	required
column	str	The column to classify.	required
cmap	str	The name of a colormap recognized by matplotlib. Defaults to None.	None
colors	list	A list of colors to use for the classification. Defaults to None.	None
labels	list	A list of labels to use for the legend. Defaults to None.	None
scheme	str	Name of a choropleth classification scheme (requires mapclassify). Name of a choropleth classification scheme (requires mapclassify). A mapclassify.MapClassifier object will be used under the hood. Supported are all schemes provided by mapclassify (e.g. 'BoxPlot', 'EqualInterval', 'FisherJenks', 'FisherJenksSampled', 'HeadTailBreaks', 'JenksCaspall', 'JenksCaspallForced', 'JenksCaspallSampled', 'MaxP', 'MaximumBreaks', 'NaturalBreaks', 'Quantiles', 'Percentiles', 'StdMean', 'UserDefined'). Arguments can be passed in classification_kwds.	'Quantiles'
k	int	Number of classes (ignored if scheme is None or if column is categorical). Default to 5.	5
legend_kwds	dict	Keyword arguments to pass to :func:matplotlib.pyplot.legend or matplotlib.pyplot.colorbar. Defaults to None. Keyword arguments to pass to :func:matplotlib.pyplot.legend or Additional accepted keywords when scheme is specified: fmt : string A formatting specification for the bin edges of the classes in the legend. For example, to have no decimals: {"fmt": "{:.0f}"}. labels : list-like A list of legend labels to override the auto-generated labblels. Needs to have the same number of elements as the number of classes (k). interval : boolean (default False) An option to control brackets from mapclassify legend. If True, open/closed interval brackets are shown in the legend.	None
classification_kwds	dict	Keyword arguments to pass to mapclassify. Defaults to None.	None

Returns:

Type	Description
	pd.DataFrame, dict: A pandas dataframe with the classification applied and a legend dictionary.

Source code in geemap/common.py

def classify(
    data,
    column,
    cmap=None,
    colors=None,
    labels=None,
    scheme="Quantiles",
    k=5,
    legend_kwds=None,
    classification_kwds=None,
):
    """Classify a dataframe column using a variety of classification schemes.

    Args:
        data (str | pd.DataFrame | gpd.GeoDataFrame): The data to classify. It can be a filepath to a vector dataset, a pandas dataframe, or a geopandas geodataframe.
        column (str): The column to classify.
        cmap (str, optional): The name of a colormap recognized by matplotlib. Defaults to None.
        colors (list, optional): A list of colors to use for the classification. Defaults to None.
        labels (list, optional): A list of labels to use for the legend. Defaults to None.
        scheme (str, optional): Name of a choropleth classification scheme (requires mapclassify).
            Name of a choropleth classification scheme (requires mapclassify).
            A mapclassify.MapClassifier object will be used
            under the hood. Supported are all schemes provided by mapclassify (e.g.
            'BoxPlot', 'EqualInterval', 'FisherJenks', 'FisherJenksSampled',
            'HeadTailBreaks', 'JenksCaspall', 'JenksCaspallForced',
            'JenksCaspallSampled', 'MaxP', 'MaximumBreaks',
            'NaturalBreaks', 'Quantiles', 'Percentiles', 'StdMean',
            'UserDefined'). Arguments can be passed in classification_kwds.
        k (int, optional): Number of classes (ignored if scheme is None or if column is categorical). Default to 5.
        legend_kwds (dict, optional): Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or `matplotlib.pyplot.colorbar`. Defaults to None.
            Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or
            Additional accepted keywords when `scheme` is specified:
            fmt : string
                A formatting specification for the bin edges of the classes in the
                legend. For example, to have no decimals: ``{"fmt": "{:.0f}"}``.
            labels : list-like
                A list of legend labels to override the auto-generated labblels.
                Needs to have the same number of elements as the number of
                classes (`k`).
            interval : boolean (default False)
                An option to control brackets from mapclassify legend.
                If True, open/closed interval brackets are shown in the legend.
        classification_kwds (dict, optional): Keyword arguments to pass to mapclassify. Defaults to None.

    Returns:
        pd.DataFrame, dict: A pandas dataframe with the classification applied and a legend dictionary.
    """

    import numpy as np
    import pandas as pd
    import geopandas as gpd
    import matplotlib as mpl
    import matplotlib.pyplot as plt

    try:
        import mapclassify
    except ImportError:
        raise ImportError(
            'mapclassify is required for this function. Install with "pip install mapclassify".'
        )

    if isinstance(data, gpd.GeoDataFrame) or isinstance(data, pd.DataFrame):
        df = data
    else:
        try:
            df = gpd.read_file(data)
        except Exception:
            raise TypeError(
                "Data must be a GeoDataFrame or a path to a file that can be read by geopandas.read_file()."
            )

    if df.empty:
        warnings.warn(
            "The GeoDataFrame you are attempting to plot is "
            "empty. Nothing has been displayed.",
            UserWarning,
        )
        return

    columns = df.columns.values.tolist()
    if column not in columns:
        raise ValueError(
            f"{column} is not a column in the GeoDataFrame. It must be one of {columns}."
        )

    # Convert categorical data to numeric
    init_column = None
    value_list = None
    if np.issubdtype(df[column].dtype, np.object0):
        value_list = df[column].unique().tolist()
        value_list.sort()
        df["category"] = df[column].replace(value_list, range(0, len(value_list)))
        init_column = column
        column = "category"
        k = len(value_list)

    if legend_kwds is not None:
        legend_kwds = legend_kwds.copy()

    # To accept pd.Series and np.arrays as column
    if isinstance(column, (np.ndarray, pd.Series)):
        if column.shape[0] != df.shape[0]:
            raise ValueError(
                "The dataframe and given column have different number of rows."
            )
        else:
            values = column

            # Make sure index of a Series matches index of df
            if isinstance(values, pd.Series):
                values = values.reindex(df.index)
    else:
        values = df[column]

    values = df[column]
    nan_idx = np.asarray(pd.isna(values), dtype="bool")

    if cmap is None:
        cmap = "Blues"
    try:
        cmap = plt.get_cmap(cmap, k)
    except:
        cmap = plt.cm.get_cmap(cmap, k)
    if colors is None:
        colors = [mpl.colors.rgb2hex(cmap(i))[1:] for i in range(cmap.N)]
        colors = ["#" + i for i in colors]
    elif isinstance(colors, list):
        colors = [check_color(i) for i in colors]
    elif isinstance(colors, str):
        colors = [check_color(colors)] * k

    allowed_schemes = [
        "BoxPlot",
        "EqualInterval",
        "FisherJenks",
        "FisherJenksSampled",
        "HeadTailBreaks",
        "JenksCaspall",
        "JenksCaspallForced",
        "JenksCaspallSampled",
        "MaxP",
        "MaximumBreaks",
        "NaturalBreaks",
        "Quantiles",
        "Percentiles",
        "StdMean",
        "UserDefined",
    ]

    if scheme.lower() not in [s.lower() for s in allowed_schemes]:
        raise ValueError(
            f"{scheme} is not a valid scheme. It must be one of {allowed_schemes}."
        )

    if classification_kwds is None:
        classification_kwds = {}
    if "k" not in classification_kwds:
        classification_kwds["k"] = k

    binning = mapclassify.classify(
        np.asarray(values[~nan_idx]), scheme, **classification_kwds
    )
    df["category"] = binning.yb
    df["color"] = [colors[i] for i in df["category"]]

    if legend_kwds is None:
        legend_kwds = {}

    if "interval" not in legend_kwds:
        legend_kwds["interval"] = True

    if "fmt" not in legend_kwds:
        if np.issubdtype(df[column].dtype, np.floating):
            legend_kwds["fmt"] = "{:.2f}"
        else:
            legend_kwds["fmt"] = "{:.0f}"

    if labels is None:
        # set categorical to True for creating the legend
        if legend_kwds is not None and "labels" in legend_kwds:
            if len(legend_kwds["labels"]) != binning.k:
                raise ValueError(
                    "Number of labels must match number of bins, "
                    "received {} labels for {} bins".format(
                        len(legend_kwds["labels"]), binning.k
                    )
                )
            else:
                labels = list(legend_kwds.pop("labels"))
        else:
            # fmt = "{:.2f}"
            if legend_kwds is not None and "fmt" in legend_kwds:
                fmt = legend_kwds.pop("fmt")

            labels = binning.get_legend_classes(fmt)
            if legend_kwds is not None:
                show_interval = legend_kwds.pop("interval", False)
            else:
                show_interval = False
            if not show_interval:
                labels = [c[1:-1] for c in labels]

        if init_column is not None:
            labels = value_list
    elif isinstance(labels, list):
        if len(labels) != len(colors):
            raise ValueError("The number of labels must match the number of colors.")
    else:
        raise ValueError("labels must be a list or None.")

    legend_dict = dict(zip(labels, colors))
    df["category"] = df["category"] + 1
    return df, legend_dict

clip_image(image, mask, output)

Clip an image by mask.

Parameters:

Name	Type	Description	Default
image	str	Path to the image file in GeoTIFF format.	required
mask	str | list | dict	The mask used to extract the image. It can be a path to vector datasets (e.g., GeoJSON, Shapefile), a list of coordinates, or m.user_roi.	required
output	str	Path to the output file.	required

Raises:

Type	Description
ImportError	If the fiona or rasterio package is not installed.
FileNotFoundError	If the image is not found.
ValueError	If the mask is not a valid GeoJSON or raster file.
FileNotFoundError	If the mask file is not found.

Source code in geemap/common.py

def clip_image(image, mask, output):
    """Clip an image by mask.

    Args:
        image (str): Path to the image file in GeoTIFF format.
        mask (str | list | dict): The mask used to extract the image. It can be a path to vector datasets (e.g., GeoJSON, Shapefile), a list of coordinates, or m.user_roi.
        output (str): Path to the output file.

    Raises:
        ImportError: If the fiona or rasterio package is not installed.
        FileNotFoundError: If the image is not found.
        ValueError: If the mask is not a valid GeoJSON or raster file.
        FileNotFoundError: If the mask file is not found.
    """
    try:
        import fiona
        import rasterio
        import rasterio.mask
    except ImportError as e:
        raise ImportError(e)

    if not os.path.exists(image):
        raise FileNotFoundError(f"{image} does not exist.")

    if not output.endswith(".tif"):
        raise ValueError("Output must be a tif file.")

    output = check_file_path(output)

    if isinstance(mask, ee.Geometry):
        mask = mask.coordinates().getInfo()[0]

    if isinstance(mask, str):
        if mask.startswith("http"):
            mask = download_file(mask, output)
        if not os.path.exists(mask):
            raise FileNotFoundError(f"{mask} does not exist.")
    elif isinstance(mask, list) or isinstance(mask, dict):
        if isinstance(mask, list):
            geojson = {
                "type": "FeatureCollection",
                "features": [
                    {
                        "type": "Feature",
                        "properties": {},
                        "geometry": {"type": "Polygon", "coordinates": [mask]},
                    }
                ],
            }
        else:
            geojson = {
                "type": "FeatureCollection",
                "features": [mask],
            }
        mask = temp_file_path(".geojson")
        with open(mask, "w") as f:
            json.dump(geojson, f)

    with fiona.open(mask, "r") as shapefile:
        shapes = [feature["geometry"] for feature in shapefile]

    with rasterio.open(image) as src:
        out_image, out_transform = rasterio.mask.mask(src, shapes, crop=True)
        out_meta = src.meta

    out_meta.update(
        {
            "driver": "GTiff",
            "height": out_image.shape[1],
            "width": out_image.shape[2],
            "transform": out_transform,
        }
    )

    with rasterio.open(output, "w", **out_meta) as dest:
        dest.write(out_image)

clone_github_repo(url, out_dir)

Clones a GitHub repository.

Parameters:

Name	Type	Description	Default
url	str	The link to the GitHub repository	required
out_dir	str	The output directory for the cloned repository.	required

Source code in geemap/common.py

def clone_github_repo(url, out_dir):
    """Clones a GitHub repository.

    Args:
        url (str): The link to the GitHub repository
        out_dir (str): The output directory for the cloned repository.
    """

    repo_name = os.path.basename(url)
    # url_zip = os.path.join(url, 'archive/master.zip')
    url_zip = url + "/archive/master.zip"

    if os.path.exists(out_dir):
        print(
            "The specified output directory already exists. Please choose a new directory."
        )
        return

    parent_dir = os.path.dirname(out_dir)
    out_file_path = os.path.join(parent_dir, repo_name + ".zip")

    try:
        urllib.request.urlretrieve(url_zip, out_file_path)
    except Exception:
        print("The provided URL is invalid. Please double check the URL.")
        return

    with zipfile.ZipFile(out_file_path, "r") as zip_ref:
        zip_ref.extractall(parent_dir)

    src = out_file_path.replace(".zip", "-master")
    os.rename(src, out_dir)
    os.remove(out_file_path)

clone_google_repo(url, out_dir=None)

Clones an Earth Engine repository from https://earthengine.googlesource.com, such as https://earthengine.googlesource.com/users/google/datasets

Parameters:

Name	Type	Description	Default
url	str	The link to the Earth Engine repository	required
out_dir	str	The output directory for the cloned repository. Defaults to None.	None

Source code in geemap/common.py

def clone_google_repo(url, out_dir=None):
    """Clones an Earth Engine repository from https://earthengine.googlesource.com, such as https://earthengine.googlesource.com/users/google/datasets

    Args:
        url (str): The link to the Earth Engine repository
        out_dir (str, optional): The output directory for the cloned repository. Defaults to None.
    """
    repo_name = os.path.basename(url)

    if out_dir is None:
        out_dir = os.path.join(os.getcwd(), repo_name)

    if not os.path.exists(os.path.dirname(out_dir)):
        os.makedirs(os.path.dirname(out_dir))

    if os.path.exists(out_dir):
        print(
            "The specified output directory already exists. Please choose a new directory."
        )
        return

    if check_git_install():
        cmd = f'git clone "{url}" "{out_dir}"'
        os.popen(cmd).read()

clone_repo(out_dir='.', unzip=True)

Clones the geemap GitHub repository.

Parameters:

Name	Type	Description	Default
out_dir	str	Output folder for the repo. Defaults to '.'.	'.'
unzip	bool	Whether to unzip the repository. Defaults to True.	True

Source code in geemap/common.py

def clone_repo(out_dir=".", unzip=True):
    """Clones the geemap GitHub repository.

    Args:
        out_dir (str, optional): Output folder for the repo. Defaults to '.'.
        unzip (bool, optional): Whether to unzip the repository. Defaults to True.
    """
    url = "https://github.com/gee-community/geemap/archive/master.zip"
    filename = "geemap-master.zip"
    download_from_url(url, out_file_name=filename, out_dir=out_dir, unzip=unzip)

cog_bands(url, titiler_endpoint=None, timeout=300)

Get band names of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
timeout	int	Timeout in seconds. Defaults to 300.	300

Returns:

Name	Type	Description
list		A list of band names

Source code in geemap/common.py

def cog_bands(url, titiler_endpoint=None, timeout=300):
    """Get band names of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        timeout (int, optional): Timeout in seconds. Defaults to 300.

    Returns:
        list: A list of band names
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    url = get_direct_url(url)
    r = requests.get(
        f"{titiler_endpoint}/cog/info",
        params={
            "url": url,
        },
        timeout=timeout,
    ).json()

    bands = [b[0] for b in r["band_descriptions"]]
    return bands

cog_bounds(url, titiler_endpoint=None, timeout=300)

Get the bounding box of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
timeout	int	Timeout in seconds. Defaults to 300.	300

Returns:

Name	Type	Description
list		A list of values representing [left, bottom, right, top]

Source code in geemap/common.py

def cog_bounds(url, titiler_endpoint=None, timeout=300):
    """Get the bounding box of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        timeout (int, optional): Timeout in seconds. Defaults to 300.

    Returns:
        list: A list of values representing [left, bottom, right, top]
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    url = get_direct_url(url)

    r = requests.get(
        f"{titiler_endpoint}/cog/bounds", params={"url": url}, timeout=timeout
    ).json()

    if "bounds" in r.keys():
        bounds = r["bounds"]
    else:
        bounds = None
    return bounds

cog_center(url, titiler_endpoint=None)

Get the centroid of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None

Returns:

Name	Type	Description
tuple		A tuple representing (longitude, latitude)

Source code in geemap/common.py

def cog_center(url, titiler_endpoint=None):
    """Get the centroid of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".

    Returns:
        tuple: A tuple representing (longitude, latitude)
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    url = get_direct_url(url)
    bounds = cog_bounds(url, titiler_endpoint)
    center = ((bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2)  # (lat, lon)
    return center

cog_info(url, titiler_endpoint=None, return_geojson=False, timeout=300)

Get band statistics of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
timeout	int	Timeout in seconds. Defaults to 300.	300

Returns:

Name	Type	Description
list		A dictionary of band info.

Source code in geemap/common.py

def cog_info(url, titiler_endpoint=None, return_geojson=False, timeout=300):
    """Get band statistics of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        timeout (int, optional): Timeout in seconds. Defaults to 300.

    Returns:
        list: A dictionary of band info.
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    url = get_direct_url(url)
    info = "info"
    if return_geojson:
        info = "info.geojson"

    r = requests.get(
        f"{titiler_endpoint}/cog/{info}",
        params={
            "url": url,
        },
        timeout=timeout,
    ).json()

    return r

cog_mosaic(links, titiler_endpoint=None, username='anonymous', layername=None, overwrite=False, verbose=True, timeout=300, **kwargs)

Creates a COG mosaic from a list of COG URLs.

Parameters:

Name	Type	Description	Default
links	list	A list containing COG HTTP URLs.	required
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
username	str	User name for the titiler endpoint. Defaults to "anonymous".	'anonymous'
layername	[type]	Layer name to use. Defaults to None.	None
overwrite	bool	Whether to overwrite the layer name if existing. Defaults to False.	False
verbose	bool	Whether to print out descriptive information. Defaults to True.	True
timeout	int	Timeout in seconds. Defaults to 300.	300

Raises:

Type	Description
Exception	If the COG mosaic fails to create.

Returns:

Name	Type	Description
str		The tile URL for the COG mosaic.

Source code in geemap/common.py

def cog_mosaic(
    links,
    titiler_endpoint=None,
    username="anonymous",
    layername=None,
    overwrite=False,
    verbose=True,
    timeout=300,
    **kwargs,
):
    """Creates a COG mosaic from a list of COG URLs.

    Args:
        links (list): A list containing COG HTTP URLs.
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        username (str, optional): User name for the titiler endpoint. Defaults to "anonymous".
        layername ([type], optional): Layer name to use. Defaults to None.
        overwrite (bool, optional): Whether to overwrite the layer name if existing. Defaults to False.
        verbose (bool, optional): Whether to print out descriptive information. Defaults to True.
        timeout (int, optional): Timeout in seconds. Defaults to 300.

    Raises:
        Exception: If the COG mosaic fails to create.

    Returns:
        str: The tile URL for the COG mosaic.
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    if layername is None:
        layername = "layer_" + random_string(5)

    try:
        if verbose:
            print("Creating COG masaic ...")

        # Create token
        r = requests.post(
            f"{titiler_endpoint}/tokens/create",
            json={"username": username, "scope": ["mosaic:read", "mosaic:create"]},
        ).json()
        token = r["token"]

        # Create mosaic
        requests.post(
            f"{titiler_endpoint}/mosaicjson/create",
            json={
                "username": username,
                "layername": layername,
                "files": links,
                # "overwrite": overwrite
            },
            params={
                "access_token": token,
            },
        ).json()

        r2 = requests.get(
            f"{titiler_endpoint}/mosaicjson/{username}.{layername}/tilejson.json",
            timeout=timeout,
        ).json()

        return r2["tiles"][0]

    except Exception as e:
        raise Exception(e)

cog_mosaic_from_file(filepath, skip_rows=0, titiler_endpoint=None, username='anonymous', layername=None, overwrite=False, verbose=True, **kwargs)

Creates a COG mosaic from a csv/txt file stored locally for through HTTP URL.

Parameters:

Name	Type	Description	Default
filepath	str	Local path or HTTP URL to the csv/txt file containing COG URLs.	required
skip_rows	int	The number of rows to skip in the file. Defaults to 0.	0
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
username	str	User name for the titiler endpoint. Defaults to "anonymous".	'anonymous'
layername	[type]	Layer name to use. Defaults to None.	None
overwrite	bool	Whether to overwrite the layer name if existing. Defaults to False.	False
verbose	bool	Whether to print out descriptive information. Defaults to True.	True

Returns:

Name	Type	Description
str		The tile URL for the COG mosaic.

Source code in geemap/common.py

def cog_mosaic_from_file(
    filepath,
    skip_rows=0,
    titiler_endpoint=None,
    username="anonymous",
    layername=None,
    overwrite=False,
    verbose=True,
    **kwargs,
):
    """Creates a COG mosaic from a csv/txt file stored locally for through HTTP URL.

    Args:
        filepath (str): Local path or HTTP URL to the csv/txt file containing COG URLs.
        skip_rows (int, optional): The number of rows to skip in the file. Defaults to 0.
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        username (str, optional): User name for the titiler endpoint. Defaults to "anonymous".
        layername ([type], optional): Layer name to use. Defaults to None.
        overwrite (bool, optional): Whether to overwrite the layer name if existing. Defaults to False.
        verbose (bool, optional): Whether to print out descriptive information. Defaults to True.

    Returns:
        str: The tile URL for the COG mosaic.
    """
    import urllib

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    links = []
    if filepath.startswith("http"):
        data = urllib.request.urlopen(filepath)
        for line in data:
            links.append(line.decode("utf-8").strip())

    else:
        with open(filepath) as f:
            links = [line.strip() for line in f.readlines()]

    links = links[skip_rows:]
    # print(links)
    mosaic = cog_mosaic(
        links, titiler_endpoint, username, layername, overwrite, verbose, **kwargs
    )
    return mosaic

cog_pixel_value(lon, lat, url, bidx=None, titiler_endpoint=None, timeout=300, **kwargs)

Get pixel value from COG.

Parameters:

Name	Type	Description	Default
lon	float	Longitude of the pixel.	required
lat	float	Latitude of the pixel.	required
url	str	HTTP URL to a COG, e.g., 'https://github.com/opengeos/data/releases/download/raster/Libya-2023-07-01.tif'	required
bidx	str	Dataset band indexes (e.g bidx=1, bidx=1&bidx=2&bidx=3). Defaults to None.	None
titiler_endpoint	str	Titiler endpoint, e.g., "https://titiler.xyz", "planetary-computer", "pc". Defaults to None.	None
timeout	int	Timeout in seconds. Defaults to 300.	300

Returns:

Name	Type	Description
list		A dictionary of band info.

Source code in geemap/common.py

def cog_pixel_value(
    lon,
    lat,
    url,
    bidx=None,
    titiler_endpoint=None,
    timeout=300,
    **kwargs,
):
    """Get pixel value from COG.

    Args:
        lon (float): Longitude of the pixel.
        lat (float): Latitude of the pixel.
        url (str): HTTP URL to a COG, e.g., 'https://github.com/opengeos/data/releases/download/raster/Libya-2023-07-01.tif'
        bidx (str, optional): Dataset band indexes (e.g bidx=1, bidx=1&bidx=2&bidx=3). Defaults to None.
        titiler_endpoint (str, optional): Titiler endpoint, e.g., "https://titiler.xyz", "planetary-computer", "pc". Defaults to None.
        timeout (int, optional): Timeout in seconds. Defaults to 300.

    Returns:
        list: A dictionary of band info.
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    url = get_direct_url(url)
    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    kwargs["url"] = url
    if bidx is not None:
        kwargs["bidx"] = bidx

    r = requests.get(
        f"{titiler_endpoint}/cog/point/{lon},{lat}", params=kwargs, timeout=timeout
    ).json()
    bands = cog_bands(url, titiler_endpoint)
    # if isinstance(titiler_endpoint, str):
    #     r = requests.get(f"{titiler_endpoint}/cog/point/{lon},{lat}", params=kwargs).json()
    # else:
    #     r = requests.get(
    #         titiler_endpoint.url_for_stac_pixel_value(lon, lat), params=kwargs
    #     ).json()

    if "detail" in r:
        print(r["detail"])
        return None
    else:
        values = r["values"]
        result = dict(zip(bands, values))
        return result

cog_stats(url, titiler_endpoint=None, timeout=300)

Get band statistics of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
timeout	int	Timeout in seconds. Defaults to 300.	300

Returns:

Name	Type	Description
list		A dictionary of band statistics.

Source code in geemap/common.py

def cog_stats(url, titiler_endpoint=None, timeout=300):
    """Get band statistics of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        timeout (int, optional): Timeout in seconds. Defaults to 300.

    Returns:
        list: A dictionary of band statistics.
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    url = get_direct_url(url)
    r = requests.get(
        f"{titiler_endpoint}/cog/statistics",
        params={
            "url": url,
        },
        timeout=timeout,
    ).json()

    return r

cog_tile(url, bands=None, titiler_endpoint=None, timeout=300, proxies=None, **kwargs)

Get a tile layer from a Cloud Optimized GeoTIFF (COG). Source code adapted from https://developmentseed.org/titiler/examples/notebooks/Working_with_CloudOptimizedGeoTIFF_simple/

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	Titiler endpoint. Defaults to "https://titiler.xyz".	None
timeout	int	Timeout in seconds. Defaults to 300.	300
proxies	dict	Proxies to use. Defaults to None.	None

Returns:

Name	Type	Description
tuple		Returns the COG Tile layer URL and bounds.

Source code in geemap/common.py

def cog_tile(
    url,
    bands=None,
    titiler_endpoint=None,
    timeout=300,
    proxies=None,
    **kwargs,
):
    """Get a tile layer from a Cloud Optimized GeoTIFF (COG).
        Source code adapted from https://developmentseed.org/titiler/examples/notebooks/Working_with_CloudOptimizedGeoTIFF_simple/

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): Titiler endpoint. Defaults to "https://titiler.xyz".
        timeout (int, optional): Timeout in seconds. Defaults to 300.
        proxies (dict, optional): Proxies to use. Defaults to None.

    Returns:
        tuple: Returns the COG Tile layer URL and bounds.
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    url = get_direct_url(url)

    kwargs["url"] = url

    band_names = cog_bands(url, titiler_endpoint)

    if bands is None and "bidx" not in kwargs:
        if len(band_names) >= 3:
            kwargs["bidx"] = [1, 2, 3]
    elif bands is not None and "bidx" not in kwargs:
        if all(isinstance(x, int) for x in bands):
            kwargs["bidx"] = bands
        elif all(isinstance(x, str) for x in bands):
            kwargs["bidx"] = [band_names.index(x) + 1 for x in bands]
        else:
            raise ValueError("Bands must be a list of integers or strings.")

    if "palette" in kwargs:
        kwargs["colormap_name"] = kwargs.pop("palette")

    if "colormap" in kwargs:
        kwargs["colormap_name"] = kwargs.pop("colormap")

    if "rescale" not in kwargs:
        stats = cog_stats(url, titiler_endpoint)
        percentile_2 = min([stats[s]["percentile_2"] for s in stats])
        percentile_98 = max([stats[s]["percentile_98"] for s in stats])
        kwargs["rescale"] = f"{percentile_2},{percentile_98}"

    TileMatrixSetId = "WebMercatorQuad"
    if "TileMatrixSetId" in kwargs.keys():
        TileMatrixSetId = kwargs["TileMatrixSetId"]
        kwargs.pop("TileMatrixSetId")

    r = requests.get(
        f"{titiler_endpoint}/cog/{TileMatrixSetId}/tilejson.json",
        params=kwargs,
        timeout=timeout,
        proxies=proxies,
    ).json()

    return r["tiles"][0]

cog_validate(source, verbose=False)

Validate Cloud Optimized Geotiff.

Parameters:

Name	Type	Description	Default
source	str	A dataset path or URL. Will be opened in "r" mode.	required
verbose	bool	Whether to print the output of the validation. Defaults to False.	False

Raises:

Type	Description
ImportError	If the rio-cogeo package is not installed.
FileNotFoundError	If the provided file could not be found.

Returns:

Name	Type	Description
tuple		A tuple containing the validation results (True is src_path is a valid COG, List of validation errors, and a list of validation warnings).

Source code in geemap/common.py

def cog_validate(source, verbose=False):
    """Validate Cloud Optimized Geotiff.

    Args:
        source (str): A dataset path or URL. Will be opened in "r" mode.
        verbose (bool, optional): Whether to print the output of the validation. Defaults to False.

    Raises:
        ImportError: If the rio-cogeo package is not installed.
        FileNotFoundError: If the provided file could not be found.

    Returns:
        tuple: A tuple containing the validation results (True is src_path is a valid COG, List of validation errors, and a list of validation warnings).
    """
    try:
        from rio_cogeo.cogeo import cog_validate, cog_info
    except ImportError:
        raise ImportError(
            "The rio-cogeo package is not installed. Please install it with `pip install rio-cogeo` or `conda install rio-cogeo -c conda-forge`."
        )

    if not source.startswith("http"):
        source = check_file_path(source)

        if not os.path.exists(source):
            raise FileNotFoundError("The provided input file could not be found.")

    if verbose:
        return cog_info(source)
    else:
        return cog_validate(source)

column_stats(collection, column, stats_type)

Aggregates over a given property of the objects in a collection, calculating the sum, min, max, mean, sample standard deviation, sample variance, total standard deviation and total variance of the selected property.

Parameters:

Name	Type	Description	Default
collection	FeatureCollection	The input feature collection to calculate statistics.	required
column	str	The name of the column to calculate statistics.	required
stats_type	str	The type of statistics to calculate.	required

Returns:

Name	Type	Description
dict		The dictionary containing information about the requested statistics.

Source code in geemap/common.py

def column_stats(collection, column, stats_type):
    """Aggregates over a given property of the objects in a collection, calculating the sum, min, max, mean,
    sample standard deviation, sample variance, total standard deviation and total variance of the selected property.

    Args:
        collection (FeatureCollection): The input feature collection to calculate statistics.
        column (str): The name of the column to calculate statistics.
        stats_type (str): The type of statistics to calculate.

    Returns:
        dict: The dictionary containing information about the requested statistics.
    """
    stats_type = stats_type.lower()
    allowed_stats = ["min", "max", "mean", "median", "sum", "stdDev", "variance"]
    if stats_type not in allowed_stats:
        print(
            "The stats type must be one of the following: {}".format(
                ",".join(allowed_stats)
            )
        )
        return

    stats_dict = {
        "min": ee.Reducer.min(),
        "max": ee.Reducer.max(),
        "mean": ee.Reducer.mean(),
        "median": ee.Reducer.median(),
        "sum": ee.Reducer.sum(),
        "stdDev": ee.Reducer.stdDev(),
        "variance": ee.Reducer.variance(),
    }

    selectors = [column]
    stats = collection.reduceColumns(
        **{"selectors": selectors, "reducer": stats_dict[stats_type]}
    )

    return stats

connect_postgis(database, host='localhost', user=None, password=None, port=5432, use_env_var=False)

Connects to a PostGIS database.

Parameters:

Name	Type	Description	Default
database	str	Name of the database	required
host	str	Hosting server for the database. Defaults to "localhost".	'localhost'
user	str	User name to access the database. Defaults to None.	None
password	str	Password to access the database. Defaults to None.	None
port	int	Port number to connect to at the server host. Defaults to 5432.	5432
use_env_var	bool	Whether to use environment variables. It set to True, user and password are treated as an environment variables with default values user="SQL_USER" and password="SQL_PASSWORD". Defaults to False.	False

Raises:

Type	Description
ValueError	If user is not specified.
ValueError	If password is not specified.

Returns:

Type	Description

Source code in geemap/common.py

def connect_postgis(
    database, host="localhost", user=None, password=None, port=5432, use_env_var=False
):
    """Connects to a PostGIS database.

    Args:
        database (str): Name of the database
        host (str, optional): Hosting server for the database. Defaults to "localhost".
        user (str, optional): User name to access the database. Defaults to None.
        password (str, optional): Password to access the database. Defaults to None.
        port (int, optional): Port number to connect to at the server host. Defaults to 5432.
        use_env_var (bool, optional): Whether to use environment variables. It set to True, user and password are treated as an environment variables with default values user="SQL_USER" and password="SQL_PASSWORD". Defaults to False.

    Raises:
        ValueError: If user is not specified.
        ValueError: If password is not specified.

    Returns:
        [type]: [description]
    """
    check_package(name="geopandas", URL="https://geopandas.org")
    check_package(
        name="sqlalchemy",
        URL="https://docs.sqlalchemy.org/en/14/intro.html#installation",
    )

    from sqlalchemy import create_engine

    if use_env_var:
        if user is not None:
            user = os.getenv(user)
        else:
            user = os.getenv("SQL_USER")

        if password is not None:
            password = os.getenv(password)
        else:
            password = os.getenv("SQL_PASSWORD")

        if user is None:
            raise ValueError("user is not specified.")
        if password is None:
            raise ValueError("password is not specified.")

    connection_string = f"postgresql://{user}:{password}@{host}:{port}/{database}"
    engine = create_engine(connection_string)

    return engine

convert_for_loop(line)

Converts JavaScript for loop to Python for loop.

Parameters:

Name	Type	Description	Default
line	str	Input JavaScript for loop	required

Returns:

Name	Type	Description
str		Converted Python for loop.

Source code in geemap/conversion.py

def convert_for_loop(line):
    """Converts JavaScript for loop to Python for loop.

    Args:
        line (str): Input JavaScript for loop

    Returns:
        str: Converted Python for loop.
    """
    new_line = ""
    if "var " in line:
        line = line.replace("var ", "")
    start_index = line.index("(")
    end_index = line.index(")")

    prefix = line[:(start_index)]
    suffix = line[(end_index + 1) :]

    params = line[(start_index + 1) : end_index]

    if " in " in params and params.count(";") == 0:
        new_line = prefix + "{}:".format(params) + suffix
        return new_line

    items = params.split("=")
    param_name = items[0].strip()
    items = params.split(";")

    subitems = []

    for item in items:
        subitems.append(item.split(" ")[-1])

    start = subitems[0]
    end = subitems[1]
    step = subitems[2]

    if "++" in step:
        step = 1
    elif "--" in step:
        step = -1

    prefix = line[:(start_index)]
    suffix = line[(end_index + 1) :]
    new_line = (
        prefix
        + "{} in range({}, {}, {}):".format(param_name, start, end, step)
        + suffix
    )

    return new_line

convert_lidar(source, destination=None, point_format_id=None, file_version=None, **kwargs)

Converts a Las from one point format to another Automatically upgrades the file version if source file version is not compatible with the new point_format_id

Parameters:

Name	Type	Description	Default
source	str | LasBase	The source data to be converted.	required
destination	str	The destination file path. Defaults to None.	None
point_format_id	int	The new point format id (the default is None, which won't change the source format id).	None
file_version	str	The new file version. None by default which means that the file_version may be upgraded for compatibility with the new point_format. The file version will not be downgraded.	None

Returns:

Type	Description
	aspy.lasdatas.base.LasBase: The converted LasData object.

Source code in geemap/common.py

def convert_lidar(
    source, destination=None, point_format_id=None, file_version=None, **kwargs
):
    """Converts a Las from one point format to another Automatically upgrades the file version if source file version
        is not compatible with the new point_format_id

    Args:
        source (str | laspy.lasdatas.base.LasBase): The source data to be converted.
        destination (str, optional): The destination file path. Defaults to None.
        point_format_id (int, optional): The new point format id (the default is None, which won't change the source format id).
        file_version (str, optional): The new file version. None by default which means that the file_version may be upgraded
            for compatibility with the new point_format. The file version will not be downgraded.

    Returns:
        aspy.lasdatas.base.LasBase: The converted LasData object.
    """
    try:
        import laspy
    except ImportError:
        print(
            "The laspy package is required for this function. Use `pip install laspy[lazrs,laszip]` to install it."
        )
        return

    if isinstance(source, str):
        source = read_lidar(source)

    las = laspy.convert(
        source, point_format_id=point_format_id, file_version=file_version
    )

    if destination is None:
        return las
    else:
        destination = check_file_path(destination)
        write_lidar(las, destination, **kwargs)
        return destination

coords_to_geojson(coords)

Convert a list of bbox coordinates representing [left, bottom, right, top] to geojson FeatureCollection.

Parameters:

Name	Type	Description	Default
coords	list	A list of bbox coordinates representing [left, bottom, right, top].	required

Returns:

Name	Type	Description
dict		A geojson FeatureCollection.

Source code in geemap/common.py

def coords_to_geojson(coords):
    """Convert a list of bbox coordinates representing [left, bottom, right, top] to geojson FeatureCollection.

    Args:
        coords (list): A list of bbox coordinates representing [left, bottom, right, top].

    Returns:
        dict: A geojson FeatureCollection.
    """

    features = []
    for bbox in coords:
        features.append(bbox_to_geojson(bbox))
    return {"type": "FeatureCollection", "features": features}

copy_credentials_to_colab()

Copies ee credentials from Google Drive to Google Colab.

Source code in geemap/common.py

def copy_credentials_to_colab():
    """Copies ee credentials from Google Drive to Google Colab."""
    src = "/content/drive/My Drive/.config/earthengine/credentials"
    dst = "/root/.config/earthengine/credentials"

    wd = os.path.dirname(dst)
    if not os.path.exists(wd):
        os.makedirs(wd)

    shutil.copyfile(src, dst)

copy_credentials_to_drive()

Copies ee credentials from Google Colab to Google Drive.

Source code in geemap/common.py

def copy_credentials_to_drive():
    """Copies ee credentials from Google Colab to Google Drive."""
    src = "/root/.config/earthengine/credentials"
    dst = "/content/drive/My Drive/.config/earthengine/credentials"

    wd = os.path.dirname(dst)
    if not os.path.exists(wd):
        os.makedirs(wd)

    shutil.copyfile(src, dst)

create_code_cell(code='', where='below')

Creates a code cell in the IPython Notebook.

Parameters:

Name	Type	Description	Default
code	str	Code to fill the new code cell with. Defaults to ''.	''
where	str	Where to add the new code cell. It can be one of the following: above, below, at_bottom. Defaults to 'below'.	'below'

Source code in geemap/coreutils.py

def create_code_cell(code: str = "", where: str = "below") -> None:
    """Creates a code cell in the IPython Notebook.

    Args:
        code (str, optional): Code to fill the new code cell with. Defaults to ''.
        where (str, optional): Where to add the new code cell. It can be one of
            the following: above, below, at_bottom. Defaults to 'below'.
    """

    import base64
    import pyperclip

    try:
        pyperclip.copy(str(code))
    except Exception as e:
        pass

    encoded_code = (base64.b64encode(str.encode(code))).decode()
    display(
        Javascript(
            """
        var code = IPython.notebook.insert_cell_{0}('code');
        code.set_text(atob("{1}"));
    """.format(
                where, encoded_code
            )
        )
    )

create_colorbar(width=150, height=30, palette=['blue', 'green', 'red'], add_ticks=True, add_labels=True, labels=None, vertical=False, out_file=None, font_type='arial.ttf', font_size=12, font_color='black', add_outline=True, outline_color='black')

Creates a colorbar based on the provided palette.

Parameters:

Name	Type	Description	Default
width	int	Width of the colorbar in pixels. Defaults to 150.	150
height	int	Height of the colorbar in pixels. Defaults to 30.	30
palette	list	Palette for the colorbar. Each color can be provided as a string (e.g., 'red'), a hex string (e.g., '#ff0000'), or an RGB tuple (255, 0, 255). Defaults to ['blue', 'green', 'red'].	['blue', 'green', 'red']
add_ticks	bool	Whether to add tick markers to the colorbar. Defaults to True.	True
add_labels	bool	Whether to add labels to the colorbar. Defaults to True.	True
labels	list	A list of labels to add to the colorbar. Defaults to None.	None
vertical	bool	Whether to rotate the colorbar vertically. Defaults to False.	False
out_file	str	File path to the output colorbar in png format. Defaults to None.	None
font_type	str	Font type to use for labels. Defaults to 'arial.ttf'.	'arial.ttf'
font_size	int	Font size to use for labels. Defaults to 12.	12
font_color	str	Font color to use for labels. Defaults to 'black'.	'black'
add_outline	bool	Whether to add an outline to the colorbar. Defaults to True.	True
outline_color	str	Color for the outline of the colorbar. Defaults to 'black'.	'black'

Returns:

Name	Type	Description
str		File path of the output colorbar in png format.

Source code in geemap/common.py

def create_colorbar(
    width=150,
    height=30,
    palette=["blue", "green", "red"],
    add_ticks=True,
    add_labels=True,
    labels=None,
    vertical=False,
    out_file=None,
    font_type="arial.ttf",
    font_size=12,
    font_color="black",
    add_outline=True,
    outline_color="black",
):
    """Creates a colorbar based on the provided palette.

    Args:
        width (int, optional): Width of the colorbar in pixels. Defaults to 150.
        height (int, optional): Height of the colorbar in pixels. Defaults to 30.
        palette (list, optional): Palette for the colorbar. Each color can be provided as a string (e.g., 'red'), a hex string (e.g., '#ff0000'), or an RGB tuple (255, 0, 255). Defaults to ['blue', 'green', 'red'].
        add_ticks (bool, optional): Whether to add tick markers to the colorbar. Defaults to True.
        add_labels (bool, optional): Whether to add labels to the colorbar. Defaults to True.
        labels (list, optional): A list of labels to add to the colorbar. Defaults to None.
        vertical (bool, optional): Whether to rotate the colorbar vertically. Defaults to False.
        out_file (str, optional): File path to the output colorbar in png format. Defaults to None.
        font_type (str, optional): Font type to use for labels. Defaults to 'arial.ttf'.
        font_size (int, optional): Font size to use for labels. Defaults to 12.
        font_color (str, optional): Font color to use for labels. Defaults to 'black'.
        add_outline (bool, optional): Whether to add an outline to the colorbar. Defaults to True.
        outline_color (str, optional): Color for the outline of the colorbar. Defaults to 'black'.

    Returns:
        str: File path of the output colorbar in png format.

    """
    import decimal

    # import io
    from matplotlib import colors
    from PIL import Image, ImageDraw, ImageFont

    warnings.simplefilter("ignore")
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)

    if out_file is None:
        filename = "colorbar_" + random_string() + ".png"
        out_dir = os.path.join(os.path.expanduser("~"), "Downloads")
        out_file = os.path.join(out_dir, filename)
    elif not out_file.endswith(".png"):
        print("The output file must end with .png")
        return
    else:
        out_file = os.path.abspath(out_file)

    if not os.path.exists(os.path.dirname(out_file)):
        os.makedirs(os.path.dirname(out_file))

    im = Image.new("RGBA", (width, height))
    ld = im.load()

    def float_range(start, stop, step):
        while start < stop:
            yield float(start)
            start += decimal.Decimal(step)

    n_colors = len(palette)
    decimal_places = 2
    rgb_colors = [colors.to_rgb(c) for c in palette]
    keys = [
        round(c, decimal_places)
        for c in list(float_range(0, 1.0001, 1.0 / (n_colors - 1)))
    ]

    heatmap = []
    for index, item in enumerate(keys):
        pair = [item, rgb_colors[index]]
        heatmap.append(pair)

    def gaussian(x, a, b, c, d=0):
        return a * math.exp(-((x - b) ** 2) / (2 * c**2)) + d

    def pixel(x, width=100, map=[], spread=1):
        width = float(width)
        r = sum(
            [
                gaussian(x, p[1][0], p[0] * width, width / (spread * len(map)))
                for p in map
            ]
        )
        g = sum(
            [
                gaussian(x, p[1][1], p[0] * width, width / (spread * len(map)))
                for p in map
            ]
        )
        b = sum(
            [
                gaussian(x, p[1][2], p[0] * width, width / (spread * len(map)))
                for p in map
            ]
        )
        return min(1.0, r), min(1.0, g), min(1.0, b)

    for x in range(im.size[0]):
        r, g, b = pixel(x, width=width, map=heatmap)
        r, g, b = [int(256 * v) for v in (r, g, b)]
        for y in range(im.size[1]):
            ld[x, y] = r, g, b

    if add_outline:
        draw = ImageDraw.Draw(im)
        draw.rectangle(
            [(0, 0), (width - 1, height - 1)], outline=check_color(outline_color)
        )
        del draw

    if add_ticks:
        tick_length = height * 0.1
        x = [key * width for key in keys]
        y_top = height - tick_length
        y_bottom = height
        draw = ImageDraw.Draw(im)
        for i in x:
            shape = [(i, y_top), (i, y_bottom)]
            draw.line(shape, fill="black", width=0)
        del draw

    if vertical:
        im = im.transpose(Image.ROTATE_90)

    width, height = im.size

    if labels is None:
        labels = [str(c) for c in keys]
    elif len(labels) == 2:
        try:
            lowerbound = float(labels[0])
            upperbound = float(labels[1])
            step = (upperbound - lowerbound) / (len(palette) - 1)
            labels = [str(lowerbound + c * step) for c in range(0, len(palette))]
        except Exception as e:
            print(e)
            print("The labels are invalid.")
            return
    elif len(labels) == len(palette):
        labels = [str(c) for c in labels]
    else:
        print("The labels must have the same length as the palette.")
        return

    if add_labels:
        default_font = os.path.join(pkg_dir, "data/fonts/arial.ttf")
        if font_type == "arial.ttf":
            font = ImageFont.truetype(default_font, font_size)
        else:
            try:
                font_list = system_fonts(show_full_path=True)
                font_names = [os.path.basename(f) for f in font_list]
                if (font_type in font_list) or (font_type in font_names):
                    font = ImageFont.truetype(font_type, font_size)
                else:
                    print(
                        "The specified font type could not be found on your system. Using the default font instead."
                    )
                    font = ImageFont.truetype(default_font, font_size)
            except Exception as e:
                print(e)
                font = ImageFont.truetype(default_font, font_size)

        font_color = check_color(font_color)

        draw = ImageDraw.Draw(im)
        w, h = draw.textsize(labels[0], font=font)

        for label in labels:
            w_tmp, h_tmp = draw.textsize(label, font)
            if w_tmp > w:
                w = w_tmp
            if h_tmp > h:
                h = h_tmp

        W, H = width + w * 2, height + h * 2
        background = Image.new("RGBA", (W, H))
        draw = ImageDraw.Draw(background)

        if vertical:
            xy = (0, h)
        else:
            xy = (w, 0)
        background.paste(im, xy, im)

        for index, label in enumerate(labels):
            w_tmp, h_tmp = draw.textsize(label, font)

            if vertical:
                spacing = 5
                x = width + spacing
                y = int(height + h - keys[index] * height - h_tmp / 2 - 1)
                draw.text((x, y), label, font=font, fill=font_color)

            else:
                x = int(keys[index] * width + w - w_tmp / 2)
                spacing = int(h * 0.05)
                y = height + spacing
                draw.text((x, y), label, font=font, fill=font_color)

        im = background.copy()

    im.save(out_file)
    return out_file

create_contours(image, min_value, max_value, interval, kernel=None, region=None, values=None)

Creates contours from an image. Code adapted from https://mygeoblog.com/2017/01/28/contour-lines-in-gee. Credits to MyGeoBlog.

Parameters:

Name	Type	Description	Default
image	Image	An image to create contours.	required
min_value	float	The minimum value of contours.	required
max_value	float	The maximum value of contours.	required
interval	float	The interval between contours.	required
kernel	Kernel	The kernel to use for smoothing image. Defaults to None.	None
region	Geometry | FeatureCollection	The region of interest. Defaults to None.	None
values	list	A list of values to create contours for. Defaults to None.	None

Raises:

Type	Description
TypeError	The image must be an ee.Image.
TypeError	The region must be an ee.Geometry or ee.FeatureCollection.

Returns:

Type	Description
	ee.Image: The image containing contours.

Source code in geemap/common.py

def create_contours(
    image, min_value, max_value, interval, kernel=None, region=None, values=None
):
    """Creates contours from an image. Code adapted from https://mygeoblog.com/2017/01/28/contour-lines-in-gee. Credits to MyGeoBlog.

    Args:
        image (ee.Image): An image to create contours.
        min_value (float): The minimum value of contours.
        max_value (float): The maximum value of contours.
        interval (float):  The interval between contours.
        kernel (ee.Kernel, optional): The kernel to use for smoothing image. Defaults to None.
        region (ee.Geometry | ee.FeatureCollection, optional): The region of interest. Defaults to None.
        values (list, optional): A list of values to create contours for. Defaults to None.

    Raises:
        TypeError: The image must be an ee.Image.
        TypeError: The region must be an ee.Geometry or ee.FeatureCollection.

    Returns:
        ee.Image: The image containing contours.
    """
    if not isinstance(image, ee.Image):
        raise TypeError("The image must be an ee.Image.")
    if region is not None:
        if isinstance(region, ee.FeatureCollection) or isinstance(region, ee.Geometry):
            pass
        else:
            raise TypeError(
                "The region must be an ee.Geometry or ee.FeatureCollection."
            )

    if kernel is None:
        kernel = ee.Kernel.gaussian(5, 3)

    if isinstance(values, list):
        values = ee.List(values)
    elif isinstance(values, ee.List):
        pass

    if values is None:
        values = ee.List.sequence(min_value, max_value, interval)

    def contouring(value):
        mycountour = (
            image.convolve(kernel)
            .subtract(ee.Image.constant(value))
            .zeroCrossing()
            .multiply(ee.Image.constant(value).toFloat())
        )
        return mycountour.mask(mycountour)

    contours = values.map(contouring)

    if region is not None:
        if isinstance(region, ee.FeatureCollection):
            return ee.ImageCollection(contours).mosaic().clipToCollection(region)
        elif isinstance(region, ee.Geometry):
            return ee.ImageCollection(contours).mosaic().clip(region)
    else:
        return ee.ImageCollection(contours).mosaic()

create_download_button(label, data, file_name=None, mime=None, key=None, help=None, on_click=None, args=None, **kwargs)

Streamlit function to create a download button.

Parameters:

Name	Type	Description	Default
label	str	A short label explaining to the user what this button is for..	required
data	str | list	The contents of the file to be downloaded. See example below for caching techniques to avoid recomputing this data unnecessarily.	required
file_name	str	An optional string to use as the name of the file to be downloaded, such as 'my_file.csv'. If not specified, the name will be automatically generated. Defaults to None.	None
mime	str	The MIME type of the data. If None, defaults to "text/plain" (if data is of type str or is a textual file) or "application/octet-stream" (if data is of type bytes or is a binary file). Defaults to None.	None
key	str	An optional string or integer to use as the unique key for the widget. If this is omitted, a key will be generated for the widget based on its content. Multiple widgets of the same type may not share the same key. Defaults to None.	None
help	str	An optional tooltip that gets displayed when the button is hovered over. Defaults to None.	None
on_click	str	An optional callback invoked when this button is clicked. Defaults to None.	None
args	list	An optional tuple of args to pass to the callback. Defaults to None.	None
kwargs	dict	An optional tuple of args to pass to the callback.	{}

Source code in geemap/common.py

def create_download_button(
    label,
    data,
    file_name=None,
    mime=None,
    key=None,
    help=None,
    on_click=None,
    args=None,
    **kwargs,
):
    """Streamlit function to create a download button.

    Args:
        label (str): A short label explaining to the user what this button is for..
        data (str | list): The contents of the file to be downloaded. See example below for caching techniques to avoid recomputing this data unnecessarily.
        file_name (str, optional): An optional string to use as the name of the file to be downloaded, such as 'my_file.csv'. If not specified, the name will be automatically generated. Defaults to None.
        mime (str, optional): The MIME type of the data. If None, defaults to "text/plain" (if data is of type str or is a textual file) or "application/octet-stream" (if data is of type bytes or is a binary file). Defaults to None.
        key (str, optional): An optional string or integer to use as the unique key for the widget. If this is omitted, a key will be generated for the widget based on its content. Multiple widgets of the same type may not share the same key. Defaults to None.
        help (str, optional): An optional tooltip that gets displayed when the button is hovered over. Defaults to None.
        on_click (str, optional): An optional callback invoked when this button is clicked. Defaults to None.
        args (list, optional): An optional tuple of args to pass to the callback. Defaults to None.
        kwargs (dict, optional): An optional tuple of args to pass to the callback.

    """
    try:
        import streamlit as st
        import pandas as pd

        if isinstance(data, str):
            if file_name is None:
                file_name = data.split("/")[-1]

            if data.endswith(".csv"):
                data = pd.read_csv(data).to_csv()
                if mime is None:
                    mime = "text/csv"
                return st.download_button(
                    label, data, file_name, mime, key, help, on_click, args, **kwargs
                )
            elif (
                data.endswith(".gif") or data.endswith(".png") or data.endswith(".jpg")
            ):
                if mime is None:
                    mime = f"image/{os.path.splitext(data)[1][1:]}"

                with open(data, "rb") as file:
                    return st.download_button(
                        label,
                        file,
                        file_name,
                        mime,
                        key,
                        help,
                        on_click,
                        args,
                        **kwargs,
                    )

            else:
                return st.download_button(
                    label,
                    label,
                    data,
                    file_name,
                    mime,
                    key,
                    help,
                    on_click,
                    args,
                    **kwargs,
                )

    except ImportError:
        print("Streamlit is not installed. Please run 'pip install streamlit'.")
        return
    except Exception as e:
        raise Exception(e)

create_download_link(filename, title='Click here to download: ')

Downloads a file from voila. Adopted from https://github.com/voila-dashboards/voila/issues/578

Parameters:

Name	Type	Description	Default
filename	str	The file path to the file to download	required
title	str	str. Defaults to "Click here to download: ".	'Click here to download: '

Returns:

Name	Type	Description
str		HTML download URL.

Source code in geemap/common.py

def create_download_link(filename, title="Click here to download: "):
    """Downloads a file from voila. Adopted from https://github.com/voila-dashboards/voila/issues/578

    Args:
        filename (str): The file path to the file to download
        title (str, optional): str. Defaults to "Click here to download: ".

    Returns:
        str: HTML download URL.
    """
    import base64

    from IPython.display import HTML

    data = open(filename, "rb").read()
    b64 = base64.b64encode(data)
    payload = b64.decode()
    basename = os.path.basename(filename)
    html = '<a download="{filename}" href="data:text/csv;base64,{payload}" style="color:#0000FF;" target="_blank">{title}</a>'
    html = html.format(payload=payload, title=title + f" {basename}", filename=basename)
    return HTML(html)

create_grid(ee_object, scale, proj=None)

Create a grid covering an Earth Engine object.

Parameters:

Name	Type	Description	Default
ee_object	Image | Geometry | FeatureCollection	The Earth Engine object.	required
scale	float	The grid cell size.	required
proj	str	The projection. Defaults to None.	None

Returns:

Type	Description
	ee.FeatureCollection: The grid as a feature collection.

Source code in geemap/common.py

def create_grid(ee_object, scale, proj=None):
    """Create a grid covering an Earth Engine object.

    Args:
        ee_object (ee.Image | ee.Geometry | ee.FeatureCollection): The Earth Engine object.
        scale (float): The grid cell size.
        proj (str, optional): The projection. Defaults to None.


    Returns:
        ee.FeatureCollection: The grid as a feature collection.
    """

    if isinstance(ee_object, ee.FeatureCollection) or isinstance(ee_object, ee.Image):
        geometry = ee_object.geometry()
    elif isinstance(ee_object, ee.Geometry):
        geometry = ee_object
    else:
        raise ValueError(
            "ee_object must be an ee.FeatureCollection, ee.Image, or ee.Geometry"
        )

    if proj is None:
        proj = geometry.projection()

    grid = geometry.coveringGrid(proj, scale)

    return grid

create_legend(title='Legend', labels=None, colors=None, legend_dict=None, builtin_legend=None, opacity=1.0, position='bottomright', draggable=True, output=None, style={})

Create a legend in HTML format. Reference: https://bit.ly/3oV6vnH

Parameters:

Name	Type	Description	Default
title	str	Title of the legend. Defaults to 'Legend'. Defaults to "Legend".	'Legend'
colors	list	A list of legend colors. Defaults to None.	None
labels	list	A list of legend labels. Defaults to None.	None
legend_dict	dict	A dictionary containing legend items as keys and color as values. If provided, legend_keys and legend_colors will be ignored. Defaults to None.	None
builtin_legend	str	Name of the builtin legend to add to the map. Defaults to None.	None
opacity	float	The opacity of the legend. Defaults to 1.0.	1.0
position	str	The position of the legend, can be one of the following: "topleft", "topright", "bottomleft", "bottomright". Defaults to "bottomright".	'bottomright'
draggable	bool	If True, the legend can be dragged to a new position. Defaults to True.	True
output	str	The output file path (*.html) to save the legend. Defaults to None.	None
style		Additional keyword arguments to style the legend, such as position, bottom, right, z-index, border, background-color, border-radius, padding, font-size, etc. The default style is: style = { 'position': 'fixed', 'z-index': '9999', 'border': '2px solid grey', 'background-color': 'rgba(255, 255, 255, 0.8)', 'border-radius': '5px', 'padding': '10px', 'font-size': '14px', 'bottom': '20px', 'right': '5px' }	{}

Returns:

Name	Type	Description
str		The HTML code of the legend.

Source code in geemap/common.py

def create_legend(
    title="Legend",
    labels=None,
    colors=None,
    legend_dict=None,
    builtin_legend=None,
    opacity=1.0,
    position="bottomright",
    draggable=True,
    output=None,
    style={},
):
    """Create a legend in HTML format. Reference: https://bit.ly/3oV6vnH

    Args:
        title (str, optional): Title of the legend. Defaults to 'Legend'. Defaults to "Legend".
        colors (list, optional): A list of legend colors. Defaults to None.
        labels (list, optional): A list of legend labels. Defaults to None.
        legend_dict (dict, optional): A dictionary containing legend items as keys and color as values.
            If provided, legend_keys and legend_colors will be ignored. Defaults to None.
        builtin_legend (str, optional): Name of the builtin legend to add to the map. Defaults to None.
        opacity (float, optional): The opacity of the legend. Defaults to 1.0.
        position (str, optional): The position of the legend, can be one of the following:
            "topleft", "topright", "bottomleft", "bottomright". Defaults to "bottomright".
        draggable (bool, optional): If True, the legend can be dragged to a new position. Defaults to True.
        output (str, optional): The output file path (*.html) to save the legend. Defaults to None.
        style: Additional keyword arguments to style the legend, such as position, bottom, right, z-index,
            border, background-color, border-radius, padding, font-size, etc. The default style is:
            style = {
                'position': 'fixed',
                'z-index': '9999',
                'border': '2px solid grey',
                'background-color': 'rgba(255, 255, 255, 0.8)',
                'border-radius': '5px',
                'padding': '10px',
                'font-size': '14px',
                'bottom': '20px',
                'right': '5px'
            }

    Returns:
        str: The HTML code of the legend.
    """

    from .legends import builtin_legends

    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    legend_template = os.path.join(pkg_dir, "data/template/legend_style.html")

    if draggable:
        legend_template = os.path.join(pkg_dir, "data/template/legend.txt")

    if not os.path.exists(legend_template):
        raise FileNotFoundError("The legend template does not exist.")

    if labels is not None:
        if not isinstance(labels, list):
            print("The legend keys must be a list.")
            return
    else:
        labels = ["One", "Two", "Three", "Four", "etc"]

    if colors is not None:
        if not isinstance(colors, list):
            print("The legend colors must be a list.")
            return
        elif all(isinstance(item, tuple) for item in colors):
            try:
                colors = [rgb_to_hex(x) for x in colors]
            except Exception as e:
                print(e)
        elif all((item.startswith("#") and len(item) == 7) for item in colors):
            pass
        elif all((len(item) == 6) for item in colors):
            pass
        else:
            print("The legend colors must be a list of tuples.")
            return
    else:
        colors = [
            "#8DD3C7",
            "#FFFFB3",
            "#BEBADA",
            "#FB8072",
            "#80B1D3",
        ]

    if len(labels) != len(colors):
        print("The legend keys and values must be the same length.")
        return

    allowed_builtin_legends = builtin_legends.keys()
    if builtin_legend is not None:
        if builtin_legend not in allowed_builtin_legends:
            print(
                "The builtin legend must be one of the following: {}".format(
                    ", ".join(allowed_builtin_legends)
                )
            )
            return
        else:
            legend_dict = builtin_legends[builtin_legend]
            labels = list(legend_dict.keys())
            colors = list(legend_dict.values())

    if legend_dict is not None:
        if not isinstance(legend_dict, dict):
            print("The legend dict must be a dictionary.")
            return
        else:
            labels = list(legend_dict.keys())
            colors = list(legend_dict.values())
            if all(isinstance(item, tuple) for item in colors):
                try:
                    colors = [rgb_to_hex(x) for x in colors]
                except Exception as e:
                    print(e)

    allowed_positions = [
        "topleft",
        "topright",
        "bottomleft",
        "bottomright",
    ]
    if position not in allowed_positions:
        raise ValueError(
            "The position must be one of the following: {}".format(
                ", ".join(allowed_positions)
            )
        )

    if position == "bottomright":
        if "bottom" not in style:
            style["bottom"] = "20px"
        if "right" not in style:
            style["right"] = "5px"
        if "left" in style:
            del style["left"]
        if "top" in style:
            del style["top"]
    elif position == "bottomleft":
        if "bottom" not in style:
            style["bottom"] = "5px"
        if "left" not in style:
            style["left"] = "5px"
        if "right" in style:
            del style["right"]
        if "top" in style:
            del style["top"]
    elif position == "topright":
        if "top" not in style:
            style["top"] = "5px"
        if "right" not in style:
            style["right"] = "5px"
        if "left" in style:
            del style["left"]
        if "bottom" in style:
            del style["bottom"]
    elif position == "topleft":
        if "top" not in style:
            style["top"] = "5px"
        if "left" not in style:
            style["left"] = "5px"
        if "right" in style:
            del style["right"]
        if "bottom" in style:
            del style["bottom"]

    if "position" not in style:
        style["position"] = "fixed"
    if "z-index" not in style:
        style["z-index"] = "9999"
    if "background-color" not in style:
        style["background-color"] = "rgba(255, 255, 255, 0.8)"
    if "padding" not in style:
        style["padding"] = "10px"
    if "border-radius" not in style:
        style["border-radius"] = "5px"
    if "font-size" not in style:
        style["font-size"] = "14px"

    content = []

    with open(legend_template) as f:
        lines = f.readlines()

    if draggable:
        for index, line in enumerate(lines):
            if index < 36:
                content.append(line)
            elif index == 36:
                line = lines[index].replace("Legend", title)
                content.append(line)
            elif index < 39:
                content.append(line)
            elif index == 39:
                for i, color in enumerate(colors):
                    item = f"    <li><span style='background:{check_color(color)};opacity:{opacity};'></span>{labels[i]}</li>\n"
                    content.append(item)
            elif index > 41:
                content.append(line)
        content = content[3:-1]

    else:
        for index, line in enumerate(lines):
            if index < 8:
                content.append(line)
            elif index == 8:
                for key, value in style.items():
                    content.append(
                        "              {}: {};\n".format(key.replace("_", "-"), value)
                    )
            elif index < 17:
                pass
            elif index < 19:
                content.append(line)
            elif index == 19:
                content.append(line.replace("Legend", title))
            elif index < 22:
                content.append(line)
            elif index == 22:
                for index, key in enumerate(labels):
                    color = colors[index]
                    if not color.startswith("#"):
                        color = "#" + color
                    item = "                    <li><span style='background:{};opacity:{};'></span>{}</li>\n".format(
                        color, opacity, key
                    )
                    content.append(item)
            elif index < 33:
                pass
            else:
                content.append(line)

    legend_text = "".join(content)

    if output is not None:
        with open(output, "w") as f:
            f.write(legend_text)
    else:
        return legend_text

create_new_cell(contents, replace=False)

Create a new cell in Jupyter notebook based on the contents.

Parameters:

Name	Type	Description	Default
contents	str	A string of Python code.	required

Source code in geemap/conversion.py

def create_new_cell(contents, replace=False):
    """Create a new cell in Jupyter notebook based on the contents.

    Args:
        contents (str): A string of Python code.
    """
    from IPython.core.getipython import get_ipython

    shell = get_ipython()
    shell.set_next_input(contents, replace=replace)

create_nlcd_qml(out_qml)

Create a QGIS Layer Style (.qml) for NLCD data

Parameters:

Name	Type	Description	Default
out_qml	str	File path to the output qml.	required

Source code in geemap/common.py

def create_nlcd_qml(out_qml):
    """Create a QGIS Layer Style (.qml) for NLCD data

    Args:
        out_qml (str): File path to the output qml.
    """
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    data_dir = os.path.join(pkg_dir, "data")
    template_dir = os.path.join(data_dir, "template")
    qml_template = os.path.join(template_dir, "NLCD.qml")

    out_dir = os.path.dirname(out_qml)
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    shutil.copyfile(qml_template, out_qml)

create_timelapse(collection, start_date, end_date, region=None, bands=None, frequency='year', reducer='median', date_format=None, out_gif=None, palette=None, vis_params=None, dimensions=768, frames_per_second=10, crs='EPSG:3857', overlay_data=None, overlay_color='black', overlay_width=1, overlay_opacity=1.0, title=None, title_xy=('2%', '90%'), add_text=True, text_xy=('2%', '2%'), text_sequence=None, font_type='arial.ttf', font_size=20, font_color='white', add_progress_bar=True, progress_bar_color='white', progress_bar_height=5, add_colorbar=False, colorbar_width=6.0, colorbar_height=0.4, colorbar_label=None, colorbar_label_size=12, colorbar_label_weight='normal', colorbar_tick_size=10, colorbar_bg_color=None, colorbar_orientation='horizontal', colorbar_dpi='figure', colorbar_xy=None, colorbar_size=(300, 300), loop=0, mp4=False, fading=False, parallel_scale=1, step=1)

Create a timelapse from any ee.ImageCollection.

Parameters:

Name	Type	Description	Default
collection	str | ImageCollection	The collection of images to create a timeseries from. It can be a string representing the collection ID or an ee.ImageCollection object.	required
start_date	str	The start date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.	required
end_date	str	The end date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.	required
region	Geometry	The region to use to filter the collection of images. It must be an ee.Geometry object. Defaults to None.	None
bands	list	A list of band names to use in the timelapse. Defaults to None.	None
frequency	str	The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'. Defaults to 'year'.	'year'
reducer	str	The reducer to use to reduce the collection of images to a single value. It can be one of the following: 'median', 'mean', 'min', 'max', 'variance', 'sum'. Defaults to 'median'.	'median'
drop_empty	bool	Whether to drop empty images from the timeseries. Defaults to True.	required
date_format	str	A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.	None
out_gif	str	The output gif file path. Defaults to None.	None
palette	list	A list of colors to render a single-band image in the timelapse. Defaults to None.	None
vis_params	dict	A dictionary of visualization parameters to use in the timelapse. Defaults to None. See more at https://developers.google.com/earth-engine/guides/image_visualization.	None
dimensions	int	a number or pair of numbers (in format 'WIDTHxHEIGHT') Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.	768
frames_per_second	int	Animation speed. Defaults to 10.	10
crs	str	The coordinate reference system to use. Defaults to "EPSG:3857".	'EPSG:3857'
overlay_data	(int, str, list)	Administrative boundary to be drawn on the timelapse. Defaults to None.	None
overlay_color	str	Color for the overlay data. Can be any color name or hex color code. Defaults to 'black'.	'black'
overlay_width	int	Width of the overlay. Defaults to 1.	1
overlay_opacity	float	Opacity of the overlay. Defaults to 1.0.	1.0
title	str	The title of the timelapse. Defaults to None.	None
title_xy	tuple	Lower left corner of the title. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	('2%', '90%')
add_text	bool	Whether to add animated text to the timelapse. Defaults to True.	True
title_xy	tuple	Lower left corner of the text sequency. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	('2%', '90%')
text_sequence	(int, str, list)	Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.	None
font_type	str	Font type. Defaults to "arial.ttf".	'arial.ttf'
font_size	int	Font size. Defaults to 20.	20
font_color	str	Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff'). Defaults to '#000000'.	'white'
add_progress_bar	bool	Whether to add a progress bar at the bottom of the GIF. Defaults to True.	True
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'white'
progress_bar_height	int	Height of the progress bar. Defaults to 5.	5
add_colorbar	bool	Whether to add a colorbar to the timelapse. Defaults to False.	False
colorbar_width	float	Width of the colorbar. Defaults to 6.0.	6.0
colorbar_height	float	Height of the colorbar. Defaults to 0.4.	0.4
colorbar_label	str	Label for the colorbar. Defaults to None.	None
colorbar_label_size	int	Font size for the colorbar label. Defaults to 12.	12
colorbar_label_weight	str	Font weight for the colorbar label. Defaults to 'normal'.	'normal'
colorbar_tick_size	int	Font size for the colorbar ticks. Defaults to 10.	10
colorbar_bg_color	str	Background color for the colorbar, can be color like "white", "black". Defaults to None.	None
colorbar_orientation	str	Orientation of the colorbar. Defaults to 'horizontal'.	'horizontal'
colorbar_dpi	str	DPI for the colorbar, can be numbers like 100, 300. Defaults to 'figure'.	'figure'
colorbar_xy	tuple	Lower left corner of the colorbar. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	None
colorbar_size	tuple	Size of the colorbar. It can be formatted like this: (300, 300). Defaults to (300, 300).	(300, 300)
loop	int	Controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.	0
mp4	bool	Whether to create an mp4 file. Defaults to False.	False
fading	int | bool	If True, add fading effect to the timelapse. Defaults to False, no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).	False
parallel_scale	int	A scaling factor used to limit memory use; using a larger parallel_scale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.	1
step	int	The step size to use when creating the date sequence. Defaults to 1.	1

Returns:

Name	Type	Description
str		File path to the timelapse gif.

Source code in geemap/timelapse.py

def create_timelapse(
    collection,
    start_date,
    end_date,
    region=None,
    bands=None,
    frequency="year",
    reducer="median",
    date_format=None,
    out_gif=None,
    palette=None,
    vis_params=None,
    dimensions=768,
    frames_per_second=10,
    crs="EPSG:3857",
    overlay_data=None,
    overlay_color="black",
    overlay_width=1,
    overlay_opacity=1.0,
    title=None,
    title_xy=("2%", "90%"),
    add_text=True,
    text_xy=("2%", "2%"),
    text_sequence=None,
    font_type="arial.ttf",
    font_size=20,
    font_color="white",
    add_progress_bar=True,
    progress_bar_color="white",
    progress_bar_height=5,
    add_colorbar=False,
    colorbar_width=6.0,
    colorbar_height=0.4,
    colorbar_label=None,
    colorbar_label_size=12,
    colorbar_label_weight="normal",
    colorbar_tick_size=10,
    colorbar_bg_color=None,
    colorbar_orientation="horizontal",
    colorbar_dpi="figure",
    colorbar_xy=None,
    colorbar_size=(300, 300),
    loop=0,
    mp4=False,
    fading=False,
    parallel_scale=1,
    step=1,
):
    """Create a timelapse from any ee.ImageCollection.

    Args:
        collection (str | ee.ImageCollection): The collection of images to create a timeseries from. It can be a string representing the collection ID or an ee.ImageCollection object.
        start_date (str): The start date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.
        end_date (str): The end date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.
        region (ee.Geometry, optional): The region to use to filter the collection of images. It must be an ee.Geometry object. Defaults to None.
        bands (list, optional): A list of band names to use in the timelapse. Defaults to None.
        frequency (str, optional): The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'. Defaults to 'year'.
        reducer (str, optional):  The reducer to use to reduce the collection of images to a single value. It can be one of the following: 'median', 'mean', 'min', 'max', 'variance', 'sum'. Defaults to 'median'.
        drop_empty (bool, optional): Whether to drop empty images from the timeseries. Defaults to True.
        date_format (str, optional): A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.
        out_gif (str): The output gif file path. Defaults to None.
        palette (list, optional): A list of colors to render a single-band image in the timelapse. Defaults to None.
        vis_params (dict, optional): A dictionary of visualization parameters to use in the timelapse. Defaults to None. See more at https://developers.google.com/earth-engine/guides/image_visualization.
        dimensions (int, optional): a number or pair of numbers (in format 'WIDTHxHEIGHT') Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.
        frames_per_second (int, optional): Animation speed. Defaults to 10.
        crs (str, optional): The coordinate reference system to use. Defaults to "EPSG:3857".
        overlay_data (int, str, list, optional): Administrative boundary to be drawn on the timelapse. Defaults to None.
        overlay_color (str, optional): Color for the overlay data. Can be any color name or hex color code. Defaults to 'black'.
        overlay_width (int, optional): Width of the overlay. Defaults to 1.
        overlay_opacity (float, optional): Opacity of the overlay. Defaults to 1.0.
        title (str, optional): The title of the timelapse. Defaults to None.
        title_xy (tuple, optional): Lower left corner of the title. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        add_text (bool, optional): Whether to add animated text to the timelapse. Defaults to True.
        title_xy (tuple, optional): Lower left corner of the text sequency. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.
        font_type (str, optional): Font type. Defaults to "arial.ttf".
        font_size (int, optional): Font size. Defaults to 20.
        font_color (str, optional): Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff').  Defaults to '#000000'.
        add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF. Defaults to True.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
        add_colorbar (bool, optional): Whether to add a colorbar to the timelapse. Defaults to False.
        colorbar_width (float, optional): Width of the colorbar. Defaults to 6.0.
        colorbar_height (float, optional): Height of the colorbar. Defaults to 0.4.
        colorbar_label (str, optional): Label for the colorbar. Defaults to None.
        colorbar_label_size (int, optional): Font size for the colorbar label. Defaults to 12.
        colorbar_label_weight (str, optional): Font weight for the colorbar label. Defaults to 'normal'.
        colorbar_tick_size (int, optional): Font size for the colorbar ticks. Defaults to 10.
        colorbar_bg_color (str, optional): Background color for the colorbar, can be color like "white", "black". Defaults to None.
        colorbar_orientation (str, optional): Orientation of the colorbar. Defaults to 'horizontal'.
        colorbar_dpi (str, optional): DPI for the colorbar, can be numbers like 100, 300. Defaults to 'figure'.
        colorbar_xy (tuple, optional): Lower left corner of the colorbar. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        colorbar_size (tuple, optional): Size of the colorbar. It can be formatted like this: (300, 300). Defaults to (300, 300).
        loop (int, optional): Controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.
        mp4 (bool, optional): Whether to create an mp4 file. Defaults to False.
        fading (int | bool, optional): If True, add fading effect to the timelapse. Defaults to False, no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).
        parallel_scale (int, optional): A scaling factor used to limit memory use; using a larger parallel_scale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.
        step (int, optional): The step size to use when creating the date sequence. Defaults to 1.

    Returns:
        str: File path to the timelapse gif.
    """
    import geemap.colormaps as cm

    if not isinstance(collection, ee.ImageCollection):
        if isinstance(collection, str):
            collection = ee.ImageCollection(collection)
        else:
            raise Exception(
                "The collection must be an ee.ImageCollection object or asset id."
            )

    col = create_timeseries(
        collection,
        start_date,
        end_date,
        region=region,
        bands=bands,
        frequency=frequency,
        reducer=reducer,
        drop_empty=True,
        date_format=date_format,
        parallel_scale=parallel_scale,
        step=step,
    )

    # rename the bands to remove the '_reducer' characters from the band names.
    col = col.map(
        lambda img: img.rename(
            img.bandNames().map(lambda name: ee.String(name).replace(f"_{reducer}", ""))
        )
    )

    if out_gif is None:
        out_gif = temp_file_path(".gif")
    else:
        out_gif = check_file_path(out_gif)

    out_dir = os.path.dirname(out_gif)

    if bands is None:
        names = col.first().bandNames().getInfo()
        if len(names) < 3:
            bands = [names[0]]
        else:
            bands = names[:3][::-1]
    elif isinstance(bands, str):
        bands = [bands]
    elif not isinstance(bands, list):
        raise Exception("The bands must be a string or a list of strings.")

    if isinstance(palette, str):
        palette = cm.get_palette(palette, 15)
    elif isinstance(palette, list) or isinstance(palette, tuple):
        pass
    elif palette is not None:
        raise Exception("The palette must be a string or a list of strings.")

    if vis_params is None:
        img = col.first().select(bands)
        scale = collection.first().select(0).projection().nominalScale().multiply(10)
        min_value = min(
            image_min_value(img, region=region, scale=scale).getInfo().values()
        )
        max_value = max(
            image_max_value(img, region=region, scale=scale).getInfo().values()
        )
        vis_params = {"bands": bands, "min": min_value, "max": max_value}

        if len(bands) == 1:
            if palette is not None:
                vis_params["palette"] = palette
            else:
                vis_params["palette"] = cm.palettes.ndvi
    elif isinstance(vis_params, dict):
        if "bands" not in vis_params:
            vis_params["bands"] = bands
        if "min" not in vis_params:
            img = col.first().select(bands)
            scale = (
                collection.first().select(0).projection().nominalScale().multiply(10)
            )
            vis_params["min"] = min(
                image_min_value(img, region=region, scale=scale).getInfo().values()
            )
        if "max" not in vis_params:
            img = col.first().select(bands)
            scale = (
                collection.first().select(0).projection().nominalScale().multiply(10)
            )
            vis_params["max"] = max(
                image_max_value(img, region=region, scale=scale).getInfo().values()
            )
        if palette is None and (len(bands) == 1) and ("palette" not in vis_params):
            vis_params["palette"] = cm.palettes.ndvi
        elif palette is not None and ("palette" not in vis_params):
            vis_params["palette"] = palette
        if len(bands) > 1 and "palette" in vis_params:
            del vis_params["palette"]
    else:
        raise Exception("The vis_params must be a dictionary.")

    col = col.select(bands).map(
        lambda img: img.visualize(**vis_params).set(
            {
                "system:time_start": img.get("system:time_start"),
                "system:date": img.get("system:date"),
            }
        )
    )

    if overlay_data is not None:
        col = add_overlay(
            col, overlay_data, overlay_color, overlay_width, overlay_opacity
        )

    video_args = {}
    video_args["dimensions"] = dimensions
    video_args["region"] = region
    video_args["framesPerSecond"] = frames_per_second
    video_args["crs"] = crs
    video_args["min"] = 0
    video_args["max"] = 255

    # if crs is not None:
    #     video_args["crs"] = crs

    if "palette" in vis_params or len(bands) > 1:
        video_args["bands"] = ["vis-red", "vis-green", "vis-blue"]
    else:
        video_args["bands"] = ["vis-gray"]

    if (
        isinstance(dimensions, int)
        and dimensions > 768
        or isinstance(dimensions, str)
        and any(dim > 768 for dim in list(map(int, dimensions.split("x"))))
    ):
        count = col.size().getInfo()
        basename = os.path.basename(out_gif)[:-4]
        names = [
            os.path.join(
                out_dir, f"{basename}_{str(i+1).zfill(int(len(str(count))))}.jpg"
            )
            for i in range(count)
        ]
        get_image_collection_thumbnails(
            col,
            out_dir,
            vis_params={
                "min": 0,
                "max": 255,
                "bands": video_args["bands"],
            },
            dimensions=dimensions,
            names=names,
        )
        make_gif(
            names,
            out_gif,
            fps=frames_per_second,
            loop=loop,
            mp4=False,
            clean_up=True,
        )
    else:
        download_ee_video(col, video_args, out_gif)

    if title is not None and isinstance(title, str):
        add_text_to_gif(
            out_gif,
            out_gif,
            xy=title_xy,
            text_sequence=title,
            font_type=font_type,
            font_size=font_size,
            font_color=font_color,
            add_progress_bar=add_progress_bar,
            progress_bar_color=progress_bar_color,
            progress_bar_height=progress_bar_height,
            duration=1000 / frames_per_second,
            loop=loop,
        )
    if add_text:
        if text_sequence is None:
            text_sequence = col.aggregate_array("system:date").getInfo()
        add_text_to_gif(
            out_gif,
            out_gif,
            xy=text_xy,
            text_sequence=text_sequence,
            font_type=font_type,
            font_size=font_size,
            font_color=font_color,
            add_progress_bar=add_progress_bar,
            progress_bar_color=progress_bar_color,
            progress_bar_height=progress_bar_height,
            duration=1000 / frames_per_second,
            loop=loop,
        )
    if add_colorbar:
        colorbar = save_colorbar(
            None,
            colorbar_width,
            colorbar_height,
            vis_params["min"],
            vis_params["max"],
            vis_params["palette"],
            label=colorbar_label,
            label_size=colorbar_label_size,
            label_weight=colorbar_label_weight,
            tick_size=colorbar_tick_size,
            bg_color=colorbar_bg_color,
            orientation=colorbar_orientation,
            dpi=colorbar_dpi,
            show_colorbar=False,
        )
        add_image_to_gif(out_gif, out_gif, colorbar, colorbar_xy, colorbar_size)

    if os.path.exists(out_gif):
        reduce_gif_size(out_gif)

    if isinstance(fading, bool):
        fading = int(fading)
    if fading > 0:
        gif_fading(out_gif, out_gif, duration=fading, verbose=False)

    if mp4:
        out_mp4 = out_gif.replace(".gif", ".mp4")
        gif_to_mp4(out_gif, out_mp4)

    return out_gif

create_timeseries(collection, start_date, end_date, region=None, bands=None, frequency='year', reducer='median', drop_empty=True, date_format=None, parallel_scale=1, step=1)

Creates a timeseries from a collection of images by a specified frequency and reducer.

Parameters:

Name	Type	Description	Default
collection	str | ImageCollection	The collection of images to create a timeseries from. It can be a string representing the collection ID or an ee.ImageCollection object.	required
start_date	str	The start date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.	required
end_date	str	The end date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.	required
region	Geometry	The region to use to filter the collection of images. It must be an ee.Geometry object. Defaults to None.	None
bands	list	The list of bands to use to create the timeseries. It must be a list of strings. Defaults to None.	None
frequency	str	The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'. Defaults to 'year'.	'year'
reducer	str	The reducer to use to reduce the collection of images to a single value. It can be one of the following: 'median', 'mean', 'min', 'max', 'variance', 'sum'. Defaults to 'median'.	'median'
drop_empty	bool	Whether to drop empty images from the timeseries. Defaults to True.	True
date_format	str	A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.	None
parallel_scale	int	A scaling factor used to limit memory use; using a larger parallel_scale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.	1
step	int	The step size to use when creating the date sequence. Defaults to 1.	1

Returns:

Type	Description
	ee.ImageCollection: The timeseries.

Source code in geemap/timelapse.py

def create_timeseries(
    collection,
    start_date,
    end_date,
    region=None,
    bands=None,
    frequency="year",
    reducer="median",
    drop_empty=True,
    date_format=None,
    parallel_scale=1,
    step=1,
):
    """Creates a timeseries from a collection of images by a specified frequency and reducer.

    Args:
        collection (str | ee.ImageCollection): The collection of images to create a timeseries from. It can be a string representing the collection ID or an ee.ImageCollection object.
        start_date (str): The start date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.
        end_date (str): The end date of the timeseries. It must be formatted like this: 'YYYY-MM-dd'.
        region (ee.Geometry, optional): The region to use to filter the collection of images. It must be an ee.Geometry object. Defaults to None.
        bands (list, optional): The list of bands to use to create the timeseries. It must be a list of strings. Defaults to None.
        frequency (str, optional): The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'. Defaults to 'year'.
        reducer (str, optional):  The reducer to use to reduce the collection of images to a single value. It can be one of the following: 'median', 'mean', 'min', 'max', 'variance', 'sum'. Defaults to 'median'.
        drop_empty (bool, optional): Whether to drop empty images from the timeseries. Defaults to True.
        date_format (str, optional): A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.
        parallel_scale (int, optional): A scaling factor used to limit memory use; using a larger parallel_scale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.
        step (int, optional): The step size to use when creating the date sequence. Defaults to 1.

    Returns:
        ee.ImageCollection: The timeseries.
    """
    if not isinstance(collection, ee.ImageCollection):
        if isinstance(collection, str):
            collection = ee.ImageCollection(collection)
        else:
            raise Exception(
                "The collection must be an ee.ImageCollection object or asset id."
            )

    if bands is not None:
        collection = collection.select(bands)
    else:
        bands = collection.first().bandNames()

    feq_dict = {
        "year": "YYYY",
        "month": "YYYY-MM",
        "quarter": "YYYY-MM",
        "week": "YYYY-MM-dd",
        "day": "YYYY-MM-dd",
        "hour": "YYYY-MM-dd HH",
        "minute": "YYYY-MM-dd HH:mm",
        "second": "YYYY-MM-dd HH:mm:ss",
    }

    if date_format is None:
        date_format = feq_dict[frequency]

    dates = date_sequence(start_date, end_date, frequency, date_format, step)

    try:
        reducer = eval(f"ee.Reducer.{reducer}()")
    except Exception as e:
        print("The provided reducer is invalid.")
        raise Exception(e)

    def create_image(date):
        start = ee.Date(date)
        if frequency == "quarter":
            end = start.advance(3, "month")
        else:
            end = start.advance(1, frequency)

        if region is None:
            sub_col = collection.filterDate(start, end)
            image = sub_col.reduce(reducer, parallel_scale)

        else:
            sub_col = collection.filterDate(start, end).filterBounds(region)
            image = ee.Image(
                ee.Algorithms.If(
                    ee.Algorithms.ObjectType(region).equals("FeatureCollection"),
                    sub_col.reduce(reducer, parallel_scale).clipToCollection(region),
                    sub_col.reduce(reducer, parallel_scale).clip(region),
                )
            )
        return image.set(
            {
                "system:time_start": ee.Date(date).millis(),
                "system:date": ee.Date(date).format(date_format),
                "empty": sub_col.limit(1).size().eq(0),
            }
        ).rename(bands)

    try:
        images = ee.ImageCollection(dates.map(create_image))
        if drop_empty:
            return images.filterMetadata("empty", "equals", 0)
        else:
            return images
    except Exception as e:
        raise Exception(e)

credentials_in_colab()

Checks if the ee credentials file exists in Google Colab.

Returns:

Name	Type	Description
bool		Returns True if Google Drive is mounted, False otherwise.

Source code in geemap/common.py

def credentials_in_colab():
    """Checks if the ee credentials file exists in Google Colab.

    Returns:
        bool: Returns True if Google Drive is mounted, False otherwise.
    """
    credentials_path = "/root/.config/earthengine/credentials"
    if os.path.exists(credentials_path):
        return True
    else:
        return False

credentials_in_drive()

Checks if the ee credentials file exists in Google Drive.

Returns:

Name	Type	Description
bool		Returns True if Google Drive is mounted, False otherwise.

Source code in geemap/common.py

def credentials_in_drive():
    """Checks if the ee credentials file exists in Google Drive.

    Returns:
        bool: Returns True if Google Drive is mounted, False otherwise.
    """
    credentials_path = "/content/drive/My Drive/.config/earthengine/credentials"
    if os.path.exists(credentials_path):
        return True
    else:
        return False

csv_points_to_shp(in_csv, out_shp, latitude='latitude', longitude='longitude')

Converts a csv file containing points (latitude, longitude) into a shapefile.

Parameters:

Name	Type	Description	Default
in_csv	str	File path or HTTP URL to the input csv file. For example, https://raw.githubusercontent.com/giswqs/data/main/world/world_cities.csv	required
out_shp	str	File path to the output shapefile.	required
latitude	str	Column name for the latitude column. Defaults to 'latitude'.	'latitude'
longitude	str	Column name for the longitude column. Defaults to 'longitude'.	'longitude'

Source code in geemap/common.py

def csv_points_to_shp(in_csv, out_shp, latitude="latitude", longitude="longitude"):
    """Converts a csv file containing points (latitude, longitude) into a shapefile.

    Args:
        in_csv (str): File path or HTTP URL to the input csv file. For example, https://raw.githubusercontent.com/giswqs/data/main/world/world_cities.csv
        out_shp (str): File path to the output shapefile.
        latitude (str, optional): Column name for the latitude column. Defaults to 'latitude'.
        longitude (str, optional): Column name for the longitude column. Defaults to 'longitude'.

    """
    import whitebox

    if in_csv.startswith("http") and in_csv.endswith(".csv"):
        out_dir = os.path.join(os.path.expanduser("~"), "Downloads")
        out_name = os.path.basename(in_csv)

        if not os.path.exists(out_dir):
            os.makedirs(out_dir)
        download_from_url(in_csv, out_dir=out_dir, verbose=False)
        in_csv = os.path.join(out_dir, out_name)

    wbt = whitebox.WhiteboxTools()
    in_csv = os.path.abspath(in_csv)
    out_shp = os.path.abspath(out_shp)

    if not os.path.exists(in_csv):
        raise Exception("The provided csv file does not exist.")

    with open(in_csv, encoding="utf-8") as csv_file:
        reader = csv.DictReader(csv_file)
        fields = reader.fieldnames
        xfield = fields.index(longitude)
        yfield = fields.index(latitude)

    wbt.csv_points_to_vector(in_csv, out_shp, xfield=xfield, yfield=yfield, epsg=4326)

csv_to_df(in_csv, **kwargs)

Converts a CSV file to pandas dataframe.

Parameters:

Name	Type	Description	Default
in_csv	str	File path to the input CSV.	required

Returns:

Type	Description
	pd.DataFrame: pandas DataFrame

Source code in geemap/common.py

def csv_to_df(in_csv, **kwargs):
    """Converts a CSV file to pandas dataframe.

    Args:
        in_csv (str): File path to the input CSV.

    Returns:
        pd.DataFrame: pandas DataFrame
    """
    import pandas as pd

    in_csv = github_raw_url(in_csv)

    try:
        return pd.read_csv(in_csv, **kwargs)
    except Exception as e:
        raise Exception(e)

csv_to_ee(in_csv, latitude='latitude', longitude='longitude', encoding='utf-8', geodesic=True)

Creates points for a CSV file and exports data as a GeoJSON.

Parameters:

Name	Type	Description	Default
in_csv	str	The file path to the input CSV file.	required
latitude	str	The name of the column containing latitude coordinates. Defaults to "latitude".	'latitude'
longitude	str	The name of the column containing longitude coordinates. Defaults to "longitude".	'longitude'
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'
geodesic	bool	Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected.	True

Returns:

Name	Type	Description
ee_object		An ee.Geometry object

Source code in geemap/common.py

def csv_to_ee(
    in_csv, latitude="latitude", longitude="longitude", encoding="utf-8", geodesic=True
):
    """Creates points for a CSV file and exports data as a GeoJSON.

    Args:
        in_csv (str): The file path to the input CSV file.
        latitude (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
        longitude (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".
        geodesic (bool, optional): Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected.

    Returns:
        ee_object: An ee.Geometry object
    """

    geojson = csv_to_geojson(
        in_csv, latitude=latitude, longitude=longitude, encoding=encoding
    )
    fc = geojson_to_ee(geojson, geodesic=geodesic)
    return fc

csv_to_gdf(in_csv, latitude='latitude', longitude='longitude', encoding='utf-8')

Creates points for a CSV file and converts them to a GeoDataFrame.

Parameters:

Name	Type	Description	Default
in_csv	str	The file path to the input CSV file.	required
latitude	str	The name of the column containing latitude coordinates. Defaults to "latitude".	'latitude'
longitude	str	The name of the column containing longitude coordinates. Defaults to "longitude".	'longitude'
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'

Returns:

Name	Type	Description
object		GeoDataFrame.

Source code in geemap/common.py

def csv_to_gdf(in_csv, latitude="latitude", longitude="longitude", encoding="utf-8"):
    """Creates points for a CSV file and converts them to a GeoDataFrame.

    Args:
        in_csv (str): The file path to the input CSV file.
        latitude (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
        longitude (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".

    Returns:
        object: GeoDataFrame.
    """

    check_package(name="geopandas", URL="https://geopandas.org")

    import geopandas as gpd

    out_dir = os.getcwd()

    out_geojson = os.path.join(out_dir, random_string() + ".geojson")
    csv_to_geojson(in_csv, out_geojson, latitude, longitude, encoding)

    gdf = gpd.read_file(out_geojson)
    os.remove(out_geojson)
    return gdf

csv_to_geojson(in_csv, out_geojson=None, latitude='latitude', longitude='longitude', encoding='utf-8')

Creates points for a CSV file and exports data as a GeoJSON.

Parameters:

Name	Type	Description	Default
in_csv	str	The file path to the input CSV file.	required
out_geojson	str	The file path to the exported GeoJSON. Default to None.	None
latitude	str	The name of the column containing latitude coordinates. Defaults to "latitude".	'latitude'
longitude	str	The name of the column containing longitude coordinates. Defaults to "longitude".	'longitude'
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'

Source code in geemap/common.py

def csv_to_geojson(
    in_csv,
    out_geojson=None,
    latitude="latitude",
    longitude="longitude",
    encoding="utf-8",
):
    """Creates points for a CSV file and exports data as a GeoJSON.

    Args:
        in_csv (str): The file path to the input CSV file.
        out_geojson (str): The file path to the exported GeoJSON. Default to None.
        latitude (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
        longitude (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".

    """

    import pandas as pd

    in_csv = github_raw_url(in_csv)

    if out_geojson is not None:
        out_geojson = check_file_path(out_geojson)

    df = pd.read_csv(in_csv)
    geojson = df_to_geojson(
        df, latitude=latitude, longitude=longitude, encoding=encoding
    )

    if out_geojson is None:
        return geojson
    else:
        with open(out_geojson, "w", encoding=encoding) as f:
            f.write(json.dumps(geojson))

csv_to_shp(in_csv, out_shp, latitude='latitude', longitude='longitude', encoding='utf-8')

Converts a csv file with latlon info to a point shapefile.

Parameters:

Name	Type	Description	Default
in_csv	str	The input csv file containing longitude and latitude columns.	required
out_shp	str	The file path to the output shapefile.	required
latitude	str	The column name of the latitude column. Defaults to 'latitude'.	'latitude'
longitude	str	The column name of the longitude column. Defaults to 'longitude'.	'longitude'

Source code in geemap/common.py

def csv_to_shp(
    in_csv, out_shp, latitude="latitude", longitude="longitude", encoding="utf-8"
):
    """Converts a csv file with latlon info to a point shapefile.

    Args:
        in_csv (str): The input csv file containing longitude and latitude columns.
        out_shp (str): The file path to the output shapefile.
        latitude (str, optional): The column name of the latitude column. Defaults to 'latitude'.
        longitude (str, optional): The column name of the longitude column. Defaults to 'longitude'.
    """
    import shapefile as shp

    if in_csv.startswith("http") and in_csv.endswith(".csv"):
        in_csv = github_raw_url(in_csv)
        in_csv = download_file(in_csv, quiet=True, overwrite=True)

    try:
        points = shp.Writer(out_shp, shapeType=shp.POINT)
        with open(in_csv, encoding=encoding) as csvfile:
            csvreader = csv.DictReader(csvfile)
            header = csvreader.fieldnames
            [points.field(field) for field in header]
            for row in csvreader:
                points.point((float(row[longitude])), (float(row[latitude])))
                points.record(*tuple([row[f] for f in header]))

        out_prj = out_shp.replace(".shp", ".prj")
        with open(out_prj, "w") as f:
            prj_str = 'GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Degree",0.0174532925199433]] '
            f.write(prj_str)

    except Exception as e:
        raise Exception(e)

csv_to_vector(in_csv, output, latitude='latitude', longitude='longitude', encoding='utf-8', **kwargs)

Creates points for a CSV file and converts them to a vector dataset.

Parameters:

Name	Type	Description	Default
in_csv	str	The file path to the input CSV file.	required
output	str	The file path to the output vector dataset.	required
latitude	str	The name of the column containing latitude coordinates. Defaults to "latitude".	'latitude'
longitude	str	The name of the column containing longitude coordinates. Defaults to "longitude".	'longitude'
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'

Source code in geemap/common.py

def csv_to_vector(
    in_csv,
    output,
    latitude="latitude",
    longitude="longitude",
    encoding="utf-8",
    **kwargs,
):
    """Creates points for a CSV file and converts them to a vector dataset.

    Args:
        in_csv (str): The file path to the input CSV file.
        output (str): The file path to the output vector dataset.
        latitude (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
        longitude (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".

    """
    gdf = csv_to_gdf(in_csv, latitude, longitude, encoding)
    gdf.to_file(output, **kwargs)

date_sequence(start, end, unit, date_format='YYYY-MM-dd', step=1)

Creates a date sequence.

Parameters:

Name	Type	Description	Default
start	str	The start date, e.g., '2000-01-01'.	required
end	str	The end date, e.g., '2000-12-31'.	required
unit	str	One of 'year', 'quarter', 'month' 'week', 'day', 'hour', 'minute', or 'second'.	required
date_format	str	A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.	'YYYY-MM-dd'
step	int	The step size. Defaults to 1.	1

Returns:

Type	Description
	ee.List: A list of date sequence.

Source code in geemap/common.py

def date_sequence(start, end, unit, date_format="YYYY-MM-dd", step=1):
    """Creates a date sequence.

    Args:
        start (str): The start date, e.g., '2000-01-01'.
        end (str): The end date, e.g., '2000-12-31'.
        unit (str): One of 'year', 'quarter', 'month' 'week', 'day', 'hour', 'minute', or 'second'.
        date_format (str, optional): A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.
        step (int, optional): The step size. Defaults to 1.

    Returns:
        ee.List: A list of date sequence.
    """

    def get_quarter(d):
        return str((int(d[5:7]) - 1) // 3 * 3 + 1).zfill(2)

    def get_monday(d):
        date_obj = datetime.datetime.strptime(d, "%Y-%m-%d")
        start_of_week = date_obj - datetime.timedelta(days=date_obj.weekday())
        return start_of_week.strftime("%Y-%m-%d")

    if unit == "year":
        start = start[:4] + "-01-01"
    elif unit == "month":
        start = start[:7] + "-01"
    elif unit == "quarter":
        start = start[:5] + get_quarter(start) + "-01"
    elif unit == "week":
        start = get_monday(start)

    start_date = ee.Date(start)
    end_date = ee.Date(end)

    if unit != "quarter":
        count = ee.Number(end_date.difference(start_date, unit)).toInt()
        num_seq = ee.List.sequence(0, count)
        if step > 1:
            num_seq = num_seq.slice(0, num_seq.size(), step)
        date_seq = num_seq.map(
            lambda d: start_date.advance(d, unit).format(date_format)
        )

    else:
        unit = "month"
        count = ee.Number(end_date.difference(start_date, unit)).divide(3).toInt()
        num_seq = ee.List.sequence(0, count.multiply(3), 3)
        date_seq = num_seq.map(
            lambda d: start_date.advance(d, unit).format(date_format)
        )

    return date_seq

delete_shp(in_shp, verbose=False)

Deletes a shapefile.

Parameters:

Name	Type	Description	Default
in_shp	str	The input shapefile to delete.	required
verbose	bool	Whether to print out descriptive text. Defaults to False.	False

Source code in geemap/common.py

def delete_shp(in_shp, verbose=False):
    """Deletes a shapefile.

    Args:
        in_shp (str): The input shapefile to delete.
        verbose (bool, optional): Whether to print out descriptive text. Defaults to False.
    """
    from pathlib import Path

    in_shp = os.path.abspath(in_shp)
    in_dir = os.path.dirname(in_shp)
    basename = os.path.basename(in_shp).replace(".shp", "")

    files = Path(in_dir).rglob(basename + ".*")

    for file in files:
        filepath = os.path.join(in_dir, str(file))
        try:
            os.remove(filepath)
            if verbose:
                print(f"Deleted {filepath}")
        except Exception as e:
            if verbose:
                print(e)

df_to_ee(df, latitude='latitude', longitude='longitude', **kwargs)

Converts a pandas DataFrame to ee.FeatureCollection.

Parameters:

Name	Type	Description	Default
df	DataFrame	An input pandas.DataFrame.	required
latitude	str	Column name for the latitude column. Defaults to 'latitude'.	'latitude'
longitude	str	Column name for the longitude column. Defaults to 'longitude'.	'longitude'

Raises:

Type	Description
TypeError	The input data type must be pandas.DataFrame.

Returns:

Type	Description
	ee.FeatureCollection: The ee.FeatureCollection converted from the input pandas DataFrame.

Source code in geemap/common.py

def df_to_ee(df, latitude="latitude", longitude="longitude", **kwargs):
    """Converts a pandas DataFrame to ee.FeatureCollection.

    Args:
        df (pandas.DataFrame): An input pandas.DataFrame.
        latitude (str, optional): Column name for the latitude column. Defaults to 'latitude'.
        longitude (str, optional): Column name for the longitude column. Defaults to 'longitude'.

    Raises:
        TypeError: The input data type must be pandas.DataFrame.

    Returns:
        ee.FeatureCollection: The ee.FeatureCollection converted from the input pandas DataFrame.
    """
    import pandas as pd

    if not isinstance(df, pd.DataFrame):
        raise TypeError("The input data type must be pandas.DataFrame.")

    geojson = df_to_geojson(df, latitude=latitude, longitude=longitude)
    fc = geojson_to_ee(geojson)

    return fc

df_to_geojson(df, out_geojson=None, latitude='latitude', longitude='longitude', encoding='utf-8')

Creates points for a Pandas DataFrame and exports data as a GeoJSON.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input Pandas DataFrame.	required
out_geojson	str	The file path to the exported GeoJSON. Default to None.	None
latitude	str	The name of the column containing latitude coordinates. Defaults to "latitude".	'latitude'
longitude	str	The name of the column containing longitude coordinates. Defaults to "longitude".	'longitude'
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'

Source code in geemap/common.py

def df_to_geojson(
    df,
    out_geojson=None,
    latitude="latitude",
    longitude="longitude",
    encoding="utf-8",
):
    """Creates points for a Pandas DataFrame and exports data as a GeoJSON.

    Args:
        df (pandas.DataFrame): The input Pandas DataFrame.
        out_geojson (str): The file path to the exported GeoJSON. Default to None.
        latitude (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
        longitude (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".

    """

    from geojson import Feature, FeatureCollection, Point

    if out_geojson is not None:
        out_dir = os.path.dirname(os.path.abspath(out_geojson))
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)

    features = df.apply(
        lambda row: Feature(
            geometry=Point((float(row[longitude]), float(row[latitude]))),
            properties=dict(row),
        ),
        axis=1,
    ).tolist()

    geojson = FeatureCollection(features=features)

    if out_geojson is None:
        return geojson
    else:
        with open(out_geojson, "w", encoding=encoding) as f:
            f.write(json.dumps(geojson))

dict_to_csv(data_dict, out_csv, by_row=False, timeout=300, proxies=None)

Downloads an ee.Dictionary as a CSV file.

Parameters:

Name	Type	Description	Default
data_dict	Dictionary	The input ee.Dictionary.	required
out_csv	str	The output file path to the CSV file.	required
by_row	bool	Whether to use by row or by column. Defaults to False.	False
timeout	int	Timeout in seconds. Defaults to 300 seconds.	300
proxies	dict	Proxy settings. Defaults to None.	None

Source code in geemap/common.py

def dict_to_csv(data_dict, out_csv, by_row=False, timeout=300, proxies=None):
    """Downloads an ee.Dictionary as a CSV file.

    Args:
        data_dict (ee.Dictionary): The input ee.Dictionary.
        out_csv (str): The output file path to the CSV file.
        by_row (bool, optional): Whether to use by row or by column. Defaults to False.
        timeout (int, optional): Timeout in seconds. Defaults to 300 seconds.
        proxies (dict, optional): Proxy settings. Defaults to None.
    """

    out_dir = os.path.dirname(out_csv)
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if not by_row:
        csv_feature = ee.Feature(None, data_dict)
        csv_feat_col = ee.FeatureCollection([csv_feature])
    else:
        keys = data_dict.keys()
        data = keys.map(lambda k: ee.Dictionary({"name": k, "value": data_dict.get(k)}))
        csv_feature = data.map(lambda f: ee.Feature(None, f))
        csv_feat_col = ee.FeatureCollection(csv_feature)

    ee_export_vector(csv_feat_col, out_csv, timeout=timeout, proxies=proxies)

display_html(src, width=950, height=600)

Display an HTML file in a Jupyter Notebook.

Args src (str): File path to HTML file. width (int, optional): Width of the map. Defaults to 950. height (int, optional): Height of the map. Defaults to 600.

Source code in geemap/common.py

def display_html(src, width=950, height=600):
    """Display an HTML file in a Jupyter Notebook.

    Args
        src (str): File path to HTML file.
        width (int, optional): Width of the map. Defaults to 950.
        height (int, optional): Height of the map. Defaults to 600.
    """
    if not os.path.isfile(src):
        raise ValueError(f"{src} is not a valid file path.")
    display(IFrame(src=src, width=width, height=height))

download_ee_image(image, filename, region=None, crs=None, crs_transform=None, scale=None, resampling='near', dtype=None, overwrite=True, num_threads=None, max_tile_size=None, max_tile_dim=None, shape=None, scale_offset=False, unmask_value=None, **kwargs)

Download an Earth Engine Image as a GeoTIFF. Images larger than the `Earth Engine size limit are split and downloaded as separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

Parameters:

Name	Type	Description	Default
image	Image	The image to be downloaded.	required
filename	str	Name of the destination file.	required
region	Geometry	Region defined by geojson polygon in WGS84. Defaults to the entire image granule.	None
crs	str	Reproject image(s) to this EPSG or WKT CRS. Where image bands have different CRSs, all are re-projected to this CRS. Defaults to the CRS of the minimum scale band.	None
crs_transform	list	tuple of float, list of float, rio.Affine, optional List of 6 numbers specifying an affine transform in the specified CRS. In row-major order: [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation]. All bands are re-projected to this transform.	None
scale	float	Resample image(s) to this pixel scale (size) (m). Where image bands have different scales, all are resampled to this scale. Defaults to the minimum scale of image bands.	None
resampling	ResamplingMethod	Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.	'near'
dtype	str	Convert to this data type (uint8, int8, uint16, int16, uint32, int32, float32 or float64). Defaults to auto select a minimum size type that can represent the range of pixel values.	None
overwrite	bool	Overwrite the destination file if it exists. Defaults to True.	True
num_threads	int	Number of tiles to download concurrently. Defaults to a sensible auto value.	None
max_tile_size		int, optional Maximum tile size (MB). If None, defaults to the Earth Engine download size limit (32 MB).	None
max_tile_dim		int, optional Maximum tile width/height (pixels). If None, defaults to Earth Engine download limit (10000).	None
shape		tuple of int, optional (height, width) dimensions to export (pixels).	None
scale_offset		bool, optional Whether to apply any EE band scales and offsets to the image.	False
unmask_value	float	The value to use for pixels that are masked in the input image. If the exported image contains zero values, you should set the unmask value to a non-zero value so that the zero values are not treated as missing data. Defaults to None.	None

Source code in geemap/common.py

def download_ee_image(
    image,
    filename,
    region=None,
    crs=None,
    crs_transform=None,
    scale=None,
    resampling="near",
    dtype=None,
    overwrite=True,
    num_threads=None,
    max_tile_size=None,
    max_tile_dim=None,
    shape=None,
    scale_offset=False,
    unmask_value=None,
    **kwargs,
):
    """Download an Earth Engine Image as a GeoTIFF. Images larger than the `Earth Engine size limit are split and downloaded as
        separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

    Args:
        image (ee.Image): The image to be downloaded.
        filename (str): Name of the destination file.
        region (ee.Geometry, optional): Region defined by geojson polygon in WGS84. Defaults to the entire image granule.
        crs (str, optional): Reproject image(s) to this EPSG or WKT CRS.  Where image bands have different CRSs, all are
            re-projected to this CRS. Defaults to the CRS of the minimum scale band.
        crs_transform (list, optional): tuple of float, list of float, rio.Affine, optional
            List of 6 numbers specifying an affine transform in the specified CRS.  In row-major order:
            [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation].  All bands are re-projected to
            this transform.
        scale (float, optional): Resample image(s) to this pixel scale (size) (m).  Where image bands have different scales,
            all are resampled to this scale.  Defaults to the minimum scale of image bands.
        resampling (ResamplingMethod, optional): Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.
        dtype (str, optional): Convert to this data type (`uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `float32`
            or `float64`).  Defaults to auto select a minimum size type that can represent the range of pixel values.
        overwrite (bool, optional): Overwrite the destination file if it exists. Defaults to True.
        num_threads (int, optional): Number of tiles to download concurrently. Defaults to a sensible auto value.
        max_tile_size: int, optional
            Maximum tile size (MB).  If None, defaults to the Earth Engine download size limit (32 MB).
        max_tile_dim: int, optional
            Maximum tile width/height (pixels).  If None, defaults to Earth Engine download limit (10000).
        shape: tuple of int, optional
            (height, width) dimensions to export (pixels).
        scale_offset: bool, optional
            Whether to apply any EE band scales and offsets to the image.
        unmask_value (float, optional): The value to use for pixels that are masked in the input image. If the exported image contains
            zero values, you should set the unmask value to a  non-zero value so that the zero values are not treated as missing data. Defaults to None.

    """

    if os.environ.get("USE_MKDOCS") is not None:
        return

    try:
        import geedim as gd
    except ImportError:
        raise ImportError(
            "Please install geedim using `pip install geedim` or `conda install -c conda-forge geedim`"
        )

    if not isinstance(image, ee.Image):
        raise ValueError("image must be an ee.Image.")

    if unmask_value is not None:
        if isinstance(region, ee.Geometry):
            image = image.clip(region)
        elif isinstance(region, ee.FeatureCollection):
            image = image.clipToCollection(region)
        image = image.unmask(unmask_value, sameFootprint=False)

    if region is not None:
        kwargs["region"] = region

    if crs is not None:
        kwargs["crs"] = crs

    if crs_transform is not None:
        kwargs["crs_transform"] = crs_transform

    if scale is not None:
        kwargs["scale"] = scale

    if resampling is not None:
        kwargs["resampling"] = resampling

    if dtype is not None:
        kwargs["dtype"] = dtype

    if max_tile_size is not None:
        kwargs["max_tile_size"] = max_tile_size

    if max_tile_dim is not None:
        kwargs["max_tile_dim"] = max_tile_dim

    if shape is not None:
        kwargs["shape"] = shape

    if scale_offset:
        kwargs["scale_offset"] = scale_offset

    img = gd.download.BaseImage(image)
    img.download(filename, overwrite=overwrite, num_threads=num_threads, **kwargs)

download_ee_image_collection(collection, out_dir=None, filenames=None, region=None, crs=None, crs_transform=None, scale=None, resampling='near', dtype=None, overwrite=True, num_threads=None, max_tile_size=None, max_tile_dim=None, shape=None, scale_offset=False, unmask_value=None, **kwargs)

Download an Earth Engine ImageCollection as GeoTIFFs. Images larger than the `Earth Engine size limit are split and downloaded as separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

Parameters:

Name	Type	Description	Default
collection	ImageCollection	The image collection to be downloaded.	required
out_dir	str	The directory to save the downloaded images. Defaults to the current directory.	None
filenames	list	A list of filenames to use for the downloaded images. Defaults to the image ID.	None
region	Geometry	Region defined by geojson polygon in WGS84. Defaults to the entire image granule.	None
crs	str	Reproject image(s) to this EPSG or WKT CRS. Where image bands have different CRSs, all are re-projected to this CRS. Defaults to the CRS of the minimum scale band.	None
crs_transform	list	tuple of float, list of float, rio.Affine, optional List of 6 numbers specifying an affine transform in the specified CRS. In row-major order: [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation]. All bands are re-projected to this transform.	None
scale	float	Resample image(s) to this pixel scale (size) (m). Where image bands have different scales, all are resampled to this scale. Defaults to the minimum scale of image bands.	None
resampling	ResamplingMethod	Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.	'near'
dtype	str	Convert to this data type (uint8, int8, uint16, int16, uint32, int32, float32 or float64). Defaults to auto select a minimum size type that can represent the range of pixel values.	None
overwrite	bool	Overwrite the destination file if it exists. Defaults to True.	True
num_threads	int	Number of tiles to download concurrently. Defaults to a sensible auto value.	None
max_tile_size		int, optional Maximum tile size (MB). If None, defaults to the Earth Engine download size limit (32 MB).	None
max_tile_dim		int, optional Maximum tile width/height (pixels). If None, defaults to Earth Engine download limit (10000).	None
shape		tuple of int, optional (height, width) dimensions to export (pixels).	None
scale_offset		bool, optional Whether to apply any EE band scales and offsets to the image.	False
unmask_value	float	The value to use for pixels that are masked in the input image. If the exported image contains zero values, you should set the unmask value to a non-zero value so that the zero values are not treated as missing data. Defaults to None.	None

Source code in geemap/common.py

def download_ee_image_collection(
    collection,
    out_dir=None,
    filenames=None,
    region=None,
    crs=None,
    crs_transform=None,
    scale=None,
    resampling="near",
    dtype=None,
    overwrite=True,
    num_threads=None,
    max_tile_size=None,
    max_tile_dim=None,
    shape=None,
    scale_offset=False,
    unmask_value=None,
    **kwargs,
):
    """Download an Earth Engine ImageCollection as GeoTIFFs. Images larger than the `Earth Engine size limit are split and downloaded as
        separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

    Args:
        collection (ee.ImageCollection): The image collection to be downloaded.
        out_dir (str, optional): The directory to save the downloaded images. Defaults to the current directory.
        filenames (list, optional): A list of filenames to use for the downloaded images. Defaults to the image ID.
        region (ee.Geometry, optional): Region defined by geojson polygon in WGS84. Defaults to the entire image granule.
        crs (str, optional): Reproject image(s) to this EPSG or WKT CRS.  Where image bands have different CRSs, all are
            re-projected to this CRS. Defaults to the CRS of the minimum scale band.
        crs_transform (list, optional): tuple of float, list of float, rio.Affine, optional
            List of 6 numbers specifying an affine transform in the specified CRS.  In row-major order:
            [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation].  All bands are re-projected to
            this transform.
        scale (float, optional): Resample image(s) to this pixel scale (size) (m).  Where image bands have different scales,
            all are resampled to this scale.  Defaults to the minimum scale of image bands.
        resampling (ResamplingMethod, optional): Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.
        dtype (str, optional): Convert to this data type (`uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `float32`
            or `float64`).  Defaults to auto select a minimum size type that can represent the range of pixel values.
        overwrite (bool, optional): Overwrite the destination file if it exists. Defaults to True.
        num_threads (int, optional): Number of tiles to download concurrently. Defaults to a sensible auto value.
        max_tile_size: int, optional
            Maximum tile size (MB).  If None, defaults to the Earth Engine download size limit (32 MB).
        max_tile_dim: int, optional
            Maximum tile width/height (pixels).  If None, defaults to Earth Engine download limit (10000).
        shape: tuple of int, optional
            (height, width) dimensions to export (pixels).
        scale_offset: bool, optional
            Whether to apply any EE band scales and offsets to the image.
        unmask_value (float, optional): The value to use for pixels that are masked in the input image. If the exported image contains zero values,
            you should set the unmask value to a  non-zero value so that the zero values are not treated as missing data. Defaults to None.
    """

    if not isinstance(collection, ee.ImageCollection):
        raise ValueError("ee_object must be an ee.ImageCollection.")

    if out_dir is None:
        out_dir = os.getcwd()

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    try:
        count = int(collection.size().getInfo())
        print(f"Total number of images: {count}\n")

        if filenames is not None:
            if len(filenames) != count:
                raise ValueError(
                    f"The number of filenames must match the number of image: {count}"
                )

        for i in range(0, count):
            image = ee.Image(collection.toList(count).get(i))
            if filenames is not None:
                name = filenames[i]
                if not name.endswith(".tif"):
                    name = name + ".tif"
            else:
                name = image.get("system:index").getInfo() + ".tif"
            filename = os.path.join(os.path.abspath(out_dir), name)
            print(f"Downloading {i + 1}/{count}: {name}")
            download_ee_image(
                image,
                filename,
                region,
                crs,
                crs_transform,
                scale,
                resampling,
                dtype,
                overwrite,
                num_threads,
                max_tile_size,
                max_tile_dim,
                shape,
                scale_offset,
                unmask_value,
                **kwargs,
            )

    except Exception as e:
        raise Exception(f"Error downloading image collection: {e}")

download_ee_image_tiles(image, features, out_dir=None, prefix=None, crs=None, crs_transform=None, scale=None, resampling='near', dtype=None, overwrite=True, num_threads=None, max_tile_size=None, max_tile_dim=None, shape=None, scale_offset=False, unmask_value=None, column=None, **kwargs)

Download an Earth Engine Image as small tiles based on ee.FeatureCollection. Images larger than the `Earth Engine size limit are split and downloaded as separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

Parameters:

Name	Type	Description	Default
image	Image	The image to be downloaded.	required
features	FeatureCollection	The features to loop through to download image.	required
out_dir	str	The output directory. Defaults to None.	None
prefix	str	The prefix for the output file. Defaults to None.	None
crs	str	Reproject image(s) to this EPSG or WKT CRS. Where image bands have different CRSs, all are re-projected to this CRS. Defaults to the CRS of the minimum scale band.	None
crs_transform	list	tuple of float, list of float, rio.Affine, optional List of 6 numbers specifying an affine transform in the specified CRS. In row-major order: [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation]. All bands are re-projected to this transform.	None
scale	float	Resample image(s) to this pixel scale (size) (m). Where image bands have different scales, all are resampled to this scale. Defaults to the minimum scale of image bands.	None
resampling	ResamplingMethod	Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.	'near'
dtype	str	Convert to this data type (uint8, int8, uint16, int16, uint32, int32, float32 or float64). Defaults to auto select a minimum size type that can represent the range of pixel values.	None
overwrite	bool	Overwrite the destination file if it exists. Defaults to True.	True
num_threads	int	Number of tiles to download concurrently. Defaults to a sensible auto value.	None
max_tile_size		int, optional Maximum tile size (MB). If None, defaults to the Earth Engine download size limit (32 MB).	None
max_tile_dim		int, optional Maximum tile width/height (pixels). If None, defaults to Earth Engine download limit (10000).	None
shape		tuple of int, optional (height, width) dimensions to export (pixels).	None
scale_offset		bool, optional Whether to apply any EE band scales and offsets to the image.	False
unmask_value	float	The value to use for pixels that are masked in the input image. If the exported image contains zero values, you should set the unmask value to a non-zero value so that the zero values are not treated as missing data. Defaults to None.	None
column	str	The column name to use for the filename. Defaults to None.	None

Source code in geemap/common.py

def download_ee_image_tiles(
    image,
    features,
    out_dir=None,
    prefix=None,
    crs=None,
    crs_transform=None,
    scale=None,
    resampling="near",
    dtype=None,
    overwrite=True,
    num_threads=None,
    max_tile_size=None,
    max_tile_dim=None,
    shape=None,
    scale_offset=False,
    unmask_value=None,
    column=None,
    **kwargs,
):
    """Download an Earth Engine Image as small tiles based on ee.FeatureCollection. Images larger than the `Earth Engine size limit are split and downloaded as
        separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

    Args:
        image (ee.Image): The image to be downloaded.
        features (ee.FeatureCollection): The features to loop through to download image.
        out_dir (str, optional): The output directory. Defaults to None.
        prefix (str, optional): The prefix for the output file. Defaults to None.
        crs (str, optional): Reproject image(s) to this EPSG or WKT CRS.  Where image bands have different CRSs, all are
            re-projected to this CRS. Defaults to the CRS of the minimum scale band.
        crs_transform (list, optional): tuple of float, list of float, rio.Affine, optional
            List of 6 numbers specifying an affine transform in the specified CRS.  In row-major order:
            [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation].  All bands are re-projected to
            this transform.
        scale (float, optional): Resample image(s) to this pixel scale (size) (m).  Where image bands have different scales,
            all are resampled to this scale.  Defaults to the minimum scale of image bands.
        resampling (ResamplingMethod, optional): Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.
        dtype (str, optional): Convert to this data type (`uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `float32`
            or `float64`).  Defaults to auto select a minimum size type that can represent the range of pixel values.
        overwrite (bool, optional): Overwrite the destination file if it exists. Defaults to True.
        num_threads (int, optional): Number of tiles to download concurrently. Defaults to a sensible auto value.
        max_tile_size: int, optional
            Maximum tile size (MB).  If None, defaults to the Earth Engine download size limit (32 MB).
        max_tile_dim: int, optional
            Maximum tile width/height (pixels).  If None, defaults to Earth Engine download limit (10000).
        shape: tuple of int, optional
            (height, width) dimensions to export (pixels).
        scale_offset: bool, optional
            Whether to apply any EE band scales and offsets to the image.
        unmask_value (float, optional): The value to use for pixels that are masked in the input image. If the exported image contains zero values,
            you should set the unmask value to a  non-zero value so that the zero values are not treated as missing data. Defaults to None.
        column (str, optional): The column name to use for the filename. Defaults to None.

    """
    import time

    start = time.time()

    if os.environ.get("USE_MKDOCS") is not None:
        return

    if not isinstance(features, ee.FeatureCollection):
        raise ValueError("features must be an ee.FeatureCollection.")

    if out_dir is None:
        out_dir = os.getcwd()

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if prefix is None:
        prefix = ""

    count = features.size().getInfo()
    collection = features.toList(count)

    if column is not None:
        names = features.aggregate_array(column).getInfo()
    else:
        names = [str(i + 1).zfill(len(str(count))) for i in range(count)]

    for i in range(count):
        region = ee.Feature(collection.get(i)).geometry()
        filename = os.path.join(
            out_dir, "{}{}.tif".format(prefix, names[i].replace("/", "_"))
        )
        print(f"Downloading {i + 1}/{count}: {filename}")
        download_ee_image(
            image,
            filename,
            region,
            crs,
            crs_transform,
            scale,
            resampling,
            dtype,
            overwrite,
            num_threads,
            max_tile_size,
            max_tile_dim,
            shape,
            scale_offset,
            unmask_value,
            **kwargs,
        )

    print(f"Downloaded {count} tiles in {time.time() - start} seconds.")

download_ee_image_tiles_parallel(image, features, out_dir=None, prefix=None, crs=None, crs_transform=None, scale=None, resampling='near', dtype=None, overwrite=True, num_threads=None, max_tile_size=None, max_tile_dim=None, shape=None, scale_offset=False, unmask_value=None, column=None, job_args={'n_jobs': -1}, ee_init=True, project_id=None, **kwargs)

Download an Earth Engine Image as small tiles based on ee.FeatureCollection. Images larger than the `Earth Engine size limit are split and downloaded as separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

Parameters:

Name	Type	Description	Default
image	Image	The image to be downloaded.	required
features	FeatureCollection	The features to loop through to download image.	required
out_dir	str	The output directory. Defaults to None.	None
prefix	str	The prefix for the output file. Defaults to None.	None
crs	str	Reproject image(s) to this EPSG or WKT CRS. Where image bands have different CRSs, all are re-projected to this CRS. Defaults to the CRS of the minimum scale band.	None
crs_transform	list	tuple of float, list of float, rio.Affine, optional List of 6 numbers specifying an affine transform in the specified CRS. In row-major order: [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation]. All bands are re-projected to this transform.	None
scale	float	Resample image(s) to this pixel scale (size) (m). Where image bands have different scales, all are resampled to this scale. Defaults to the minimum scale of image bands.	None
resampling	ResamplingMethod	Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.	'near'
dtype	str	Convert to this data type (uint8, int8, uint16, int16, uint32, int32, float32 or float64). Defaults to auto select a minimum size type that can represent the range of pixel values.	None
overwrite	bool	Overwrite the destination file if it exists. Defaults to True.	True
num_threads	int	Number of tiles to download concurrently. Defaults to a sensible auto value.	None
max_tile_size		int, optional Maximum tile size (MB). If None, defaults to the Earth Engine download size limit (32 MB).	None
max_tile_dim		int, optional Maximum tile width/height (pixels). If None, defaults to Earth Engine download limit (10000).	None
shape		tuple of int, optional (height, width) dimensions to export (pixels).	None
scale_offset		bool, optional Whether to apply any EE band scales and offsets to the image.	False
unmask_value	float	The value to use for pixels that are masked in the input image. If the exported image contains zero values, you should set the unmask value to a non-zero value so that the zero values are not treated as missing data. Defaults to None.	None
column	str	The column name in the feature collection to use as the filename. Defaults to None.	None
job_args	dict	The arguments to pass to joblib.Parallel. Defaults to {"n_jobs": -1}.	{'n_jobs': -1}
ee_init	bool	Whether to initialize Earth Engine. Defaults to True.	True
project_id	str	The Earth Engine project ID. Defaults to None.	None

Source code in geemap/common.py

def download_ee_image_tiles_parallel(
    image,
    features,
    out_dir=None,
    prefix=None,
    crs=None,
    crs_transform=None,
    scale=None,
    resampling="near",
    dtype=None,
    overwrite=True,
    num_threads=None,
    max_tile_size=None,
    max_tile_dim=None,
    shape=None,
    scale_offset=False,
    unmask_value=None,
    column=None,
    job_args={"n_jobs": -1},
    ee_init=True,
    project_id=None,
    **kwargs,
):
    """Download an Earth Engine Image as small tiles based on ee.FeatureCollection. Images larger than the `Earth Engine size limit are split and downloaded as
        separate tiles, then re-assembled into a single GeoTIFF. See https://github.com/dugalh/geedim/blob/main/geedim/download.py#L574

    Args:
        image (ee.Image): The image to be downloaded.
        features (ee.FeatureCollection): The features to loop through to download image.
        out_dir (str, optional): The output directory. Defaults to None.
        prefix (str, optional): The prefix for the output file. Defaults to None.
        crs (str, optional): Reproject image(s) to this EPSG or WKT CRS.  Where image bands have different CRSs, all are
            re-projected to this CRS. Defaults to the CRS of the minimum scale band.
        crs_transform (list, optional): tuple of float, list of float, rio.Affine, optional
            List of 6 numbers specifying an affine transform in the specified CRS.  In row-major order:
            [xScale, xShearing, xTranslation, yShearing, yScale, yTranslation].  All bands are re-projected to
            this transform.
        scale (float, optional): Resample image(s) to this pixel scale (size) (m).  Where image bands have different scales,
            all are resampled to this scale.  Defaults to the minimum scale of image bands.
        resampling (ResamplingMethod, optional): Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.
        dtype (str, optional): Convert to this data type (`uint8`, `int8`, `uint16`, `int16`, `uint32`, `int32`, `float32`
            or `float64`).  Defaults to auto select a minimum size type that can represent the range of pixel values.
        overwrite (bool, optional): Overwrite the destination file if it exists. Defaults to True.
        num_threads (int, optional): Number of tiles to download concurrently. Defaults to a sensible auto value.
        max_tile_size: int, optional
            Maximum tile size (MB).  If None, defaults to the Earth Engine download size limit (32 MB).
        max_tile_dim: int, optional
            Maximum tile width/height (pixels).  If None, defaults to Earth Engine download limit (10000).
        shape: tuple of int, optional
            (height, width) dimensions to export (pixels).
        scale_offset: bool, optional
            Whether to apply any EE band scales and offsets to the image.
        unmask_value (float, optional): The value to use for pixels that are masked in the input image. If the exported image contains zero values,
            you should set the unmask value to a  non-zero value so that the zero values are not treated as missing data. Defaults to None.
        column (str, optional): The column name in the feature collection to use as the filename. Defaults to None.
        job_args (dict, optional): The arguments to pass to joblib.Parallel. Defaults to {"n_jobs": -1}.
        ee_init (bool, optional): Whether to initialize Earth Engine. Defaults to True.
        project_id (str, optional): The Earth Engine project ID. Defaults to None.

    """
    import joblib
    import time

    start = time.time()

    if os.environ.get("USE_MKDOCS") is not None:
        return

    if not isinstance(features, ee.FeatureCollection):
        raise ValueError("features must be an ee.FeatureCollection.")

    if out_dir is None:
        out_dir = os.getcwd()

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if prefix is None:
        prefix = ""

    count = features.size().getInfo()
    if column is not None:
        names = features.aggregate_array(column).getInfo()
    else:
        names = [str(i + 1).zfill(len(str(count))) for i in range(count)]
    collection = features.toList(count)

    def download_data(index):
        if ee_init:
            ee_initialize(
                opt_url="https://earthengine-highvolume.googleapis.com",
                project=project_id,
            )
        region = ee.Feature(collection.get(index)).geometry()
        filename = os.path.join(
            out_dir, "{}{}.tif".format(prefix, names[index].replace("/", "_"))
        )
        print(f"Downloading {index + 1}/{count}: {filename}")

        download_ee_image(
            image,
            filename,
            region,
            crs,
            crs_transform,
            scale,
            resampling,
            dtype,
            overwrite,
            num_threads,
            max_tile_size,
            max_tile_dim,
            shape,
            scale_offset,
            unmask_value,
            **kwargs,
        )

    with joblib.Parallel(**job_args) as parallel:
        parallel(joblib.delayed(download_data)(index) for index in range(count))

    end = time.time()
    print(f"Finished in {end - start} seconds.")

download_ee_video(collection, video_args, out_gif, timeout=300, proxies=None)

Downloads a video thumbnail as a GIF image from Earth Engine.

Parameters:

Name	Type	Description	Default
collection	object	An ee.ImageCollection.	required
video_args	object	Parameters for expring the video thumbnail.	required
out_gif	str	File path to the output GIF.	required
timeout	int	The number of seconds the request will be timed out. Defaults to 300.	300
proxies	dict	A dictionary of proxy servers to use. Defaults to None.	None

Source code in geemap/common.py

def download_ee_video(collection, video_args, out_gif, timeout=300, proxies=None):
    """Downloads a video thumbnail as a GIF image from Earth Engine.

    Args:
        collection (object): An ee.ImageCollection.
        video_args (object): Parameters for expring the video thumbnail.
        out_gif (str): File path to the output GIF.
        timeout (int, optional): The number of seconds the request will be timed out. Defaults to 300.
        proxies (dict, optional): A dictionary of proxy servers to use. Defaults to None.
    """

    out_gif = os.path.abspath(out_gif)
    if not out_gif.endswith(".gif"):
        print("The output file must have an extension of .gif.")
        return

    if not os.path.exists(os.path.dirname(out_gif)):
        os.makedirs(os.path.dirname(out_gif))

    if "region" in video_args.keys():
        roi = video_args["region"]

        if not isinstance(roi, ee.Geometry):
            try:
                roi = roi.geometry()
            except Exception as e:
                print("Could not convert the provided roi to ee.Geometry")
                print(e)
                return

        video_args["region"] = roi
    if "dimensions" not in video_args:
        video_args["dimensions"] = 768

    try:
        print("Generating URL...")
        url = collection.getVideoThumbURL(video_args)

        print(f"Downloading GIF image from {url}\nPlease wait ...")
        r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)

        if r.status_code != 200:
            print("An error occurred while downloading.")
            print(r.json()["error"]["message"])
            return
        else:
            with open(out_gif, "wb") as fd:
                for chunk in r.iter_content(chunk_size=1024):
                    fd.write(chunk)
            print(f"The GIF image has been saved to: {out_gif}")
    except Exception as e:
        print(e)

download_file(url=None, output=None, quiet=False, proxy=None, speed=None, use_cookies=True, verify=True, id=None, fuzzy=False, resume=False, unzip=True, overwrite=False)

Download a file from URL, including Google Drive shared URL.

Parameters:

Name	Type	Description	Default
url	Optional[str]	Google Drive URL is also supported. Defaults to None.	None
output	Optional[str]	Output filename. Default is basename of URL.	None
quiet	bool	Suppress terminal output. Default is False.	False
proxy	Optional[str]	Proxy. Defaults to None.	None
speed	Optional[float]	Download byte size per second (e.g., 256KB/s = 256 * 1024). Defaults to None.	None
use_cookies	bool	Flag to use cookies. Defaults to True.	True
verify	Union[bool, str]	Either a bool, in which case it controls whether the server's TLS certificate is verified, or a string, in which case it must be a path to a CA bundle to use. Default is True.	True
id	Optional[str]	Google Drive's file ID. Defaults to None.	None
fuzzy	bool	Fuzzy extraction of Google Drive's file Id. Defaults to False.	False
resume	bool	Resume the download from existing tmp file if possible. Defaults to False.	False
unzip	bool	Unzip the file. Defaults to True.	True
overwrite	bool	Overwrite the file if it already exists. Defaults to False.	False

Returns:

Name	Type	Description
str	str	The output file path.

Source code in geemap/coreutils.py

def download_file(
    url: Optional[str] = None,
    output: Optional[str] = None,
    quiet: bool = False,
    proxy: Optional[str] = None,
    speed: Optional[float] = None,
    use_cookies: bool = True,
    verify: Union[bool, str] = True,
    id: Optional[str] = None,
    fuzzy: bool = False,
    resume: bool = False,
    unzip: bool = True,
    overwrite: bool = False,
) -> str:
    """Download a file from URL, including Google Drive shared URL.

    Args:
        url (Optional[str], optional): Google Drive URL is also supported.
            Defaults to None.
        output (Optional[str], optional): Output filename. Default is basename of URL.
        quiet (bool, optional): Suppress terminal output. Default is False.
        proxy (Optional[str], optional): Proxy. Defaults to None.
        speed (Optional[float], optional): Download byte size per second (e.g.,
            256KB/s = 256 * 1024). Defaults to None.
        use_cookies (bool, optional): Flag to use cookies. Defaults to True.
        verify (Union[bool, str], optional): Either a bool, in which case it
            controls whether the server's TLS certificate is verified, or a
            string, in which case it must be a path to a CA bundle to use.
            Default is True.
        id (Optional[str], optional): Google Drive's file ID. Defaults to None.
        fuzzy (bool, optional): Fuzzy extraction of Google Drive's file Id.
            Defaults to False.
        resume (bool, optional): Resume the download from existing tmp file if
            possible. Defaults to False.
        unzip (bool, optional): Unzip the file. Defaults to True.
        overwrite (bool, optional): Overwrite the file if it already exists.
            Defaults to False.

    Returns:
        str: The output file path.
    """

    import gdown

    if output is None:
        if isinstance(url, str) and url.startswith("http"):
            output = os.path.basename(url)

    if isinstance(url, str):
        if os.path.exists(os.path.abspath(output)) and (not overwrite):
            print(
                f"{output} already exists. Skip downloading. Set overwrite=True to overwrite."
            )
            return os.path.abspath(output)
        else:
            url = github_raw_url(url)

    if "https://drive.google.com/file/d/" in url:
        fuzzy = True

    output = gdown.download(
        url, output, quiet, proxy, speed, use_cookies, verify, id, fuzzy, resume
    )

    if unzip and output.endswith(".zip"):
        with zipfile.ZipFile(output, "r") as zip_ref:
            if not quiet:
                print("Extracting files...")
            zip_ref.extractall(os.path.dirname(output))

    return os.path.abspath(output)

download_folder(url=None, id=None, output=None, quiet=False, proxy=None, speed=None, use_cookies=True, remaining_ok=False)

Downloads the entire folder from URL.

Parameters:

Name	Type	Description	Default
url	str	URL of the Google Drive folder. Must be of the format 'https://drive.google.com/drive/folders/{url}'. Defaults to None.	None
id	str	Google Drive's folder ID. Defaults to None.	None
output	str	String containing the path of the output folder. Defaults to current working directory.	None
quiet	bool	Suppress terminal output. Defaults to False.	False
proxy	str	Proxy. Defaults to None.	None
speed	float	Download byte size per second (e.g., 256KB/s = 256 * 1024). Defaults to None.	None
use_cookies	bool	Flag to use cookies. Defaults to True.	True
resume	bool	Resume the download from existing tmp file if possible. Defaults to False.	required

Returns:

Name	Type	Description
list		List of files downloaded, or None if failed.

Source code in geemap/common.py

def download_folder(
    url=None,
    id=None,
    output=None,
    quiet=False,
    proxy=None,
    speed=None,
    use_cookies=True,
    remaining_ok=False,
):
    """Downloads the entire folder from URL.

    Args:
        url (str, optional): URL of the Google Drive folder. Must be of the format 'https://drive.google.com/drive/folders/{url}'. Defaults to None.
        id (str, optional): Google Drive's folder ID. Defaults to None.
        output (str, optional):  String containing the path of the output folder. Defaults to current working directory.
        quiet (bool, optional): Suppress terminal output. Defaults to False.
        proxy (str, optional): Proxy. Defaults to None.
        speed (float, optional): Download byte size per second (e.g., 256KB/s = 256 * 1024). Defaults to None.
        use_cookies (bool, optional): Flag to use cookies. Defaults to True.
        resume (bool, optional): Resume the download from existing tmp file if possible. Defaults to False.

    Returns:
        list: List of files downloaded, or None if failed.
    """
    import gdown

    files = gdown.download_folder(
        url, id, output, quiet, proxy, speed, use_cookies, remaining_ok
    )
    return files

download_from_gdrive(gfile_url, file_name, out_dir='.', unzip=True, verbose=True)

Download a file shared via Google Drive (e.g., https://drive.google.com/file/d/18SUo_HcDGltuWYZs1s7PpOmOq_FvFn04/view?usp=sharing)

Parameters:

Name	Type	Description	Default
gfile_url	str	The Google Drive shared file URL	required
file_name	str	The output file name to use.	required
out_dir	str	The output directory. Defaults to '.'.	'.'
unzip	bool	Whether to unzip the output file if it is a zip file. Defaults to True.	True
verbose	bool	Whether to display or not the output of the function	True

Source code in geemap/common.py

def download_from_gdrive(gfile_url, file_name, out_dir=".", unzip=True, verbose=True):
    """Download a file shared via Google Drive
       (e.g., https://drive.google.com/file/d/18SUo_HcDGltuWYZs1s7PpOmOq_FvFn04/view?usp=sharing)

    Args:
        gfile_url (str): The Google Drive shared file URL
        file_name (str): The output file name to use.
        out_dir (str, optional): The output directory. Defaults to '.'.
        unzip (bool, optional): Whether to unzip the output file if it is a zip file. Defaults to True.
        verbose (bool, optional): Whether to display or not the output of the function
    """
    try:
        from google_drive_downloader import GoogleDriveDownloader as gdd
    except ImportError:
        raise Exception(
            "Please install the google_drive_downloader package using `pip install googledrivedownloader`"
        )

    file_id = gfile_url.split("/")[5]
    if verbose:
        print(f"Google Drive file id: {file_id}")

    dest_path = os.path.join(out_dir, file_name)
    gdd.download_file_from_google_drive(file_id, dest_path, True, unzip)

    return

download_from_url(url, out_file_name=None, out_dir='.', unzip=True, verbose=True)

Download a file from a URL (e.g., https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip)

Parameters:

Name	Type	Description	Default
url	str	The HTTP URL to download.	required
out_file_name	str	The output file name to use. Defaults to None.	None
out_dir	str	The output directory to use. Defaults to '.'.	'.'
unzip	bool	Whether to unzip the downloaded file if it is a zip file. Defaults to True.	True
verbose	bool	Whether to display or not the output of the function	True

Source code in geemap/common.py

def download_from_url(url, out_file_name=None, out_dir=".", unzip=True, verbose=True):
    """Download a file from a URL (e.g., https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip)

    Args:
        url (str): The HTTP URL to download.
        out_file_name (str, optional): The output file name to use. Defaults to None.
        out_dir (str, optional): The output directory to use. Defaults to '.'.
        unzip (bool, optional): Whether to unzip the downloaded file if it is a zip file. Defaults to True.
        verbose (bool, optional): Whether to display or not the output of the function
    """
    in_file_name = os.path.basename(url)

    if out_file_name is None:
        out_file_name = in_file_name
    out_file_path = os.path.join(os.path.abspath(out_dir), out_file_name)

    if verbose:
        print(f"Downloading {url} ...")

    try:
        urllib.request.urlretrieve(url, out_file_path)
    except Exception:
        raise Exception("The URL is invalid. Please double check the URL.")

    final_path = out_file_path

    if unzip:
        # if it is a zip file
        if ".zip" in out_file_name:
            if verbose:
                print(f"Unzipping {out_file_name} ...")
            with zipfile.ZipFile(out_file_path, "r") as zip_ref:
                zip_ref.extractall(out_dir)
            final_path = os.path.join(
                os.path.abspath(out_dir), out_file_name.replace(".zip", "")
            )

        # if it is a tar file
        if ".tar" in out_file_name:
            if verbose:
                print(f"Unzipping {out_file_name} ...")
            with tarfile.open(out_file_path, "r") as tar_ref:
                with tarfile.open(out_file_path, "r") as tar_ref:

                    def is_within_directory(directory, target):
                        abs_directory = os.path.abspath(directory)
                        abs_target = os.path.abspath(target)

                        prefix = os.path.commonprefix([abs_directory, abs_target])

                        return prefix == abs_directory

                    def safe_extract(
                        tar, path=".", members=None, *, numeric_owner=False
                    ):
                        for member in tar.getmembers():
                            member_path = os.path.join(path, member.name)
                            if not is_within_directory(path, member_path):
                                raise Exception("Attempted Path Traversal in Tar File")

                        tar.extractall(path, members, numeric_owner=numeric_owner)

                    safe_extract(tar_ref, out_dir)
            final_path = os.path.join(
                os.path.abspath(out_dir), out_file_name.replace(".tar", "")
            )

    if verbose:
        print(f"Data downloaded to: {final_path}")

    return

download_gee_app(url, out_file=None)

Downloads JavaScript source code from a GEE App

Parameters:

Name	Type	Description	Default
url	str	The URL of the GEE App.	required
out_file	str	The output file path for the downloaded JavaScript. Defaults to None.	None

Source code in geemap/conversion.py

def download_gee_app(url, out_file=None):
    """Downloads JavaScript source code from a GEE App

    Args:
        url (str): The URL of the GEE App.
        out_file (str, optional): The output file path for the downloaded JavaScript. Defaults to None.
    """
    cwd = os.getcwd()
    out_file_name = os.path.basename(url) + ".js"
    out_file_path = os.path.join(cwd, out_file_name)
    items = url.split("/")
    items[3] = "javascript"
    items[4] = items[4] + "-modules.json"
    json_url = "/".join(items)
    print(f"The json url: {json_url}")

    if out_file is not None:
        out_file_path = out_file
        if not out_file_path.endswith("js"):
            out_file_path += ".js"

    out_dir = os.path.dirname(out_file_path)
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    json_path = out_file_path + "on"

    try:
        urllib.request.urlretrieve(json_url, json_path)
    except Exception:
        raise Exception("The URL is invalid. Please double check the URL.")

    with open(out_file_path, "w") as f1:
        with open(json_path, encoding="utf-8") as f2:
            lines = f2.readlines()
            for line in lines:
                # print(line)
                items = line.split("\\n")
                for index, item in enumerate(items):
                    if (index > 0) and (index < (len(items) - 1)):
                        item = item.replace('\\"', '"')
                        item = item.replace(r"\\", "\n")
                        item = item.replace("\\r", "")
                        f1.write(item + "\n")
    os.remove(json_path)
    print(f"The JavaScript is saved at: {out_file_path}")

download_ned(region, out_dir=None, return_url=False, download_args={}, **kwargs)

Download the US National Elevation Datasets (NED) for a region.

Parameters:

Name	Type	Description	Default
region	str | list	A filepath to a vector dataset or a list of bounds in the form of [minx, miny, maxx, maxy].	required
out_dir	str	The directory to download the files to. Defaults to None, which uses the current working directory.	None
return_url	bool	Whether to return the download URLs of the files. Defaults to False.	False
download_args	dict	A dictionary of arguments to pass to the download_file function. Defaults to {}.	{}

Returns:

Name	Type	Description
list		A list of the download URLs of the files if return_url is True.

Source code in geemap/common.py

def download_ned(region, out_dir=None, return_url=False, download_args={}, **kwargs):
    """Download the US National Elevation Datasets (NED) for a region.

    Args:
        region (str | list): A filepath to a vector dataset or a list of bounds in the form of [minx, miny, maxx, maxy].
        out_dir (str, optional): The directory to download the files to. Defaults to None, which uses the current working directory.
        return_url (bool, optional): Whether to return the download URLs of the files. Defaults to False.
        download_args (dict, optional): A dictionary of arguments to pass to the download_file function. Defaults to {}.

    Returns:
        list: A list of the download URLs of the files if return_url is True.
    """
    import geopandas as gpd

    if out_dir is None:
        out_dir = os.getcwd()
    else:
        out_dir = os.path.abspath(out_dir)

    if isinstance(region, str):
        if region.startswith("http"):
            region = github_raw_url(region)
            region = download_file(region)
        elif not os.path.exists(region):
            raise ValueError("region must be a path or a URL to a vector dataset.")

        roi = gpd.read_file(region, **kwargs)
        roi = roi.to_crs(epsg=4326)
        bounds = roi.total_bounds

    elif isinstance(region, list):
        bounds = region

    else:
        raise ValueError(
            "region must be a filepath or a list of bounds in the form of [minx, miny, maxx, maxy]."
        )
    minx, miny, maxx, maxy = [float(x) for x in bounds]
    tiles = []
    left = abs(math.floor(minx))
    right = abs(math.floor(maxx)) - 1
    upper = math.ceil(maxy)
    bottom = math.ceil(miny) - 1

    for y in range(upper, bottom, -1):
        for x in range(left, right, -1):
            tile_id = "n{}w{}".format(str(y).zfill(2), str(x).zfill(3))
            tiles.append(tile_id)

    links = []
    filepaths = []

    for index, tile in enumerate(tiles):
        tif_url = f"https://prd-tnm.s3.amazonaws.com/StagedProducts/Elevation/13/TIFF/current/{tile}/USGS_13_{tile}.tif"

        r = requests.head(tif_url)
        if r.status_code == 200:
            tif = os.path.join(out_dir, os.path.basename(tif_url))
            links.append(tif_url)
            filepaths.append(tif)
        else:
            print(f"{tif_url} does not exist.")

    if return_url:
        return links
    else:
        for index, link in enumerate(links):
            print(f"Downloading {index + 1} of {len(links)}: {os.path.basename(link)}")
            download_file(link, filepaths[index], **download_args)

dynamic_world(region=None, start_date='2020-01-01', end_date='2021-01-01', clip=False, reducer=None, projection='EPSG:3857', scale=10, return_type='hillshade')

Create 10-m land cover composite based on Dynamic World. The source code is adapted from the following tutorial by Spatial Thoughts: https://developers.google.com/earth-engine/tutorials/community/introduction-to-dynamic-world-pt-1

Parameters:

Name	Type	Description	Default
region	Geometry | FeatureCollection	The region of interest.	None
start_date	str | Date	The start date of the query. Default to "2020-01-01".	'2020-01-01'
end_date	str | Date	The end date of the query. Default to "2021-01-01".	'2021-01-01'
clip	bool	Whether to clip the image to the region. Default to False.	False
reducer	Reducer	The reducer to be used. Default to None.	None
projection	str	The projection to be used for creating hillshade. Default to "EPSG:3857".	'EPSG:3857'
scale	int	The scale to be used for creating hillshade. Default to 10.	10
return_type	str	The type of image to be returned. Can be one of 'hillshade', 'visualize', 'class', or 'probability'. Default to "hillshade".	'hillshade'

Returns:

Type	Description
	ee.Image: The image with the specified return_type.

Source code in geemap/common.py

def dynamic_world(
    region=None,
    start_date="2020-01-01",
    end_date="2021-01-01",
    clip=False,
    reducer=None,
    projection="EPSG:3857",
    scale=10,
    return_type="hillshade",
):
    """Create 10-m land cover composite based on Dynamic World. The source code is adapted from the following tutorial by Spatial Thoughts:
    https://developers.google.com/earth-engine/tutorials/community/introduction-to-dynamic-world-pt-1

    Args:
        region (ee.Geometry | ee.FeatureCollection): The region of interest.
        start_date (str | ee.Date): The start date of the query. Default to "2020-01-01".
        end_date (str | ee.Date): The end date of the query. Default to "2021-01-01".
        clip (bool, optional): Whether to clip the image to the region. Default to False.
        reducer (ee.Reducer, optional): The reducer to be used. Default to None.
        projection (str, optional): The projection to be used for creating hillshade. Default to "EPSG:3857".
        scale (int, optional): The scale to be used for creating hillshade. Default to 10.
        return_type (str, optional): The type of image to be returned. Can be one of 'hillshade', 'visualize', 'class', or 'probability'. Default to "hillshade".

    Returns:
        ee.Image: The image with the specified return_type.
    """

    if return_type not in ["hillshade", "visualize", "class", "probability"]:
        raise ValueError(
            f"{return_type} must be one of 'hillshade', 'visualize', 'class', or 'probability'."
        )

    if reducer is None:
        reducer = ee.Reducer.mode()

    dw = ee.ImageCollection("GOOGLE/DYNAMICWORLD/V1").filter(
        ee.Filter.date(start_date, end_date)
    )

    if isinstance(region, ee.FeatureCollection) or isinstance(region, ee.Geometry):
        dw = dw.filterBounds(region)
    else:
        raise ValueError("region must be an ee.FeatureCollection or ee.Geometry.")

    # Create a Mode Composite
    classification = dw.select("label")
    dwComposite = classification.reduce(reducer)
    if clip and (region is not None):
        if isinstance(region, ee.Geometry):
            dwComposite = dwComposite.clip(region)
        elif isinstance(region, ee.FeatureCollection):
            dwComposite = dwComposite.clipToCollection(region)
        elif isinstance(region, ee.Feature):
            dwComposite = dwComposite.clip(region.geometry())

    dwVisParams = {
        "min": 0,
        "max": 8,
        "palette": [
            "#419BDF",
            "#397D49",
            "#88B053",
            "#7A87C6",
            "#E49635",
            "#DFC35A",
            "#C4281B",
            "#A59B8F",
            "#B39FE1",
        ],
    }

    if return_type == "class":
        return dwComposite
    elif return_type == "visualize":
        return dwComposite.visualize(**dwVisParams)
    else:
        # Create a Top-1 Probability Hillshade Visualization
        probabilityBands = [
            "water",
            "trees",
            "grass",
            "flooded_vegetation",
            "crops",
            "shrub_and_scrub",
            "built",
            "bare",
            "snow_and_ice",
        ]

        # Select probability bands
        probabilityCol = dw.select(probabilityBands)

        # Create a multi-band image with the average pixel-wise probability
        # for each band across the time-period
        meanProbability = probabilityCol.reduce(ee.Reducer.mean())

        # Composites have a default projection that is not suitable
        # for hillshade computation.
        # Set a EPSG:3857 projection with 10m scale
        proj = ee.Projection(projection).atScale(scale)
        meanProbability = meanProbability.setDefaultProjection(proj)

        # Create the Top1 Probability Hillshade
        top1Probability = meanProbability.reduce(ee.Reducer.max())

        if clip and (region is not None):
            if isinstance(region, ee.Geometry):
                top1Probability = top1Probability.clip(region)
            elif isinstance(region, ee.FeatureCollection):
                top1Probability = top1Probability.clipToCollection(region)
            elif isinstance(region, ee.Feature):
                top1Probability = top1Probability.clip(region.geometry())

        if return_type == "probability":
            return top1Probability
        else:
            top1Confidence = top1Probability.multiply(100).int()
            hillshade = ee.Terrain.hillshade(top1Confidence).divide(255)
            rgbImage = dwComposite.visualize(**dwVisParams).divide(255)
            probabilityHillshade = rgbImage.multiply(hillshade)

            return probabilityHillshade

dynamic_world_s2(region=None, start_date='2020-01-01', end_date='2021-01-01', clip=False, cloud_pct=0.35, reducer=None)

Create Sentinel-2 composite for the Dynamic World Land Cover product.

Parameters:

Name	Type	Description	Default
region	Geometry | FeatureCollection	The region of interest. Default to None.	None
start_date	str | Date	The start date of the query. Default to "2020-01-01".	'2020-01-01'
end_date	str | Date	The end date of the query. Default to "2021-01-01".	'2021-01-01'
clip	bool	Whether to clip the image to the region. Default to False.	False
cloud_pct	float	The percentage of cloud cover to be used for filtering. Default to 0.35.	0.35
reducer	Reducer	The reducer to be used for creating image composite. Default to None.	None

Returns:

Type	Description
	ee.Image: The Sentinel-2 composite.

Source code in geemap/common.py

def dynamic_world_s2(
    region=None,
    start_date="2020-01-01",
    end_date="2021-01-01",
    clip=False,
    cloud_pct=0.35,
    reducer=None,
):
    """Create Sentinel-2 composite for the Dynamic World Land Cover product.

    Args:
        region (ee.Geometry | ee.FeatureCollection): The region of interest. Default to None.
        start_date (str | ee.Date): The start date of the query. Default to "2020-01-01".
        end_date (str | ee.Date): The end date of the query. Default to "2021-01-01".
        clip (bool, optional): Whether to clip the image to the region. Default to False.
        cloud_pct (float, optional): The percentage of cloud cover to be used for filtering. Default to 0.35.
        reducer (ee.Reducer, optional): The reducer to be used for creating image composite. Default to None.

    Returns:
        ee.Image: The Sentinel-2 composite.
    """
    s2 = (
        ee.ImageCollection("COPERNICUS/S2_HARMONIZED")
        .filterDate(start_date, end_date)
        .filter(ee.Filter.lt("CLOUDY_PIXEL_PERCENTAGE", cloud_pct * 100))
    )

    if isinstance(region, ee.FeatureCollection) or isinstance(region, ee.Geometry):
        s2 = s2.filterBounds(region)
    else:
        raise ValueError("region must be an ee.FeatureCollection or ee.Geometry.")

    if reducer is None:
        reducer = ee.Reducer.median()

    image = s2.reduce(reducer).rename(s2.first().bandNames())

    if clip and (region is not None):
        if isinstance(region, ee.Geometry):
            image = image.clip(region)
        elif isinstance(region, ee.FeatureCollection):
            image = image.clipToCollection(region)

    return image

dynamic_world_timeseries(region, start_date='2016-01-01', end_date='2021-12-31', cloud_pct=30, frequency='year', reducer='mode', drop_empty=True, date_format=None, return_type='hillshade', parallel_scale=1)

Create Dynamic World timeseries.

Parameters:

Name	Type	Description	Default
region	Geometry | FeatureCollection	The region of interest.	required
start_date	str | Date	The start date of the query. Default to "2016-01-01".	'2016-01-01'
end_date	str | Date	The end date of the query. Default to "2021-12-31".	'2021-12-31'
cloud_pct	int	The cloud percentage threshold (<=). Defaults to 30.	30
frequency	str	The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'. Defaults to 'year'.	'year'
reducer	str	The reducer to be used. Defaults to "mode".	'mode'
drop_empty	bool	Whether to drop empty images from the timeseries. Defaults to True.	True
date_format	str	A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.	None
return_type	str	The type of image to be returned. Can be one of 'hillshade', 'visualize', 'class', or 'probability'. Default to "hillshade".	'hillshade'
parallel_scale	int	A scaling factor used to limit memory use; using a larger parallel_scale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.	1

Returns:

Type	Description
	ee.ImageCollection: An ImageCollection of the Dynamic World land cover timeseries.

Source code in geemap/timelapse.py

def dynamic_world_timeseries(
    region,
    start_date="2016-01-01",
    end_date="2021-12-31",
    cloud_pct=30,
    frequency="year",
    reducer="mode",
    drop_empty=True,
    date_format=None,
    return_type="hillshade",
    parallel_scale=1,
):
    """Create Dynamic World timeseries.

    Args:
        region (ee.Geometry | ee.FeatureCollection): The region of interest.
        start_date (str | ee.Date): The start date of the query. Default to "2016-01-01".
        end_date (str | ee.Date): The end date of the query. Default to "2021-12-31".
        cloud_pct (int, optional): The cloud percentage threshold (<=). Defaults to 30.
        frequency (str, optional): The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'. Defaults to 'year'.
        reducer (str, optional): The reducer to be used. Defaults to "mode".
        drop_empty (bool, optional): Whether to drop empty images from the timeseries. Defaults to True.
        date_format (str, optional): A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.
        return_type (str, optional): The type of image to be returned. Can be one of 'hillshade', 'visualize', 'class', or 'probability'. Default to "hillshade".
        parallel_scale (int, optional): A scaling factor used to limit memory use; using a larger parallel_scale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.

    Returns:
        ee.ImageCollection: An ImageCollection of the Dynamic World land cover timeseries.
    """
    if return_type not in ["hillshade", "visualize", "class", "probability"]:
        raise ValueError(
            f"{return_type} must be one of 'hillshade', 'visualize', 'class', or 'probability'."
        )

    if (
        isinstance(region, ee.FeatureCollection)
        or isinstance(region, ee.Feature)
        or isinstance(region, ee.Geometry)
    ):
        pass
    else:
        raise ValueError(
            f"{region} must be one of ee.FeatureCollection, ee.Feature, or ee.Geometry."
        )

    if cloud_pct < 0 or cloud_pct > 100:
        raise ValueError(f"{cloud_pct} must be between 0 and 100.")

    s2 = (
        ee.ImageCollection("COPERNICUS/S2_HARMONIZED")
        .filterDate(start_date, end_date)
        .filterBounds(region)
        .filter(ee.Filter.lte("CLOUDY_PIXEL_PERCENTAGE", cloud_pct))
    )

    ids = s2.aggregate_array("system:index")

    dw = ee.ImageCollection("GOOGLE/DYNAMICWORLD/V1").filter(
        ee.Filter.inList("system:index", ids)
    )

    collection = dw.select("label")

    dwVisParams = {
        "min": 0,
        "max": 8,
        "palette": [
            "#419BDF",
            "#397D49",
            "#88B053",
            "#7A87C6",
            "#E49635",
            "#DFC35A",
            "#C4281B",
            "#A59B8F",
            "#B39FE1",
        ],
    }

    images = create_timeseries(
        collection,
        start_date,
        end_date,
        region,
        None,
        frequency,
        reducer,
        drop_empty,
        date_format,
        parallel_scale,
    )

    if return_type == "class":
        return images
    elif return_type == "visualize":
        result = images.map(lambda img: img.visualize(**dwVisParams))
        return result
    else:
        # Create a Top-1 Probability Hillshade Visualization
        probabilityBands = [
            "water",
            "trees",
            "grass",
            "flooded_vegetation",
            "crops",
            "shrub_and_scrub",
            "built",
            "bare",
            "snow_and_ice",
        ]

        # Select probability bands
        probabilityCol = dw.select(probabilityBands)

        prob_col = create_timeseries(
            probabilityCol,
            start_date,
            end_date,
            region,
            None,
            frequency,
            "mean",
            drop_empty,
            date_format,
            parallel_scale,
        )

        prob_images = ee.ImageCollection(
            prob_col.map(
                lambda img: img.reduce(ee.Reducer.max()).set(
                    "system:time_start", img.get("system:time_start")
                )
            )
        )

        if return_type == "probability":
            return prob_images

        elif return_type == "hillshade":
            count = prob_images.size()
            nums = ee.List.sequence(0, count.subtract(1))

            def create_hillshade(d):
                proj = ee.Projection("EPSG:3857").atScale(10)
                img = ee.Image(images.toList(images.size()).get(d))
                prob_img = ee.Image(prob_images.toList(prob_images.size()).get(d))
                prob_img = prob_img.setDefaultProjection(proj)
                top1Confidence = prob_img.multiply(100).int()
                hillshade = ee.Terrain.hillshade(top1Confidence).divide(255)
                rgbImage = img.visualize(**dwVisParams).divide(255)
                probabilityHillshade = rgbImage.multiply(hillshade)
                return probabilityHillshade.set(
                    "system:time_start", img.get("system:time_start")
                )

            result = ee.ImageCollection(nums.map(create_hillshade))
            return result

edit_download_html(htmlWidget, filename, title='Click here to download: ')

Downloads a file from voila. Adopted from https://github.com/voila-dashboards/voila/issues/578#issuecomment-617668058

Parameters:

Name	Type	Description	Default
htmlWidget	object	The HTML widget to display the URL.	required
filename	str	File path to download.	required
title	str	Download description. Defaults to "Click here to download: ".	'Click here to download: '

Source code in geemap/common.py

def edit_download_html(htmlWidget, filename, title="Click here to download: "):
    """Downloads a file from voila. Adopted from https://github.com/voila-dashboards/voila/issues/578#issuecomment-617668058

    Args:
        htmlWidget (object): The HTML widget to display the URL.
        filename (str): File path to download.
        title (str, optional): Download description. Defaults to "Click here to download: ".
    """

    # from IPython.display import HTML
    # import ipywidgets as widgets
    import base64

    # Change widget html temporarily to a font-awesome spinner
    htmlWidget.value = '<i class="fa fa-spinner fa-spin fa-2x fa-fw"></i><span class="sr-only">Loading...</span>'

    # Process raw data
    data = open(filename, "rb").read()
    b64 = base64.b64encode(data)
    payload = b64.decode()

    basename = os.path.basename(filename)

    # Create and assign html to widget
    html = '<a download="{filename}" href="data:text/csv;base64,{payload}" target="_blank">{title}</a>'
    htmlWidget.value = html.format(
        payload=payload, title=title + basename, filename=basename
    )

ee_api_to_csv(outfile=None, timeout=300, proxies=None)

Extracts Earth Engine API documentation from https://developers.google.com/earth-engine/api_docs as a csv file.

Parameters:

Name	Type	Description	Default
outfile	str	The output file path to a csv file. Defaults to None.	None
timeout	int	Timeout in seconds. Defaults to 300.	300
proxies	dict	Proxy settings. Defaults to None.	None

Source code in geemap/common.py

def ee_api_to_csv(outfile=None, timeout=300, proxies=None):
    """Extracts Earth Engine API documentation from https://developers.google.com/earth-engine/api_docs as a csv file.

    Args:
        outfile (str, optional): The output file path to a csv file. Defaults to None.
        timeout (int, optional): Timeout in seconds. Defaults to 300.
        proxies (dict, optional): Proxy settings. Defaults to None.
    """
    from bs4 import BeautifulSoup

    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    data_dir = os.path.join(pkg_dir, "data")
    template_dir = os.path.join(data_dir, "template")
    csv_file = os.path.join(template_dir, "ee_api_docs.csv")

    if outfile is None:
        outfile = csv_file
    else:
        if not outfile.endswith(".csv"):
            print("The output file must end with .csv")
            return
        else:
            out_dir = os.path.dirname(outfile)
            if not os.path.exists(out_dir):
                os.makedirs(out_dir)

    url = "https://developers.google.com/earth-engine/api_docs"

    try:
        r = requests.get(url, timeout=timeout, proxies=proxies)
        soup = BeautifulSoup(r.content, "html.parser")

        names = []
        descriptions = []
        functions = []
        returns = []
        arguments = []
        types = []
        details = []

        names = [h2.text for h2 in soup.find_all("h2")]
        descriptions = [h2.next_sibling.next_sibling.text for h2 in soup.find_all("h2")]
        func_tables = soup.find_all("table", class_="blue")
        functions = [func_table.find("code").text for func_table in func_tables]
        returns = [func_table.find_all("td")[1].text for func_table in func_tables]

        detail_tables = []
        tables = soup.find_all("table", class_="blue")

        for table in tables:
            item = table.next_sibling
            if item.attrs == {"class": ["details"]}:
                detail_tables.append(item)
            else:
                detail_tables.append("")

        for detail_table in detail_tables:
            if detail_table != "":
                items = [item.text for item in detail_table.find_all("code")]
            else:
                items = ""
            arguments.append(items)

        for detail_table in detail_tables:
            if detail_table != "":
                items = [item.text for item in detail_table.find_all("td")]
                items = items[1::3]
            else:
                items = ""
            types.append(items)

        for detail_table in detail_tables:
            if detail_table != "":
                items = [item.text for item in detail_table.find_all("p")]
            else:
                items = ""
            details.append(items)

        with open(outfile, "w", encoding="utf-8") as csv_file:
            csv_writer = csv.writer(csv_file, delimiter="\t")

            csv_writer.writerow(
                [
                    "name",
                    "description",
                    "function",
                    "returns",
                    "argument",
                    "type",
                    "details",
                ]
            )

            for i in range(len(names)):
                name = names[i]
                description = descriptions[i]
                function = functions[i]
                return_type = returns[i]
                argument = "|".join(arguments[i])
                argu_type = "|".join(types[i])
                detail = "|".join(details[i])

                csv_writer.writerow(
                    [
                        name,
                        description,
                        function,
                        return_type,
                        argument,
                        argu_type,
                        detail,
                    ]
                )

    except Exception as e:
        print(e)

ee_data_html(asset)

Generates HTML from an asset to be used in the HTML widget.

Parameters:

Name	Type	Description	Default
asset	dict	A dictionary containing an Earth Engine asset.	required

Returns:

Name	Type	Description
str		A string containing HTML.

Source code in geemap/common.py

def ee_data_html(asset):
    """Generates HTML from an asset to be used in the HTML widget.

    Args:
        asset (dict): A dictionary containing an Earth Engine asset.

    Returns:
        str: A string containing HTML.
    """
    try:
        asset_title = asset.get("title", "Unknown")
        asset_dates = asset.get("dates", "Unknown")
        ee_id_snippet = asset.get("id", "Unknown")
        asset_uid = asset.get("uid", None)
        asset_url = asset.get("asset_url", "")
        code_url = asset.get("sample_code", None)
        thumbnail_url = asset.get("thumbnail_url", None)
        asset_type = asset.get("type", "Unknown")

        if asset_type == "image":
            ee_id_snippet = "ee.Image('{}')".format(ee_id_snippet)
        elif asset_type == "image_collection":
            ee_id_snippet = "ee.ImageCollection('{}')".format(ee_id_snippet)
        elif asset_type == "table":
            ee_id_snippet = "ee.FeatureCollection('{}')".format(ee_id_snippet)

        if not code_url and asset_uid:
            coder_url = f"""https://code.earthengine.google.com/?scriptPath=Examples%3ADatasets%2F{asset_uid}"""
        else:
            coder_url = code_url

        ## ee datasets always have a asset_url, and should have a thumbnail
        catalog = (
            bool(asset_url)
            * f"""
                    <h4>Data Catalog</h4>
                        <p style="margin-left: 40px"><a href="{asset_url.replace('terms-of-use','description')}" target="_blank">Description</a></p>
                        <p style="margin-left: 40px"><a href="{asset_url.replace('terms-of-use','bands')}" target="_blank">Bands</a></p>
                        <p style="margin-left: 40px"><a href="{asset_url.replace('terms-of-use','image-properties')}" target="_blank">Properties</a></p>
                        <p style="margin-left: 40px"><a href="{coder_url}" target="_blank">Example</a></p>
                    """
        )
        thumbnail = (
            bool(thumbnail_url)
            * f"""
                    <h4>Dataset Thumbnail</h4>
                    <img src="{thumbnail_url}">
                    """
        )
        ## only community datasets have a code_url
        alternative = (
            bool(code_url)
            * f"""
                    <h4>Community Catalog</h4>
                        <p style="margin-left: 40px">{asset.get('provider','Provider unknown')}</p>
                        <p style="margin-left: 40px">{asset.get('tags','Tags unknown')}</p>
                        <p style="margin-left: 40px"><a href="{coder_url}" target="_blank">Example</a></p>
                    """
        )

        template = f"""
            <html>
            <body>
                <h3>{asset_title}</h3>
                <h4>Dataset Availability</h4>
                    <p style="margin-left: 40px">{asset_dates}</p>
                <h4>Earth Engine Snippet</h4>
                    <p style="margin-left: 40px">{ee_id_snippet}</p>
                {catalog}
                {alternative}
                {thumbnail}
            </body>
            </html>
        """
        return template

    except Exception as e:
        print(e)

ee_data_thumbnail(asset_id, timeout=300, proxies=None)

Retrieves the thumbnail URL of an Earth Engine asset.

Parameters:

Name	Type	Description	Default
asset_id	str	An Earth Engine asset id.	required
timeout	int	Timeout in seconds. Defaults to 300.	300
proxies	dict	Proxy settings. Defaults to None.	None

Returns:

Name	Type	Description
str		An http url of the thumbnail.

Source code in geemap/common.py

def ee_data_thumbnail(asset_id, timeout=300, proxies=None):
    """Retrieves the thumbnail URL of an Earth Engine asset.

    Args:
        asset_id (str): An Earth Engine asset id.
        timeout (int, optional): Timeout in seconds. Defaults to 300.
        proxies (dict, optional): Proxy settings. Defaults to None.

    Returns:
        str: An http url of the thumbnail.
    """
    import urllib

    from bs4 import BeautifulSoup

    asset_uid = asset_id.replace("/", "_")
    asset_url = "https://developers.google.com/earth-engine/datasets/catalog/{}".format(
        asset_uid
    )
    thumbnail_url = "https://mw1.google.com/ges/dd/images/{}_sample.png".format(
        asset_uid
    )

    r = requests.get(thumbnail_url, timeout=timeout, proxies=proxies)

    try:
        if r.status_code != 200:
            html_page = urllib.request.urlopen(asset_url)
            soup = BeautifulSoup(html_page, features="html.parser")

            for img in soup.findAll("img"):
                if "sample.png" in img.get("src"):
                    thumbnail_url = img.get("src")
                    return thumbnail_url

        return thumbnail_url
    except Exception as e:
        print(e)

ee_export_geojson(ee_object, filename=None, selectors=None, timeout=300, proxies=None)

Exports Earth Engine FeatureCollection to geojson.

Parameters:

Name	Type	Description	Default
ee_object	object	ee.FeatureCollection to export.	required
filename	str	Output file name. Defaults to None.	None
selectors	list	A list of attributes to export. Defaults to None.	None
timeout	int	Timeout in seconds. Defaults to 300 seconds.	300
proxies	dict	Proxy settings. Defaults to None.	None

Source code in geemap/common.py

def ee_export_geojson(
    ee_object, filename=None, selectors=None, timeout=300, proxies=None
):
    """Exports Earth Engine FeatureCollection to geojson.

    Args:
        ee_object (object): ee.FeatureCollection to export.
        filename (str): Output file name. Defaults to None.
        selectors (list, optional): A list of attributes to export. Defaults to None.
        timeout (int, optional): Timeout in seconds. Defaults to 300 seconds.
        proxies (dict, optional): Proxy settings. Defaults to None.
    """

    if not isinstance(ee_object, ee.FeatureCollection):
        print("The ee_object must be an ee.FeatureCollection.")
        return

    if filename is None:
        out_dir = os.path.join(os.path.expanduser("~"), "Downloads")
        filename = os.path.join(out_dir, random_string(6) + ".geojson")

    allowed_formats = ["geojson"]
    filename = os.path.abspath(filename)
    basename = os.path.basename(filename)
    name = os.path.splitext(basename)[0]
    filetype = os.path.splitext(basename)[1][1:].lower()

    if not (filetype.lower() in allowed_formats):
        print("The output file type must be geojson.")
        return

    if selectors is None:
        selectors = ee_object.first().propertyNames().getInfo()
        selectors = [".geo"] + selectors

    elif not isinstance(selectors, list):
        print("selectors must be a list, such as ['attribute1', 'attribute2']")
        return
    else:
        allowed_attributes = ee_object.first().propertyNames().getInfo()
        for attribute in selectors:
            if not (attribute in allowed_attributes):
                print(
                    "Attributes must be one chosen from: {} ".format(
                        ", ".join(allowed_attributes)
                    )
                )
                return

    try:
        # print('Generating URL ...')
        url = ee_object.getDownloadURL(
            filetype=filetype, selectors=selectors, filename=name
        )
        # print('Downloading data from {}\nPlease wait ...'.format(url))
        r = None
        r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)

        if r.status_code != 200:
            print("An error occurred while downloading. \n Retrying ...")
            try:
                new_ee_object = ee_object.map(filter_polygons)
                print("Generating URL ...")
                url = new_ee_object.getDownloadURL(
                    filetype=filetype, selectors=selectors, filename=name
                )
                print(f"Downloading data from {url}\nPlease wait ...")
                r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)
            except Exception as e:
                print(e)

        with open(filename, "wb") as fd:
            for chunk in r.iter_content(chunk_size=1024):
                fd.write(chunk)
    except Exception as e:
        print("An error occurred while downloading.")
        if r is not None:
            print(r.json()["error"]["message"])

        return

    with open(filename) as f:
        geojson = f.read()

    return geojson

ee_export_image(ee_object, filename, scale=None, crs=None, crs_transform=None, region=None, dimensions=None, file_per_band=False, format='ZIPPED_GEO_TIFF', unzip=True, unmask_value=None, timeout=300, proxies=None, verbose=True)

Exports an ee.Image as a GeoTIFF.

Parameters:

Name	Type	Description	Default
ee_object	object	The ee.Image to download.	required
filename	str	Output filename for the exported image.	required
scale	float	A default scale to use for any bands that do not specify one; ignored if crs and crs_transform is specified. Defaults to None.	None
crs	str	A default CRS string to use for any bands that do not explicitly specify one. Defaults to None.	None
crs_transform	list	a default affine transform to use for any bands that do not specify one, of the same format as the crs_transform of bands. Defaults to None.	None
region	object	A polygon specifying a region to download; ignored if crs and crs_transform is specified. Defaults to None.	None
dimensions	list	An optional array of two integers defining the width and height to which the band is cropped. Defaults to None.	None
file_per_band	bool	Whether to produce a different GeoTIFF per band. Defaults to False.	False
format	str	One of: "ZIPPED_GEO_TIFF" (GeoTIFF file(s) wrapped in a zip file, default), "GEO_TIFF" (GeoTIFF file), "NPY" (NumPy binary format). If "GEO_TIFF" or "NPY", filePerBand and all band-level transformations will be ignored. Loading a NumPy output results in a structured array.	'ZIPPED_GEO_TIFF'
unzip	bool	Whether to unzip the downloaded file. Defaults to True.	True
unmask_value	float	The value to use for pixels that are masked in the input image. If the exported image contains zero values, you should set the unmask value to a non-zero value so that the zero values are not treated as missing data. Defaults to None.	None
timeout	int	The timeout in seconds for the request. Defaults to 300.	300
proxies	dict	A dictionary of proxy servers to use. Defaults to None.	None
verbose	bool	Whether to print out descriptive text. Defaults to True.	True

Source code in geemap/common.py

def ee_export_image(
    ee_object,
    filename,
    scale=None,
    crs=None,
    crs_transform=None,
    region=None,
    dimensions=None,
    file_per_band=False,
    format="ZIPPED_GEO_TIFF",
    unzip=True,
    unmask_value=None,
    timeout=300,
    proxies=None,
    verbose=True,
):
    """Exports an ee.Image as a GeoTIFF.

    Args:
        ee_object (object): The ee.Image to download.
        filename (str): Output filename for the exported image.
        scale (float, optional): A default scale to use for any bands that do not specify one; ignored if crs and crs_transform is specified. Defaults to None.
        crs (str, optional): A default CRS string to use for any bands that do not explicitly specify one. Defaults to None.
        crs_transform (list, optional): a default affine transform to use for any bands that do not specify one, of the same format as the crs_transform of bands. Defaults to None.
        region (object, optional): A polygon specifying a region to download; ignored if crs and crs_transform is specified. Defaults to None.
        dimensions (list, optional): An optional array of two integers defining the width and height to which the band is cropped. Defaults to None.
        file_per_band (bool, optional): Whether to produce a different GeoTIFF per band. Defaults to False.
        format (str, optional):  One of: "ZIPPED_GEO_TIFF" (GeoTIFF file(s) wrapped in a zip file, default), "GEO_TIFF" (GeoTIFF file), "NPY" (NumPy binary format). If "GEO_TIFF" or "NPY",
            filePerBand and all band-level transformations will be ignored. Loading a NumPy output results in a structured array.
        unzip (bool, optional): Whether to unzip the downloaded file. Defaults to True.
        unmask_value (float, optional): The value to use for pixels that are masked in the input image.
            If the exported image contains zero values, you should set the unmask value to a  non-zero value so that the zero values are not treated as missing data. Defaults to None.
        timeout (int, optional): The timeout in seconds for the request. Defaults to 300.
        proxies (dict, optional): A dictionary of proxy servers to use. Defaults to None.
        verbose (bool, optional): Whether to print out descriptive text. Defaults to True.
    """

    if not isinstance(ee_object, ee.Image):
        print("The ee_object must be an ee.Image.")
        return

    if unmask_value is not None:
        ee_object = ee_object.selfMask().unmask(unmask_value)
        if isinstance(region, ee.Geometry):
            ee_object = ee_object.clip(region)
        elif isinstance(region, ee.FeatureCollection):
            ee_object = ee_object.clipToCollection(region)

    filename = os.path.abspath(filename)
    basename = os.path.basename(filename)
    name = os.path.splitext(basename)[0]
    filetype = os.path.splitext(basename)[1][1:].lower()
    filename_zip = filename.replace(".tif", ".zip")

    if filetype != "tif":
        print("The filename must end with .tif")
        return

    try:
        if verbose:
            print("Generating URL ...")
        params = {"name": name, "filePerBand": file_per_band}

        params["scale"] = scale
        if region is None:
            region = ee_object.geometry()
        if dimensions is not None:
            params["dimensions"] = dimensions
        if region is not None:
            params["region"] = region
        if crs is not None:
            params["crs"] = crs
        if crs_transform is not None:
            params["crs_transform"] = crs_transform
        if format != "ZIPPED_GEO_TIFF":
            params["format"] = format

        try:
            url = ee_object.getDownloadURL(params)
        except Exception as e:
            print("An error occurred while downloading.")
            print(e)
            return

        if verbose:
            print(f"Downloading data from {url}\nPlease wait ...")
        # Need to initialize r to something because of how we currently handle errors
        # We should aim to refactor the code such that only one try block is needed
        r = None
        r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)

        if r.status_code != 200:
            print("An error occurred while downloading.")
            return

        with open(filename_zip, "wb") as fd:
            for chunk in r.iter_content(chunk_size=1024):
                fd.write(chunk)

    except Exception as e:
        print("An error occurred while downloading.")
        if r is not None:
            print(r.json()["error"]["message"])
        return

    try:
        if unzip:
            with zipfile.ZipFile(filename_zip) as z:
                z.extractall(os.path.dirname(filename))
            os.remove(filename_zip)

        if verbose:
            if file_per_band:
                print(f"Data downloaded to {os.path.dirname(filename)}")
            else:
                print(f"Data downloaded to {filename}")
    except Exception as e:
        print(e)

ee_export_image_collection(ee_object, out_dir, scale=None, crs=None, crs_transform=None, region=None, dimensions=None, file_per_band=False, format='ZIPPED_GEO_TIFF', unmask_value=None, filenames=None, timeout=300, proxies=None, verbose=True)

Exports an ImageCollection as GeoTIFFs.

Parameters:

Name	Type	Description	Default
ee_object	object	The ee.Image to download.	required
out_dir	str	The output directory for the exported images.	required
scale	float	A default scale to use for any bands that do not specify one; ignored if crs and crs_transform is specified. Defaults to None.	None
crs	str	A default CRS string to use for any bands that do not explicitly specify one. Defaults to None.	None
crs_transform	list	a default affine transform to use for any bands that do not specify one, of the same format as the crs_transform of bands. Defaults to None.	None
region	object	A polygon specifying a region to download; ignored if crs and crs_transform is specified. Defaults to None.	None
dimensions	list	An optional array of two integers defining the width and height to which the band is cropped. Defaults to None.	None
file_per_band	bool	Whether to produce a different GeoTIFF per band. Defaults to False.	False
format	str	One of: "ZIPPED_GEO_TIFF" (GeoTIFF file(s) wrapped in a zip file, default), "GEO_TIFF" (GeoTIFF file), "NPY" (NumPy binary format). If "GEO_TIFF" or "NPY", filePerBand and all band-level transformations will be ignored. Loading a NumPy output results in a structured array.	'ZIPPED_GEO_TIFF'
unmask_value	float	The value to use for pixels that are masked in the input image. If the exported image contains zero values, you should set the unmask value to a non-zero value so that the zero values are not treated as missing data. Defaults to None.	None
filenames	list | int	A list of filenames to use for the exported images. Defaults to None.	None
timeout	int	The timeout in seconds for the request. Defaults to 300.	300
proxies	dict	A dictionary of proxy servers to use. Defaults to None.	None
verbose	bool	Whether to print out descriptive text. Defaults to True.	True

Source code in geemap/common.py

def ee_export_image_collection(
    ee_object,
    out_dir,
    scale=None,
    crs=None,
    crs_transform=None,
    region=None,
    dimensions=None,
    file_per_band=False,
    format="ZIPPED_GEO_TIFF",
    unmask_value=None,
    filenames=None,
    timeout=300,
    proxies=None,
    verbose=True,
):
    """Exports an ImageCollection as GeoTIFFs.

    Args:
        ee_object (object): The ee.Image to download.
        out_dir (str): The output directory for the exported images.
        scale (float, optional): A default scale to use for any bands that do not specify one; ignored if crs and crs_transform is specified. Defaults to None.
        crs (str, optional): A default CRS string to use for any bands that do not explicitly specify one. Defaults to None.
        crs_transform (list, optional): a default affine transform to use for any bands that do not specify one, of the same format as the crs_transform of bands. Defaults to None.
        region (object, optional): A polygon specifying a region to download; ignored if crs and crs_transform is specified. Defaults to None.
        dimensions (list, optional): An optional array of two integers defining the width and height to which the band is cropped. Defaults to None.
        file_per_band (bool, optional): Whether to produce a different GeoTIFF per band. Defaults to False.
        format (str, optional):  One of: "ZIPPED_GEO_TIFF" (GeoTIFF file(s) wrapped in a zip file, default), "GEO_TIFF" (GeoTIFF file), "NPY" (NumPy binary format). If "GEO_TIFF" or "NPY",
            filePerBand and all band-level transformations will be ignored. Loading a NumPy output results in a structured array.
        unmask_value (float, optional): The value to use for pixels that are masked in the input image.
            If the exported image contains zero values, you should set the unmask value to a  non-zero value so that the zero values are not treated as missing data. Defaults to None.
        filenames (list | int, optional): A list of filenames to use for the exported images. Defaults to None.
        timeout (int, optional): The timeout in seconds for the request. Defaults to 300.
        proxies (dict, optional): A dictionary of proxy servers to use. Defaults to None.
        verbose (bool, optional): Whether to print out descriptive text. Defaults to True.
    """

    if not isinstance(ee_object, ee.ImageCollection):
        print("The ee_object must be an ee.ImageCollection.")
        return

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    try:
        count = int(ee_object.size().getInfo())
        if verbose:
            print(f"Total number of images: {count}\n")

        if filenames is None:
            filenames = ee_object.aggregate_array("system:index").getInfo()
        elif isinstance(filenames, int):
            filenames = [str(f + filenames) for f in range(0, count)]

        if len(filenames) != count:
            raise Exception(
                "The number of filenames must be equal to the number of images."
            )

        filenames = [str(f) + ".tif" for f in filenames if not str(f).endswith(".tif")]

        for i in range(0, count):
            image = ee.Image(ee_object.toList(count).get(i))
            filename = os.path.join(out_dir, filenames[i])
            if verbose:
                print(f"Exporting {i + 1}/{count}: {filename}")
            ee_export_image(
                image,
                filename=filename,
                scale=scale,
                crs=crs,
                crs_transform=crs_transform,
                region=region,
                dimensions=dimensions,
                file_per_band=file_per_band,
                format=format,
                unmask_value=unmask_value,
                timeout=timeout,
                proxies=proxies,
            )
            print("\n")

    except Exception as e:
        print(e)

ee_export_image_collection_to_asset(ee_object, descriptions=None, assetIds=None, pyramidingPolicy=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, **kwargs)

Creates a batch task to export an ImageCollection as raster images to Google Drive.

Parameters:

Name	Type	Description	Default
ee_object		The image collection to export.	required
descriptions		A list of human-readable names of the tasks.	None
assetIds		The destination asset ID.	None
pyramidingPolicy		The pyramiding policy to apply to each band in the image, a dictionary keyed by band name. Values must be one of: "mean", "sample", "min", "max", or "mode". Defaults to "mean". A special key, ".default", may be used to change the default for all bands.	None
dimensions		The dimensions of the exported image. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the image's region.	None
scale		The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	None
crs		The coordinate reference system of the exported image's projection. Defaults to the image's default projection.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported image's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image's native CRS transform.	None
maxPixels		The maximum allowed number of pixels in the exported image. The task will fail if the exported region covers more pixels in the specified projection. Defaults to 100,000,000.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform'.	{}

Source code in geemap/common.py

def ee_export_image_collection_to_asset(
    ee_object,
    descriptions=None,
    assetIds=None,
    pyramidingPolicy=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    **kwargs,
):
    """Creates a batch task to export an ImageCollection as raster images to Google Drive.

    Args:
        ee_object: The image collection to export.
        descriptions: A list of human-readable names of the tasks.
        assetIds: The destination asset ID.
        pyramidingPolicy: The pyramiding policy to apply to each band in the
            image, a dictionary keyed by band name. Values must be
            one of: "mean", "sample", "min", "max", or "mode".
            Defaults to "mean". A special key, ".default", may be used to
            change the default for all bands.
        dimensions: The dimensions of the exported image. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the image's
            region.
        scale: The resolution in meters per pixel. Defaults to the
            native resolution of the image asset unless a crsTransform
            is specified.
        crs: The coordinate reference system of the exported image's
            projection. Defaults to the image's default projection.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported image's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image's native CRS transform.
        maxPixels: The maximum allowed number of pixels in the exported
            image. The task will fail if the exported region covers more
            pixels in the specified projection. Defaults to 100,000,000.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform'.
    """

    if not isinstance(ee_object, ee.ImageCollection):
        raise ValueError("The ee_object must be an ee.ImageCollection.")

    try:
        count = int(ee_object.size().getInfo())
        print(f"Total number of images: {count}\n")

        if (descriptions is not None) and (len(descriptions) != count):
            print("The number of descriptions is not equal to the number of images.")
            return

        if descriptions is None:
            descriptions = ee_object.aggregate_array("system:index").getInfo()

        if assetIds is None:
            assetIds = descriptions

        images = ee_object.toList(count)

        if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
            return

        for i in range(0, count):
            image = ee.Image(images.get(i))
            description = descriptions[i]
            assetId = assetIds[i]
            ee_export_image_to_asset(
                image,
                description,
                assetId,
                pyramidingPolicy,
                dimensions,
                region,
                scale,
                crs,
                crsTransform,
                maxPixels,
                **kwargs,
            )

    except Exception as e:
        print(e)

ee_export_image_collection_to_cloud_storage(ee_object, descriptions=None, bucket=None, fileNamePrefix=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, shardSize=None, fileDimensions=None, skipEmptyTiles=None, fileFormat=None, formatOptions=None, **kwargs)

Creates a batch task to export an ImageCollection as raster images to a Google Cloud bucket.

Parameters:

Name	Type	Description	Default
ee_object		The image collection to export.	required
descriptions		A list of human-readable names of the tasks.	None
bucket		The name of a Cloud Storage bucket for the export.	None
fileNamePrefix		Cloud Storage object name prefix for the export. Defaults to the name of the task.	None
dimensions		The dimensions of the exported image. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the image's region.	None
scale		The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	None
crs		The coordinate reference system of the exported image's projection. Defaults to the image's default projection.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported image's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image's native CRS transform.	None
maxPixels		The maximum allowed number of pixels in the exported image. The task will fail if the exported region covers more pixels in the specified projection. Defaults to 100,000,000.	None
shardSize		Size in pixels of the tiles in which this image will be computed. Defaults to 256.	None
fileDimensions		The dimensions in pixels of each image file, if the image is too large to fit in a single file. May specify a single number to indicate a square shape, or a tuple of two dimensions to indicate (width,height). Note that the image will still be clipped to the overall image dimensions. Must be a multiple of shardSize.	None
skipEmptyTiles		If true, skip writing empty (i.e. fully-masked) image tiles. Defaults to false.	None
fileFormat		The string file format to which the image is exported. Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to 'GeoTIFF'.	None
formatOptions		A dictionary of string keys to format specific options.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform'.	{}

Source code in geemap/common.py

def ee_export_image_collection_to_cloud_storage(
    ee_object,
    descriptions=None,
    bucket=None,
    fileNamePrefix=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    shardSize=None,
    fileDimensions=None,
    skipEmptyTiles=None,
    fileFormat=None,
    formatOptions=None,
    **kwargs,
):
    """Creates a batch task to export an ImageCollection as raster images to a Google Cloud bucket.

    Args:
        ee_object: The image collection to export.
        descriptions: A list of human-readable names of the tasks.
        bucket: The name of a Cloud Storage bucket for the export.
        fileNamePrefix: Cloud Storage object name prefix for the export.
            Defaults to the name of the task.
        dimensions: The dimensions of the exported image. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the image's
            region.
        scale: The resolution in meters per pixel. Defaults to the
            native resolution of the image asset unless a crsTransform
            is specified.
        crs: The coordinate reference system of the exported image's
            projection. Defaults to the image's default projection.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported image's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image's native CRS transform.
        maxPixels: The maximum allowed number of pixels in the exported
            image. The task will fail if the exported region covers more
            pixels in the specified projection. Defaults to 100,000,000.
        shardSize: Size in pixels of the tiles in which this image will be
            computed. Defaults to 256.
        fileDimensions: The dimensions in pixels of each image file, if the
            image is too large to fit in a single file. May specify a
            single number to indicate a square shape, or a tuple of two
            dimensions to indicate (width,height). Note that the image will
            still be clipped to the overall image dimensions. Must be a
            multiple of shardSize.
        skipEmptyTiles: If true, skip writing empty (i.e. fully-masked)
            image tiles. Defaults to false.
        fileFormat: The string file format to which the image is exported.
            Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to
            'GeoTIFF'.
        formatOptions: A dictionary of string keys to format specific options.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform'.
    """

    if not isinstance(ee_object, ee.ImageCollection):
        raise ValueError("The ee_object must be an ee.ImageCollection.")

    try:
        count = int(ee_object.size().getInfo())
        print(f"Total number of images: {count}\n")

        if (descriptions is not None) and (len(descriptions) != count):
            print("The number of descriptions is not equal to the number of images.")
            return

        if descriptions is None:
            descriptions = ee_object.aggregate_array("system:index").getInfo()

        images = ee_object.toList(count)

        if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
            return

        for i in range(0, count):
            image = ee.Image(images.get(i))
            description = descriptions[i]
            ee_export_image_to_cloud_storage(
                image,
                description,
                bucket,
                fileNamePrefix,
                dimensions,
                region,
                scale,
                crs,
                crsTransform,
                maxPixels,
                shardSize,
                fileDimensions,
                skipEmptyTiles,
                fileFormat,
                formatOptions,
                **kwargs,
            )

    except Exception as e:
        print(e)

ee_export_image_collection_to_drive(ee_object, descriptions=None, folder=None, fileNamePrefix=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, shardSize=None, fileDimensions=None, skipEmptyTiles=None, fileFormat=None, formatOptions=None, **kwargs)

Creates a batch task to export an ImageCollection as raster images to Google Drive.

Parameters:

Name	Type	Description	Default
ee_object		The image collection to export.	required
descriptions		A list of human-readable names of the tasks.	None
folder		The name of a unique folder in your Drive account to export into. Defaults to the root of the drive.	None
fileNamePrefix		The Google Drive filename for the export. Defaults to the name of the task.	None
dimensions		The dimensions of the exported image. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the image's region.	None
scale		The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	None
crs		The coordinate reference system of the exported image's projection. Defaults to the image's default projection.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported image's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image's native CRS transform.	None
maxPixels		The maximum allowed number of pixels in the exported image. The task will fail if the exported region covers more pixels in the specified projection. Defaults to 100,000,000.	None
shardSize		Size in pixels of the tiles in which this image will be computed. Defaults to 256.	None
fileDimensions		The dimensions in pixels of each image file, if the image is too large to fit in a single file. May specify a single number to indicate a square shape, or a tuple of two dimensions to indicate (width,height). Note that the image will still be clipped to the overall image dimensions. Must be a multiple of shardSize.	None
skipEmptyTiles		If true, skip writing empty (i.e. fully-masked) image tiles. Defaults to false.	None
fileFormat		The string file format to which the image is exported. Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to 'GeoTIFF'.	None
formatOptions		A dictionary of string keys to format specific options.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform', 'driveFolder', and 'driveFileNamePrefix'.	{}

Source code in geemap/common.py

def ee_export_image_collection_to_drive(
    ee_object,
    descriptions=None,
    folder=None,
    fileNamePrefix=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    shardSize=None,
    fileDimensions=None,
    skipEmptyTiles=None,
    fileFormat=None,
    formatOptions=None,
    **kwargs,
):
    """Creates a batch task to export an ImageCollection as raster images to Google Drive.

    Args:
        ee_object: The image collection to export.
        descriptions: A list of human-readable names of the tasks.
        folder: The name of a unique folder in your Drive account to
            export into. Defaults to the root of the drive.
        fileNamePrefix: The Google Drive filename for the export.
            Defaults to the name of the task.
        dimensions: The dimensions of the exported image. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the image's
            region.
        scale: The resolution in meters per pixel. Defaults to the
            native resolution of the image asset unless a crsTransform
            is specified.
        crs: The coordinate reference system of the exported image's
            projection. Defaults to the image's default projection.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported image's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image's native CRS transform.
        maxPixels: The maximum allowed number of pixels in the exported
            image. The task will fail if the exported region covers more
            pixels in the specified projection. Defaults to 100,000,000.
        shardSize: Size in pixels of the tiles in which this image will be
            computed. Defaults to 256.
        fileDimensions: The dimensions in pixels of each image file, if the
            image is too large to fit in a single file. May specify a
            single number to indicate a square shape, or a tuple of two
            dimensions to indicate (width,height). Note that the image will
            still be clipped to the overall image dimensions. Must be a
            multiple of shardSize.
        skipEmptyTiles: If true, skip writing empty (i.e. fully-masked)
            image tiles. Defaults to false.
        fileFormat: The string file format to which the image is exported.
            Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to
            'GeoTIFF'.
        formatOptions: A dictionary of string keys to format specific options.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform', 'driveFolder', and 'driveFileNamePrefix'.
    """

    if not isinstance(ee_object, ee.ImageCollection):
        raise ValueError("The ee_object must be an ee.ImageCollection.")

    try:
        count = int(ee_object.size().getInfo())
        print(f"Total number of images: {count}\n")

        if (descriptions is not None) and (len(descriptions) != count):
            raise ValueError(
                "The number of descriptions is not equal to the number of images."
            )

        if descriptions is None:
            descriptions = ee_object.aggregate_array("system:index").getInfo()

        images = ee_object.toList(count)

        if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
            return

        for i in range(0, count):
            image = ee.Image(images.get(i))
            description = descriptions[i]
            ee_export_image_to_drive(
                image,
                description,
                folder,
                fileNamePrefix,
                dimensions,
                region,
                scale,
                crs,
                crsTransform,
                maxPixels,
                shardSize,
                fileDimensions,
                skipEmptyTiles,
                fileFormat,
                formatOptions,
                **kwargs,
            )

    except Exception as e:
        print(e)

ee_export_image_to_asset(image, description='myExportImageTask', assetId=None, pyramidingPolicy=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, **kwargs)

Creates a task to export an EE Image to an EE Asset.

Parameters:

Name	Type	Description	Default
image		The image to be exported.	required
description		Human-readable name of the task.	'myExportImageTask'
assetId		The destination asset ID.	None
pyramidingPolicy		The pyramiding policy to apply to each band in the image, a dictionary keyed by band name. Values must be one of: "mean", "sample", "min", "max", or "mode". Defaults to "mean". A special key, ".default", may be used to change the default for all bands.	None
dimensions		The dimensions of the exported image. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the image's region.	None
scale		The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	None
crs		The coordinate reference system of the exported image's projection. Defaults to the image's default projection.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported image's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image's native CRS transform.	None
maxPixels		The maximum allowed number of pixels in the exported image. The task will fail if the exported region covers more pixels in the specified projection. Defaults to 100,000,000.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform'.	{}

Source code in geemap/common.py

def ee_export_image_to_asset(
    image,
    description="myExportImageTask",
    assetId=None,
    pyramidingPolicy=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    **kwargs,
):
    """Creates a task to export an EE Image to an EE Asset.

    Args:
        image: The image to be exported.
        description: Human-readable name of the task.
        assetId: The destination asset ID.
        pyramidingPolicy: The pyramiding policy to apply to each band in the
            image, a dictionary keyed by band name. Values must be
            one of: "mean", "sample", "min", "max", or "mode".
            Defaults to "mean". A special key, ".default", may be used to
            change the default for all bands.
        dimensions: The dimensions of the exported image. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the image's
            region.
        scale: The resolution in meters per pixel. Defaults to the
            native resolution of the image asset unless a crsTransform
            is specified.
        crs: The coordinate reference system of the exported image's
            projection. Defaults to the image's default projection.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported image's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image's native CRS transform.
        maxPixels: The maximum allowed number of pixels in the exported
            image. The task will fail if the exported region covers more
            pixels in the specified projection. Defaults to 100,000,000.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform'.
    """

    if isinstance(image, ee.Image) or isinstance(image, ee.image.Image):
        pass
    else:
        raise ValueError("Input image must be an instance of ee.Image")

    if isinstance(assetId, str):
        if assetId.startswith("users/") or assetId.startswith("projects/"):
            pass
        else:
            assetId = f"{ee_user_id()}/{assetId}"

    task = ee.batch.Export.image.toAsset(
        image,
        description,
        assetId,
        pyramidingPolicy,
        dimensions,
        region,
        scale,
        crs,
        crsTransform,
        maxPixels,
        **kwargs,
    )
    task.start()

ee_export_image_to_cloud_storage(image, description='myExportImageTask', bucket=None, fileNamePrefix=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, shardSize=None, fileDimensions=None, skipEmptyTiles=None, fileFormat=None, formatOptions=None, **kwargs)

Creates a task to export an EE Image to Google Cloud Storage.

Parameters:

Name	Type	Description	Default
image		The image to be exported.	required
description		Human-readable name of the task.	'myExportImageTask'
bucket		The name of a Cloud Storage bucket for the export.	None
fileNamePrefix		Cloud Storage object name prefix for the export. Defaults to the name of the task.	None
dimensions		The dimensions of the exported image. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the image's region.	None
scale		The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	None
crs		The coordinate reference system of the exported image's projection. Defaults to the image's default projection.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported image's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image's native CRS transform.	None
maxPixels		The maximum allowed number of pixels in the exported image. The task will fail if the exported region covers more pixels in the specified projection. Defaults to 100,000,000.	None
shardSize		Size in pixels of the tiles in which this image will be computed. Defaults to 256.	None
fileDimensions		The dimensions in pixels of each image file, if the image is too large to fit in a single file. May specify a single number to indicate a square shape, or a tuple of two dimensions to indicate (width,height). Note that the image will still be clipped to the overall image dimensions. Must be a multiple of shardSize.	None
skipEmptyTiles		If true, skip writing empty (i.e. fully-masked) image tiles. Defaults to false.	None
fileFormat		The string file format to which the image is exported. Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to 'GeoTIFF'.	None
formatOptions		A dictionary of string keys to format specific options.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform'.	{}

Source code in geemap/common.py

def ee_export_image_to_cloud_storage(
    image,
    description="myExportImageTask",
    bucket=None,
    fileNamePrefix=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    shardSize=None,
    fileDimensions=None,
    skipEmptyTiles=None,
    fileFormat=None,
    formatOptions=None,
    **kwargs,
):
    """Creates a task to export an EE Image to Google Cloud Storage.

    Args:
        image: The image to be exported.
        description: Human-readable name of the task.
        bucket: The name of a Cloud Storage bucket for the export.
        fileNamePrefix: Cloud Storage object name prefix for the export.
            Defaults to the name of the task.
        dimensions: The dimensions of the exported image. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the image's
            region.
        scale: The resolution in meters per pixel. Defaults to the
            native resolution of the image asset unless a crsTransform
            is specified.
        crs: The coordinate reference system of the exported image's
            projection. Defaults to the image's default projection.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported image's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image's native CRS transform.
        maxPixels: The maximum allowed number of pixels in the exported
            image. The task will fail if the exported region covers more
            pixels in the specified projection. Defaults to 100,000,000.
        shardSize: Size in pixels of the tiles in which this image will be
            computed. Defaults to 256.
        fileDimensions: The dimensions in pixels of each image file, if the
            image is too large to fit in a single file. May specify a
            single number to indicate a square shape, or a tuple of two
            dimensions to indicate (width,height). Note that the image will
            still be clipped to the overall image dimensions. Must be a
            multiple of shardSize.
        skipEmptyTiles: If true, skip writing empty (i.e. fully-masked)
            image tiles. Defaults to false.
        fileFormat: The string file format to which the image is exported.
            Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to
            'GeoTIFF'.
        formatOptions: A dictionary of string keys to format specific options.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform'.
    """

    if not isinstance(image, ee.Image):
        raise ValueError("Input image must be an instance of ee.Image")

    try:
        task = ee.batch.Export.image.toCloudStorage(
            image,
            description,
            bucket,
            fileNamePrefix,
            dimensions,
            region,
            scale,
            crs,
            crsTransform,
            maxPixels,
            shardSize,
            fileDimensions,
            skipEmptyTiles,
            fileFormat,
            formatOptions,
            **kwargs,
        )
        task.start()
    except Exception as e:
        print(e)

ee_export_image_to_drive(image, description='myExportImageTask', folder=None, fileNamePrefix=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, shardSize=None, fileDimensions=None, skipEmptyTiles=None, fileFormat=None, formatOptions=None, **kwargs)

Creates a batch task to export an Image as a raster to Google Drive.

Parameters:

Name	Type	Description	Default
image		The image to be exported.	required
description		Human-readable name of the task.	'myExportImageTask'
folder		The name of a unique folder in your Drive account to export into. Defaults to the root of the drive.	None
fileNamePrefix		The Google Drive filename for the export. Defaults to the name of the task.	None
dimensions		The dimensions of the exported image. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the image's region.	None
scale		The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	None
crs		The coordinate reference system of the exported image's projection. Defaults to the image's default projection.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported image's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image's native CRS transform.	None
maxPixels		The maximum allowed number of pixels in the exported image. The task will fail if the exported region covers more pixels in the specified projection. Defaults to 100,000,000.	None
shardSize		Size in pixels of the tiles in which this image will be computed. Defaults to 256.	None
fileDimensions		The dimensions in pixels of each image file, if the image is too large to fit in a single file. May specify a single number to indicate a square shape, or a tuple of two dimensions to indicate (width,height). Note that the image will still be clipped to the overall image dimensions. Must be a multiple of shardSize.	None
skipEmptyTiles		If true, skip writing empty (i.e. fully-masked) image tiles. Defaults to false.	None
fileFormat		The string file format to which the image is exported. Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to 'GeoTIFF'.	None
formatOptions		A dictionary of string keys to format specific options.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform', 'driveFolder', and 'driveFileNamePrefix'.	{}

Source code in geemap/common.py

def ee_export_image_to_drive(
    image,
    description="myExportImageTask",
    folder=None,
    fileNamePrefix=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    shardSize=None,
    fileDimensions=None,
    skipEmptyTiles=None,
    fileFormat=None,
    formatOptions=None,
    **kwargs,
):
    """Creates a batch task to export an Image as a raster to Google Drive.

    Args:
        image: The image to be exported.
        description: Human-readable name of the task.
        folder: The name of a unique folder in your Drive account to
            export into. Defaults to the root of the drive.
        fileNamePrefix: The Google Drive filename for the export.
            Defaults to the name of the task.
        dimensions: The dimensions of the exported image. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the image's
            region.
        scale: The resolution in meters per pixel. Defaults to the
            native resolution of the image asset unless a crsTransform
            is specified.
        crs: The coordinate reference system of the exported image's
            projection. Defaults to the image's default projection.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported image's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image's native CRS transform.
        maxPixels: The maximum allowed number of pixels in the exported
            image. The task will fail if the exported region covers more
            pixels in the specified projection. Defaults to 100,000,000.
        shardSize: Size in pixels of the tiles in which this image will be
            computed. Defaults to 256.
        fileDimensions: The dimensions in pixels of each image file, if the
            image is too large to fit in a single file. May specify a
            single number to indicate a square shape, or a tuple of two
            dimensions to indicate (width,height). Note that the image will
            still be clipped to the overall image dimensions. Must be a
            multiple of shardSize.
        skipEmptyTiles: If true, skip writing empty (i.e. fully-masked)
            image tiles. Defaults to false.
        fileFormat: The string file format to which the image is exported.
            Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to
            'GeoTIFF'.
        formatOptions: A dictionary of string keys to format specific options.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform', 'driveFolder', and 'driveFileNamePrefix'.
    """

    if not isinstance(image, ee.Image):
        raise ValueError("Input image must be an instance of ee.Image")

    task = ee.batch.Export.image.toDrive(
        image,
        description,
        folder,
        fileNamePrefix,
        dimensions,
        region,
        scale,
        crs,
        crsTransform,
        maxPixels,
        shardSize,
        fileDimensions,
        skipEmptyTiles,
        fileFormat,
        formatOptions,
        **kwargs,
    )
    task.start()

ee_export_map_to_cloud_storage(image, description='myExportMapTask', bucket=None, fileFormat=None, path=None, writePublicTiles=None, maxZoom=None, scale=None, minZoom=None, region=None, skipEmptyTiles=None, mapsApiKey=None, **kwargs)

Creates a task to export an Image as a pyramid of map tiles.

Exports a rectangular pyramid of map tiles for use with web map viewers. The map tiles will be accompanied by a reference index.html file that displays them using the Google Maps API, and an earth.html file for opening the map on Google Earth.

Parameters:

Name	Type	Description	Default
image		The image to export as tiles.	required
description		Human-readable name of the task.	'myExportMapTask'
bucket		The destination bucket to write to.	None
fileFormat		The map tiles' file format, one of 'auto', 'png', or 'jpeg'. Defaults to 'auto', which means that opaque tiles will be encoded as 'jpg' and tiles with transparency will be encoded as 'png'.	None
path		The string used as the output's path. A trailing '/' is optional. Defaults to the task's description.	None
writePublicTiles		Whether to write public tiles instead of using the bucket's default object ACL. Defaults to True and requires the invoker to be an OWNER of bucket.	None
maxZoom		The maximum zoom level of the map tiles to export.	None
scale		The max image resolution in meters per pixel, as an alternative to 'maxZoom'. The scale will be converted to the most appropriate maximum zoom level at the equator.	None
minZoom		The optional minimum zoom level of the map tiles to export.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Map tiles will be produced in the rectangular region containing this geometry. Defaults to the image's region.	None
skipEmptyTiles		If true, skip writing empty (i.e. fully-transparent) map tiles. Defaults to false.	None
mapsApiKey		Used in index.html to initialize the Google Maps API. This removes the "development purposes only" message from the map.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform'.	{}

Source code in geemap/common.py

def ee_export_map_to_cloud_storage(
    image,
    description="myExportMapTask",
    bucket=None,
    fileFormat=None,
    path=None,
    writePublicTiles=None,
    maxZoom=None,
    scale=None,
    minZoom=None,
    region=None,
    skipEmptyTiles=None,
    mapsApiKey=None,
    **kwargs,
):
    """Creates a task to export an Image as a pyramid of map tiles.

    Exports a rectangular pyramid of map tiles for use with web map
    viewers. The map tiles will be accompanied by a reference
    index.html file that displays them using the Google Maps API,
    and an earth.html file for opening the map on Google Earth.

    Args:
        image: The image to export as tiles.
        description: Human-readable name of the task.
        bucket: The destination bucket to write to.
        fileFormat: The map tiles' file format, one of 'auto', 'png',
            or 'jpeg'. Defaults to 'auto', which means that opaque tiles
            will be encoded as 'jpg' and tiles with transparency will be
            encoded as 'png'.
        path: The string used as the output's path. A trailing '/'
            is optional. Defaults to the task's description.
        writePublicTiles: Whether to write public tiles instead of using the
            bucket's default object ACL. Defaults to True and requires the
            invoker to be an OWNER of bucket.
        maxZoom: The maximum zoom level of the map tiles to export.
        scale: The max image resolution in meters per pixel, as an alternative
            to 'maxZoom'. The scale will be converted to the most appropriate
            maximum zoom level at the equator.
        minZoom: The optional minimum zoom level of the map tiles to export.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Map tiles will be
            produced in the rectangular region containing this geometry.
            Defaults to the image's region.
        skipEmptyTiles: If true, skip writing empty (i.e. fully-transparent)
            map tiles. Defaults to false.
        mapsApiKey: Used in index.html to initialize the Google Maps API. This
            removes the "development purposes only" message from the map.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform'.

    """
    if not isinstance(image, ee.Image):
        raise TypeError("image must be an ee.Image")

    if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
        return

    print(
        f"Exporting {description}... Please check the Task Manager from the JavaScript Code Editor."
    )

    task = ee.batch.Export.map.toCloudStorage(
        image,
        description,
        bucket,
        fileFormat,
        path,
        writePublicTiles,
        maxZoom,
        scale,
        minZoom,
        region,
        skipEmptyTiles,
        mapsApiKey,
        **kwargs,
    )
    task.start()

ee_export_vector(ee_object, filename, selectors=None, verbose=True, keep_zip=False, timeout=300, proxies=None)

Exports Earth Engine FeatureCollection to other formats, including shp, csv, json, kml, and kmz.

Parameters:

Name	Type	Description	Default
ee_object	object	ee.FeatureCollection to export.	required
filename	str	Output file name.	required
selectors	list	A list of attributes to export. Defaults to None.	None
verbose	bool	Whether to print out descriptive text.	True
keep_zip	bool	Whether to keep the downloaded shapefile as a zip file.	False
timeout	int	Timeout in seconds. Defaults to 300 seconds.	300
proxies	dict	A dictionary of proxies to use. Defaults to None.	None

Source code in geemap/common.py

def ee_export_vector(
    ee_object,
    filename,
    selectors=None,
    verbose=True,
    keep_zip=False,
    timeout=300,
    proxies=None,
):
    """Exports Earth Engine FeatureCollection to other formats, including shp, csv, json, kml, and kmz.

    Args:
        ee_object (object): ee.FeatureCollection to export.
        filename (str): Output file name.
        selectors (list, optional): A list of attributes to export. Defaults to None.
        verbose (bool, optional): Whether to print out descriptive text.
        keep_zip (bool, optional): Whether to keep the downloaded shapefile as a zip file.
        timeout (int, optional): Timeout in seconds. Defaults to 300 seconds.
        proxies (dict, optional): A dictionary of proxies to use. Defaults to None.
    """

    if not isinstance(ee_object, ee.FeatureCollection):
        raise ValueError("ee_object must be an ee.FeatureCollection")

    allowed_formats = ["csv", "geojson", "json", "kml", "kmz", "shp"]
    # allowed_formats = ['csv', 'kml', 'kmz']
    filename = os.path.abspath(filename)
    basename = os.path.basename(filename)
    name = os.path.splitext(basename)[0]
    filetype = os.path.splitext(basename)[1][1:].lower()

    if filetype == "shp":
        filename = filename.replace(".shp", ".zip")

    if not (filetype.lower() in allowed_formats):
        raise ValueError(
            "The file type must be one of the following: {}".format(
                ", ".join(allowed_formats)
            )
        )

    if selectors is None:
        selectors = ee_object.first().propertyNames().getInfo()
        if filetype == "csv":
            # remove .geo coordinate field
            ee_object = ee_object.select([".*"], None, False)

    if filetype == "geojson":
        selectors = [".geo"] + selectors

    elif not isinstance(selectors, list):
        raise ValueError(
            "selectors must be a list, such as ['attribute1', 'attribute2']"
        )
    else:
        allowed_attributes = ee_object.first().propertyNames().getInfo()
        for attribute in selectors:
            if not (attribute in allowed_attributes):
                raise ValueError(
                    "Attributes must be one chosen from: {} ".format(
                        ", ".join(allowed_attributes)
                    )
                )

    try:
        if verbose:
            print("Generating URL ...")
        url = ee_object.getDownloadURL(
            filetype=filetype, selectors=selectors, filename=name
        )
        if verbose:
            print(f"Downloading data from {url}\nPlease wait ...")
        r = None
        r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)

        if r.status_code != 200:
            print("An error occurred while downloading. \n Retrying ...")
            try:
                new_ee_object = ee_object.map(filter_polygons)
                print("Generating URL ...")
                url = new_ee_object.getDownloadURL(
                    filetype=filetype, selectors=selectors, filename=name
                )
                print(f"Downloading data from {url}\nPlease wait ...")
                r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)
            except Exception as e:
                print(e)
                raise ValueError

        with open(filename, "wb") as fd:
            for chunk in r.iter_content(chunk_size=1024):
                fd.write(chunk)
    except Exception as e:
        print("An error occurred while downloading.")
        if r is not None:
            print(r.json()["error"]["message"])
        raise ValueError(e)

    try:
        if filetype == "shp":
            with zipfile.ZipFile(filename) as z:
                z.extractall(os.path.dirname(filename))
            if not keep_zip:
                os.remove(filename)
            filename = filename.replace(".zip", ".shp")
        if verbose:
            print(f"Data downloaded to {filename}")
    except Exception as e:
        raise ValueError(e)

ee_export_vector_to_asset(collection, description='myExportTableTask', assetId=None, maxVertices=None, **kwargs)

Creates a task to export a FeatureCollection to Asset.

Parameters:

Name	Type	Description	Default
collection		The feature collection to be exported.	required
description		Human-readable name of the task.	'myExportTableTask'
assetId		The destination asset ID.	None
maxVertices		Max number of uncut vertices per geometry; geometries with more vertices will be cut into pieces smaller than this size.	None
**kwargs		Holds other keyword arguments that may have been deprecated.	{}

Source code in geemap/common.py

def ee_export_vector_to_asset(
    collection,
    description="myExportTableTask",
    assetId=None,
    maxVertices=None,
    **kwargs,
):
    """Creates a task to export a FeatureCollection to Asset.

    Args:
        collection: The feature collection to be exported.
        description: Human-readable name of the task.
        assetId: The destination asset ID.
        maxVertices:
            Max number of uncut vertices per geometry; geometries with more
            vertices will be cut into pieces smaller than this size.
        **kwargs: Holds other keyword arguments that may have been deprecated.
    """
    if not isinstance(collection, ee.FeatureCollection):
        raise ValueError("The collection must be an ee.FeatureCollection.")

    if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
        return

    if isinstance(assetId, str):
        if assetId.startswith("users/") or assetId.startswith("projects/"):
            pass
        else:
            assetId = f"{ee_user_id()}/{assetId}"

    print(assetId)
    print(
        f"Exporting {description}... Please check the Task Manager from the JavaScript Code Editor."
    )

    task = ee.batch.Export.table.toAsset(
        collection,
        description,
        assetId,
        maxVertices,
        **kwargs,
    )
    task.start()

ee_export_vector_to_cloud_storage(collection, description='myExportTableTask', bucket=None, fileNamePrefix=None, fileFormat=None, selectors=None, maxVertices=None, **kwargs)

Creates a task to export a FeatureCollection to Google Cloud Storage.

Parameters:

Name	Type	Description	Default
collection		The feature collection to be exported.	required
description		Human-readable name of the task.	'myExportTableTask'
bucket		The name of a Cloud Storage bucket for the export.	None
fileNamePrefix		Cloud Storage object name prefix for the export. Defaults to the name of the task.	None
fileFormat		The output format: "CSV" (default), "GeoJSON", "KML", "KMZ", "SHP", or "TFRecord".	None
selectors		The list of properties to include in the output, as a list of strings or a comma-separated string. By default, all properties are included.	None
maxVertices		Max number of uncut vertices per geometry; geometries with more vertices will be cut into pieces smaller than this size.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'outputBucket'.	{}

Source code in geemap/common.py

def ee_export_vector_to_cloud_storage(
    collection,
    description="myExportTableTask",
    bucket=None,
    fileNamePrefix=None,
    fileFormat=None,
    selectors=None,
    maxVertices=None,
    **kwargs,
):
    """Creates a task to export a FeatureCollection to Google Cloud Storage.

    Args:
        collection: The feature collection to be exported.
        description: Human-readable name of the task.
        bucket: The name of a Cloud Storage bucket for the export.
        fileNamePrefix: Cloud Storage object name prefix for the export.
            Defaults to the name of the task.
        fileFormat: The output format: "CSV" (default), "GeoJSON", "KML", "KMZ",
            "SHP", or "TFRecord".
        selectors: The list of properties to include in the output, as a list
            of strings or a comma-separated string. By default, all properties
            are included.
        maxVertices:
            Max number of uncut vertices per geometry; geometries with more
            vertices will be cut into pieces smaller than this size.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'outputBucket'.
    """
    if not isinstance(collection, ee.FeatureCollection):
        raise ValueError("The collection must be an ee.FeatureCollection.")

    allowed_formats = ["csv", "geojson", "kml", "kmz", "shp", "tfrecord"]
    if not (fileFormat.lower() in allowed_formats):
        raise ValueError(
            "The file type must be one of the following: {}".format(
                ", ".join(allowed_formats)
            )
        )

    if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
        return

    print(
        f"Exporting {description}... Please check the Task Manager from the JavaScript Code Editor."
    )

    task = ee.batch.Export.table.toCloudStorage(
        collection,
        description,
        bucket,
        fileNamePrefix,
        fileFormat,
        selectors,
        maxVertices,
        **kwargs,
    )
    task.start()

ee_export_vector_to_drive(collection, description='myExportTableTask', folder=None, fileNamePrefix=None, fileFormat=None, selectors=None, maxVertices=None, **kwargs)

Creates a task to export a FeatureCollection to Drive.

Parameters:

Name	Type	Description	Default
collection		The feature collection to be exported.	required
description		Human-readable name of the task.	'myExportTableTask'
folder		The name of a unique folder in your Drive account to export into. Defaults to the root of the drive.	None
fileNamePrefix		The Google Drive filename for the export. Defaults to the name of the task.	None
fileFormat		The output format: "CSV" (default), "GeoJSON", "KML", "KMZ", "SHP", or "TFRecord".	None
selectors		The list of properties to include in the output, as a list of strings or a comma-separated string. By default, all properties are included.	None
maxVertices		Max number of uncut vertices per geometry; geometries with more vertices will be cut into pieces smaller than this size.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'driveFolder' and 'driveFileNamePrefix'.	{}

Source code in geemap/common.py

def ee_export_vector_to_drive(
    collection,
    description="myExportTableTask",
    folder=None,
    fileNamePrefix=None,
    fileFormat=None,
    selectors=None,
    maxVertices=None,
    **kwargs,
):
    """Creates a task to export a FeatureCollection to Drive.

    Args:
        collection: The feature collection to be exported.
        description: Human-readable name of the task.
        folder: The name of a unique folder in your Drive account to
            export into. Defaults to the root of the drive.
        fileNamePrefix: The Google Drive filename for the export.
            Defaults to the name of the task.
        fileFormat: The output format: "CSV" (default), "GeoJSON", "KML",
            "KMZ", "SHP", or "TFRecord".
        selectors: The list of properties to include in the output, as a list
            of strings or a comma-separated string. By default, all properties
            are included.
        maxVertices:
            Max number of uncut vertices per geometry; geometries with more
            vertices will be cut into pieces smaller than this size.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'driveFolder' and 'driveFileNamePrefix'.
    """
    if not isinstance(collection, ee.FeatureCollection):
        raise ValueError("The collection must be an ee.FeatureCollection.")

    allowed_formats = ["csv", "geojson", "kml", "kmz", "shp", "tfrecord"]
    if not (fileFormat.lower() in allowed_formats):
        raise ValueError(
            "The file type must be one of the following: {}".format(
                ", ".join(allowed_formats)
            )
        )

    if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
        return

    print(
        f"Exporting {description}... Please check the Task Manager from the JavaScript Code Editor."
    )

    task = ee.batch.Export.table.toDrive(
        collection,
        description,
        folder,
        fileNamePrefix,
        fileFormat,
        selectors,
        maxVertices,
        **kwargs,
    )
    task.start()

ee_export_vector_to_feature_view(collection, description='myExportTableTask', assetId=None, ingestionTimeParameters=None, **kwargs)

Creates a task to export a FeatureCollection to a FeatureView.

Parameters:

Name	Type	Description	Default
collection		The feature collection to be exported.	required
description		Human-readable name of the task.	'myExportTableTask'
assetId		The destination asset ID.	None
ingestionTimeParameters		The FeatureView ingestion time parameters.	None
**kwargs		Holds other keyword arguments that may have been deprecated.	{}

Source code in geemap/common.py

def ee_export_vector_to_feature_view(
    collection,
    description="myExportTableTask",
    assetId=None,
    ingestionTimeParameters=None,
    **kwargs,
):
    """Creates a task to export a FeatureCollection to a FeatureView.

    Args:
        collection: The feature collection to be exported.
        description: Human-readable name of the task.
        assetId: The destination asset ID.
        ingestionTimeParameters: The FeatureView ingestion time parameters.
        **kwargs: Holds other keyword arguments that may have been deprecated.
    """
    if not isinstance(collection, ee.FeatureCollection):
        raise ValueError("The collection must be an ee.FeatureCollection.")

    if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
        return

    print(
        f"Exporting {description}... Please check the Task Manager from the JavaScript Code Editor."
    )

    task = ee.batch.Export.table.toFeatureView(
        collection,
        description,
        assetId,
        ingestionTimeParameters,
        **kwargs,
    )
    task.start()

ee_export_video_to_cloud_storage(collection, description='myExportVideoTask', bucket=None, fileNamePrefix=None, framesPerSecond=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, maxFrames=None, **kwargs)

Creates a task to export an ImageCollection as a video to Cloud Storage.

Parameters:

Name	Type	Description	Default
collection		The image collection to be exported. The collection must only contain RGB images.	required
description		Human-readable name of the task.	'myExportVideoTask'
bucket		The name of a Cloud Storage bucket for the export.	None
fileNamePrefix		Cloud Storage object name prefix for the export. Defaults to the task's description.	None
framesPerSecond		A number between .1 and 120 describing the framerate of the exported video.	None
dimensions		The dimensions of the exported video. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the first image's region.	None
scale		The resolution in meters per pixel.	None
crs		The coordinate reference system of the exported video's projection. Defaults to SR-ORG:6627.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported video's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image collection's native CRS transform.	None
maxPixels		The maximum number of pixels per frame. Defaults to 1e8 pixels per frame. By setting this explicitly, you may raise or lower the limit.	None
maxFrames		The maximum number of frames to export. Defaults to 1000 frames. By setting this explicitly, you may raise or lower the limit.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform'.	{}

Source code in geemap/common.py

def ee_export_video_to_cloud_storage(
    collection,
    description="myExportVideoTask",
    bucket=None,
    fileNamePrefix=None,
    framesPerSecond=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    maxFrames=None,
    **kwargs,
):
    """Creates a task to export an ImageCollection as a video to Cloud Storage.

    Args:
        collection: The image collection to be exported. The collection must
            only contain RGB images.
        description: Human-readable name of the task.
        bucket: The name of a Cloud Storage bucket for the export.
        fileNamePrefix: Cloud Storage object name prefix for the export.
            Defaults to the task's description.
        framesPerSecond: A number between .1 and 120 describing the
            framerate of the exported video.
        dimensions: The dimensions of the exported video. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the first
            image's region.
        scale: The resolution in meters per pixel.
        crs: The coordinate reference system of the exported video's
            projection. Defaults to SR-ORG:6627.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported video's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image collection's native CRS transform.
        maxPixels: The maximum number of pixels per frame.
            Defaults to 1e8 pixels per frame. By setting this explicitly,
            you may raise or lower the limit.
        maxFrames: The maximum number of frames to export.
            Defaults to 1000 frames. By setting this explicitly, you may
            raise or lower the limit.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform'.

    """
    if not isinstance(collection, ee.ImageCollection):
        raise TypeError("collection must be an ee.ImageCollection")

    if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
        return

    print(
        f"Exporting {description}... Please check the Task Manager from the JavaScript Code Editor."
    )

    task = ee.batch.Export.video.toCloudStorage(
        collection,
        description,
        bucket,
        fileNamePrefix,
        framesPerSecond,
        dimensions,
        region,
        scale,
        crs,
        crsTransform,
        maxPixels,
        maxFrames,
        **kwargs,
    )
    task.start()

ee_export_video_to_drive(collection, description='myExportVideoTask', folder=None, fileNamePrefix=None, framesPerSecond=None, dimensions=None, region=None, scale=None, crs=None, crsTransform=None, maxPixels=None, maxFrames=None, **kwargs)

Creates a task to export an ImageCollection as a video to Drive.

Parameters:

Name	Type	Description	Default
collection		The image collection to be exported. The collection must only contain RGB images.	required
description		Human-readable name of the task.	'myExportVideoTask'
folder		The name of a unique folder in your Drive account to export into. Defaults to the root of the drive.	None
fileNamePrefix		The Google Drive filename for the export. Defaults to the name of the task.	None
framesPerSecond		A number between .1 and 120 describing the framerate of the exported video.	None
dimensions		The dimensions of the exported video. Takes either a single positive integer as the maximum dimension or "WIDTHxHEIGHT" where WIDTH and HEIGHT are each positive integers.	None
region		The lon,lat coordinates for a LinearRing or Polygon specifying the region to export. Can be specified as a nested lists of numbers or a serialized string. Defaults to the first image's region.	None
scale		The resolution in meters per pixel.	None
crs		The coordinate reference system of the exported video's projection. Defaults to SR-ORG:6627.	None
crsTransform		A comma-separated string of 6 numbers describing the affine transform of the coordinate reference system of the exported video's projection, in the order: xScale, xShearing, xTranslation, yShearing, yScale and yTranslation. Defaults to the image collection's native CRS transform.	None
maxPixels		The maximum number of pixels per frame. Defaults to 1e8 pixels per frame. By setting this explicitly, you may raise or lower the limit.	None
maxFrames		The maximum number of frames to export. Defaults to 1000 frames. By setting this explicitly, you may raise or lower the limit.	None
**kwargs		Holds other keyword arguments that may have been deprecated such as 'crs_transform'.	{}

Source code in geemap/common.py

def ee_export_video_to_drive(
    collection,
    description="myExportVideoTask",
    folder=None,
    fileNamePrefix=None,
    framesPerSecond=None,
    dimensions=None,
    region=None,
    scale=None,
    crs=None,
    crsTransform=None,
    maxPixels=None,
    maxFrames=None,
    **kwargs,
):
    """Creates a task to export an ImageCollection as a video to Drive.

    Args:
        collection: The image collection to be exported. The collection must
            only contain RGB images.
        description: Human-readable name of the task.
        folder: The name of a unique folder in your Drive account to
            export into. Defaults to the root of the drive.
        fileNamePrefix: The Google Drive filename for the export.
            Defaults to the name of the task.
        framesPerSecond: A number between .1 and 120 describing the
            framerate of the exported video.
        dimensions: The dimensions of the exported video. Takes either a
            single positive integer as the maximum dimension or "WIDTHxHEIGHT"
            where WIDTH and HEIGHT are each positive integers.
        region: The lon,lat coordinates for a LinearRing or Polygon
            specifying the region to export. Can be specified as a nested
            lists of numbers or a serialized string. Defaults to the first
            image's region.
        scale: The resolution in meters per pixel.
        crs: The coordinate reference system of the exported video's
            projection. Defaults to SR-ORG:6627.
        crsTransform: A comma-separated string of 6 numbers describing
            the affine transform of the coordinate reference system of the
            exported video's projection, in the order: xScale, xShearing,
            xTranslation, yShearing, yScale and yTranslation. Defaults to
            the image collection's native CRS transform.
        maxPixels: The maximum number of pixels per frame.
            Defaults to 1e8 pixels per frame. By setting this explicitly,
            you may raise or lower the limit.
        maxFrames: The maximum number of frames to export.
            Defaults to 1000 frames. By setting this explicitly, you may
            raise or lower the limit.
        **kwargs: Holds other keyword arguments that may have been deprecated
            such as 'crs_transform'.

    """
    if not isinstance(collection, ee.ImageCollection):
        raise TypeError("collection must be an ee.ImageCollection")

    if os.environ.get("USE_MKDOCS") is not None:  # skip if running GitHub CI.
        return

    print(
        f"Exporting {description}... Please check the Task Manager from the JavaScript Code Editor."
    )

    task = ee.batch.Export.video.toDrive(
        collection,
        description,
        folder,
        fileNamePrefix,
        framesPerSecond,
        dimensions,
        region,
        scale,
        crs,
        crsTransform,
        maxPixels,
        maxFrames,
        **kwargs,
    )
    task.start()

ee_function_tree(name)

Construct the tree structure based on an Earth Engine function. For example, the function "ee.Algorithms.FMask.matchClouds" will return a list ["ee.Algorithms", "ee.Algorithms.FMask", "ee.Algorithms.FMask.matchClouds"]

Parameters:

Name	Type	Description	Default
name	str	The name of the Earth Engine function	required

Returns:

Name	Type	Description
list		The list for parent functions.

Source code in geemap/common.py

def ee_function_tree(name):
    """Construct the tree structure based on an Earth Engine function. For example, the function "ee.Algorithms.FMask.matchClouds" will return a list ["ee.Algorithms", "ee.Algorithms.FMask", "ee.Algorithms.FMask.matchClouds"]

    Args:
        name (str): The name of the Earth Engine function

    Returns:
        list: The list for parent functions.
    """
    func_list = []
    try:
        items = name.split(".")
        if items[0] == "ee":
            for i in range(2, len(items) + 1):
                func_list.append(".".join(items[0:i]))
        else:
            for i in range(1, len(items) + 1):
                func_list.append(".".join(items[0:i]))

        return func_list
    except Exception as e:
        print(e)
        print("The provided function name is invalid.")

ee_initialize(token_name='EARTHENGINE_TOKEN', auth_mode=None, auth_args=None, user_agent_prefix='geemap', project=None, **kwargs)

Authenticates Earth Engine and initialize an Earth Engine session

Parameters:

Name	Type	Description	Default
token_name	str	The name of the Earth Engine token. Defaults to "EARTHENGINE_TOKEN". In Colab, you can also set a secret named "EE_PROJECT_ID" to initialize Earth Engine.	'EARTHENGINE_TOKEN'
auth_mode	str	The authentication mode, can be one of colab, notebook, localhost, or gcloud. See https://developers.google.com/earth-engine/guides/auth for more details. Defaults to None.	None
auth_args	dict	Additional authentication parameters for aa.Authenticate(). Defaults to {}.	None
user_agent_prefix	str	If set, the prefix (version-less) value used for setting the user-agent string. Defaults to "geemap".	'geemap'
project	str	The Google cloud project ID for Earth Engine. Defaults to None.	None
kwargs	dict	Additional parameters for ee.Initialize(). For example, opt_url='https://earthengine-highvolume.googleapis.com' to use the Earth Engine High-Volume platform. Defaults to {}.	{}

Source code in geemap/coreutils.py

def ee_initialize(
    token_name: str = "EARTHENGINE_TOKEN",
    auth_mode: Optional[str] = None,
    auth_args: Optional[Dict[str, Any]] = None,
    user_agent_prefix: str = "geemap",
    project: Optional[str] = None,
    **kwargs: Any,
) -> None:
    """Authenticates Earth Engine and initialize an Earth Engine session

    Args:
        token_name (str, optional): The name of the Earth Engine token.
            Defaults to "EARTHENGINE_TOKEN". In Colab, you can also set a secret
            named "EE_PROJECT_ID" to initialize Earth Engine.
        auth_mode (str, optional): The authentication mode, can be one of colab,
            notebook, localhost, or gcloud.
            See https://developers.google.com/earth-engine/guides/auth for more
            details. Defaults to None.
        auth_args (dict, optional): Additional authentication parameters for
            aa.Authenticate(). Defaults to {}.
        user_agent_prefix (str, optional): If set, the prefix (version-less)
            value used for setting the user-agent string. Defaults to "geemap".
        project (str, optional): The Google cloud project ID for Earth Engine.
            Defaults to None.
        kwargs (dict, optional): Additional parameters for ee.Initialize().
            For example, opt_url='https://earthengine-highvolume.googleapis.com'
            to use the Earth Engine High-Volume platform. Defaults to {}.
    """
    import google.oauth2.credentials
    from .__init__ import __version__

    user_agent = f"{user_agent_prefix}/{__version__}"
    ee.data.setUserAgent(user_agent)

    if ee.data._credentials is not None:
        return

    ee_token = get_env_var(token_name)
    if ee_token is not None:

        stored = json.loads(ee_token)
        credentials = google.oauth2.credentials.Credentials(
            None,
            token_uri="https://oauth2.googleapis.com/token",
            client_id=stored["client_id"],
            client_secret=stored["client_secret"],
            refresh_token=stored["refresh_token"],
            quota_project_id=stored["project"],
        )

        ee.Initialize(credentials=credentials, **kwargs)
        return

    if auth_args is None:
        auth_args = {}

    if project is None:
        kwargs["project"] = get_env_var("EE_PROJECT_ID")
    else:
        kwargs["project"] = project

    if auth_mode is None:
        if in_colab_shell() and (ee.data._credentials is None):
            ee.Authenticate()
            ee.Initialize(**kwargs)
            return
        else:
            auth_mode = "notebook"

    auth_args["auth_mode"] = auth_mode

    ee.Authenticate(**auth_args)
    ee.Initialize(**kwargs)

ee_join_table(ee_object, data, src_key, dst_key=None)

Join a table to an ee.FeatureCollection attribute table.

Parameters:

Name	Type	Description	Default
ee_object	FeatureCollection	The ee.FeatureCollection to be joined by a table.	required
data	str | DataFraem | GeoDataFrame	The table to join to the ee.FeatureCollection.	required
src_key	str	The key of ee.FeatureCollection attribute table to join.	required
dst_key	str	The key of the table to be joined to the ee.FeatureCollection. Defaults to None.	None

Returns:

Type	Description
	ee.FeatureCollection: The joined ee.FeatureCollection.

Source code in geemap/common.py

def ee_join_table(ee_object, data, src_key, dst_key=None):
    """Join a table to an ee.FeatureCollection attribute table.

    Args:
        ee_object (ee.FeatureCollection): The ee.FeatureCollection to be joined by a table.
        data (str | pd.DataFraem | gpd.GeoDataFrame): The table to join to the ee.FeatureCollection.
        src_key (str): The key of ee.FeatureCollection attribute table to join.
        dst_key (str, optional): The key of the table to be joined to the ee.FeatureCollection. Defaults to None.

    Returns:
        ee.FeatureCollection: The joined ee.FeatureCollection.
    """
    import pandas as pd

    if not isinstance(ee_object, ee.FeatureCollection):
        raise TypeError("The input ee_object must be of type ee.FeatureCollection.")

    if not isinstance(src_key, str):
        raise TypeError("The input src_key must be of type str.")

    if dst_key is None:
        dst_key = src_key

    if isinstance(data, str):
        data = github_raw_url(data)
        if data.endswith(".csv"):
            df = pd.read_csv(data)
        elif data.endswith(".geojson"):
            df = geojson_to_df(data)
        else:
            import geopandas as gpd

            gdf = gpd.read_file(data)
            df = gdf_to_df(gdf)
    elif isinstance(data, pd.DataFrame):
        if "geometry" in data.columns:
            df = data.drop(columns=["geometry"])
        elif "geom" in data.columns:
            df = data.drop(columns=["geom"])
        else:
            df = data
    else:
        raise TypeError("The input data must be of type str or pandas.DataFrame.")

    df[dst_key] = df[dst_key].astype(str)
    df.set_index(dst_key, inplace=True)
    df = df[~df.index.duplicated(keep="first")]
    table = ee.Dictionary(df.to_dict("index"))

    fc = ee_object.map(lambda f: f.set(table.get(f.get(src_key), ee.Dictionary())))
    return fc

ee_num_round(num, decimal=2)

Rounds a number to a specified number of decimal places.

Parameters:

Name	Type	Description	Default
num	Number	The number to round.	required
decimal	int	The number of decimal places to round. Defaults to 2.	2

Returns:

Type	Description
	ee.Number: The number with the specified decimal places rounded.

Source code in geemap/common.py

def ee_num_round(num, decimal=2):
    """Rounds a number to a specified number of decimal places.

    Args:
        num (ee.Number): The number to round.
        decimal (int, optional): The number of decimal places to round. Defaults to 2.

    Returns:
        ee.Number: The number with the specified decimal places rounded.
    """
    format_str = "%.{}f".format(decimal)
    return ee.Number.parse(ee.Number(num).format(format_str))

ee_search(asset_limit=100)

Search Earth Engine API and user assets. If you received a warning (IOPub message rate exceeded) in Jupyter notebook, you can relaunch Jupyter notebook using the following command: jupyter notebook --NotebookApp.iopub_msg_rate_limit=10000

Parameters:

Name	Type	Description	Default
asset_limit	int	The number of assets to display for each asset type, i.e., Image, ImageCollection, and FeatureCollection. Defaults to 100.	100

Source code in geemap/common.py

def ee_search(asset_limit=100):
    """Search Earth Engine API and user assets. If you received a warning (IOPub message rate exceeded) in Jupyter notebook, you can relaunch Jupyter notebook using the following command:
        jupyter notebook --NotebookApp.iopub_msg_rate_limit=10000

    Args:
        asset_limit (int, optional): The number of assets to display for each asset type, i.e., Image, ImageCollection, and FeatureCollection. Defaults to 100.
    """

    warnings.filterwarnings("ignore")

    class Flags:
        def __init__(
            self,
            repos=None,
            docs=None,
            assets=None,
            docs_dict=None,
            asset_dict=None,
            asset_import=None,
        ):
            self.repos = repos
            self.docs = docs
            self.assets = assets
            self.docs_dict = docs_dict
            self.asset_dict = asset_dict
            self.asset_import = asset_import

    flags = Flags()

    search_type = widgets.ToggleButtons(
        options=["Scripts", "Docs", "Assets"],
        tooltips=[
            "Search Earth Engine Scripts",
            "Search Earth Engine API",
            "Search Earth Engine Assets",
        ],
        button_style="primary",
    )
    search_type.style.button_width = "100px"

    search_box = widgets.Text(placeholder="Filter scripts...", value="Loading...")
    search_box.layout.width = "310px"

    tree_widget = widgets.Output()

    left_widget = widgets.VBox()
    right_widget = widgets.VBox()
    output_widget = widgets.Output()
    output_widget.layout.max_width = "650px"

    search_widget = widgets.HBox()
    search_widget.children = [left_widget, right_widget]
    display(search_widget)

    repo_tree, repo_output, _ = build_repo_tree()
    left_widget.children = [search_type, repo_tree]
    right_widget.children = [repo_output]

    flags.repos = repo_tree
    search_box.value = ""

    def search_type_changed(change):
        search_box.value = ""

        output_widget.outputs = ()
        tree_widget.outputs = ()
        if change["new"] == "Scripts":
            search_box.placeholder = "Filter scripts..."
            left_widget.children = [search_type, repo_tree]
            right_widget.children = [repo_output]
        elif change["new"] == "Docs":
            search_box.placeholder = "Filter methods..."
            search_box.value = "Loading..."
            left_widget.children = [search_type, search_box, tree_widget]
            right_widget.children = [output_widget]
            if flags.docs is None:
                api_dict = read_api_csv()
                ee_api_tree, tree_dict = build_api_tree(api_dict, output_widget)
                flags.docs = ee_api_tree
                flags.docs_dict = tree_dict
            else:
                ee_api_tree = flags.docs
            with tree_widget:
                tree_widget.outputs = ()
                display(ee_api_tree)
                right_widget.children = [output_widget]
            search_box.value = ""
        elif change["new"] == "Assets":
            search_box.placeholder = "Filter assets..."
            left_widget.children = [search_type, search_box, tree_widget]
            right_widget.children = [output_widget]
            search_box.value = "Loading..."
            if flags.assets is None:
                asset_tree, asset_widget, asset_dict = build_asset_tree(
                    limit=asset_limit
                )
                flags.assets = asset_tree
                flags.asset_dict = asset_dict
                flags.asset_import = asset_widget

            with tree_widget:
                tree_widget.outputs = ()
                display(flags.assets)
            right_widget.children = [flags.asset_import]
            search_box.value = ""

    search_type.observe(search_type_changed, names="value")

    def search_box_callback(text):
        if search_type.value == "Docs":
            with tree_widget:
                if text.value == "":
                    print("Loading...")
                    tree_widget.outputs = ()
                    display(flags.docs)
                else:
                    tree_widget.outputs = ()
                    print("Searching...")
                    tree_widget.outputs = ()
                    sub_tree = search_api_tree(text.value, flags.docs_dict)
                    display(sub_tree)
        elif search_type.value == "Assets":
            with tree_widget:
                if text.value == "":
                    print("Loading...")
                    tree_widget.outputs = ()
                    display(flags.assets)
                else:
                    tree_widget.outputs = ()
                    print("Searching...")
                    tree_widget.outputs = ()
                    sub_tree = search_api_tree(text.value, flags.asset_dict)
                    display(sub_tree)

    search_box.on_submit(search_box_callback)

ee_tile_layer(ee_object, vis_params={}, name='Layer untitled', shown=True, opacity=1.0)

Converts and Earth Engine layer to ipyleaflet TileLayer.

Parameters:

Name	Type	Description	Default
ee_object	Collection | Feature | Image | MapId	The object to add to the map.	required
vis_params	dict	The visualization parameters. Defaults to {}.	{}
name	str	The name of the layer. Defaults to 'Layer untitled'.	'Layer untitled'
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
opacity	float	The layer's opacity represented as a number between 0 and 1. Defaults to 1.	1.0

Source code in geemap/geemap.py

def ee_tile_layer(
    ee_object, vis_params={}, name="Layer untitled", shown=True, opacity=1.0
):
    """Converts and Earth Engine layer to ipyleaflet TileLayer.

    Args:
        ee_object (Collection|Feature|Image|MapId): The object to add to the map.
        vis_params (dict, optional): The visualization parameters. Defaults to {}.
        name (str, optional): The name of the layer. Defaults to 'Layer untitled'.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        opacity (float, optional): The layer's opacity represented as a number between 0 and 1. Defaults to 1.
    """
    return EELeafletTileLayer(ee_object, vis_params, name, shown, opacity)

ee_to_bbox(ee_object)

Get the bounding box of an Earth Engine object as a list in the format [xmin, ymin, xmax, ymax].

Parameters:

Name	Type	Description	Default
ee_object	Image | Geometry | Feature | FeatureCollection	The input Earth Engine object.	required

Returns:

Name	Type	Description
list		The bounding box of the Earth Engine object in the format [xmin, ymin, xmax, ymax].

Source code in geemap/common.py

def ee_to_bbox(ee_object):
    """Get the bounding box of an Earth Engine object as a list in the format [xmin, ymin, xmax, ymax].

    Args:
        ee_object (ee.Image | ee.Geometry | ee.Feature | ee.FeatureCollection): The input Earth Engine object.

    Returns:
        list: The bounding box of the Earth Engine object in the format [xmin, ymin, xmax, ymax].
    """
    if (
        isinstance(ee_object, ee.Image)
        or isinstance(ee_object, ee.Feature)
        or isinstance(ee_object, ee.FeatureCollection)
    ):
        geometry = ee_object.geometry()
    elif isinstance(ee_object, ee.Geometry):
        geometry = ee_object
    else:
        raise Exception(
            "The ee_object must be an ee.Image, ee.Feature, ee.FeatureCollection or ee.Geometry object."
        )

    bounds = geometry.bounds().getInfo()["coordinates"][0]
    xmin = bounds[0][0]
    ymin = bounds[0][1]
    xmax = bounds[1][0]
    ymax = bounds[2][1]
    bbox = [xmin, ymin, xmax, ymax]
    return bbox

ee_to_csv(ee_object, filename, columns=None, remove_geom=True, sort_columns=False, **kwargs)

Downloads an ee.FeatureCollection as a CSV file.

Parameters:

Name	Type	Description	Default
ee_object	object	ee.FeatureCollection	required
filename	str	The output filepath of the CSV file.	required
columns	list	A list of attributes to export. Defaults to None.	None
remove_geom	bool	Whether to remove the geometry column. Defaults to True.	True
sort_columns	bool	Whether to sort the columns alphabetically. Defaults to False.	False
kwargs		Additional arguments passed to ee_to_df().	{}

Source code in geemap/common.py

def ee_to_csv(
    ee_object,
    filename,
    columns=None,
    remove_geom=True,
    sort_columns=False,
    **kwargs,
):
    """Downloads an ee.FeatureCollection as a CSV file.

    Args:
        ee_object (object): ee.FeatureCollection
        filename (str): The output filepath of the CSV file.
        columns (list, optional): A list of attributes to export. Defaults to None.
        remove_geom (bool, optional): Whether to remove the geometry column. Defaults to True.
        sort_columns (bool, optional): Whether to sort the columns alphabetically. Defaults to False.
        kwargs: Additional arguments passed to ee_to_df().

    """
    try:
        if filename.lower().endswith(".csv"):
            df = ee_to_df(ee_object, columns, remove_geom, sort_columns, **kwargs)
            df.to_csv(filename, index=False)
        else:
            print("The filename must end with .csv")

    except Exception as e:
        print(e)

ee_to_df(ee_object, columns=None, remove_geom=True, sort_columns=False, **kwargs)

Converts an ee.FeatureCollection to pandas dataframe.

Parameters:

Name	Type	Description	Default
ee_object	FeatureCollection	ee.FeatureCollection.	required
columns	list	List of column names. Defaults to None.	None
remove_geom	bool	Whether to remove the geometry column. Defaults to True.	True
sort_columns	bool	Whether to sort the column names. Defaults to False.	False
kwargs		Additional arguments passed to ee.data.computeFeature.	{}

Raises:

Type	Description
TypeError	ee_object must be an ee.FeatureCollection

Returns:

Type	Description
	pd.DataFrame: pandas DataFrame

Source code in geemap/common.py

def ee_to_df(
    ee_object,
    columns=None,
    remove_geom=True,
    sort_columns=False,
    **kwargs,
):
    """Converts an ee.FeatureCollection to pandas dataframe.

    Args:
        ee_object (ee.FeatureCollection): ee.FeatureCollection.
        columns (list): List of column names. Defaults to None.
        remove_geom (bool): Whether to remove the geometry column. Defaults to True.
        sort_columns (bool): Whether to sort the column names. Defaults to False.
        kwargs: Additional arguments passed to ee.data.computeFeature.

    Raises:
        TypeError: ee_object must be an ee.FeatureCollection

    Returns:
        pd.DataFrame: pandas DataFrame
    """
    if isinstance(ee_object, ee.Feature):
        ee_object = ee.FeatureCollection([ee_object])

    if not isinstance(ee_object, ee.FeatureCollection):
        raise TypeError("ee_object must be an ee.FeatureCollection")

    try:
        if remove_geom:
            data = ee_object.map(
                lambda f: ee.Feature(None, f.toDictionary(f.propertyNames().sort()))
            )
        else:
            data = ee_object

        kwargs["expression"] = data
        kwargs["fileFormat"] = "PANDAS_DATAFRAME"

        df = ee.data.computeFeatures(kwargs)

        if isinstance(columns, list):
            df = df[columns]

        if remove_geom and ("geo" in df.columns):
            df = df.drop(columns=["geo"], axis=1)

        if sort_columns:
            df = df.reindex(sorted(df.columns), axis=1)

        return df
    except Exception as e:
        raise Exception(e)

ee_to_gdf(ee_object, columns=None, sort_columns=False, **kwargs)

Converts an ee.FeatureCollection to GeoPandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
ee_object	FeatureCollection	ee.FeatureCollection.	required
columns	list	List of column names. Defaults to None.	None
sort_columns	bool	Whether to sort the column names. Defaults to False.	False
kwargs		Additional arguments passed to ee.data.computeFeature.	{}

Raises:

Type	Description
TypeError	ee_object must be an ee.FeatureCollection

Returns:

Type	Description
	gpd.GeoDataFrame: GeoPandas GeoDataFrame

Source code in geemap/common.py

def ee_to_gdf(
    ee_object,
    columns=None,
    sort_columns=False,
    **kwargs,
):
    """Converts an ee.FeatureCollection to GeoPandas GeoDataFrame.

    Args:
        ee_object (ee.FeatureCollection): ee.FeatureCollection.
        columns (list): List of column names. Defaults to None.
        sort_columns (bool): Whether to sort the column names. Defaults to False.
        kwargs: Additional arguments passed to ee.data.computeFeature.

    Raises:
        TypeError: ee_object must be an ee.FeatureCollection

    Returns:
        gpd.GeoDataFrame: GeoPandas GeoDataFrame
    """
    if isinstance(ee_object, ee.Feature):
        ee_object = ee.FeatureCollection([ee_object])

    if not isinstance(ee_object, ee.FeatureCollection):
        raise TypeError("ee_object must be an ee.FeatureCollection")

    try:
        kwargs["expression"] = ee_object
        kwargs["fileFormat"] = "GEOPANDAS_GEODATAFRAME"

        crs = ee_object.first().geometry().projection().crs().getInfo()
        gdf = ee.data.computeFeatures(kwargs)

        if isinstance(columns, list):
            gdf = gdf[columns]

        if sort_columns:
            gdf = gdf.reindex(sorted(gdf.columns), axis=1)

        gdf.crs = crs
        return gdf
    except Exception as e:
        raise Exception(e)

ee_to_geojson(ee_object, filename=None, indent=2, **kwargs)

Converts Earth Engine object to geojson.

Parameters:

Name	Type	Description	Default
ee_object	object	An Earth Engine object.	required
filename	str	The file path to save the geojson. Defaults to None.	None

Returns:

Name	Type	Description
object		GeoJSON object.

Source code in geemap/common.py

def ee_to_geojson(ee_object, filename=None, indent=2, **kwargs):
    """Converts Earth Engine object to geojson.

    Args:
        ee_object (object): An Earth Engine object.
        filename (str, optional): The file path to save the geojson. Defaults to None.

    Returns:
        object: GeoJSON object.
    """

    try:
        if (
            isinstance(ee_object, ee.Geometry)
            or isinstance(ee_object, ee.Feature)
            or isinstance(ee_object, ee.FeatureCollection)
        ):
            json_object = ee_object.getInfo()
            if filename is not None:
                filename = os.path.abspath(filename)
                if not os.path.exists(os.path.dirname(filename)):
                    os.makedirs(os.path.dirname(filename))
                with open(filename, "w") as f:
                    f.write(json.dumps(json_object, indent=indent, **kwargs) + "\n")
            else:
                return json_object
        else:
            print("Could not convert the Earth Engine object to geojson")
    except Exception as e:
        raise Exception(e)

ee_to_geotiff(ee_object, output, bbox=None, vis_params={}, zoom=None, resolution=None, crs='EPSG:3857', to_cog=False, quiet=False, **kwargs)

Downloads an Earth Engine object as GeoTIFF.

Parameters:

Name	Type	Description	Default
ee_object	Image | FeatureCollection	The Earth Engine object to download.	required
output	str	The output path for the GeoTIFF.	required
bbox	str	The bounding box in the format [xmin, ymin, xmax, ymax]. Defaults to None, which is the bounding box of the Earth Engine object.	None
vis_params	dict	Visualization parameters. Defaults to {}.	{}
zoom	int	The zoom level to download the image at. Defaults to None.	None
resolution	float	The resolution in meters to download the image at. Defaults to None.	None
crs	str	The CRS of the output image. Defaults to "EPSG:3857".	'EPSG:3857'
to_cog	bool	Whether to convert the image to Cloud Optimized GeoTIFF. Defaults to False.	False
quiet	bool	Whether to hide the download progress bar. Defaults to False.	False

Source code in geemap/common.py

def ee_to_geotiff(
    ee_object,
    output,
    bbox=None,
    vis_params={},
    zoom=None,
    resolution=None,
    crs="EPSG:3857",
    to_cog=False,
    quiet=False,
    **kwargs,
):
    """Downloads an Earth Engine object as GeoTIFF.

    Args:
        ee_object (ee.Image | ee.FeatureCollection): The Earth Engine object to download.
        output (str): The output path for the GeoTIFF.
        bbox (str, optional): The bounding box in the format [xmin, ymin, xmax, ymax]. Defaults to None,
            which is the bounding box of the Earth Engine object.
        vis_params (dict, optional): Visualization parameters. Defaults to {}.
        zoom (int, optional): The zoom level to download the image at. Defaults to None.
        resolution (float, optional): The resolution in meters to download the image at. Defaults to None.
        crs (str, optional): The CRS of the output image. Defaults to "EPSG:3857".
        to_cog (bool, optional): Whether to convert the image to Cloud Optimized GeoTIFF. Defaults to False.
        quiet (bool, optional): Whether to hide the download progress bar. Defaults to False.

    """

    from box import Box

    image = None

    if (
        not isinstance(ee_object, ee.Image)
        and not isinstance(ee_object, ee.ImageCollection)
        and not isinstance(ee_object, ee.FeatureCollection)
        and not isinstance(ee_object, ee.Feature)
        and not isinstance(ee_object, ee.Geometry)
    ):
        err_str = "\n\nThe image argument in 'addLayer' function must be an instance of one of ee.Image, ee.Geometry, ee.Feature or ee.FeatureCollection."
        raise AttributeError(err_str)

    if (
        isinstance(ee_object, ee.geometry.Geometry)
        or isinstance(ee_object, ee.feature.Feature)
        or isinstance(ee_object, ee.featurecollection.FeatureCollection)
    ):
        features = ee.FeatureCollection(ee_object)

        width = 2

        if "width" in vis_params:
            width = vis_params["width"]

        color = "000000"

        if "color" in vis_params:
            color = vis_params["color"]

        image_fill = features.style(**{"fillColor": color}).updateMask(
            ee.Image.constant(0.5)
        )
        image_outline = features.style(
            **{"color": color, "fillColor": "00000000", "width": width}
        )

        image = image_fill.blend(image_outline)
    elif isinstance(ee_object, ee.image.Image):
        image = ee_object
    elif isinstance(ee_object, ee.imagecollection.ImageCollection):
        image = ee_object.mosaic()

    if "palette" in vis_params:
        if isinstance(vis_params["palette"], Box):
            try:
                vis_params["palette"] = vis_params["palette"]["default"]
            except Exception as e:
                print("The provided palette is invalid.")
                raise Exception(e)
        elif isinstance(vis_params["palette"], str):
            vis_params["palette"] = check_cmap(vis_params["palette"])
        elif not isinstance(vis_params["palette"], list):
            raise ValueError(
                "The palette must be a list of colors or a string or a Box object."
            )

    map_id_dict = ee.Image(image).getMapId(vis_params)
    url = map_id_dict["tile_fetcher"].url_format

    if bbox is None:
        bbox = ee_to_bbox(image)

    if zoom is None and resolution is None:
        raise ValueError("Either zoom level or resolution must be specified.")

    tms_to_geotiff(output, bbox, zoom, resolution, url, crs, to_cog, quiet, **kwargs)

ee_to_numpy(ee_object, region=None, scale=None, bands=None, **kwargs)

Extracts a rectangular region of pixels from an image into a numpy array.

Parameters:

Name	Type	Description	Default
ee_object	Image	The image to sample.	required
region	Geometry	The region to sample. Defaults to None.	None
bands	list	The list of band names to extract. Defaults to None.	None
scale	int	A nominal scale in meters of the projection to sample in. Defaults to None.	None

Returns:

Type	Description
	np.ndarray: A 3D numpy array in the format of [row, column, band].

Source code in geemap/common.py

def ee_to_numpy(ee_object, region=None, scale=None, bands=None, **kwargs):
    """Extracts a rectangular region of pixels from an image into a numpy array.

    Args:
        ee_object (ee.Image): The image to sample.
        region (ee.Geometry, optional): The region to sample. Defaults to None.
        bands (list, optional): The list of band names to extract. Defaults to None.
        scale (int, optional): A nominal scale in meters of the projection to sample in. Defaults to None.

    Returns:
        np.ndarray: A 3D numpy array in the format of [row, column, band].
    """
    import numpy as np

    if (region is not None) or (scale is not None):
        ee_object = ee_object.clipToBoundsAndScale(geometry=region, scale=scale)

    kwargs["expression"] = ee_object
    kwargs["fileFormat"] = "NUMPY_NDARRAY"
    if bands is not None:
        kwargs["bandIds"] = bands

    try:
        struct_array = ee.data.computePixels(kwargs)
        array = np.dstack(([struct_array[band] for band in struct_array.dtype.names]))
        return array
    except Exception as e:
        raise Exception(e)

ee_to_shp(ee_object, filename, columns=None, sort_columns=False, **kwargs)

Downloads an ee.FeatureCollection as a shapefile.

Parameters:

Name	Type	Description	Default
ee_object	object	ee.FeatureCollection	required
filename	str	The output filepath of the shapefile.	required
columns	list	A list of attributes to export. Defaults to None.	None
sort_columns	bool	Whether to sort the columns alphabetically. Defaults to False.	False
kwargs		Additional arguments passed to ee_to_gdf().	{}

Source code in geemap/common.py

def ee_to_shp(
    ee_object,
    filename,
    columns=None,
    sort_columns=False,
    **kwargs,
):
    """Downloads an ee.FeatureCollection as a shapefile.

    Args:
        ee_object (object): ee.FeatureCollection
        filename (str): The output filepath of the shapefile.
        columns (list, optional): A list of attributes to export. Defaults to None.
        sort_columns (bool, optional): Whether to sort the columns alphabetically. Defaults to False.
        kwargs: Additional arguments passed to ee_to_gdf().

    """
    try:
        if filename.lower().endswith(".shp"):
            gdf = ee_to_gdf(ee_object, columns, sort_columns, **kwargs)
            gdf.to_file(filename)
        else:
            print("The filename must end with .shp")

    except Exception as e:
        print(e)

ee_to_xarray(dataset, drop_variables=None, io_chunks=None, n_images=-1, mask_and_scale=True, decode_times=True, decode_timedelta=None, use_cftime=None, concat_characters=True, decode_coords=True, crs=None, scale=None, projection=None, geometry=None, primary_dim_name=None, primary_dim_property=None, ee_mask_value=None, ee_initialize=True, **kwargs)

Open an Earth Engine ImageCollection as an Xarray Dataset. This function is a wrapper for xee. EarthEngineBackendEntrypoint.open_dataset(). See https://github.com/google/Xee/blob/main/xee/ext.py#L886

Parameters:

Name	Type	Description	Default
dataset		An asset ID for an ImageCollection, or an ee.ImageCollection object.	required
drop_variables	optional	Variables or bands to drop before opening.	None
io_chunks	optional	Specifies the chunking strategy for loading data from EE. By default, this automatically calculates optional chunks based on the request_byte_limit.	None
n_images	optional	The max number of EE images in the collection to open. Useful when there are a large number of images in the collection since calculating collection size can be slow. -1 indicates that all images should be included.	-1
mask_and_scale	optional	Lazily scale (using scale_factor and add_offset) and mask (using _FillValue).	True
decode_times	optional	Decode cf times (e.g., integers since "hours since 2000-01-01") to np.datetime64.	True
decode_timedelta	optional	If True, decode variables and coordinates with time units in {"days", "hours", "minutes", "seconds", "milliseconds", "microseconds"} into timedelta objects. If False, leave them encoded as numbers. If None (default), assume the same value of decode_time.	None
use_cftime	optional	Only relevant if encoded dates come from a standard calendar (e.g. "gregorian", "proleptic_gregorian", "standard", or not specified). If None (default), attempt to decode times to np.datetime64[ns] objects; if this is not possible, decode times to cftime.datetime objects. If True, always decode times to cftime.datetime objects, regardless of whether or not they can be represented using np.datetime64[ns] objects. If False, always decode times to np.datetime64[ns] objects; if this is not possible raise an error.	None
concat_characters	optional	Should character arrays be concatenated to strings, for example: ["h", "e", "l", "l", "o"] -> "hello"	True
decode_coords	optional	bool or {"coordinates", "all"}, Controls which variables are set as coordinate variables: - "coordinates" or True: Set variables referred to in the 'coordinates' attribute of the datasets or individual variables as coordinate variables. - "all": Set variables referred to in 'grid_mapping', 'bounds' and other attributes as coordinate variables.	True
crs	optional	The coordinate reference system (a CRS code or WKT string). This defines the frame of reference to coalesce all variables upon opening. By default, data is opened with `EPSG:4326'.	None
scale	optional	The scale in the crs or projection's units of measure -- either meters or degrees. This defines the scale that all data is represented in upon opening. By default, the scale is 1° when the CRS is in degrees or 10,000 when in meters.	None
projection	optional	Specify an ee.Projection object to define the scale and crs (or other coordinate reference system) with which to coalesce all variables upon opening. By default, the scale and reference system is set by the the crs and scale arguments.	None
geometry	optional	Specify an ee.Geometry to define the regional bounds when opening the data. When not set, the bounds are defined by the CRS's 'area_of_use` boundaries. If those aren't present, the bounds are derived from the geometry of the first image of the collection.	None
primary_dim_name	optional	Override the name of the primary dimension of the output Dataset. By default, the name is 'time'.	None
primary_dim_property	optional	Override the ee.Image property for which to derive the values of the primary dimension. By default, this is 'system:time_start'.	None
ee_mask_value	optional	Value to mask to EE nodata values. By default, this is 'np.iinfo(np.int32).max' i.e. 2147483647.	None
request_byte_limit		the max allowed bytes to request at a time from Earth Engine. By default, it is 48MBs.	required
ee_initialize	optional	Whether to initialize ee with the high-volume endpoint. Defaults to True.	True

Returns:

Type	Description
	An xarray.Dataset that streams in remote data from Earth Engine.

Source code in geemap/common.py

def ee_to_xarray(
    dataset,
    drop_variables=None,
    io_chunks=None,
    n_images=-1,
    mask_and_scale=True,
    decode_times=True,
    decode_timedelta=None,
    use_cftime=None,
    concat_characters=True,
    decode_coords=True,
    crs=None,
    scale=None,
    projection=None,
    geometry=None,
    primary_dim_name=None,
    primary_dim_property=None,
    ee_mask_value=None,
    ee_initialize=True,
    **kwargs,
):
    """Open an Earth Engine ImageCollection as an Xarray Dataset. This function is a wrapper for
        xee. EarthEngineBackendEntrypoint.open_dataset().
        See https://github.com/google/Xee/blob/main/xee/ext.py#L886

    Args:
        dataset: An asset ID for an ImageCollection, or an
            ee.ImageCollection object.
        drop_variables (optional): Variables or bands to drop before opening.
        io_chunks (optional): Specifies the chunking strategy for loading data
            from EE. By default, this automatically calculates optional chunks based
            on the `request_byte_limit`.
        n_images (optional): The max number of EE images in the collection to
            open. Useful when there are a large number of images in the collection
            since calculating collection size can be slow. -1 indicates that all
            images should be included.
        mask_and_scale (optional): Lazily scale (using scale_factor and
            add_offset) and mask (using _FillValue).
        decode_times (optional): Decode cf times (e.g., integers since "hours
            since 2000-01-01") to np.datetime64.
        decode_timedelta (optional): If True, decode variables and coordinates
            with time units in {"days", "hours", "minutes", "seconds",
            "milliseconds", "microseconds"} into timedelta objects. If False, leave
            them encoded as numbers. If None (default), assume the same value of
            decode_time.
        use_cftime (optional): Only relevant if encoded dates come from a standard
            calendar (e.g. "gregorian", "proleptic_gregorian", "standard", or not
            specified).  If None (default), attempt to decode times to
            ``np.datetime64[ns]`` objects; if this is not possible, decode times to
            ``cftime.datetime`` objects. If True, always decode times to
            ``cftime.datetime`` objects, regardless of whether or not they can be
            represented using ``np.datetime64[ns]`` objects.  If False, always
            decode times to ``np.datetime64[ns]`` objects; if this is not possible
            raise an error.
        concat_characters (optional): Should character arrays be concatenated to
            strings, for example: ["h", "e", "l", "l", "o"] -> "hello"
        decode_coords (optional): bool or {"coordinates", "all"}, Controls which
            variables are set as coordinate variables: - "coordinates" or True: Set
            variables referred to in the ``'coordinates'`` attribute of the datasets
            or individual variables as coordinate variables. - "all": Set variables
            referred to in  ``'grid_mapping'``, ``'bounds'`` and other attributes as
            coordinate variables.
        crs (optional): The coordinate reference system (a CRS code or WKT
            string). This defines the frame of reference to coalesce all variables
            upon opening. By default, data is opened with `EPSG:4326'.
        scale (optional): The scale in the `crs` or `projection`'s units of
            measure -- either meters or degrees. This defines the scale that all
            data is represented in upon opening. By default, the scale is 1° when
            the CRS is in degrees or 10,000 when in meters.
        projection (optional): Specify an `ee.Projection` object to define the
            `scale` and `crs` (or other coordinate reference system) with which to
            coalesce all variables upon opening. By default, the scale and reference
            system is set by the the `crs` and `scale` arguments.
        geometry (optional): Specify an `ee.Geometry` to define the regional
            bounds when opening the data. When not set, the bounds are defined by
            the CRS's 'area_of_use` boundaries. If those aren't present, the bounds
            are derived from the geometry of the first image of the collection.
        primary_dim_name (optional): Override the name of the primary dimension of
            the output Dataset. By default, the name is 'time'.
        primary_dim_property (optional): Override the `ee.Image` property for
            which to derive the values of the primary dimension. By default, this is
            'system:time_start'.
        ee_mask_value (optional): Value to mask to EE nodata values. By default,
            this is 'np.iinfo(np.int32).max' i.e. 2147483647.
        request_byte_limit: the max allowed bytes to request at a time from Earth
            Engine. By default, it is 48MBs.
        ee_initialize (optional): Whether to initialize ee with the high-volume endpoint. Defaults to True.

    Returns:
      An xarray.Dataset that streams in remote data from Earth Engine.
    """
    try:
        import xee
    except ImportError:
        install_package("xee")
        import xee

    import xarray as xr

    kwargs["drop_variables"] = drop_variables
    kwargs["io_chunks"] = io_chunks
    kwargs["n_images"] = n_images
    kwargs["mask_and_scale"] = mask_and_scale
    kwargs["decode_times"] = decode_times
    kwargs["decode_timedelta"] = decode_timedelta
    kwargs["use_cftime"] = use_cftime
    kwargs["concat_characters"] = concat_characters
    kwargs["decode_coords"] = decode_coords
    kwargs["crs"] = crs
    kwargs["scale"] = scale
    kwargs["projection"] = projection
    kwargs["geometry"] = geometry
    kwargs["primary_dim_name"] = primary_dim_name
    kwargs["primary_dim_property"] = primary_dim_property
    kwargs["ee_mask_value"] = ee_mask_value
    kwargs["engine"] = "ee"

    if ee_initialize:
        opt_url = "https://earthengine-highvolume.googleapis.com"
        ee.Initialize(opt_url=opt_url)

    if isinstance(dataset, str):
        if not dataset.startswith("ee://"):
            dataset = "ee://" + dataset
    elif isinstance(dataset, ee.Image):
        dataset = ee.ImageCollection(dataset)
    elif isinstance(dataset, ee.ImageCollection):
        pass
    elif isinstance(dataset, list):
        items = []
        for item in dataset:
            if isinstance(item, str) and not item.startswith("ee://"):
                item = "ee://" + item
            items.append(item)
        dataset = items
    else:
        raise ValueError(
            "The dataset must be an ee.Image, ee.ImageCollection, or a list of ee.Image."
        )

    if isinstance(dataset, list):
        ds = xr.open_mfdataset(dataset, **kwargs)
    else:
        ds = xr.open_dataset(dataset, **kwargs)

    return ds

ee_user_id()

Gets Earth Engine account user id.

Returns:

Name	Type	Description
str		A string containing the user id.

Source code in geemap/common.py

def ee_user_id():
    """Gets Earth Engine account user id.

    Returns:
        str: A string containing the user id.
    """
    # ee_initialize()
    roots = ee.data.getAssetRoots()
    if len(roots) == 0:
        return None
    else:
        root = ee.data.getAssetRoots()[0]
        user_id = root["id"].replace("projects/earthengine-legacy/assets/", "")
        return user_id

ee_vector_style(collection, column, labels=None, color='black', pointSize=3, pointShape='circle', width=2, fillColor=None, lineType='solid', neighborhood=5, return_fc=False)

Create a vector style for a feature collection.

Parameters:

Name	Type	Description	Default
collection	FeatureCollection	The input feature collection.	required
column	str	The name of the column to use for styling.	required
labels	list	A list of labels to use for styling. Defaults to None.	None
color	str | list	A default color (CSS 3.0 color value e.g. 'FF0000' or 'red') to use for drawing the features. Supports opacity (e.g.: 'FF000088' for 50% transparent red). Defaults to "black".	'black'
pointSize	int | list	The default size in pixels of the point markers. Defaults to 3.	3
pointShape	str | list	The default shape of the marker to draw at each point location. One of: circle, square, diamond, cross, plus, pentagram, hexagram, triangle, triangle_up, triangle_down, triangle_left, triangle_right, pentagon, hexagon, star5, star6. This argument also supports the following Matlab marker abbreviations: o, s, d, x, +, p, h, ^, v, <, >. Defaults to "circle".	'circle'
width	int | list	The default line width for lines and outlines for polygons and point shapes. Defaults to 2.	2
fillColor	str | list	The color for filling polygons and point shapes. Defaults to 'color' at 0.66 opacity. Defaults to None.	None
lineType	str | list	The default line style for lines and outlines of polygons and point shapes. Defaults to 'solid'. One of: solid, dotted, dashed. Defaults to "solid".	'solid'
neighborhood	int	If styleProperty is used and any feature has a pointSize or width larger than the defaults, tiling artifacts can occur. Specifies the maximum neighborhood (pointSize + width) needed for any feature. Defaults to 5.	5
return_fc	bool	If True, return an ee.FeatureCollection with a style property. Otherwise, return a styled ee.Image. Defaults to False.	False

Returns:

Type	Description
	ee.FeatureCollection | ee.Image: The styled Earth Engine FeatureCollection or Image.

Source code in geemap/common.py

def ee_vector_style(
    collection,
    column,
    labels=None,
    color="black",
    pointSize=3,
    pointShape="circle",
    width=2,
    fillColor=None,
    lineType="solid",
    neighborhood=5,
    return_fc=False,
):
    """Create a vector style for a feature collection.

    Args:
        collection (ee.FeatureCollection): The input feature collection.
        column (str): The name of the column to use for styling.
        labels (list, optional): A list of labels to use for styling. Defaults to None.
        color (str | list, optional): A default color (CSS 3.0 color value e.g. 'FF0000' or 'red') to use for drawing the features. Supports opacity (e.g.: 'FF000088' for 50% transparent red). Defaults to "black".
        pointSize (int | list, optional): The default size in pixels of the point markers. Defaults to 3.
        pointShape (str | list, optional): The default shape of the marker to draw at each point location. One of: circle, square, diamond, cross, plus, pentagram, hexagram, triangle, triangle_up, triangle_down, triangle_left, triangle_right, pentagon, hexagon, star5, star6. This argument also supports the following Matlab marker abbreviations: o, s, d, x, +, p, h, ^, v, <, >. Defaults to "circle".
        width (int | list, optional): The default line width for lines and outlines for polygons and point shapes. Defaults to 2.
        fillColor (str | list, optional): The color for filling polygons and point shapes. Defaults to 'color' at 0.66 opacity. Defaults to None.
        lineType (str | list, optional): The default line style for lines and outlines of polygons and point shapes. Defaults to 'solid'. One of: solid, dotted, dashed. Defaults to "solid".
        neighborhood (int, optional): If styleProperty is used and any feature has a pointSize or width larger than the defaults, tiling artifacts can occur. Specifies the maximum neighborhood (pointSize + width) needed for any feature. Defaults to 5.
        return_fc (bool, optional): If True, return an ee.FeatureCollection with a style property. Otherwise, return a styled ee.Image. Defaults to False.

    Returns:
        ee.FeatureCollection | ee.Image: The styled Earth Engine FeatureCollection or Image.
    """
    if not isinstance(collection, ee.FeatureCollection):
        raise ValueError("collection must be an ee.FeatureCollection.")

    if not isinstance(column, str):
        raise ValueError("column must be a string.")

    prop_names = ee.Feature(collection.first()).propertyNames().getInfo()
    if column not in prop_names:
        raise ValueError(
            f"{column} is not a property name of the collection. It must be one of {','.join(prop_names)}."
        )

    if labels is None:
        labels = collection.aggregate_array(column).distinct().sort().getInfo()
    elif isinstance(labels, list):
        collection = collection.filter(ee.Filter.inList(column, labels))
    elif not isinstance(labels, list):
        raise ValueError("labels must be a list.")

    size = len(labels)
    if isinstance(color, str):
        color = [color] * size
    elif size != len(color):
        raise ValueError("labels and color must be the same length.")
    elif not isinstance(color, list):
        raise ValueError("color must be a string or a list.")

    if isinstance(pointSize, int):
        pointSize = [pointSize] * size
    elif not isinstance(pointSize, list):
        raise ValueError("pointSize must be an integer or a list.")

    if isinstance(pointShape, str):
        pointShape = [pointShape] * size
    elif not isinstance(pointShape, list):
        raise ValueError("pointShape must be a string or a list.")

    if isinstance(width, int):
        width = [width] * size
    elif not isinstance(width, list):
        raise ValueError("width must be an integer or a list.")

    if fillColor is None:
        fillColor = color
    elif isinstance(fillColor, str):
        fillColor = [fillColor] * size
    elif not isinstance(fillColor, list):
        raise ValueError("fillColor must be a list.")

    if not isinstance(neighborhood, int):
        raise ValueError("neighborhood must be an integer.")

    if isinstance(lineType, str):
        lineType = [lineType] * size
    elif not isinstance(lineType, list):
        raise ValueError("lineType must be a string or list.")

    style_dict = {}

    for i, label in enumerate(labels):
        style_dict[label] = {
            "color": color[i],
            "pointSize": pointSize[i],
            "pointShape": pointShape[i],
            "width": width[i],
            "fillColor": fillColor[i],
            "lineType": lineType[i],
        }

    style = ee.Dictionary(style_dict)

    result = collection.map(lambda f: f.set("style", style.get(f.get(column))))

    if return_fc:
        return result
    else:
        return result.style(**{"styleProperty": "style", "neighborhood": neighborhood})

execute_notebook(in_file)

Executes a Jupyter notebook and save output cells

Parameters:

Name	Type	Description	Default
in_file	str	Input Jupyter notebook.	required

Source code in geemap/conversion.py

def execute_notebook(in_file):
    """Executes a Jupyter notebook and save output cells

    Args:
        in_file (str): Input Jupyter notebook.
    """
    # command = 'jupyter nbconvert --to notebook --execute ' + in_file + ' --inplace'
    command = 'jupyter nbconvert --to notebook --execute "{}" --inplace'.format(in_file)
    print(os.popen(command).read().rstrip())

execute_notebook_dir(in_dir)

Executes all Jupyter notebooks in the given directory recursively and save output cells.

Parameters:

Name	Type	Description	Default
in_dir	str	Input folder containing notebooks.	required

Source code in geemap/conversion.py

def execute_notebook_dir(in_dir):
    """Executes all Jupyter notebooks in the given directory recursively and save output cells.

    Args:
        in_dir (str): Input folder containing notebooks.
    """
    print("Executing Earth Engine Jupyter notebooks ...\n")

    in_dir = os.path.abspath(in_dir)
    files = list(Path(in_dir).rglob("*.ipynb"))
    count = len(files)
    if files is not None:
        for index, file in enumerate(files):
            in_file = str(file)
            print(f"Processing {index + 1}/{count}: {file} ...")
            execute_notebook(in_file)

explode(coords)

Explode a GeoJSON geometry's coordinates object and yield coordinate tuples. As long as the input is conforming, the type of the geometry doesn't matter. From Fiona 1.4.8

Parameters:

Name	Type	Description	Default
coords	list	A list of coordinates.	required

Yields:

Type	Description

Source code in geemap/common.py

def explode(coords):
    """Explode a GeoJSON geometry's coordinates object and yield
    coordinate tuples. As long as the input is conforming, the type of
    the geometry doesn't matter.  From Fiona 1.4.8

    Args:
        coords (list): A list of coordinates.

    Yields:
        [type]: [description]
    """

    for e in coords:
        if isinstance(e, (float, int)):
            yield coords
            break
        else:
            for f in explode(e):
                yield f

extract_pixel_values(ee_object, region, scale=None, projection=None, tileScale=1, getInfo=False)

Samples the pixels of an image, returning them as a ee.Dictionary.

Parameters:

Name	Type	Description	Default
ee_object	Image | ImageCollection	The ee.Image or ee.ImageCollection to sample.	required
region	Geometry	The region to sample from. If unspecified, uses the image's whole footprint.	required
scale	float	A nominal scale in meters of the projection to sample in. Defaults to None.	None
projection	str	The projection in which to sample. If unspecified, the projection of the image's first band is used. If specified in addition to scale, rescaled to the specified scale. Defaults to None.	None
tileScale	int	A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.	1
getInfo	bool	Whether to use getInfo with the results, i.e., returning the values a list. Default to False.	False

Raises:

Type	Description
TypeError	The image must be an instance of ee.Image.
TypeError	Region must be an instance of ee.Geometry.

Returns:

Type	Description
	ee.Dictionary: The dictionary containing band names and pixel values.

Source code in geemap/common.py

def extract_pixel_values(
    ee_object, region, scale=None, projection=None, tileScale=1, getInfo=False
):
    """Samples the pixels of an image, returning them as a ee.Dictionary.

    Args:
        ee_object (ee.Image | ee.ImageCollection): The ee.Image or ee.ImageCollection to sample.
        region (ee.Geometry): The region to sample from. If unspecified, uses the image's whole footprint.
        scale (float, optional): A nominal scale in meters of the projection to sample in. Defaults to None.
        projection (str, optional): The projection in which to sample. If unspecified, the projection of the image's first band is used. If specified in addition to scale, rescaled to the specified scale. Defaults to None.
        tileScale (int, optional): A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.
        getInfo (bool, optional): Whether to use getInfo with the results, i.e., returning the values a list. Default to False.

    Raises:
        TypeError: The image must be an instance of ee.Image.
        TypeError: Region must be an instance of ee.Geometry.

    Returns:
        ee.Dictionary: The dictionary containing band names and pixel values.
    """
    if isinstance(ee_object, ee.ImageCollection):
        ee_object = ee_object.toBands()

    if not isinstance(ee_object, ee.Image):
        raise TypeError("The image must be an instance of ee.Image.")

    if not isinstance(region, ee.Geometry):
        raise TypeError("Region must be an instance of ee.Geometry.")

    dict_values = (
        ee_object.sample(region, scale, projection, tileScale=tileScale)
        .first()
        .toDictionary()
    )

    if getInfo:
        band_names = ee_object.bandNames().getInfo()
        values_tmp = dict_values.getInfo()
        values = [values_tmp[i] for i in band_names]
        return dict(zip(band_names, values))
    else:
        return dict_values

extract_timeseries_to_point(lat, lon, image_collection, start_date, end_date, band_names, scale=None, crs=None, crsTransform=None, out_df=None)

Extracts pixel time series from an ee.ImageCollection at a point.

Parameters:

Name	Type	Description	Default
lat	float	Latitude of the point.	required
lon	float	Longitude of the point.	required
image_collection	ImageCollection	Image collection to sample.	required
start_date	str	Start date (e.g., '2020-01-01').	required
end_date	str	End date (e.g., '2020-12-31').	required
band_names	list	List of bands to extract.	required
scale	float	Sampling scale in meters.	None
crs	str	Projection CRS. Defaults to image CRS.	None
crsTransform	list	CRS transform matrix (3x2 row-major). Overrides scale.	None
out_df	str	File path to save CSV. If None, returns a DataFrame.	None

Returns:

Type	Description
	pd.DataFrame or None: Time series data if not exporting to CSV.

Source code in geemap/common.py

def extract_timeseries_to_point(
    lat,
    lon,
    image_collection,
    start_date,
    end_date,
    band_names,
    scale=None,
    crs=None,
    crsTransform=None,
    out_df=None,
):
    """
    Extracts pixel time series from an ee.ImageCollection at a point.

    Args:
        lat (float): Latitude of the point.
        lon (float): Longitude of the point.
        image_collection (ee.ImageCollection): Image collection to sample.
        start_date (str): Start date (e.g., '2020-01-01').
        end_date (str): End date (e.g., '2020-12-31').
        band_names (list): List of bands to extract.
        scale (float): Sampling scale in meters.
        crs (str, optional): Projection CRS. Defaults to image CRS.
        crsTransform (list, optional): CRS transform matrix (3x2 row-major). Overrides scale.
        out_df (str, optional): File path to save CSV. If None, returns a DataFrame.

    Returns:
        pd.DataFrame or None: Time series data if not exporting to CSV.
    """

    import pandas as pd
    from datetime import datetime

    if not isinstance(image_collection, ee.ImageCollection):
        raise ValueError("image_collection must be an instance of ee.ImageCollection.")

    property_names = image_collection.first().propertyNames().getInfo()
    if "system:time_start" not in property_names:
        raise ValueError("The image collection lacks the 'system:time_start' property.")

    point = ee.Geometry.Point([lon, lat])

    try:
        image_collection = (
            image_collection.filterBounds(point)
            .filterDate(start_date, end_date)
            .select(band_names)
        )
    except Exception as e:
        raise RuntimeError(f"Error filtering image collection: {e}")

    try:
        result = image_collection.getRegion(
            geometry=point, scale=scale, crs=crs, crsTransform=crsTransform
        ).getInfo()

        result_df = pd.DataFrame(result[1:], columns=result[0])

        if result_df.empty:
            raise ValueError(
                "Extraction returned an empty DataFrame. Check your point, date range, or selected bands."
            )

        result_df["time"] = result_df["time"].apply(
            lambda t: datetime.utcfromtimestamp(t / 1000)
        )

        if out_df:
            result_df.to_csv(out_df, index=False)
        else:
            return result_df

    except Exception as e:
        raise RuntimeError(f"Error extracting data: {e}.")

extract_transect(image, line, reducer='mean', n_segments=100, dist_interval=None, scale=None, crs=None, crsTransform=None, tileScale=1.0, to_pandas=False, **kwargs)

Extracts transect from an image. Credits to Gena for providing the JavaScript example https://code.earthengine.google.com/b09759b8ac60366ee2ae4eccdd19e615.

Parameters:

Name	Type	Description	Default
image	Image	The image to extract transect from.	required
line	LineString	The LineString used to extract transect from an image.	required
reducer	str	The ee.Reducer to use, e.g., 'mean', 'median', 'min', 'max', 'stdDev'. Defaults to "mean".	'mean'
n_segments	int	The number of segments that the LineString will be split into. Defaults to 100.	100
dist_interval	float	The distance interval used for splitting the LineString. If specified, the n_segments parameter will be ignored. Defaults to None.	None
scale	float	A nominal scale in meters of the projection to work in. Defaults to None.	None
crs	Projection	The projection to work in. If unspecified, the projection of the image's first band is used. If specified in addition to scale, rescaled to the specified scale. Defaults to None.	None
crsTransform	list	The list of CRS transform values. This is a row-major ordering of the 3x2 transform matrix. This option is mutually exclusive with 'scale', and will replace any transform already set on the projection. Defaults to None.	None
tileScale	float	A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.	1.0
to_pandas	bool	Whether to convert the result to a pandas dataframe. Default to False.	False

Raises:

Type	Description
TypeError	If the geometry type is not LineString.
Exception	If the program fails to compute.

Returns:

Type	Description
	ee.FeatureCollection: The FeatureCollection containing the transect with distance and reducer values.

Source code in geemap/common.py

def extract_transect(
    image,
    line,
    reducer="mean",
    n_segments=100,
    dist_interval=None,
    scale=None,
    crs=None,
    crsTransform=None,
    tileScale=1.0,
    to_pandas=False,
    **kwargs,
):
    """Extracts transect from an image. Credits to Gena for providing the JavaScript example https://code.earthengine.google.com/b09759b8ac60366ee2ae4eccdd19e615.

    Args:
        image (ee.Image): The image to extract transect from.
        line (ee.Geometry.LineString): The LineString used to extract transect from an image.
        reducer (str, optional): The ee.Reducer to use, e.g., 'mean', 'median', 'min', 'max', 'stdDev'. Defaults to "mean".
        n_segments (int, optional): The number of segments that the LineString will be split into. Defaults to 100.
        dist_interval (float, optional): The distance interval used for splitting the LineString. If specified, the n_segments parameter will be ignored. Defaults to None.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.
        crs (ee.Projection, optional): The projection to work in. If unspecified, the projection of the image's first band is used. If specified in addition to scale, rescaled to the specified scale. Defaults to None.
        crsTransform (list, optional): The list of CRS transform values. This is a row-major ordering of the 3x2 transform matrix. This option is mutually exclusive with 'scale', and will replace any transform already set on the projection. Defaults to None.
        tileScale (float, optional): A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.
        to_pandas (bool, optional): Whether to convert the result to a pandas dataframe. Default to False.

    Raises:
        TypeError: If the geometry type is not LineString.
        Exception: If the program fails to compute.

    Returns:
        ee.FeatureCollection: The FeatureCollection containing the transect with distance and reducer values.
    """
    try:
        geom_type = line.type().getInfo()
        if geom_type != "LineString":
            raise TypeError("The geometry type must be LineString.")

        reducer = eval("ee.Reducer." + reducer + "()")
        maxError = image.projection().nominalScale().divide(5)

        length = line.length(maxError)
        if dist_interval is None:
            dist_interval = length.divide(n_segments)

        distances = ee.List.sequence(0, length, dist_interval)
        lines = line.cutLines(distances, maxError).geometries()

        def set_dist_attr(l):
            l = ee.List(l)
            geom = ee.Geometry(l.get(0))
            distance = ee.Number(l.get(1))
            geom = ee.Geometry.LineString(geom.coordinates())
            return ee.Feature(geom, {"distance": distance})

        lines = lines.zip(distances).map(set_dist_attr)
        lines = ee.FeatureCollection(lines)

        transect = image.reduceRegions(
            **{
                "collection": ee.FeatureCollection(lines),
                "reducer": reducer,
                "scale": scale,
                "crs": crs,
                "crsTransform": crsTransform,
                "tileScale": tileScale,
            }
        )

        if to_pandas:
            return ee_to_df(transect)
        return transect

    except Exception as e:
        raise Exception(e)

extract_values_to_points(in_fc, image, out_fc=None, scale=None, crs=None, crsTransform=None, tileScale=1, stats_type='FIRST', timeout=300, proxies=None, **kwargs)

Extracts image values to points.

Parameters:

Name	Type	Description	Default
in_fc	object	ee.FeatureCollection.	required
image	object	The ee.Image to extract pixel values.	required
out_fc	object	The output feature collection. Defaults to None.	None
scale	Projectoin	A nominal scale in meters of the projection to sample in. If unspecified,the scale of the image's first band is used.	None
crs	str	The projection to work in. If unspecified, the projection of the image's first band is used. If specified in addition to scale, rescaled to the specified scale. Defaults to None.	None
crsTransform	list	The list of CRS transform values. This is a row-major ordering of the 3x2 transform matrix. This option is mutually exclusive with 'scale', and will replace any transform already set on the projection.	None
tile_scale	float	A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default.	required
stats_type	str	Statistic type to be calculated. Defaults to 'FIRST'.	'FIRST'
timeout	int	The number of seconds after which the request will be terminated. Defaults to 300.	300
proxies	dict	A dictionary of proxy servers to use for each request. Defaults to None.	None

Returns:

Name	Type	Description
object		ee.FeatureCollection

Source code in geemap/common.py

def extract_values_to_points(
    in_fc,
    image,
    out_fc=None,
    scale=None,
    crs=None,
    crsTransform=None,
    tileScale=1,
    stats_type="FIRST",
    timeout=300,
    proxies=None,
    **kwargs,
):
    """Extracts image values to points.

    Args:
        in_fc (object): ee.FeatureCollection.
        image (object): The ee.Image to extract pixel values.
        out_fc (object, optional): The output feature collection. Defaults to None.
        scale (ee.Projectoin, optional): A nominal scale in meters of the projection to sample in. If unspecified,the scale of the image's first band is used.
        crs (str, optional): The projection to work in. If unspecified, the projection of the image's first band is used. If specified in addition to scale, rescaled to the specified scale. Defaults to None.
        crsTransform (list, optional): The list of CRS transform values. This is a row-major ordering of the 3x2 transform matrix. This option is mutually exclusive with 'scale', and will replace any transform already set on the projection.
        tile_scale (float, optional): A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default.
        stats_type (str, optional): Statistic type to be calculated. Defaults to 'FIRST'.
        timeout (int, optional): The number of seconds after which the request will be terminated. Defaults to 300.
        proxies (dict, optional): A dictionary of proxy servers to use for each request. Defaults to None.

    Returns:
        object: ee.FeatureCollection
    """

    if "tile_scale" in kwargs:
        tileScale = kwargs["tile_scale"]
    if "crs_transform" in kwargs:
        crsTransform = kwargs["crs_transform"]

    allowed_stats = {
        "FIRST": ee.Reducer.first(),
        "MEAN": ee.Reducer.mean(),
        "MAXIMUM": ee.Reducer.max(),
        "MEDIAN": ee.Reducer.median(),
        "MINIMUM": ee.Reducer.min(),
        "MODE": ee.Reducer.mode(),
        "STD": ee.Reducer.stdDev(),
        "MIN_MAX": ee.Reducer.minMax(),
        "SUM": ee.Reducer.sum(),
        "VARIANCE": ee.Reducer.variance(),
    }

    if stats_type.upper() not in allowed_stats:
        raise ValueError(
            f"The statistics_type must be one of the following {', '.join(allowed_stats.keys())}"
        )

    if not isinstance(in_fc, ee.FeatureCollection):
        try:
            in_fc = shp_to_ee(in_fc)
        except Exception as e:
            print(e)
            return

    if not isinstance(image, ee.Image):
        print("The image must be an instance of ee.Image.")
        return

    result = image.reduceRegions(
        collection=in_fc,
        reducer=allowed_stats[stats_type.upper()],
        scale=scale,
        crs=crs,
        crsTransform=crsTransform,
        tileScale=tileScale,
    )

    if out_fc is not None:
        ee_export_vector(result, out_fc, timeout=timeout, proxies=proxies)
    else:
        return result

file_browser(in_dir=None, show_hidden=False, add_root_node=True, search_description=None, use_import=False, return_sep_widgets=False, node_icon='file')

Creates a simple file browser and text editor.

Parameters:

Name	Type	Description	Default
in_dir	str	The input directory. Defaults to None, which will use the current working directory.	None
show_hidden	bool	Whether to show hidden files/folders. Defaults to False.	False
add_root_node	bool	Whether to add the input directory as a root node. Defaults to True.	True
search_description	str	The description of the search box. Defaults to None.	None
use_import	bool	Whether to show the import button. Defaults to False.	False
return_sep_widgets	bool	Whether to return the results as separate widgets. Defaults to False.	False

Returns:

Name	Type	Description
object		An ipywidget.

Source code in geemap/common.py

def file_browser(
    in_dir=None,
    show_hidden=False,
    add_root_node=True,
    search_description=None,
    use_import=False,
    return_sep_widgets=False,
    node_icon="file",
):
    """Creates a simple file browser and text editor.

    Args:
        in_dir (str, optional): The input directory. Defaults to None, which will use the current working directory.
        show_hidden (bool, optional): Whether to show hidden files/folders. Defaults to False.
        add_root_node (bool, optional): Whether to add the input directory as a root node. Defaults to True.
        search_description (str, optional): The description of the search box. Defaults to None.
        use_import (bool, optional): Whether to show the import button. Defaults to False.
        return_sep_widgets (bool, optional): Whether to return the results as separate widgets. Defaults to False.

    Returns:
        object: An ipywidget.
    """
    import platform

    if in_dir is None:
        in_dir = os.getcwd()

    if not os.path.exists(in_dir):
        print("The provided directory does not exist.")
        return
    elif not os.path.isdir(in_dir):
        print("The provided path is not a valid directory.")
        return

    sep = "/"
    if platform.system() == "Windows":
        sep = "\\"

    if in_dir.endswith(sep):
        in_dir = in_dir[:-1]

    full_widget = widgets.HBox()
    left_widget = widgets.VBox()

    right_widget = widgets.VBox()

    import_btn = widgets.Button(
        description="import",
        button_style="primary",
        tooltip="import the content to a new cell",
        disabled=True,
    )
    import_btn.layout.width = "70px"
    path_widget = widgets.Text()
    path_widget.layout.min_width = "400px"
    # path_widget.layout.max_width = '400px'
    save_widget = widgets.Button(
        description="Save",
        button_style="primary",
        tooltip="Save edits to file.",
        disabled=True,
    )
    info_widget = widgets.HBox()
    info_widget.children = [path_widget, save_widget]
    if use_import:
        info_widget.children = [import_btn, path_widget, save_widget]

    text_widget = widgets.Textarea()
    text_widget.layout.width = "630px"
    text_widget.layout.height = "600px"

    right_widget.children = [info_widget, text_widget]
    full_widget.children = [left_widget]

    if search_description is None:
        search_description = "Search files/folders..."
    search_box = widgets.Text(placeholder=search_description)
    search_box.layout.width = "310px"
    tree_widget = widgets.Output()
    tree_widget.layout.max_width = "310px"
    tree_widget.overflow = "auto"

    left_widget.children = [search_box, tree_widget]

    tree = Tree(multiple_selection=False)
    tree_dict = {}

    def on_button_clicked(b):
        content = text_widget.value
        out_file = path_widget.value

        out_dir = os.path.dirname(out_file)
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)

        with open(out_file, "w") as f:
            f.write(content)

        text_widget.disabled = True
        text_widget.value = "The content has been saved successfully."
        save_widget.disabled = True
        path_widget.disabled = True

        if (out_file not in tree_dict.keys()) and (out_dir in tree_dict.keys()):
            node = Node(os.path.basename(out_file))
            tree_dict[out_file] = node
            parent_node = tree_dict[out_dir]
            parent_node.add_node(node)

    save_widget.on_click(on_button_clicked)

    def import_btn_clicked(b):
        if (text_widget.value != "") and (path_widget.value.endswith(".py")):
            create_code_cell(text_widget.value)

    import_btn.on_click(import_btn_clicked)

    def search_box_callback(text):
        with tree_widget:
            if text.value == "":
                print("Loading...")
                tree_widget.outputs = ()
                display(tree)
            else:
                tree_widget.outputs = ()
                print("Searching...")
                tree_widget.outputs = ()
                sub_tree = search_api_tree(text.value, tree_dict)
                display(sub_tree)

    search_box.on_submit(search_box_callback)

    def handle_file_click(event):
        if event["new"]:
            cur_node = event["owner"]
            for key in tree_dict.keys():
                if (cur_node is tree_dict[key]) and (os.path.isfile(key)):
                    if key.endswith(".py"):
                        import_btn.disabled = False
                    else:
                        import_btn.disabled = True
                    try:
                        with open(key) as f:
                            content = f.read()
                            text_widget.value = content
                            text_widget.disabled = False
                            path_widget.value = key
                            path_widget.disabled = False
                            save_widget.disabled = False
                            full_widget.children = [left_widget, right_widget]
                    except Exception as e:
                        path_widget.value = key
                        path_widget.disabled = True
                        save_widget.disabled = True
                        text_widget.disabled = True
                        text_widget.value = (
                            "Failed to open {}.".format(cur_node.name) + "\n\n" + str(e)
                        )
                        full_widget.children = [left_widget, right_widget]
                        return
                    break

    def handle_folder_click(event):
        if event["new"]:
            full_widget.children = [left_widget]
            text_widget.value = ""

    if add_root_node:
        root_name = in_dir.split(sep)[-1]
        root_node = Node(root_name)
        tree_dict[in_dir] = root_node
        tree.add_node(root_node)
        root_node.observe(handle_folder_click, "selected")

    for root, d_names, f_names in os.walk(in_dir):
        if not show_hidden:
            folders = root.split(sep)
            for folder in folders:
                if folder.startswith("."):
                    continue
            for d_name in d_names:
                if d_name.startswith("."):
                    d_names.remove(d_name)
            for f_name in f_names:
                if f_name.startswith("."):
                    f_names.remove(f_name)

        d_names.sort()
        f_names.sort()

        if (not add_root_node) and (root == in_dir):
            for d_name in d_names:
                node = Node(d_name)
                tree_dict[os.path.join(in_dir, d_name)] = node
                tree.add_node(node)
                node.opened = False
                node.observe(handle_folder_click, "selected")

        if (root != in_dir) and (root not in tree_dict.keys()):
            name = root.split(sep)[-1]
            dir_name = os.path.dirname(root)
            parent_node = tree_dict[dir_name]
            node = Node(name)
            tree_dict[root] = node
            parent_node.add_node(node)
            node.observe(handle_folder_click, "selected")

        if len(f_names) > 0:
            parent_node = tree_dict[root]
            parent_node.opened = False
            for f_name in f_names:
                node = Node(f_name)
                node.icon = node_icon
                full_path = os.path.join(root, f_name)
                tree_dict[full_path] = node
                parent_node.add_node(node)
                node.observe(handle_file_click, "selected")

    with tree_widget:
        tree_widget.outputs = ()
        display(tree)

    if return_sep_widgets:
        return left_widget, right_widget, tree_dict
    else:
        return full_widget

filter_HUC08(region)

Filters HUC08 watersheds intersecting a given region.

Parameters:

Name	Type	Description	Default
region	object	ee.Geometry	required

Returns:

Name	Type	Description
object		ee.FeatureCollection

Source code in geemap/common.py

def filter_HUC08(region):
    """Filters HUC08 watersheds intersecting a given region.

    Args:
        region (object): ee.Geometry

    Returns:
        object: ee.FeatureCollection
    """

    USGS_HUC08 = ee.FeatureCollection("USGS/WBD/2017/HUC08")  # Subbasins
    HUC08 = USGS_HUC08.filterBounds(region)
    return HUC08

filter_HUC10(region)

Filters HUC10 watersheds intersecting a given region.

Parameters:

Name	Type	Description	Default
region	object	ee.Geometry	required

Returns:

Name	Type	Description
object		ee.FeatureCollection

Source code in geemap/common.py

def filter_HUC10(region):
    """Filters HUC10 watersheds intersecting a given region.

    Args:
        region (object): ee.Geometry

    Returns:
        object: ee.FeatureCollection
    """

    USGS_HUC10 = ee.FeatureCollection("USGS/WBD/2017/HUC10")  # Watersheds
    HUC10 = USGS_HUC10.filterBounds(region)
    return HUC10

filter_NWI(HUC08_Id, region, exclude_riverine=True)

Retrieves NWI dataset for a given HUC8 watershed.

Parameters:

Name	Type	Description	Default
HUC08_Id	str	The HUC8 watershed id.	required
region	object	ee.Geometry	required
exclude_riverine	bool	Whether to exclude riverine wetlands. Defaults to True.	True

Returns:

Name	Type	Description
object		ee.FeatureCollection

Source code in geemap/common.py

def filter_NWI(HUC08_Id, region, exclude_riverine=True):
    """Retrieves NWI dataset for a given HUC8 watershed.

    Args:
        HUC08_Id (str): The HUC8 watershed id.
        region (object): ee.Geometry
        exclude_riverine (bool, optional): Whether to exclude riverine wetlands. Defaults to True.

    Returns:
        object: ee.FeatureCollection
    """
    nwi_asset_prefix = "users/wqs/NWI-HU8/HU8_"
    nwi_asset_suffix = "_Wetlands"
    nwi_asset_path = nwi_asset_prefix + HUC08_Id + nwi_asset_suffix
    nwi_huc = ee.FeatureCollection(nwi_asset_path).filterBounds(region)

    if exclude_riverine:
        nwi_huc = nwi_huc.filter(
            ee.Filter.notEquals(**{"leftField": "WETLAND_TY", "rightValue": "Riverine"})
        )
    return nwi_huc

filter_polygons(ftr)

Converts GeometryCollection to Polygon/MultiPolygon

Parameters:

Name	Type	Description	Default
ftr	object	ee.Feature	required

Returns:

Name	Type	Description
object		ee.Feature

Source code in geemap/common.py

def filter_polygons(ftr):
    """Converts GeometryCollection to Polygon/MultiPolygon

    Args:
        ftr (object): ee.Feature

    Returns:
        object: ee.Feature
    """
    # ee_initialize()
    geometries = ftr.geometry().geometries()
    geometries = geometries.map(
        lambda geo: ee.Feature(ee.Geometry(geo)).set("geoType", ee.Geometry(geo).type())
    )

    polygons = (
        ee.FeatureCollection(geometries)
        .filter(ee.Filter.eq("geoType", "Polygon"))
        .geometry()
    )
    return ee.Feature(polygons).copyProperties(ftr)

find_HUC08(HUC08_Id)

Finds a HUC08 watershed based on a given HUC08 ID

Parameters:

Name	Type	Description	Default
HUC08_Id	str	The HUC08 ID.	required

Returns:

Name	Type	Description
object		ee.FeatureCollection

Source code in geemap/common.py

def find_HUC08(HUC08_Id):
    """Finds a HUC08 watershed based on a given HUC08 ID

    Args:
        HUC08_Id (str): The HUC08 ID.

    Returns:
        object: ee.FeatureCollection
    """

    USGS_HUC08 = ee.FeatureCollection("USGS/WBD/2017/HUC08")  # Subbasins
    HUC08 = USGS_HUC08.filter(ee.Filter.eq("huc8", HUC08_Id))
    return HUC08

find_HUC10(HUC10_Id)

Finds a HUC10 watershed based on a given HUC08 ID

Parameters:

Name	Type	Description	Default
HUC10_Id	str	The HUC10 ID.	required

Returns:

Name	Type	Description
object		ee.FeatureCollection

Source code in geemap/common.py

def find_HUC10(HUC10_Id):
    """Finds a HUC10 watershed based on a given HUC08 ID

    Args:
        HUC10_Id (str): The HUC10 ID.

    Returns:
        object: ee.FeatureCollection
    """

    USGS_HUC10 = ee.FeatureCollection("USGS/WBD/2017/HUC10")  # Watersheds
    HUC10 = USGS_HUC10.filter(ee.Filter.eq("huc10", HUC10_Id))
    return HUC10

find_NAIP(region, add_NDVI=True, add_NDWI=True)

Create annual NAIP mosaic for a given region.

Parameters:

Name	Type	Description	Default
region	object	ee.Geometry	required
add_NDVI	bool	Whether to add the NDVI band. Defaults to True.	True
add_NDWI	bool	Whether to add the NDWI band. Defaults to True.	True

Returns:

Name	Type	Description
object		ee.ImageCollection

Source code in geemap/common.py

def find_NAIP(region, add_NDVI=True, add_NDWI=True):
    """Create annual NAIP mosaic for a given region.

    Args:
        region (object): ee.Geometry
        add_NDVI (bool, optional): Whether to add the NDVI band. Defaults to True.
        add_NDWI (bool, optional): Whether to add the NDWI band. Defaults to True.

    Returns:
        object: ee.ImageCollection
    """

    init_collection = (
        ee.ImageCollection("USDA/NAIP/DOQQ")
        .filterBounds(region)
        .filterDate("2009-01-01", "2019-12-31")
        .filter(ee.Filter.listContains("system:band_names", "N"))
    )

    yearList = ee.List(
        init_collection.distinct(["system:time_start"]).aggregate_array(
            "system:time_start"
        )
    )
    init_years = yearList.map(lambda y: ee.Date(y).get("year"))

    # remove duplicates
    init_years = ee.Dictionary(
        init_years.reduce(ee.Reducer.frequencyHistogram())
    ).keys()
    years = init_years.map(lambda x: ee.Number.parse(x))
    # years = init_years.map(lambda x: x)

    # Available NAIP years with NIR band
    def NAIPAnnual(year):
        start_date = ee.Date.fromYMD(year, 1, 1)
        end_date = ee.Date.fromYMD(year, 12, 31)
        collection = init_collection.filterDate(start_date, end_date)
        # .filterBounds(geometry)
        # .filter(ee.Filter.listContains("system:band_names", "N"))
        time_start = ee.Date(
            ee.List(collection.aggregate_array("system:time_start")).sort().get(0)
        ).format("YYYY-MM-dd")
        time_end = ee.Date(
            ee.List(collection.aggregate_array("system:time_end")).sort().get(-1)
        ).format("YYYY-MM-dd")
        col_size = collection.size()
        image = ee.Image(collection.mosaic().clip(region))

        if add_NDVI:
            NDVI = (
                ee.Image(image)
                .normalizedDifference(["N", "R"])
                .select(["nd"], ["ndvi"])
            )
            image = image.addBands(NDVI)

        if add_NDWI:
            NDWI = (
                ee.Image(image)
                .normalizedDifference(["G", "N"])
                .select(["nd"], ["ndwi"])
            )
            image = image.addBands(NDWI)

        return image.set(
            {
                "system:time_start": time_start,
                "system:time_end": time_end,
                "tiles": col_size,
            }
        )

    # remove years with incomplete coverage
    naip = ee.ImageCollection(years.map(NAIPAnnual))
    mean_size = ee.Number(naip.aggregate_mean("tiles"))
    total_sd = ee.Number(naip.aggregate_total_sd("tiles"))
    threshold = mean_size.subtract(total_sd.multiply(1))
    naip = naip.filter(
        ee.Filter.Or(ee.Filter.gte("tiles", threshold), ee.Filter.gte("tiles", 15))
    )
    naip = naip.filter(ee.Filter.gte("tiles", 7))

    naip_count = naip.size()
    naip_seq = ee.List.sequence(0, naip_count.subtract(1))

    def set_index(index):
        img = ee.Image(naip.toList(naip_count).get(index))
        return img.set({"system:uid": ee.Number(index).toUint8()})

    naip = naip_seq.map(set_index)

    return ee.ImageCollection(naip)

find_NWI(HUC08_Id, exclude_riverine=True)

Finds NWI dataset for a given HUC08 watershed.

Parameters:

Name	Type	Description	Default
HUC08_Id	str	The HUC08 watershed ID.	required
exclude_riverine	bool	Whether to exclude riverine wetlands. Defaults to True.	True

Returns:

Name	Type	Description
object		ee.FeatureCollection

Source code in geemap/common.py

def find_NWI(HUC08_Id, exclude_riverine=True):
    """Finds NWI dataset for a given HUC08 watershed.

    Args:
        HUC08_Id (str): The HUC08 watershed ID.
        exclude_riverine (bool, optional): Whether to exclude riverine wetlands. Defaults to True.

    Returns:
        object: ee.FeatureCollection
    """

    nwi_asset_prefix = "users/wqs/NWI-HU8/HU8_"
    nwi_asset_suffix = "_Wetlands"
    nwi_asset_path = nwi_asset_prefix + HUC08_Id + nwi_asset_suffix
    nwi_huc = ee.FeatureCollection(nwi_asset_path)
    if exclude_riverine:
        nwi_huc = nwi_huc.filter(
            ee.Filter.notEquals(**{"leftField": "WETLAND_TY", "rightValue": "Riverine"})
        )
    return nwi_huc

find_files(input_dir, ext=None, fullpath=True, recursive=True)

Find files in a directory.

Parameters:

Name	Type	Description	Default
input_dir	str	The input directory.	required
ext	str	The file extension to match. Defaults to None.	None
fullpath	bool	Whether to return the full path. Defaults to True.	True
recursive	bool	Whether to search recursively. Defaults to True.	True

Returns:

Name	Type	Description
list		A list of matching files.

Source code in geemap/common.py

def find_files(input_dir, ext=None, fullpath=True, recursive=True):
    """Find files in a directory.

    Args:
        input_dir (str): The input directory.
        ext (str, optional): The file extension to match. Defaults to None.
        fullpath (bool, optional): Whether to return the full path. Defaults to True.
        recursive (bool, optional): Whether to search recursively. Defaults to True.

    Returns:
        list: A list of matching files.
    """

    from pathlib import Path

    files = []

    if ext is None:
        ext = "*"
    else:
        ext = ext.replace(".", "")

    ext = f"*.{ext}"

    if recursive:
        if fullpath:
            files = [str(path.joinpath()) for path in Path(input_dir).rglob(ext)]
        else:
            files = [str(path.name) for path in Path(input_dir).rglob(ext)]
    else:
        if fullpath:
            files = [str(path.joinpath()) for path in Path(input_dir).glob(ext)]
        else:
            files = [path.name for path in Path(input_dir).glob(ext)]

    return files

find_landsat_by_path_row(landsat_col, path_num, row_num)

Finds Landsat images by WRS path number and row number.

Parameters:

Name	Type	Description	Default
landsat_col	str	The image collection id of Landsat.	required
path_num	int	The WRS path number.	required
row_num	int	the WRS row number.	required

Returns:

Name	Type	Description
object		ee.ImageCollection

Source code in geemap/common.py

def find_landsat_by_path_row(landsat_col, path_num, row_num):
    """Finds Landsat images by WRS path number and row number.

    Args:
        landsat_col (str): The image collection id of Landsat.
        path_num (int): The WRS path number.
        row_num (int): the WRS row number.

    Returns:
        object: ee.ImageCollection
    """
    try:
        if isinstance(landsat_col, str):
            landsat_col = ee.ImageCollection(landsat_col)
            collection = landsat_col.filter(ee.Filter.eq("WRS_PATH", path_num)).filter(
                ee.Filter.eq("WRS_ROW", row_num)
            )
            return collection
    except Exception as e:
        print(e)

find_matching_bracket(lines, start_line_index, start_char_index, matching_char='{')

Finds the position of the matching closing bracket from a list of lines.

Parameters:

Name	Type	Description	Default
lines	list	The input list of lines.	required
start_line_index	int	The line index where the starting bracket is located.	required
start_char_index	int	The position index of the starting bracket.	required
matching_char	str	The starting bracket to search for. Defaults to '{'.	'{'

Returns:

Name	Type	Description
matching_line_index	int	The line index where the matching closing bracket is located.
matching_char_index	int	The position index of the matching closing bracket.

Source code in geemap/conversion.py

def find_matching_bracket(lines, start_line_index, start_char_index, matching_char="{"):
    """Finds the position of the matching closing bracket from a list of lines.

    Args:
        lines (list): The input list of lines.
        start_line_index (int): The line index where the starting bracket is located.
        start_char_index (int): The position index of the starting bracket.
        matching_char (str, optional): The starting bracket to search for. Defaults to '{'.

    Returns:
        matching_line_index (int): The line index where the matching closing bracket is located.
        matching_char_index (int): The position index of the matching closing bracket.
    """
    matching_line_index = -1
    matching_char_index = -1

    matching_chars = {"{": "}", "(": ")", "[": "]"}
    if matching_char not in matching_chars.keys():
        print(
            "The matching character must be one of the following: {}".format(
                ", ".join(matching_chars.keys())
            )
        )
        return matching_line_index, matching_char_index

    # Create a deque to use it as a stack.
    d = deque()

    for line_index in range(start_line_index, len(lines)):
        line = lines[line_index]
        # deal with the line where the starting bracket is located.
        if line_index == start_line_index:
            line = lines[line_index][start_char_index:]

        for index, item in enumerate(line):
            # Pops a starting bracket for each closing bracket
            if item == matching_chars[matching_char]:
                d.popleft()
            # Push all starting brackets
            elif item == matching_char:
                d.append(matching_char)

            # If deque becomes empty
            if not d:
                matching_line_index = line_index
                if line_index == start_line_index:
                    matching_char_index = start_char_index + index
                else:
                    matching_char_index = index

                return matching_line_index, matching_char_index

    return matching_line_index, matching_char_index

fishnet(data, h_interval=1.0, v_interval=1.0, rows=None, cols=None, delta=1.0, intersect=True, output=None, **kwargs)

Create a fishnet (i.e., rectangular grid) based on an input vector dataset.

Parameters:

Name	Type	Description	Default
data	str | Geometry | Feature | FeatureCollection	The input vector dataset. It can be a file path, HTTP URL, ee.Geometry, ee.Feature, or ee.FeatureCollection.	required
h_interval	float	The horizontal interval in degrees. It will be ignored if rows and cols are specified. Defaults to 1.0.	1.0
v_interval	float	The vertical interval in degrees. It will be ignored if rows and cols are specified. Defaults to 1.0.	1.0
rows	int	The number of rows. Defaults to None.	None
cols	int	The number of columns. Defaults to None.	None
delta	float	The buffer distance in degrees. Defaults to 1.0.	1.0
intersect	bool	If True, the output will be a feature collection of intersecting polygons. Defaults to True.	True
output	str	The output file path. Defaults to None.	None

Returns:

Type	Description
	ee.FeatureCollection: The fishnet as an ee.FeatureCollection.

Source code in geemap/common.py

def fishnet(
    data,
    h_interval=1.0,
    v_interval=1.0,
    rows=None,
    cols=None,
    delta=1.0,
    intersect=True,
    output=None,
    **kwargs,
):
    """Create a fishnet (i.e., rectangular grid) based on an input vector dataset.

    Args:
        data (str | ee.Geometry | ee.Feature | ee.FeatureCollection): The input vector dataset. It can be a file path, HTTP URL, ee.Geometry, ee.Feature, or ee.FeatureCollection.
        h_interval (float, optional): The horizontal interval in degrees. It will be ignored if rows and cols are specified. Defaults to 1.0.
        v_interval (float, optional): The vertical interval in degrees. It will be ignored if rows and cols are specified. Defaults to 1.0.
        rows (int, optional): The number of rows. Defaults to None.
        cols (int, optional): The number of columns. Defaults to None.
        delta (float, optional): The buffer distance in degrees. Defaults to 1.0.
        intersect (bool, optional): If True, the output will be a feature collection of intersecting polygons. Defaults to True.
        output (str, optional): The output file path. Defaults to None.


    Returns:
        ee.FeatureCollection: The fishnet as an ee.FeatureCollection.
    """
    if isinstance(data, str):
        data = vector_to_ee(data, **kwargs)

    if isinstance(data, ee.FeatureCollection) or isinstance(data, ee.Feature):
        data = data.geometry()
    elif isinstance(data, ee.Geometry):
        pass
    else:
        raise ValueError(
            "data must be a string, ee.FeatureCollection, ee.Feature, or ee.Geometry."
        )

    coords = data.bounds().coordinates().getInfo()

    west = coords[0][0][0]
    east = coords[0][1][0]
    south = coords[0][0][1]
    north = coords[0][2][1]

    if rows is not None and cols is not None:
        v_interval = (north - south) / rows
        h_interval = (east - west) / cols

    # west = west - delta * h_interval
    east = east + delta * h_interval
    # south = south - delta * v_interval
    north = north + delta * v_interval

    grids = latlon_grid(v_interval, h_interval, west, east, south, north)

    if intersect:
        grids = grids.filterBounds(data)

    if output is not None:
        ee_export_vector(grids, output)

    else:
        return grids

format_params(line, sep=':')

Formats keys in a dictionary and adds quotes to the keys. For example, {min: 0, max: 10} will result in ('min': 0, 'max': 10)

Parameters:

Name	Type	Description	Default
line	str	A string.	required
sep	str	Separator. Defaults to ':'.	':'

Returns:

Type	Description
	[str]: A string with keys quoted

Source code in geemap/conversion.py

def format_params(line, sep=":"):
    """Formats keys in a dictionary and adds quotes to the keys.
    For example, {min: 0, max: 10} will result in ('min': 0, 'max': 10)

    Args:
        line (str): A string.
        sep (str, optional): Separator. Defaults to ':'.

    Returns:
        [str]: A string with keys quoted
    """
    # print(line)
    new_line = line
    prefix = ""
    # suffix = ""

    if line.strip().startswith("for"):  # skip for loop
        return line

    # find all occurrences of a substring
    def find_all(a_str, sub):
        start = 0
        while True:
            start = a_str.find(sub, start)
            if start == -1:
                return
            yield start
            start += len(sub)  # use start += 1 to find overlapping matches

    indices = list(find_all(line, sep))
    count = len(indices)

    if "{" in line:
        bracket_index = line.index("{")
        if bracket_index < indices[0]:
            prefix = line[: bracket_index + 1]
            line = line[bracket_index + 1 :]

    if count > 0:
        items = line.split(sep)

        if count == 1:
            for i in range(0, count):
                item = items[i].strip()
                if ('"' not in item) and ("'" not in item):
                    new_item = "'" + item + "'"
                    items[i] = items[i].replace(item, new_item)
            new_line = ":".join(items)
        elif count > 1:
            for i in range(0, count):
                item = items[i]
                if "," in item:
                    subitems = item.split(",")
                    subitem = subitems[-1]
                    if ('"' not in subitem) and ("'" not in subitem):
                        new_subitem = "'" + subitem.strip() + "'"
                        subitems[-1] = subitems[-1].replace(subitem, new_subitem)
                        items[i] = ", ".join(subitems)
                else:
                    if ('"' not in item) and ("'" not in item):
                        new_item = "'" + item.strip() + "'"
                        padding = len(item) - len(item.strip())
                        items[i] = " " * padding + item.replace(item, new_item)

            new_line = ":".join(items)

    return prefix + new_line

gdf_bounds(gdf, return_geom=False)

Returns the bounding box of a GeoDataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoDataFrame.	required
return_geom	bool	Whether to return the bounding box as a GeoDataFrame. Defaults to False.	False

Returns:

Type	Description
	list | gpd.GeoDataFrame: A bounding box in the form of a list (minx, miny, maxx, maxy) or GeoDataFrame.

Source code in geemap/common.py

def gdf_bounds(gdf, return_geom=False):
    """Returns the bounding box of a GeoDataFrame.

    Args:
        gdf (gpd.GeoDataFrame): A GeoDataFrame.
        return_geom (bool, optional): Whether to return the bounding box as a GeoDataFrame. Defaults to False.

    Returns:
        list | gpd.GeoDataFrame: A bounding box in the form of a list (minx, miny, maxx, maxy) or GeoDataFrame.
    """
    bounds = gdf.total_bounds
    if return_geom:
        return bbox_to_gdf(bbox=bounds)
    else:
        return bounds

gdf_centroid(gdf, return_geom=False)

Returns the centroid of a GeoDataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoDataFrame.	required
return_geom	bool	Whether to return the bounding box as a GeoDataFrame. Defaults to False.	False

Returns:

Type	Description
	list | gpd.GeoDataFrame: A bounding box in the form of a list (lon, lat) or GeoDataFrame.

Source code in geemap/common.py

def gdf_centroid(gdf, return_geom=False):
    """Returns the centroid of a GeoDataFrame.

    Args:
        gdf (gpd.GeoDataFrame): A GeoDataFrame.
        return_geom (bool, optional): Whether to return the bounding box as a GeoDataFrame. Defaults to False.

    Returns:
        list | gpd.GeoDataFrame: A bounding box in the form of a list (lon, lat) or GeoDataFrame.
    """

    warnings.filterwarnings("ignore")

    centroid = gdf_bounds(gdf, return_geom=True).centroid
    if return_geom:
        return centroid
    else:
        return centroid.x[0], centroid.y[0]

gdf_geom_type(gdf, first_only=True)

Returns the geometry type of a GeoDataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoDataFrame.	required
first_only	bool	Whether to return the geometry type of the first feature in the GeoDataFrame. Defaults to True.	True

Returns:

Name	Type	Description
str		The geometry type of the GeoDataFrame.

Source code in geemap/common.py

def gdf_geom_type(gdf, first_only=True):
    """Returns the geometry type of a GeoDataFrame.

    Args:
        gdf (gpd.GeoDataFrame): A GeoDataFrame.
        first_only (bool, optional): Whether to return the geometry type of the first feature in the GeoDataFrame. Defaults to True.

    Returns:
        str: The geometry type of the GeoDataFrame.
    """

    if first_only:
        return gdf.geometry.type[0]
    else:
        return gdf.geometry.type

gdf_to_df(gdf, drop_geom=True)

Converts a GeoDataFrame to a pandas DataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoDataFrame.	required
drop_geom	bool	Whether to drop the geometry column. Defaults to True.	True

Returns:

Type	Description
	pd.DataFrame: A pandas DataFrame containing the GeoDataFrame.

Source code in geemap/common.py

def gdf_to_df(gdf, drop_geom=True):
    """Converts a GeoDataFrame to a pandas DataFrame.

    Args:
        gdf (gpd.GeoDataFrame): A GeoDataFrame.
        drop_geom (bool, optional): Whether to drop the geometry column. Defaults to True.

    Returns:
        pd.DataFrame: A pandas DataFrame containing the GeoDataFrame.
    """
    import pandas as pd

    if drop_geom:
        df = pd.DataFrame(gdf.drop(columns=["geometry"]))
    else:
        df = pd.DataFrame(gdf)

    return df

gdf_to_ee(gdf, geodesic=True, date=None, date_format='YYYY-MM-dd')

Converts a GeoPandas GeoDataFrame to ee.FeatureCollection.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	The input geopandas.GeoDataFrame to be converted ee.FeatureCollection.	required
geodesic	bool	Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected. Defaults to True.	True
date	str	Column name for the date column. Defaults to None.	None
date_format	str	Date format. A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.	'YYYY-MM-dd'

Raises:

Type	Description
TypeError	The input data type must be geopandas.GeoDataFrame.

Returns:

Type	Description
	ee.FeatureCollection: The output ee.FeatureCollection converted from the input geopandas.GeoDataFrame.

Source code in geemap/common.py

def gdf_to_ee(gdf, geodesic=True, date=None, date_format="YYYY-MM-dd"):
    """Converts a GeoPandas GeoDataFrame to ee.FeatureCollection.

    Args:
        gdf (geopandas.GeoDataFrame): The input geopandas.GeoDataFrame to be converted ee.FeatureCollection.
        geodesic (bool, optional): Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected. Defaults to True.
        date (str, optional): Column name for the date column. Defaults to None.
        date_format (str, optional): Date format. A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults to 'YYYY-MM-dd'.

    Raises:
        TypeError: The input data type must be geopandas.GeoDataFrame.

    Returns:
        ee.FeatureCollection: The output ee.FeatureCollection converted from the input geopandas.GeoDataFrame.
    """
    check_package(name="geopandas", URL="https://geopandas.org")

    import geopandas as gpd

    if not isinstance(gdf, gpd.GeoDataFrame):
        raise TypeError("The input data type must be geopandas.GeoDataFrame.")

    out_json = os.path.join(os.getcwd(), random_string(6) + ".geojson")
    gdf = gdf.to_crs(4326)
    gdf.to_file(out_json, driver="GeoJSON")

    fc = geojson_to_ee(out_json, geodesic=geodesic)

    if date is not None:
        try:
            fc = fc.map(
                lambda x: x.set(
                    "system:time_start",
                    ee.Date.parse(date_format, x.get(date)).millis(),
                )
            )
        except Exception as e:
            raise Exception(e)

    os.remove(out_json)

    return fc

gdf_to_geojson(gdf, out_geojson=None, epsg=None)

Converts a GeoDataFame to GeoJSON.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoPandas GeoDataFrame.	required
out_geojson	str	File path to he output GeoJSON. Defaults to None.	None
epsg	str	An EPSG string, e.g., "4326". Defaults to None.	None

Raises:

Type	Description
TypeError	When the output file extension is incorrect.
Exception	When the conversion fails.

Returns:

Name	Type	Description
dict		When the out_json is None returns a dict.

Source code in geemap/common.py

def gdf_to_geojson(gdf, out_geojson=None, epsg=None):
    """Converts a GeoDataFame to GeoJSON.

    Args:
        gdf (GeoDataFrame): A GeoPandas GeoDataFrame.
        out_geojson (str, optional): File path to he output GeoJSON. Defaults to None.
        epsg (str, optional): An EPSG string, e.g., "4326". Defaults to None.

    Raises:
        TypeError: When the output file extension is incorrect.
        Exception: When the conversion fails.

    Returns:
        dict: When the out_json is None returns a dict.
    """
    check_package(name="geopandas", URL="https://geopandas.org")

    try:
        if epsg is not None:
            gdf = gdf.to_crs(epsg=epsg)
        geojson = gdf.__geo_interface__

        if out_geojson is None:
            return geojson
        else:
            ext = os.path.splitext(out_geojson)[1]
            if ext.lower() not in [".json", ".geojson"]:
                raise TypeError(
                    "The output file extension must be either .json or .geojson"
                )
            out_dir = os.path.dirname(out_geojson)
            if not os.path.exists(out_dir):
                os.makedirs(out_dir)

            gdf.to_file(out_geojson, driver="GeoJSON")
    except Exception as e:
        raise Exception(e)

geocode(location, max_rows=10, reverse=False)

Search location by address and lat/lon coordinates.

Parameters:

Name	Type	Description	Default
location	str	Place name or address	required
max_rows	int	Maximum number of records to return. Defaults to 10.	10
reverse	bool	Search place based on coordinates. Defaults to False.	False

Source code in geemap/common.py

def geocode(location, max_rows=10, reverse=False):
    """Search location by address and lat/lon coordinates.

    Args:
        location (str): Place name or address
        max_rows (int, optional): Maximum number of records to return. Defaults to 10.
        reverse (bool, optional): Search place based on coordinates. Defaults to False.
    Returns:
        list: Returns a list of locations.
    """
    import geocoder

    if not isinstance(location, str):
        print("The location must be a string.")
        return None

    if not reverse:
        locations = []
        addresses = set()
        g = geocoder.arcgis(location, maxRows=max_rows)

        for result in g:
            address = result.address
            if address not in addresses:
                addresses.add(address)
                locations.append(result)

        if len(locations) > 0:
            return locations
        else:
            return None

    else:
        try:
            if "," in location:
                latlon = [float(x) for x in location.split(",")]
            elif " " in location:
                latlon = [float(x) for x in location.split(" ")]
            else:
                return
            g = geocoder.arcgis(latlon, method="reverse")
            locations = []
            addresses = set()

            for result in g:
                address = result.address
                if address not in addresses:
                    addresses.add(address)
                    locations.append(result)

            if len(locations) > 0:
                return locations
            else:
                return None

        except Exception as e:
            print(e)
            return None

geojson_to_df(in_geojson, encoding='utf-8', drop_geometry=True)

Converts a GeoJSON object to a pandas DataFrame.

Parameters:

Name	Type	Description	Default
in_geojson	str | dict	The input GeoJSON file or dict.	required
encoding	str	The encoding of the GeoJSON object. Defaults to "utf-8".	'utf-8'
drop_geometry	bool	Whether to drop the geometry column. Defaults to True.	True

Raises:

Type	Description
FileNotFoundError	If the input GeoJSON file could not be found.

Returns:

Type	Description
	pd.DataFrame: A pandas DataFrame containing the GeoJSON object.

Source code in geemap/common.py

def geojson_to_df(in_geojson, encoding="utf-8", drop_geometry=True):
    """Converts a GeoJSON object to a pandas DataFrame.

    Args:
        in_geojson (str | dict): The input GeoJSON file or dict.
        encoding (str, optional): The encoding of the GeoJSON object. Defaults to "utf-8".
        drop_geometry (bool, optional): Whether to drop the geometry column. Defaults to True.

    Raises:
        FileNotFoundError: If the input GeoJSON file could not be found.

    Returns:
        pd.DataFrame: A pandas DataFrame containing the GeoJSON object.
    """

    import pandas as pd
    from urllib.request import urlopen

    if isinstance(in_geojson, str):
        if in_geojson.startswith("http"):
            in_geojson = github_raw_url(in_geojson)
            with urlopen(in_geojson) as f:
                data = json.load(f)
        else:
            in_geojson = os.path.abspath(in_geojson)
            if not os.path.exists(in_geojson):
                raise FileNotFoundError("The provided GeoJSON file could not be found.")

            with open(in_geojson, encoding=encoding) as f:
                data = json.load(f)

    elif isinstance(in_geojson, dict):
        data = in_geojson

    df = pd.json_normalize(data["features"])
    df.columns = [col.replace("properties.", "") for col in df.columns]
    if drop_geometry:
        df = df[df.columns.drop(list(df.filter(regex="geometry")))]
    return df

geojson_to_ee(geo_json, geodesic=False, encoding='utf-8')

Converts a GeoJSON to an Earth Engine Geometry or FeatureCollection.

Parameters:

Name	Type	Description	Default
geo_json	Union[Dict[str, Any], str]	A GeoJSON geometry dictionary or file path.	required
geodesic	bool	Whether line segments should be interpreted as spherical geodesics. If false, indicates that line segments should be interpreted as planar lines in the specified CRS. If absent, defaults to true if the CRS is geographic (including the default EPSG:4326), or to false if the CRS is projected. Defaults to False.	False
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'

Returns:

Type	Description
Union[Geometry, FeatureCollection]	Union[ee.Geometry, ee.FeatureCollection]: An Earth Engine Geometry or FeatureCollection.

Raises:

Type	Description
Exception	If the GeoJSON cannot be converted to an Earth Engine object.

Source code in geemap/coreutils.py

def geojson_to_ee(
    geo_json: Union[Dict[str, Any], str],
    geodesic: bool = False,
    encoding: str = "utf-8",
) -> Union[ee.Geometry, ee.FeatureCollection]:
    """Converts a GeoJSON to an Earth Engine Geometry or FeatureCollection.

    Args:
        geo_json (Union[Dict[str, Any], str]): A GeoJSON geometry dictionary or
            file path.
        geodesic (bool, optional): Whether line segments should be interpreted
            as spherical geodesics. If false, indicates that line segments
            should be interpreted as planar lines in the specified CRS. If
            absent, defaults to true if the CRS is geographic (including the
            default EPSG:4326), or to false if the CRS is projected. Defaults to False.
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".

    Returns:
        Union[ee.Geometry, ee.FeatureCollection]: An Earth Engine Geometry or FeatureCollection.

    Raises:
        Exception: If the GeoJSON cannot be converted to an Earth Engine object.
    """

    try:
        if isinstance(geo_json, str):
            if geo_json.startswith("http") and geo_json.endswith(".geojson"):
                geo_json = github_raw_url(geo_json)
                out_geojson = temp_file_path(extension=".geojson")
                download_file(geo_json, out_geojson)
                with open(out_geojson, "r", encoding=encoding) as f:
                    geo_json = json.loads(f.read())
                os.remove(out_geojson)

            elif os.path.isfile(geo_json):
                with open(os.path.abspath(geo_json), encoding=encoding) as f:
                    geo_json = json.load(f)

        # geo_json["geodesic"] = geodesic
        if geo_json["type"] == "FeatureCollection":
            for feature in geo_json["features"]:
                if feature["geometry"]["type"] != "Point":
                    feature["geometry"]["geodesic"] = geodesic
            features = ee.FeatureCollection(geo_json)
            return features
        elif geo_json["type"] == "Feature":
            geom = None
            if "style" in geo_json["properties"]:
                keys = geo_json["properties"]["style"].keys()
                if "radius" in keys:  # Checks whether it is a circle
                    geom = ee.Geometry(geo_json["geometry"])
                    radius = geo_json["properties"]["style"]["radius"]
                    geom = geom.buffer(radius)
                elif geo_json["geometry"]["type"] == "Point":
                    geom = ee.Geometry(geo_json["geometry"])
                else:
                    geom = ee.Geometry(geo_json["geometry"], "", geodesic)
            elif (
                geo_json["geometry"]["type"] == "Point"
            ):  # Checks whether it is a point
                coordinates = geo_json["geometry"]["coordinates"]
                longitude = coordinates[0]
                latitude = coordinates[1]
                geom = ee.Geometry.Point(longitude, latitude)
            else:
                geom = ee.Geometry(geo_json["geometry"], "", geodesic)
            return geom
        else:
            raise Exception("Could not convert the geojson to ee.Geometry()")

    except Exception as e:
        print("Could not convert the geojson to ee.Geometry()")
        raise Exception(e)

geometry_type(ee_object)

Get geometry type of an Earth Engine object.

Parameters:

Name	Type	Description	Default
ee_object	Any	An Earth Engine object.	required

Returns:

Name	Type	Description
str	str	Returns geometry type. One of Point, MultiPoint, LineString, LinearRing, MultiLineString, BBox, Rectangle, Polygon, MultiPolygon.

Raises:

Type	Description
TypeError	If the ee_object is not one of ee.Geometry, ee.Feature, ee.FeatureCollection.

Source code in geemap/coreutils.py

def geometry_type(ee_object: Any) -> str:
    """Get geometry type of an Earth Engine object.

    Args:
        ee_object (Any): An Earth Engine object.

    Returns:
        str: Returns geometry type. One of Point, MultiPoint, LineString,
            LinearRing, MultiLineString, BBox, Rectangle, Polygon, MultiPolygon.

    Raises:
        TypeError: If the ee_object is not one of ee.Geometry, ee.Feature,
            ee.FeatureCollection.
    """
    if isinstance(ee_object, ee.Geometry):
        return ee_object.type().getInfo()
    elif isinstance(ee_object, ee.Feature):
        return ee_object.geometry().type().getInfo()
    elif isinstance(ee_object, ee.FeatureCollection):
        return ee.Feature(ee_object.first()).geometry().type().getInfo()
    else:
        raise TypeError(
            "The ee_object must be one of ee.Geometry, ee.Feature, ee.FeatureCollection."
        )

geotiff_to_image(image, output)

Converts a GeoTIFF file to a JPEG/PNG image.

Parameters:

Name	Type	Description	Default
image	str	The path to the input GeoTIFF file.	required
output	str	The path to save the output JPEG/PNG file.	required

Returns:

Type	Description
None	None

Source code in geemap/common.py

def geotiff_to_image(image: str, output: str) -> None:
    """
    Converts a GeoTIFF file to a JPEG/PNG image.

    Args:
        image (str): The path to the input GeoTIFF file.
        output (str): The path to save the output JPEG/PNG file.

    Returns:
        None
    """

    import rasterio
    from PIL import Image

    # Open the GeoTIFF file
    with rasterio.open(image) as dataset:
        # Read the image data
        data = dataset.read()

        # Convert the image data to 8-bit format (assuming it's not already)
        if dataset.dtypes[0] != "uint8":
            data = (data / data.max() * 255).astype("uint8")

        # Convert the image data to RGB format if it's a single band image
        if dataset.count == 1:
            data = data.squeeze()
            data = data.reshape((1, data.shape[0], data.shape[1]))
            data = data.repeat(3, axis=0)

        # Create a PIL Image object from the image data
        image = Image.fromarray(data.transpose(1, 2, 0))

        # Save the image as a JPEG file
        image.save(output)

get_all_NAIP(start_year=2009, end_year=2019)

Creates annual NAIP imagery mosaic.

Parameters:

Name	Type	Description	Default
start_year	int	The starting year. Defaults to 2009.	2009
end_year	int	The ending year. Defaults to 2019.	2019

Returns:

Name	Type	Description
object		ee.ImageCollection

Source code in geemap/common.py

def get_all_NAIP(start_year=2009, end_year=2019):
    """Creates annual NAIP imagery mosaic.

    Args:
        start_year (int, optional): The starting year. Defaults to 2009.
        end_year (int, optional): The ending year. Defaults to 2019.

    Returns:
        object: ee.ImageCollection
    """
    try:

        def get_annual_NAIP(year):
            try:
                collection = ee.ImageCollection("USDA/NAIP/DOQQ")
                start_date = ee.Date.fromYMD(year, 1, 1)
                end_date = ee.Date.fromYMD(year, 12, 31)
                naip = collection.filterDate(start_date, end_date).filter(
                    ee.Filter.listContains("system:band_names", "N")
                )
                return ee.ImageCollection(naip)
            except Exception as e:
                print(e)

        years = ee.List.sequence(start_year, end_year)
        collection = years.map(get_annual_NAIP)
        return collection

    except Exception as e:
        print(e)

get_annual_NAIP(year, RGBN=True)

Filters NAIP ImageCollection by year.

Parameters:

Name	Type	Description	Default
year	int	The year to filter the NAIP ImageCollection.	required
RGBN	bool	Whether to retrieve 4-band NAIP imagery only. Defaults to True.	True

Returns:

Name	Type	Description
object		ee.ImageCollection

Source code in geemap/common.py

def get_annual_NAIP(year, RGBN=True):
    """Filters NAIP ImageCollection by year.

    Args:
        year (int): The year to filter the NAIP ImageCollection.
        RGBN (bool, optional): Whether to retrieve 4-band NAIP imagery only. Defaults to True.

    Returns:
        object: ee.ImageCollection
    """
    try:
        collection = ee.ImageCollection("USDA/NAIP/DOQQ")
        start_date = str(year) + "-01-01"
        end_date = str(year) + "-12-31"
        naip = collection.filterDate(start_date, end_date)
        if RGBN:
            naip = naip.filter(ee.Filter.listContains("system:band_names", "N"))
        return naip
    except Exception as e:
        print(e)

get_basemap(name)

Gets a basemap tile layer by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the basemap.	required

Returns:

Type	Description
	ipylealfet.TileLayer | ipyleaflet.WMSLayer: The basemap layer.

Source code in geemap/geemap.py

def get_basemap(name):
    """Gets a basemap tile layer by name.

    Args:
        name (str): The name of the basemap.

    Returns:
        ipylealfet.TileLayer | ipyleaflet.WMSLayer: The basemap layer.
    """

    if isinstance(name, str):
        if name in basemaps.keys():
            basemap = basemaps[name]
            if basemap["type"] in ["xyz", "normal", "grau"]:
                layer = ipyleaflet.TileLayer(
                    url=basemap["url"],
                    name=basemap["name"],
                    max_zoom=24,
                    attribution=basemap["attribution"],
                )
            elif basemap["type"] == "wms":
                layer = ipyleaflet.WMSLayer(
                    url=basemap["url"],
                    layers=basemap["layers"],
                    name=basemap["name"],
                    attribution=basemap["attribution"],
                    format=basemap["format"],
                    transparent=basemap["transparent"],
                )
            return layer
        else:
            raise ValueError(
                "Basemap must be a string. Please choose from: "
                + str(list(basemaps.keys()))
            )
    else:
        raise ValueError(
            "Basemap must be a string. Please choose from: "
            + str(list(basemaps.keys()))
        )

get_bounds(geometry, north_up=True, transform=None)

Bounding box of a GeoJSON geometry, GeometryCollection, or FeatureCollection. left, bottom, right, top not xmin, ymin, xmax, ymax If not north_up, y will be switched to guarantee the above. Source code adapted from https://github.com/mapbox/rasterio/blob/master/rasterio/features.py#L361

Parameters:

Name	Type	Description	Default
geometry	dict	A GeoJSON dict.	required
north_up	bool	. Defaults to True.	True
transform	[type]	. Defaults to None.	None

Returns:

Name	Type	Description
list		A list of coordinates representing [left, bottom, right, top]

Source code in geemap/common.py

def get_bounds(geometry, north_up=True, transform=None):
    """Bounding box of a GeoJSON geometry, GeometryCollection, or FeatureCollection.
    left, bottom, right, top
    *not* xmin, ymin, xmax, ymax
    If not north_up, y will be switched to guarantee the above.
    Source code adapted from https://github.com/mapbox/rasterio/blob/master/rasterio/features.py#L361

    Args:
        geometry (dict): A GeoJSON dict.
        north_up (bool, optional): . Defaults to True.
        transform ([type], optional): . Defaults to None.

    Returns:
        list: A list of coordinates representing [left, bottom, right, top]
    """

    if "bbox" in geometry:
        return tuple(geometry["bbox"])

    geometry = geometry.get("geometry") or geometry

    # geometry must be a geometry, GeometryCollection, or FeatureCollection
    if not (
        "coordinates" in geometry or "geometries" in geometry or "features" in geometry
    ):
        raise ValueError(
            "geometry must be a GeoJSON-like geometry, GeometryCollection, "
            "or FeatureCollection"
        )

    if "features" in geometry:
        # Input is a FeatureCollection
        xmins = []
        ymins = []
        xmaxs = []
        ymaxs = []
        for feature in geometry["features"]:
            xmin, ymin, xmax, ymax = get_bounds(feature["geometry"])
            xmins.append(xmin)
            ymins.append(ymin)
            xmaxs.append(xmax)
            ymaxs.append(ymax)
        if north_up:
            return min(xmins), min(ymins), max(xmaxs), max(ymaxs)
        else:
            return min(xmins), max(ymaxs), max(xmaxs), min(ymins)

    elif "geometries" in geometry:
        # Input is a geometry collection
        xmins = []
        ymins = []
        xmaxs = []
        ymaxs = []
        for geometry in geometry["geometries"]:
            xmin, ymin, xmax, ymax = get_bounds(geometry)
            xmins.append(xmin)
            ymins.append(ymin)
            xmaxs.append(xmax)
            ymaxs.append(ymax)
        if north_up:
            return min(xmins), min(ymins), max(xmaxs), max(ymaxs)
        else:
            return min(xmins), max(ymaxs), max(xmaxs), min(ymins)

    elif "coordinates" in geometry:
        # Input is a singular geometry object
        if transform is not None:
            xyz = list(explode(geometry["coordinates"]))
            xyz_px = [transform * point for point in xyz]
            xyz = tuple(zip(*xyz_px))
            return min(xyz[0]), max(xyz[1]), max(xyz[0]), min(xyz[1])
        else:
            xyz = tuple(zip(*list(explode(geometry["coordinates"]))))
            if north_up:
                return min(xyz[0]), min(xyz[1]), max(xyz[0]), max(xyz[1])
            else:
                return min(xyz[0]), max(xyz[1]), max(xyz[0]), min(xyz[1])

    # all valid inputs returned above, so whatever falls through is an error
    raise ValueError(
        "geometry must be a GeoJSON-like geometry, GeometryCollection, "
        "or FeatureCollection"
    )

get_census_dict(reset=False)

Returns a dictionary of Census data.

Parameters:

Name	Type	Description	Default
reset	bool	Reset the dictionary. Defaults to False.	False

Returns:

Name	Type	Description
dict		A dictionary of Census data.

Source code in geemap/common.py

def get_census_dict(reset=False):
    """Returns a dictionary of Census data.

    Args:
        reset (bool, optional): Reset the dictionary. Defaults to False.

    Returns:
        dict: A dictionary of Census data.
    """
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    census_data = os.path.join(pkg_dir, "data/census_data.json")

    if reset:
        try:
            from owslib.wms import WebMapService
        except ImportError:
            raise ImportError(
                'The owslib package must be installed to use this function. Install with "pip install owslib"'
            )

        census_dict = {}

        names = [
            "Current",
            "ACS 2021",
            "ACS 2019",
            "ACS 2018",
            "ACS 2017",
            "ACS 2016",
            "ACS 2015",
            "ACS 2014",
            "ACS 2013",
            "ACS 2012",
            "ECON 2012",
            "Census 2020",
            "Census 2010",
            "Physical Features",
            "Decennial Census 2020",
            "Decennial Census 2010",
            "Decennial Census 2000",
            "Decennial Physical Features",
        ]

        links = {}

        print("Retrieving data. Please wait ...")
        for name in names:
            if "Decennial" not in name:
                links[name] = (
                    f"https://tigerweb.geo.census.gov/arcgis/services/TIGERweb/tigerWMS_{name.replace(' ', '')}/MapServer/WMSServer"
                )
            else:
                links[name] = (
                    f"https://tigerweb.geo.census.gov/arcgis/services/Census2020/tigerWMS_{name.replace('Decennial', '').replace(' ', '')}/MapServer/WMSServer"
                )

            wms = WebMapService(links[name], timeout=300)
            layers = list(wms.contents)
            layers.sort()
            census_dict[name] = {
                "url": links[name],
                "layers": layers,
                # "title": wms.identification.title,
                # "abstract": wms.identification.abstract,
            }

        with open(census_data, "w") as f:
            json.dump(census_dict, f, indent=4)

    else:
        with open(census_data, "r") as f:
            census_dict = json.load(f)

    return census_dict

get_center(geometry, north_up=True, transform=None)

Get the centroid of a GeoJSON.

Parameters:

Name	Type	Description	Default
geometry	dict	A GeoJSON dict.	required
north_up	bool	. Defaults to True.	True
transform	[type]	. Defaults to None.	None

Returns:

Name	Type	Description
list		[lon, lat]

Source code in geemap/common.py

def get_center(geometry, north_up=True, transform=None):
    """Get the centroid of a GeoJSON.

    Args:
        geometry (dict): A GeoJSON dict.
        north_up (bool, optional): . Defaults to True.
        transform ([type], optional): . Defaults to None.

    Returns:
        list: [lon, lat]
    """
    bounds = get_bounds(geometry, north_up, transform)
    center = ((bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2)  # (lat, lon)
    return center

get_current_latlon()

Get the current latitude and longitude based on the user's location.

Source code in geemap/common.py

def get_current_latlon():
    """Get the current latitude and longitude based on the user's location."""
    import geocoder

    g = geocoder.ip("me")
    props = g.geojson["features"][0]["properties"]
    lat = props["lat"]
    lon = props["lng"]
    return lat, lon

get_current_year()

Get the current year.

Returns:

Name	Type	Description
int		The current year.

Source code in geemap/common.py

def get_current_year():
    """Get the current year.

    Returns:
        int: The current year.
    """
    today = datetime.date.today()
    return today.year

get_direct_url(url)

Get the direct URL for a given URL.

Parameters:

Name	Type	Description	Default
url	str	The URL to get the direct URL for.	required

Returns:

Name	Type	Description
str		The direct URL.

Source code in geemap/common.py

def get_direct_url(url):
    """Get the direct URL for a given URL.

    Args:
        url (str): The URL to get the direct URL for.

    Returns:
        str: The direct URL.
    """

    if not isinstance(url, str):
        raise ValueError("url must be a string.")

    if not url.startswith("http"):
        raise ValueError("url must start with http.")

    r = requests.head(url, allow_redirects=True)
    return r.url

get_ee_token()

Get Earth Engine token.

Returns:

Name	Type	Description
dict		The Earth Engine token.

Source code in geemap/common.py

def get_ee_token():
    """Get Earth Engine token.

    Returns:
        dict: The Earth Engine token.
    """
    credential_file_path = os.path.expanduser("~/.config/earthengine/credentials")

    if os.path.exists(credential_file_path):
        with open(credential_file_path, "r") as f:
            credentials = json.load(f)
            return credentials
    else:
        print("Earth Engine credentials not found. Please run ee.Authenticate()")
        return None

get_env_var(key)

Retrieves an environment variable or Colab secret for the given key.

Colab secrets have precedence over environment variables.

Parameters:

Name	Type	Description	Default
key	str	The key that's used to fetch the environment variable.	required

Returns:

Type	Description
Optional[str]	Optional[str]: The retrieved key, or None if no environment variable was found.

Source code in geemap/coreutils.py

def get_env_var(key: str) -> Optional[str]:
    """Retrieves an environment variable or Colab secret for the given key.

    Colab secrets have precedence over environment variables.

    Args:
        key (str): The key that's used to fetch the environment variable.

    Returns:
        Optional[str]: The retrieved key, or None if no environment variable was found.
    """
    if not key:
        return None

    if in_colab_shell():
        from google.colab import userdata

        try:
            return userdata.get(key)
        except (userdata.SecretNotFoundError, userdata.NotebookAccessError):
            pass

    return os.environ.get(key)

get_geometry_coords(row, geom, coord_type, shape_type, mercator=False)

Returns the coordinates ('x' or 'y') of edges of a Polygon exterior.

:param: (GeoPandas Series) row : The row of each of the GeoPandas DataFrame. :param: (str) geom : The column name. :param: (str) coord_type : Whether it's 'x' or 'y' coordinate. :param: (str) shape_type

Source code in geemap/common.py

def get_geometry_coords(row, geom, coord_type, shape_type, mercator=False):
    """
    Returns the coordinates ('x' or 'y') of edges of a Polygon exterior.

    :param: (GeoPandas Series) row : The row of each of the GeoPandas DataFrame.
    :param: (str) geom : The column name.
    :param: (str) coord_type : Whether it's 'x' or 'y' coordinate.
    :param: (str) shape_type
    """

    # Parse the exterior of the coordinate
    if shape_type.lower() in ["polygon", "multipolygon"]:
        exterior = row[geom].geoms[0].exterior
        if coord_type == "x":
            # Get the x coordinates of the exterior
            coords = list(exterior.coords.xy[0])
            if mercator:
                coords = [lnglat_to_meters(x, 0)[0] for x in coords]
            return coords

        elif coord_type == "y":
            # Get the y coordinates of the exterior
            coords = list(exterior.coords.xy[1])
            if mercator:
                coords = [lnglat_to_meters(0, y)[1] for y in coords]
            return coords

    elif shape_type.lower() in ["linestring", "multilinestring"]:
        if coord_type == "x":
            coords = list(row[geom].coords.xy[0])
            if mercator:
                coords = [lnglat_to_meters(x, 0)[0] for x in coords]
            return coords
        elif coord_type == "y":
            coords = list(row[geom].coords.xy[1])
            if mercator:
                coords = [lnglat_to_meters(0, y)[1] for y in coords]
            return coords

    elif shape_type.lower() in ["point", "multipoint"]:
        exterior = row[geom]

        if coord_type == "x":
            # Get the x coordinates of the exterior
            coords = exterior.coords.xy[0][0]
            if mercator:
                coords = lnglat_to_meters(coords, 0)[0]
            return coords

        elif coord_type == "y":
            # Get the y coordinates of the exterior
            coords = exterior.coords.xy[1][0]
            if mercator:
                coords = lnglat_to_meters(0, coords)[1]
            return coords

get_google_maps_api_key(key='GOOGLE_MAPS_API_KEY')

Retrieves the Google Maps API key from the environment or Colab user data.

Parameters:

Name	Type	Description	Default
key	str	The name of the environment variable or Colab user data key where the API key is stored. Defaults to 'GOOGLE_MAPS_API_KEY'.	'GOOGLE_MAPS_API_KEY'

Returns:

Name	Type	Description
str	Optional[str]	The API key, or None if it could not be found.

Source code in geemap/coreutils.py

def get_google_maps_api_key(key: str = "GOOGLE_MAPS_API_KEY") -> Optional[str]:
    """
    Retrieves the Google Maps API key from the environment or Colab user data.

    Args:
        key (str, optional): The name of the environment variable or Colab user
            data key where the API key is stored. Defaults to
            'GOOGLE_MAPS_API_KEY'.

    Returns:
        str: The API key, or None if it could not be found.
    """
    if api_key := get_env_var(key):
        return api_key
    return os.environ.get(key, None)

get_image_collection_thumbnails(ee_object, out_dir, vis_params, dimensions=500, region=None, format='jpg', names=None, verbose=True, timeout=300, proxies=None)

Download thumbnails for all images in an ImageCollection.

Parameters:

Name	Type	Description	Default
ee_object	object	The ee.ImageCollection instance.	required
out_dir	[str	The output directory to store thumbnails.	required
vis_params	dict	The visualization parameters.	required
dimensions	int	(a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 500.	500
region	object	Geospatial region of the image to render, it may be an ee.Geometry, GeoJSON, or an array of lat/lon points (E,S,W,N). If not set the default is the bounds image. Defaults to None.	None
format	str	Either 'png' or 'jpg'. Default to 'jpg'.	'jpg'
names	list	The list of output file names. Defaults to None.	None
verbose	bool	Whether or not to print hints. Defaults to True.	True
timeout	int	The number of seconds after which the request will be terminated. Defaults to 300.	300
proxies	dict	A dictionary of proxy servers to use for the request. Defaults to None.	None

Source code in geemap/common.py

def get_image_collection_thumbnails(
    ee_object,
    out_dir,
    vis_params,
    dimensions=500,
    region=None,
    format="jpg",
    names=None,
    verbose=True,
    timeout=300,
    proxies=None,
):
    """Download thumbnails for all images in an ImageCollection.

    Args:
        ee_object (object): The ee.ImageCollection instance.
        out_dir ([str): The output directory to store thumbnails.
        vis_params (dict): The visualization parameters.
        dimensions (int, optional):(a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 500.
        region (object, optional): Geospatial region of the image to render, it may be an ee.Geometry, GeoJSON, or an array of lat/lon points (E,S,W,N). If not set the default is the bounds image. Defaults to None.
        format (str, optional): Either 'png' or 'jpg'. Default to 'jpg'.
        names (list, optional): The list of output file names. Defaults to None.
        verbose (bool, optional): Whether or not to print hints. Defaults to True.
        timeout (int, optional): The number of seconds after which the request will be terminated. Defaults to 300.
        proxies (dict, optional): A dictionary of proxy servers to use for the request. Defaults to None.
    """
    if not isinstance(ee_object, ee.ImageCollection):
        print("The ee_object must be an ee.ImageCollection.")
        raise TypeError("The ee_object must be an ee.Image.")

    if format not in ["png", "jpg"]:
        raise ValueError("The output image format must be png or jpg.")

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    try:
        count = int(ee_object.size().getInfo())
        if verbose:
            print(f"Total number of images: {count}\n")

        if (names is not None) and (len(names) != count):
            print("The number of names is not equal to the number of images.")
            return

        if names is None:
            names = ee_object.aggregate_array("system:index").getInfo()

        images = ee_object.toList(count)

        for i in range(0, count):
            image = ee.Image(images.get(i))
            name = str(names[i])
            ext = os.path.splitext(name)[1][1:]
            if ext != format:
                name = name + "." + format
            out_img = os.path.join(out_dir, name)
            if verbose:
                print(f"Downloading {i+1}/{count}: {name} ...")

            get_image_thumbnail(
                image,
                out_img,
                vis_params,
                dimensions,
                region,
                format,
                timeout=timeout,
                proxies=proxies,
            )

    except Exception as e:
        print(e)

get_image_thumbnail(ee_object, out_img, vis_params, dimensions=500, region=None, format='jpg', crs='EPSG:3857', timeout=300, proxies=None)

Download a thumbnail for an ee.Image.

Parameters:

Name	Type	Description	Default
ee_object	object	The ee.Image instance.	required
out_img	str	The output file path to the png thumbnail.	required
vis_params	dict	The visualization parameters.	required
dimensions	int	(a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 500.	500
region	object	Geospatial region of the image to render, it may be an ee.Geometry, GeoJSON, or an array of lat/lon points (E,S,W,N). If not set the default is the bounds image. Defaults to None.	None
format	str	Either 'png' or 'jpg'. Default to 'jpg'.	'jpg'
timeout	int	The number of seconds after which the request will be terminated. Defaults to 300.	300
proxies	dict	A dictionary of proxy servers to use for the request. Defaults to None.	None

Source code in geemap/common.py

def get_image_thumbnail(
    ee_object,
    out_img,
    vis_params,
    dimensions=500,
    region=None,
    format="jpg",
    crs="EPSG:3857",
    timeout=300,
    proxies=None,
):
    """Download a thumbnail for an ee.Image.

    Args:
        ee_object (object): The ee.Image instance.
        out_img (str): The output file path to the png thumbnail.
        vis_params (dict): The visualization parameters.
        dimensions (int, optional):(a number or pair of numbers in format WIDTHxHEIGHT) Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 500.
        region (object, optional): Geospatial region of the image to render, it may be an ee.Geometry, GeoJSON, or an array of lat/lon points (E,S,W,N). If not set the default is the bounds image. Defaults to None.
        format (str, optional): Either 'png' or 'jpg'. Default to 'jpg'.
        timeout (int, optional): The number of seconds after which the request will be terminated. Defaults to 300.
        proxies (dict, optional): A dictionary of proxy servers to use for the request. Defaults to None.
    """

    if not isinstance(ee_object, ee.Image):
        raise TypeError("The ee_object must be an ee.Image.")

    ext = os.path.splitext(out_img)[1][1:]
    if ext not in ["png", "jpg"]:
        raise ValueError("The output image format must be png or jpg.")
    else:
        format = ext

    out_image = os.path.abspath(out_img)
    out_dir = os.path.dirname(out_image)
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if region is not None:
        vis_params["region"] = region

    vis_params["dimensions"] = dimensions
    vis_params["format"] = format
    vis_params["crs"] = crs
    url = ee_object.getThumbURL(vis_params)

    try:
        r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)
    except Exception as e:
        print("An error occurred while downloading.")
        print(e)

    if r.status_code != 200:
        print("An error occurred while downloading.")
        print(r.json()["error"]["message"])

    else:
        with open(out_img, "wb") as fd:
            for chunk in r.iter_content(chunk_size=1024):
                fd.write(chunk)

get_info(ee_object, layer_name='', opened=False, return_node=False)

Print out the information for an Earth Engine object using a tree structure. The source code was adapted from https://github.com/google/earthengine-jupyter. Credits to Tyler Erickson.

Parameters:

Name	Type	Description	Default
ee_object	Union[FeatureCollection, Image, Geometry, Feature]	The Earth Engine object.	required
layer_name	str	The name of the layer. Defaults to "".	''
opened	bool	Whether to expand the tree. Defaults to False.	False
return_node	bool	Whether to return the widget as ipytree.Node. If False, returns the widget as ipytree.Tree. Defaults to False.	False

Returns:

Type	Description
Union[Node, Tree, None]	Union[Node, Tree, None]: The tree or node representing the Earth Engine object information.

Source code in geemap/coreutils.py

def get_info(
    ee_object: Union[ee.FeatureCollection, ee.Image, ee.Geometry, ee.Feature],
    layer_name: str = "",
    opened: bool = False,
    return_node: bool = False,
) -> Union[Node, Tree, None]:
    """Print out the information for an Earth Engine object using a tree structure.
    The source code was adapted from https://github.com/google/earthengine-jupyter.
    Credits to Tyler Erickson.

    Args:
        ee_object (Union[ee.FeatureCollection, ee.Image, ee.Geometry, ee.Feature]):
            The Earth Engine object.
        layer_name (str, optional): The name of the layer. Defaults to "".
        opened (bool, optional): Whether to expand the tree. Defaults to False.
        return_node (bool, optional): Whether to return the widget as ipytree.Node.
            If False, returns the widget as ipytree.Tree. Defaults to False.

    Returns:
        Union[Node, Tree, None]: The tree or node representing the Earth Engine
            object information.
    """

    tree_json = build_computed_object_tree(ee_object, layer_name, opened)

    def _create_node(data):
        """Create a widget for the computed object tree."""
        node = Node(data.get("label", "Node"), opened=data.get("expanded", False))
        if children := data.get("children"):
            for child in children:
                node.add_node(_create_node(child))
        else:
            node.icon = "file"
            node.value = str(data)  # Store the entire data as a string
        return node

    root_node = _create_node(tree_json)
    if return_node:
        return root_node
    else:
        tree = Tree()
        tree.add_node(root_node)
        return tree

get_js_examples(out_dir=None)

Gets Earth Engine JavaScript examples from the geemap package.

Parameters:

Name	Type	Description	Default
out_dir	str	The folder to copy the JavaScript examples to. Defaults to None.	None

Returns:

Name	Type	Description
str		The folder containing the JavaScript examples.

Source code in geemap/conversion.py

def get_js_examples(out_dir=None):
    """Gets Earth Engine JavaScript examples from the geemap package.

    Args:
        out_dir (str, optional): The folder to copy the JavaScript examples to. Defaults to None.

    Returns:
        str: The folder containing the JavaScript examples.
    """
    pkg_dir = Path(__file__).parent
    example_dir = pkg_dir / "data"
    js_dir = example_dir / "javascripts"

    files = list(js_dir.rglob("*.js"))
    if out_dir is None:
        out_dir = js_dir
    else:
        out_dir.mkdir(parent=True, exist_ok=True)

        for file in files:
            out_path = out_dir / file.name
            shutil.copyfile(file, out_path)

    return out_dir

get_local_tile_layer(source, port='default', debug=False, indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, attribution=None, tile_format='ipyleaflet', layer_name='Local COG', return_client=False, quiet=False, **kwargs)

Generate an ipyleaflet/folium TileLayer from a local raster dataset or remote Cloud Optimized GeoTIFF (COG). If you are using this function in JupyterHub on a remote server and the raster does not render properly, try running the following two lines before calling this function:

import os
os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = 'proxy/{port}'

Parameters:

Name	Type	Description	Default
source	str	The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.	required
port	str	The port to use for the server. Defaults to "default".	'default'
debug	bool	If True, the server will be started in debug mode. Defaults to False.	False
indexes	int	The band(s) to use. Band indexing starts at 1. Defaults to None.	None
colormap	str	The name of the colormap from matplotlib to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.	None
vmin	float	The minimum value to use when colormapping the colormap when plotting a single band. Defaults to None.	None
vmax	float	The maximum value to use when colormapping the colormap when plotting a single band. Defaults to None.	None
nodata	float	The value from the band to use to interpret as not valid data. Defaults to None.	None
attribution	str	Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.	None
tile_format	str	The tile layer format. Can be either ipyleaflet or folium. Defaults to "ipyleaflet".	'ipyleaflet'
layer_name	str	The layer name to use. Defaults to None.	'Local COG'
return_client	bool	If True, the tile client will be returned. Defaults to False.	False
quiet	bool	If True, the error messages will be suppressed. Defaults to False.	False

Returns:

Type	Description
	ipyleaflet.TileLayer | folium.TileLayer: An ipyleaflet.TileLayer or folium.TileLayer.

Source code in geemap/common.py

def get_local_tile_layer(
    source,
    port="default",
    debug=False,
    indexes=None,
    colormap=None,
    vmin=None,
    vmax=None,
    nodata=None,
    attribution=None,
    tile_format="ipyleaflet",
    layer_name="Local COG",
    return_client=False,
    quiet=False,
    **kwargs,
):
    """Generate an ipyleaflet/folium TileLayer from a local raster dataset or remote Cloud Optimized GeoTIFF (COG).
        If you are using this function in JupyterHub on a remote server and the raster does not render properly, try
        running the following two lines before calling this function:

        import os
        os.environ['LOCALTILESERVER_CLIENT_PREFIX'] = 'proxy/{port}'

    Args:
        source (str): The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
        port (str, optional): The port to use for the server. Defaults to "default".
        debug (bool, optional): If True, the server will be started in debug mode. Defaults to False.
        indexes (int, optional): The band(s) to use. Band indexing starts at 1. Defaults to None.
        colormap (str, optional): The name of the colormap from `matplotlib` to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.
        vmin (float, optional): The minimum value to use when colormapping the colormap when plotting a single band. Defaults to None.
        vmax (float, optional): The maximum value to use when colormapping the colormap when plotting a single band. Defaults to None.
        nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
        attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
        tile_format (str, optional): The tile layer format. Can be either ipyleaflet or folium. Defaults to "ipyleaflet".
        layer_name (str, optional): The layer name to use. Defaults to None.
        return_client (bool, optional): If True, the tile client will be returned. Defaults to False.
        quiet (bool, optional): If True, the error messages will be suppressed. Defaults to False.

    Returns:
        ipyleaflet.TileLayer | folium.TileLayer: An ipyleaflet.TileLayer or folium.TileLayer.
    """
    import rasterio

    check_package(
        "localtileserver", URL="https://github.com/banesullivan/localtileserver"
    )

    # Handle legacy localtileserver kwargs
    if "cmap" in kwargs:
        warnings.warn(
            "`cmap` is a deprecated keyword argument for get_local_tile_layer. Please use `colormap`."
        )
    if "palette" in kwargs:
        warnings.warn(
            "`palette` is a deprecated keyword argument for get_local_tile_layer. Please use `colormap`."
        )
    if "band" in kwargs or "bands" in kwargs:
        warnings.warn(
            "`band` and `bands` are deprecated keyword arguments for get_local_tile_layer. Please use `indexes`."
        )
    if "projection" in kwargs:
        warnings.warn(
            "`projection` is a deprecated keyword argument for get_local_tile_layer and will be ignored."
        )
    if "style" in kwargs:
        warnings.warn(
            "`style` is a deprecated keyword argument for get_local_tile_layer and will be ignored."
        )

    if "max_zoom" not in kwargs:
        kwargs["max_zoom"] = 30
    if "max_native_zoom" not in kwargs:
        kwargs["max_native_zoom"] = 30
    if "cmap" in kwargs:
        colormap = kwargs.pop("cmap")
    if "palette" in kwargs:
        colormap = kwargs.pop("palette")
    if "band" in kwargs:
        indexes = kwargs.pop("band")
    if "bands" in kwargs:
        indexes = kwargs.pop("bands")

    # Make it compatible with binder and JupyterHub
    if os.environ.get("JUPYTERHUB_SERVICE_PREFIX") is not None:
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = (
            f"{os.environ['JUPYTERHUB_SERVICE_PREFIX'].lstrip('/')}/proxy/{{port}}"
        )

    if is_studio_lab():
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = (
            f"studiolab/default/jupyter/proxy/{{port}}"
        )
    elif is_on_aws():
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = "proxy/{port}"
    elif "prefix" in kwargs:
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = kwargs["prefix"]
        kwargs.pop("prefix")

    from localtileserver import (
        get_leaflet_tile_layer,
        get_folium_tile_layer,
        TileClient,
    )

    # if "show_loading" not in kwargs:
    #     kwargs["show_loading"] = False

    if isinstance(source, str):
        if not source.startswith("http"):
            if source.startswith("~"):
                source = os.path.expanduser(source)
            # else:
            #     source = os.path.abspath(source)
            # if not os.path.exists(source):
            #     raise ValueError("The source path does not exist.")
        else:
            source = github_raw_url(source)
    elif isinstance(source, TileClient) or isinstance(
        source, rasterio.io.DatasetReader
    ):
        pass

    else:
        raise ValueError("The source must either be a string or TileClient")

    if tile_format not in ["ipyleaflet", "folium"]:
        raise ValueError("The tile format must be either ipyleaflet or folium.")

    if layer_name is None:
        if source.startswith("http"):
            layer_name = "RemoteTile_" + random_string(3)
        else:
            layer_name = "LocalTile_" + random_string(3)

    if isinstance(source, str) or isinstance(source, rasterio.io.DatasetReader):
        tile_client = TileClient(source, port=port, debug=debug)
    else:
        tile_client = source

    if quiet:
        output = widgets.Output()
        with output:
            if tile_format == "ipyleaflet":
                tile_layer = get_leaflet_tile_layer(
                    tile_client,
                    port=port,
                    debug=debug,
                    indexes=indexes,
                    colormap=colormap,
                    vmin=vmin,
                    vmax=vmax,
                    nodata=nodata,
                    attribution=attribution,
                    name=layer_name,
                    **kwargs,
                )
            else:
                tile_layer = get_folium_tile_layer(
                    tile_client,
                    port=port,
                    debug=debug,
                    indexes=indexes,
                    colormap=colormap,
                    vmin=vmin,
                    vmax=vmax,
                    nodata=nodata,
                    attr=attribution,
                    overlay=True,
                    name=layer_name,
                    **kwargs,
                )
    else:
        if tile_format == "ipyleaflet":
            tile_layer = get_leaflet_tile_layer(
                tile_client,
                port=port,
                debug=debug,
                indexes=indexes,
                colormap=colormap,
                vmin=vmin,
                vmax=vmax,
                nodata=nodata,
                attribution=attribution,
                name=layer_name,
                **kwargs,
            )
        else:
            tile_layer = get_folium_tile_layer(
                tile_client,
                port=port,
                debug=debug,
                indexes=indexes,
                colormap=colormap,
                vmin=vmin,
                vmax=vmax,
                nodata=nodata,
                attr=attribution,
                overlay=True,
                name=layer_name,
                **kwargs,
            )

    if return_client:
        return tile_layer, tile_client
    else:
        return tile_layer

get_nb_template(download_latest=False, out_file=None)

Get the Earth Engine Jupyter notebook template.

Parameters:

Name	Type	Description	Default
download_latest	bool	If True, downloads the latest notebook template from GitHub. Defaults to False.	False
out_file	str	Set the output file path of the notebook template. Defaults to None.	None

Returns:

Name	Type	Description
str		The file path of the template.

Source code in geemap/conversion.py

def get_nb_template(download_latest=False, out_file=None):
    """Get the Earth Engine Jupyter notebook template.

    Args:
        download_latest (bool, optional): If True, downloads the latest notebook template from GitHub. Defaults to False.
        out_file (str, optional): Set the output file path of the notebook template. Defaults to None.

    Returns:
        str: The file path of the template.
    """
    pkg_dir = Path(__file__).parent
    example_dir = pkg_dir / "data"
    template_dir = example_dir / "template"
    template_file = template_dir / "template.py"

    if out_file is None:
        out_file = template_file
        return out_file

    out_file = out_file.with_suffix(".py")
    outfile.parent.mkdir(parents=True, exist_ok=True)

    if download_latest:
        template_url = "https://raw.githubusercontent.com/gee-community/geemap/master/examples/template/template.py"
        print(f"Downloading the latest notebook template from {template_url}")
        urllib.request.urlretrieve(template_url, out_file)
    elif out_file is not None:
        shutil.copyfile(template_file, out_file)

    return out_file

get_palettable(types=None)

Get a list of palettable color palettes.

Parameters:

Name	Type	Description	Default
types	list	A list of palettable types to return, e.g., types=['matplotlib', 'cartocolors']. Defaults to None.	None

Returns:

Name	Type	Description
list		A list of palettable color palettes.

Source code in geemap/common.py

def get_palettable(types=None):
    """Get a list of palettable color palettes.

    Args:
        types (list, optional): A list of palettable types to return, e.g., types=['matplotlib', 'cartocolors']. Defaults to None.

    Returns:
        list: A list of palettable color palettes.
    """
    try:
        import palettable
    except ImportError:
        raise ImportError(
            "The palettable package is not installed. Please install it with `pip install palettable`."
        )

    if types is not None and (not isinstance(types, list)):
        raise ValueError("The types must be a list.")

    allowed_palettes = [
        "cartocolors",
        "cmocean",
        "colorbrewer",
        "cubehelix",
        "lightbartlein",
        "matplotlib",
        "mycarta",
        "scientific",
        "tableau",
        "wesanderson",
    ]

    if types is None:
        types = allowed_palettes[:]

    if all(x in allowed_palettes for x in types):
        pass
    else:
        raise ValueError(
            "The types must be one of the following: " + ", ".join(allowed_palettes)
        )

    palettes = []

    if "cartocolors" in types:
        cartocolors_diverging = [
            f"cartocolors.diverging.{c}"
            for c in dir(palettable.cartocolors.diverging)[:-19]
        ]
        cartocolors_qualitative = [
            f"cartocolors.qualitative.{c}"
            for c in dir(palettable.cartocolors.qualitative)[:-19]
        ]
        cartocolors_sequential = [
            f"cartocolors.sequential.{c}"
            for c in dir(palettable.cartocolors.sequential)[:-41]
        ]

        palettes = (
            palettes
            + cartocolors_diverging
            + cartocolors_qualitative
            + cartocolors_sequential
        )

    if "cmocean" in types:
        cmocean_diverging = [
            f"cmocean.diverging.{c}" for c in dir(palettable.cmocean.diverging)[:-19]
        ]
        cmocean_sequential = [
            f"cmocean.sequential.{c}" for c in dir(palettable.cmocean.sequential)[:-19]
        ]

        palettes = palettes + cmocean_diverging + cmocean_sequential

    if "colorbrewer" in types:
        colorbrewer_diverging = [
            f"colorbrewer.diverging.{c}"
            for c in dir(palettable.colorbrewer.diverging)[:-19]
        ]
        colorbrewer_qualitative = [
            f"colorbrewer.qualitative.{c}"
            for c in dir(palettable.colorbrewer.qualitative)[:-19]
        ]
        colorbrewer_sequential = [
            f"colorbrewer.sequential.{c}"
            for c in dir(palettable.colorbrewer.sequential)[:-41]
        ]

        palettes = (
            palettes
            + colorbrewer_diverging
            + colorbrewer_qualitative
            + colorbrewer_sequential
        )

    if "cubehelix" in types:
        cubehelix = [
            "classic_16",
            "cubehelix1_16",
            "cubehelix2_16",
            "cubehelix3_16",
            "jim_special_16",
            "perceptual_rainbow_16",
            "purple_16",
            "red_16",
        ]
        cubehelix = [f"cubehelix.{c}" for c in cubehelix]
        palettes = palettes + cubehelix

    if "lightbartlein" in types:
        lightbartlein_diverging = [
            f"lightbartlein.diverging.{c}"
            for c in dir(palettable.lightbartlein.diverging)[:-19]
        ]
        lightbartlein_sequential = [
            f"lightbartlein.sequential.{c}"
            for c in dir(palettable.lightbartlein.sequential)[:-19]
        ]

        palettes = palettes + lightbartlein_diverging + lightbartlein_sequential

    if "matplotlib" in types:
        matplotlib_colors = [
            f"matplotlib.{c}" for c in dir(palettable.matplotlib)[:-16]
        ]
        palettes = palettes + matplotlib_colors

    if "mycarta" in types:
        mycarta = [f"mycarta.{c}" for c in dir(palettable.mycarta)[:-16]]
        palettes = palettes + mycarta

    if "scientific" in types:
        scientific_diverging = [
            f"scientific.diverging.{c}"
            for c in dir(palettable.scientific.diverging)[:-19]
        ]
        scientific_sequential = [
            f"scientific.sequential.{c}"
            for c in dir(palettable.scientific.sequential)[:-19]
        ]

        palettes = palettes + scientific_diverging + scientific_sequential

    if "tableau" in types:
        tableau = [f"tableau.{c}" for c in dir(palettable.tableau)[:-14]]
        palettes = palettes + tableau

    return palettes

get_palette_colors(cmap_name=None, n_class=None, hashtag=False)

Get a palette from a matplotlib colormap. See the list of colormaps at https://matplotlib.org/stable/tutorials/colors/colormaps.html.

Parameters:

Name	Type	Description	Default
cmap_name	str	The name of the matplotlib colormap. Defaults to None.	None
n_class	int	The number of colors. Defaults to None.	None
hashtag	bool	Whether to return a list of hex colors. Defaults to False.	False

Returns:

Name	Type	Description
list		A list of hex colors.

Source code in geemap/common.py

def get_palette_colors(cmap_name=None, n_class=None, hashtag=False):
    """Get a palette from a matplotlib colormap. See the list of colormaps at https://matplotlib.org/stable/tutorials/colors/colormaps.html.

    Args:
        cmap_name (str, optional): The name of the matplotlib colormap. Defaults to None.
        n_class (int, optional): The number of colors. Defaults to None.
        hashtag (bool, optional): Whether to return a list of hex colors. Defaults to False.

    Returns:
        list: A list of hex colors.
    """
    import matplotlib as mpl
    import matplotlib.pyplot as plt

    try:
        cmap = plt.get_cmap(cmap_name, n_class)
    except:
        cmap = plt.cm.get_cmap(cmap_name, n_class)
    colors = [mpl.colors.rgb2hex(cmap(i))[1:] for i in range(cmap.N)]
    if hashtag:
        colors = ["#" + i for i in colors]
    return colors

get_temp_dir()

Returns the temporary directory.

Returns:

Name	Type	Description
str		The temporary directory.

Source code in geemap/common.py

def get_temp_dir():
    """Returns the temporary directory.

    Returns:
        str: The temporary directory.
    """

    import tempfile

    return tempfile.gettempdir()

get_wms_layers(url, return_titles=False)

Returns a list of WMS layers from a WMS service.

Parameters:

Name	Type	Description	Default
url	str	The URL of the WMS service.	required
return_titles	bool	If True, the titles of the layers will be returned. Defaults to False.	False

Returns:

Name	Type	Description
list		A list of WMS layers.

Source code in geemap/common.py

def get_wms_layers(url, return_titles=False):
    """Returns a list of WMS layers from a WMS service.

    Args:
        url (str): The URL of the WMS service.
        return_titles (bool, optional): If True, the titles of the layers will be returned. Defaults to False.

    Returns:
        list: A list of WMS layers.
    """
    from owslib.wms import WebMapService

    wms = WebMapService(url)
    layers = list(wms.contents)
    layers.sort()
    if return_titles:
        return layers, [wms[layer].title for layer in layers]
    else:
        return layers

gif_fading(in_gif, out_gif, duration=1, verbose=True)

Fade in/out the gif.

Parameters:

Name	Type	Description	Default
in_gif	str	The input gif file. Can be a directory path or http URL, e.g., "https://i.imgur.com/ZWSZC5z.gif"	required
out_gif	str	The output gif file.	required
duration	float	The duration of the fading. Defaults to 1.	1
verbose	bool	Whether to print the progress. Defaults to True.	True

Raises:

Type	Description
FileNotFoundError	Raise exception when the input gif does not exist.
Exception	Raise exception when ffmpeg is not installed.

Source code in geemap/timelapse.py

def gif_fading(in_gif, out_gif, duration=1, verbose=True):
    """Fade in/out the gif.

    Args:
        in_gif (str): The input gif file. Can be a directory path or http URL, e.g., "https://i.imgur.com/ZWSZC5z.gif"
        out_gif (str): The output gif file.
        duration (float, optional): The duration of the fading. Defaults to 1.
        verbose (bool, optional): Whether to print the progress. Defaults to True.

    Raises:
        FileNotFoundError: Raise exception when the input gif does not exist.
        Exception: Raise exception when ffmpeg is not installed.
    """
    import glob
    import tempfile

    current_dir = os.getcwd()

    if isinstance(in_gif, str) and in_gif.startswith("http"):
        ext = os.path.splitext(in_gif)[1]
        file_path = temp_file_path(ext)
        download_from_url(in_gif, file_path, verbose=verbose)
        in_gif = file_path

    in_gif = os.path.abspath(in_gif)
    if not in_gif.endswith(".gif"):
        raise Exception("in_gif must be a gif file.")

    if " " in in_gif:
        raise Exception("The filename cannot contain spaces.")

    out_gif = os.path.abspath(out_gif)
    if not os.path.exists(os.path.dirname(out_gif)):
        os.makedirs(os.path.dirname(out_gif))

    if not os.path.exists(in_gif):
        raise FileNotFoundError(f"{in_gif} does not exist.")

    basename = os.path.basename(in_gif).replace(".gif", "")
    temp_dir = os.path.join(tempfile.gettempdir(), basename)
    if os.path.exists(temp_dir):
        shutil.rmtree(temp_dir)

    gif_to_png(in_gif, temp_dir, verbose=verbose)

    os.chdir(temp_dir)

    images = list(glob.glob(os.path.join(temp_dir, "*.png")))
    count = len(images)

    files = []
    for i in range(1, count + 1):
        files.append(f"-loop 1 -t {duration} -i {i}.png")
    inputs = " ".join(files)

    filters = []
    for i in range(1, count):
        if i == 1:
            filters.append(
                f"\"[1:v][0:v]blend=all_expr='A*(if(gte(T,3),1,T/3))+B*(1-(if(gte(T,3),1,T/3)))'[v0];"
            )
        else:
            filters.append(
                f"[{i}:v][{i-1}:v]blend=all_expr='A*(if(gte(T,3),1,T/3))+B*(1-(if(gte(T,3),1,T/3)))'[v{i-1}];"
            )

    last_filter = ""
    for i in range(count - 1):
        last_filter += f"[v{i}]"
    last_filter += f'concat=n={count-1}:v=1:a=0[v]" -map "[v]"'
    filters.append(last_filter)
    filters = " ".join(filters)

    cmd = f"ffmpeg -y -loglevel error {inputs} -filter_complex {filters} {out_gif}"

    # if fade >= duration:
    #     duration = fade + 1

    # files = []
    # for i in range(1, count + 1):
    #     files.append(f"-framerate {framerate} -loop 1 -t {duration} -i {i}.png")

    # inputs = " ".join(files)

    # filters = []
    # for i in range(count):
    #     if i == 0:
    #         filters.append(f'"[0:v]fade=t=out:st=4:d={fade}[v0];')
    #     else:
    #         filters.append(
    #             f"[{i}:v]fade=t=in:st=0:d={fade},fade=t=out:st=4:d={fade}[v{i}];"
    #         )

    # last_filter = ""
    # for i in range(count):
    #     last_filter += f"[v{i}]"
    # last_filter += f"concat=n={count}:v=1:a=0,split[v0][v1];"
    # filters.append(last_filter)
    # palette = f'[v0]palettegen[p];[v1][p]paletteuse[v]" -map "[v]"'
    # filters.append(palette)
    # filters = " ".join(filters)

    # cmd = f"ffmpeg -y {inputs} -filter_complex {filters} {out_gif}"

    os.system(cmd)
    try:
        shutil.rmtree(temp_dir)
    except Exception as e:
        print(e)

    os.chdir(current_dir)

gif_to_mp4(in_gif, out_mp4)

Converts a gif to mp4.

Parameters:

Name	Type	Description	Default
in_gif	str	The input gif file.	required
out_mp4	str	The output mp4 file.	required

Source code in geemap/timelapse.py

def gif_to_mp4(in_gif, out_mp4):
    """Converts a gif to mp4.

    Args:
        in_gif (str): The input gif file.
        out_mp4 (str): The output mp4 file.
    """
    from PIL import Image

    if not os.path.exists(in_gif):
        raise FileNotFoundError(f"{in_gif} does not exist.")

    out_mp4 = os.path.abspath(out_mp4)
    if not out_mp4.endswith(".mp4"):
        out_mp4 = out_mp4 + ".mp4"

    if not os.path.exists(os.path.dirname(out_mp4)):
        os.makedirs(os.path.dirname(out_mp4))

    if not is_tool("ffmpeg"):
        print("ffmpeg is not installed on your computer.")
        return

    width, height = Image.open(in_gif).size

    if width % 2 == 0 and height % 2 == 0:
        cmd = f"ffmpeg -loglevel error -i {in_gif} -vcodec libx264 -crf 25 -pix_fmt yuv420p {out_mp4}"
        os.system(cmd)
    else:
        width += width % 2
        height += height % 2
        cmd = f"ffmpeg -loglevel error -i {in_gif} -vf scale={width}:{height} -vcodec libx264 -crf 25 -pix_fmt yuv420p {out_mp4}"
        os.system(cmd)

    if not os.path.exists(out_mp4):
        raise Exception(f"Failed to create mp4 file.")

gif_to_png(in_gif, out_dir=None, prefix='', verbose=True)

Converts a gif to png.

Parameters:

Name	Type	Description	Default
in_gif	str	The input gif file.	required
out_dir	str	The output directory. Defaults to None.	None
prefix	str	The prefix of the output png files. Defaults to None.	''
verbose	bool	Whether to print the progress. Defaults to True.	True

Raises:

Type	Description
FileNotFoundError	Raise exception when the input gif does not exist.
Exception	Raise exception when ffmpeg is not installed.

Source code in geemap/timelapse.py

def gif_to_png(in_gif, out_dir=None, prefix="", verbose=True):
    """Converts a gif to png.

    Args:
        in_gif (str): The input gif file.
        out_dir (str, optional): The output directory. Defaults to None.
        prefix (str, optional): The prefix of the output png files. Defaults to None.
        verbose (bool, optional): Whether to print the progress. Defaults to True.

    Raises:
        FileNotFoundError: Raise exception when the input gif does not exist.
        Exception: Raise exception when ffmpeg is not installed.
    """
    import tempfile

    in_gif = os.path.abspath(in_gif)
    if " " in in_gif:
        raise Exception("in_gif cannot contain spaces.")
    if not os.path.exists(in_gif):
        raise FileNotFoundError(f"{in_gif} does not exist.")

    basename = os.path.basename(in_gif).replace(".gif", "")
    if out_dir is None:
        out_dir = os.path.join(tempfile.gettempdir(), basename)
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)
    elif isinstance(out_dir, str) and not os.path.exists(out_dir):
        os.makedirs(out_dir)
    elif not isinstance(out_dir, str):
        raise Exception("out_dir must be a string.")

    out_dir = os.path.abspath(out_dir)
    cmd = f"ffmpeg -loglevel error -i {in_gif} -vsync 0 {out_dir}/{prefix}%d.png"
    os.system(cmd)

    if verbose:
        print(f"Images are saved to {out_dir}")

github_raw_url(url)

Get the raw URL for a GitHub file.

Parameters:

Name	Type	Description	Default
url	str	The GitHub URL.	required

Returns:

Name	Type	Description
str	str	The raw URL.

Source code in geemap/coreutils.py

def github_raw_url(url: str) -> str:
    """Get the raw URL for a GitHub file.

    Args:
        url (str): The GitHub URL.

    Returns:
        str: The raw URL.
    """
    if isinstance(url, str) and url.startswith("https://github.com/") and "blob" in url:
        url = url.replace("github.com", "raw.githubusercontent.com").replace(
            "blob/", "", 1
        )
    return url

goes_fire_timelapse(roi=None, out_gif=None, start_date='2020-09-05T15:00', end_date='2020-09-06T02:00', data='GOES-17', scan='full_disk', dimensions=768, framesPerSecond=10, date_format='YYYY-MM-dd HH:mm', xy=('3%', '3%'), text_sequence=None, font_type='arial.ttf', font_size=20, font_color='#ffffff', add_progress_bar=True, progress_bar_color='white', progress_bar_height=5, loop=0, crs=None, overlay_data=None, overlay_color='#000000', overlay_width=1, overlay_opacity=1.0, mp4=False, fading=False, **kwargs)

Create a timelapse of GOES fire data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/8a083a7fb13b95ad4ba148ed9b65475e. Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

Parameters:

Name	Type	Description	Default
out_gif	str	The file path to save the gif.	None
start_date	str	The start date of the time series. Defaults to "2021-10-24T14:00:00".	'2020-09-05T15:00'
end_date	str	The end date of the time series. Defaults to "2021-10-25T01:00:00".	'2020-09-06T02:00'
data	str	The GOES satellite data to use. Defaults to "GOES-17".	'GOES-17'
scan	str	The GOES scan to use. Defaults to "full_disk".	'full_disk'
region	Geometry	The region of interest. Defaults to None.	required
dimensions	int	a number or pair of numbers (in format 'WIDTHxHEIGHT') Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.	768
frames_per_second	int	Animation speed. Defaults to 10.	required
date_format	str	The date format to use. Defaults to "YYYY-MM-dd HH:mm".	'YYYY-MM-dd HH:mm'
xy	tuple	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	('3%', '3%')
text_sequence	(int, str, list)	Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.	None
font_type	str	Font type. Defaults to "arial.ttf".	'arial.ttf'
font_size	int	Font size. Defaults to 20.	20
font_color	str	Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff'). Defaults to '#000000'.	'#ffffff'
add_progress_bar	bool	Whether to add a progress bar at the bottom of the GIF. Defaults to True.	True
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'white'
progress_bar_height	int	Height of the progress bar. Defaults to 5.	5
loop	int	controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.	0
crs	str	The coordinate reference system to use, e.g., "EPSG:3857". Defaults to None.	None
overlay_data	(int, str, list)	Administrative boundary to be drawn on the timelapse. Defaults to None.	None
overlay_color	str	Color for the overlay data. Can be any color name or hex color code. Defaults to 'black'.	'#000000'
overlay_width	int	Width of the overlay. Defaults to 1.	1
overlay_opacity	float	Opacity of the overlay. Defaults to 1.0.	1.0
mp4	bool	Whether to convert the GIF to MP4. Defaults to False.	False
fading	int | bool	If True, add fading effect to the timelapse. Defaults to False, no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).	False

Raises:

Type	Description
Exception	Raise exception.

Source code in geemap/timelapse.py

def goes_fire_timelapse(
    roi=None,
    out_gif=None,
    start_date="2020-09-05T15:00",
    end_date="2020-09-06T02:00",
    data="GOES-17",
    scan="full_disk",
    dimensions=768,
    framesPerSecond=10,
    date_format="YYYY-MM-dd HH:mm",
    xy=("3%", "3%"),
    text_sequence=None,
    font_type="arial.ttf",
    font_size=20,
    font_color="#ffffff",
    add_progress_bar=True,
    progress_bar_color="white",
    progress_bar_height=5,
    loop=0,
    crs=None,
    overlay_data=None,
    overlay_color="#000000",
    overlay_width=1,
    overlay_opacity=1.0,
    mp4=False,
    fading=False,
    **kwargs,
):
    """Create a timelapse of GOES fire data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/8a083a7fb13b95ad4ba148ed9b65475e.
    Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

    Args:
        out_gif (str): The file path to save the gif.
        start_date (str, optional): The start date of the time series. Defaults to "2021-10-24T14:00:00".
        end_date (str, optional): The end date of the time series. Defaults to "2021-10-25T01:00:00".
        data (str, optional): The GOES satellite data to use. Defaults to "GOES-17".
        scan (str, optional): The GOES scan to use. Defaults to "full_disk".
        region (ee.Geometry, optional): The region of interest. Defaults to None.
        dimensions (int, optional): a number or pair of numbers (in format 'WIDTHxHEIGHT') Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.
        frames_per_second (int, optional): Animation speed. Defaults to 10.
        date_format (str, optional): The date format to use. Defaults to "YYYY-MM-dd HH:mm".
        xy (tuple, optional): Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.
        font_type (str, optional): Font type. Defaults to "arial.ttf".
        font_size (int, optional): Font size. Defaults to 20.
        font_color (str, optional): Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff').  Defaults to '#000000'.
        add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF. Defaults to True.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
        loop (int, optional): controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.
        crs (str, optional): The coordinate reference system to use, e.g., "EPSG:3857". Defaults to None.
        overlay_data (int, str, list, optional): Administrative boundary to be drawn on the timelapse. Defaults to None.
        overlay_color (str, optional): Color for the overlay data. Can be any color name or hex color code. Defaults to 'black'.
        overlay_width (int, optional): Width of the overlay. Defaults to 1.
        overlay_opacity (float, optional): Opacity of the overlay. Defaults to 1.0.
        mp4 (bool, optional): Whether to convert the GIF to MP4. Defaults to False.
        fading (int | bool, optional): If True, add fading effect to the timelapse. Defaults to False, no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).

    Raises:
        Exception: Raise exception.
    """

    try:
        if "region" in kwargs:
            roi = kwargs["region"]

        if out_gif is None:
            out_gif = os.path.abspath(f"goes_fire_{random_string(3)}.gif")

        if roi is None:
            roi = ee.Geometry.BBox(-123.17, 36.56, -118.22, 40.03)

        col = goes_fire_timeseries(start_date, end_date, data, scan, roi)
        if overlay_data is not None:
            col = add_overlay(
                col, overlay_data, overlay_color, overlay_width, overlay_opacity
            )

        # visParams = {
        #     "bands": ["CMI_C02", "CMI_GREEN", "CMI_C01"],
        #     "min": 0,
        #     "max": 0.8,
        #     "dimensions": dimensions,
        #     "framesPerSecond": framesPerSecond,
        #     "region": region,
        #     "crs": col.first().projection(),
        # }

        if crs is None:
            crs = col.first().projection()

        cmiFdcVisParams = {
            "dimensions": dimensions,
            "framesPerSecond": framesPerSecond,
            "region": roi,
            "crs": crs,
        }

        if text_sequence is None:
            text_sequence = image_dates(col, date_format=date_format).getInfo()

        download_ee_video(col, cmiFdcVisParams, out_gif)

        if os.path.exists(out_gif):
            add_text_to_gif(
                out_gif,
                out_gif,
                xy,
                text_sequence,
                font_type,
                font_size,
                font_color,
                add_progress_bar,
                progress_bar_color,
                progress_bar_height,
                duration=1000 / framesPerSecond,
                loop=loop,
            )

            try:
                reduce_gif_size(out_gif)
                if isinstance(fading, bool):
                    fading = int(fading)
                if fading > 0:
                    gif_fading(out_gif, out_gif, duration=fading, verbose=False)

            except Exception as _:
                pass

            if mp4:
                out_mp4 = out_gif.replace(".gif", ".mp4")
                gif_to_mp4(out_gif, out_mp4)

            return out_gif

    except Exception as e:
        raise Exception(e)

goes_fire_timeseries(start_date='2020-09-05T15:00', end_date='2020-09-06T02:00', data='GOES-17', scan='full_disk', region=None, merge=True)

Create a time series of GOES Fire data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/8a083a7fb13b95ad4ba148ed9b65475e. Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

Parameters:

Name	Type	Description	Default
start_date	str	The start date of the time series. Defaults to "2020-09-05T15:00".	'2020-09-05T15:00'
end_date	str	The end date of the time series. Defaults to "2020-09-06T02:00".	'2020-09-06T02:00'
data	str	The GOES satellite data to use. Defaults to "GOES-17".	'GOES-17'
scan	str	The GOES scan to use. Defaults to "full_disk".	'full_disk'
region	Geometry	The region of interest. Defaults to None.	None
merge	bool	Whether to merge the fire timeseries with GOES CMI timeseries. Defaults to True.	True

Raises:

Type	Description
ValueError	The data must be either GOES-16 or GOES-17.
ValueError	The scan must be either full_disk or conus.

Returns:

Type	Description
	ee.ImageCollection: GOES fire timeseries.

Source code in geemap/timelapse.py

def goes_fire_timeseries(
    start_date="2020-09-05T15:00",
    end_date="2020-09-06T02:00",
    data="GOES-17",
    scan="full_disk",
    region=None,
    merge=True,
):
    """Create a time series of GOES Fire data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/8a083a7fb13b95ad4ba148ed9b65475e.
    Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

    Args:
        start_date (str, optional): The start date of the time series. Defaults to "2020-09-05T15:00".
        end_date (str, optional): The end date of the time series. Defaults to "2020-09-06T02:00".
        data (str, optional): The GOES satellite data to use. Defaults to "GOES-17".
        scan (str, optional): The GOES scan to use. Defaults to "full_disk".
        region (ee.Geometry, optional): The region of interest. Defaults to None.
        merge (bool, optional): Whether to merge the fire timeseries with GOES CMI timeseries. Defaults to True.

    Raises:
        ValueError: The data must be either GOES-16 or GOES-17.
        ValueError: The scan must be either full_disk or conus.

    Returns:
        ee.ImageCollection: GOES fire timeseries.
    """

    if data not in ["GOES-16", "GOES-17"]:
        raise ValueError("The data must be either GOES-16 or GOES-17.")

    if scan.lower() not in ["full_disk", "conus"]:
        raise ValueError("The scan must be either full_disk or conus.")

    scan_types = {
        "full_disk": "FDCF",
        "conus": "FDCC",
    }

    if region is None:
        region = ee.Geometry.BBox(-123.17, 36.56, -118.22, 40.03)

    # Get the fire/hotspot characterization dataset.
    col = ee.ImageCollection(f"NOAA/GOES/{data[-2:]}/{scan_types[scan.lower()]}")
    fdcCol = col.filterDate(start_date, end_date)

    # Identify fire-detected pixels of medium to high confidence.
    fireMaskCodes = [10, 30, 11, 31, 12, 32, 13, 33, 14, 34, 15, 35]
    confVals = [1.0, 1.0, 0.9, 0.9, 0.8, 0.8, 0.5, 0.5, 0.3, 0.3, 0.1, 0.1]
    defaultConfVal = 0

    def fdcVis(img):
        confImg = img.remap(fireMaskCodes, confVals, defaultConfVal, "Mask")
        return (
            confImg.gte(0.3)
            .selfMask()
            .set("system:time_start", img.get("system:time_start"))
        )

    fdcVisCol = fdcCol.map(fdcVis)
    if not merge:
        return fdcVisCol
    else:
        geosVisCol = goes_timeseries(start_date, end_date, data, scan, region)
        # Join the fire collection to the CMI collection.
        joinFilter = ee.Filter.equals(
            **{"leftField": "system:time_start", "rightField": "system:time_start"}
        )
        joinedCol = ee.Join.saveFirst("match").apply(geosVisCol, fdcVisCol, joinFilter)

        def overlayVis(img):
            cmi = ee.Image(img).visualize(
                **{
                    "bands": ["CMI_C02", "CMI_GREEN", "CMI_C01"],
                    "min": 0,
                    "max": 0.8,
                    "gamma": 0.8,
                }
            )
            fdc = ee.Image(img.get("match")).visualize(
                **{"palette": ["ff5349"], "min": 0, "max": 1, "opacity": 0.7}
            )
            return cmi.blend(fdc).set("system:time_start", img.get("system:time_start"))

        cmiFdcVisCol = ee.ImageCollection(joinedCol.map(overlayVis))
        return cmiFdcVisCol

goes_timelapse(roi=None, out_gif=None, start_date='2021-10-24T14:00:00', end_date='2021-10-25T01:00:00', data='GOES-17', scan='full_disk', bands=['CMI_C02', 'CMI_GREEN', 'CMI_C01'], dimensions=768, framesPerSecond=10, date_format='YYYY-MM-dd HH:mm', xy=('3%', '3%'), text_sequence=None, font_type='arial.ttf', font_size=20, font_color='#ffffff', add_progress_bar=True, progress_bar_color='white', progress_bar_height=5, loop=0, crs=None, overlay_data=None, overlay_color='black', overlay_width=1, overlay_opacity=1.0, mp4=False, fading=False, **kwargs)

Create a timelapse of GOES data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/57245f2d3d04233765c42fb5ef19c1f4. Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

Parameters:

Name	Type	Description	Default
roi	Geometry	The region of interest. Defaults to None.	None
out_gif	str	The file path to save the gif.	None
start_date	str	The start date of the time series. Defaults to "2021-10-24T14:00:00".	'2021-10-24T14:00:00'
end_date	str	The end date of the time series. Defaults to "2021-10-25T01:00:00".	'2021-10-25T01:00:00'
data	str	The GOES satellite data to use. Defaults to "GOES-17".	'GOES-17'
scan	str	The GOES scan to use. Defaults to "full_disk".	'full_disk'
bands	list	The bands to visualize. Defaults to ["CMI_C02", "CMI_GREEN", "CMI_C01"].	['CMI_C02', 'CMI_GREEN', 'CMI_C01']
dimensions	int	a number or pair of numbers (in format 'WIDTHxHEIGHT') Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.	768
frames_per_second	int	Animation speed. Defaults to 10.	required
date_format	str	The date format to use. Defaults to "YYYY-MM-dd HH:mm".	'YYYY-MM-dd HH:mm'
xy	tuple	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	('3%', '3%')
text_sequence	(int, str, list)	Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.	None
font_type	str	Font type. Defaults to "arial.ttf".	'arial.ttf'
font_size	int	Font size. Defaults to 20.	20
font_color	str	Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff'). Defaults to '#000000'.	'#ffffff'
add_progress_bar	bool	Whether to add a progress bar at the bottom of the GIF. Defaults to True.	True
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'white'
progress_bar_height	int	Height of the progress bar. Defaults to 5. loop (int, optional): controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.	5
crs	str	The coordinate reference system to use, e.g., "EPSG:3857". Defaults to None.	None
overlay_data	(int, str, list)	Administrative boundary to be drawn on the timelapse. Defaults to None.	None
overlay_color	str	Color for the overlay data. Can be any color name or hex color code. Defaults to 'black'.	'black'
overlay_width	int	Line width of the overlay. Defaults to 1.	1
overlay_opacity	float	Opacity of the overlay. Defaults to 1.0.	1.0
mp4	bool	Whether to save the animation as an mp4 file. Defaults to False.	False
fading	int | bool	If True, add fading effect to the timelapse. Defaults to False, no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).	False

Source code in geemap/timelapse.py

def goes_timelapse(
    roi=None,
    out_gif=None,
    start_date="2021-10-24T14:00:00",
    end_date="2021-10-25T01:00:00",
    data="GOES-17",
    scan="full_disk",
    bands=["CMI_C02", "CMI_GREEN", "CMI_C01"],
    dimensions=768,
    framesPerSecond=10,
    date_format="YYYY-MM-dd HH:mm",
    xy=("3%", "3%"),
    text_sequence=None,
    font_type="arial.ttf",
    font_size=20,
    font_color="#ffffff",
    add_progress_bar=True,
    progress_bar_color="white",
    progress_bar_height=5,
    loop=0,
    crs=None,
    overlay_data=None,
    overlay_color="black",
    overlay_width=1,
    overlay_opacity=1.0,
    mp4=False,
    fading=False,
    **kwargs,
):
    """Create a timelapse of GOES data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/57245f2d3d04233765c42fb5ef19c1f4.
    Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

    Args:
        roi (ee.Geometry, optional): The region of interest. Defaults to None.
        out_gif (str): The file path to save the gif.
        start_date (str, optional): The start date of the time series. Defaults to "2021-10-24T14:00:00".
        end_date (str, optional): The end date of the time series. Defaults to "2021-10-25T01:00:00".
        data (str, optional): The GOES satellite data to use. Defaults to "GOES-17".
        scan (str, optional): The GOES scan to use. Defaults to "full_disk".
        bands (list, optional): The bands to visualize. Defaults to ["CMI_C02", "CMI_GREEN", "CMI_C01"].
        dimensions (int, optional): a number or pair of numbers (in format 'WIDTHxHEIGHT') Maximum dimensions of the thumbnail to render, in pixels. If only one number is passed, it is used as the maximum, and the other dimension is computed by proportional scaling. Defaults to 768.
        frames_per_second (int, optional): Animation speed. Defaults to 10.
        date_format (str, optional): The date format to use. Defaults to "YYYY-MM-dd HH:mm".
        xy (tuple, optional): Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.
        font_type (str, optional): Font type. Defaults to "arial.ttf".
        font_size (int, optional): Font size. Defaults to 20.
        font_color (str, optional): Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff').  Defaults to '#000000'.
        add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF. Defaults to True.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.        loop (int, optional): controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.
        crs (str, optional): The coordinate reference system to use, e.g., "EPSG:3857". Defaults to None.
        overlay_data (int, str, list, optional): Administrative boundary to be drawn on the timelapse. Defaults to None.
        overlay_color (str, optional): Color for the overlay data. Can be any color name or hex color code. Defaults to 'black'.
        overlay_width (int, optional): Line width of the overlay. Defaults to 1.
        overlay_opacity (float, optional): Opacity of the overlay. Defaults to 1.0.
        mp4 (bool, optional): Whether to save the animation as an mp4 file. Defaults to False.
        fading (int | bool, optional): If True, add fading effect to the timelapse. Defaults to False, no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).
    Raises:
        Exception: Raise exception.
    """

    try:
        if "region" in kwargs:
            roi = kwargs["region"]

        if out_gif is None:
            out_gif = os.path.abspath(f"goes_{random_string(3)}.gif")

        visParams = {
            "bands": bands,
            "min": 0,
            "max": 0.8,
        }
        col = goes_timeseries(start_date, end_date, data, scan, roi)
        col = col.select(bands).map(
            lambda img: img.visualize(**visParams).set(
                {
                    "system:time_start": img.get("system:time_start"),
                }
            )
        )
        if overlay_data is not None:
            col = add_overlay(
                col, overlay_data, overlay_color, overlay_width, overlay_opacity
            )

        if roi is None:
            roi = ee.Geometry.Polygon(
                [
                    [
                        [-159.5954, 60.4088],
                        [-159.5954, 24.5178],
                        [-114.2438, 24.5178],
                        [-114.2438, 60.4088],
                    ]
                ],
                None,
                False,
            )

        if crs is None:
            crs = col.first().projection()

        videoParams = {
            "bands": ["vis-red", "vis-green", "vis-blue"],
            "min": 0,
            "max": 255,
            "dimensions": dimensions,
            "framesPerSecond": framesPerSecond,
            "region": roi,
            "crs": crs,
        }

        if text_sequence is None:
            text_sequence = image_dates(col, date_format=date_format).getInfo()

        download_ee_video(col, videoParams, out_gif)

        if os.path.exists(out_gif):
            add_text_to_gif(
                out_gif,
                out_gif,
                xy,
                text_sequence,
                font_type,
                font_size,
                font_color,
                add_progress_bar,
                progress_bar_color,
                progress_bar_height,
                duration=1000 / framesPerSecond,
                loop=loop,
            )

            try:
                reduce_gif_size(out_gif)

                if isinstance(fading, bool):
                    fading = int(fading)
                if fading > 0:
                    gif_fading(out_gif, out_gif, duration=fading, verbose=False)

            except Exception as _:
                pass

            if mp4:
                out_mp4 = out_gif.replace(".gif", ".mp4")
                gif_to_mp4(out_gif, out_mp4)

            return out_gif

    except Exception as e:
        raise Exception(e)

goes_timeseries(start_date='2021-10-24T14:00:00', end_date='2021-10-25T01:00:00', data='GOES-17', scan='full_disk', region=None, show_night=[False, 'a_mode'])

Create a time series of GOES data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/57245f2d3d04233765c42fb5ef19c1f4. Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

Parameters:

Name	Type	Description	Default
start_date	str	The start date of the time series. Defaults to "2021-10-24T14:00:00".	'2021-10-24T14:00:00'
end_date	str	The end date of the time series. Defaults to "2021-10-25T01:00:00".	'2021-10-25T01:00:00'
data	str	The GOES satellite data to use. Defaults to "GOES-17".	'GOES-17'
scan	str	The GOES scan to use. Defaults to "full_disk".	'full_disk'
region	Geometry	The region of interest. Defaults to None.	None
show_night	list	Show the clouds at night through [True, "a_mode"] o [True, "b_mode"]. Defaults to [False, "a_mode"]	[False, 'a_mode']

Returns:

Type	Description
	ee.ImageCollection: GOES timeseries.

Source code in geemap/timelapse.py

def goes_timeseries(
    start_date="2021-10-24T14:00:00",
    end_date="2021-10-25T01:00:00",
    data="GOES-17",
    scan="full_disk",
    region=None,
    show_night=[False, "a_mode"],
):
    """Create a time series of GOES data. The code is adapted from Justin Braaten's code: https://code.earthengine.google.com/57245f2d3d04233765c42fb5ef19c1f4.
    Credits to Justin Braaten. See also https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

    Args:
        start_date (str, optional): The start date of the time series. Defaults to "2021-10-24T14:00:00".
        end_date (str, optional): The end date of the time series. Defaults to "2021-10-25T01:00:00".
        data (str, optional): The GOES satellite data to use. Defaults to "GOES-17".
        scan (str, optional): The GOES scan to use. Defaults to "full_disk".
        region (ee.Geometry, optional): The region of interest. Defaults to None.
        show_night (list, optional): Show the clouds at night through [True, "a_mode"] o [True, "b_mode"].  Defaults to [False, "a_mode"]
    Raises:
        ValueError: The data must be either GOES-16 or GOES-17.
        ValueError: The scan must be either full_disk, conus, or mesoscale.

    Returns:
        ee.ImageCollection: GOES timeseries.
    """

    if data not in ["GOES-16", "GOES-17"]:
        raise ValueError("The data must be either GOES-16 or GOES-17.")

    if scan.lower() not in ["full_disk", "conus", "mesoscale"]:
        raise ValueError("The scan must be either full_disk, conus, or mesoscale.")

    scan_types = {
        "full_disk": "MCMIPF",
        "conus": "MCMIPC",
        "mesoscale": "MCMIPM",
    }

    col = ee.ImageCollection(f"NOAA/GOES/{data[-2:]}/{scan_types[scan.lower()]}")

    if region is None:
        region = ee.Geometry.Polygon(
            [
                [
                    [-159.5954379282731, 60.40883060191719],
                    [-159.5954379282731, 24.517881970830725],
                    [-114.2438754282731, 24.517881970830725],
                    [-114.2438754282731, 60.40883060191719],
                ]
            ],
            None,
            False,
        )

    # Applies scaling factors.
    def applyScaleAndOffset(img):
        def getFactorImg(factorNames):
            factorList = img.toDictionary().select(factorNames).values()
            return ee.Image.constant(factorList)

        scaleImg = getFactorImg(["CMI_C.._scale"])
        offsetImg = getFactorImg(["CMI_C.._offset"])
        scaled = img.select("CMI_C..").multiply(scaleImg).add(offsetImg)
        return img.addBands(**{"srcImg": scaled, "overwrite": True})

    # Adds a synthetic green band.
    def addGreenBand(img):
        green = img.expression(
            "CMI_GREEN = 0.45 * red + 0.10 * nir + 0.45 * blue",
            {
                "blue": img.select("CMI_C01"),
                "red": img.select("CMI_C02"),
                "nir": img.select("CMI_C03"),
            },
        )
        return img.addBands(green)

    # Show at clouds at night (a-mode)
    def showNighta(img):
        # Make normalized infrared
        IR_n = img.select("CMI_C13").unitScale(ee.Number(90), ee.Number(313))
        IR_n = IR_n.expression(
            "ir_p = (1 -IR_n)/1.4",
            {
                "IR_n": IR_n.select("CMI_C13"),
            },
        )

        # Add infrared to rgb bands
        R_ir = img.select("CMI_C02").max(IR_n)
        G_ir = img.select("CMI_GREEN").max(IR_n)
        B_ir = img.select("CMI_C01").max(IR_n)

        return img.addBands([R_ir, G_ir, B_ir], overwrite=True)

    # Show at clouds at night (b-mode)
    def showNightb(img):
        night = img.select("CMI_C03").unitScale(0, 0.016).subtract(1).multiply(-1)

        cmi11 = img.select("CMI_C11").unitScale(100, 310)
        cmi13 = img.select("CMI_C13").unitScale(100, 300)
        cmi15 = img.select("CMI_C15").unitScale(100, 310)
        iNight = cmi15.addBands([cmi13, cmi11]).clamp(0, 1).subtract(1).multiply(-1)

        iRGBNight = iNight.visualize(**{"min": 0, "max": 1, "gamma": 1.4}).updateMask(
            night
        )

        iRGB = img.visualize(
            **{
                "bands": ["CMI_C02", "CMI_C03", "CMI_C01"],
                "min": 0.15,
                "max": 1,
                "gamma": 1.4,
            }
        )
        return iRGB.blend(iRGBNight).set(
            "system:time_start", img.get("system:time_start")
        )

    # Scales select bands for visualization.
    def scaleForVis(img):
        return (
            img.select(["CMI_C01", "CMI_GREEN", "CMI_C02", "CMI_C03", "CMI_C05"])
            .resample("bicubic")
            .log10()
            .interpolate([-1.6, 0.176], [0, 1], "clamp")
            .unmask(0)
            .set("system:time_start", img.get("system:time_start"))
        )

    # Wraps previous functions.
    def processForVis(img):
        if show_night[0]:
            if show_night[1] == "a_mode":
                return scaleForVis(showNighta(addGreenBand(applyScaleAndOffset(img))))

            else:
                return showNightb(applyScaleAndOffset(img))

        else:
            return scaleForVis(addGreenBand(applyScaleAndOffset(img)))

    return col.filterDate(start_date, end_date).filterBounds(region).map(processForVis)

has_transparency(img)

Checks whether an image has transparency.

Parameters:

Name	Type	Description	Default
img	object	a PIL Image object.	required

Returns:

Name	Type	Description
bool		True if it has transparency, False otherwise.

Source code in geemap/common.py

2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041