foliumap module¶

Module for creating interactive maps with the folium library.

`CustomControl` ¶

Bases: MacroElement

Put any HTML on the map as a Leaflet Control.

Adopted from https://github.com/python-visualization/folium/pull/1662

Source code in geemap/foliumap.py

class CustomControl(MacroElement):
    """Put any HTML on the map as a Leaflet Control.

    Adopted from https://github.com/python-visualization/folium/pull/1662
    """

    _template = Template("""
        {% macro script(this, kwargs) %}
        L.Control.CustomControl = L.Control.extend({
            onAdd: function(map) {
                let div = L.DomUtil.create('div');
                div.innerHTML = `{{ this.html }}`;
                return div;
            },
            onRemove: function(map) {
                // Nothing to do here
            }
        });
        L.control.customControl = function(opts) {
            return new L.Control.CustomControl(opts);
        }
        L.control.customControl(
            { position: "{{ this.position }}" }
        ).addTo({{ this._parent.get_name() }});
        {% endmacro %}
    """)

    def __init__(self, html, position: str = "bottomleft"):
        def escape_backticks(text: str) -> str:
            """Escape backticks so text can be used in a JS template."""
            return re.sub(r"(?<!\\)`", r"\`", text)

        super().__init__()
        self.html = escape_backticks(html)
        self.position = position

`init(html, position='bottomleft')` ¶

Source code in geemap/foliumap.py

def __init__(self, html, position: str = "bottomleft"):
    def escape_backticks(text: str) -> str:
        """Escape backticks so text can be used in a JS template."""
        return re.sub(r"(?<!\\)`", r"\`", text)

    super().__init__()
    self.html = escape_backticks(html)
    self.position = position

`FloatText` ¶

Bases: MacroElement

Adds a floating image in HTML canvas on top of the map.

Source code in geemap/foliumap.py

class FloatText(MacroElement):
    """Adds a floating image in HTML canvas on top of the map."""

    _template = Template("""
            {% macro header(this,kwargs) %}
                <style>
                    #{{this.get_name()}} {
                        position:absolute;
                        bottom:{{this.bottom}}%;
                        left:{{this.left}}%;
                        }
                </style>
            {% endmacro %}

            {% macro html(this, kwargs) %}

            <!doctype html>
            <html lang="en">
            <head>
            </head>
            <body>

            <div id='{{this.get_name()}}' class='{{this.get_name()}}'
                style='position: absolute; z-index:9999; border:2px solid grey; background-color:rgba(255, 255, 255, 0.8);
                border-radius:5px; padding: 5px; font-size:14px; '>

            <div class='text'>{{this.text}}</div>
            </div>

            </body>
            </html>

            <style type='text/css'>
            .{{this.get_name()}} .text {
                text-align: left;
                margin-bottom: 0px;
                font-size: 90%;
                float: left;
                }
            </style>
            {% endmacro %}
            """)

    def __init__(self, text, bottom=75, left=75):
        super().__init__()
        self._name = "FloatText"
        self.text = text
        self.bottom = bottom
        self.left = left

`Map` ¶

Bases: Map

The Map class inherits from folium.Map.

By default, the Map will use OpenStreetMap as the basemap.

Source code in geemap/foliumap.py

class Map(folium.Map):
    """The Map class inherits from folium.Map.

    By default, the Map will use OpenStreetMap as the basemap.
    """

    def __init__(self, **kwargs):
        logging.getLogger("googleapiclient.discovery_cache").setLevel(logging.ERROR)

        if "ee_initialize" not in kwargs.keys():
            kwargs["ee_initialize"] = True

        if kwargs["ee_initialize"]:
            coreutils.ee_initialize()

        # Default map center location and zoom level.
        latlon = [20, 0]
        zoom = 2

        # Interchangeable parameters between ipyleaflet and folium.
        if "center" in kwargs.keys():
            kwargs["location"] = kwargs["center"]
            kwargs.pop("center")
        if "location" in kwargs.keys():
            latlon = kwargs["location"]
        else:
            kwargs["location"] = latlon

        if "zoom" in kwargs.keys():
            kwargs["zoom_start"] = kwargs["zoom"]
            kwargs.pop("zoom")
        if "zoom_start" in kwargs.keys():
            zoom = kwargs["zoom_start"]
        else:
            kwargs["zoom_start"] = zoom
        if "max_zoom" not in kwargs.keys():
            kwargs["max_zoom"] = 30

        if "add_google_map" not in kwargs.keys() and "basemap" not in kwargs.keys():
            kwargs["add_google_map"] = False
        if "plugin_LatLngPopup" not in kwargs.keys():
            kwargs["plugin_LatLngPopup"] = False
        if "plugin_Fullscreen" not in kwargs.keys():
            kwargs["plugin_Fullscreen"] = True
        if "plugin_Draw" not in kwargs.keys():
            kwargs["plugin_Draw"] = True
        if "Draw_export" not in kwargs.keys():
            kwargs["Draw_export"] = False
        if "plugin_MiniMap" not in kwargs.keys():
            kwargs["plugin_MiniMap"] = False
        if "locate_control" not in kwargs:
            kwargs["locate_control"] = False
        if "search_control" not in kwargs:
            kwargs["search_control"] = True
        if "scale_control" in kwargs:
            kwargs["scale"] = kwargs["scale_control"]
            kwargs.pop("scale_control")

        if (
            "width" in kwargs
            and isinstance(kwargs["width"], str)
            and ("%" not in kwargs["width"])
        ):
            kwargs["width"] = float(kwargs["width"].replace("px", ""))

        height = None
        width = None

        if "height" in kwargs:
            height = kwargs.pop("height")
        else:
            height = 600

        if "width" in kwargs:
            width = kwargs.pop("width")
        else:
            width = "100%"

        if "tiles" not in kwargs:
            kwargs["tiles"] = None
            if "basemap" not in kwargs:
                kwargs["basemap"] = "OpenStreetMap"

        super().__init__(**kwargs)
        self.baseclass = "folium"

        # The list of Earth Engine Geometry objects converted from geojson.
        self.draw_features = []
        # The Earth Engine Geometry object converted from the last drawn feature.
        self.draw_last_feature = None
        self.draw_layer = None
        self.user_roi = None
        self.user_rois = None
        self.search_locations = None
        self.search_loc_marker = None
        self.search_loc_geom = None

        if (height is not None) or (width is not None):
            f = folium.Figure(width=width, height=height)
            self.add_to(f)

        if kwargs.get("add_google_map"):
            basemaps["ROADMAP"].add_to(self)
        if kwargs.get("basemap"):
            basemaps[kwargs.get("basemap")].add_to(self)
        if kwargs.get("plugin_LatLngPopup"):
            folium.LatLngPopup().add_to(self)
        if kwargs.get("plugin_Fullscreen"):
            plugins.Fullscreen().add_to(self)
        if kwargs.get("plugin_Draw"):
            plugins.Draw(export=kwargs.get("Draw_export")).add_to(self)
        if kwargs.get("plugin_MiniMap"):
            plugins.MiniMap().add_to(self)
        if kwargs.get("plugin_LayerControl"):
            folium.LayerControl().add_to(self)
        if kwargs["locate_control"]:
            plugins.LocateControl().add_to(self)
        if kwargs["search_control"]:
            plugins.Geocoder(collapsed=True, position="topleft").add_to(self)

        if "plugin_LayerControl" not in kwargs:
            self.options["layersControl"] = True
        else:
            self.options["layersControl"] = kwargs["plugin_LayerControl"]

        self.fit_bounds([latlon, latlon], max_zoom=zoom)

    def setOptions(
        self,
        mapTypeId: str = "HYBRID",
        styles: dict[str, Any] | None = None,
        types: dict[str, Any] | None = None,
    ):
        """Adds Google basemap to the map.

        Args:
            mapTypeId: 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.
            styles ([type], optional): A dictionary of custom MapTypeStyle objects keyed
                with a name that will appear in the map's Map Type Controls. Defaults to
                None.
            types ([type], optional): A list of mapTypeIds to make available. If
                omitted, but opt_styles is specified, appends all of the style keys to
                the standard Google Maps API map types. Defaults to None.
        """
        styles = styles or {}
        types = types or {}

        try:
            basemaps[mapTypeId].add_to(self)
        except Exception:
            raise Exception(
                "Basemap can only be one of the following: {}".format(
                    ", ".join(basemaps.keys())
                )
            )

    set_options = setOptions

    def add_basemap(self, basemap: str = "HYBRID", show: bool = True, **kwargs):
        """Adds a basemap to the map.

        Args:
            basemap: Can be one of string from ee_basemaps.
        """
        import xyzservices

        try:
            map_dict = {
                "ROADMAP": "Esri.WorldStreetMap",
                "SATELLITE": "Esri.WorldImagery",
                "TERRAIN": "Esri.WorldTopoMap",
                "HYBRID": "Esri.WorldImagery",
            }

            if isinstance(basemap, str):
                if basemap.upper() in map_dict:
                    if basemap in os.environ:
                        if "name" in kwargs:
                            kwargs["name"] = basemap
                        basemap = os.environ[basemap]
                        self.add_tile_layer(tiles=basemap, **kwargs)

                    else:
                        basemap = basemap.upper()
                        basemaps[basemap].add_to(self)

                elif 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 = 22
                    layer = folium.TileLayer(
                        tiles=url,
                        attr=attribution,
                        name=name,
                        max_zoom=max_zoom,
                        overlay=True,
                        control=True,
                        show=show,
                        **kwargs,
                    )

                    self.add_layer(layer)

                    arc_add_layer(url, name)

                elif basemap in basemaps:
                    bmap = basemaps[basemap]
                    bmap.show = show
                    bmap.add_to(self)
                    if isinstance(basemaps[basemap], folium.TileLayer):
                        url = basemaps[basemap].tiles
                    elif isinstance(basemaps[basemap], folium.WmsTileLayer):
                        url = basemaps[basemap].url
                    arc_add_layer(url, basemap)
                else:
                    print(
                        "Basemap can only be one of the following: {}".format(
                            ", ".join(basemaps.keys())
                        )
                    )

        except Exception:
            raise Exception(
                "Basemap can only be one of the following: {}".format(
                    ", ".join(basemaps.keys())
                )
            )

    def add_layer(
        self,
        ee_object,
        vis_params: dict[str, Any] | None = None,
        name: str = "Layer untitled",
        shown: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Adds a given EE object to the map as a layer.

        Args:
            ee_object (Collection|Feature|Image|MapId): The object to add to the map.
            vis_params: The visualization parameters. Defaults to {}.
            name: The name of the layer.
            shown: A flag indicating whether the layer should be on by default.
            opacity: The layer's opacity represented as a number between 0 and 1.
        """
        vis_params = vis_params or {}

        layer = ee_tile_layers.EEFoliumTileLayer(
            ee_object, vis_params, name, shown, opacity, **kwargs
        )
        layer.add_to(self)
        arc_add_layer(layer.url_format, name, shown, opacity)

    addLayer = add_layer

    def _repr_mimebundle_(self, **kwargs) -> None:
        """Adds Layer control to the map.

        Reference:

        https://ipython.readthedocs.io/en/stable/config/integrating.html#MyObject._repr_mimebundle_
        """
        del kwargs  # Unused.
        if self.options["layersControl"]:
            self.add_layer_control()

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

        Args:
            lon: The longitude of the center, in degrees.
            lat: The latitude of the center, in degrees.
            zoom: The zoom level, from 1 to 24.
        """
        self.fit_bounds([[lat, lon], [lat, lon]], max_zoom=zoom)

        if is_arcpy():
            arc_zoom_to_extent(lon, lat, lon, lat)

    setCenter = set_center

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

        Args:
          bounds (list | tuple): A list/tuple containing minx, miny, maxx, maxy values
            for the bounds.
        """
        # The folium 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 zoom_to_gdf(self, gdf) -> None:
        """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 center_object(
        self,
        ee_object: ee.ComputedObject,
        zoom: int | None = None,
        max_error: float = 0.001,
    ) -> None:
        """Centers the map view on a given object.

        Args:
            ee_object: An Earth Engine object to center on a geometry, image or feature.
            zoom: The zoom level, from 1 to 24.
            max_error: The maximum error for the geometry.
        """
        if isinstance(ee_object, ee.Geometry):
            geometry = ee_object.transform(maxError=max_error)
        else:
            try:
                geometry = ee_object.geometry(maxError=max_error).transform(
                    maxError=max_error
                )
            except Exception:
                raise Exception(
                    "ee_object must be an instance of one of ee.Geometry, "
                    "ee.FeatureCollection, ee.Image, or ee.ImageCollection."
                )

        if zoom is not None:
            if not isinstance(zoom, int):
                raise Exception("Zoom must be an integer.")

            centroid = geometry.centroid(maxError=max_error).getInfo()["coordinates"]
            lat = centroid[1]
            lon = centroid[0]
            self.set_center(lon, lat, zoom)

            if is_arcpy():
                arc_zoom_to_extent(lon, lat, lon, lat)

        else:
            coordinates = geometry.bounds(maxError=max_error).getInfo()["coordinates"][
                0
            ]
            x = [c[0] for c in coordinates]
            y = [c[1] for c in coordinates]
            xmin = min(x)
            xmax = max(x)
            ymin = min(y)
            ymax = max(y)
            bounds = [[ymin, xmin], [ymax, xmax]]
            self.fit_bounds(bounds)

            if is_arcpy():
                arc_zoom_to_extent(xmin, ymin, xmax, ymax)

    centerObject = center_object

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

        Args:
            layerControl: Whether to show the control that allows the user to toggle
                layers on/off.
            fullscreenControl: Whether to show the control that allows the user to make
                the map full-screen.
            latLngPopup: Whether to show the control that pops up the Lat/lon when the
                user clicks on the map.
        """
        if layerControl:
            folium.LayerControl().add_to(self)
        if fullscreenControl:
            plugins.Fullscreen().add_to(self)
        if latLngPopup:
            folium.LatLngPopup().add_to(self)

    setControlVisibility = set_control_visibility

    def add_layer_control(self):
        """Adds layer control to the map."""
        layer_ctrl = False
        for item in self.to_dict()["children"]:
            if item.startswith("layer_control"):
                layer_ctrl = True
                break
        if not layer_ctrl:
            folium.LayerControl().add_to(self)

    addLayerControl = add_layer_control

    def add_marker(
        self,
        location,
        popup: str | None = None,
        tooltip: str | None = None,
        icon: str | None = None,
        draggable: bool = False,
        **kwargs,
    ):
        """Adds a marker to the map.

        More info about marker options at

        https://python-visualization.github.io/folium/modules.html#folium.map.Marker.

        Args:
            location (list | tuple): Location of the marker in the format of [lat, lng].
            popup: The popup text.
            tooltip: The tooltip text.
            icon: The icon to use.
            draggable: Whether the marker is draggable.
        """
        if isinstance(location, list):
            location = tuple(location)
        if isinstance(location, tuple):
            folium.Marker(
                location=location,
                popup=popup,
                tooltip=tooltip,
                icon=icon,
                draggable=draggable,
                **kwargs,
            ).add_to(self)
        else:
            raise TypeError("The location must be a list or a tuple.")

    def add_wms_layer(
        self,
        url: str,
        layers: str,
        name: str | None = None,
        attribution: str | None = "",
        overlay: bool = True,
        control: bool = True,
        shown: bool = True,
        format: str = "image/png",
        transparent: bool = True,
        version: str = "1.1.1",
        styles: str = "",
        **kwargs,
    ) -> None:
        """Add a WMS layer to the map.

        Args:
            url: The URL of the WMS web service.
            layers: Comma-separated list of WMS layers to show.
            name: The layer name to use on the layer control.
            attribution: The attribution of the data layer.
            overlay: Allows overlay.
            control: Adds the layer to the layer control.
            shown: A flag indicating whether the layer should be on by default.
            format: WMS image format (use ‘image/png’ for layers with transparency).
            transparent: Whether the layer shall allow transparency.
            version: Version of the WMS service to use.
            styles: Comma-separated list of WMS styles.
        """
        try:
            folium.raster_layers.WmsTileLayer(
                url=url,
                layers=layers,
                name=name,
                attr=attribution,
                overlay=overlay,
                control=control,
                show=shown,
                styles=styles,
                fmt=format,
                transparent=transparent,
                version=version,
                **kwargs,
            ).add_to(self)
        except Exception:
            raise Exception("Failed to add the specified WMS TileLayer.")

    def add_tile_layer(
        self,
        tiles: str = "OpenStreetMap",
        name: str = "Untitled",
        attribution: str = ".",
        overlay: bool = True,
        control: bool = True,
        shown: bool = True,
        opacity: float = 1.0,
        API_key: str | None = None,
        **kwargs,
    ) -> None:
        """Add a XYZ tile layer to the map.

        Args:
            tiles: The URL of the XYZ tile service.
            name: The layer name to use on the layer control.
            attribution: The attribution of the data layer.
            overlay: Allows overlay.
            control: Adds the layer to the layer control.
            shown: A flag indicating whether the layer should be on by default.
            opacity: Sets the opacity for the layer.
            API_key: – API key for Cloudmade or Mapbox tiles.
        """

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

        try:
            folium.raster_layers.TileLayer(
                tiles=tiles,
                name=name,
                attr=attribution,
                overlay=overlay,
                control=control,
                show=shown,
                opacity=opacity,
                API_key=API_key,
                **kwargs,
            ).add_to(self)
        except Exception:
            raise Exception("Failed to add the specified TileLayer.")

    def add_cog_layer(
        self,
        url: str,
        name: str = "Untitled",
        attribution: str = ".",
        opacity: float = 1.0,
        shown: bool = True,
        bands: list[str] | None = None,
        titiler_endpoint=None,
        **kwargs,
    ) -> None:
        """Adds a COG TileLayer to the map.

        Args:
            urlThe URL of the COG tile layer.
            name: The layer name to use for the layer.
            attribution: The attribution to use.
            opacity: The opacity of the layer.
            shown: A flag indicating whether the layer should be on by default.
            bands: A list of bands to use.
            titiler_endpoint: Titiler endpoint.
                Defaults to "https://giswqs-titiler-endpoint.hf.space".
        """
        tile_url = cog_tile(url, bands, titiler_endpoint, **kwargs)
        bounds = cog_bounds(url, titiler_endpoint)
        self.add_tile_layer(
            tiles=tile_url,
            name=name,
            attribution=attribution,
            opacity=opacity,
            shown=shown,
        )
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

    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: str | None = None,
        collection: str | None = None,
        item: str | None = None,
        assets: str | list[str] | None = None,
        bands: list[str] | None = None,
        titiler_endpoint: str | None = None,
        name: str = "STAC Layer",
        # TODO: Why `.`? This does not match the doc string.
        attribution: str = ".",
        opacity: float = 1.0,
        shown: bool = True,
        **kwargs,
    ) -> None:
        """Adds a STAC TileLayer to the map.

        Args:
            url: 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: The Microsoft Planetary Computer STAC collection ID, e.g.,
                landsat-8-c2-l2.
            item: The Microsoft Planetary Computer STAC item ID, e.g.,
                LC08_L2SP_047027_20201204_02_T1.
            assets: The Microsoft Planetary Computer STAC asset ID, e.g.,
                ["SR_B7", "SR_B5", "SR_B4"].
            bands: A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]
            titiler_endpoint: Titiler endpoint, e.g.,
                "https://giswqs-titiler-endpoint.hf.space", "planetary-computer", "pc".
            name: The layer name to use for the layer.
            attribution: The attribution to use.
            opacity: The opacity of the layer.
            shown: A flag indicating whether the layer should be on by default.
        """
        tile_url = stac_tile(
            url, collection, item, assets, bands, titiler_endpoint, **kwargs
        )
        bounds = stac_bounds(url, collection, item, titiler_endpoint)
        self.add_tile_layer(
            url=tile_url,
            name=name,
            attribution=attribution,
            opacity=opacity,
            shown=shown,
        )
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

    def add_raster(
        self,
        source: str,
        indexes: int | None = None,
        colormap: str | None = None,
        vmin: float | None = None,
        vmax: float | None = None,
        nodata: float | None = None,
        attribution: str | None = None,
        layer_name: str | None = "Raster",
        array_args: dict | None = None,
        **kwargs,
    ) -> None:
        """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: The path to the GeoTIFF file or the URL of the Cloud Optimized
                GeoTIFF.
            indexes: The band(s) to use. Band indexing starts at 1.
            colormap: 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: The minimum value to use when colormapping the colormap when plotting
                a single band.
            vmax: The maximum value to use when colormapping the colormap when plotting
                a single band.
            nodata: The value from the band to use to interpret as not valid data.
            attribution: Attribution for the source raster. This defaults to a message
                about it being a local file.
            layer_name: The layer name to use.
            array_args: Additional arguments to pass to `array_to_image`.
                Defaults to {}.
        """
        array_args = array_args or {}

        if isinstance(source, (np.ndarray, 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,
            tile_format="folium",
            layer_name=layer_name,
            return_client=True,
            **kwargs,
        )
        tile_layer.add_to(self)

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

        arc_add_layer(tile_layer.tiles, layer_name, True, 1.0)
        arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

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

        Args:
            source: The path to the remote Cloud Optimized GeoTIFF.
            band: The band to use. Band indexing starts at 1.
            palette: 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: The minimum value to use when colormapping the palette when plotting a
                single band.
            vmax: The maximum value to use when colormapping the palette when plotting a
                single band.
            nodata: The value from the band to use to interpret as not valid
                data.
            attribution: Attribution for the source raster. This defaults to a message
                about it being a local file.
            layer_name: The layer name to use.
        """
        if isinstance(source, str) and source.startswith(("http://", "https://")):
            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 add_heatmap(
        self,
        data: str | list[Any] | pd.DataFrame,
        latitude: str = "latitude",
        longitude: str = "longitude",
        value: str = "value",
        name: str = "Heat map",
        radius: int = 25,
        **kwargs,
    ):
        """Adds a heat map to the map.

        Reference: https://stackoverflow.com/a/54756617

        Args:
            data: 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: The column name of latitude.
            longitude: The column name of longitude.
            value: The column name of values.
            name: Layer name to use.
            radius: Radius of each “point” of the heatmap.

        Raises:
            ValueError: If data is not a list.
        """
        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.")

        plugins.HeatMap(data, name=name, radius=radius, **kwargs).add_to(
            folium.FeatureGroup(name=name).add_to(self)
        )

    def add_legend(
        self,
        title: str = "Legend",
        labels=None,
        colors=None,
        legend_dict=None,
        builtin_legend: str | None = None,
        opacity: float = 1.0,
        position: str = "bottomright",
        draggable: bool = True,
        style: dict[str, Any] | None = None,
    ):
        """Adds a customized legend to the map.

        Reference: https://bit.ly/3oV6vnH.

        If you want to add multiple legends to the map, you need to set the `draggable`
        argument to False.

        Args:
            title: Title of the legend.
            colors (list, optional): A list of legend colors.
            labels (list, optional): A list of legend labels.
            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.
            builtin_legend: Name of the builtin legend to add to the map.
            opacity: The opacity of the legend.
            position: The position of the legend, can be one of the following:
                "topleft", "topright", "bottomleft", "bottomright".
            draggable: If True, the legend can be dragged to a new position.
            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'
                }
        """
        style = style or {}

        content = create_legend(
            title,
            labels,
            colors,
            legend_dict,
            builtin_legend,
            opacity,
            position,
            draggable,
            style=style,
        )
        if draggable:
            from branca.element import MacroElement, Template

            content = (
                '"""\n{% macro html(this, kwargs) %}\n'
                + content
                + '\n{% endmacro %}"""'
            )

            macro = MacroElement()
            macro._template = Template(content)

            self.get_root().add_child(macro)
        else:
            self.add_html(content, position=position)

    def add_colorbar(
        self,
        vis_params,
        index: list | None = None,
        label: str = "",
        categorical: bool = False,
        step: int | None = None,
        background_color=None,
        **kwargs,
    ) -> None:
        """Add a colorbar to the map.

        Args:
            vis_params: TODO.
            index: 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.
            label: The caption for the colormap.
            categorical: Whether or not to create a categorical colormap.
            step: The step to split the LinearColormap into a StepColormap.
            background_color: TODO.
            # TODO: Fix - these are in vis_params and are not normal 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.
        """
        from branca.colormap import LinearColormap

        del kwargs  # Unused.

        if not isinstance(vis_params, dict):
            raise ValueError("vis_params must be a dictionary.")

        if "palette" not in vis_params:
            raise ValueError("vis_params must contain a palette.")

        if "min" not in vis_params:
            vis_params["min"] = 0
        if "max" not in vis_params:
            vis_params["max"] = 1

        colors = coreutils.to_hex_colors(coreutils.check_cmap(vis_params["palette"]))
        vmin = vis_params["min"]
        vmax = vis_params["max"]

        if isinstance(colors, box.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=label
        )

        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)

        if background_color is not None:
            svg_style = (
                "<style>svg {background-color: " + background_color + ";}</style>"
            )

            self.get_root().header.add_child(folium.Element(svg_style))

        self.add_child(colormap)

    add_colorbar_branca = add_colorbar

    def add_colormap(
        self,
        width: float = 4.0,
        height: float = 0.3,
        vmin: float = 0.0,
        vmax: float = 1.0,
        palette=None,
        vis_params=None,
        cmap: str = "gray",
        discrete: bool = False,
        label: str | None = None,
        label_size: int = 10,
        label_weight: str = "normal",
        tick_size: int = 8,
        bg_color: str = "white",
        orientation: str = "horizontal",
        dpi: float | str = "figure",
        transparent: bool = False,
        position=(70, 5),
        **kwargs,
    ):
        """Add a colorbar to the map.

        Under the hood, it uses matplotlib to generate the colorbar, save it as a png
        file, and add it to the map using m.add_image().

        Args:
            width: Width of the colorbar in inches.
            height: Height of the colorbar in inches.
            vmin: Minimum value of the colorbar.
            vmax: Maximum value of the colorbar.
            palette (list): List of colors to use for the colorbar. It can also be a
                cmap name, such as ndvi, ndwi, dem, coolwarm.
            vis_params (dict): Visualization parameters as a dictionary. See
                https://developers.google.com/earth-engine/guides/image_visualization for
                options.
            cmap: Matplotlib colormap. See
                https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py
                for options.
            discrete: Whether to create a discrete colorbar.
            label: Label for the colorbar.
            label_size: Font size for the colorbar label.
            label_weight: Font weight for the colorbar label, can be "normal", "bold",
                etc.
            tick_size: Font size for the colorbar tick labels.
            bg_color: Background color for the colorbar.
            orientation: Orientation of the colorbar, such as "vertical" and
                "horizontal".
            dpi: The resolution in dots per inch. If 'figure', use the figure's dpi
                value.
            transparent: Whether to make the background transparent.
            position (tuple, optional): The position of the colormap in the format of
                (x, y), the percentage ranging from 0 to 100, starting from the
                lower-left corner.
            **kwargs: Other keyword arguments to pass to matplotlib.pyplot.savefig().

        Returns:
            str: Path to the output image.
        """
        colorbar = save_colorbar(
            None,
            width,
            height,
            vmin,
            vmax,
            palette,
            vis_params,
            cmap,
            discrete,
            label,
            label_size,
            label_weight,
            tick_size,
            bg_color,
            orientation,
            dpi,
            transparent,
            show_colorbar=False,
            **kwargs,
        )

        self.add_image(colorbar, position=position)

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

        Args:
            ee_object (object): An ee.FeatureCollection.
            column: 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: The name to be used for the new layer.
            shown: TODO
            opacity: TODO
        """
        styled_vector = vector_styling(ee_object, column, palette, **kwargs)
        self.addLayer(
            styled_vector.style(**{"styleProperty": "style"}),
            {},
            layer_name,
            shown,
            opacity,
        )

    def add_shapefile(
        self, in_shp: str, layer_name: str = "Untitled", **kwargs
    ) -> None:
        """Adds a shapefile to the map.

        See https://python-visualization.github.io/folium/modules.html#folium.features.GeoJson
        for more info about setting style.

        Args:
            in_shp: The input file path to the shapefile.
            layer_name: The layer name to be used.

        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.")

        data = shp_to_geojson(in_shp)

        geo_json = folium.GeoJson(data=data, name=layer_name, **kwargs)
        geo_json.add_to(self)

    def add_geojson(
        self,
        in_geojson: str,
        layer_name: str = "Untitled",
        encoding: str = "utf-8",
        info_mode: str = "on_hover",
        fields=None,
        **kwargs,
    ):
        """Adds a GeoJSON file to the map.

        Args:
            in_geojson: The input file path to the GeoJSON.
            layer_name: The layer name to be used.
            encoding: The encoding of the GeoJSON file.
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
            fields (list, optional): The fields to be displayed in the popup.

        Raises:
            FileNotFoundError: The provided GeoJSON file could not be found.
        """
        try:
            if isinstance(in_geojson, str):
                if in_geojson.startswith(("http://", "https://")):
                    in_geojson = coreutils.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)

        # Interchangeable parameters between ipyleaflet and folium.
        if "style_function" not in kwargs:
            if "style" in kwargs:
                style_dict = kwargs["style"]
                if isinstance(kwargs["style"], dict) and len(kwargs["style"]) > 0:
                    kwargs["style_function"] = lambda x: style_dict
                kwargs.pop("style")
            else:
                style_dict = {
                    # "stroke": True,
                    "color": "#000000",
                    "weight": 1,
                    "opacity": 1,
                    # "fill": True,
                    # "fillColor": "#ffffff",
                    "fillOpacity": 0.1,
                    # "dashArray": "9"
                    # "clickable": True,
                }
                kwargs["style_function"] = lambda x: style_dict

        if "style_callback" in kwargs:
            kwargs.pop("style_callback")

        if "hover_style" in kwargs:
            kwargs.pop("hover_style")

        if "fill_colors" in kwargs:
            fill_colors = kwargs["fill_colors"]

            def random_color(feature):
                del feature  # Unused.
                style_dict["fillColor"] = random.choice(fill_colors)
                return style_dict

            kwargs["style_function"] = random_color
            kwargs.pop("fill_colors")

        if "highlight_function" not in kwargs:
            kwargs["highlight_function"] = lambda feat: {
                "weight": 2,
                "fillOpacity": 0.5,
            }

        tooltip = None
        popup = None
        if info_mode is not None:
            if fields is None:
                fields = list(data["features"][0]["properties"].keys())
            if info_mode == "on_hover":
                tooltip = folium.GeoJsonTooltip(fields=fields)
            elif info_mode == "on_click":
                popup = folium.GeoJsonPopup(fields=fields)

        geojson = folium.GeoJson(
            data=data, name=layer_name, tooltip=tooltip, popup=popup, **kwargs
        )
        geojson.add_to(self)

    def add_kml(
        self,
        in_kml: str,
        layer_name: str = "Untitled",
        info_mode: str = "on_hover",
        fields: list | None = None,
        **kwargs,
    ) -> None:
        """Adds a KML file to the map.

        Args:
            in_kml: The input file path to the KML.
            layer_name: The layer name to be used.
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
            fields: The fields to be displayed in the popup.

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

        """
        if in_kml.startswith(("http://", "https://")) and in_kml.endswith(".kml"):
            out_dir = os.path.abspath("./cache")
            if not os.path.exists(out_dir):
                os.makedirs(out_dir)
            download_from_url(in_kml, out_dir=out_dir, unzip=False, verbose=False)
            in_kml = os.path.join(out_dir, os.path.basename(in_kml))
            if not os.path.exists(in_kml):
                raise FileNotFoundError("The downloaded kml file could not be found.")
        else:
            in_kml = os.path.abspath(in_kml)
            if not os.path.exists(in_kml):
                raise FileNotFoundError("The provided KML could not be found.")

        data = kml_to_geojson(in_kml)

        self.add_geojson(
            data, layer_name=layer_name, info_mode=info_mode, fields=fields, **kwargs
        )

    def add_gdf(
        self,
        gdf,
        layer_name: str = "Untitled",
        zoom_to_layer: bool = True,
        info_mode: str = "on_hover",
        fields: list | None = None,
        **kwargs,
    ) -> None:
        """Adds a GeoPandas GeoDataFrame to the map.

        Args:
            gdf (GeoDataFrame): A GeoPandas GeoDataFrame.
            layer_name: The layer name to be used.
            zoom_to_layer: Whether to zoom to the layer.
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
            fields: The fields to be displayed in the popup.

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

        self.add_geojson(
            data, layer_name=layer_name, info_mode=info_mode, fields=fields, **kwargs
        )

        if zoom_to_layer:
            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: str,
        con,
        layer_name: str = "Untitled",
        zoom_to_layer: bool = True,
        **kwargs,
    ):
        """Adds a GeoPandas GeoDataFrameto the map.

        Args:
            sql: 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: The layer name to be used.
            zoom_to_layer: Whether to zoom to the layer.
        """
        if "fill_colors" in kwargs:
            kwargs.pop("fill_colors")
        gdf = read_postgis(sql, con, **kwargs)
        data = gdf_to_geojson(gdf, epsg="4326")

        self.add_geojson(data, layer_name=layer_name, **kwargs)

        if zoom_to_layer:
            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_osm(
        self,
        query,
        layer_name: str = "Untitled",
        which_result: int | None = None,
        by_osmid: bool = False,
        to_ee: bool = False,
        geodesic: bool = True,
        **kwargs,
    ) -> None:
        """Adds OSM data to the map.

        Args:
            query (str | dict | list): Query string(s) or structured dict(s) to geocode.
            layer_name: The layer name to be used.
            which_result: 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.
            by_osmid: If True, handle query as an OSM ID for lookup rather than text
                search.
            to_ee: Whether to convert the csv to an ee.FeatureCollection.
            geodesic: 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 = common.osm_to_gdf(query, which_result=which_result, by_osmid=by_osmid)
        geojson = gdf.__geo_interface__

        if to_ee:
            fc = coreutils.geojson_to_ee(geojson, geodesic=geodesic)
            self.addLayer(fc, {}, layer_name)
            self.centerObject(fc)
        else:
            self.add_geojson(geojson, layer_name=layer_name, **kwargs)
            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: int | None = None,
        by_osmid: bool = False,
        layer_name: str = "Untitled",
        style: dict[str, Any] | None = None,
        hover_style: dict[str, Any] | None = None,
        style_callback=None,
        fill_colors: list[str] = ["black"],
        info_mode: str = "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: 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.
            by_osmid: If True, handle query as an OSM ID for lookup rather than text
                search.
            layer_name: The layer name to be used.
            style: A dictionary specifying the style to be used. Defaults to {}.
            hover_style: Hover style dictionary.
            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.
            fill_colors: The random colors to use for filling polygons. Defaults to
                ["black"].
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
        """
        style = style or {}
        hover_style = hover_style or {}

        gdf = osm.osm_gdf_from_geocode(
            query, which_result=which_result, by_osmid=by_osmid
        )
        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: str,
        tags: dict[str, Any],
        dist: int = 1000,
        layer_name: str = "Untitled",
        style: dict[str, Any] | None = None,
        hover_style: dict[str, Any] | None = None,
        style_callback=None,
        fill_colors: list[str] = ["black"],
        info_mode: str = "on_hover",
    ):
        """Adds OSM entities within some distance N, S, E, W of address to the map.

        Args:
            address: The address to geocode and use as the central point around which to
                get the geometries.
            tags: 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: Distance in meters.
            layer_name: The layer name to be used.
            style: A dictionary specifying the style to be used.
            hover_style: Hover style dictionary. Defaults to {}.
            style_callback: Styling function that is called for each feature, and should
                return the feature style. This styling function takes the feature as
                argument.
            fill_colors: The random colors to use for filling polygons. Defaults to
                ["black"].
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
        """
        style = style or {}
        hover_style = hover_style or {}

        gdf = osm.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: dict,
        which_result: int | None = None,
        layer_name: str = "Untitled",
        style: dict[str, Any] | None = None,
        hover_style: dict[str, Any] | None = None,
        style_callback=None,
        fill_colors: list[str] = ["black"],
        info_mode: str = "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 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: 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.
            layer_name: The layer name to be used.
            style: A dictionary specifying the style to be used. Defaults to {}.
            hover_style: 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.
            fill_colors: The random colors to use for filling polygons. Defaults to
                ["black"].
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
        """
        style = style or {}
        hover_style = hover_style or {}

        gdf = osm.osm_gdf_from_place(query, tags, which_result)
        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: tuple[float, float],
        tags: dict,
        dist: int = 1000,
        layer_name: str = "Untitled",
        style: dict[str, Any] | None = None,
        hover_style: dict[str, Any] | None = None,
        style_callback=None,
        fill_colors: list[str] = ["black"],
        info_mode: str = "on_hover",
    ):
        """Adds OSM entities within some distance N, S, E, W of a point to the map.

        Args:
            center_point: The (lat, lng) center point around which to get the
                geometries.
            tags: 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: Distance in meters.
            layer_name: The layer name to be used.
            style: A dictionary specifying the style to be used. Defaults to {}.
            hover_style: 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.
            fill_colors: The random colors to use for filling polygons. Defaults to ["black"].
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
        """
        style = style or {}
        hover_style = hover_style or {}

        gdf = osm.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: dict,
        layer_name: str = "Untitled",
        style: dict[str, Any] | None = None,
        hover_style: dict[str, Any] | None = None,
        style_callback=None,
        fill_colors: list[str] = ["black"],
        info_mode: str = "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 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: The layer name to be used.
            style: A dictionary specifying the style to be used. Defaults to {}.
            hover_style: 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.
            fill_colors (list, optional): The random colors to use for filling
                polygons. Defaults to ["black"].
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
        """
        style = style or {}
        hover_style = hover_style or {}

        gdf = osm.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: float,
        south: float,
        east: float,
        west: float,
        tags: dict,
        layer_name: str = "Untitled",
        style: dict[str, Any] | None = None,
        hover_style: dict[str, Any] | None = None,
        style_callback=None,
        fill_colors: list[str] = ["black"],
        info_mode: str = "on_hover",
    ):
        """Adds OSM entities within a N, S, E, W bounding box to the map.

        Args:
            north: Northern latitude of bounding box.
            south: Southern latitude of bounding box.
            east: Eastern longitude of bounding box.
            west: Western longitude of bounding box.
            tags: 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: The layer name to be used.
            style: A dictionary specifying the style to be used. Defaults to {}.
            hover_style: 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.
            fill_colors: The random colors to use for filling polygons. Defaults to
                ["black"].
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
        """
        style = style or {}
        hover_style = hover_style or {}

        gdf = osm.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_points_from_xy(
        self,
        data: str | pd.DataFrame,
        x: str = "longitude",
        y: str = "latitude",
        popup: list[str] | None = None,
        min_width: int = 100,
        max_width: int = 200,
        layer_name: str = "Marker Cluster",
        color_column: str | None = None,
        marker_colors: list | None = None,
        icon_colors: list[str] = ["white"],
        icon_names: list[str] = ["info"],
        angle: int = 0,
        prefix: str = "fa",
        add_legend: bool = True,
        max_cluster_radius: int = 80,
        **kwargs,
    ):
        """Adds a marker cluster to the map.

        Args:
            data: A csv or Pandas DataFrame containing x, y, z values.
            x: The column name for the x values.
            y: The column name for the y values.
            popup: A list of column names to be used as the popup.
            min_width: The minimum width of the popup.
            max_width: The maximum width of the popup.
            layer_name: The name of the layer.
            color_column: The column name for the color values.
            marker_colors: List of colors to be used for the markers.
            icon_colors: List of colors to be used for the icons. Defaults to ['white'].
            icon_names: A list of names to be used for the icons. More icons can be
                found at https://fontawesome.com/v4/icons or
                https://getbootstrap.com/docs/3.3/components/?utm_source=pocket_mylist. Defaults
                to ['info'].
            angle: The angle of the icon.
            prefix: The prefix states the source of the icon. 'fa' for font-awesome or
                'glyphicon' for bootstrap 3.
            add_legend: If True, a legend will be added to the map.
            max_cluster_radius: The maximum radius that a cluster will cover from the
                central marker (in pixels).
            **kwargs: Other keyword arguments to pass to folium.MarkerCluster(). For a
                list of available options, see
                https://github.com/Leaflet/Leaflet.markercluster. For example, to change
                the cluster radius, use options={"maxClusterRadius": 50}.
        """
        if "maxClusterRadius" not in kwargs:
            kwargs["maxClusterRadius"] = max_cluster_radius

        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://", "https://")) 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 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 popup is None:
            popup = col_names

        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)}")

        marker_cluster = plugins.MarkerCluster(name=layer_name, **kwargs).add_to(self)

        for idx, row in df.iterrows():
            html = ""
            for p in popup:
                html = html + "<b>" + p + "</b>" + ": " + str(row[p]) + "<br>"
            popup_html = folium.Popup(html, min_width=min_width, max_width=max_width)

            if items is not None:
                index = items.index(row[color_column])
                marker_icon = folium.Icon(
                    color=marker_colors[index],
                    icon_color=icon_colors[index],
                    icon=icon_names[index],
                    angle=angle,
                    prefix=prefix,
                )
            else:
                marker_icon = None

            folium.Marker(
                location=[row[y], row[x]],
                popup=popup_html,
                icon=marker_icon,
            ).add_to(marker_cluster)

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

    def add_circle_markers_from_xy(
        self,
        data,
        x: str = "longitude",
        y: str = "latitude",
        radius: int = 10,
        popup: list | None = None,
        tooltip: list | None = None,
        min_width: int = 100,
        max_width: int = 200,
        **kwargs,
    ):
        """Adds a marker cluster to the map.

        Args:
            data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z
                values.
            x: The column name for the x values.
            y: The column name for the y values.
            radius: The radius of the circle.
            popup: A list of column names to be used as the popup.
            tooltip: A list of column names to be used as the tooltip.
            min_width: The minimum width of the popup.
            max_width: The maximum width of the popup.
        """
        data = coreutils.github_raw_url(data)

        if isinstance(data, pd.DataFrame):
            df = data
        elif not data.startswith(("http://", "https://")) 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 "color" not in kwargs:
            kwargs["color"] = None
        if "fill" not in kwargs:
            kwargs["fill"] = True
        if "fill_color" not in kwargs:
            kwargs["fill_color"] = "blue"
        if "fill_opacity" not in kwargs:
            kwargs["fill_opacity"] = 0.7

        if popup is None:
            popup = col_names

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

        if tooltip is not None:
            if not isinstance(tooltip, list):
                tooltip = [tooltip]

        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 _ in df.itertuples():
            html = ""
            for p in popup:
                html = (
                    html
                    + "<b>"
                    + p
                    + "</b>"
                    + ": "
                    + str(eval(str("row." + p)))
                    + "<br>"
                )
            popup_html = folium.Popup(html, min_width=min_width, max_width=max_width)

            if tooltip is not None:
                html = ""
                for p in tooltip:
                    html = (
                        html
                        + "<b>"
                        + p
                        + "</b>"
                        + ": "
                        + str(eval(str("row." + p)))
                        + "<br>"
                    )

                tooltip_str = folium.Tooltip(html)
            else:
                tooltip_str = None

            folium.CircleMarker(
                location=[eval(f"row.{y}"), eval(f"row.{x}")],
                radius=radius,
                popup=popup_html,
                tooltip=tooltip_str,
                **kwargs,
            ).add_to(self)

    def add_markers_from_xy(
        self,
        data,
        x: str = "longitude",
        y: str = "latitude",
        popup: list | None = None,
        min_width: int = 100,
        max_width: int = 200,
        layer_name: str = "Markers",
        icon: str | None = None,
        icon_shape: str = "circle-dot",
        border_width: int = 3,
        border_color: str = "#0000ff",
        **kwargs,
    ):
        """Adds markers to the map from a csv or Pandas DataFrame containing x, y values.

        Args:
            data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
            x: The column name for the x values.
            y: The column name for the y values.
            popup: A list of column names to be used as the popup.
            min_width: The minimum width of the popup.
            max_width: The maximum width of the popup.
            layer_name: The name of the layer.
            icon: The Font-Awesome icon name to use to render the marker.
            icon_shape: The shape of the marker, such as "retangle-dot",
                "circle-dot".
            border_width: The width of the border.
            border_color: The color of the border.
            kwargs: Additional keyword arguments to pass to BeautifyIcon. See
                https://python-visualization.github.io/folium/plugins.html#folium.plugins.BeautifyIcon.
        """
        from folium.plugins import BeautifyIcon

        layer_group = folium.FeatureGroup(name=layer_name)

        if isinstance(data, pd.DataFrame):
            df = data
        elif not data.startswith(("http://", "https://")) 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 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 = folium.Popup(html, min_width=min_width, max_width=max_width)

            marker_icon = BeautifyIcon(
                icon, icon_shape, border_width, border_color, **kwargs
            )
            folium.Marker(  # pytype: disable=wrong-arg-types
                location=[getattr(row, y), getattr(row, x)],
                popup=popup_html,
                icon=marker_icon,
            ).add_to(layer_group)

        layer_group.add_to(self)

    def add_planet_by_month(
        self,
        year: int = 2016,
        month: int = 1,
        name: str | None = None,
        api_key: str | None = None,
        token_name: str = "PLANET_API_KEY",
    ) -> None:
        """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: The year of Planet global mosaic, must be >=2016.
            month: The month of Planet global mosaic, must be 1-12.
            name: The layer name to use.
            api_key: The Planet API key.
            token_name: The environment variable name of the API key.
        """
        layer = planet_tile_by_month(
            year, month, name, api_key, token_name, tile_format="folium"
        )
        layer.add_to(self)

    def add_planet_by_quarter(
        self,
        year: int = 2016,
        quarter: int = 1,
        name: str | None = None,
        api_key: str | None = None,
        token_name: str = "PLANET_API_KEY",
    ) -> None:
        """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: The year of Planet global mosaic, must be >=2016.
            quarter: The quarter of Planet global mosaic, must be 1-12.
            name: The layer name to use.
            api_key: The Planet API key.
            token_name: The environment variable name of the API key.
        """
        layer = planet_tile_by_quarter(
            year, quarter, name, api_key, token_name, tile_format="folium"
        )
        layer.add_to(self)

    def publish(
        self,
        name: str = "Folium Map",
        description: str = "",
        source_url: str = "",
        tags=None,
        source_file: str | None = None,
        open: bool = True,
        formatting=None,
        token: str | None = None,
        **kwargs,
    ):
        """Publish the map to datapane.com

        Args:

            name: The document name - can include spaces, caps, symbols, etc.,
                e.g., "Profit & Loss 2020".
            description: A high-level description for the document, this is displayed in
                searches and thumbnails.
            source_url: A URL pointing to the source code for the document, e.g. a
                GitHub repo or a Colab notebook.
            tags (bool, optional): A list of tags (as strings) used to categorise your
                document.
            source_file: Path of jupyter notebook file to upload.
            open: Whether to open the map.
            formatting (ReportFormatting, optional): Set the basic styling for your
                report.
            token: The token to use to datapane to publish the map. See
                https://docs.datapane.com/tut-getting-started.
        """
        import datapane as dp

        warnings.filterwarnings("ignore")

        if token is None:
            try:
                _ = dp.ping(verbose=False)
            except Exception as e:
                if os.environ.get("DP_TOKEN") is not None:
                    dp.login(token=os.environ.get("DP_TOKEN"))
                else:
                    raise Exception(e)
        else:
            dp.login(token)

        dp.upload_report(
            dp.Plot(self),
            name=name,
            description=description,
            source_url=source_url,
            tags=tags,
            source_file=source_file,
            open=open,
            formatting=formatting,
            **kwargs,
        )

    def to_html(self, filename: str | None = None, **kwargs) -> str | None:
        """Exports a map as an HTML file.

        Args:
            filename: File path to the output HTML.

        Raises:
            ValueError: If it is an invalid HTML file.

        Returns:
            A string containing the HTML code.
        """
        if self.options["layersControl"]:
            self.add_layer_control()

        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)
            self.save(filename, **kwargs)
        else:
            filename = os.path.abspath(coreutils.random_string() + ".html")
            self.save(filename, **kwargs)
            out_html = ""
            with open(filename) as f:
                lines = f.readlines()
                out_html = "".join(lines)
            os.remove(filename)
            return out_html

    def to_streamlit(
        self,
        width: int | None = None,
        height: int = 600,
        scrolling: bool = False,
        add_layer_control: bool = True,
        bidirectional: bool = False,
        **kwargs,
    ):
        """Renders `folium.Figure` or `folium.Map` in a Streamlit app.

        This method is a static Streamlit Component, meaning, no information is passed
        back from Leaflet on browser interaction.

        Args:
            width: Width of the map. Defaults to None.
            height: Height of the map. Defaults to 600.
            scrolling: Whether to allow the map to scroll. Defaults to False.
            add_layer_control: Whether to add the layer control. Defaults to True.
            bidirectional: Whether to add bidirectional functionality to the map. The
                streamlit-folium package is required to use the bidirectional
                functionality. Defaults to False.

        Returns:
            streamlit.components: components.html object.
        """
        import streamlit.components.v1 as components

        del kwargs  # Unused.

        if add_layer_control:
            self.add_layer_control()

        if bidirectional:
            from streamlit_folium import st_folium

            return st_folium(self, width=width, height=height)
        else:
            return components.html(
                self.to_html(), width=width, height=height, scrolling=scrolling
            )

    def st_map_center(self, st_component) -> tuple[float, float]:
        """Returns the center of the map.

        Args:
            st_folium (streamlit-folium): The streamlit component.
        """
        bounds = st_component["bounds"]
        west = bounds["_southWest"]["lng"]
        south = bounds["_southWest"]["lat"]
        east = bounds["_northEast"]["lng"]
        north = bounds["_northEast"]["lat"]
        return (south + (north - south) / 2, west + (east - west) / 2)

    def st_map_bounds(self, st_component) -> list[list[float]]:
        """Returns the bounds of the map in the format of (miny, minx, maxy, maxx).

        Args:
            st_folium (streamlit-folium): The streamlit component.
        """
        bounds = st_component["bounds"]
        south = bounds["_southWest"]["lat"]
        west = bounds["_southWest"]["lng"]
        north = bounds["_northEast"]["lat"]
        east = bounds["_northEast"]["lng"]

        return [[south, west], [north, east]]

    def st_fit_bounds(self) -> None:
        """Fit the map to the bounds of the map."""
        import streamlit as st

        if "map_bounds" in st.session_state:
            bounds = st.session_state["map_bounds"]

            self.fit_bounds(bounds)

    def st_last_draw(self, st_component):
        """Returns the last draw feature of the map.

        Args:
            st_folium (streamlit-folium): The streamlit component.
        """
        return st_component["last_active_drawing"]

    def st_last_click(self, st_component):
        """Returns the last click feature of the map.

        Args:
            st_folium (streamlit-folium): The streamlit component.
        """
        coords = st_component["last_clicked"]
        return coords["lat"], coords["lng"]

    def st_draw_features(self, st_component):
        """Get the draw features of the map.

        Args:
            st_folium (streamlit-folium): The streamlit component.

        Returns:
            list: The draw features of the map.
        """
        return st_component["all_drawings"]

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

        Args:
            wms: 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: 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.
        """
        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)

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

        Args:
            provider: 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

        del kwargs  # Unused.

        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=url, name=name, attribution=attribution)
        else:
            raise ValueError(
                f"The provider {provider} is not valid. It must start with xyz or qms."
            )

    def add_labels(
        self,
        data,
        column: str,
        font_size: str = "12pt",
        font_color: str = "black",
        font_family: str = "arial",
        font_weight: str = "normal",
        x: str = "longitude",
        y: str = "latitude",
        draggable: bool = True,
        layer_name: str = "Labels",
        **kwargs,
    ):
        """Adds a label layer to the map.

        Reference:
        https://python-visualization.github.io/folium/modules.html#folium.features.DivIcon

        Args:
            data (pd.DataFrame | ee.FeatureCollection): The input data to label.
            column: The column name of the data to label.
            font_size: The font size of the labels.
            font_color: The font color of the labels.
            font_family: The font family of the labels.
            font_weight: The font weight of the labels, can be normal, bold.
            x: The column name of the longitude.
            y: The column name of the latitude.
            draggable: Whether the labels are draggable.
            layer_name: The name of the layer.
        """
        from folium.features import DivIcon

        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"]:
                import geopandas as gpd

                df = gpd.read_file(data)
                df[x] = df.centroid.x
                df[y] = df.centroid.y
        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 Exception as _:
            raise ValueError("font_size must be something like '10pt'")

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

        layer_group.add_to(self)

    def split_map(
        self,
        left_layer: str = "TERRAIN",
        right_layer: str = "OpenTopoMap",
        left_args: dict[str, Any] | None = None,
        right_args: dict[str, Any] | None = None,
        left_label=None,
        right_label=None,
        left_position="bottomleft",
        right_position="bottomright",
        **kwargs,
    ):
        """Adds a split-panel map.

        Args:
            left_layer: The left tile layer. Can be a local file path, HTTP URL, or a
                basemap name.
            right_layer: The right tile layer. Can be a local file path, HTTP URL, or a
                basemap name.
            left_args (dict, optional): The arguments for the left tile layer. Defaults to {}.
            right_args (dict, optional): The arguments for the right tile layer. Defaults to {}.
            left_label: TODO
            right_label: TODO
            left_position: TODO
            right_position: TODO
        """
        left_args = left_args or {}
        right_args = right_args or {}

        del kwargs  # Unused.

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

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

        if "layer_name" not in left_args:
            left_args["layer_name"] = "Left Layer"

        if "layer_name" not in right_args:
            right_args["layer_name"] = "Right Layer"

        bounds = None

        try:
            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 left_layer in basemaps.keys():
                left_layer = basemaps[left_layer]
            elif isinstance(left_layer, str):
                if left_layer.startswith(
                    ("http://", "https://")
                ) and left_layer.endswith(".tif"):
                    url = cog_tile(left_layer, **left_args)
                    bbox = cog_bounds(left_layer)
                    bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                    left_layer = folium.raster_layers.TileLayer(
                        tiles=url,
                        name=left_name,
                        attr=" ",
                        overlay=True,
                    )
                elif os.path.exists(left_layer):
                    left_layer, left_client = get_local_tile_layer(
                        left_layer,
                        tile_format="folium",
                        return_client=True,
                        **left_args,
                    )
                    bounds = image_bounds(left_client)

                else:
                    left_layer = folium.raster_layers.TileLayer(
                        tiles=left_layer,
                        name=left_name,
                        attr=" ",
                        overlay=True,
                        **left_args,
                    )
            elif isinstance(
                left_layer, (folium.raster_layers.TileLayer, folium.WmsTileLayer)
            ):
                pass
            else:
                raise ValueError(
                    "left_layer must be one of the following: "
                    f"{', '.join(basemaps.keys())} or a string url to a tif file."
                )

            if right_layer in basemaps.keys():
                right_layer = basemaps[right_layer]
            elif isinstance(right_layer, str):
                if right_layer.startswith(
                    ("http://", "https://")
                ) and right_layer.endswith(".tif"):
                    url = cog_tile(right_layer, **right_args)
                    bbox = cog_bounds(right_layer)
                    bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                    right_layer = folium.raster_layers.TileLayer(
                        tiles=url,
                        name=right_name,
                        attr=" ",
                        overlay=True,
                    )
                elif os.path.exists(right_layer):
                    right_layer, right_client = get_local_tile_layer(
                        right_layer,
                        tile_format="folium",
                        return_client=True,
                        **right_args,
                    )
                    bounds = image_bounds(right_client)
                else:
                    right_layer = folium.raster_layers.TileLayer(
                        tiles=right_layer,
                        name=right_name,
                        attr=" ",
                        overlay=True,
                        **right_args,
                    )
            elif isinstance(
                right_layer, (folium.raster_layers.TileLayer, folium.WmsTileLayer)
            ):
                pass
            else:
                raise ValueError(
                    "right_layer must be one of the following: "
                    f"{', '.join(basemaps.keys())} or a string url to a tif file."
                )

            control = folium.plugins.SideBySideLayers(
                layer_left=left_layer, layer_right=right_layer
            )
            left_layer.add_to(self)
            right_layer.add_to(self)
            control.add_to(self)

            if left_label is not None:
                if "<" not in left_label:
                    left_label = f"<h4>{left_label}</h4>"
                self.add_html(left_label, position=left_position)

            if right_label is not None:
                if "<" not in right_label:
                    right_label = f"<h4>{right_label}</h4>"
                self.add_html(right_label, position=right_position)
            if bounds is not None:
                self.fit_bounds(bounds)

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

    def add_netcdf(
        self,
        filename: str,
        variables: list[str] | None = None,
        palette: str | None = None,
        vmin: float | None = None,
        vmax: float | None = None,
        nodata: float | None = None,
        attribution: str | None = None,
        layer_name: str = "NetCDF layer",
        shift_lon: bool = True,
        lat: str = "lat",
        lon: str = "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: File path or HTTP URL to the netCDF file.
            variables: The variable/band names to extract data from the netCDF
                file. If None, all variables will be extracted.
            palette: 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: The minimum value to use when colormapping the palette when plotting a
                single band.
            vmax: The maximum value to use when colormapping the palette when plotting a
                single band.
            nodata: The value from the band to use to interpret as not valid
                data.
            attribution: Attribution for the source raster. This defaults to a message
                about it being a local file.
            layer_name: The layer name to use.
            shift_lon: Flag to shift longitude values from [0, 360] to the range [-180,
                180].
            lat: Name of the latitude variable.
            lon: Name of the longitude variable.
        """
        if coreutils.in_colab_shell():
            print("The add_netcdf() function is not supported in Colab.")
            return

        tif, vars = netcdf_to_tif(  # pylint: disable=redefined-builtin
            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_data(
        self,
        data,
        column: str,
        colors=None,
        labels=None,
        cmap=None,
        scheme: str = "Quantiles",
        k: int = 5,
        add_legend=True,
        legend_title=None,
        legend_kwds=None,
        classification_kwds=None,
        style_function=None,
        highlight_function=None,
        layer_name: str = "Untitled",
        info_mode: str = "on_hover",
        encoding: str = "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: The column to classify.
            cmap: The name of a colormap recognized by matplotlib.
            colors: A list of colors to use for the classification.
            labels: A list of labels to use for the legend.
            scheme: 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: Number of classes (ignored if scheme is None or if column is
                categorical).
            legend_kwds (dict, optional): Keyword arguments to pass to
                :func:`matplotlib.pyplot.legend` or
                `matplotlib.pyplot.colorbar`.
                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.
            style_function (function, optional): Styling function that is called for
                each feature, and should return the feature style. This styling function
                takes the feature as argument. 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"]}
                    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,
                    }
            highlight_function (function, optional): Highlighting function that is
                called for each feature, and should return the feature style. This
                styling function takes the feature as argument.
                highlight_function is a function that takes the feature as argument and
                should return a dictionary of the following form:
                    highlight_function = lambda feat: {"fillColor": feat["properties"]["color"]}
            layer_name: The layer name to be used.
            info_mode: Displays the attributes by either on_hover or on_click. Any value
                other than "on_hover" or "on_click" will be treated as None.
            encoding: The encoding of the GeoJSON file.

        """
        gdf, legend_dict = classify(  # pytype: disable=attribute-error
            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" in kwargs:
            warnings.warn(
                "The style arguments is for ipyleaflet only. ",
                UserWarning,
            )
            kwargs.pop("style")

        if "hover_style" in kwargs:
            warnings.warn(
                "The hover_style arguments is for ipyleaflet only. ",
                UserWarning,
            )
            kwargs.pop("hover_style")

        if "style_callback" in kwargs:
            warnings.warn(
                "The style_callback arguments is for ipyleaflet only. ",
                UserWarning,
            )
            kwargs.pop("style_callback")

        if style_function is None:
            style_function = lambda feat: {
                # "stroke": False,
                # "color": "#ff0000",
                "weight": 1,
                "opacity": 1,
                # "fill": True,
                # "fillColor": "#ffffff",
                "fillOpacity": 1.0,
                # "dashArray": "9"
                # "clickable": True,
                "fillColor": feat["properties"]["color"],
            }

        if highlight_function is None:
            highlight_function = lambda feat: {
                "weight": 2,
                "fillOpacity": 0.5,
            }

        self.add_gdf(
            gdf,
            layer_name=layer_name,
            style_function=style_function,
            highlight_function=highlight_function,
            info_mode=info_mode,
            encoding=encoding,
            **kwargs,
        )
        if add_legend:
            self.add_legend(title=legend_title, legend_dict=legend_dict)

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

        Args:
            image (str | ipywidgets.Image): The image to add.
            position (tuple, optional): The position of the image in the format of (x, y),
                the percentage ranging from 0 to 100, starting from the lower-left corner.
        """
        if isinstance(image, str):
            if image.startswith(("http://", "https://")):
                html = f'<img src="{image}">'
                if isinstance(position, tuple):
                    position = "bottomright"
                self.add_html(html, position=position, **kwargs)

            elif os.path.exists(image):
                if position == "bottomleft":
                    position = (5, 5)
                elif position == "bottomright":
                    position = (80, 5)
                elif position == "topleft":
                    position = (5, 60)
                elif position == "topright":
                    position = (80, 60)

                with open(image, "rb") as lf:
                    # open in binary mode, read bytes, encode, decode obtained bytes as utf-8 string
                    b64_content = base64.b64encode(lf.read()).decode("utf-8")
                    widget = plugins.FloatImage(
                        f"data:image/png;base64,{b64_content}",
                        bottom=position[1],
                        left=position[0],
                    )
                    widget.add_to(self)

        else:
            raise Exception("Invalid image")

    def add_widget(self, content: str, position: str = "bottomright", **kwargs):
        """Add a widget (e.g., text, HTML, figure) to the map.

        Args:
            content: The widget to add.
            position: The position of the widget.
        """
        del kwargs  # Unused.

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

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

        if isinstance(content, str):
            widget = CustomControl(content, position=position)
            widget.add_to(self)
        elif isinstance(content, figure.Figure):
            buf = io.BytesIO()
            content.savefig(buf, format="png")
            buf.seek(0)
            b64_content = base64.b64encode(buf.read()).decode("utf-8")
            widget = CustomControl(
                f"""<img src="data:image/png;base64,{b64_content}">""",
                position=position,
            )
            widget.add_to(self)
        else:
            raise Exception("The content must be a string or a matplotlib figure")

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

        Args:
            html: The HTML to add.
            position: The position of the widget.
        """

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

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

        Args:
            text: The text to add.
            fontsize: The font size.
            fontcolor: The font color.
            bold: Whether to use bold font.
            padding: The padding.
            background: Whether to use background.
            bg_color: The background color.
            border_radius: The border radius.
            position: The position of the widget.
        """

        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: str = "100%", height: str = "500px", **kwargs) -> str:
        """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: The width of the map.
            height: The height of the map.

        Returns:
            The HTML string to use in Gradio.
        """
        del kwargs  # Unused.

        if isinstance(width, int):
            width = f"{width}px"
        if isinstance(height, int):
            height = f"{height}px"

        html = self.to_html()
        assert html is not None  # For pytype.
        lines = html.split("\n")
        output = []
        skipped_lines = []
        for index, line in enumerate(lines):
            if index in skipped_lines:
                continue
            if line.lstrip().startswith('{"attribution":'):
                continue
            elif "on(L.Draw.Event.CREATED, function(e)" in line:
                for i in range(14):
                    skipped_lines.append(index + i)
            elif "L.Control.geocoder" in line:
                for i in range(5):
                    skipped_lines.append(index + i)
            elif "function(e)" in line:
                print(
                    "Warning: The folium plotting backend does not support functions "
                    f"in code blocks. Please delete line {index + 1}."
                )
            else:
                output.append(line + "\n")

        return f"""<iframe style="width: {width}; height: {height}" name="result" allow="midi; geolocation; microphone; camera;
        display-capture; encrypted-media;" sandbox="allow-modals allow-forms
        allow-scripts allow-same-origin allow-popups
        allow-top-navigation-by-user-activation allow-downloads" allowfullscreen=""
        allowpaymentrequest="" frameborder="0" srcdoc='{"".join(output)}'></iframe>"""

    def remove_labels(self, **kwargs):
        """Removes a layer from the map."""
        del kwargs  # Unused.
        print("The folium plotting backend does not support removing labels.")

    def basemap_demo(self):
        """A demo for using geemap basemaps."""
        print("The folium plotting backend does not support this function.")

    def set_plot_options(
        self,
        **kwargs,
    ):
        """Sets plotting options."""
        del kwargs  # Unused.
        print("The folium plotting backend does not support this function.")

    def ts_inspector(
        self,
        left_ts,
        right_ts,
        left_names,
        right_names,
        left_vis: dict[str, Any] | None = None,
        right_vis: dict[str, Any] | None = None,
        width="130px",
        **kwargs,
    ):
        del left_ts, right_ts, left_names, right_names, left_vis, right_vis  # Unused.
        del width, kwargs  # Unused.
        print("The folium plotting backend does not support this function.")

    def add_time_slider(
        self,
        ee_object,
        vis_params: dict[str, Any] | None = None,
        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,
    ):
        del ee_object, vis_params, region, layer_name, labels, time_interval  # Unused.
        del position, slider_length, date_format, opacity, kwargs  # Unused.
        print("The folium plotting backend does not support this function.")

    def extract_values_to_points(self, filename: str):
        del filename  # Unused.
        print("The folium plotting backend does not support this function.")

`add_basemap(basemap='HYBRID', show=True, **kwargs)` ¶

Adds a basemap to the map.

Parameters:

Name	Type	Description	Default
`basemap`	`str`	Can be one of string from ee_basemaps.	`'HYBRID'`

Source code in geemap/foliumap.py

def add_basemap(self, basemap: str = "HYBRID", show: bool = True, **kwargs):
    """Adds a basemap to the map.

    Args:
        basemap: Can be one of string from ee_basemaps.
    """
    import xyzservices

    try:
        map_dict = {
            "ROADMAP": "Esri.WorldStreetMap",
            "SATELLITE": "Esri.WorldImagery",
            "TERRAIN": "Esri.WorldTopoMap",
            "HYBRID": "Esri.WorldImagery",
        }

        if isinstance(basemap, str):
            if basemap.upper() in map_dict:
                if basemap in os.environ:
                    if "name" in kwargs:
                        kwargs["name"] = basemap
                    basemap = os.environ[basemap]
                    self.add_tile_layer(tiles=basemap, **kwargs)

                else:
                    basemap = basemap.upper()
                    basemaps[basemap].add_to(self)

            elif 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 = 22
                layer = folium.TileLayer(
                    tiles=url,
                    attr=attribution,
                    name=name,
                    max_zoom=max_zoom,
                    overlay=True,
                    control=True,
                    show=show,
                    **kwargs,
                )

                self.add_layer(layer)

                arc_add_layer(url, name)

            elif basemap in basemaps:
                bmap = basemaps[basemap]
                bmap.show = show
                bmap.add_to(self)
                if isinstance(basemaps[basemap], folium.TileLayer):
                    url = basemaps[basemap].tiles
                elif isinstance(basemaps[basemap], folium.WmsTileLayer):
                    url = basemaps[basemap].url
                arc_add_layer(url, basemap)
            else:
                print(
                    "Basemap can only be one of the following: {}".format(
                        ", ".join(basemaps.keys())
                    )
                )

    except Exception:
        raise Exception(
            "Basemap can only be one of the following: {}".format(
                ", ".join(basemaps.keys())
            )
        )

`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/foliumap.py

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

    Args:
        wms: 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: 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.
    """
    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)

`add_circle_markers_from_xy(data, x='longitude', y='latitude', radius=10, popup=None, tooltip=None, min_width=100, max_width=200, **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.	`'longitude'`
`y`	`str`	The column name for the y values.	`'latitude'`
`radius`	`int`	The radius of the circle.	`10`
`popup`	`list \| None`	A list of column names to be used as the popup.	`None`
`tooltip`	`list \| None`	A list of column names to be used as the tooltip.	`None`
`min_width`	`int`	The minimum width of the popup.	`100`
`max_width`	`int`	The maximum width of the popup.	`200`

Source code in geemap/foliumap.py

def add_circle_markers_from_xy(
    self,
    data,
    x: str = "longitude",
    y: str = "latitude",
    radius: int = 10,
    popup: list | None = None,
    tooltip: list | None = None,
    min_width: int = 100,
    max_width: int = 200,
    **kwargs,
):
    """Adds a marker cluster to the map.

    Args:
        data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z
            values.
        x: The column name for the x values.
        y: The column name for the y values.
        radius: The radius of the circle.
        popup: A list of column names to be used as the popup.
        tooltip: A list of column names to be used as the tooltip.
        min_width: The minimum width of the popup.
        max_width: The maximum width of the popup.
    """
    data = coreutils.github_raw_url(data)

    if isinstance(data, pd.DataFrame):
        df = data
    elif not data.startswith(("http://", "https://")) 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 "color" not in kwargs:
        kwargs["color"] = None
    if "fill" not in kwargs:
        kwargs["fill"] = True
    if "fill_color" not in kwargs:
        kwargs["fill_color"] = "blue"
    if "fill_opacity" not in kwargs:
        kwargs["fill_opacity"] = 0.7

    if popup is None:
        popup = col_names

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

    if tooltip is not None:
        if not isinstance(tooltip, list):
            tooltip = [tooltip]

    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 _ in df.itertuples():
        html = ""
        for p in popup:
            html = (
                html
                + "<b>"
                + p
                + "</b>"
                + ": "
                + str(eval(str("row." + p)))
                + "<br>"
            )
        popup_html = folium.Popup(html, min_width=min_width, max_width=max_width)

        if tooltip is not None:
            html = ""
            for p in tooltip:
                html = (
                    html
                    + "<b>"
                    + p
                    + "</b>"
                    + ": "
                    + str(eval(str("row." + p)))
                    + "<br>"
                )

            tooltip_str = folium.Tooltip(html)
        else:
            tooltip_str = None

        folium.CircleMarker(
            location=[eval(f"row.{y}"), eval(f"row.{x}")],
            radius=radius,
            popup=popup_html,
            tooltip=tooltip_str,
            **kwargs,
        ).add_to(self)

`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
`name`	`str`	The layer name to use for the layer.	`'Untitled'`
`attribution`	`str`	The attribution to use.	`'.'`
`opacity`	`float`	The opacity of the layer.	`1.0`
`shown`	`bool`	A flag indicating whether the layer should be on by default.	`True`
`bands`	`list[str] \| None`	A list of bands to use.	`None`
`titiler_endpoint`		Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`None`

Source code in geemap/foliumap.py

def add_cog_layer(
    self,
    url: str,
    name: str = "Untitled",
    attribution: str = ".",
    opacity: float = 1.0,
    shown: bool = True,
    bands: list[str] | None = None,
    titiler_endpoint=None,
    **kwargs,
) -> None:
    """Adds a COG TileLayer to the map.

    Args:
        urlThe URL of the COG tile layer.
        name: The layer name to use for the layer.
        attribution: The attribution to use.
        opacity: The opacity of the layer.
        shown: A flag indicating whether the layer should be on by default.
        bands: A list of bands to use.
        titiler_endpoint: Titiler endpoint.
            Defaults to "https://giswqs-titiler-endpoint.hf.space".
    """
    tile_url = cog_tile(url, bands, titiler_endpoint, **kwargs)
    bounds = cog_bounds(url, titiler_endpoint)
    self.add_tile_layer(
        tiles=tile_url,
        name=name,
        attribution=attribution,
        opacity=opacity,
        shown=shown,
    )
    self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

`add_colorbar(vis_params, index=None, label='', categorical=False, step=None, background_color=None, **kwargs)` ¶

Add a colorbar to the map.

Parameters:

Name	Type	Description	Default
`vis_params`		TODO.	required
`index`	`list \| None`	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.	`None`
`label`	`str`	The caption for the colormap.	`''`
`categorical`	`bool`	Whether or not to create a categorical colormap.	`False`
`step`	`int \| None`	The step to split the LinearColormap into a StepColormap.	`None`
`background_color`		TODO.	`None`
`# TODO`		Fix - these are in vis_params and are not normal args:	required
`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.	required
`vmax`	`float`	The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1]. Defaults to 1.0.	required

Source code in geemap/foliumap.py

def add_colorbar(
    self,
    vis_params,
    index: list | None = None,
    label: str = "",
    categorical: bool = False,
    step: int | None = None,
    background_color=None,
    **kwargs,
) -> None:
    """Add a colorbar to the map.

    Args:
        vis_params: TODO.
        index: 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.
        label: The caption for the colormap.
        categorical: Whether or not to create a categorical colormap.
        step: The step to split the LinearColormap into a StepColormap.
        background_color: TODO.
        # TODO: Fix - these are in vis_params and are not normal 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.
    """
    from branca.colormap import LinearColormap

    del kwargs  # Unused.

    if not isinstance(vis_params, dict):
        raise ValueError("vis_params must be a dictionary.")

    if "palette" not in vis_params:
        raise ValueError("vis_params must contain a palette.")

    if "min" not in vis_params:
        vis_params["min"] = 0
    if "max" not in vis_params:
        vis_params["max"] = 1

    colors = coreutils.to_hex_colors(coreutils.check_cmap(vis_params["palette"]))
    vmin = vis_params["min"]
    vmax = vis_params["max"]

    if isinstance(colors, box.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=label
    )

    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)

    if background_color is not None:
        svg_style = (
            "<style>svg {background-color: " + background_color + ";}</style>"
        )

        self.get_root().header.add_child(folium.Element(svg_style))

    self.add_child(colormap)

`add_colormap(width=4.0, height=0.3, vmin=0.0, vmax=1.0, palette=None, vis_params=None, cmap='gray', discrete=False, label=None, label_size=10, label_weight='normal', tick_size=8, bg_color='white', orientation='horizontal', dpi='figure', transparent=False, position=(70, 5), **kwargs)` ¶

Add a colorbar to the map.

Under the hood, it uses matplotlib to generate the colorbar, save it as a png file, and add it to the map using m.add_image().

Parameters:

Name	Type	Description	Default
`width`	`float`	Width of the colorbar in inches.	`4.0`
`height`	`float`	Height of the colorbar in inches.	`0.3`
`vmin`	`float`	Minimum value of the colorbar.	`0.0`
`vmax`	`float`	Maximum value of the colorbar.	`1.0`
`palette`	`list`	List of colors to use for the colorbar. It can also be a cmap name, such as ndvi, ndwi, dem, coolwarm.	`None`
`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. 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.	`False`
`label`	`str \| None`	Label for the colorbar.	`None`
`label_size`	`int`	Font size for the colorbar label.	`10`
`label_weight`	`str`	Font weight for the colorbar label, can be "normal", "bold", etc.	`'normal'`
`tick_size`	`int`	Font size for the colorbar tick labels.	`8`
`bg_color`	`str`	Background color for the colorbar.	`'white'`
`orientation`	`str`	Orientation of the colorbar, such as "vertical" and "horizontal".	`'horizontal'`
`dpi`	`float \| str`	The resolution in dots per inch. If 'figure', use the figure's dpi value.	`'figure'`
`transparent`	`bool`	Whether to make the background transparent.	`False`
`position`	`tuple`	The position of the colormap in the format of (x, y), the percentage ranging from 0 to 100, starting from the lower-left corner.	`(70, 5)`
`**kwargs`		Other keyword arguments to pass to matplotlib.pyplot.savefig().	`{}`

Returns:

Name	Type	Description
`str`		Path to the output image.

Source code in geemap/foliumap.py

def add_colormap(
    self,
    width: float = 4.0,
    height: float = 0.3,
    vmin: float = 0.0,
    vmax: float = 1.0,
    palette=None,
    vis_params=None,
    cmap: str = "gray",
    discrete: bool = False,
    label: str | None = None,
    label_size: int = 10,
    label_weight: str = "normal",
    tick_size: int = 8,
    bg_color: str = "white",
    orientation: str = "horizontal",
    dpi: float | str = "figure",
    transparent: bool = False,
    position=(70, 5),
    **kwargs,
):
    """Add a colorbar to the map.

    Under the hood, it uses matplotlib to generate the colorbar, save it as a png
    file, and add it to the map using m.add_image().

    Args:
        width: Width of the colorbar in inches.
        height: Height of the colorbar in inches.
        vmin: Minimum value of the colorbar.
        vmax: Maximum value of the colorbar.
        palette (list): List of colors to use for the colorbar. It can also be a
            cmap name, such as ndvi, ndwi, dem, coolwarm.
        vis_params (dict): Visualization parameters as a dictionary. See
            https://developers.google.com/earth-engine/guides/image_visualization for
            options.
        cmap: Matplotlib colormap. See
            https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py
            for options.
        discrete: Whether to create a discrete colorbar.
        label: Label for the colorbar.
        label_size: Font size for the colorbar label.
        label_weight: Font weight for the colorbar label, can be "normal", "bold",
            etc.
        tick_size: Font size for the colorbar tick labels.
        bg_color: Background color for the colorbar.
        orientation: Orientation of the colorbar, such as "vertical" and
            "horizontal".
        dpi: The resolution in dots per inch. If 'figure', use the figure's dpi
            value.
        transparent: Whether to make the background transparent.
        position (tuple, optional): The position of the colormap in the format of
            (x, y), the percentage ranging from 0 to 100, starting from the
            lower-left corner.
        **kwargs: Other keyword arguments to pass to matplotlib.pyplot.savefig().

    Returns:
        str: Path to the output image.
    """
    colorbar = save_colorbar(
        None,
        width,
        height,
        vmin,
        vmax,
        palette,
        vis_params,
        cmap,
        discrete,
        label,
        label_size,
        label_weight,
        tick_size,
        bg_color,
        orientation,
        dpi,
        transparent,
        show_colorbar=False,
        **kwargs,
    )

    self.add_image(colorbar, position=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, style_function=None, highlight_function=None, layer_name='Untitled', 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`		The name of a colormap recognized by matplotlib.	`None`
`colors`		A list of colors to use for the classification.	`None`
`labels`		A list of labels to use for the legend.	`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).	`5`
`legend_kwds`	`dict`	Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or `matplotlib.pyplot.colorbar`. 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.	`None`
`style_function`	`function`	Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. 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"]} 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`
`highlight_function`	`function`	Highlighting function that is called for each feature, and should return the feature style. This styling function takes the feature as argument. highlight_function is a function that takes the feature as argument and should return a dictionary of the following form: highlight_function = lambda feat: {"fillColor": feat["properties"]["color"]}	`None`
`layer_name`	`str`	The layer name to be used.	`'Untitled'`
`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.	`'on_hover'`
`encoding`	`str`	The encoding of the GeoJSON file.	`'utf-8'`

Source code in geemap/foliumap.py

def add_data(
    self,
    data,
    column: str,
    colors=None,
    labels=None,
    cmap=None,
    scheme: str = "Quantiles",
    k: int = 5,
    add_legend=True,
    legend_title=None,
    legend_kwds=None,
    classification_kwds=None,
    style_function=None,
    highlight_function=None,
    layer_name: str = "Untitled",
    info_mode: str = "on_hover",
    encoding: str = "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: The column to classify.
        cmap: The name of a colormap recognized by matplotlib.
        colors: A list of colors to use for the classification.
        labels: A list of labels to use for the legend.
        scheme: 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: Number of classes (ignored if scheme is None or if column is
            categorical).
        legend_kwds (dict, optional): Keyword arguments to pass to
            :func:`matplotlib.pyplot.legend` or
            `matplotlib.pyplot.colorbar`.
            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.
        style_function (function, optional): Styling function that is called for
            each feature, and should return the feature style. This styling function
            takes the feature as argument. 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"]}
                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,
                }
        highlight_function (function, optional): Highlighting function that is
            called for each feature, and should return the feature style. This
            styling function takes the feature as argument.
            highlight_function is a function that takes the feature as argument and
            should return a dictionary of the following form:
                highlight_function = lambda feat: {"fillColor": feat["properties"]["color"]}
        layer_name: The layer name to be used.
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
        encoding: The encoding of the GeoJSON file.

    """
    gdf, legend_dict = classify(  # pytype: disable=attribute-error
        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" in kwargs:
        warnings.warn(
            "The style arguments is for ipyleaflet only. ",
            UserWarning,
        )
        kwargs.pop("style")

    if "hover_style" in kwargs:
        warnings.warn(
            "The hover_style arguments is for ipyleaflet only. ",
            UserWarning,
        )
        kwargs.pop("hover_style")

    if "style_callback" in kwargs:
        warnings.warn(
            "The style_callback arguments is for ipyleaflet only. ",
            UserWarning,
        )
        kwargs.pop("style_callback")

    if style_function is None:
        style_function = lambda feat: {
            # "stroke": False,
            # "color": "#ff0000",
            "weight": 1,
            "opacity": 1,
            # "fill": True,
            # "fillColor": "#ffffff",
            "fillOpacity": 1.0,
            # "dashArray": "9"
            # "clickable": True,
            "fillColor": feat["properties"]["color"],
        }

    if highlight_function is None:
        highlight_function = lambda feat: {
            "weight": 2,
            "fillOpacity": 0.5,
        }

    self.add_gdf(
        gdf,
        layer_name=layer_name,
        style_function=style_function,
        highlight_function=highlight_function,
        info_mode=info_mode,
        encoding=encoding,
        **kwargs,
    )
    if add_legend:
        self.add_legend(title=legend_title, legend_dict=legend_dict)

`add_gdf(gdf, layer_name='Untitled', zoom_to_layer=True, info_mode='on_hover', fields=None, **kwargs)` ¶

Adds a GeoPandas GeoDataFrame to the map.

Parameters:

Name	Type	Description	Default
`gdf`	`GeoDataFrame`	A GeoPandas GeoDataFrame.	required
`layer_name`	`str`	The layer name to be used.	`'Untitled'`
`zoom_to_layer`	`bool`	Whether to zoom to the layer.	`True`
`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.	`'on_hover'`
`fields`	`list \| None`	The fields to be displayed in the popup.	`None`

Source code in geemap/foliumap.py

def add_gdf(
    self,
    gdf,
    layer_name: str = "Untitled",
    zoom_to_layer: bool = True,
    info_mode: str = "on_hover",
    fields: list | None = None,
    **kwargs,
) -> None:
    """Adds a GeoPandas GeoDataFrame to the map.

    Args:
        gdf (GeoDataFrame): A GeoPandas GeoDataFrame.
        layer_name: The layer name to be used.
        zoom_to_layer: Whether to zoom to the layer.
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
        fields: The fields to be displayed in the popup.

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

    self.add_geojson(
        data, layer_name=layer_name, info_mode=info_mode, fields=fields, **kwargs
    )

    if zoom_to_layer:
        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', zoom_to_layer=True, **kwargs)` ¶

Adds a GeoPandas GeoDataFrameto 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.	`'Untitled'`
`zoom_to_layer`	`bool`	Whether to zoom to the layer.	`True`

Source code in geemap/foliumap.py

def add_gdf_from_postgis(
    self,
    sql: str,
    con,
    layer_name: str = "Untitled",
    zoom_to_layer: bool = True,
    **kwargs,
):
    """Adds a GeoPandas GeoDataFrameto the map.

    Args:
        sql: 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: The layer name to be used.
        zoom_to_layer: Whether to zoom to the layer.
    """
    if "fill_colors" in kwargs:
        kwargs.pop("fill_colors")
    gdf = read_postgis(sql, con, **kwargs)
    data = gdf_to_geojson(gdf, epsg="4326")

    self.add_geojson(data, layer_name=layer_name, **kwargs)

    if zoom_to_layer:
        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_geojson(in_geojson, layer_name='Untitled', encoding='utf-8', info_mode='on_hover', fields=None, **kwargs)` ¶

Adds a GeoJSON file to the map.

Parameters:

Name	Type	Description	Default
`in_geojson`	`str`	The input file path to the GeoJSON.	required
`layer_name`	`str`	The layer name to be used.	`'Untitled'`
`encoding`	`str`	The encoding of the GeoJSON file.	`'utf-8'`
`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.	`'on_hover'`
`fields`	`list`	The fields to be displayed in the popup.	`None`

Raises:

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

Source code in geemap/foliumap.py

def add_geojson(
    self,
    in_geojson: str,
    layer_name: str = "Untitled",
    encoding: str = "utf-8",
    info_mode: str = "on_hover",
    fields=None,
    **kwargs,
):
    """Adds a GeoJSON file to the map.

    Args:
        in_geojson: The input file path to the GeoJSON.
        layer_name: The layer name to be used.
        encoding: The encoding of the GeoJSON file.
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
        fields (list, optional): The fields to be displayed in the popup.

    Raises:
        FileNotFoundError: The provided GeoJSON file could not be found.
    """
    try:
        if isinstance(in_geojson, str):
            if in_geojson.startswith(("http://", "https://")):
                in_geojson = coreutils.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)

    # Interchangeable parameters between ipyleaflet and folium.
    if "style_function" not in kwargs:
        if "style" in kwargs:
            style_dict = kwargs["style"]
            if isinstance(kwargs["style"], dict) and len(kwargs["style"]) > 0:
                kwargs["style_function"] = lambda x: style_dict
            kwargs.pop("style")
        else:
            style_dict = {
                # "stroke": True,
                "color": "#000000",
                "weight": 1,
                "opacity": 1,
                # "fill": True,
                # "fillColor": "#ffffff",
                "fillOpacity": 0.1,
                # "dashArray": "9"
                # "clickable": True,
            }
            kwargs["style_function"] = lambda x: style_dict

    if "style_callback" in kwargs:
        kwargs.pop("style_callback")

    if "hover_style" in kwargs:
        kwargs.pop("hover_style")

    if "fill_colors" in kwargs:
        fill_colors = kwargs["fill_colors"]

        def random_color(feature):
            del feature  # Unused.
            style_dict["fillColor"] = random.choice(fill_colors)
            return style_dict

        kwargs["style_function"] = random_color
        kwargs.pop("fill_colors")

    if "highlight_function" not in kwargs:
        kwargs["highlight_function"] = lambda feat: {
            "weight": 2,
            "fillOpacity": 0.5,
        }

    tooltip = None
    popup = None
    if info_mode is not None:
        if fields is None:
            fields = list(data["features"][0]["properties"].keys())
        if info_mode == "on_hover":
            tooltip = folium.GeoJsonTooltip(fields=fields)
        elif info_mode == "on_click":
            popup = folium.GeoJsonPopup(fields=fields)

    geojson = folium.GeoJson(
        data=data, name=layer_name, tooltip=tooltip, popup=popup, **kwargs
    )
    geojson.add_to(self)

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

Adds a heat map to the map.

Reference: https://stackoverflow.com/a/54756617

Parameters:

Name	Type	Description	Default
`data`	`str \| list[Any] \| 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.	`'latitude'`
`longitude`	`str`	The column name of longitude.	`'longitude'`
`value`	`str`	The column name of values.	`'value'`
`name`	`str`	Layer name to use.	`'Heat map'`
`radius`	`int`	Radius of each “point” of the heatmap.	`25`

Raises:

Type	Description
`ValueError`	If data is not a list.

Source code in geemap/foliumap.py

def add_heatmap(
    self,
    data: str | list[Any] | pd.DataFrame,
    latitude: str = "latitude",
    longitude: str = "longitude",
    value: str = "value",
    name: str = "Heat map",
    radius: int = 25,
    **kwargs,
):
    """Adds a heat map to the map.

    Reference: https://stackoverflow.com/a/54756617

    Args:
        data: 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: The column name of latitude.
        longitude: The column name of longitude.
        value: The column name of values.
        name: Layer name to use.
        radius: Radius of each “point” of the heatmap.

    Raises:
        ValueError: If data is not a list.
    """
    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.")

    plugins.HeatMap(data, name=name, radius=radius, **kwargs).add_to(
        folium.FeatureGroup(name=name).add_to(self)
    )

`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 widget.	`'bottomright'`

Source code in geemap/foliumap.py

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

    Args:
        html: The HTML to add.
        position: The position of the widget.
    """

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

`add_image(image, position=(0, 0), **kwargs)` ¶

Add an image to the map.

Parameters:

Name	Type	Description	Default
`image`	`str \| Image`	The image to add.	required
`position`	`tuple`	The position of the image in the format of (x, y), the percentage ranging from 0 to 100, starting from the lower-left corner.	`(0, 0)`

Source code in geemap/foliumap.py

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

    Args:
        image (str | ipywidgets.Image): The image to add.
        position (tuple, optional): The position of the image in the format of (x, y),
            the percentage ranging from 0 to 100, starting from the lower-left corner.
    """
    if isinstance(image, str):
        if image.startswith(("http://", "https://")):
            html = f'<img src="{image}">'
            if isinstance(position, tuple):
                position = "bottomright"
            self.add_html(html, position=position, **kwargs)

        elif os.path.exists(image):
            if position == "bottomleft":
                position = (5, 5)
            elif position == "bottomright":
                position = (80, 5)
            elif position == "topleft":
                position = (5, 60)
            elif position == "topright":
                position = (80, 60)

            with open(image, "rb") as lf:
                # open in binary mode, read bytes, encode, decode obtained bytes as utf-8 string
                b64_content = base64.b64encode(lf.read()).decode("utf-8")
                widget = plugins.FloatImage(
                    f"data:image/png;base64,{b64_content}",
                    bottom=position[1],
                    left=position[0],
                )
                widget.add_to(self)

    else:
        raise Exception("Invalid image")

`add_kml(in_kml, layer_name='Untitled', info_mode='on_hover', fields=None, **kwargs)` ¶

Adds a KML 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.	`'Untitled'`
`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.	`'on_hover'`
`fields`	`list \| None`	The fields to be displayed in the popup.	`None`

Raises:

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

Source code in geemap/foliumap.py

def add_kml(
    self,
    in_kml: str,
    layer_name: str = "Untitled",
    info_mode: str = "on_hover",
    fields: list | None = None,
    **kwargs,
) -> None:
    """Adds a KML file to the map.

    Args:
        in_kml: The input file path to the KML.
        layer_name: The layer name to be used.
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
        fields: The fields to be displayed in the popup.

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

    """
    if in_kml.startswith(("http://", "https://")) and in_kml.endswith(".kml"):
        out_dir = os.path.abspath("./cache")
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)
        download_from_url(in_kml, out_dir=out_dir, unzip=False, verbose=False)
        in_kml = os.path.join(out_dir, os.path.basename(in_kml))
        if not os.path.exists(in_kml):
            raise FileNotFoundError("The downloaded kml file could not be found.")
    else:
        in_kml = os.path.abspath(in_kml)
        if not os.path.exists(in_kml):
            raise FileNotFoundError("The provided KML could not be found.")

    data = kml_to_geojson(in_kml)

    self.add_geojson(
        data, layer_name=layer_name, info_mode=info_mode, fields=fields, **kwargs
    )

`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://python-visualization.github.io/folium/modules.html#folium.features.DivIcon

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.	`'12pt'`
`font_color`	`str`	The font color of the labels.	`'black'`
`font_family`	`str`	The font family of the labels.	`'arial'`
`font_weight`	`str`	The font weight of the labels, can be normal, bold.	`'normal'`
`x`	`str`	The column name of the longitude.	`'longitude'`
`y`	`str`	The column name of the latitude.	`'latitude'`
`draggable`	`bool`	Whether the labels are draggable.	`True`
`layer_name`	`str`	The name of the layer.	`'Labels'`

Source code in geemap/foliumap.py

def add_labels(
    self,
    data,
    column: str,
    font_size: str = "12pt",
    font_color: str = "black",
    font_family: str = "arial",
    font_weight: str = "normal",
    x: str = "longitude",
    y: str = "latitude",
    draggable: bool = True,
    layer_name: str = "Labels",
    **kwargs,
):
    """Adds a label layer to the map.

    Reference:
    https://python-visualization.github.io/folium/modules.html#folium.features.DivIcon

    Args:
        data (pd.DataFrame | ee.FeatureCollection): The input data to label.
        column: The column name of the data to label.
        font_size: The font size of the labels.
        font_color: The font color of the labels.
        font_family: The font family of the labels.
        font_weight: The font weight of the labels, can be normal, bold.
        x: The column name of the longitude.
        y: The column name of the latitude.
        draggable: Whether the labels are draggable.
        layer_name: The name of the layer.
    """
    from folium.features import DivIcon

    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"]:
            import geopandas as gpd

            df = gpd.read_file(data)
            df[x] = df.centroid.x
            df[y] = df.centroid.y
    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 Exception as _:
        raise ValueError("font_size must be something like '10pt'")

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

    layer_group.add_to(self)

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

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

Parameters:

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

Source code in geemap/foliumap.py

def add_layer(
    self,
    ee_object,
    vis_params: dict[str, Any] | None = None,
    name: str = "Layer untitled",
    shown: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Adds a given EE object to the map as a layer.

    Args:
        ee_object (Collection|Feature|Image|MapId): The object to add to the map.
        vis_params: The visualization parameters. Defaults to {}.
        name: The name of the layer.
        shown: A flag indicating whether the layer should be on by default.
        opacity: The layer's opacity represented as a number between 0 and 1.
    """
    vis_params = vis_params or {}

    layer = ee_tile_layers.EEFoliumTileLayer(
        ee_object, vis_params, name, shown, opacity, **kwargs
    )
    layer.add_to(self)
    arc_add_layer(layer.url_format, name, shown, opacity)

`add_layer_control()` ¶

Adds layer control to the map.

Source code in geemap/foliumap.py

def add_layer_control(self):
    """Adds layer control to the map."""
    layer_ctrl = False
    for item in self.to_dict()["children"]:
        if item.startswith("layer_control"):
            layer_ctrl = True
            break
    if not layer_ctrl:
        folium.LayerControl().add_to(self)

`add_legend(title='Legend', labels=None, colors=None, legend_dict=None, builtin_legend=None, opacity=1.0, position='bottomright', draggable=True, style=None)` ¶

Adds a customized legend to the map.

Reference: https://bit.ly/3oV6vnH.

If you want to add multiple legends to the map, you need to set the draggable argument to False.

Parameters:

Name	Type	Description	Default
`title`	`str`	Title of the legend.	`'Legend'`
`colors`	`list`	A list of legend colors.	`None`
`labels`	`list`	A list of legend labels.	`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.	`None`
`builtin_legend`	`str \| None`	Name of the builtin legend to add to the map.	`None`
`opacity`	`float`	The opacity of the legend.	`1.0`
`position`	`str`	The position of the legend, can be one of the following: "topleft", "topright", "bottomleft", "bottomright".	`'bottomright'`
`draggable`	`bool`	If True, the legend can be dragged to a new position.	`True`
`style`	`dict[str, Any] \| None`	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' }	`None`

Source code in geemap/foliumap.py

def add_legend(
    self,
    title: str = "Legend",
    labels=None,
    colors=None,
    legend_dict=None,
    builtin_legend: str | None = None,
    opacity: float = 1.0,
    position: str = "bottomright",
    draggable: bool = True,
    style: dict[str, Any] | None = None,
):
    """Adds a customized legend to the map.

    Reference: https://bit.ly/3oV6vnH.

    If you want to add multiple legends to the map, you need to set the `draggable`
    argument to False.

    Args:
        title: Title of the legend.
        colors (list, optional): A list of legend colors.
        labels (list, optional): A list of legend labels.
        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.
        builtin_legend: Name of the builtin legend to add to the map.
        opacity: The opacity of the legend.
        position: The position of the legend, can be one of the following:
            "topleft", "topright", "bottomleft", "bottomright".
        draggable: If True, the legend can be dragged to a new position.
        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'
            }
    """
    style = style or {}

    content = create_legend(
        title,
        labels,
        colors,
        legend_dict,
        builtin_legend,
        opacity,
        position,
        draggable,
        style=style,
    )
    if draggable:
        from branca.element import MacroElement, Template

        content = (
            '"""\n{% macro html(this, kwargs) %}\n'
            + content
            + '\n{% endmacro %}"""'
        )

        macro = MacroElement()
        macro._template = Template(content)

        self.get_root().add_child(macro)
    else:
        self.add_html(content, position=position)

`add_marker(location, popup=None, tooltip=None, icon=None, draggable=False, **kwargs)` ¶

Adds a marker to the map.

More info about marker options at

https://python-visualization.github.io/folium/modules.html#folium.map.Marker.

Parameters:

Name	Type	Description	Default
`location`	`list \| tuple`	Location of the marker in the format of [lat, lng].	required
`popup`	`str \| None`	The popup text.	`None`
`tooltip`	`str \| None`	The tooltip text.	`None`
`icon`	`str \| None`	The icon to use.	`None`
`draggable`	`bool`	Whether the marker is draggable.	`False`

Source code in geemap/foliumap.py

def add_marker(
    self,
    location,
    popup: str | None = None,
    tooltip: str | None = None,
    icon: str | None = None,
    draggable: bool = False,
    **kwargs,
):
    """Adds a marker to the map.

    More info about marker options at

    https://python-visualization.github.io/folium/modules.html#folium.map.Marker.

    Args:
        location (list | tuple): Location of the marker in the format of [lat, lng].
        popup: The popup text.
        tooltip: The tooltip text.
        icon: The icon to use.
        draggable: Whether the marker is draggable.
    """
    if isinstance(location, list):
        location = tuple(location)
    if isinstance(location, tuple):
        folium.Marker(
            location=location,
            popup=popup,
            tooltip=tooltip,
            icon=icon,
            draggable=draggable,
            **kwargs,
        ).add_to(self)
    else:
        raise TypeError("The location must be a list or a tuple.")

`add_markers_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Markers', icon=None, icon_shape='circle-dot', border_width=3, border_color='#0000ff', **kwargs)` ¶

Adds markers to the map from a csv or Pandas DataFrame containing x, y values.

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.	`'longitude'`
`y`	`str`	The column name for the y values.	`'latitude'`
`popup`	`list \| None`	A list of column names to be used as the popup.	`None`
`min_width`	`int`	The minimum width of the popup.	`100`
`max_width`	`int`	The maximum width of the popup.	`200`
`layer_name`	`str`	The name of the layer.	`'Markers'`
`icon`	`str \| None`	The Font-Awesome icon name to use to render the marker.	`None`
`icon_shape`	`str`	The shape of the marker, such as "retangle-dot", "circle-dot".	`'circle-dot'`
`border_width`	`int`	The width of the border.	`3`
`border_color`	`str`	The color of the border.	`'#0000ff'`
`kwargs`		Additional keyword arguments to pass to BeautifyIcon. See https://python-visualization.github.io/folium/plugins.html#folium.plugins.BeautifyIcon.	`{}`

Source code in geemap/foliumap.py

def add_markers_from_xy(
    self,
    data,
    x: str = "longitude",
    y: str = "latitude",
    popup: list | None = None,
    min_width: int = 100,
    max_width: int = 200,
    layer_name: str = "Markers",
    icon: str | None = None,
    icon_shape: str = "circle-dot",
    border_width: int = 3,
    border_color: str = "#0000ff",
    **kwargs,
):
    """Adds markers to the map from a csv or Pandas DataFrame containing x, y values.

    Args:
        data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
        x: The column name for the x values.
        y: The column name for the y values.
        popup: A list of column names to be used as the popup.
        min_width: The minimum width of the popup.
        max_width: The maximum width of the popup.
        layer_name: The name of the layer.
        icon: The Font-Awesome icon name to use to render the marker.
        icon_shape: The shape of the marker, such as "retangle-dot",
            "circle-dot".
        border_width: The width of the border.
        border_color: The color of the border.
        kwargs: Additional keyword arguments to pass to BeautifyIcon. See
            https://python-visualization.github.io/folium/plugins.html#folium.plugins.BeautifyIcon.
    """
    from folium.plugins import BeautifyIcon

    layer_group = folium.FeatureGroup(name=layer_name)

    if isinstance(data, pd.DataFrame):
        df = data
    elif not data.startswith(("http://", "https://")) 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 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 = folium.Popup(html, min_width=min_width, max_width=max_width)

        marker_icon = BeautifyIcon(
            icon, icon_shape, border_width, border_color, **kwargs
        )
        folium.Marker(  # pytype: disable=wrong-arg-types
            location=[getattr(row, y), getattr(row, x)],
            popup=popup_html,
            icon=marker_icon,
        ).add_to(layer_group)

    layer_group.add_to(self)

`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`	`list[str] \| None`	The variable/band names to extract data from the netCDF file. If None, all variables will be extracted.	`None`
`palette`	`str \| None`	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 \| None`	The minimum value to use when colormapping the palette when plotting a single band.	`None`
`vmax`	`float \| None`	The maximum value to use when colormapping the palette when plotting a single band.	`None`
`nodata`	`float \| None`	The value from the band to use to interpret as not valid data.	`None`
`attribution`	`str \| None`	Attribution for the source raster. This defaults to a message about it being a local file.	`None`
`layer_name`	`str`	The layer name to use.	`'NetCDF layer'`
`shift_lon`	`bool`	Flag to shift longitude values from [0, 360] to the range [-180, 180].	`True`
`lat`	`str`	Name of the latitude variable.	`'lat'`
`lon`	`str`	Name of the longitude variable.	`'lon'`

Source code in geemap/foliumap.py

def add_netcdf(
    self,
    filename: str,
    variables: list[str] | None = None,
    palette: str | None = None,
    vmin: float | None = None,
    vmax: float | None = None,
    nodata: float | None = None,
    attribution: str | None = None,
    layer_name: str = "NetCDF layer",
    shift_lon: bool = True,
    lat: str = "lat",
    lon: str = "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: File path or HTTP URL to the netCDF file.
        variables: The variable/band names to extract data from the netCDF
            file. If None, all variables will be extracted.
        palette: 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: The minimum value to use when colormapping the palette when plotting a
            single band.
        vmax: The maximum value to use when colormapping the palette when plotting a
            single band.
        nodata: The value from the band to use to interpret as not valid
            data.
        attribution: Attribution for the source raster. This defaults to a message
            about it being a local file.
        layer_name: The layer name to use.
        shift_lon: Flag to shift longitude values from [0, 360] to the range [-180,
            180].
        lat: Name of the latitude variable.
        lon: Name of the longitude variable.
    """
    if coreutils.in_colab_shell():
        print("The add_netcdf() function is not supported in Colab.")
        return

    tif, vars = netcdf_to_tif(  # pylint: disable=redefined-builtin
        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', which_result=None, by_osmid=False, to_ee=False, geodesic=True, **kwargs)` ¶

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.	`'Untitled'`
`which_result`	`int \| None`	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.	`None`
`by_osmid`	`bool`	If True, handle query as an OSM ID for lookup rather than text search.	`False`
`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/foliumap.py

def add_osm(
    self,
    query,
    layer_name: str = "Untitled",
    which_result: int | None = None,
    by_osmid: bool = False,
    to_ee: bool = False,
    geodesic: bool = True,
    **kwargs,
) -> None:
    """Adds OSM data to the map.

    Args:
        query (str | dict | list): Query string(s) or structured dict(s) to geocode.
        layer_name: The layer name to be used.
        which_result: 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.
        by_osmid: If True, handle query as an OSM ID for lookup rather than text
            search.
        to_ee: Whether to convert the csv to an ee.FeatureCollection.
        geodesic: 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 = common.osm_to_gdf(query, which_result=which_result, by_osmid=by_osmid)
    geojson = gdf.__geo_interface__

    if to_ee:
        fc = coreutils.geojson_to_ee(geojson, geodesic=geodesic)
        self.addLayer(fc, {}, layer_name)
        self.centerObject(fc)
    else:
        self.add_geojson(geojson, layer_name=layer_name, **kwargs)
        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=None, hover_style=None, 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[str, Any]`	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.	`1000`
`layer_name`	`str`	The layer name to be used.	`'Untitled'`
`style`	`dict[str, Any] \| None`	A dictionary specifying the style to be used.	`None`
`hover_style`	`dict[str, Any] \| None`	Hover style dictionary. Defaults to {}.	`None`
`style_callback`		Styling function that is called for each feature, and should return the feature style. This styling function takes the feature as argument.	`None`
`fill_colors`	`list[str]`	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.	`'on_hover'`

Source code in geemap/foliumap.py

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

    Args:
        address: The address to geocode and use as the central point around which to
            get the geometries.
        tags: 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: Distance in meters.
        layer_name: The layer name to be used.
        style: A dictionary specifying the style to be used.
        hover_style: Hover style dictionary. Defaults to {}.
        style_callback: Styling function that is called for each feature, and should
            return the feature style. This styling function takes the feature as
            argument.
        fill_colors: The random colors to use for filling polygons. Defaults to
            ["black"].
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
    """
    style = style or {}
    hover_style = hover_style or {}

    gdf = osm.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=None, hover_style=None, 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.	`'Untitled'`
`style`	`dict[str, Any] \| None`	A dictionary specifying the style to be used. Defaults to {}.	`None`
`hover_style`	`dict[str, Any] \| None`	Hover style dictionary. Defaults to {}.	`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.	`None`
`fill_colors`	`list[str]`	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.	`'on_hover'`

Source code in geemap/foliumap.py

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

    Args:
        north: Northern latitude of bounding box.
        south: Southern latitude of bounding box.
        east: Eastern longitude of bounding box.
        west: Western longitude of bounding box.
        tags: 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: The layer name to be used.
        style: A dictionary specifying the style to be used. Defaults to {}.
        hover_style: 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.
        fill_colors: The random colors to use for filling polygons. Defaults to
            ["black"].
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
    """
    style = style or {}
    hover_style = hover_style or {}

    gdf = osm.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, layer_name='Untitled', style=None, hover_style=None, 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 \| None`	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.	`None`
`by_osmid`	`bool`	If True, handle query as an OSM ID for lookup rather than text search.	`False`
`layer_name`	`str`	The layer name to be used.	`'Untitled'`
`style`	`dict[str, Any] \| None`	A dictionary specifying the style to be used. Defaults to {}.	`None`
`hover_style`	`dict[str, Any] \| None`	Hover style dictionary.	`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.	`None`
`fill_colors`	`list[str]`	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.	`'on_hover'`

Source code in geemap/foliumap.py

def add_osm_from_geocode(
    self,
    query,
    which_result: int | None = None,
    by_osmid: bool = False,
    layer_name: str = "Untitled",
    style: dict[str, Any] | None = None,
    hover_style: dict[str, Any] | None = None,
    style_callback=None,
    fill_colors: list[str] = ["black"],
    info_mode: str = "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: 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.
        by_osmid: If True, handle query as an OSM ID for lookup rather than text
            search.
        layer_name: The layer name to be used.
        style: A dictionary specifying the style to be used. Defaults to {}.
        hover_style: Hover style dictionary.
        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.
        fill_colors: The random colors to use for filling polygons. Defaults to
            ["black"].
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
    """
    style = style or {}
    hover_style = hover_style or {}

    gdf = osm.osm_gdf_from_geocode(
        query, which_result=which_result, by_osmid=by_osmid
    )
    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, layer_name='Untitled', style=None, hover_style=None, 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 \| None`	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.	`None`
`layer_name`	`str`	The layer name to be used.	`'Untitled'`
`style`	`dict[str, Any] \| None`	A dictionary specifying the style to be used. Defaults to {}.	`None`
`hover_style`	`dict[str, Any] \| None`	Hover style dictionary. Defaults to {}.	`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.	`None`
`fill_colors`	`list[str]`	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.	`'on_hover'`

Source code in geemap/foliumap.py

def add_osm_from_place(
    self,
    query,
    tags: dict,
    which_result: int | None = None,
    layer_name: str = "Untitled",
    style: dict[str, Any] | None = None,
    hover_style: dict[str, Any] | None = None,
    style_callback=None,
    fill_colors: list[str] = ["black"],
    info_mode: str = "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 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: 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.
        layer_name: The layer name to be used.
        style: A dictionary specifying the style to be used. Defaults to {}.
        hover_style: 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.
        fill_colors: The random colors to use for filling polygons. Defaults to
            ["black"].
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
    """
    style = style or {}
    hover_style = hover_style or {}

    gdf = osm.osm_gdf_from_place(query, tags, which_result)
    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=None, hover_style=None, 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[float, float]`	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.	`1000`
`layer_name`	`str`	The layer name to be used.	`'Untitled'`
`style`	`dict[str, Any] \| None`	A dictionary specifying the style to be used. Defaults to {}.	`None`
`hover_style`	`dict[str, Any] \| None`	Hover style dictionary. Defaults to {}.	`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.	`None`
`fill_colors`	`list[str]`	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.	`'on_hover'`

Source code in geemap/foliumap.py

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

    Args:
        center_point: The (lat, lng) center point around which to get the
            geometries.
        tags: 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: Distance in meters.
        layer_name: The layer name to be used.
        style: A dictionary specifying the style to be used. Defaults to {}.
        hover_style: 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.
        fill_colors: The random colors to use for filling polygons. Defaults to ["black"].
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
    """
    style = style or {}
    hover_style = hover_style or {}

    gdf = osm.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=None, hover_style=None, 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.	`'Untitled'`
`style`	`dict[str, Any] \| None`	A dictionary specifying the style to be used. Defaults to {}.	`None`
`hover_style`	`dict[str, Any] \| None`	Hover style dictionary. Defaults to {}.	`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.	`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.	`'on_hover'`

Source code in geemap/foliumap.py

def add_osm_from_polygon(
    self,
    polygon,
    tags: dict,
    layer_name: str = "Untitled",
    style: dict[str, Any] | None = None,
    hover_style: dict[str, Any] | None = None,
    style_callback=None,
    fill_colors: list[str] = ["black"],
    info_mode: str = "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 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: The layer name to be used.
        style: A dictionary specifying the style to be used. Defaults to {}.
        hover_style: 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.
        fill_colors (list, optional): The random colors to use for filling
            polygons. Defaults to ["black"].
        info_mode: Displays the attributes by either on_hover or on_click. Any value
            other than "on_hover" or "on_click" will be treated as None.
    """
    style = style or {}
    hover_style = hover_style or {}

    gdf = osm.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_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.	`2016`
`month`	`int`	The month of Planet global mosaic, must be 1-12.	`1`
`name`	`str \| None`	The layer name to use.	`None`
`api_key`	`str \| None`	The Planet API key.	`None`
`token_name`	`str`	The environment variable name of the API key.	`'PLANET_API_KEY'`

Source code in geemap/foliumap.py

def add_planet_by_month(
    self,
    year: int = 2016,
    month: int = 1,
    name: str | None = None,
    api_key: str | None = None,
    token_name: str = "PLANET_API_KEY",
) -> None:
    """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: The year of Planet global mosaic, must be >=2016.
        month: The month of Planet global mosaic, must be 1-12.
        name: The layer name to use.
        api_key: The Planet API key.
        token_name: The environment variable name of the API key.
    """
    layer = planet_tile_by_month(
        year, month, name, api_key, token_name, tile_format="folium"
    )
    layer.add_to(self)

`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.	`2016`
`quarter`	`int`	The quarter of Planet global mosaic, must be 1-12.	`1`
`name`	`str \| None`	The layer name to use.	`None`
`api_key`	`str \| None`	The Planet API key.	`None`
`token_name`	`str`	The environment variable name of the API key.	`'PLANET_API_KEY'`

Source code in geemap/foliumap.py

def add_planet_by_quarter(
    self,
    year: int = 2016,
    quarter: int = 1,
    name: str | None = None,
    api_key: str | None = None,
    token_name: str = "PLANET_API_KEY",
) -> None:
    """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: The year of Planet global mosaic, must be >=2016.
        quarter: The quarter of Planet global mosaic, must be 1-12.
        name: The layer name to use.
        api_key: The Planet API key.
        token_name: The environment variable name of the API key.
    """
    layer = planet_tile_by_quarter(
        year, quarter, name, api_key, token_name, tile_format="folium"
    )
    layer.add_to(self)

`add_points_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Marker Cluster', color_column=None, marker_colors=None, icon_colors=['white'], icon_names=['info'], angle=0, prefix='fa', add_legend=True, max_cluster_radius=80, **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.	`'longitude'`
`y`	`str`	The column name for the y values.	`'latitude'`
`popup`	`list[str] \| None`	A list of column names to be used as the popup.	`None`
`min_width`	`int`	The minimum width of the popup.	`100`
`max_width`	`int`	The maximum width of the popup.	`200`
`layer_name`	`str`	The name of the layer.	`'Marker Cluster'`
`color_column`	`str \| None`	The column name for the color values.	`None`
`marker_colors`	`list \| None`	List of colors to be used for the markers.	`None`
`icon_colors`	`list[str]`	List of colors to be used for the icons. Defaults to ['white'].	`['white']`
`icon_names`	`list[str]`	A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons or https://getbootstrap.com/docs/3.3/components/?utm_source=pocket_mylist. Defaults to ['info'].	`['info']`
`angle`	`int`	The angle of the icon.	`0`
`prefix`	`str`	The prefix states the source of the icon. 'fa' for font-awesome or 'glyphicon' for bootstrap 3.	`'fa'`
`add_legend`	`bool`	If True, a legend will be added to the map.	`True`
`max_cluster_radius`	`int`	The maximum radius that a cluster will cover from the central marker (in pixels).	`80`
`**kwargs`		Other keyword arguments to pass to folium.MarkerCluster(). For a list of available options, see https://github.com/Leaflet/Leaflet.markercluster. For example, to change the cluster radius, use options={"maxClusterRadius": 50}.	`{}`

Source code in geemap/foliumap.py

def add_points_from_xy(
    self,
    data: str | pd.DataFrame,
    x: str = "longitude",
    y: str = "latitude",
    popup: list[str] | None = None,
    min_width: int = 100,
    max_width: int = 200,
    layer_name: str = "Marker Cluster",
    color_column: str | None = None,
    marker_colors: list | None = None,
    icon_colors: list[str] = ["white"],
    icon_names: list[str] = ["info"],
    angle: int = 0,
    prefix: str = "fa",
    add_legend: bool = True,
    max_cluster_radius: int = 80,
    **kwargs,
):
    """Adds a marker cluster to the map.

    Args:
        data: A csv or Pandas DataFrame containing x, y, z values.
        x: The column name for the x values.
        y: The column name for the y values.
        popup: A list of column names to be used as the popup.
        min_width: The minimum width of the popup.
        max_width: The maximum width of the popup.
        layer_name: The name of the layer.
        color_column: The column name for the color values.
        marker_colors: List of colors to be used for the markers.
        icon_colors: List of colors to be used for the icons. Defaults to ['white'].
        icon_names: A list of names to be used for the icons. More icons can be
            found at https://fontawesome.com/v4/icons or
            https://getbootstrap.com/docs/3.3/components/?utm_source=pocket_mylist. Defaults
            to ['info'].
        angle: The angle of the icon.
        prefix: The prefix states the source of the icon. 'fa' for font-awesome or
            'glyphicon' for bootstrap 3.
        add_legend: If True, a legend will be added to the map.
        max_cluster_radius: The maximum radius that a cluster will cover from the
            central marker (in pixels).
        **kwargs: Other keyword arguments to pass to folium.MarkerCluster(). For a
            list of available options, see
            https://github.com/Leaflet/Leaflet.markercluster. For example, to change
            the cluster radius, use options={"maxClusterRadius": 50}.
    """
    if "maxClusterRadius" not in kwargs:
        kwargs["maxClusterRadius"] = max_cluster_radius

    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://", "https://")) 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 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 popup is None:
        popup = col_names

    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)}")

    marker_cluster = plugins.MarkerCluster(name=layer_name, **kwargs).add_to(self)

    for idx, row in df.iterrows():
        html = ""
        for p in popup:
            html = html + "<b>" + p + "</b>" + ": " + str(row[p]) + "<br>"
        popup_html = folium.Popup(html, min_width=min_width, max_width=max_width)

        if items is not None:
            index = items.index(row[color_column])
            marker_icon = folium.Icon(
                color=marker_colors[index],
                icon_color=icon_colors[index],
                icon=icon_names[index],
                angle=angle,
                prefix=prefix,
            )
        else:
            marker_icon = None

        folium.Marker(
            location=[row[y], row[x]],
            popup=popup_html,
            icon=marker_icon,
        ).add_to(marker_cluster)

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

`add_raster(source, indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Raster', array_args=None, **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 \| None`	The band(s) to use. Band indexing starts at 1.	`None`
`colormap`	`str \| None`	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 \| None`	The minimum value to use when colormapping the colormap when plotting a single band.	`None`
`vmax`	`float \| None`	The maximum value to use when colormapping the colormap when plotting a single band.	`None`
`nodata`	`float \| None`	The value from the band to use to interpret as not valid data.	`None`
`attribution`	`str \| None`	Attribution for the source raster. This defaults to a message about it being a local file.	`None`
`layer_name`	`str \| None`	The layer name to use.	`'Raster'`
`array_args`	`dict \| None`	Additional arguments to pass to `array_to_image`. Defaults to {}.	`None`

Source code in geemap/foliumap.py

def add_raster(
    self,
    source: str,
    indexes: int | None = None,
    colormap: str | None = None,
    vmin: float | None = None,
    vmax: float | None = None,
    nodata: float | None = None,
    attribution: str | None = None,
    layer_name: str | None = "Raster",
    array_args: dict | None = None,
    **kwargs,
) -> None:
    """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: The path to the GeoTIFF file or the URL of the Cloud Optimized
            GeoTIFF.
        indexes: The band(s) to use. Band indexing starts at 1.
        colormap: 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: The minimum value to use when colormapping the colormap when plotting
            a single band.
        vmax: The maximum value to use when colormapping the colormap when plotting
            a single band.
        nodata: The value from the band to use to interpret as not valid data.
        attribution: Attribution for the source raster. This defaults to a message
            about it being a local file.
        layer_name: The layer name to use.
        array_args: Additional arguments to pass to `array_to_image`.
            Defaults to {}.
    """
    array_args = array_args or {}

    if isinstance(source, (np.ndarray, 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,
        tile_format="folium",
        layer_name=layer_name,
        return_client=True,
        **kwargs,
    )
    tile_layer.add_to(self)

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

    arc_add_layer(tile_layer.tiles, layer_name, True, 1.0)
    arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

`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 \| None`	The band to use. Band indexing starts at 1.	`None`
`palette`	`str \| None`	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 \| None`	The minimum value to use when colormapping the palette when plotting a single band.	`None`
`vmax`	`float \| None`	The maximum value to use when colormapping the palette when plotting a single band.	`None`
`nodata`	`float \| None`	The value from the band to use to interpret as not valid data.	`None`
`attribution`	`str \| None`	Attribution for the source raster. This defaults to a message about it being a local file.	`None`
`layer_name`	`str \| None`	The layer name to use.	`None`

Source code in geemap/foliumap.py

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

    Args:
        source: The path to the remote Cloud Optimized GeoTIFF.
        band: The band to use. Band indexing starts at 1.
        palette: 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: The minimum value to use when colormapping the palette when plotting a
            single band.
        vmax: The maximum value to use when colormapping the palette when plotting a
            single band.
        nodata: The value from the band to use to interpret as not valid
            data.
        attribution: Attribution for the source raster. This defaults to a message
            about it being a local file.
        layer_name: The layer name to use.
    """
    if isinstance(source, str) and source.startswith(("http://", "https://")):
        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_shapefile(in_shp, layer_name='Untitled', **kwargs)` ¶

Adds a shapefile to the map.

See https://python-visualization.github.io/folium/modules.html#folium.features.GeoJson for more info about setting style.

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.	`'Untitled'`

Raises:

Type	Description
`FileNotFoundError`	The provided shapefile could not be found.

Source code in geemap/foliumap.py

def add_shapefile(
    self, in_shp: str, layer_name: str = "Untitled", **kwargs
) -> None:
    """Adds a shapefile to the map.

    See https://python-visualization.github.io/folium/modules.html#folium.features.GeoJson
    for more info about setting style.

    Args:
        in_shp: The input file path to the shapefile.
        layer_name: The layer name to be used.

    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.")

    data = shp_to_geojson(in_shp)

    geo_json = folium.GeoJson(data=data, name=layer_name, **kwargs)
    geo_json.add_to(self)

`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 \| None`	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 \| None`	The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.	`None`
`item`	`str \| None`	The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.	`None`
`assets`	`str \| list[str] \| None`	The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"].	`None`
`bands`	`list[str] \| None`	A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]	`None`
`titiler_endpoint`	`str \| None`	Titiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space", "planetary-computer", "pc".	`None`
`name`	`str`	The layer name to use for the layer.	`'STAC Layer'`
`attribution`	`str`	The attribution to use.	`'.'`
`opacity`	`float`	The opacity of the layer.	`1.0`
`shown`	`bool`	A flag indicating whether the layer should be on by default.	`True`

Source code in geemap/foliumap.py

def add_stac_layer(
    self,
    url: str | None = None,
    collection: str | None = None,
    item: str | None = None,
    assets: str | list[str] | None = None,
    bands: list[str] | None = None,
    titiler_endpoint: str | None = None,
    name: str = "STAC Layer",
    # TODO: Why `.`? This does not match the doc string.
    attribution: str = ".",
    opacity: float = 1.0,
    shown: bool = True,
    **kwargs,
) -> None:
    """Adds a STAC TileLayer to the map.

    Args:
        url: 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: The Microsoft Planetary Computer STAC collection ID, e.g.,
            landsat-8-c2-l2.
        item: The Microsoft Planetary Computer STAC item ID, e.g.,
            LC08_L2SP_047027_20201204_02_T1.
        assets: The Microsoft Planetary Computer STAC asset ID, e.g.,
            ["SR_B7", "SR_B5", "SR_B4"].
        bands: A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]
        titiler_endpoint: Titiler endpoint, e.g.,
            "https://giswqs-titiler-endpoint.hf.space", "planetary-computer", "pc".
        name: The layer name to use for the layer.
        attribution: The attribution to use.
        opacity: The opacity of the layer.
        shown: A flag indicating whether the layer should be on by default.
    """
    tile_url = stac_tile(
        url, collection, item, assets, bands, titiler_endpoint, **kwargs
    )
    bounds = stac_bounds(url, collection, item, titiler_endpoint)
    self.add_tile_layer(
        url=tile_url,
        name=name,
        attribution=attribution,
        opacity=opacity,
        shown=shown,
    )
    self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

`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.	`'Untitled'`
`shown`	`bool`	TODO	`True`
`opacity`	`float`	TODO	`1.0`

Source code in geemap/foliumap.py

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

    Args:
        ee_object (object): An ee.FeatureCollection.
        column: 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: The name to be used for the new layer.
        shown: TODO
        opacity: TODO
    """
    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.	`20`
`fontcolor`	`str`	The font color.	`'black'`
`bold`	`bool`	Whether to use bold font.	`False`
`padding`	`str`	The padding.	`'5px'`
`background`	`bool`	Whether to use background.	`True`
`bg_color`	`str`	The background color.	`'white'`
`border_radius`	`str`	The border radius.	`'5px'`
`position`	`str`	The position of the widget.	`'bottomright'`

Source code in geemap/foliumap.py

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

    Args:
        text: The text to add.
        fontsize: The font size.
        fontcolor: The font color.
        bold: Whether to use bold font.
        padding: The padding.
        background: Whether to use background.
        bg_color: The background color.
        border_radius: The border radius.
        position: The position of the widget.
    """

    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(tiles='OpenStreetMap', name='Untitled', attribution='.', overlay=True, control=True, shown=True, opacity=1.0, API_key=None, **kwargs)` ¶

Add a XYZ tile layer to the map.

Parameters:

Name	Type	Description	Default
`tiles`	`str`	The URL of the XYZ tile service.	`'OpenStreetMap'`
`name`	`str`	The layer name to use on the layer control.	`'Untitled'`
`attribution`	`str`	The attribution of the data layer.	`'.'`
`overlay`	`bool`	Allows overlay.	`True`
`control`	`bool`	Adds the layer to the layer control.	`True`
`shown`	`bool`	A flag indicating whether the layer should be on by default.	`True`
`opacity`	`float`	Sets the opacity for the layer.	`1.0`
`API_key`	`str \| None`	– API key for Cloudmade or Mapbox tiles.	`None`

Source code in geemap/foliumap.py

def add_tile_layer(
    self,
    tiles: str = "OpenStreetMap",
    name: str = "Untitled",
    attribution: str = ".",
    overlay: bool = True,
    control: bool = True,
    shown: bool = True,
    opacity: float = 1.0,
    API_key: str | None = None,
    **kwargs,
) -> None:
    """Add a XYZ tile layer to the map.

    Args:
        tiles: The URL of the XYZ tile service.
        name: The layer name to use on the layer control.
        attribution: The attribution of the data layer.
        overlay: Allows overlay.
        control: Adds the layer to the layer control.
        shown: A flag indicating whether the layer should be on by default.
        opacity: Sets the opacity for the layer.
        API_key: – API key for Cloudmade or Mapbox tiles.
    """

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

    try:
        folium.raster_layers.TileLayer(
            tiles=tiles,
            name=name,
            attr=attribution,
            overlay=overlay,
            control=control,
            show=shown,
            opacity=opacity,
            API_key=API_key,
            **kwargs,
        ).add_to(self)
    except Exception:
        raise Exception("Failed to add the specified TileLayer.")

`add_widget(content, position='bottomright', **kwargs)` ¶

Add a widget (e.g., text, HTML, figure) to the map.

Parameters:

Name	Type	Description	Default
`content`	`str`	The widget to add.	required
`position`	`str`	The position of the widget.	`'bottomright'`

Source code in geemap/foliumap.py

def add_widget(self, content: str, position: str = "bottomright", **kwargs):
    """Add a widget (e.g., text, HTML, figure) to the map.

    Args:
        content: The widget to add.
        position: The position of the widget.
    """
    del kwargs  # Unused.

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

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

    if isinstance(content, str):
        widget = CustomControl(content, position=position)
        widget.add_to(self)
    elif isinstance(content, figure.Figure):
        buf = io.BytesIO()
        content.savefig(buf, format="png")
        buf.seek(0)
        b64_content = base64.b64encode(buf.read()).decode("utf-8")
        widget = CustomControl(
            f"""<img src="data:image/png;base64,{b64_content}">""",
            position=position,
        )
        widget.add_to(self)
    else:
        raise Exception("The content must be a string or a matplotlib figure")

`add_wms_layer(url, layers, name=None, attribution='', overlay=True, control=True, shown=True, format='image/png', transparent=True, version='1.1.1', styles='', **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 \| None`	The layer name to use on the layer control.	`None`
`attribution`	`str \| None`	The attribution of the data layer.	`''`
`overlay`	`bool`	Allows overlay.	`True`
`control`	`bool`	Adds the layer to the layer control.	`True`
`shown`	`bool`	A flag indicating whether the layer should be on by default.	`True`
`format`	`str`	WMS image format (use ‘image/png’ for layers with transparency).	`'image/png'`
`transparent`	`bool`	Whether the layer shall allow transparency.	`True`
`version`	`str`	Version of the WMS service to use.	`'1.1.1'`
`styles`	`str`	Comma-separated list of WMS styles.	`''`

Source code in geemap/foliumap.py

def add_wms_layer(
    self,
    url: str,
    layers: str,
    name: str | None = None,
    attribution: str | None = "",
    overlay: bool = True,
    control: bool = True,
    shown: bool = True,
    format: str = "image/png",
    transparent: bool = True,
    version: str = "1.1.1",
    styles: str = "",
    **kwargs,
) -> None:
    """Add a WMS layer to the map.

    Args:
        url: The URL of the WMS web service.
        layers: Comma-separated list of WMS layers to show.
        name: The layer name to use on the layer control.
        attribution: The attribution of the data layer.
        overlay: Allows overlay.
        control: Adds the layer to the layer control.
        shown: A flag indicating whether the layer should be on by default.
        format: WMS image format (use ‘image/png’ for layers with transparency).
        transparent: Whether the layer shall allow transparency.
        version: Version of the WMS service to use.
        styles: Comma-separated list of WMS styles.
    """
    try:
        folium.raster_layers.WmsTileLayer(
            url=url,
            layers=layers,
            name=name,
            attr=attribution,
            overlay=overlay,
            control=control,
            show=shown,
            styles=styles,
            fmt=format,
            transparent=transparent,
            version=version,
            **kwargs,
        ).add_to(self)
    except Exception:
        raise Exception("Failed to add the specified WMS TileLayer.")

`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/foliumap.py

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

    Args:
        provider: 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

    del kwargs  # Unused.

    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=url, name=name, attribution=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/foliumap.py

def basemap_demo(self):
    """A demo for using geemap basemaps."""
    print("The folium plotting backend does not support this function.")

`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`	`ComputedObject`	An Earth Engine object to center on a geometry, image or feature.	required
`zoom`	`int \| None`	The zoom level, from 1 to 24.	`None`
`max_error`	`float`	The maximum error for the geometry.	`0.001`

Source code in geemap/foliumap.py

def center_object(
    self,
    ee_object: ee.ComputedObject,
    zoom: int | None = None,
    max_error: float = 0.001,
) -> None:
    """Centers the map view on a given object.

    Args:
        ee_object: An Earth Engine object to center on a geometry, image or feature.
        zoom: The zoom level, from 1 to 24.
        max_error: The maximum error for the geometry.
    """
    if isinstance(ee_object, ee.Geometry):
        geometry = ee_object.transform(maxError=max_error)
    else:
        try:
            geometry = ee_object.geometry(maxError=max_error).transform(
                maxError=max_error
            )
        except Exception:
            raise Exception(
                "ee_object must be an instance of one of ee.Geometry, "
                "ee.FeatureCollection, ee.Image, or ee.ImageCollection."
            )

    if zoom is not None:
        if not isinstance(zoom, int):
            raise Exception("Zoom must be an integer.")

        centroid = geometry.centroid(maxError=max_error).getInfo()["coordinates"]
        lat = centroid[1]
        lon = centroid[0]
        self.set_center(lon, lat, zoom)

        if is_arcpy():
            arc_zoom_to_extent(lon, lat, lon, lat)

    else:
        coordinates = geometry.bounds(maxError=max_error).getInfo()["coordinates"][
            0
        ]
        x = [c[0] for c in coordinates]
        y = [c[1] for c in coordinates]
        xmin = min(x)
        xmax = max(x)
        ymin = min(y)
        ymax = max(y)
        bounds = [[ymin, xmin], [ymax, xmax]]
        self.fit_bounds(bounds)

        if is_arcpy():
            arc_zoom_to_extent(xmin, ymin, xmax, ymax)

`publish(name='Folium Map', description='', source_url='', tags=None, source_file=None, open=True, formatting=None, token=None, **kwargs)` ¶

Publish the map to datapane.com

Args:

name: The document name - can include spaces, caps, symbols, etc.,
    e.g., "Profit & Loss 2020".
description: A high-level description for the document, this is displayed in
    searches and thumbnails.
source_url: A URL pointing to the source code for the document, e.g. a
    GitHub repo or a Colab notebook.
tags (bool, optional): A list of tags (as strings) used to categorise your
    document.
source_file: Path of jupyter notebook file to upload.
open: Whether to open the map.
formatting (ReportFormatting, optional): Set the basic styling for your
    report.
token: The token to use to datapane to publish the map. See
    https://docs.datapane.com/tut-getting-started.

Source code in geemap/foliumap.py

def publish(
    self,
    name: str = "Folium Map",
    description: str = "",
    source_url: str = "",
    tags=None,
    source_file: str | None = None,
    open: bool = True,
    formatting=None,
    token: str | None = None,
    **kwargs,
):
    """Publish the map to datapane.com

    Args:

        name: The document name - can include spaces, caps, symbols, etc.,
            e.g., "Profit & Loss 2020".
        description: A high-level description for the document, this is displayed in
            searches and thumbnails.
        source_url: A URL pointing to the source code for the document, e.g. a
            GitHub repo or a Colab notebook.
        tags (bool, optional): A list of tags (as strings) used to categorise your
            document.
        source_file: Path of jupyter notebook file to upload.
        open: Whether to open the map.
        formatting (ReportFormatting, optional): Set the basic styling for your
            report.
        token: The token to use to datapane to publish the map. See
            https://docs.datapane.com/tut-getting-started.
    """
    import datapane as dp

    warnings.filterwarnings("ignore")

    if token is None:
        try:
            _ = dp.ping(verbose=False)
        except Exception as e:
            if os.environ.get("DP_TOKEN") is not None:
                dp.login(token=os.environ.get("DP_TOKEN"))
            else:
                raise Exception(e)
    else:
        dp.login(token)

    dp.upload_report(
        dp.Plot(self),
        name=name,
        description=description,
        source_url=source_url,
        tags=tags,
        source_file=source_file,
        open=open,
        formatting=formatting,
        **kwargs,
    )

`remove_labels(**kwargs)` ¶

Removes a layer from the map.

Source code in geemap/foliumap.py

def remove_labels(self, **kwargs):
    """Removes a layer from the map."""
    del kwargs  # Unused.
    print("The folium plotting backend does not support removing labels.")

`setOptions(mapTypeId='HYBRID', styles=None, types=None)` ¶

Adds Google basemap to the 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.	`'HYBRID'`
`styles`	`[type]`	A dictionary of custom MapTypeStyle objects keyed with a name that will appear in the map's Map Type Controls. Defaults to None.	`None`
`types`	`[type]`	A list of mapTypeIds to make available. If omitted, but opt_styles is specified, appends all of the style keys to the standard Google Maps API map types. Defaults to None.	`None`

Source code in geemap/foliumap.py

def setOptions(
    self,
    mapTypeId: str = "HYBRID",
    styles: dict[str, Any] | None = None,
    types: dict[str, Any] | None = None,
):
    """Adds Google basemap to the map.

    Args:
        mapTypeId: 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.
        styles ([type], optional): A dictionary of custom MapTypeStyle objects keyed
            with a name that will appear in the map's Map Type Controls. Defaults to
            None.
        types ([type], optional): A list of mapTypeIds to make available. If
            omitted, but opt_styles is specified, appends all of the style keys to
            the standard Google Maps API map types. Defaults to None.
    """
    styles = styles or {}
    types = types or {}

    try:
        basemaps[mapTypeId].add_to(self)
    except Exception:
        raise Exception(
            "Basemap can only be one of the following: {}".format(
                ", ".join(basemaps.keys())
            )
        )

`set_center(lon, lat, zoom=10)` ¶

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`	`int`	The zoom level, from 1 to 24.	`10`

Source code in geemap/foliumap.py

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

    Args:
        lon: The longitude of the center, in degrees.
        lat: The latitude of the center, in degrees.
        zoom: The zoom level, from 1 to 24.
    """
    self.fit_bounds([[lat, lon], [lat, lon]], max_zoom=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.	`True`
`fullscreenControl`	`bool`	Whether to show the control that allows the user to make the map full-screen.	`True`
`latLngPopup`	`bool`	Whether to show the control that pops up the Lat/lon when the user clicks on the map.	`True`

Source code in geemap/foliumap.py

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

    Args:
        layerControl: Whether to show the control that allows the user to toggle
            layers on/off.
        fullscreenControl: Whether to show the control that allows the user to make
            the map full-screen.
        latLngPopup: Whether to show the control that pops up the Lat/lon when the
            user clicks on the map.
    """
    if layerControl:
        folium.LayerControl().add_to(self)
    if fullscreenControl:
        plugins.Fullscreen().add_to(self)
    if latLngPopup:
        folium.LatLngPopup().add_to(self)

`set_plot_options(**kwargs)` ¶

Sets plotting options.

Source code in geemap/foliumap.py

def set_plot_options(
    self,
    **kwargs,
):
    """Sets plotting options."""
    del kwargs  # Unused.
    print("The folium plotting backend does not support this function.")

`split_map(left_layer='TERRAIN', right_layer='OpenTopoMap', left_args=None, right_args=None, left_label=None, right_label=None, left_position='bottomleft', right_position='bottomright', **kwargs)` ¶

Adds a split-panel map.

Parameters:

Name	Type	Description	Default
`left_layer`	`str`	The left tile layer. Can be a local file path, HTTP URL, or a basemap name.	`'TERRAIN'`
`right_layer`	`str`	The right tile layer. Can be a local file path, HTTP URL, or a basemap name.	`'OpenTopoMap'`
`left_args`	`dict`	The arguments for the left tile layer. Defaults to {}.	`None`
`right_args`	`dict`	The arguments for the right tile layer. Defaults to {}.	`None`
`left_label`		TODO	`None`
`right_label`		TODO	`None`
`left_position`		TODO	`'bottomleft'`
`right_position`		TODO	`'bottomright'`

Source code in geemap/foliumap.py

def split_map(
    self,
    left_layer: str = "TERRAIN",
    right_layer: str = "OpenTopoMap",
    left_args: dict[str, Any] | None = None,
    right_args: dict[str, Any] | None = None,
    left_label=None,
    right_label=None,
    left_position="bottomleft",
    right_position="bottomright",
    **kwargs,
):
    """Adds a split-panel map.

    Args:
        left_layer: The left tile layer. Can be a local file path, HTTP URL, or a
            basemap name.
        right_layer: The right tile layer. Can be a local file path, HTTP URL, or a
            basemap name.
        left_args (dict, optional): The arguments for the left tile layer. Defaults to {}.
        right_args (dict, optional): The arguments for the right tile layer. Defaults to {}.
        left_label: TODO
        right_label: TODO
        left_position: TODO
        right_position: TODO
    """
    left_args = left_args or {}
    right_args = right_args or {}

    del kwargs  # Unused.

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

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

    if "layer_name" not in left_args:
        left_args["layer_name"] = "Left Layer"

    if "layer_name" not in right_args:
        right_args["layer_name"] = "Right Layer"

    bounds = None

    try:
        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 left_layer in basemaps.keys():
            left_layer = basemaps[left_layer]
        elif isinstance(left_layer, str):
            if left_layer.startswith(
                ("http://", "https://")
            ) and left_layer.endswith(".tif"):
                url = cog_tile(left_layer, **left_args)
                bbox = cog_bounds(left_layer)
                bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                left_layer = folium.raster_layers.TileLayer(
                    tiles=url,
                    name=left_name,
                    attr=" ",
                    overlay=True,
                )
            elif os.path.exists(left_layer):
                left_layer, left_client = get_local_tile_layer(
                    left_layer,
                    tile_format="folium",
                    return_client=True,
                    **left_args,
                )
                bounds = image_bounds(left_client)

            else:
                left_layer = folium.raster_layers.TileLayer(
                    tiles=left_layer,
                    name=left_name,
                    attr=" ",
                    overlay=True,
                    **left_args,
                )
        elif isinstance(
            left_layer, (folium.raster_layers.TileLayer, folium.WmsTileLayer)
        ):
            pass
        else:
            raise ValueError(
                "left_layer must be one of the following: "
                f"{', '.join(basemaps.keys())} or a string url to a tif file."
            )

        if right_layer in basemaps.keys():
            right_layer = basemaps[right_layer]
        elif isinstance(right_layer, str):
            if right_layer.startswith(
                ("http://", "https://")
            ) and right_layer.endswith(".tif"):
                url = cog_tile(right_layer, **right_args)
                bbox = cog_bounds(right_layer)
                bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                right_layer = folium.raster_layers.TileLayer(
                    tiles=url,
                    name=right_name,
                    attr=" ",
                    overlay=True,
                )
            elif os.path.exists(right_layer):
                right_layer, right_client = get_local_tile_layer(
                    right_layer,
                    tile_format="folium",
                    return_client=True,
                    **right_args,
                )
                bounds = image_bounds(right_client)
            else:
                right_layer = folium.raster_layers.TileLayer(
                    tiles=right_layer,
                    name=right_name,
                    attr=" ",
                    overlay=True,
                    **right_args,
                )
        elif isinstance(
            right_layer, (folium.raster_layers.TileLayer, folium.WmsTileLayer)
        ):
            pass
        else:
            raise ValueError(
                "right_layer must be one of the following: "
                f"{', '.join(basemaps.keys())} or a string url to a tif file."
            )

        control = folium.plugins.SideBySideLayers(
            layer_left=left_layer, layer_right=right_layer
        )
        left_layer.add_to(self)
        right_layer.add_to(self)
        control.add_to(self)

        if left_label is not None:
            if "<" not in left_label:
                left_label = f"<h4>{left_label}</h4>"
            self.add_html(left_label, position=left_position)

        if right_label is not None:
            if "<" not in right_label:
                right_label = f"<h4>{right_label}</h4>"
            self.add_html(right_label, position=right_position)
        if bounds is not None:
            self.fit_bounds(bounds)

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

`st_draw_features(st_component)` ¶

Get the draw features of the map.

Parameters:

Name	Type	Description	Default
`st_folium`	`streamlit - folium`	The streamlit component.	required

Returns:

Name	Type	Description
`list`		The draw features of the map.

Source code in geemap/foliumap.py

def st_draw_features(self, st_component):
    """Get the draw features of the map.

    Args:
        st_folium (streamlit-folium): The streamlit component.

    Returns:
        list: The draw features of the map.
    """
    return st_component["all_drawings"]

`st_fit_bounds()` ¶

Fit the map to the bounds of the map.

Source code in geemap/foliumap.py

def st_fit_bounds(self) -> None:
    """Fit the map to the bounds of the map."""
    import streamlit as st

    if "map_bounds" in st.session_state:
        bounds = st.session_state["map_bounds"]

        self.fit_bounds(bounds)

`st_last_click(st_component)` ¶

Returns the last click feature of the map.

Parameters:

Name	Type	Description	Default
`st_folium`	`streamlit - folium`	The streamlit component.	required

Source code in geemap/foliumap.py

def st_last_click(self, st_component):
    """Returns the last click feature of the map.

    Args:
        st_folium (streamlit-folium): The streamlit component.
    """
    coords = st_component["last_clicked"]
    return coords["lat"], coords["lng"]

`st_last_draw(st_component)` ¶

Returns the last draw feature of the map.

Parameters:

Name	Type	Description	Default
`st_folium`	`streamlit - folium`	The streamlit component.	required

Source code in geemap/foliumap.py

def st_last_draw(self, st_component):
    """Returns the last draw feature of the map.

    Args:
        st_folium (streamlit-folium): The streamlit component.
    """
    return st_component["last_active_drawing"]

`st_map_bounds(st_component)` ¶

Returns the bounds of the map in the format of (miny, minx, maxy, maxx).

Parameters:

Name	Type	Description	Default
`st_folium`	`streamlit - folium`	The streamlit component.	required

Source code in geemap/foliumap.py

def st_map_bounds(self, st_component) -> list[list[float]]:
    """Returns the bounds of the map in the format of (miny, minx, maxy, maxx).

    Args:
        st_folium (streamlit-folium): The streamlit component.
    """
    bounds = st_component["bounds"]
    south = bounds["_southWest"]["lat"]
    west = bounds["_southWest"]["lng"]
    north = bounds["_northEast"]["lat"]
    east = bounds["_northEast"]["lng"]

    return [[south, west], [north, east]]

`st_map_center(st_component)` ¶

Returns the center of the map.

Parameters:

Name	Type	Description	Default
`st_folium`	`streamlit - folium`	The streamlit component.	required

Source code in geemap/foliumap.py

def st_map_center(self, st_component) -> tuple[float, float]:
    """Returns the center of the map.

    Args:
        st_folium (streamlit-folium): The streamlit component.
    """
    bounds = st_component["bounds"]
    west = bounds["_southWest"]["lng"]
    south = bounds["_southWest"]["lat"]
    east = bounds["_northEast"]["lng"]
    north = bounds["_northEast"]["lat"]
    return (south + (north - south) / 2, west + (east - west) / 2)

`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.	`'100%'`
`height`	`str`	The height of the map.	`'500px'`

Returns:

Type	Description
`str`	The HTML string to use in Gradio.

Source code in geemap/foliumap.py

def to_gradio(self, width: str = "100%", height: str = "500px", **kwargs) -> str:
    """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: The width of the map.
        height: The height of the map.

    Returns:
        The HTML string to use in Gradio.
    """
    del kwargs  # Unused.

    if isinstance(width, int):
        width = f"{width}px"
    if isinstance(height, int):
        height = f"{height}px"

    html = self.to_html()
    assert html is not None  # For pytype.
    lines = html.split("\n")
    output = []
    skipped_lines = []
    for index, line in enumerate(lines):
        if index in skipped_lines:
            continue
        if line.lstrip().startswith('{"attribution":'):
            continue
        elif "on(L.Draw.Event.CREATED, function(e)" in line:
            for i in range(14):
                skipped_lines.append(index + i)
        elif "L.Control.geocoder" in line:
            for i in range(5):
                skipped_lines.append(index + i)
        elif "function(e)" in line:
            print(
                "Warning: The folium plotting backend does not support functions "
                f"in code blocks. Please delete line {index + 1}."
            )
        else:
            output.append(line + "\n")

    return f"""<iframe style="width: {width}; height: {height}" name="result" allow="midi; geolocation; microphone; camera;
    display-capture; encrypted-media;" sandbox="allow-modals allow-forms
    allow-scripts allow-same-origin allow-popups
    allow-top-navigation-by-user-activation allow-downloads" allowfullscreen=""
    allowpaymentrequest="" frameborder="0" srcdoc='{"".join(output)}'></iframe>"""

`to_html(filename=None, **kwargs)` ¶

Exports a map as an HTML file.

Parameters:

Name	Type	Description	Default
`filename`	`str \| None`	File path to the output HTML.	`None`

Raises:

Type	Description
`ValueError`	If it is an invalid HTML file.

Returns:

Type	Description
`str \| None`	A string containing the HTML code.

Source code in geemap/foliumap.py

def to_html(self, filename: str | None = None, **kwargs) -> str | None:
    """Exports a map as an HTML file.

    Args:
        filename: File path to the output HTML.

    Raises:
        ValueError: If it is an invalid HTML file.

    Returns:
        A string containing the HTML code.
    """
    if self.options["layersControl"]:
        self.add_layer_control()

    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)
        self.save(filename, **kwargs)
    else:
        filename = os.path.abspath(coreutils.random_string() + ".html")
        self.save(filename, **kwargs)
        out_html = ""
        with open(filename) as f:
            lines = f.readlines()
            out_html = "".join(lines)
        os.remove(filename)
        return out_html

`to_streamlit(width=None, height=600, scrolling=False, add_layer_control=True, bidirectional=False, **kwargs)` ¶

Renders folium.Figure or folium.Map in a Streamlit app.

This method is a static Streamlit Component, meaning, no information is passed back from Leaflet on browser interaction.

Parameters:

Name	Type	Description	Default
`width`	`int \| None`	Width of the map. Defaults to None.	`None`
`height`	`int`	Height of the map. Defaults to 600.	`600`
`scrolling`	`bool`	Whether to allow the map to scroll. Defaults to False.	`False`
`add_layer_control`	`bool`	Whether to add the layer control. Defaults to True.	`True`
`bidirectional`	`bool`	Whether to add bidirectional functionality to the map. The streamlit-folium package is required to use the bidirectional functionality. Defaults to False.	`False`

Returns:

Type	Description
	streamlit.components: components.html object.

Source code in geemap/foliumap.py

def to_streamlit(
    self,
    width: int | None = None,
    height: int = 600,
    scrolling: bool = False,
    add_layer_control: bool = True,
    bidirectional: bool = False,
    **kwargs,
):
    """Renders `folium.Figure` or `folium.Map` in a Streamlit app.

    This method is a static Streamlit Component, meaning, no information is passed
    back from Leaflet on browser interaction.

    Args:
        width: Width of the map. Defaults to None.
        height: Height of the map. Defaults to 600.
        scrolling: Whether to allow the map to scroll. Defaults to False.
        add_layer_control: Whether to add the layer control. Defaults to True.
        bidirectional: Whether to add bidirectional functionality to the map. The
            streamlit-folium package is required to use the bidirectional
            functionality. Defaults to False.

    Returns:
        streamlit.components: components.html object.
    """
    import streamlit.components.v1 as components

    del kwargs  # Unused.

    if add_layer_control:
        self.add_layer_control()

    if bidirectional:
        from streamlit_folium import st_folium

        return st_folium(self, width=width, height=height)
    else:
        return components.html(
            self.to_html(), width=width, height=height, scrolling=scrolling
        )

`zoom_to_bounds(bounds)` ¶

Zooms to a bounding box in the form of [minx, miny, maxx, maxy].

Parameters:

Name	Type	Description	Default
`bounds`	`list \| tuple`	A list/tuple containing minx, miny, maxx, maxy values for the bounds.	required

Source code in geemap/foliumap.py

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

    Args:
      bounds (list | tuple): A list/tuple containing minx, miny, maxx, maxy values
        for the bounds.
    """
    # The folium 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/foliumap.py

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

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

`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."""

    endpoint: str
    name: str
    TileMatrixSetId: str

    def __init__(
        self,
        endpoint: str = "https://planetarycomputer.microsoft.com/api/data/v1",
        name: str = "item",
        TileMatrixSetId: str = "WebMercatorQuad",
    ):
        """Initialize the PlanetaryComputerEndpoint object.

        Args:
            endpoint: The endpoint of the titiler server. Defaults to
                "https://planetarycomputer.microsoft.com/api/data/v1".
            name: The name to be used in the file path. Defaults to "item".
            TileMatrixSetId: The TileMatrixSetId to be used in the
                file path. Defaults to "WebMercatorQuad".
        """
        super().__init__(endpoint, name, TileMatrixSetId)

    def url_for_stac_collection(self) -> str:
        return f"{self.endpoint}/collection/{self.TileMatrixSetId}/tilejson.json"

    def url_for_collection_assets(self) -> str:
        return f"{self.endpoint}/collection/assets"

    def url_for_collection_bounds(self) -> str:
        return f"{self.endpoint}/collection/bounds"

    def url_for_collection_info(self) -> str:
        return f"{self.endpoint}/collection/info"

    def url_for_collection_info_geojson(self) -> str:
        return f"{self.endpoint}/collection/info.geojson"

    def url_for_collection_pixel_value(self, lon: float, lat: float) -> str:
        return f"{self.endpoint}/collection/point/{lon},{lat}"

    def url_for_collection_wmts(self) -> str:
        return f"{self.endpoint}/collection/{self.TileMatrixSetId}/WMTSCapabilities.xml"

    def url_for_collection_lat_lon_assets(self, lng: float, lat: float) -> str:
        return f"{self.endpoint}/collection/{lng},{lat}/assets"

    def url_for_collection_bbox_assets(
        self, minx: float, miny: float, maxx: float, maxy: float
    ) -> str:
        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: str = "https://planetarycomputer.microsoft.com/api/data/v1",
    name: str = "item",
    TileMatrixSetId: str = "WebMercatorQuad",
):
    """Initialize the PlanetaryComputerEndpoint object.

    Args:
        endpoint: The endpoint of the titiler server. Defaults to
            "https://planetarycomputer.microsoft.com/api/data/v1".
        name: The name to be used in the file path. Defaults to "item".
        TileMatrixSetId: The TileMatrixSetId to be used in the
            file path. Defaults to "WebMercatorQuad".
    """
    super().__init__(endpoint, name, TileMatrixSetId)

`SideBySideLayers` ¶

Bases: JSCSSMixin, Layer

Side-by-side with swiping.

Creates a SideBySideLayers that takes two Layers and adds a sliding control with the leaflet-side-by-side plugin. Uses the Leaflet leaflet-side-by-side plugin https://github.com/digidem/leaflet-side-by-side. Adopted from https://github.com/python-visualization/folium/pull/1292/files.

Parameters:

Name	Type	Description	Default
`layer_left`		Layer. The left Layer within the side by side control. Must be created and added to the map before being passed to this class.	required
`layer_right`		Layer. The right Layer within the side by side control. Must be created and added to the map before being passed to this class.	required

Examples >>> sidebyside = SideBySideLayers(layer_left, layer_right) >>> sidebyside.add_to(m)

Source code in geemap/foliumap.py

class SideBySideLayers(JSCSSMixin, Layer):
    """Side-by-side with swiping.

    Creates a SideBySideLayers that takes two Layers and adds a sliding control with the
    leaflet-side-by-side plugin. Uses the Leaflet leaflet-side-by-side plugin
    https://github.com/digidem/leaflet-side-by-side. Adopted from
    https://github.com/python-visualization/folium/pull/1292/files.

    Args:
        layer_left: Layer.
            The left Layer within the side by side control.
            Must be created and added to the map before being passed to this class.
        layer_right: Layer.
            The right Layer within the side by side control.
            Must be created and added to the map before being passed to this class.

    Examples
        >>> sidebyside = SideBySideLayers(layer_left, layer_right)
        >>> sidebyside.add_to(m)
    """

    _template = Template("""
        {% macro script(this, kwargs) %}
            var {{ this.get_name() }} = L.control.sideBySide(
                {{ this.layer_left.get_name() }}, {{ this.layer_right.get_name() }}
            ).addTo({{ this._parent.get_name() }});
        {% endmacro %}
        """)

    default_js = [
        (
            "leaflet.sidebyside",
            "https://cdn.jsdelivr.net/gh/digidem/leaflet-side-by-side@gh-pages/leaflet-side-by-side.min.js",
        ),
    ]

    def __init__(self, layer_left, layer_right):
        super().__init__(control=False)
        self._name = "SideBySideLayers"
        self.layer_left = layer_left
        self.layer_right = layer_right

`SplitControl` ¶

Bases: Layer

Side-by-side plugin.

Creates a SplitControl that takes two Layers and adds a sliding control with the leaflet-side-by-side plugin. Uses the Leaflet leaflet-side-by-side plugin https://github.com/digidem/leaflet-side-by-side Parameters. The source code is adapted from https://github.com/python-visualization/folium/pull/1292

Parameters:

Name	Description	Default
`layer_left`	Layer. The left Layer within the side by side control. Must be created and added to the map before being passed to this class.	required
`layer_right`	Layer. The right Layer within the side by side control. Must be created and added to the map before being passed to this class.	required
`name`	string, default None The name of the Layer, as it will appear in LayerControls.	required
`overlay`	bool, default True Adds the layer as an optional overlay (True) or the base layer (False).	required
`control`	bool, default True Whether the Layer will be included in LayerControls.	required
`show`	bool, default True Whether the layer will be shown on opening (only for overlays).	`True`

Examples

>>> sidebyside = SideBySideLayers(layer_left, layer_right)
>>> sidebyside.add_to(m)

Source code in geemap/foliumap.py

class SplitControl(Layer):
    """Side-by-side plugin.

    Creates a SplitControl that takes two Layers and adds a sliding control with the
    leaflet-side-by-side plugin. Uses the Leaflet leaflet-side-by-side plugin
    https://github.com/digidem/leaflet-side-by-side Parameters. The source code is
    adapted from https://github.com/python-visualization/folium/pull/1292

    Args:
        layer_left: Layer.
            The left Layer within the side by side control.
            Must be created and added to the map before being passed to this class.
        layer_right: Layer.
            The right Layer within the side by side control.
            Must be created and added to the map before being passed to this class.
        name : string, default None
            The name of the Layer, as it will appear in LayerControls.
        overlay : bool, default True
            Adds the layer as an optional overlay (True) or the base layer (False).
        control : bool, default True
            Whether the Layer will be included in LayerControls.
        show: bool, default True
            Whether the layer will be shown on opening (only for overlays).

    Examples

        >>> sidebyside = SideBySideLayers(layer_left, layer_right)
        >>> sidebyside.add_to(m)
    """

    _template = Template("""
        {% macro script(this, kwargs) %}
            var {{ this.get_name() }} = L.control.sideBySide(
                {{ this.layer_left.get_name() }}, {{ this.layer_right.get_name() }}
            ).addTo({{ this._parent.get_name() }});
        {% endmacro %}
        """)

    def __init__(
        self, layer_left, layer_right, name=None, overlay=True, control=False, show=True
    ):
        super().__init__(name=name, overlay=overlay, control=control, show=show)
        self._name = "SplitControl"
        self.layer_left = layer_left
        self.layer_right = layer_right

    def render(self, **kwargs) -> None:
        super().render()

        figure = self.get_root()
        assert isinstance(figure, Figure), (
            "You cannot render this Element " "if it is not in a Figure."
        )

        figure.header.add_child(
            JavascriptLink(
                "https://raw.githack.com/digidem/leaflet-side-by-side/gh-pages/leaflet-side-by-side.js"
            ),  # noqa
            name="leaflet.sidebyside",
        )

`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."""

    endpoint: str
    name: str
    TileMatrixSetId: str

    def __init__(
        self,
        endpoint: str = "https://giswqs-titiler-endpoint.hf.space",
        name: str = "stac",
        TileMatrixSetId: str = "WebMercatorQuad",
    ):
        """Initialize the TitilerEndpoint object.

        Args:
            endpoint: The endpoint of the titiler server. Defaults to
                "https://giswqs-titiler-endpoint.hf.space".
            name: The name to be used in the file path. Defaults to "stac".
            TileMatrixSetId: 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) -> str:
        return f"{self.endpoint}/{self.name}/{self.TileMatrixSetId}/tilejson.json"

    def url_for_stac_assets(self) -> str:
        return f"{self.endpoint}/{self.name}/assets"

    def url_for_stac_bounds(self) -> str:
        return f"{self.endpoint}/{self.name}/bounds"

    def url_for_stac_info(self) -> str:
        return f"{self.endpoint}/{self.name}/info"

    def url_for_stac_info_geojson(self) -> str:
        return f"{self.endpoint}/{self.name}/info.geojson"

    def url_for_stac_statistics(self) -> str:
        return f"{self.endpoint}/{self.name}/statistics"

    def url_for_stac_pixel_value(self, lon: float, lat: float) -> str:
        return f"{self.endpoint}/{self.name}/point/{lon},{lat}"

    def url_for_stac_wmts(self) -> str:
        return (
            f"{self.endpoint}/{self.name}/{self.TileMatrixSetId}/WMTSCapabilities.xml"
        )

`init(endpoint='https://giswqs-titiler-endpoint.hf.space', name='stac', TileMatrixSetId='WebMercatorQuad')` ¶

Initialize the TitilerEndpoint object.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	The endpoint of the titiler server. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`'https://giswqs-titiler-endpoint.hf.space'`
`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: str = "https://giswqs-titiler-endpoint.hf.space",
    name: str = "stac",
    TileMatrixSetId: str = "WebMercatorQuad",
):
    """Initialize the TitilerEndpoint object.

    Args:
        endpoint: The endpoint of the titiler server. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        name: The name to be used in the file path. Defaults to "stac".
        TileMatrixSetId: 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.

    """
    import 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%').	`None`
`image_size`	`tuple[int, int]`	Resize image.	`(80, 80)`
`circle_mask`	`bool`	Whether to apply a circle mask to the image. This only works with non-png images.	`False`

Source code in geemap/timelapse.py

def add_image_to_gif(
    in_gif: str,
    out_gif: str,
    in_image: str,
    xy=None,
    image_size: tuple[int, int] = (80, 80),
    circle_mask: bool = False,
) -> None:
    """Adds an image logo to a GIF image.

    Args:
        in_gif: Input file path to the GIF image.
        out_gif: Output file path to the GIF image.
        in_image: 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%').
        image_size: Resize image.
        circle_mask: Whether to apply a circle mask to the image. This only works with
            non-png images.
    """
    warnings.simplefilter("ignore")

    in_gif = os.path.abspath(in_gif)

    is_url = False
    if in_image.startswith(("http://", "https://")):
        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://", "https://")):
            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)
    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(
                f"xy is out of bounds. x must be within [0, {gif_width}], and "
                f"y must be within [0, {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.	`'black'`
`width`	`int`	The width of the overlay.	`1`
`opacity`	`float`	The opacity of the overlay.	`1.0`
`region`	`Geometry \| FeatureCollection \| None`	The region of interest to add the overlay to.	`None`

Returns:

Type	Description
`ImageCollection`	An ImageCollection with the overlay added.

Source code in geemap/timelapse.py

def add_overlay(
    collection: ee.ImageCollection,  # pytype: disable=annotation-type-mismatch
    overlay_data: str | ee.Geometry | ee.FeatureCollection,
    color: str = "black",
    width: int = 1,
    opacity: float = 1.0,
    region: ee.Geometry | ee.FeatureCollection | None = None,
) -> ee.ImageCollection:
    """Adds an overlay to an image collection.

    Args:
        collection: The image collection to add the overlay to.
        overlay_data: The overlay data to add to the image collection. It can be an HTTP
            URL to a GeoJSON file.
        color: The color of the overlay.
        width: The width of the overlay.
        opacity: The opacity of the overlay.
        region: The region of interest to add the overlay to.

    Returns:
        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://", "https://")
                ) and overlay_data.endswith(".geojson"):
                    overlay_data = coreutils.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 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:
        target_proj = collection.first().projection()
        region_geom = None
        if region is not None:
            if isinstance(region, ee.Geometry):
                region_geom = region
            else:
                region_geom = region.geometry()

        if region_geom is not None:
            overlay_data = overlay_data.filterBounds(region_geom).map(
                lambda feature: feature.intersection(region_geom, ee.ErrorMargin(1))
            )

        empty = ee.Image().byte().setDefaultProjection(target_proj)
        image = empty.paint(
            **{
                "featureCollection": overlay_data,
                "color": 1,
                "width": width,
            }
        ).visualize(**{"palette": coreutils.check_color(color), "opacity": opacity})
        image = image.setDefaultProjection(target_proj)

        if region_geom is not None:
            image = image.clip(region_geom)

        blend_col = collection.map(
            lambda img: img.blend(image)
            .setDefaultProjection(img.projection())
            .set("system:time_start", img.get("system:time_start"))
        )
        return blend_col
    except Exception as e:
        print("Error in add_overlay:")
        raise 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.	`'blue'`
`progress_bar_height`	`int`	Height of the progress bar.	`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.	`100`
`loop`	`int`	controls how many times the animation repeats. 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.	`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.
        progress_bar_height (int, optional): Height of the progress bar.
        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.
        loop (int, optional): controls how many times the animation repeats. 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.
    """
    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 = coreutils.check_color(progress_bar_color)

    image = Image.open(in_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
    ]

    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)
        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,
    )

`add_sample_markers_to_gif(in_gif, out_gif, sample_points, marker_colors, marker_size, marker_style, roi_bounds, gif_dimensions)` ¶

Add sample point markers to a GIF.

Parameters:

Name	Type	Description	Default
`in_gif`	`str`	Path to input GIF file	required
`out_gif`	`str`	Path to output GIF file	required
`sample_points`	`list`	List of [lon, lat] coordinates	required
`marker_colors`	`list`	List of colors for each marker	required
`marker_size`	`int`	Size of markers in pixels	required
`marker_style`	`str`	Style of markers ('cross', 'circle', 'square')	required
`roi_bounds`	`list`	[min_lon, min_lat, max_lon, max_lat] bounds of the ROI	required
`gif_dimensions`	`int`	Dimensions of the GIF	required

Source code in geemap/timelapse.py

def add_sample_markers_to_gif(
    in_gif,
    out_gif,
    sample_points,
    marker_colors,
    marker_size,
    marker_style,
    roi_bounds,
    gif_dimensions,
):
    """Add sample point markers to a GIF.

    Args:
        in_gif (str): Path to input GIF file
        out_gif (str): Path to output GIF file
        sample_points (list): List of [lon, lat] coordinates
        marker_colors (list): List of colors for each marker
        marker_size (int): Size of markers in pixels
        marker_style (str): Style of markers ('cross', 'circle', 'square')
        roi_bounds (list): [min_lon, min_lat, max_lon, max_lat] bounds of the ROI
        gif_dimensions (int): Dimensions of the GIF
    """
    del gif_dimensions  # Unused.

    warnings.simplefilter("ignore")

    in_gif = os.path.abspath(in_gif)
    out_gif = os.path.abspath(out_gif)

    if not os.path.exists(in_gif):
        raise FileNotFoundError(f"Input GIF file does not exist: {in_gif}")

    if not os.path.exists(os.path.dirname(out_gif)):
        os.makedirs(os.path.dirname(out_gif))

    try:
        gif = Image.open(in_gif)

        gif_width, gif_height = gif.size

        # Convert sample points to pixel coordinates.
        sample_points_pixel = []

        for i, point in enumerate(sample_points):
            lon, lat = point[0], point[1]

            pixel_x, pixel_y = get_pixel_coordinates_from_geo(
                lon, lat, roi_bounds, gif_width, gif_height
            )

            sample_points_pixel.append(
                {
                    "x": pixel_x,
                    "y": pixel_y,
                    "color": marker_colors[i] if i < len(marker_colors) else "red",
                }
            )

        # Process each frame.
        frames = []
        frame_count = 0

        try:
            while True:
                frame = gif.copy()
                frame = frame.convert("RGB")

                # Draw markers on the frame.
                draw = ImageDraw.Draw(frame)

                for point in sample_points_pixel:
                    x, y = point["x"], point["y"]
                    color = point["color"]

                    # Draw marker based on style.
                    if marker_style == "circle":
                        draw_circle_marker(draw, x, y, marker_size, color)
                    elif marker_style == "square":
                        draw_square_marker(draw, x, y, marker_size, color)
                    else:
                        draw_cross_marker(draw, x, y, marker_size, color)

                # Convert back to GIF frame format.
                b = io.BytesIO()
                frame.save(b, format="GIF")
                frame = Image.open(b)
                frames.append(frame)

                # Move to next frame.
                gif.seek(gif.tell() + 1)
                frame_count += 1

        except EOFError:
            # End of GIF frames.
            pass

        # Save the new GIF with markers.
        if frames:
            frames[0].save(
                out_gif,
                save_all=True,
                append_images=frames[1:],
                duration=gif.info.get("duration", 100),
                loop=gif.info.get("loop", 0),
                optimize=True,
            )

    except Exception as e:
        raise Exception(f"Error processing GIF: {str(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%').	`None`
`text_sequence`	`(int, str, list)`	Text to be drawn. It can be an integer number, a string, or a list of strings.	`None`
`font_type`	`str`	Font type.	`'arial.ttf'`
`font_size`	`int`	Font size.	`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').	`'#000000'`
`add_progress_bar`	`bool`	Whether to add a progress bar at the bottom of the GIF.	`True`
`progress_bar_color`	`str`	Color for the progress bar.	`'white'`
`progress_bar_height`	`int`	Height of the progress bar.	`5`
`duration`	`float`	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.	`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.	`0`

Source code in geemap/timelapse.py

def add_text_to_gif(
    in_gif: str,
    out_gif: str,
    xy=None,
    text_sequence=None,
    font_type: str = "arial.ttf",
    font_size: int = 20,
    font_color: str = "#000000",
    add_progress_bar: bool = True,
    progress_bar_color: str = "white",
    progress_bar_height: int = 5,
    duration: float = 100,
    loop: int = 0,
) -> None:
    """Adds animated text to a GIF image.

    Args:
        in_gif: The file path to the input GIF image.
        out_gif: 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%').
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer
            number, a string, or a list of strings.
        font_type: Font type.
        font_size: Font size.
        font_color: Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255,
            127, 0)), or hex code (e.g., '#ff00ff').
        add_progress_bar: Whether to add a progress bar at the bottom of the
            GIF.
        progress_bar_color: Color for the progress bar.
        progress_bar_height: Height of the progress bar.
        duration: 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.
        loop: 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.
    """
    warnings.simplefilter("ignore")

    # pytype: disable=attribute-error
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    # pytype: enable=attribute-error
    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 = coreutils.check_color(font_color)
    progress_bar_color = coreutils.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}], "
                f"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)):
            frame = frame.convert("RGB")
            draw = ImageDraw.Draw(frame)
            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."""
    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: float, ymin: float, xmax: float, ymax: float) -> None:
    """Zoom to an extent in ArcGIS Pro.

    Args:
        xmin: The minimum x value of the extent.
        ymin: The minimum y value of the extent.
        xmax: The maximum x value of the extent.
        ymax: 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 \| None`	The path to the output image. If None, a temporary file will be created. Defaults to None.	`None`
`source`	`str \| None`	The path to an existing GeoTIFF file with map projection information. Defaults to None.	`None`
`# TODO`		What type should dtype be?	required
`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 \| None`	The resolution of the output image in meters. Defaults to None.	`None`
`crs`	`str \| None`	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: np.ndarray,
    output: str | None = None,
    source: str | None = None,
    dtype=None,
    compress: str = "deflate",
    transpose: bool = True,
    cellsize: float | None = None,
    crs: str | None = None,
    driver: str = "COG",
    **kwargs,
) -> str | None:
    """Save a NumPy array as a GeoTIFF using the projection information from an existing GeoTIFF file.

    Args:
        array: The NumPy array to be saved as a GeoTIFF.
        output: The path to the output image. If None, a temporary file will be
            created. Defaults to None.
        source: The path to an existing GeoTIFF file with map projection
            information. Defaults to None.
        # TODO: What type should dtype be?
        dtype (np.dtype, optional): The data type of the output array. Defaults to None.
        compress: The compression method. Can be one of the following: "deflate", "lzw",
            "packbits", "jpeg". Defaults to "deflate".
        transpose: Whether to transpose the array from (bands, rows, columns) to (rows,
            columns, bands). Defaults to True.
        cellsize: The resolution of the output image in meters. Defaults to None.
        crs: The CRS of the output image. Defaults to None.
        driver: 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 rasterio

    if output is None:
        return array_to_memory_file(
            array,
            source,
            dtype,
            compress,
            transpose,
            cellsize,
            crs,
            driver=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 \| None`	Path to the source file to extract metadata from. Defaults to None.	`None`
`dtype`	`str \| None`	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 \| None`	The cell size of the array if source is not provided. Defaults to None.	`None`
`crs`	`str \| None`	The coordinate reference system of the array if source is not provided. Defaults to None.	`None`
`transform`	`tuple \| None`	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: np.ndarray,
    source: str | None = None,
    dtype: str | None = None,
    compress: str = "deflate",
    transpose: bool = True,
    cellsize: float | None = None,
    crs: str | None = None,
    transform: tuple | None = None,
    driver: str = "COG",
    **kwargs,
):
    """Convert a NumPy array to a memory file.

    Args:
        array: The input NumPy array.
        source: Path to the source file to extract metadata from. Defaults to None.
        dtype: The desired data type of the array. Defaults to None.
        compress: The compression method for the output file. Defaults to "deflate".
        transpose: Whether to transpose the array from (bands, rows, columns) to (rows,
            columns, bands). Defaults to True.
        cellsize: The cell size of the array if source is not provided. Defaults to
            None.
        crs: The coordinate reference system of the array if source is not
            provided. Defaults to None.
        transform: The affine transformation matrix if source is not provided. Defaults
            to None.
        driver: 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 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.
    return rasterio.open(dst.name, mode="r")

`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`	`ImageCollection`	ee.ImageCollection

Source code in geemap/common.py

def bands_to_image_collection(img) -> ee.ImageCollection:
    """Converts all bands in an image to an image collection.

    Args:
        img (object): The image to convert.

    Returns:
        object: ee.ImageCollection
    """
    return ee.ImageCollection(img.bandNames().map(lambda b: img.select([b])))

`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=None, **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.	`True`
`sort_column`	`str \| None`	The column to sort the data.	`None`
`max_rows`	`int \| None`	Maximum number of rows to display.	`None`
`x_label`	`str \| None`	Label for the x axis.	`None`
`y_label`	`str \| None`	Label for the y axis.	`None`
`title`	`str \| None`	Title for the plot.	`None`
`legend_title`	`str \| None`	Title for the legend.	`None`
`width`	`int \| None`	Width of the plot in pixels.	`None`
`height`	`int`	Height of the plot in pixels.	`500`
`layout_args`	`dict \| None`	Layout arguments for the plot to be passed to fig.update_layout(), such as {'title':'Plot Title', 'title_x':0.5}.	`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:

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: bool = True,
    sort_column: str | None = None,
    max_rows: int | None = None,
    x_label: str | None = None,
    y_label: str | None = None,
    title: str | None = None,
    legend_title: str | None = None,
    width: int | None = None,
    height: int = 500,
    layout_args: dict | None = None,
    **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: Whether to sort the data in descending order.
        sort_column: The column to sort the data.
        max_rows: Maximum number of rows to display.
        x_label: Label for the x axis.
        y_label: Label for the y axis.
        title: Title for the plot.
        legend_title: Title for the legend.
        width: Width of the plot in pixels.
        height: Height of the plot in pixels.
        layout_args: Layout arguments for the plot to be passed to fig.update_layout(),
            such as {'title':'Plot Title', 'title_x':0.5}.
        **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://", "https://")):
            data = coreutils.github_raw_url(data)
            data = common.get_direct_url(data)
        data = pd.read_csv(data)

    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)

    labels = kwargs.pop("labels", {})

    if x_label is not None:
        labels[x] = x_label  # pytype: disable=unsupported-operands
    if y_label is not None:
        if isinstance(y, str):
            labels[y] = y_label  # pytype: disable=unsupported-operands
        elif isinstance(y, list):
            labels[y[0]] = y_label  # pytype: disable=unsupported-operands

    if layout_args is None:
        layout_args = {}

    if isinstance(legend_title, str):
        if "legend" not in layout_args:
            layout_args["legend"] = {}
        layout_args["legend"]["title"] = legend_title

    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

`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:

Type	Description
`list[float] \| None`	The bounding box coordinates in the form [west, south, east, north].

Source code in geemap/common.py

def bbox_coords(geometry, decimals=4) -> list[float] | None:
    """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:
        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.
    """
    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`	`Sequence[float]`	A list of coordinates representing [left, bottom, right, top].	required

Returns:

Type	Description
`dict[str, Any]`	A geojson feature.

Source code in geemap/common.py

def bbox_to_geojson(bounds: Sequence[float]) -> dict[str, Any]:
    """Convert coordinates of a bounding box to a geojson.

    Args:
        bounds: A list of coordinates representing [left, bottom, right, top].

    Returns:
        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
`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,
) -> ee.Image:
    """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:
        The blended image.
    """
    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.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.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'.")

    return ee.Image().expression(expression, {"a": top, "b": bottom})

`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:

Type	Description
`tuple[tuple[float, float], tuple[float, float]]`	A tuple of (x_range, y_range).

Source code in geemap/common.py

def bounds_to_xy_range(bounds) -> tuple[tuple[float, float], tuple[float, float]]:
    """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:
        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]
    else:
        raise ValueError("bounds must be a list of length 4 or 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

`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: dict, output_widget, layout_width: str = "100%"):
    """Builds an Earth Engine API tree view.

    Args:
        api_dict: The dictionary containing information about each Earth Engine API
            function.
        output_widget (object): An Output widget.
        layout_width: 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.
    """
    from ipytree import Node, Tree

    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 = ipywidgets.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_repo_tree(out_dir=None, name='gee_repos')` ¶

Builds a repo tree for GEE account.

Parameters:

Name	Type	Description	Default
`out_dir`	`str \| None`	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: str | None = None, name: str = "gee_repos"):
    """Builds a repo tree for GEE account.

    Args:
        out_dir: The output directory for the repos. Defaults to None.
        name: 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 = ipywidgets.Text(
        placeholder="Enter the link to a Git repository here..."
    )
    path_widget.layout.width = "475px"
    clone_widget = ipywidgets.Button(
        description="Clone",
        button_style="primary",
        tooltip="Clone the repository to folder.",
    )
    info_widget = ipywidgets.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)

    result = file_browser(
        in_dir=repo_dir,
        add_root_node=False,
        search_description="Filter scripts...",
        use_import=True,
        return_sep_widgets=True,
    )
    assert result is not None  # For pytype.
    left_widget, right_widget, tree_dict = result
    info_widget.children = [right_widget]

    def handle_folder_click(event) -> None:
        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 = f"Cloned to {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

`calculate_landsat_indices(image)` ¶

Calculate common vegetation and spectral indices for Landsat images.

Parameters:

Name	Type	Description	Default
`image`	`Image`	Landsat image with bands Blue, Green, Red, NIR, SWIR1, SWIR2	required

Returns:

Type	Description
`Image`	Image with added index bands

Source code in geemap/timelapse.py

def calculate_landsat_indices(image: ee.Image) -> ee.Image:
    """Calculate common vegetation and spectral indices for Landsat images.

    Args:
        image: Landsat image with bands Blue, Green, Red, NIR, SWIR1, SWIR2

    Returns:
        Image with added index bands
    """
    # Normalized Difference Vegetation Index.
    ndvi = image.normalizedDifference(["NIR", "Red"]).rename("NDVI")

    # Enhanced Vegetation Index.
    evi = image.expression(
        "2.5 * ((NIR - RED) / (NIR + 6 * RED - 7.5 * BLUE + 1))",
        {
            "NIR": image.select("NIR"),
            "RED": image.select("Red"),
            "BLUE": image.select("Blue"),
        },
    ).rename("EVI")

    # Normalized Difference Water Index.
    ndwi = image.normalizedDifference(["Green", "NIR"]).rename("NDWI")

    # Modified Normalized Difference Water Index.
    mndwi = image.normalizedDifference(["Green", "SWIR1"]).rename("MNDWI")

    # Normalized Difference Built-up Index.
    ndbi = image.normalizedDifference(["SWIR1", "NIR"]).rename("NDBI")

    # Normalized Burn Ratio.
    nbr = image.normalizedDifference(["NIR", "SWIR2"]).rename("NBR")

    # Soil Adjusted Vegetation Index.
    savi = image.expression(
        "((NIR - RED) / (NIR + RED + 0.5)) * (1.5)",
        {"NIR": image.select("NIR"), "RED": image.select("Red")},
    ).rename("SAVI")

    # Green Normalized Difference Vegetation Index.
    gndvi = image.normalizedDifference(["NIR", "Green"]).rename("GNDVI")

    # Normalized Difference Moisture Index.
    ndmi = image.normalizedDifference(["NIR", "SWIR1"]).rename("NDMI")

    # Modified Soil Adjusted Vegetation Index 2.
    msavi2 = image.expression(
        "(2 * NIR + 1 - sqrt(pow((2 * NIR + 1), 2) - 8 * (NIR - RED))) / 2",
        {"NIR": image.select("NIR"), "RED": image.select("Red")},
    ).rename("MSAVI2")

    # Visible Atmospherically Resistant Index.
    vari = image.expression(
        "(GREEN - RED) / (GREEN + RED - BLUE)",
        {
            "GREEN": image.select("Green"),
            "RED": image.select("Red"),
            "BLUE": image.select("Blue"),
        },
    ).rename("VARI")

    # Modified Chlorophyll Absorption Ratio Index.
    mcari = image.expression(
        "((RE - RED) - 0.2 * (RE - GREEN)) * (RE / RED)",
        {
            "RE": image.select("NIR"),  # Using NIR as proxy for Red Edge.
            "RED": image.select("Red"),
            "GREEN": image.select("Green"),
        },
    ).rename("MCARI")

    # Tasseled Cap Transformation coefficients for Landsat 8 OLI.
    # These coefficients are for surface reflectance data.
    tcb = image.expression(
        "0.3037*BLUE + 0.2793*GREEN + 0.4743*RED + 0.5585*NIR + 0.5082*SWIR1 + 0.1863*SWIR2",
        {
            "BLUE": image.select("Blue"),
            "GREEN": image.select("Green"),
            "RED": image.select("Red"),
            "NIR": image.select("NIR"),
            "SWIR1": image.select("SWIR1"),
            "SWIR2": image.select("SWIR2"),
        },
    ).rename("TCB")

    tcg = image.expression(
        "-0.2848*BLUE - 0.2435*GREEN - 0.5436*RED + 0.7243*NIR + 0.0840*SWIR1 - 0.1800*SWIR2",
        {
            "BLUE": image.select("Blue"),
            "GREEN": image.select("Green"),
            "RED": image.select("Red"),
            "NIR": image.select("NIR"),
            "SWIR1": image.select("SWIR1"),
            "SWIR2": image.select("SWIR2"),
        },
    ).rename("TCG")

    tcw = image.expression(
        "0.1509*BLUE + 0.1973*GREEN + 0.3279*RED + 0.3406*NIR - 0.7112*SWIR1 - 0.4572*SWIR2",
        {
            "BLUE": image.select("Blue"),
            "GREEN": image.select("Green"),
            "RED": image.select("Red"),
            "NIR": image.select("NIR"),
            "SWIR1": image.select("SWIR1"),
            "SWIR2": image.select("SWIR2"),
        },
    ).rename("TCW")

    return image.addBands(
        [
            ndvi,
            evi,
            ndwi,
            mndwi,
            ndbi,
            nbr,
            savi,
            gndvi,
            ndmi,
            msavi2,
            vari,
            mcari,
            tcb,
            tcg,
            tcw,
        ]
    )

`calculate_sentinel2_indices(image)` ¶

Calculate common vegetation and water indices for Sentinel-2 images.

Parameters:

Name	Type	Description	Default
`image`	`Image`	Sentinel-2 image with bands B2, B3, B4, B5, B6, B7, B8, B8A, B11, B12	required

Returns:

Type	Description
	ee.Image: Image with added index bands

Source code in geemap/timelapse.py

def calculate_sentinel2_indices(image):
    """Calculate common vegetation and water indices for Sentinel-2 images.

    Args:
        image (ee.Image): Sentinel-2 image with bands B2, B3, B4, B5, B6, B7, B8, B8A, B11, B12

    Returns:
        ee.Image: Image with added index bands
    """
    # Normalized Difference Vegetation Index.
    ndvi = image.normalizedDifference(["B8", "B4"]).rename("NDVI")

    # Enhanced Vegetation Index.
    evi = image.expression(
        "2.5 * ((NIR - RED) / (NIR + 6 * RED - 7.5 * BLUE + 1))",
        {
            "NIR": image.select("B8"),
            "RED": image.select("B4"),
            "BLUE": image.select("B2"),
        },
    ).rename("EVI")

    # Normalized Difference Water Index.
    ndwi = image.normalizedDifference(["B3", "B8"]).rename("NDWI")

    # Modified Normalized Difference Water Index.
    mndwi = image.normalizedDifference(["B3", "B11"]).rename("MNDWI")

    # Normalized Difference Built-up Index.
    ndbi = image.normalizedDifference(["B11", "B8"]).rename("NDBI")

    # Normalized Burn Ratio.
    nbr = image.normalizedDifference(["B8", "B12"]).rename("NBR")

    # Soil Adjusted Vegetation Index.
    savi = image.expression(
        "((NIR - RED) / (NIR + RED + 0.5)) * (1.5)",
        {"NIR": image.select("B8"), "RED": image.select("B4")},
    ).rename("SAVI")

    # Green Normalized Difference Vegetation Index.
    gndvi = image.normalizedDifference(["B8", "B3"]).rename("GNDVI")

    # Normalized Difference Red Edge.
    ndre = image.normalizedDifference(["B8", "B5"]).rename("NDRE")

    # Chlorophyll Index Red Edge.
    cire = image.expression(
        "(NIR / RE1) - 1", {"NIR": image.select("B8"), "RE1": image.select("B5")}
    ).rename("CIRE")

    return image.addBands([ndvi, evi, ndwi, mndwi, ndbi, nbr, savi, gndvi, ndre, cire])

`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[float, float]`	A tuple of (latitude, longitude).	required
`zoom`	`int`	The zoom level.	required

Returns:

Type	Description
`tuple[tuple[float, float], tuple[float, float]]`	A tuple of (x_range, y_range).

Source code in geemap/common.py

def center_zoom_to_xy_range(
    center: tuple[float, float], zoom: int
) -> tuple[tuple[float, float], tuple[float, float]]:
    """Convert center and zoom to x and y range to be used as input to bokeh map.

    Args:
        center: A tuple of (latitude, longitude).
        zoom: The zoom level.

    Returns:
        A tuple of (x_range, y_range).
    """
    if isinstance(center, (tuple, 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)` ¶

Returns the normalized Google basemap name.

Parameters:

Name	Type	Description	Default
`basemap`	`str`	The basemap name.	required

Source code in geemap/common.py

def check_basemap(basemap: str) -> str:
    """Returns the normalized Google basemap name.

    Args:
        basemap: The basemap name.
    """
    if not isinstance(basemap, str):
        return basemap

    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()]

    return basemap

`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:

Type	Description
`str`	The path to the directory.

Source code in geemap/common.py

def check_dir(dir_path: str, make_dirs: bool = True) -> str:
    """Checks if a directory exists and creates it if it does not.

    Args:
        dir_path: The path to the directory.
        make_dirs: 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:
        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:

Type	Description
`str`	The absolute path to the file.

Source code in geemap/common.py

def check_file_path(file_path: str, make_dirs: bool = True) -> str:
    """Gets the absolute file path.

    Args:
        file_path: The path to the file.
        make_dirs: 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:
        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:

Type	Description
`bool`	Returns True if Git is installed, otherwise returns False.

Source code in geemap/common.py

def check_git_install() -> bool:
    """Checks if Git is installed.

    Returns:
        Returns True if Git is installed, otherwise returns False.
    """
    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`	`str`	The HTML string with local images converted to base64.

Source code in geemap/common.py

def check_html_string(html_string: str) -> str:
    """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.
    """
    # Search for img tags with src attribute
    img_regex = r'<img[^>]+src\s*=\s*["\']([^"\':]+)["\'][^>]*>'

    for match in re.findall(img_regex, html_string):
        img_data = pathlib.Path(match).read_bytes()
        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_map_functions(input_lines)` ¶

Extracts Earth Engine map function.

Parameters:

Name	Type	Description	Default
`input_lines`	`Sequence[str]`	List of Earth Engine JavaScript.	required

Returns:

Type	Description
`list[str]`	Output JavaScript with map function.

Source code in geemap/conversion.py

def check_map_functions(input_lines: Sequence[str]) -> list[str]:
    """Extracts Earth Engine map function.

    Args:
        input_lines: List of Earth Engine JavaScript.

    Returns:
        Output JavaScript with map function.
    """
    output_lines = []
    current_num_of_nested_funcs = 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]
            )  # pytype: disable=unsupported-operands

            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
                )  # pytype: disable=wrong-arg-types

                func_start_index = line.index("function")
                func_name = "func_" + coreutils.random_string()
                func_header = line[func_start_index:].replace(
                    "function", "function " + func_name
                )
                output_lines.append("\n")
                output_lines.append(func_header)

                current_num_of_nested_funcs += 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(
                        ("    " * current_num_of_nested_funcs) + tmp_line
                    )
                    if "{" in tmp_line:
                        current_num_of_nested_funcs += 1
                    if "}" in tmp_line:
                        current_num_of_nested_funcs -= 1
                    input_lines[index + 1 + sub_index] = (
                        ""  # pytype: disable=unsupported-operands
                    )

                current_num_of_nested_funcs -= 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  # pytype: disable=unsupported-operands
                )

                output_lines.append(header_line)
            except Exception as e:
                print(
                    f"An error occurred: {e}. "
                    f"The closing curly bracket could not be found in Line {index+1}: "
                    f"{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.

Source code in geemap/common.py

def check_titiler_endpoint(
    titiler_endpoint: str | None = None,
) -> str | TitilerEndpoint:
    """Returns the default titiler endpoint."""
    if titiler_endpoint is None:
        if os.environ.get("TITILER_ENDPOINT") is not None:
            titiler_endpoint = os.environ.get("TITILER_ENDPOINT")
            assert titiler_endpoint is not None  # For pytype.

            if titiler_endpoint == "planetary-computer":
                titiler_endpoint = PlanetaryComputerEndpoint()
        else:
            titiler_endpoint = "https://giswqs-titiler-endpoint.hf.space"
    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 geopandas as gpd
    import mapclassify

    if isinstance(data, (gpd.GeoDataFrame, 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 = [coreutils.check_color(i) for i in colors]
    elif isinstance(colors, str):
        colors = [coreutils.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.
    """
    import fiona
    import rasterio
    import rasterio.mask

    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://", "https://")):
            mask = coreutils.download_file(mask, output)
        if not os.path.exists(mask):
            raise FileNotFoundError(f"{mask} does not exist.")
    elif isinstance(mask, (list, dict)):
        if isinstance(mask, list):
            geojson = {
                "type": "FeatureCollection",
                "features": [
                    {
                        "type": "Feature",
                        "properties": {},
                        "geometry": {"type": "Polygon", "coordinates": [mask]},
                    }
                ],
            }
        else:
            geojson = {
                "type": "FeatureCollection",
                "features": [mask],
            }
        mask = coreutils.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: str, out_dir: str) -> None:
    """Clones a GitHub repository.

    Args:
        url: The link to the GitHub repository
        out_dir: The output directory for the cloned repository.
    """
    repo_name = os.path.basename(url)
    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 user 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 \| None`	The output directory for the cloned repository. Defaults to None.	`None`

Source code in geemap/common.py

def clone_google_repo(url: str, out_dir: str | None = None):
    """Clones an Earth Engine user repository.

    From https://earthengine.googlesource.com, such as
    https://earthengine.googlesource.com/users/google/datasets

    Args:
        url: The link to the Earth Engine repository
        out_dir: 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: str = ".", unzip: bool = True) -> None:
    """Clones the geemap GitHub repository.

    Args:
        out_dir: Output folder for the repo. Defaults to '.'.
        unzip: 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 \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`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: str, titiler_endpoint: str | None = None, timeout: int = 300):
    """Get band names of a Cloud Optimized GeoTIFF (COG).

    Args:
        url: 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: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        timeout: 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()

    return [b[0] for b in r["band_descriptions"]]

`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 \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`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: str, titiler_endpoint: str | None = None, timeout: int = 300):
    """Get the bounding box of a Cloud Optimized GeoTIFF (COG).

    Args:
        url: 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: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        timeout: 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 \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`None`

Returns:

Name	Type	Description
`tuple`		A tuple representing (longitude, latitude)

Source code in geemap/common.py

def cog_center(url: str, titiler_endpoint: str | None = None):
    """Get the centroid of a Cloud Optimized GeoTIFF (COG).

    Args:
        url: 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: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".

    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)

    # lat, lon
    return (bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2

`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 \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`None`
`return_geojson`	`bool`	TODO.	`False`
`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: str,
    titiler_endpoint: str | None = None,
    return_geojson: bool = False,
    timeout: int = 300,
):
    """Get band statistics of a Cloud Optimized GeoTIFF (COG).

    Args:
        url: 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: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        return_geojson: TODO.
        timeout: 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"

    return requests.get(
        f"{titiler_endpoint}/cog/{info}",
        params={
            "url": url,
        },
        timeout=timeout,
    ).json()

`cog_mosaic(links, titiler_endpoint=None, username='anonymous', layername=None, overwrite=False, verbose=True, timeout=300, **unused_kwargs)` ¶

Creates a COG mosaic from a list of COG URLs.

Parameters:

Name	Type	Description	Default
`links`	`list[str]`	A list containing COG HTTP URLs.	required
`titiler_endpoint`	`str \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`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:

Type	Description
`str`	The tile URL for the COG mosaic.

Source code in geemap/common.py

def cog_mosaic(
    links: list[str],
    titiler_endpoint: str | None = None,
    username: str = "anonymous",
    layername=None,
    overwrite: bool = False,
    verbose: bool = True,
    timeout: int = 300,
    **unused_kwargs,
) -> str:
    """Creates a COG mosaic from a list of COG URLs.

    Args:
        links: A list containing COG HTTP URLs.
        titiler_endpoint: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        username: User name for the titiler endpoint. Defaults to "anonymous".
        layername ([type], optional): Layer name to use. Defaults to None.
        overwrite: Whether to overwrite the layer name if existing. Defaults to False.
        verbose: Whether to print out descriptive information. Defaults to True.
        timeout: Timeout in seconds. Defaults to 300.

    Raises:
        Exception: If the COG mosaic fails to create.

    Returns:
        The tile URL for the COG mosaic.
    """
    del overwrite  # Unused.

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    if layername is None:
        layername = "layer_" + coreutils.random_string(5)

    if verbose:
        print("Creating COG masaic ...")

    r = requests.post(
        f"{titiler_endpoint}/tokens/create",
        json={"username": username, "scope": ["mosaic:read", "mosaic:create"]},
    ).json()
    token = r["token"]

    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]

`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 \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`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:

Type	Description
`str`	The tile URL for the COG mosaic.

Source code in geemap/common.py

def cog_mosaic_from_file(
    filepath: str,
    skip_rows: int = 0,
    titiler_endpoint: str | None = None,
    username: str = "anonymous",
    layername=None,
    overwrite: bool = False,
    verbose: bool = True,
    **kwargs,
) -> str:
    """Creates a COG mosaic from a csv/txt file stored locally for through HTTP URL.

    Args:
        filepath: Local path or HTTP URL to the csv/txt file containing COG URLs.
        skip_rows: The number of rows to skip in the file. Defaults to 0.
        titiler_endpoint: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        username: User name for the titiler endpoint. Defaults to "anonymous".
        layername ([type], optional): Layer name to use. Defaults to None.
        overwrite: Whether to overwrite the layer name if existing. Defaults to False.
        verbose: Whether to print out descriptive information. Defaults to True.

    Returns:
        The tile URL for the COG mosaic.
    """
    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    links = []
    if filepath.startswith(("http://", "https://")):
        with urllib.request.urlopen(filepath) as data:
            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:]

    return cog_mosaic(
        links, titiler_endpoint, username, layername, overwrite, verbose, **kwargs
    )

`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 \| None`	Dataset band indexes (e.g bidx=1, bidx=1&bidx=2&bidx=3). Defaults to None.	`None`
`titiler_endpoint`	`str \| None`	Titiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space", "planetary-computer", "pc". Defaults to None.	`None`
`timeout`	`int`	Timeout in seconds. Defaults to 300.	`300`

Returns:

Name	Type	Description
`list`	`dict[str, float] \| None`	A dictionary of band info.

Source code in geemap/common.py

def cog_pixel_value(
    lon: float,
    lat: float,
    url: str,
    bidx: str | None = None,
    titiler_endpoint: str | None = None,
    timeout: int = 300,
    **kwargs,
) -> dict[str, float] | None:
    """Get pixel value from COG.

    Args:
        lon: Longitude of the pixel.
        lat: Latitude of the pixel.
        url: HTTP URL to a COG, e.g.,
            'https://github.com/opengeos/data/releases/download/raster/Libya-2023-07-01.tif'
        bidx: Dataset band indexes (e.g bidx=1, bidx=1&bidx=2&bidx=3). Defaults to None.
        titiler_endpoint: Titiler endpoint, e.g.,
            "https://giswqs-titiler-endpoint.hf.space", "planetary-computer",
            "pc". Defaults to None.
        timeout: 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 "detail" in r:
        print(r["detail"])
        return None

    values = r["values"]
    return dict(zip(bands, values))

`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 \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`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: str, titiler_endpoint: str | None = None, timeout: int = 300):
    """Get band statistics of a Cloud Optimized GeoTIFF (COG).

    Args:
        url: 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: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        timeout: 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)
    return requests.get(
        f"{titiler_endpoint}/cog/statistics",
        params={
            "url": url,
        },
        timeout=timeout,
    ).json()

`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
`bands`	`list[str] \| None`	A list of band names.	`None`
`titiler_endpoint`	`str \| None`	Titiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	`None`
`timeout`	`int`	Timeout in seconds. Defaults to 300.	`300`
`proxies`	`dict \| None`	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: str,
    bands: list[str] | None = None,
    titiler_endpoint: str | None = None,
    timeout: int = 300,
    proxies: dict | None = 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: HTTP URL to a COG, e.g.,
            https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        bands: A list of band names.
        titiler_endpoint: Titiler endpoint. Defaults to
            "https://giswqs-titiler-endpoint.hf.space".
        timeout: Timeout in seconds. Defaults to 300.
        proxies: 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).
    """
    from rio_cogeo.cogeo import cog_validate, cog_info

    if not source.startswith(("http://", "https://")):
        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)

    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]

    return collection.reduceColumns(
        **{"selectors": selectors, "reducer": stats_dict[stats_type]}
    )

`combine_gif_with_chart(base_gif, chart_frames, chart_position, chart_size_ratio, spacer_width, fps, loop)` ¶

Combine GIF with chart frames.

Source code in geemap/timelapse.py

def combine_gif_with_chart(
    base_gif, chart_frames, chart_position, chart_size_ratio, spacer_width, fps, loop
):
    """Combine GIF with chart frames."""
    del chart_size_ratio  # Unused.

    base_image = Image.open(base_gif)
    base_frames = []

    # Extract all frames from base gif.
    try:
        while True:
            base_frames.append(base_image.copy())
            base_image.seek(base_image.tell() + 1)
    except EOFError:
        pass

    # Create combined frames.
    combined_frames = []
    temp_dir = tempfile.mkdtemp()

    for i, base_frame in enumerate(base_frames):
        base_frame = base_frame.convert("RGB")

        # Get corresponding chart frame (cycle if needed).
        chart_idx = i % len(chart_frames) if chart_frames else 0

        if chart_frames:
            chart_frame = Image.open(chart_frames[chart_idx])
            chart_frame = chart_frame.convert("RGB")

            # Calculate dimensions.
            base_width, base_height = base_frame.size
            chart_width, chart_height = chart_frame.size

            # Create combined image based on position.
            if chart_position == "right":
                combined_width = base_width + spacer_width + chart_width
                combined_height = max(base_height, chart_height)
                combined_frame = Image.new(
                    "RGB", (combined_width, combined_height), "white"
                )
                combined_frame.paste(base_frame, (0, 0))
                combined_frame.paste(chart_frame, (base_width + spacer_width, 0))

            elif chart_position == "left":
                combined_width = chart_width + spacer_width + base_width
                combined_height = max(base_height, chart_height)
                combined_frame = Image.new(
                    "RGB", (combined_width, combined_height), "white"
                )
                combined_frame.paste(chart_frame, (0, 0))
                combined_frame.paste(base_frame, (chart_width + spacer_width, 0))

            elif chart_position == "bottom":
                combined_width = max(base_width, chart_width)
                combined_height = base_height + spacer_width + chart_height
                combined_frame = Image.new(
                    "RGB", (combined_width, combined_height), "white"
                )
                combined_frame.paste(base_frame, (0, 0))
                combined_frame.paste(chart_frame, (0, base_height + spacer_width))

            else:  # Default to right.
                combined_width = base_width + spacer_width + chart_width
                combined_height = max(base_height, chart_height)
                combined_frame = Image.new(
                    "RGB", (combined_width, combined_height), "white"
                )
                combined_frame.paste(base_frame, (0, 0))
                combined_frame.paste(chart_frame, (base_width + spacer_width, 0))

        else:
            combined_frame = base_frame

        combined_frames.append(combined_frame)

    # Save combined gif.
    output_path = base_gif.replace(".gif", "_with_chart.gif")

    if combined_frames:
        combined_frames[0].save(
            output_path,
            save_all=True,
            append_images=combined_frames[1:],
            duration=int(1000 / fps),
            loop=loop,
            optimize=True,
        )

    # Clean up chart frames.
    for frame_path in chart_frames:
        if os.path.exists(frame_path):
            os.remove(frame_path)

    return output_path

`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 \| None`	User name to access the database. Defaults to None.	`None`
`password`	`str \| None`	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: str,
    host: str = "localhost",
    user: str | None = None,
    password: str | None = None,
    port: int = 5432,
    use_env_var: bool = False,
):
    """Connects to a PostGIS database.

    Args:
        database: Name of the database
        host: Hosting server for the database. Defaults to "localhost".
        user: User name to access the database. Defaults to None.
        password: Password to access the database. Defaults to None.
        port: Port number to connect to at the server host. Defaults to 5432.
        use_env_var: 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]
    """
    import sqlalchemy

    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}"
    return sqlalchemy.create_engine(connection_string)

`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:

Type	Description
`str`	Converted Python for loop.

Source code in geemap/conversion.py

def convert_for_loop(line: str) -> str:
    """Converts JavaScript for loop to Python for loop.

    Args:
        line: Input JavaScript for loop

    Returns:
        Converted Python for loop.
    """
    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 + f"{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 + f"{param_name} in range({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.
    """
    import laspy

    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

    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`	`Sequence[Sequence[float]]`	A list of bbox coordinates representing [left, bottom, right, top].	required

Returns:

Type	Description
`dict[str, Any]`	A geojson FeatureCollection.

Source code in geemap/common.py

def coords_to_geojson(coords: Sequence[Sequence[float]]) -> dict[str, Any]:
    """Convert a list of bbox coordinates representing [left, bottom, right, top] to geojson FeatureCollection.

    Args:
        coords: A list of bbox coordinates representing [left, bottom, right, top].

    Returns:
        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() -> None:
    """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() -> None:
    """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_colorbar(width=150, height=30, palette=None, 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'].	`None`
`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: list[int | str] | None = None,
    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.
    """
    palette = palette or ["blue", "green", "red"]
    from PIL import Image, ImageDraw, ImageFont

    warnings.simplefilter("ignore")
    # pytype: disable=attribute-error
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    # pytype: enable=attribute-error

    if out_file is None:
        filename = f"colorbar_{coreutils.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: float, a: float, b: float, c: float, d: float = 0) -> float:
        return a * math.exp(-((x - b) ** 2) / (2 * c**2)) + d

    def pixel(
        x, width: float = 100, color_map=None, spread: float = 1
    ) -> tuple[float, float, float]:
        color_map = color_map or []

        width = float(width)
        r = sum(
            [
                gaussian(x, p[1][0], p[0] * width, width / (spread * len(color_map)))
                for p in color_map
            ]
        )
        g = sum(
            [
                gaussian(x, p[1][1], p[0] * width, width / (spread * len(color_map)))
                for p in color_map
            ]
        )
        b = sum(
            [
                gaussian(x, p[1][2], p[0] * width, width / (spread * len(color_map)))
                for p in color_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, color_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=coreutils.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 = coreutils.check_color(font_color)

        draw = ImageDraw.Draw(im)
        w, h = draw.textsize(labels[0], font=font)  # pytype: disable=attribute-error

        for label in labels:
            w_tmp, h_tmp = draw.textsize(label, font)  # pytype: disable=attribute-error
            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)  # pytype: disable=attribute-error

            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.

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 \| None`	The kernel to use for smoothing image.	`None`
`region`	`Geometry \| FeatureCollection \| None`	The region of interest.	`None`
`values`	`list[float] \| List \| None`	Values to create contours for.	`None`

Returns:

Type	Description
`Image`	The image containing contours.

Source code in geemap/common.py

def create_contours(
    image: ee.Image,
    min_value: float,
    max_value: float,
    interval: float,
    kernel: ee.Kernel | None = None,
    region: ee.Geometry | ee.FeatureCollection | None = None,
    values: list[float] | ee.List | None = None,
) -> ee.Image:
    """Creates contours from an image.

    Code adapted from https://mygeoblog.com/2017/01/28/contour-lines-in-gee.

    Args:
        image: An image to create contours.
        min_value: The minimum value of contours.
        max_value: The maximum value of contours.
        interval: The interval between contours.
        kernel: The kernel to use for smoothing image.
        region: The region of interest.
        values: Values to create contours for.

    Returns:
        The image containing contours.
    """
    if not isinstance(image, ee.Image):
        raise TypeError("The image must be an ee.Image.")

    if region is not None and not isinstance(
        region, (ee.FeatureCollection, ee.Geometry)
    ):
        raise TypeError("The region must be an ee.Geometry or ee.FeatureCollection.")

    kernel = kernel or ee.Kernel.gaussian(5, 3)

    if isinstance(values, list):
        values = ee.List(values)
    elif isinstance(values, ee.List):
        pass
    elif values is None:
        values = ee.List.sequence(min_value, max_value, interval)
    else:
        raise TypeError("The values must be a list or ee.List.")

    def contouring(value: ee.Number) -> ee.Image:
        contour = (
            image.convolve(kernel)
            .subtract(ee.Image.constant(value))
            .zeroCrossing()
            .multiply(ee.Image.constant(value).toFloat())
        )
        return contour.mask(contour)

    contours = values.map(contouring)

    if region is not None:
        if isinstance(region, ee.FeatureCollection):
            return ee.ImageCollection(contours).mosaic().clipToCollection(region)
        if isinstance(region, ee.Geometry):
            return ee.ImageCollection(contours).mosaic().clip(region)
        # Should never reach here.

    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.

    """
    import streamlit as st

    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
            )

        if 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,
                )

        return st.download_button(
            label,
            label,
            data,
            file_name,
            mime,
            key,
            help,
            on_click,
            args,
            **kwargs,
        )

`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`	Defaults to "Click here to download: ".	`'Click here to download: '`

Returns:

Type	Description
`HTML`	HTML download URL.

Source code in geemap/common.py

def create_download_link(
    filename: str, title: str = "Click here to download: "
) -> HTML:
    """Downloads a file from voila.

    Adopted from https://github.com/voila-dashboards/voila/issues/578

    Args:
        filename: The file path to the file to download.
        title: Defaults to "Click here to download: ".

    Returns:
        HTML download URL.
    """
    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 \| Any`	The grid cell size.	required
`proj`	`str \| Any \| None`	The projection. Defaults to None.	`None`

Returns:

Type	Description
`FeatureCollection`	The grid as a feature collection.

Source code in geemap/common.py

def create_grid(
    ee_object: ee.Image | ee.Geometry | ee.FeatureCollection,
    scale: float | Any,
    proj: str | Any | None = None,
) -> ee.FeatureCollection:
    """Create a grid covering an Earth Engine object.

    Args:
        ee_object: The Earth Engine object.
        scale: The grid cell size.
        proj: The projection. Defaults to None.

    Returns:
        The grid as a feature collection.
    """
    if isinstance(ee_object, (ee.FeatureCollection, 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()

    return geometry.coveringGrid(proj, scale)

create_landsat_index_timelapse(roi, out_gif, start_year, end_year, start_date, end_date, bands, indices, vis_params, dimensions, frames_per_second, crs, apply_fmask, overlay_data, overlay_color, overlay_width, overlay_opacity, frequency, reducer, date_format, title, title_xy, add_text, text_xy, text_sequence, font_type, font_size, font_color, add_progress_bar, progress_bar_color, progress_bar_height, add_colorbar, colorbar_width, colorbar_height, colorbar_label, colorbar_label_size, colorbar_label_weight, colorbar_tick_size, colorbar_bg_color, colorbar_orientation, colorbar_dpi, colorbar_xy, colorbar_size, loop, fading, step, **kwargs) ¶

Create a Landsat timelapse with indices.

Source code in geemap/timelapse.py

def create_landsat_index_timelapse(
    roi,
    out_gif,
    start_year,
    end_year,
    start_date,
    end_date,
    bands,
    indices,
    vis_params,
    dimensions,
    frames_per_second,
    crs,
    apply_fmask,
    overlay_data,
    overlay_color,
    overlay_width,
    overlay_opacity,
    frequency,
    reducer,
    date_format,
    title,
    title_xy,
    add_text,
    text_xy,
    text_sequence,
    font_type,
    font_size,
    font_color,
    add_progress_bar,
    progress_bar_color,
    progress_bar_height,
    add_colorbar,
    colorbar_width,
    colorbar_height,
    colorbar_label,
    colorbar_label_size,
    colorbar_label_weight,
    colorbar_tick_size,
    colorbar_bg_color,
    colorbar_orientation,
    colorbar_dpi,
    colorbar_xy,
    colorbar_size,
    loop,
    fading,
    step,
    **kwargs,
):
    """Create a Landsat timelapse with indices."""
    del indices, kwargs  # Unused.

    if end_year is None:
        end_year = get_current_year()

    # Create time series with indices.
    base_ts_collection = landsat_timeseries(
        roi,
        start_year,
        end_year,
        start_date,
        end_date,
        apply_fmask,
        frequency,
        date_format,
        step,
    )

    # Add indices to each image.
    # pytype: disable=attribute-error
    ts_collection = base_ts_collection.map(calculate_landsat_indices)
    # pytype: enable=attribute-error

    # Use create_timelapse with the index collection.
    start = f"{start_year}-{start_date}"
    end = f"{end_year}-{end_date}"

    return create_timelapse(
        ts_collection,
        start,
        end,
        roi,
        bands,
        frequency,
        reducer,
        date_format,
        out_gif,
        None,
        vis_params,
        dimensions,
        frames_per_second,
        crs,
        overlay_data,
        overlay_color,
        overlay_width,
        overlay_opacity,
        title,
        title_xy,
        add_text,
        text_xy,
        text_sequence,
        font_type,
        font_size,
        font_color,
        add_progress_bar,
        progress_bar_color,
        progress_bar_height,
        add_colorbar,
        colorbar_width,
        colorbar_height,
        colorbar_label,
        colorbar_label_size,
        colorbar_label_weight,
        colorbar_tick_size,
        colorbar_bg_color,
        colorbar_orientation,
        colorbar_dpi,
        colorbar_xy,
        colorbar_size,
        loop,
        False,
        fading,
        1,
        1,
    )

`create_landsat_time_series_chart_frames(sample_data, chart_title, chart_ylabel, dimensions, fps, xlabel_format='auto', xlabel_interval='auto')` ¶

Create frames for the Landsat time series chart with current time indicator.

Parameters:

Name	Type	Description	Default
`sample_data`	`dict`	Sample data for each point/band combination.	required
`chart_title`	`str`	Title for the chart.	required
`chart_ylabel`	`str`	Y-axis label.	required
`dimensions`	`int / str`	Dimensions for the chart.	required
`fps`	`int`	Frames per second.	required
`xlabel_format`	`str`	Format for x-axis labels.	`'auto'`
`xlabel_interval`	`str`	Interval for x-axis labels.	`'auto'`

Returns:

Type	Description
`list[str]`	List of paths to chart frame images.

Source code in geemap/timelapse.py

def create_landsat_time_series_chart_frames(
    sample_data,
    chart_title: str,
    chart_ylabel: str,
    dimensions,
    fps: int,
    xlabel_format: str = "auto",
    xlabel_interval: str = "auto",
) -> list[str]:
    """Create frames for the Landsat time series chart with current time indicator.

    Args:
        sample_data (dict): Sample data for each point/band combination.
        chart_title: Title for the chart.
        chart_ylabel: Y-axis label.
        dimensions (int/str): Dimensions for the chart.
        fps: Frames per second.
        xlabel_format: Format for x-axis labels.
        xlabel_interval: Interval for x-axis labels.

    Returns:
        List of paths to chart frame images.
    """
    del fps  # Unused.

    if not sample_data:
        return []

    # Get all unique dates across all points/bands.
    all_dates = set()
    for point_data in sample_data.values():
        all_dates.update(point_data["dates"])

    if not all_dates:
        return []

    sorted_dates = sorted(list(all_dates))

    # Create chart frames.
    chart_frames = []
    temp_dir = tempfile.mkdtemp()

    # Calculate chart dimensions.
    if isinstance(dimensions, str) and "x" in dimensions:
        width, height = map(int, dimensions.split("x"))
    else:
        width = height = int(dimensions) if isinstance(dimensions, int) else 768

    chart_width = int(width * 0.8)  # 80% of gif width.
    chart_height = height

    try:
        for frame_idx, current_date in enumerate(sorted_dates):
            fig, ax = plt.subplots(
                figsize=(chart_width / 100, chart_height / 100), dpi=100
            )

            # Plot all time series.
            for point_key, point_data in sample_data.items():
                if point_data["dates"] and point_data["values"]:
                    # Use custom label if available, otherwise use point_key.
                    label = point_data.get("label", point_key)

                    ax.plot(
                        point_data["dates"],
                        point_data["values"],
                        color=point_data["color"],
                        label=label,
                        linewidth=2,
                        marker="o",
                        markersize=4,
                    )

            # Add vertical line for current time.
            ax.axvline(
                x=current_date, color="red", linestyle="--", linewidth=2, alpha=0.8
            )

            ax.set_xlabel("Date", fontsize=10)
            ax.set_ylabel(chart_ylabel, fontsize=10)
            ax.set_title(chart_title, fontsize=12)
            ax.legend(fontsize=8, loc="upper left")
            ax.grid(True, alpha=0.3)

            # Format x-axis based on parameters or auto-detect.
            date_range = (max(sorted_dates) - min(sorted_dates)).days

            if xlabel_format == "auto" or xlabel_interval == "auto":
                # Auto-detect based on data characteristics.
                # Landsat typically has longer time series (annual data).
                if (
                    date_range <= 365
                ):  # Less than 1 year - likely monthly/quarterly data.
                    format_str = "%Y-%m"
                    locator = mdates.MonthLocator(
                        interval=max(1, len(sorted_dates) // 8)
                    )
                elif date_range <= 1825:  # Less than 5 years - yearly data.
                    format_str = "%Y"
                    locator = mdates.YearLocator()
                else:  # Long time series - multi-year intervals.
                    format_str = "%Y"
                    year_interval = max(1, len(sorted_dates) // 15)
                    locator = mdates.YearLocator(base=year_interval)
            else:
                # Use manual settings.
                format_str = xlabel_format if xlabel_format != "auto" else "%Y"

                if xlabel_interval == "day":
                    locator = mdates.DayLocator(
                        interval=max(1, len(sorted_dates) // 15)
                    )
                elif xlabel_interval == "week":
                    locator = mdates.WeekdayLocator(
                        interval=max(1, len(sorted_dates) // 10)
                    )
                elif xlabel_interval == "month":
                    locator = mdates.MonthLocator(
                        interval=max(1, len(sorted_dates) // 8)
                    )
                elif xlabel_interval == "year":
                    locator = mdates.YearLocator()
                else:
                    locator = mdates.YearLocator()

            ax.xaxis.set_major_formatter(mdates.DateFormatter(format_str))
            ax.xaxis.set_major_locator(locator)

            plt.setp(ax.xaxis.get_majorticklabels(), rotation=45, fontsize=8)

            # Set consistent y-axis limits.
            all_values = []
            for point_data in sample_data.values():
                all_values.extend([v for v in point_data["values"] if v is not None])

            if all_values:
                y_min, y_max = min(all_values), max(all_values)
                y_range = y_max - y_min
                if y_range > 0:
                    ax.set_ylim(y_min - y_range * 0.1, y_max + y_range * 0.1)
                else:
                    ax.set_ylim(y_min - 0.01, y_max + 0.01)

            plt.tight_layout()

            # Save frame.
            frame_path = os.path.join(temp_dir, f"chart_frame_{frame_idx:04d}.png")
            plt.savefig(frame_path, dpi=100, bbox_inches="tight", facecolor="white")
            plt.close()

            chart_frames.append(frame_path)

    except Exception as e:
        print(f"Error creating chart frames: {str(e)}")
        # Clean up any created frames.
        for frame_path in chart_frames:
            if os.path.exists(frame_path):
                os.remove(frame_path)
        return []

    return chart_frames

`create_legend(title='Legend', labels=None, colors=None, legend_dict=None, builtin_legend=None, opacity=1.0, position='bottomright', draggable=True, output=None, style=None)` ¶

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[str] \| None`	A list of legend labels. Defaults to None.	`None`
`legend_dict`	`dict[str, str] \| None`	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 \| None`	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 \| None`	The output file path (*.html) to save the legend. Defaults to None.	`None`
`style`	`dict \| None`	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' }	`None`

Returns:

Name	Type	Description
`str`		The HTML code of the legend.

Source code in geemap/common.py

def create_legend(
    title: str = "Legend",
    labels: list[str] | None = None,
    colors=None,
    legend_dict: dict[str, str] | None = None,
    builtin_legend: str | None = None,
    opacity: float = 1.0,
    position: str = "bottomright",
    draggable: bool = True,
    output: str | None = None,
    style: dict | None = None,
):
    """Create a legend in HTML format. Reference: https://bit.ly/3oV6vnH

    Args:
        title: Title of the legend. Defaults to 'Legend'. Defaults to "Legend".
        colors (list, optional): A list of legend colors. Defaults to None.
        labels: A list of legend labels. Defaults to None.
        legend_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.
        builtin_legend: Name of the builtin legend to add to the map. Defaults to None.
        opacity: The opacity of the legend. Defaults to 1.0.
        position: The position of the legend, can be one of the following:
            "topleft", "topright", "bottomleft", "bottomright". Defaults to "bottomright".
        draggable: If True, the legend can be dragged to a new position. Defaults to True.
        output: 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

    style = style or {}

    # pytype: disable=attribute-error
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    # pytype: enable=attribute-error

    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

        if all(isinstance(item, tuple) for item in colors):
            try:
                colors = [coreutils.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 = [coreutils.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:{coreutils.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]
                    # pytype: disable=attribute-error
                    if not color.startswith("#"):
                        color = "#" + color
                    # pytype: enable=attribute-error
                    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 None:
        return legend_text

    with open(output, "w") as f:
        f.write(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: str, replace: bool = False) -> None:
    """Create a new cell in Jupyter notebook based on the contents.

    Args:
        contents: A string of Python code.
    """
    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: str) -> None:
    """Create a QGIS Layer Style (.qml) for NLCD data.

    Args:
        out_qml: File path to the output qml.
    """
    # pytype: disable=attribute-error
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    # pytype: enable=attribute-error

    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_s2_time_series_chart_frames(sample_data, chart_title, chart_ylabel, dimensions, fps, xlabel_format='auto', xlabel_interval='auto')` ¶

Create frames for the Sentinel-2 time series chart with current time indicator.

Parameters:

Name	Type	Description	Default
`sample_data`	`dict`	Dictionary containing sample data for each point/band combination.	required
`chart_title`	`str`	Title for the chart.	required
`chart_ylabel`	`str`	Y-axis label.	required
`dimensions`	`int \| str`	Dimensions for the chart.	required
`fps`	`int`	Frames per second.	required
`xlabel_format`	`str`	Format for x-axis labels.	`'auto'`
`xlabel_interval`	`str`	Interval for x-axis labels.	`'auto'`

Returns:

Type	Description
	List of paths to chart frame images.

Source code in geemap/timelapse.py

def create_s2_time_series_chart_frames(
    sample_data: dict,
    chart_title: str,
    chart_ylabel: str,
    dimensions: int | str,
    fps: int,
    xlabel_format: str = "auto",
    xlabel_interval: str = "auto",
):
    """Create frames for the Sentinel-2 time series chart with current time indicator.

    Args:
        sample_data: Dictionary containing sample data for each point/band combination.
        chart_title: Title for the chart.
        chart_ylabel: Y-axis label.
        dimensions: Dimensions for the chart.
        fps: Frames per second.
        xlabel_format: Format for x-axis labels.
        xlabel_interval: Interval for x-axis labels.

    Returns:
        List of paths to chart frame images.
    """
    del fps  # Unused.

    if not sample_data:
        return []

    # Get all unique dates across all points/bands.
    all_dates = set()
    for point_data in sample_data.values():
        all_dates.update(point_data["dates"])

    if not all_dates:
        return []

    sorted_dates = sorted(list(all_dates))

    # Create chart frames.
    chart_frames = []
    temp_dir = tempfile.mkdtemp()

    # Calculate chart dimensions
    if isinstance(dimensions, str) and "x" in dimensions:
        width, height = map(int, dimensions.split("x"))
    else:
        width = height = int(dimensions) if isinstance(dimensions, int) else 768

    chart_width = int(width * 0.8)  # 80% of gif width.
    chart_height = height

    try:
        for frame_idx, current_date in enumerate(sorted_dates):
            fig, ax = plt.subplots(
                figsize=(chart_width / 100, chart_height / 100), dpi=100
            )

            # Plot all time series.
            for point_key, point_data in sample_data.items():
                if point_data["dates"] and point_data["values"]:
                    # Use custom label if available, otherwise use point_key.
                    label = point_data.get("label", point_key)

                    ax.plot(
                        point_data["dates"],
                        point_data["values"],
                        color=point_data["color"],
                        label=label,
                        linewidth=2,
                        marker="o",
                        markersize=4,
                    )

            # Add vertical line for current time.
            ax.axvline(
                x=current_date, color="red", linestyle="--", linewidth=2, alpha=0.8
            )

            # Formatting.
            ax.set_xlabel("Date", fontsize=10)
            ax.set_ylabel(chart_ylabel, fontsize=10)
            ax.set_title(chart_title, fontsize=12)
            ax.legend(fontsize=8, loc="upper left")
            ax.grid(True, alpha=0.3)

            # Format x-axis based on parameters or auto-detect.
            date_range = (max(sorted_dates) - min(sorted_dates)).days

            if xlabel_format == "auto" or xlabel_interval == "auto":
                # Auto-detect based on data characteristics.
                if date_range <= 30:  # Less than 1 month.
                    format_str = "%m-%d"
                    if len(sorted_dates) <= 10:
                        locator = mdates.DayLocator(interval=max(1, date_range // 10))
                    else:
                        locator = mdates.WeekdayLocator(interval=1)
                elif date_range <= 90:  # Less than 3 months.
                    format_str = "%m-%d"
                    if len(sorted_dates) <= 15:
                        locator = mdates.WeekdayLocator(interval=1)
                    else:
                        locator = mdates.WeekdayLocator(
                            interval=max(1, len(sorted_dates) // 10)
                        )
                elif date_range <= 365:  # Less than 1 year.
                    format_str = "%Y-%m"
                    locator = mdates.MonthLocator(
                        interval=max(1, len(sorted_dates) // 8)
                    )
                else:  # More than 1 year.
                    format_str = "%Y"
                    locator = mdates.YearLocator()
            else:
                # Use manual settings.
                format_str = xlabel_format if xlabel_format != "auto" else "%Y-%m-%d"

                if xlabel_interval == "day":
                    locator = mdates.DayLocator(
                        interval=max(1, len(sorted_dates) // 15)
                    )
                elif xlabel_interval == "week":
                    locator = mdates.WeekdayLocator(
                        interval=max(1, len(sorted_dates) // 10)
                    )
                elif xlabel_interval == "month":
                    locator = mdates.MonthLocator(
                        interval=max(1, len(sorted_dates) // 8)
                    )
                elif xlabel_interval == "year":
                    locator = mdates.YearLocator()
                else:
                    locator = mdates.WeekdayLocator(
                        interval=max(1, len(sorted_dates) // 10)
                    )

            ax.xaxis.set_major_formatter(mdates.DateFormatter(format_str))
            ax.xaxis.set_major_locator(locator)

            # Add minor ticks for better granularity.
            if date_range <= 90:
                ax.xaxis.set_minor_locator(mdates.DayLocator(interval=1))

            plt.setp(ax.xaxis.get_majorticklabels(), rotation=45, fontsize=8)

            # Set consistent y-axis limits.
            all_values = []
            for point_data in sample_data.values():
                all_values.extend([v for v in point_data["values"] if v is not None])

            if all_values:
                y_min, y_max = min(all_values), max(all_values)
                y_range = y_max - y_min
                if y_range > 0:
                    ax.set_ylim(y_min - y_range * 0.1, y_max + y_range * 0.1)
                else:
                    ax.set_ylim(y_min - 0.01, y_max + 0.01)

            plt.tight_layout()

            # Save frame.
            frame_path = os.path.join(temp_dir, f"chart_frame_{frame_idx:04d}.png")
            plt.savefig(frame_path, dpi=100, bbox_inches="tight", facecolor="white")
            plt.close()

            chart_frames.append(frame_path)

    except Exception as e:
        print(f"Error creating chart frames: {str(e)}")
        # Clean up any created frames.
        for frame_path in chart_frames:
            if os.path.exists(frame_path):
                os.remove(frame_path)
        return []

    return chart_frames

create_sentinel2_index_timelapse(roi, out_gif, start_year, end_year, start_date, end_date, bands, indices, vis_params, dimensions, frames_per_second, crs, mask_cloud, cloud_pct, overlay_data, overlay_color, overlay_width, overlay_opacity, frequency, reducer, date_format, title, title_xy, add_text, text_xy, text_sequence, font_type, font_size, font_color, add_progress_bar, progress_bar_color, progress_bar_height, add_colorbar, colorbar_width, colorbar_height, colorbar_label, colorbar_label_size, colorbar_label_weight, colorbar_tick_size, colorbar_bg_color, colorbar_orientation, colorbar_dpi, colorbar_xy, colorbar_size, loop, fading, **kwargs) ¶

Create a Sentinel-2 timelapse with indices.

Source code in geemap/timelapse.py

def create_sentinel2_index_timelapse(
    roi,
    out_gif,
    start_year,
    end_year,
    start_date,
    end_date,
    bands,
    indices,
    vis_params,
    dimensions,
    frames_per_second,
    crs,
    mask_cloud,
    cloud_pct,
    overlay_data,
    overlay_color,
    overlay_width,
    overlay_opacity,
    frequency,
    reducer,
    date_format,
    title,
    title_xy,
    add_text,
    text_xy,
    text_sequence,
    font_type,
    font_size,
    font_color,
    add_progress_bar,
    progress_bar_color,
    progress_bar_height,
    add_colorbar,
    colorbar_width,
    colorbar_height,
    colorbar_label,
    colorbar_label_size,
    colorbar_label_weight,
    colorbar_tick_size,
    colorbar_bg_color,
    colorbar_orientation,
    colorbar_dpi,
    colorbar_xy,
    colorbar_size,
    loop,
    fading,
    **kwargs,
):
    """Create a Sentinel-2 timelapse with indices."""
    del indices, kwargs  # Unused.

    if end_year is None:
        end_year = datetime.datetime.now().year

    start = f"{start_year}-{start_date}"
    end = f"{end_year}-{end_date}"

    # Create time series with indices.
    base_ts_collection = sentinel2_timeseries(
        roi,
        start_year,
        end_year,
        start_date,
        end_date,
        None,  # Get all bands first.
        mask_cloud,
        cloud_pct,
        frequency,
        reducer,
        True,  # drop_empty
        date_format,
        1,
        1,
    )

    # Add indices to each image.
    ts_collection = base_ts_collection.map(calculate_sentinel2_indices)

    # Use create_timelapse with the index collection.
    return create_timelapse(
        ts_collection,
        start,
        end,
        roi,
        bands,
        frequency,
        reducer,
        date_format,
        out_gif,
        None,
        vis_params,
        dimensions,
        frames_per_second,
        crs,
        overlay_data,
        overlay_color,
        overlay_width,
        overlay_opacity,
        title,
        title_xy,
        add_text,
        text_xy,
        text_sequence,
        font_type,
        font_size,
        font_color,
        add_progress_bar,
        progress_bar_color,
        progress_bar_height,
        add_colorbar,
        colorbar_width,
        colorbar_height,
        colorbar_label,
        colorbar_label_size,
        colorbar_label_weight,
        colorbar_tick_size,
        colorbar_bg_color,
        colorbar_orientation,
        colorbar_dpi,
        colorbar_xy,
        colorbar_size,
        loop,
        False,
        fading,
        1,
        1,
    )

`create_time_series_chart_frames(sample_data, chart_title, chart_ylabel, dimensions, fps, xlabel_format='auto', xlabel_interval='auto')` ¶

Create frames for the time series chart with current time indicator.

Source code in geemap/timelapse.py

def create_time_series_chart_frames(
    sample_data,
    chart_title,
    chart_ylabel,
    dimensions,
    fps,
    xlabel_format="auto",
    xlabel_interval="auto",
):
    """Create frames for the time series chart with current time indicator."""
    del fps  # Unused.

    if not sample_data:
        return []

    # Get all unique dates across all points.
    all_dates = set()
    for point_data in sample_data.values():
        all_dates.update(point_data["dates"])

    if not all_dates:
        return []

    sorted_dates = sorted(list(all_dates))

    # Create chart frames.
    chart_frames = []
    temp_dir = tempfile.mkdtemp()

    # Calculate chart dimensions.
    if isinstance(dimensions, str) and "x" in dimensions:
        width, height = map(int, dimensions.split("x"))
    else:
        width = height = int(dimensions) if isinstance(dimensions, int) else 768

    chart_width = int(width * 0.8)  # 80% of gif width.
    chart_height = height

    try:
        for frame_idx, current_date in enumerate(sorted_dates):
            fig, ax = plt.subplots(
                figsize=(chart_width / 100, chart_height / 100), dpi=100
            )

            # Plot all time series.
            for point_name, point_data in sample_data.items():
                if point_data["dates"] and point_data["values"]:
                    ax.plot(
                        point_data["dates"],
                        point_data["values"],
                        color=point_data["color"],
                        label=point_name,
                        linewidth=2,
                        marker="o",
                        markersize=4,
                    )

            # Add vertical line for current time.
            ax.axvline(
                x=current_date, color="red", linestyle="--", linewidth=2, alpha=0.8
            )

            # Formatting.
            ax.set_xlabel("Date", fontsize=10)
            ax.set_ylabel(chart_ylabel, fontsize=10)
            ax.set_title(chart_title, fontsize=12)
            ax.legend(fontsize=8)
            ax.grid(True, alpha=0.3)

            # Format x-axis based on parameters or auto-detect.
            date_range = (max(sorted_dates) - min(sorted_dates)).days

            if xlabel_format == "auto" or xlabel_interval == "auto":
                # Auto-detect based on data characteristics.
                if date_range <= 30:  # Less than 1 month - likely daily/weekly data.
                    format_str = "%m-%d"
                    if len(sorted_dates) <= 10:
                        # Few points, show all.
                        locator = mdates.DayLocator(interval=max(1, date_range // 10))
                    else:
                        # Many points, show weekly.
                        locator = mdates.WeekdayLocator(interval=1)
                elif date_range <= 90:  # Less than 3 months - likely weekly data.
                    format_str = "%m-%d"
                    if len(sorted_dates) <= 15:
                        # Weekly data with few points.
                        locator = mdates.WeekdayLocator(interval=1)
                    else:
                        # Weekly data with many points.
                        locator = mdates.WeekdayLocator(
                            interval=max(1, len(sorted_dates) // 10)
                        )
                elif date_range <= 365:  # Less than 1 year - likely monthly data.
                    format_str = "%Y-%m"
                    locator = mdates.MonthLocator(
                        interval=max(1, len(sorted_dates) // 8)
                    )
                else:  # More than 1 year - yearly data.
                    format_str = "%Y"
                    locator = mdates.YearLocator()
            else:
                # Use manual settings.
                format_str = xlabel_format if xlabel_format != "auto" else "%Y-%m-%d"

                if xlabel_interval == "day":
                    locator = mdates.DayLocator(
                        interval=max(1, len(sorted_dates) // 15)
                    )
                elif xlabel_interval == "week":
                    locator = mdates.WeekdayLocator(
                        interval=max(1, len(sorted_dates) // 10)
                    )
                elif xlabel_interval == "month":
                    locator = mdates.MonthLocator(
                        interval=max(1, len(sorted_dates) // 8)
                    )
                elif xlabel_interval == "year":
                    locator = mdates.YearLocator()
                else:
                    locator = mdates.WeekdayLocator(
                        interval=max(1, len(sorted_dates) // 10)
                    )

            ax.xaxis.set_major_formatter(mdates.DateFormatter(format_str))
            ax.xaxis.set_major_locator(locator)

            # Add minor ticks for better granularity on weekly data.
            if date_range <= 90:
                ax.xaxis.set_minor_locator(mdates.DayLocator(interval=1))

            plt.setp(ax.xaxis.get_majorticklabels(), rotation=45, fontsize=8)

            # Set consistent y-axis limits.
            all_values = []
            for point_data in sample_data.values():
                all_values.extend([v for v in point_data["values"] if v is not None])

            if all_values:
                y_min, y_max = min(all_values), max(all_values)
                y_range = y_max - y_min
                if y_range > 0:
                    ax.set_ylim(y_min - y_range * 0.1, y_max + y_range * 0.1)
                else:
                    ax.set_ylim(y_min - 1, y_max + 1)

            plt.tight_layout()

            # Save frame.
            frame_path = os.path.join(temp_dir, f"chart_frame_{frame_idx:04d}.png")
            plt.savefig(frame_path, dpi=100, bbox_inches="tight", facecolor="white")
            plt.close()

            chart_frames.append(frame_path)

    except Exception as e:
        print(f"Error creating chart frames: {str(e)}")
        # Clean up any created frames.
        for frame_path in chart_frames:
            if os.path.exists(frame_path):
                os.remove(frame_path)
        return []

    return chart_frames

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.	`None`
`bands`	`list`	A list of band names to use in the timelapse.	`None`
`frequency`	`str`	The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'.	`'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'.	`'median'`
`date_format`	`str \| None`	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 \| None`	The output gif file path.	`None`
`palette`	`list`	A list of colors to render a single-band image in the timelapse.	`None`
`vis_params`	`dict`	A dictionary of visualization parameters to use in the timelapse. 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.	`768`
`frames_per_second`	`int`	Animation speed.	`10`
`crs`	`str`	The coordinate reference system to use.	`'EPSG:3857'`
`overlay_data`	`(int, str, list)`	Administrative boundary to be drawn on the timelapse.	`None`
`overlay_color`	`str`	Color for the overlay data. Can be any color name or hex color code.	`'black'`
`overlay_width`	`int`	Width of the overlay.	`1`
`overlay_opacity`	`float`	Opacity of the overlay.	`1.0`
`title`	`str \| None`	The title of the timelapse.	`None`
`title_xy`	`tuple[str, str]`	Lower left corner of the title. It can be formatted like this: (10, 10) or ('15%', '25%').	`('2%', '90%')`
`add_text`	`bool`	Whether to add animated text to the timelapse.	`True`
`title_xy`	`tuple[str, str]`	Lower left corner of the text sequency. It can be formatted like this: (10, 10) or ('15%', '25%').	`('2%', '90%')`
`text_sequence`	`(int, str, list)`	Text to be drawn. It can be an integer number, a string, or a list of strings.	`None`
`font_type`	`str`	Font type.	`'arial.ttf'`
`font_size`	`int`	Font size.	`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').	`'white'`
`add_progress_bar`	`bool`	Whether to add a progress bar at the bottom of the GIF.	`True`
`progress_bar_color`	`str`	Color for the progress bar.	`'white'`
`progress_bar_height`	`int`	Height of the progress bar.	`5`
`add_colorbar`	`bool`	Whether to add a colorbar to the timelapse.	`False`
`colorbar_width`	`float`	Width of the colorbar.	`6.0`
`colorbar_height`	`float`	Height of the colorbar.	`0.4`
`colorbar_label`	`str \| None`	Label for the colorbar.	`None`
`colorbar_label_size`	`int`	Font size for the colorbar label.	`12`
`colorbar_label_weight`	`str`	Font weight for the colorbar label.	`'normal'`
`colorbar_tick_size`	`int`	Font size for the colorbar ticks.	`10`
`colorbar_bg_color`	`str \| None`	Background color for the colorbar, can be color like "white", "black".	`None`
`colorbar_orientation`	`str`	Orientation of the colorbar.	`'horizontal'`
`colorbar_dpi`	`str`	DPI for the colorbar, can be numbers like 100, 300.	`'figure'`
`colorbar_xy`	`tuple`	Lower left corner of the colorbar. It can be formatted like this: (10, 10) or ('15%', '25%').	`None`
`colorbar_size`	`tuple`	Size of the colorbar. It can be formatted like this: (300, 300).	`(300, 300)`
`loop`	`int`	Controls how many times the animation repeats. 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.	`0`
`mp4`	`bool`	Whether to create an mp4 file.	`False`
`fading`	`bool`	If True, add fading effect to the timelapse. Defaults to 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.	`1`
`step`	`int`	The step size to use when creating the date sequence.	`1`

Returns:

Name	Type	Description
`str`		File path to the timelapse gif.

Source code in geemap/timelapse.py

def create_timelapse(
    collection: str | ee.ImageCollection,
    start_date: str,
    end_date: str,
    region=None,
    bands=None,
    frequency: str = "year",
    reducer: str = "median",
    date_format: str | None = None,
    out_gif: str | None = None,
    palette=None,
    vis_params=None,
    dimensions: int = 768,
    frames_per_second: int = 10,
    crs: str = "EPSG:3857",
    overlay_data=None,
    overlay_color: str = "black",
    overlay_width: int = 1,
    overlay_opacity: float = 1.0,
    title: str | None = None,
    title_xy: tuple[str, str] = ("2%", "90%"),
    add_text: bool = True,
    text_xy: tuple[str, str] = ("2%", "2%"),
    text_sequence=None,
    font_type: str = "arial.ttf",
    font_size: int = 20,
    font_color: str = "white",
    add_progress_bar: bool = True,
    progress_bar_color: str = "white",
    progress_bar_height: int = 5,
    add_colorbar: bool = False,
    colorbar_width: float = 6.0,
    colorbar_height: float = 0.4,
    colorbar_label: str | None = None,
    colorbar_label_size: int = 12,
    colorbar_label_weight: str = "normal",
    colorbar_tick_size: int = 10,
    colorbar_bg_color: str | None = None,
    colorbar_orientation: str = "horizontal",
    colorbar_dpi="figure",
    colorbar_xy=None,
    colorbar_size=(300, 300),
    loop: int = 0,
    mp4: bool = False,
    fading: bool = False,
    parallel_scale: int = 1,
    step: int = 1,
):
    """Create a timelapse from any ee.ImageCollection.

    Args:
        collection: 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: The start date of the timeseries. It must be formatted like this:
            'YYYY-MM-dd'.
        end_date: 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.
        bands (list, optional): A list of band names to use in the timelapse.
        frequency: The frequency of the timeseries. It must be one of the following:
            'year', 'month', 'day', 'hour', 'minute', 'second'.
        reducer: 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'.
        date_format: A pattern, as described at
            http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults
            to 'YYYY-MM-dd'.
        out_gif: The output gif file path.
        palette (list, optional): A list of colors to render a single-band image in the
            timelapse.
        vis_params (dict, optional): A dictionary of visualization parameters to use in
            the timelapse. See more at
            https://developers.google.com/earth-engine/guides/image_visualization.
        dimensions: 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.
        frames_per_second: Animation speed.
        crs: The coordinate reference system to use.
        overlay_data (int, str, list, optional): Administrative boundary to be drawn on
            the timelapse.
        overlay_color: Color for the overlay data. Can be any color name or hex color
            code.
        overlay_width: Width of the overlay.
        overlay_opacity: Opacity of the overlay.
        title: The title of the timelapse.
        title_xy: Lower left corner of the title. It can be formatted like this: (10,
            10) or ('15%', '25%').
        add_text: Whether to add animated text to the timelapse.
        title_xy: Lower left corner of the text sequency. It can be formatted like this:
            (10, 10) or ('15%', '25%').
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer
            number, a string, or a list of strings.
        font_type: Font type.
        font_size: Font size.
        font_color: Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255,
            127, 0)), or hex code (e.g., '#ff00ff').
        add_progress_bar: Whether to add a progress bar at the bottom of the
            GIF.
        progress_bar_color: Color for the progress bar.
        progress_bar_height: Height of the progress bar.
        add_colorbar: Whether to add a colorbar to the timelapse.
        colorbar_width: Width of the colorbar.
        colorbar_height: Height of the colorbar.
        colorbar_label: Label for the colorbar.
        colorbar_label_size: Font size for the colorbar label.
        colorbar_label_weight: Font weight for the colorbar label.
        colorbar_tick_size: Font size for the colorbar ticks.
        colorbar_bg_color: Background color for the colorbar, can be color like "white",
            "black".
        colorbar_orientation: Orientation of the colorbar.
        colorbar_dpi (str, optional): DPI for the colorbar, can be numbers like 100,
            300.
        colorbar_xy (tuple, optional): Lower left corner of the colorbar. It can be
            formatted like this: (10, 10) or ('15%', '25%').
        colorbar_size (tuple, optional): Size of the colorbar. It can be formatted like
            this: (300, 300).
        loop: Controls how many times the animation repeats. 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.
        mp4: Whether to create an mp4 file.
        fading: If True, add fading effect to the timelapse. Defaults to no
            fading. To add fading effect, set it to True (1 second fading duration) or
            to an integer value (fading duration).
        parallel_scale: 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.
        step: The step size to use when creating the date sequence.

    Returns:
        str: File path to the timelapse gif.
    """
    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 = coreutils.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 = colormaps.get_palette(palette, 15)
    elif isinstance(palette, (list, 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"] = colormaps.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"] = colormaps.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 "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.	`None`
`bands`	`list`	The list of bands to use to create the timeseries. It must be a list of strings.	`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'.	`'median'`
`drop_empty`	`bool`	Whether to drop empty images from the timeseries.	`True`
`date_format`	`str \| None`	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.	`1`
`step`	`int`	The step size to use when creating the date sequence.	`1`

Returns:

Type	Description
`ImageCollection`	ee.ImageCollection: The timeseries.

Source code in geemap/timelapse.py

def create_timeseries(
    collection,
    start_date: str,
    end_date: str,
    region=None,
    bands=None,
    frequency: str = "year",
    reducer: str = "median",
    drop_empty: bool = True,
    date_format: str | None = None,
    parallel_scale: int = 1,
    step: int = 1,
) -> ee.ImageCollection:
    """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: The start date of the timeseries. It must be formatted like this:
            'YYYY-MM-dd'.
        end_date: 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.
        bands (list, optional): The list of bands to use to create the timeseries. It
            must be a list of strings.
        frequency: The frequency of the timeseries. It must be one of the following:
            'year', 'month', 'day', 'hour', 'minute', 'second'. Defaults to 'year'.
        reducer: 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'.
        drop_empty: Whether to drop empty images from the timeseries.
        date_format: A pattern, as described at
            http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults
            to 'YYYY-MM-dd'.
        parallel_scale: 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.
        step: The step size to use when creating the date sequence.

    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 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)

    images = ee.ImageCollection(dates.map(create_image))
    if drop_empty:
        return images.filterMetadata("empty", "equals", 0)

    return images

`credentials_in_colab()` ¶

Returns True if Earth Engine credentials exist in Colab, False otherwise.

Source code in geemap/common.py

def credentials_in_colab() -> bool:
    """Returns True if Earth Engine credentials exist in Colab, False otherwise."""
    credentials_path = "/root/.config/earthengine/credentials"
    return os.path.exists(credentials_path)

`credentials_in_drive()` ¶

Returns True if Google Drive is mounted, False otherwise.

Source code in geemap/common.py

def credentials_in_drive() -> bool:
    """Returns True if Google Drive is mounted, False otherwise."""
    credentials_path = "/content/drive/My Drive/.config/earthengine/credentials"
    return os.path.exists(credentials_path)

`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://", "https://")) 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
        # pytype: disable=attribute-error
        # TODO(schwehr): Fix this.
        xfield = fields.index(longitude)
        yfield = fields.index(latitude)
        # pytype: enable=attribute-error

    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
    """
    in_csv = coreutils.github_raw_url(in_csv)

    return pd.read_csv(in_csv, **kwargs)

`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
    )

    return coreutils.geojson_to_ee(geojson, geodesic=geodesic)

`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.
    """
    import geopandas as gpd

    out_dir = os.getcwd()

    out_geojson = os.path.join(out_dir, coreutils.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".
    """
    in_csv = coreutils.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://", "https://")) and in_csv.endswith(".csv"):
        in_csv = coreutils.github_raw_url(in_csv)
        in_csv = coreutils.download_file(in_csv, quiet=True, overwrite=True)

    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)

`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: str, end: str, unit: str, date_format: str = "YYYY-MM-dd", step: int = 1
):
    """Creates a date sequence.

    Args:
        start: The start date, e.g., '2000-01-01'.
        end: The end date, e.g., '2000-12-31'.
        unit: One of 'year', 'quarter', 'month' 'week', 'day', 'hour', 'minute', or
            'second'.
        date_format: A pattern, as described at
            http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html. Defaults
            to 'YYYY-MM-dd'.
        step: The step size. Defaults to 1.

    Returns:
        ee.List: A list of date sequence.
    """

    def get_quarter(d: str) -> str:
        return str((int(d[5:7]) - 1) // 3 * 3 + 1).zfill(2)

    def get_monday(d: str) -> str:
        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_dp_report(name)` ¶

Deletes a datapane report.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the report to delete.	required

Source code in geemap/foliumap.py

def delete_dp_report(name: str) -> None:
    """Deletes a datapane report.

    Args:
        name: Name of the report to delete.
    """
    import datapane as dp

    reports = dp.Report.list()
    items = list(reports)
    names = list(map(lambda item: item["name"], items))
    if name in names:
        report = dp.Report.get(name)
        url = report.blocks[0]["url"]
        dp.Report.delete(dp.Report.by_id(url))

`delete_dp_reports()` ¶

Deletes all datapane reports.

Source code in geemap/foliumap.py

def delete_dp_reports():
    """Deletes all datapane reports."""
    import datapane as dp

    reports = dp.Report.list()
    for item in reports:
        print(item["name"])
        report = dp.Report.get(item["name"])
        url = report.blocks[0]["url"]
        print(f"Deleting {url}...")
        dp.Report.delete(dp.Report.by_id(url))

`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: str, verbose: bool = False) -> None:
    """Deletes a shapefile.

    Args:
        in_shp: The input shapefile to delete.
        verbose: Whether to print out descriptive text. Defaults to False.
    """
    in_shp = os.path.abspath(in_shp)
    in_dir = os.path.dirname(in_shp)
    basename = os.path.basename(in_shp).replace(".shp", "")

    files = pathlib.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.
    """
    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)

    return coreutils.geojson_to_ee(geojson)

`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.

    """
    import geedim as gd

    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.

    """
    start = time.time()

    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 \| None`	The output directory. Defaults to None.	`None`
`prefix`		The prefix for the output file. Defaults to None.	required
`crs`		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.	required
`crs_transform`	`list[float] \| None`	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 \| None`	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`	`str`	Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.	`'near'`
`dtype`	`str \| None`	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 \| None`	Number of tiles to download concurrently. Defaults to a sensible auto value.	`None`
`max_tile_size`	`int \| None`	Maximum tile size (MB). If None, defaults to the Earth Engine download size limit (32 MB).	`None`
`max_tile_dim`	`int \| None`	Maximum tile width/height (pixels). If None, defaults to Earth Engine download limit (10000).	`None`
`shape`	`tuple[int, int] \| None`	(height, width) dimensions to export (pixels).	`None`
`scale_offset`	`bool`	Whether to apply any EE band scales and offsets to the image.	`False`
`unmask_value`	`float \| None`	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 \| None`	The column name in the feature collection to use as the filename. Defaults to None.	`None`
`job_args`	`dict[str, Any]`	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 \| None`	The Earth Engine project ID. Defaults to None.	`None`

Source code in geemap/common.py

def download_ee_image_tiles_parallel(
    image: ee.Image,
    features: ee.FeatureCollection,
    out_dir: str | None = None,
    prefix: str | None = None,
    crs: str | None = None,
    crs_transform: list[float] | None = None,
    scale: float | None = None,
    resampling: str = "near",
    dtype: str | None = None,
    overwrite: bool = True,
    num_threads: int | None = None,
    max_tile_size: int | None = None,
    max_tile_dim: int | None = None,
    shape: tuple[int, int] | None = None,
    scale_offset: bool = False,
    unmask_value: float | None = None,
    column: str | None = None,
    job_args: dict[str, Any] = {"n_jobs": -1},
    ee_init: bool = True,
    project_id: str | None = 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: The image to be downloaded.
        features: The features to loop through to download image.
        out_dir: The output directory. Defaults to None.
        prefix : The prefix for the output file. Defaults to None.
        crs : 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: 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: 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: Resampling method, can be 'near', 'bilinear', 'bicubic', or 'average'. Defaults to None.
        dtype: 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: Overwrite the destination file if it exists. Defaults to True.
        num_threads: Number of tiles to download concurrently. Defaults to a sensible auto value.
        max_tile_size: Maximum tile size (MB). If None, defaults to the Earth Engine download size limit (32 MB).
        max_tile_dim: Maximum tile width/height (pixels). If None, defaults to Earth Engine download limit (10000).
        shape: (height, width) dimensions to export (pixels).
        scale_offset: Whether to apply any EE band scales and offsets to the image.
        unmask_value: 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: The column name in the feature collection to use as the filename. Defaults to None.
        job_args: The arguments to pass to joblib.Parallel. Defaults to {"n_jobs": -1}.
        ee_init: Whether to initialize Earth Engine. Defaults to True.
        project_id: The Earth Engine project ID. Defaults to None.

    """
    import joblib

    start = time.time()

    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: int) -> None:
        if ee_init:
            coreutils.ee_initialize(
                opt_url=ee.data.HIGH_VOLUME_API_BASE_URL,
                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_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

    return gdown.download_folder(
        url, id, output, quiet, proxy, speed, use_cookies, remaining_ok
    )

`download_from_gdrive(gfile_url, file_name, out_dir='.', unzip=True, verbose=True)` ¶

Download a file shared via Google Drive.

For example:

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: str,
    file_name: str,
    out_dir: str = ".",
    unzip: bool = True,
    verbose: bool = True,
) -> None:
    """Download a file shared via Google Drive.

    For example:

        https://drive.google.com/file/d/18SUo_HcDGltuWYZs1s7PpOmOq_FvFn04/view?usp=sharing

    Args:
        gfile_url: The Google Drive shared file URL
        file_name: The output file name to use.
        out_dir: The output directory. Defaults to '.'.
        unzip: Whether to unzip the output file if it is a zip file. Defaults to True.
        verbose: Whether to display or not the output of the function.
    """
    from google_drive_downloader import GoogleDriveDownloader as gdd

    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.coreutils.download_file_from_google_drive(file_id, dest_path, True, unzip)

`download_from_url(url, out_file_name=None, out_dir='.', unzip=True, verbose=True)` ¶

Download a file from a URL.

For example:

1	`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 \| None`	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: str,
    out_file_name: str | None = None,
    out_dir: str = ".",
    unzip: bool = True,
    verbose: bool = True,
) -> None:
    """Download a file from a URL.

    For example:

        https://github.com/giswqs/whitebox/raw/master/examples/testdata.zip

    Args:
        url: The HTTP URL to download.
        out_file_name: The output file name to use. Defaults to None.
        out_dir: The output directory to use. Defaults to '.'.
        unzip: Whether to unzip the downloaded file if it is a zip file. Defaults to
            True.
        verbose: 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 ".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 ".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}")

`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 \| None`	The output file path for the downloaded JavaScript.	`None`

Source code in geemap/conversion.py

def download_gee_app(url: str, out_file: str | None = None) -> None:
    """Downloads JavaScript source code from a GEE App.

    Args:
        url: The URL of the GEE App.
        out_file: The output file path for the downloaded JavaScript.
    """
    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"

    urllib.request.urlretrieve(json_url, json_path)

    with open(out_file_path, "w", encoding="utf-8") as f1:
        with open(json_path, encoding="utf-8") as f2:
            lines = f2.readlines()
            for line in lines:
                items = line.split("\\n")
                for index, item in enumerate(items):
                    if 0 < 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=None, **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 \| None`	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 \| None`	A dictionary of arguments to pass to the download_file function. Defaults to {}.	`None`

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: str | list,
    out_dir: str | None = None,
    return_url: bool = False,
    download_args: dict | None = None,
    **kwargs,
):
    """Download the US National Elevation Datasets (NED) for a region.

    Args:
        region: A filepath to a vector dataset or a list of bounds in the form of [minx, miny, maxx, maxy].
        out_dir: The directory to download the files to. Defaults to None, which uses the current working directory.
        return_url: Whether to return the download URLs of the files. Defaults to False.
        download_args: 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

    download_args = download_args or {}

    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://", "https://")):
            region = coreutils.github_raw_url(region)
            region = coreutils.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 = f"n{str(y).zfill(2)}w{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

    for index, link in enumerate(links):
        print(f"Downloading {index + 1} of {len(links)}: {os.path.basename(link)}")
        coreutils.download_file(link, filepaths[index], **download_args)

`draw_circle_marker(draw, x, y, size, color)` ¶

Draw a circle marker.

Source code in geemap/timelapse.py

def draw_circle_marker(draw, x, y, size, color):
    """Draw a circle marker."""
    half_size = size // 2
    # Outer circle (outline).
    draw.ellipse(
        [x - half_size, y - half_size, x + half_size, y + half_size],
        outline="white",
        width=3,
    )
    # Inner circle (fill).
    draw.ellipse(
        [x - half_size + 2, y - half_size + 2, x + half_size - 2, y + half_size - 2],
        fill=color,
        outline=color,
    )

`draw_cross_marker(draw, x, y, size, color)` ¶

Draw a cross marker.

Source code in geemap/timelapse.py

def draw_cross_marker(draw, x, y, size, color):
    """Draw a cross marker."""
    half_size = size // 2
    # Horizontal line.
    draw.line([x - half_size, y, x + half_size, y], fill=color, width=3)
    # Vertical line.
    draw.line([x, y - half_size, x, y + half_size], fill=color, width=3)
    # Add outline for better visibility.
    draw.line([x - half_size, y, x + half_size, y], fill="white", width=1)
    draw.line([x, y - half_size, x, y + half_size], fill="white", width=1)

`draw_square_marker(draw, x, y, size, color)` ¶

Draw a square marker.

Source code in geemap/timelapse.py

def draw_square_marker(draw, x, y, size, color):
    """Draw a square marker."""
    half_size = size // 2
    # Outer square (outline).
    draw.rectangle(
        [x - half_size, y - half_size, x + half_size, y + half_size],
        outline="white",
        width=3,
    )
    # Inner square (fill).
    draw.rectangle(
        [x - half_size + 2, y - half_size + 2, x + half_size - 2, y + half_size - 2],
        fill=color,
        outline=color,
    )

`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, 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, 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.	`'2016-01-01'`
`end_date`	`str \| Date`	The end date of the query.	`'2021-12-31'`
`cloud_pct`	`int`	The cloud percentage threshold (<=).	`30`
`frequency`	`str`	The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'.	`'year'`
`reducer`	`str`	The reducer to be used.	`'mode'`
`drop_empty`	`bool`	Whether to drop empty images from the timeseries.	`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'.	`'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.	`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.
        end_date (str | ee.Date): The end date of the query.
        cloud_pct (int, optional): The cloud percentage threshold (<=).
        frequency (str, optional): The frequency of the timeseries. It must be one of the following: 'year', 'month', 'day', 'hour', 'minute', 'second'.
        reducer (str, optional): The reducer to be used.
        drop_empty (bool, optional): Whether to drop empty images from the timeseries.
        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'.
        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.

    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, ee.Feature, 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",
        ]

        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: str, title: str = "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: File path to download.
        title: Download description. Defaults to "Click here to download: ".
    """
    # 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.

Fetches from https://developers.google.com/earth-engine/api_docs as a csv file.

Parameters:

Name	Type	Description	Default
`outfile`	`str \| None`	The output file path to a csv file. Defaults to None.	`None`
`timeout`	`int`	Timeout in seconds. Defaults to 300.	`300`
`proxies`	`dict \| None`	Proxy settings. Defaults to None.	`None`

Source code in geemap/common.py

def ee_api_to_csv(
    outfile: str | None = None, timeout: int = 300, proxies: dict | None = None
) -> None:
    """Extracts Earth Engine API documentation.

    Fetches from https://developers.google.com/earth-engine/api_docs as a csv file.

    Args:
        outfile: The output file path to a csv file. Defaults to None.
        timeout: Timeout in seconds. Defaults to 300.
        proxies: Proxy settings. Defaults to None.
    """
    import bs4

    # pytype: disable=attribute-error
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    # pytype: enable=attribute-error
    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

        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 = bs4.BeautifulSoup(r.content, "html.parser")

        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: list[str | bs4.Tag] = []
        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 != "":
                assert isinstance(detail_table, bs4.Tag)  # For pytype.
                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 != "":
                assert isinstance(detail_table, bs4.Tag)  # For pytype.
                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 != "":
                assert isinstance(detail_table, bs4.Tag)  # For pytype.
                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[str, Any]`	A dictionary containing an Earth Engine asset.	required

Returns:

Name	Type	Description
`str`	`str \| None`	A string containing HTML.

Source code in geemap/common.py

def ee_data_html(asset: dict[str, Any]) -> str | None:
    """Generates HTML from an asset to be used in the HTML widget.

    Args:
        asset: 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 = f"ee.Image('{ee_id_snippet}')"
        elif asset_type == "image_collection":
            ee_id_snippet = f"ee.ImageCollection('{ee_id_snippet}')"
        elif asset_type == "table":
            ee_id_snippet = f"ee.FeatureCollection('{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 = (
            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>
                    """
            if asset_url
            else ""
        )
        thumbnail = (
            f"""
                    <h4>Dataset Thumbnail</h4>
                    <img src="{thumbnail_url}">
                    """
            if thumbnail_url
            else ""
        )
        # Only community datasets have a code_url.
        alternative = (
            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>
                    """
            if thumbnail_url
            else ""
        )

        return 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>
        """

    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
`timeout`	`int`	Timeout in seconds. Defaults to 300.	`300`
`proxies`	`dict \| None`	Proxy settings. Defaults to None.	`None`

Returns:

Type	Description
`str`	An http url of the thumbnail.

Source code in geemap/common.py

def ee_data_thumbnail(
    asset_id: str, timeout: int = 300, proxies: dict | None = None
) -> str:
    """Retrieves the thumbnail URL of an Earth Engine asset.

    Args:
        asset_id An Earth Engine asset id.
        timeout: Timeout in seconds. Defaults to 300.
        proxies: Proxy settings. Defaults to None.

    Returns:
        An http url of the thumbnail.
    """
    import bs4

    asset_uid = asset_id.replace("/", "_")
    asset_url = "https://developers.google.com/earth-engine/datasets/catalog/{}".format(
        asset_uid
    )
    # TODO(schwehr): Stop using mw for images.
    thumbnail_url = "https://mw1.google.com/ges/dd/images/{}_sample.png".format(
        asset_uid
    )

    r = requests.get(thumbnail_url, timeout=timeout, proxies=proxies)

    if r.status_code != 200:
        html_page = urllib.request.urlopen(asset_url)
        soup = bs4.BeautifulSoup(html_page, features="html.parser")

        for img in soup.find_all("img"):
            if "sample.png" in img.get("src"):
                return img.get("src")

    return thumbnail_url

`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`	`Any`	ee.FeatureCollection to export.	required
`filename`	`str \| None`	Output file name. Defaults to None.	`None`
`selectors`	`list[str] \| None`	A list of attributes to export. Defaults to None.	`None`
`timeout`	`int`	Timeout in seconds. Defaults to 300 seconds.	`300`
`proxies`	`dict[str, None] \| None`	Proxy settings. Defaults to None.	`None`

Source code in geemap/common.py

def ee_export_geojson(
    ee_object: Any,
    filename: str | None = None,
    selectors: list[str] | None = None,
    timeout: int = 300,
    proxies: dict[str, None] | None = None,
) -> str | None:
    """Exports Earth Engine FeatureCollection to geojson.

    Args:
        ee_object: ee.FeatureCollection to export.
        filename: Output file name. Defaults to None.
        selectors: A list of attributes to export. Defaults to None.
        timeout: Timeout in seconds. Defaults to 300 seconds.
        proxies: 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, coreutils.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 filetype.lower() not 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 attribute not 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`	`Image`	The ee.Image to download.	required
`filename`	`str`	Output filename for the exported image.	required
`scale`	`float \| None`	A default scale to use for any bands that do not specify one; ignored if crs and crs_transform is specified.	`None`
`crs`	`str \| None`	A default CRS string to use for any bands that do not explicitly specify one.	`None`
`crs_transform`	`list[float] \| None`	a default affine transform to use for any bands that do not specify one, of the same format as the crs_transform of bands.	`None`
`region`	`Any \| None`	A polygon specifying a region to download; ignored if crs and crs_transform is specified.	`None`
`dimensions`	`list[int] \| None`	An optional array of two integers defining the width and height to which the band is cropped.	`None`
`file_per_band`	`bool`	Whether to produce a different GeoTIFF per band.	`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 \| None`	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.	`None`
`timeout`	`int`	The timeout in seconds for the request.	`300`
`proxies`	`dict[str, Any] \| None`	A dictionary of proxy servers to use.	`None`
`verbose`	`bool`	Whether to print out descriptive text.	`True`

Source code in geemap/common.py

def ee_export_image(
    ee_object: ee.Image,
    filename: str,
    scale: float | None = None,
    crs: str | None = None,
    crs_transform: list[float] | None = None,
    region: Any | None = None,
    dimensions: list[int] | None = None,
    file_per_band: bool = False,
    format: str = "ZIPPED_GEO_TIFF",  # pylint: disable=redefined-builtin
    unzip: bool = True,
    unmask_value: float | None = None,
    timeout: int = 300,
    proxies: dict[str, Any] | None = None,
    verbose: bool = True,
) -> None:
    """Exports an ee.Image as a GeoTIFF.

    Args:
        ee_object: The ee.Image to download.
        filename: Output filename for the exported image.
        scale: A default scale to use for any bands that do not specify one; ignored if
            crs and crs_transform is specified.
        crs: A default CRS string to use for any bands that do not explicitly specify
            one.
        crs_transform: a default affine transform to use for any bands that do not
            specify one, of the same format as the crs_transform of bands.
        region: A polygon specifying a region to download; ignored if crs and
            crs_transform is specified.
        dimensions: An optional array of two integers defining the width and height to
            which the band is cropped.
        file_per_band: Whether to produce a different GeoTIFF per band.
        format: 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: Whether to unzip the downloaded file. Defaults to True.
        unmask_value: 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.
        timeout: The timeout in seconds for the request.
        proxies: A dictionary of proxy servers to use.
        verbose: Whether to print out descriptive text.
    """
    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

    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.
    r = None
    try:
        r = requests.get(url, stream=True, timeout=timeout, proxies=proxies)

        if r.status_code != 200:
            print("An error occurred while downloading.")
            return
    except Exception as e:
        print("An error occurred while downloading.")
        if r is not None:
            print(r.json()["error"]["message"])
        return

    with open(filename_zip, "wb") as fd:
        for chunk in r.iter_content(chunk_size=1024):
            fd.write(chunk)

    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}")

`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`	`ImageCollection`	The ee.ImageCollection to download.	required
`out_dir`	`str`	The output directory for the exported images.	required
`scale`	`float \| None`	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 \| None`	A default CRS string to use for any bands that do not explicitly specify one.	`None`
`crs_transform`	`list[float] \| None`	a default affine transform to use for any bands that do not specify one, of the same format as the crs_transform of bands.	`None`
`region`	`Any`	A polygon specifying a region to download; ignored if crs and crs_transform is specified.	`None`
`dimensions`	`list[float] \| None`	An optional array of two integers defining the width and height to which the band is cropped.	`None`
`file_per_band`	`bool`	Whether to produce a different GeoTIFF per band.	`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 \| None`	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.	`None`
`filenames`	`list[str] \| int \| None`	A list of filenames to use for the exported images.	`None`
`timeout`	`int`	The timeout in seconds for the request.	`300`
`proxies`	`dict[str, Any] \| None`	A dictionary of proxy servers to use.	`None`
`verbose`	`bool`	Whether to print out descriptive text.	`True`

Source code in geemap/common.py

def ee_export_image_collection(
    ee_object: ee.ImageCollection,
    out_dir: str,
    scale: float | None = None,
    crs: str | None = None,
    crs_transform: list[float] | None = None,
    region: Any = None,
    dimensions: list[float] | None = None,
    file_per_band: bool = False,
    format: str = "ZIPPED_GEO_TIFF",  # pylint: disable=redefined-builtin
    unmask_value: float | None = None,
    filenames: list[str] | int | None = None,
    timeout: int = 300,
    proxies: dict[str, Any] | None = None,
    verbose: bool = True,
):
    """Exports an ImageCollection as GeoTIFFs.

    Args:
        ee_object: The ee.ImageCollection to download.
        out_dir: The output directory for the exported images.
        scale: 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: A default CRS string to use for any bands that do not explicitly specify
            one.
        crs_transform: a default affine transform to use for any bands that do not
            specify one, of the same format as the crs_transform of bands.
        region: A polygon specifying a region to download; ignored if crs and
            crs_transform is specified.
        dimensions: An optional array of two integers defining the width and height to
            which the band is cropped.
        file_per_band: Whether to produce a different GeoTIFF per band.
        format: 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: 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.
        filenames: A list of filenames to use for the exported images.
        timeout: The timeout in seconds for the request.
        proxies: A dictionary of proxy servers to use.
        verbose: Whether to print out descriptive text.
    """
    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 assets.

Parameters:

Name	Type	Description	Default
`ee_object`	`str \| ImageCollection \| ComputedObject`	The image collection to export.	required
`descriptions`	`list[str] \| None`	A list of human-readable names of the tasks.	`None`
`assetIds`	`list[str] \| None`	The destination asset ID.	`None`
`pyramidingPolicy`	`dict[str, str] \| None`	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`	`int \| str \| None`	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`	`float \| None`	The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	`None`
`crs`	`str \| None`	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`	`int \| None`	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: str | ee.ImageCollection | ee.ComputedObject,
    descriptions: list[str] | None = None,
    assetIds: list[str] | None = None,
    pyramidingPolicy: dict[str, str] | None = None,
    dimensions: int | str | None = None,
    region=None,
    scale: float | None = None,
    crs: str | None = None,
    crsTransform=None,
    maxPixels: int | None = None,
    **kwargs,
):
    """Creates a batch task to export an ImageCollection as assets.

    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)

        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 to a Google Cloud bucket.

Parameters:

Name	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 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)

        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 to Google Drive.

Parameters:

Name	Type	Description	Default
`ee_object`	`str \| ImageCollection \| ComputedObject`	The image collection to export.	required
`descriptions`	`list[str] \| None`	A list of human-readable names of the tasks.	`None`
`folder`	`str \| None`	The name of a unique folder in your Drive account to export into. Defaults to the root of the drive.	`None`
`fileNamePrefix`	`str \| None`	The Google Drive filename for the export. Defaults to the name of the task.	`None`
`dimensions`	`int \| str \| None`	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`	`float \| None`	The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	`None`
`crs`	`str \| None`	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`	`int \| None`	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`	`int \| None`	Size in pixels of the tiles in which this image will be computed. Defaults to 256.	`None`
`fileDimensions`	`int \| list[int] \| None`	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`	`bool \| None`	If true, skip writing empty (i.e. fully-masked) image tiles. Defaults to false.	`None`
`fileFormat`	`str \| None`	The string file format to which the image is exported. Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to 'GeoTIFF'.	`None`
`formatOptions`	`dict[str, Any] \| None`	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: str | ee.ImageCollection | ee.ComputedObject,
    descriptions: list[str] | None = None,
    folder: str | None = None,
    fileNamePrefix: str | None = None,
    dimensions: int | str | None = None,
    region=None,
    scale: float | None = None,
    crs: str | None = None,
    crsTransform=None,
    maxPixels: int | None = None,
    shardSize: int | None = None,
    fileDimensions: int | list[int] | None = None,
    skipEmptyTiles: bool | None = None,
    fileFormat: str | None = None,
    formatOptions: dict[str, Any] | None = None,
    **kwargs,
):
    """Creates a batch task to export an ImageCollection 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)

        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,  # pytype: disable=attribute-error
                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`	`Image`	The image to be exported.	required
`description`	`str`	Human-readable name of the task.	`'myExportImageTask'`
`assetId`	`str \| None`	The destination asset ID.	`None`
`pyramidingPolicy`	`dict[str, str] \| None`	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`	`int \| str \| None`	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`	`list[list[float]] \| str \| None`	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`	`float \| None`	The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	`None`
`crs`	`str \| None`	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`	`int \| None`	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: ee.Image,
    description: str = "myExportImageTask",
    assetId: str | None = None,
    pyramidingPolicy: dict[str, str] | None = None,
    dimensions: int | str | None = None,
    region: list[list[float]] | str | None = None,
    scale: float | None = None,
    crs: str | None = None,
    crsTransform=None,
    maxPixels: int | None = 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 not isinstance(image, ee.Image):
        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	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`	`Image`	The image to be exported.	required
`description`	`str`	Human-readable name of the task.	`'myExportImageTask'`
`folder`	`str \| None`	The name of a unique folder in your Drive account to export into. Defaults to the root of the drive.	`None`
`fileNamePrefix`	`str \| None`	The Google Drive filename for the export. Defaults to the name of the task.	`None`
`dimensions`	`int \| str \| None`	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`	`float \| None`	The resolution in meters per pixel. Defaults to the native resolution of the image asset unless a crsTransform is specified.	`None`
`crs`	`str \| None`	The coordinate reference system of the exported image's projection. Defaults to the image's default projection.	`None`
`crsTransform`	`list[float] \| None`	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`	`int \| None`	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`	`int \| None`	Size in pixels of the tiles in which this image will be computed. Defaults to 256.	`None`
`fileDimensions`	`int \| list[int] \| None`	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`	`bool \| None`	If true, skip writing empty (i.e. fully-masked) image tiles. Defaults to false.	`None`
`fileFormat`	`str \| None`	The string file format to which the image is exported. Currently only 'GeoTIFF' and 'TFRecord' are supported, defaults to 'GeoTIFF'.	`None`
`formatOptions`	`dict[str, Any] \| None`	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: ee.Image,
    description: str = "myExportImageTask",
    folder: str | None = None,
    fileNamePrefix: str | None = None,
    dimensions: int | str | None = None,
    region=None,
    scale: float | None = None,
    crs: str | None = None,
    crsTransform: list[float] | None = None,
    maxPixels: int | None = None,
    shardSize: int | None = None,
    fileDimensions: int | list[int] | None = None,
    skipEmptyTiles: bool | None = None,
    fileFormat: str | None = None,
    formatOptions: dict[str, Any] | None = 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	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")

    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.

Includes shp, csv, json, kml, and kmz.

Parameters:

Name	Type	Description	Default
`ee_object`	`Any`	ee.FeatureCollection to export.	required
`filename`	`str`	Output file name.	required
`selectors`	`list[str] \| None`	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 shapefile as a zip file.	`False`
`timeout`	`int`	Timeout in seconds. Defaults to 300 seconds.	`300`
`proxies`	`dict[str, Any] \| None`	A dictionary of proxies to use. Defaults to None.	`None`

Source code in geemap/common.py

def ee_export_vector(
    ee_object: Any,
    filename: str,
    selectors: list[str] | None = None,
    verbose: bool = True,
    keep_zip: bool = False,
    timeout: int = 300,
    proxies: dict[str, Any] | None = None,
):
    """Exports Earth Engine FeatureCollection to other formats.

    Includes shp, csv, json, kml, and kmz.

    Args:
        ee_object: ee.FeatureCollection to export.
        filename: Output file name.
        selectors: A list of attributes to export. Defaults to None.
        verbose: Whether to print out descriptive text.
        keep_zip: Whether to keep the shapefile as a zip file.
        timeout: Timeout in seconds. Defaults to 300 seconds.
        proxies: 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"]
    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 filetype.lower() not 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 attribute not 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`	`FeatureCollection`	The feature collection to be exported.	required
`description`	`str`	Human-readable name of the task.	`'myExportTableTask'`
`assetId`	`str \| None`	The destination asset ID.	`None`
`maxVertices`	`int \| None`	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: ee.FeatureCollection,
    description: str = "myExportTableTask",
    assetId: str | None = None,
    maxVertices: int | None = None,
    **kwargs,
) -> None:
    """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 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='csv', selectors=None, maxVertices=None, **kwargs)` ¶

Creates a task to export a FeatureCollection to Google Cloud Storage.

Parameters:

Name	Type	Description	Default
`collection`	`FeatureCollection`	The feature collection to be exported.	required
`description`	`str`	Human-readable name of the task.	`'myExportTableTask'`
`bucket`	`str \| None`	The name of a Cloud Storage bucket for the export.	`None`
`fileNamePrefix`	`str \| None`	Cloud Storage object name prefix for the export. Defaults to the name of the task.	`None`
`fileFormat`	`str`	The output format: "CSV" (default), "GeoJSON", "KML", "KMZ", "SHP", or "TFRecord".	`'csv'`
`selectors`	`list[str] \| None`	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`	`int \| None`	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: ee.FeatureCollection,
    description: str = "myExportTableTask",
    bucket: str | None = None,
    fileNamePrefix: str | None = None,
    fileFormat: str = "csv",
    selectors: list[str] | None = None,
    maxVertices: int | None = None,
    **kwargs,
) -> None:
    """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 fileFormat.lower() not in allowed_formats:
        raise ValueError(
            "The file type must be one of the following: {}".format(
                ", ".join(allowed_formats)
            )
        )

    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='csv', selectors=None, maxVertices=None, **kwargs)` ¶

Creates a task to export a FeatureCollection to Drive.

Parameters:

Name	Type	Description	Default
`collection`	`FeatureCollection`	The feature collection to be exported.	required
`description`	`str`	Human-readable name of the task.	`'myExportTableTask'`
`folder`	`str \| None`	The name of a unique folder in your Drive account to export into. Defaults to the root of the drive.	`None`
`fileNamePrefix`	`str \| None`	The Google Drive filename for the export. Defaults to the name of the task.	`None`
`fileFormat`	`str`	The output format: "CSV" (default), "GeoJSON", "KML", "KMZ", "SHP", or "TFRecord".	`'csv'`
`selectors`	`list[str] \| None`	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`	`int \| None`	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: ee.FeatureCollection,
    description: str = "myExportTableTask",
    folder: str | None = None,
    fileNamePrefix: str | None = None,
    fileFormat: str = "csv",
    selectors: list[str] | None = None,
    maxVertices: int | None = None,
    **kwargs,
) -> None:
    """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 fileFormat.lower() not in allowed_formats:
        raise ValueError(
            "The file type must be one of the following: {}".format(
                ", ".join(allowed_formats)
            )
        )

    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`	`FeatureCollection`	The feature collection to be exported.	required
`description`	`str`	Human-readable name of the task.	`'myExportTableTask'`
`assetId`	`str \| None`	The destination asset ID.	`None`
`ingestionTimeParameters`	`dict[str, Any] \| None`	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: ee.FeatureCollection,
    description: str = "myExportTableTask",
    assetId: str | None = None,
    ingestionTimeParameters: dict[str, Any] | None = None,
    **kwargs,
) -> None:
    """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.")

    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	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")

    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	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")

    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:

Type	Description
`list[str] \| None`	The list for parent functions.

Source code in geemap/common.py

def ee_function_tree(name: str) -> list[str] | None:
    """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: The name of the Earth Engine function

    Returns:
        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_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.
    """
    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 = coreutils.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"))

    return ee_object.map(lambda f: f.set(table.get(f.get(src_key), ee.Dictionary())))

`ee_num_round(num, decimal=2)` ¶

Rounds a number to a specified number of decimal places.

Parameters:

Name	Type	Description	Default
`num`	`float \| Number \| ComputedObject`	The number to round.	required
`decimal`	`int`	The number of decimal places to round. Defaults to 2.	`2`

Returns:

Type	Description
`Number`	ee.Number: The number with the specified decimal places rounded.

Source code in geemap/common.py

def ee_num_round(
    num: float | ee.Number | ee.ComputedObject, decimal: int = 2
) -> ee.Number:
    """Rounds a number to a specified number of decimal places.

    Args:
        num: 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"%.{decimal}f"
    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:

1	`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: int = 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: 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 = ipywidgets.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 = ipywidgets.Text(placeholder="Filter scripts...", value="Loading...")
    search_box.layout.width = "310px"

    tree_widget = ipywidgets.Output()

    left_widget = ipywidgets.VBox()
    right_widget = ipywidgets.VBox()
    output_widget = ipywidgets.Output()
    output_widget.layout.max_width = "650px"

    search_widget = ipywidgets.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:
                # pytype: disable=attribute-error
                asset_tree, asset_widget, asset_dict = build_asset_tree(
                    limit=asset_limit
                )
                # pytype: enable=attribute-error
                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) -> None:
        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=None, name='Layer untitled', shown=True, opacity=1.0, **kwargs)` ¶

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[str, Any] \| None`	Visualization parameters. Defaults to {}.	`None`
`name`	`str`	The name of the layer.	`'Layer untitled'`
`shown`	`bool`	A flag indicating whether the layer should be on by default.	`True`
`opacity`	`float`	The layer's opacity represented as a number between 0 and 1.	`1.0`

Source code in geemap/foliumap.py

def ee_tile_layer(
    ee_object,
    vis_params: dict[str, Any] | None = None,
    name: str = "Layer untitled",
    shown: bool = True,
    opacity: float = 1.0,
    **kwargs,
):
    """Converts and Earth Engine layer to ipyleaflet TileLayer.

    Args:
        ee_object (Collection|Feature|Image|MapId): The object to add to the map.
        vis_params: Visualization parameters. Defaults to {}.
        name: The name of the layer.
        shown: A flag indicating whether the layer should be on by default.
        opacity: The layer's opacity represented as a number between 0 and 1.
    """
    vis_params = vis_params or {}
    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, ee.Feature, ee.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 = ee_object
    elif isinstance(ee_object, ee.ImageCollection):
        image = ee_object.mosaic()

    if "palette" in vis_params:
        if isinstance(vis_params["palette"], box.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"] = coreutils.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)
    tile_layer = folium.raster_layers.TileLayer(
        tiles=map_id_dict["tile_fetcher"].url_format,
        attr="Google Earth Engine",
        name=name,
        overlay=True,
        control=True,
        opacity=opacity,
        show=shown,
        max_zoom=24,
        **kwargs,
    )
    return tile_layer

`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`	`list[float]`	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) -> list[float]:
    """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, ee.Feature, 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]
    return [xmin, ymin, xmax, ymax]

`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")

    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

`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")

    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

`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 \| None`	The file path to save the geojson. Defaults to None.	`None`
`indent`	`int`	TODO	`2`

Returns:

Name	Type	Description
`object`		GeoJSON object.

Source code in geemap/common.py

def ee_to_geojson(ee_object, filename: str | None = None, indent: int = 2, **kwargs):
    """Converts Earth Engine object to geojson.

    Args:
        ee_object (object): An Earth Engine object.
        filename: The file path to save the geojson. Defaults to None.
        indent: TODO

    Returns:
        object: GeoJSON object.
    """
    if isinstance(ee_object, (ee.Geometry, ee.Feature, 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")

`ee_to_geotiff(ee_object, output, bbox=None, vis_params=None, 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
`# TODO`		What is the proper type for bbox?	required
`bbox`		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[str, Any] \| None`	Visualization parameters. Defaults to {}.	`None`
`zoom`	`int \| None`	The zoom level to download the image at.	`None`
`resolution`	`float \| None`	The resolution in meters to download the image at.	`None`
`crs`	`str`	The CRS of the output image.	`'EPSG:3857'`
`to_cog`	`bool`	Whether to convert the image to Cloud Optimized GeoTIFF.	`False`
`quiet`	`bool`	Whether to hide the download progress bar.	`False`

Source code in geemap/common.py

def ee_to_geotiff(
    ee_object,
    output: str,
    bbox=None,
    vis_params: dict[str, Any] | None = None,
    zoom: int | None = None,
    resolution: float | None = None,
    crs: str = "EPSG:3857",
    to_cog: bool = False,
    quiet: bool = False,
    **kwargs,
):
    """Downloads an Earth Engine object as GeoTIFF.

    Args:
        ee_object (ee.Image | ee.FeatureCollection): The Earth Engine object to download.
        output: The output path for the GeoTIFF.
        # TODO: What is the proper type for bbox?
        bbox: 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: Visualization parameters. Defaults to {}.
        zoom: The zoom level to download the image at.
        resolution: The resolution in meters to download the image at.
        crs: The CRS of the output image.
        to_cog: Whether to convert the image to Cloud Optimized GeoTIFF.
        quiet: Whether to hide the download progress bar.
    """
    vis_params = vis_params or {}

    if not isinstance(
        ee_object,
        (ee.Image, ee.ImageCollection, ee.FeatureCollection, ee.Feature, ee.Geometry),
    ):
        raise AttributeError(
            "The image argument in 'addLayer' function must be an instance of one of "
            "ee.Image, ee.ImageCollection, ee.Geometry, ee.Feature, or "
            "ee.FeatureCollection."
        )

    image = None

    if isinstance(ee_object, (ee.Geometry, ee.Feature, ee.FeatureCollection)):
        features = ee.FeatureCollection(ee_object)

        width = vis_params.get("width", 2)
        color = vis_params.get("color", "000000")

        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 = ee_object
    elif isinstance(ee_object, ee.ImageCollection):
        image = ee_object.mosaic()

    if "palette" in vis_params:
        if isinstance(vis_params["palette"], box.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"] = coreutils.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].
    """
    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

    struct_array = ee.data.computePixels(kwargs)
    return np.dstack([struct_array[band] for band in struct_array.dtype.names])

`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, project=None, opt_url=None, **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 (or reinitialize) Earth Engine. Defaults to True. If True and Earth Engine is already initialized, it will reinitialize with the current project to switch to the specified opt_url (high-volume endpoint by default). If True and Earth Engine is not initialized, a project parameter must be provided. If False, uses the current Earth Engine initialization state.	`True`
`project`	`optional`	The Google Cloud Project ID to use for Earth Engine initialization. Required if ee_initialize is True and Earth Engine is not already initialized. If Earth Engine is already initialized and ee_initialize is True, the current project will be used automatically.	`None`
`opt_url`	`optional`	The Earth Engine API URL to use. Defaults to the high-volume endpoint 'https://earthengine-highvolume.googleapis.com'. Used when ee_initialize is True to initialize or reinitialize Earth Engine.	`None`

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,
    project=None,
    opt_url=None,
    **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 (or reinitialize) Earth Engine.
            Defaults to True. If True and Earth Engine is already initialized, it will
            reinitialize with the current project to switch to the specified opt_url
            (high-volume endpoint by default). If True and Earth Engine is not initialized,
            a project parameter must be provided. If False, uses the current Earth Engine
            initialization state.
        project (optional): The Google Cloud Project ID to use for Earth Engine
            initialization. Required if ee_initialize is True and Earth Engine is
            not already initialized. If Earth Engine is already initialized and
            ee_initialize is True, the current project will be used automatically.
        opt_url (optional): The Earth Engine API URL to use. Defaults to the
            high-volume endpoint 'https://earthengine-highvolume.googleapis.com'.
            Used when ee_initialize is True to initialize or reinitialize Earth Engine.

    Returns:
      An xarray.Dataset that streams in remote data from Earth Engine.
    """
    import xee

    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:
        # Set default opt_url if not provided
        if opt_url is None:
            opt_url = ee.data.HIGH_VOLUME_API_BASE_URL

        if ee.data.is_initialized():
            # If already initialized, get the current project and reinitialize
            # to switch to high-volume endpoint (or custom opt_url)
            try:
                state = ee.data._get_state()
                current_project = getattr(state, "cloud_api_user_project", None)
            except Exception as e:
                raise RuntimeError(
                    f"Failed to access Earth Engine internal state for current project: {e}\n"
                    "Please provide the 'project' parameter explicitly or ensure Earth Engine is properly initialized."
                )

            # Use current_project if available, otherwise use provided project
            if current_project is not None:
                ee.Initialize(project=current_project, opt_url=opt_url)
            elif project is not None:
                ee.Initialize(project=project, opt_url=opt_url)
            else:
                raise ValueError(
                    "Earth Engine is already initialized, but no project could be determined from the current authentication context. "
                    "Please provide a project parameter or reinitialize Earth Engine with a project:\n"
                    "  ee.Initialize(project='YOUR-PROJECT-ID')"
                )
        else:
            # Not initialized - need a project to initialize
            if project is None:
                raise ValueError(
                    "Earth Engine is not initialized and no project was provided. "
                    "Please either:\n"
                    "  1. Initialize Earth Engine before calling this function:\n"
                    "     ee.Initialize(project='YOUR-PROJECT-ID')\n"
                    "  2. Provide a project parameter:\n"
                    "     geemap.ee_to_xarray(..., project='YOUR-PROJECT-ID')\n"
                    "  3. Set ee_initialize=False if already initialized elsewhere"
                )
            ee.Initialize(opt_url=opt_url, project=project)

    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:

Type	Description
`str \| None`	A string containing the user id.

Source code in geemap/common.py

def ee_user_id() -> str | None:
    """Gets Earth Engine account user id.

    Returns:
        A string containing the user id.
    """
    roots = ee.data.getAssetRoots()
    if len(roots) == 0:
        return None

    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

    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: str) -> None:
    """Executes a Jupyter notebook and save output cells.

    Args:
        in_file: Input Jupyter notebook.
    """
    command = f'jupyter nbconvert --to notebook --execute "{in_file}" --inplace'
    print(os.popen(command).read().rstrip())

`execute_notebook_dir(in_dir)` ¶

Executes all notebooks in the given directory recursively and saves 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: str) -> None:
    """Executes all notebooks in the given directory recursively and saves output cells.

    Args:
        in_dir: Input folder containing notebooks.
    """
    print("Executing Earth Engine Jupyter notebooks ...")

    in_dir = os.path.abspath(in_dir)
    files = list(pathlib.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`	`Sequence[Any]`	A list of coordinates.	required

Yields:

Type	Description
`Any`

Source code in geemap/common.py

def explode(coords: Sequence[Any]) -> Iterator[Any]:
    """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: A list of coordinates.

    Yields:
        [type]: [description]
    """
    for e in coords:
        if isinstance(e, (float, int)):
            yield coords
            break
        else:
            yield from explode(e)

`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))

    return dict_values

`extract_timeseries_to_point(lat, lon, image_collection, start_date=None, end_date=None, band_names=None, scale=None, crs=None, crsTransform=None, out_csv=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').	`None`
`end_date`	`str`	End date (e.g., '2020-12-31').	`None`
`band_names`	`list`	List of bands to extract.	`None`
`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_csv`	`str`	File path to save CSV. If None, returns a DataFrame.	`None`

Returns:

Type	Description
`DataFrame \| 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=None,
    end_date=None,
    band_names=None,
    scale=None,
    crs=None,
    crsTransform=None,
    out_csv=None,
) -> pd.DataFrame | 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, optional): Start date (e.g., '2020-01-01').
        end_date (str, optional): End date (e.g., '2020-12-31').
        band_names (list, optional): List of bands to extract.
        scale (float, optional): 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_csv (str, optional): File path to save CSV. If None, returns a DataFrame.

    Returns:
        Time series data if not exporting to CSV.
    """
    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:
        if start_date and end_date:
            image_collection = image_collection.filterDate(start_date, end_date)
        if band_names:
            image_collection = image_collection.select(band_names)
        image_collection = image_collection.filterBounds(point)
    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.datetime.utcfromtimestamp(t / 1000)
        )

        if out_csv:
            result_df.to_csv(out_csv, 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.
    """
    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

`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 \| None`	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 \| None`	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`
`node_icon`	`str`	TODO.	`'file'`

Returns:

Name	Type	Description
`object`		An ipywidget.

Source code in geemap/common.py

def file_browser(
    in_dir: str | None = None,
    show_hidden: bool = False,
    add_root_node: bool = True,
    search_description: str | None = None,
    use_import: bool = False,
    return_sep_widgets: bool = False,
    node_icon: str = "file",
):
    """Creates a simple file browser and text editor.

    Args:
        in_dir: The input directory. Defaults to None, which will use the current
            working directory.
        show_hidden: Whether to show hidden files/folders. Defaults to False.
        add_root_node: Whether to add the input directory as a root node. Defaults to
            True.
        search_description: The description of the search box. Defaults to None.
        use_import: Whether to show the import button. Defaults to False.
        return_sep_widgets: Whether to return the results as separate widgets. Defaults
            to False.
        node_icon: TODO.

    Returns:
        object: An ipywidget.
    """
    from ipytree import Node, Tree

    if in_dir is None:
        in_dir = os.getcwd()

    if not os.path.exists(in_dir):
        print("The provided directory does not exist.")
        return

    if 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 = ipywidgets.HBox()
    left_widget = ipywidgets.VBox()

    right_widget = ipywidgets.VBox()

    import_btn = ipywidgets.Button(
        description="import",
        button_style="primary",
        tooltip="import the content to a new cell",
        disabled=True,
    )
    import_btn.layout.width = "70px"
    path_widget = ipywidgets.Text()
    path_widget.layout.min_width = "400px"
    # path_widget.layout.max_width = '400px'
    save_widget = ipywidgets.Button(
        description="Save",
        button_style="primary",
        tooltip="Save edits to file.",
        disabled=True,
    )
    info_widget = ipywidgets.HBox()
    info_widget.children = [path_widget, save_widget]
    if use_import:
        info_widget.children = [import_btn, path_widget, save_widget]

    text_widget = ipywidgets.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 = ipywidgets.Text(placeholder=search_description)
    search_box.layout.width = "310px"
    tree_widget = ipywidgets.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) -> None:
        if (text_widget.value != "") and (path_widget.value.endswith(".py")):
            coreutils.create_code_cell(text_widget.value)

    import_btn.on_click(import_btn_clicked)

    def search_box_callback(text) -> None:
        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) -> None:
        if event["new"]:
            cur_node = event["owner"]
            for key in tree_dict.keys():
                assert isinstance(key, str)  # For pytype.
                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 = f"Failed to open {cur_node.name}.\n\n{e}"
                        full_widget.children = [left_widget, right_widget]
                        return
                    break

    def handle_folder_click(event) -> None:
        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

    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

    return USGS_HUC08.filterBounds(region)

`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

    return USGS_HUC10.filterBounds(region)

`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`	`Feature`	ee.Feature

Source code in geemap/common.py

def filter_polygons(ftr) -> ee.Feature:
    """Converts GeometryCollection to Polygon/MultiPolygon

    Args:
        ftr (object): ee.Feature

    Returns:
        object: ee.Feature
    """
    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

    return USGS_HUC08.filter(ee.Filter.eq("huc8", HUC08_Id))

`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

    return USGS_HUC10.filter(ee.Filter.eq("huc10", HUC10_Id))

`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)` ¶

Return a list of matching files in a directory.

Parameters:

Name	Type	Description	Default
`input_dir`	`str`	The input directory.	required
`ext`	`str \| None`	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`

Source code in geemap/common.py

def find_files(
    input_dir: str,
    ext: str | None = None,
    fullpath: bool = True,
    recursive: bool = True,
) -> list[str]:
    """Return a list of matching files in a directory.

    Args:
        input_dir: The input directory.
        ext: The file extension to match. Defaults to None.
        fullpath: Whether to return the full path. Defaults to True.
        recursive: Whether to search recursively. Defaults to True.
    """
    if ext is None:
        ext = "*"
    else:
        ext = ext.replace(".", "")

    ext = f"*.{ext}"

    files: list[str]

    path = pathlib.Path(input_dir)
    if recursive:
        if fullpath:
            files = [str(path.joinpath()) for path in path.rglob(ext)]
        else:
            files = [str(path.name) for path in path.rglob(ext)]
    else:
        if fullpath:
            files = [str(path.joinpath()) for path in path.glob(ext)]
        else:
            files = [path.name for path in path.glob(ext)]

    return files

`find_landsat_by_path_row(landsat_col, path_num, row_num)` ¶

Returns an image collection of 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

Source code in geemap/common.py

def find_landsat_by_path_row(
    landsat_col: str, path_num: int, row_num: int
) -> ee.ImageCollection | None:
    """Returns an image collection of Landsat images by WRS path number and row number.

    Args:
        landsat_col: The image collection id of Landsat.
        path_num: The WRS path number.
        row_num: the WRS row number.
    """
    try:
        if isinstance(landsat_col, str):  # TODO: Convert to raise ValueError.
            landsat_col = ee.ImageCollection(landsat_col)
            return landsat_col.filter(ee.Filter.eq("WRS_PATH", path_num)).filter(
                ee.Filter.eq("WRS_ROW", row_num)
            )
    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[str]`	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.	`'{'`

Returns:

Name	Type	Description
`matching_line_index`	`int`	Line index where the matching closing bracket is located.
`matching_char_index`	`int`	Position index of the matching closing bracket.

Source code in geemap/conversion.py

def find_matching_bracket(
    lines: list[str],
    start_line_index: int,
    start_char_index: int,
    matching_char: str = "{",
) -> tuple[int, int]:
    """Finds the position of the matching closing bracket from a list of lines.

    Args:
        lines: The input list of lines.
        start_line_index: The line index where the starting bracket is located.
        start_char_index: The position index of the starting bracket.
        matching_char: The starting bracket to search for.

    Returns:
        matching_line_index: Line index where the matching closing bracket is located.
        matching_char_index: Position index of the matching closing bracket.
    """
    matching_line_index = -1
    matching_char_index = -1

    matching_chars = {"{": "}", "(": ")", "[": "]"}
    if matching_char not in matching_chars:
        characters = ", ".join(matching_chars)
        print(f"The matching character must be one of the following: {characters}")
        return matching_line_index, matching_char_index

    # Create a deque to use it as a stack.
    d = collections.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 \| None`	The number of rows. Defaults to None.	`None`
`cols`	`int \| None`	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 \| None`	The output file path. Defaults to None.	`None`

Returns:

Type	Description
`FeatureCollection \| None`	The fishnet as an ee.FeatureCollection if output is None.

Source code in geemap/common.py

def fishnet(
    data,
    h_interval: float = 1.0,
    v_interval: float = 1.0,
    rows: int | None = None,
    cols: int | None = None,
    delta: float = 1.0,
    intersect: bool = True,
    output: str | None = None,
    **kwargs,
) -> ee.FeatureCollection | None:
    """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: The horizontal interval in degrees. It will be ignored if rows and cols are specified. Defaults to 1.0.
        v_interval: The vertical interval in degrees. It will be ignored if rows and cols are specified. Defaults to 1.0.
        rows: The number of rows. Defaults to None.
        cols: The number of columns. Defaults to None.
        delta: The buffer distance in degrees. Defaults to 1.0.
        intersect: If True, the output will be a feature collection of intersecting polygons. Defaults to True.
        output: The output file path. Defaults to None.

    Returns:
        The fishnet as an ee.FeatureCollection if output is None.
    """
    if isinstance(data, str):
        data = vector_to_ee(data, **kwargs)

    if isinstance(data, (ee.Feature, ee.FeatureCollection)):
        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

    east = east + delta * h_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.	`':'`

Returns:

Type	Description
`str`	A string with keys quoted.

Source code in geemap/conversion.py

def format_params(line: str, sep: str = ":") -> str:
    """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: A string.
        sep: Separator.

    Returns:
        A string with keys quoted.
    """
    new_line = line
    prefix = ""

    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)

    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

    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]

    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
`DataFrame`	A pandas DataFrame containing the GeoDataFrame.

Source code in geemap/common.py

def gdf_to_df(gdf, drop_geom=True) -> pd.DataFrame:
    """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:
        A pandas DataFrame containing the GeoDataFrame.
    """
    if drop_geom:
        return pd.DataFrame(gdf.drop(columns=["geometry"]))

    return pd.DataFrame(gdf)

`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.
    """
    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(), coreutils.random_string(6) + ".geojson")
    gdf = gdf.to_crs(4326)
    gdf.to_file(out_json, driver="GeoJSON")

    fc = coreutils.geojson_to_ee(out_json, geodesic=geodesic)

    if date is not None:
        fc = fc.map(
            lambda x: x.set(
                "system:time_start",
                ee.Date.parse(date_format, x.get(date)).millis(),
            )
        )

    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.
    """
    if epsg is not None:
        gdf = gdf.to_crs(epsg=epsg)
    geojson = gdf.__geo_interface__

    if out_geojson is None:
        return geojson

    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")

`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`

Returns:

Name	Type	Description
`list`		Returns a list of locations.

Source code in geemap/common.py

def geocode(location: str, max_rows: int = 10, reverse: bool = False):
    """Search location by address and lat/lon coordinates.

    Args:
        location: Place name or address.
        max_rows: Maximum number of records to return. Defaults to 10.
        reverse: 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

        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.
    """
    if isinstance(in_geojson, str):
        if in_geojson.startswith(("http://", "https://")):
            in_geojson = coreutils.github_raw_url(in_geojson)
            with urllib.request.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

`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

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: The path to the input GeoTIFF file.
        output: The path to save the output JPEG/PNG file.
    """
    import rasterio
    from PIL import Image

    with rasterio.open(image) as dataset:
        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)

        image = Image.fromarray(data.transpose(1, 2, 0))

        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_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. 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:

Type	Description
`tuple[float, float, float, float]`	A tuple of coordinates representing left, bottom, right, top.

Source code in geemap/common.py

def get_bounds(
    geometry: dict, north_up: bool = True, transform=None
) -> tuple[float, float, float, float]:
    """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. Adapted from:

    https://github.com/mapbox/rasterio/blob/master/rasterio/features.py#L361

    Args:
        geometry: A GeoJSON dict.
        north_up: Defaults to True.
        transform ([type], optional): Defaults to None.

    Returns:
        A tuple 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)

        return min(xmins), max(ymaxs), max(xmaxs), min(ymins)

    if "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)

        return min(xmins), max(ymaxs), max(xmaxs), min(ymins)

    if "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])

        xyz = tuple(zip(*list(explode(geometry["coordinates"]))))
        if north_up:
            return min(xyz[0]), min(xyz[1]), max(xyz[0]), max(xyz[1])

        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.
    """
    # pytype: disable=attribute-error
    pkg_dir = str(importlib.resources.files("geemap").joinpath("geemap.py").parent)
    # pytype: enable=attribute-error

    census_data = os.path.join(pkg_dir, "data/census_data.json")

    if reset:
        from owslib.wms import WebMapService

        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) as f:
            census_dict = json.load(f)

    return census_dict

`get_center(geometry, north_up=True, transform=None)` ¶

Returns the lat, lon of 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`

Source code in geemap/common.py

def get_center(
    geometry: dict, north_up: bool = True, transform=None
) -> tuple[float, float]:
    """Returns the lat, lon of the centroid of a GeoJSON.

    Args:
        geometry: A GeoJSON dict.
        north_up: Defaults to True.
        transform ([type], optional): Defaults to None.
    """
    bounds = get_bounds(geometry, north_up, transform)

    return (bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2  # lat, lon.

`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()` ¶

Returns the current year.

Source code in geemap/common.py

def get_current_year() -> int:
    """Returns the current year."""
    return datetime.date.today().year

`get_default_index_vis_params()` ¶

Get default visualization parameters for different indices.

Source code in geemap/timelapse.py

def get_default_index_vis_params():
    """Get default visualization parameters for different indices."""
    return {
        "NDVI": {
            "min": -0.1,
            "max": 1,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "EVI": {
            "min": -0.2,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "NDWI": {
            "min": -0.3,
            "max": 0.8,
            "palette": ["#8b4513", "#daa520", "#ffffbf", "#87ceeb", "#0000ff"],
        },
        "MNDWI": {
            "min": -0.3,
            "max": 0.8,
            "palette": ["#8b4513", "#daa520", "#ffffbf", "#87ceeb", "#0000ff"],
        },
        "NDBI": {
            "min": -0.5,
            "max": 0.5,
            "palette": ["#0000ff", "#87ceeb", "#ffffbf", "#daa520", "#8b4513"],
        },
        "NBR": {
            "min": -0.5,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "SAVI": {
            "min": -0.2,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "GNDVI": {
            "min": -0.2,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "NDRE": {
            "min": -0.2,
            "max": 0.6,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "CIRE": {
            "min": 0,
            "max": 5,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
    }

`get_default_landsat_band_labels()` ¶

Get default chart labels for Landsat bands.

Source code in geemap/timelapse.py

def get_default_landsat_band_labels() -> dict[str, str]:
    """Get default chart labels for Landsat bands."""
    return {
        "Blue": "Blue",
        "Green": "Green",
        "Red": "Red",
        "NIR": "NIR",
        "SWIR1": "SWIR1",
        "SWIR2": "SWIR2",
    }

`get_default_landsat_index_vis_params()` ¶

Get default visualization parameters for different Landsat indices.

Source code in geemap/timelapse.py

def get_default_landsat_index_vis_params() -> dict[str, dict[str, Any]]:
    """Get default visualization parameters for different Landsat indices."""
    return {
        "NDVI": {
            "min": -0.1,
            "max": 1,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "EVI": {
            "min": -0.2,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "NDWI": {
            "min": -0.3,
            "max": 0.8,
            "palette": ["#8b4513", "#daa520", "#ffffbf", "#87ceeb", "#0000ff"],
        },
        "MNDWI": {
            "min": -0.3,
            "max": 0.8,
            "palette": ["#8b4513", "#daa520", "#ffffbf", "#87ceeb", "#0000ff"],
        },
        "NDBI": {
            "min": -0.5,
            "max": 0.5,
            "palette": ["#0000ff", "#87ceeb", "#ffffbf", "#daa520", "#8b4513"],
        },
        "NBR": {
            "min": -0.5,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "SAVI": {
            "min": -0.2,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "GNDVI": {
            "min": -0.2,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "NDMI": {
            "min": -0.2,
            "max": 0.6,
            "palette": ["#8b4513", "#daa520", "#ffffbf", "#87ceeb", "#0000ff"],
        },
        "MSAVI2": {
            "min": -0.2,
            "max": 0.8,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "VARI": {
            "min": -0.2,
            "max": 0.6,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "MCARI": {
            "min": 0,
            "max": 2,
            "palette": ["#d7191c", "#fdae61", "#ffffbf", "#abd9e9", "#2c7bb6"],
        },
        "TCB": {
            "min": 0,
            "max": 0.4,
            "palette": ["#000000", "#404040", "#808080", "#c0c0c0", "#ffffff"],
        },
        "TCG": {
            "min": -0.1,
            "max": 0.1,
            "palette": ["#8b4513", "#daa520", "#ffffbf", "#90ee90", "#006400"],
        },
        "TCW": {
            "min": -0.2,
            "max": 0.1,
            "palette": ["#8b4513", "#daa520", "#ffffbf", "#87ceeb", "#0000ff"],
        },
    }

`get_direct_url(url)` ¶

Returns the direct URL for a given URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL to get the direct URL for.	required

Source code in geemap/common.py

def get_direct_url(url: str) -> str:
    """Returns the direct URL for a given URL.

    Args:
        url: The URL to get the direct URL for.
    """
    if not isinstance(url, str):
        raise ValueError("url must be a string.")

    if not url.startswith(("http://", "https://")):
        raise ValueError("url must start with http.")

    return requests.head(url, allow_redirects=True).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 not os.path.exists(credential_file_path):
        print("Earth Engine credentials not found. Please run ee.Authenticate()")
        return None

    with open(credential_file_path) as f:
        credentials = json.load(f)
        return credentials

`get_geometry_coords(row, geom, coord_type, shape_type, mercator=False)` ¶

Returns the coordinates ('x' or 'y') of edges of a Polygon exterior.

row (GeoPandas Series): The row of each of the GeoPandas DataFrame. geom: The column name. coord_type: Whether it's 'x' or 'y' coordinate. shape_type: The shape type of the geometry. mercator: Whether to convert to Web Mercator coordinates.

Source code in geemap/common.py

def get_geometry_coords(
    row, geom: str, coord_type: str, shape_type: str, mercator: bool = False
) -> float | list[float] | None:
    """Returns the coordinates ('x' or 'y') of edges of a Polygon exterior.

    row (GeoPandas Series): The row of each of the GeoPandas DataFrame.
    geom: The column name.
    coord_type: Whether it's 'x' or 'y' coordinate.
    shape_type: The shape type of the geometry.
    mercator: Whether to convert to Web Mercator coordinates.
    """
    # 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

        if 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

        if 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

        if 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_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",  # pylint: disable=redefined-builtin
    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",  # pylint: disable=redefined-builtin
    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_index_chart_labels()` ¶

Get chart labels for different indices.

Source code in geemap/timelapse.py

def get_index_chart_labels():
    """Get chart labels for different indices."""
    return {
        "NDVI": "NDVI",
        "EVI": "EVI",
        "NDWI": "NDWI",
        "MNDWI": "MNDWI",
        "NDBI": "NDBI",
        "NBR": "NBR",
        "SAVI": "SAVI",
        "GNDVI": "GNDVI",
        "NDRE": "NDRE",
        "CIRE": "CIre",
    }

`get_js_examples(out_dir=None)` ¶

Gets Earth Engine JavaScript examples from the geemap package.

Parameters:

Name	Type	Description	Default
`out_dir`	`str \| None`	The folder to copy the JavaScript examples to.	`None`

Returns:

Type	Description
`str`	The folder containing the JavaScript examples.

Source code in geemap/conversion.py

def get_js_examples(out_dir: str | None = None) -> str:
    """Gets Earth Engine JavaScript examples from the geemap package.

    Args:
        out_dir: The folder to copy the JavaScript examples to.

    Returns:
        The folder containing the JavaScript examples.
    """
    pkg_dir = pathlib.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:
        assert isinstance(out_dir, pathlib.Path)
        out_dir.mkdir(parent=True, exist_ok=True)

        for file in files:
            out_path = out_dir / file.name
            shutil.copyfile(file, out_path)

    return str(out_dir)

`get_landsat_index_chart_labels()` ¶

Get chart labels for different Landsat indices.

Source code in geemap/timelapse.py

def get_landsat_index_chart_labels() -> dict[str, str]:
    """Get chart labels for different Landsat indices."""
    return {
        "NDVI": "NDVI",
        "EVI": "EVI",
        "NDWI": "NDWI",
        "MNDWI": "MNDWI",
        "NDBI": "NDBI",
        "NBR": "NBR",
        "SAVI": "SAVI",
        "GNDVI": "GNDVI",
        "NDMI": "NDMI",
        "MSAVI2": "MSAVI2",
        "VARI": "VARI",
        "MCARI": "MCARI",
        "TCB": "Tasseled Cap Brightness",
        "TCG": "Tasseled Cap Greenness",
        "TCW": "Tasseled Cap Wetness",
    }

`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
    from localtileserver import (
        get_leaflet_tile_layer,
        get_folium_tile_layer,
        TileClient,
    )

    # 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")

    if isinstance(source, str):
        if not source.startswith(("http://", "https://")):
            if source.startswith("~"):
                source = os.path.expanduser(source)
        else:
            source = coreutils.github_raw_url(source)
    elif isinstance(source, (TileClient, 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://", "https://")):
            layer_name = "RemoteTile_" + coreutils.random_string(3)
        else:
            layer_name = "LocalTile_" + coreutils.random_string(3)

    if isinstance(source, (str, rasterio.io.DatasetReader)):
        tile_client = TileClient(source, port=port, debug=debug)
    else:
        tile_client = source

    if quiet:
        output = ipywidgets.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

    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.	`False`
`out_file`	`Path \| None`	Set the output file path of the notebook template.	`None`

Returns:

Type	Description
`Path`	File path of the template.

Source code in geemap/conversion.py

def get_nb_template(
    download_latest: bool = False, out_file: pathlib.Path | None = None
) -> pathlib.Path:
    """Get the Earth Engine Jupyter notebook template.

    Args:
        download_latest: If True, downloads the latest notebook template from GitHub.
        out_file: Set the output file path of the notebook template.

    Returns:
        File path of the template.
    """
    pkg_dir = pathlib.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")
    out_file.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.
    """
    import 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)` ¶

Returns a list of hex colors in 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 \| None`	The name of the matplotlib colormap. Defaults to None.	`None`
`n_class`	`int \| None`	The number of colors. Defaults to None.	`None`
`hashtag`	`bool`	Whether to return a list of hex colors. Defaults to False.	`False`

Source code in geemap/common.py

def get_palette_colors(
    cmap_name: str | None = None, n_class: int | None = None, hashtag: bool = False
) -> list[str]:
    """Returns a list of hex colors in a palette from a matplotlib colormap.

    See the list of colormaps at https://matplotlib.org/stable/tutorials/colors/colormaps.html.

    Args:
        cmap_name: The name of the matplotlib colormap. Defaults to None.
        n_class: The number of colors. Defaults to None.
        hashtag: Whether to return a list of hex colors. Defaults to False.
    """
    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_pixel_coordinates_from_geo(lon, lat, roi_bounds, gif_width, gif_height)` ¶

Convert geographic coordinates to pixel coordinates.

Parameters:

Name	Type	Description	Default
`lon`	`float`	Longitude	required
`lat`	`float`	Latitude	required
`roi_bounds`	`list`	[min_lon, min_lat, max_lon, max_lat]	required
`gif_width`	`int`	Width of GIF in pixels	required
`gif_height`	`int`	Height of GIF in pixels	required

Returns:

Name	Type	Description
`tuple`		(pixel_x, pixel_y)

Source code in geemap/timelapse.py

def get_pixel_coordinates_from_geo(lon, lat, roi_bounds, gif_width, gif_height):
    """Convert geographic coordinates to pixel coordinates.

    Args:
        lon (float): Longitude
        lat (float): Latitude
        roi_bounds (list): [min_lon, min_lat, max_lon, max_lat]
        gif_width (int): Width of GIF in pixels
        gif_height (int): Height of GIF in pixels

    Returns:
        tuple: (pixel_x, pixel_y)
    """
    min_lon, min_lat, max_lon, max_lat = roi_bounds

    # Linear transformation from geographic to pixel coordinates.
    pixel_x = int(((lon - min_lon) / (max_lon - min_lon)) * gif_width)
    pixel_y = int(((max_lat - lat) / (max_lat - min_lat)) * gif_height)  # Flip Y axis.

    # Ensure coordinates are within bounds.
    pixel_x = max(0, min(gif_width - 1, pixel_x))
    pixel_y = max(0, min(gif_height - 1, pixel_y))

    return pixel_x, pixel_y

`get_temp_dir()` ¶

Returns the temporary directory.

Source code in geemap/common.py

def get_temp_dir() -> str:
    """Returns the temporary directory."""
    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`

Source code in geemap/common.py

def get_wms_layers(url: str, return_titles: bool = False):
    """Returns a list of WMS layers from a WMS service.

    Args:
        url: The URL of the WMS service.
        return_titles: If True, the titles of the layers will be returned. Defaults to
            False.
    """
    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]

    return layers

`gif_fading(in_gif, out_gif, duration=1.0, 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.	`1.0`
`verbose`	`bool`	Whether to print the progress.	`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: str, out_gif: str, duration: float = 1.0, verbose: bool = True
) -> None:
    """Fade in/out the gif.

    Args:
        in_gif: The input gif file. Can be a directory path or http URL, e.g.,
            "https://i.imgur.com/ZWSZC5z.gif"
        out_gif: The output gif file.
        duration: The duration of the fading.
        verbose: Whether to print the progress.

    Raises:
        FileNotFoundError: Raise exception when the input gif does not exist.
        Exception: Raise exception when ffmpeg is not installed.
    """
    current_dir = os.getcwd()

    if isinstance(in_gif, str) and in_gif.startswith(("http://", "https://")):
        ext = os.path.splitext(in_gif)[1]
        file_path = coreutils.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}"

    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: str, out_mp4: str) -> None:
    """Converts a gif to mp4.

    Args:
        in_gif: The input gif file.
        out_mp4: The output mp4 file.
    """
    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} "
            f"-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 \| None`	The output directory.	`None`
`prefix`	`str`	The prefix of the output png files.	`''`
`verbose`	`bool`	Whether to print the progress.	`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: str, out_dir: str | None = None, prefix: str = "", verbose: bool = True
) -> None:
    """Converts a gif to png.

    Args:
        in_gif: The input gif file.
        out_dir: The output directory.
        prefix: The prefix of the output png files.
        verbose: Whether to print the progress.

    Raises:
        FileNotFoundError: Raise exception when the input gif does not exist.
        Exception: Raise exception when ffmpeg is not installed.
    """
    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}")

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.	`'2020-09-05T15:00'`
`end_date`	`str`	The end date of the time series.	`'2020-09-06T02:00'`
`data`	`str`	The GOES satellite data to use.	`'GOES-17'`
`scan`	`str`	The GOES scan to use.	`'full_disk'`
`region`	`Geometry`	The region of interest.	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.	`768`
`frames_per_second`	`int`	Animation speed.	required
`date_format`	`str`	The date format to use.	`'YYYY-MM-dd HH:mm'`
`xy`	`tuple`	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%').	`('3%', '3%')`
`text_sequence`	`(int, str, list)`	Text to be drawn. It can be an integer number, a string, or a list of strings.	`None`
`font_type`	`str`	Font type.	`'arial.ttf'`
`font_size`	`int`	Font size.	`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').	`'#ffffff'`
`add_progress_bar`	`bool`	Whether to add a progress bar at the bottom of the GIF.	`True`
`progress_bar_color`	`str`	Color for the progress bar.	`'white'`
`progress_bar_height`	`int`	Height of the progress bar.	`5`
`loop`	`int`	controls how many times the animation repeats. 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.	`0`
`crs`	`str`	The coordinate reference system to use, e.g., "EPSG:3857".	`None`
`overlay_data`	`(int, str, list)`	Administrative boundary to be drawn on the timelapse.	`None`
`overlay_color`	`str`	Color for the overlay data. Can be any color name or hex color code.	`'#000000'`
`overlay_width`	`int`	Width of the overlay.	`1`
`overlay_opacity`	`float`	Opacity of the overlay.	`1.0`
`mp4`	`bool`	Whether to convert the GIF to MP4.	`False`
`fading`	`int \| bool`	If True, add fading effect to the timelapse. Defaults to 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.
        end_date (str, optional): The end date of the time series.
        data (str, optional): The GOES satellite data to use.
        scan (str, optional): The GOES scan to use.
        region (ee.Geometry, optional): The region of interest.
        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.
        frames_per_second (int, optional): Animation speed.
        date_format (str, optional): The date format to use.
        xy (tuple, optional): Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%').
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer number, a string, or a list of strings.
        font_type (str, optional): Font type.
        font_size (int, optional): Font size.
        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').
        add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF.
        progress_bar_color (str, optional): Color for the progress bar.
        progress_bar_height (int, optional): Height of the progress bar.
        loop (int, optional): controls how many times the animation repeats. 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.
        crs (str, optional): The coordinate reference system to use, e.g., "EPSG:3857".
        overlay_data (int, str, list, optional): Administrative boundary to be drawn on the timelapse.
        overlay_color (str, optional): Color for the overlay data. Can be any color name or hex color code.
        overlay_width (int, optional): Width of the overlay.
        overlay_opacity (float, optional): Opacity of the overlay.
        mp4 (bool, optional): Whether to convert the GIF to MP4.
        fading (int | bool, optional): If True, add fading effect to the timelapse. Defaults to 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.
    """
    if "region" in kwargs:
        roi = kwargs["region"]

    if out_gif is None:
        out_gif = os.path.abspath(f"goes_fire_{coreutils.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, roi
        )

    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

`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.
https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

Parameters:

Name	Type	Description	Default
`start_date`	`str`	The start date of the time series.	`'2020-09-05T15:00'`
`end_date`	`str`	The end date of the time series.	`'2020-09-06T02:00'`
`data`	`str`	The GOES satellite data to use.	`'GOES-17'`
`scan`	`str`	The GOES scan to use.	`'full_disk'`
`region`	`Geometry`	The region of interest.	`None`
`merge`	`bool`	Whether to merge the fire timeseries with GOES CMI timeseries.	`True`

Raises:

Type	Description
`ValueError`	The data must be either GOES-16 or GOES-20.
`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: str = "2020-09-05T15:00",
    end_date: str = "2020-09-06T02:00",
    data: str = "GOES-17",
    scan: str = "full_disk",
    region=None,
    merge: bool = True,
):
    """Create a time series of GOES Fire data.

    The code is adapted from Justin Braaten's code:

    * https://code.earthengine.google.com/8a083a7fb13b95ad4ba148ed9b65475e.
    * https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

    Args:
        start_date: The start date of the time series.
        end_date: The end date of the time series.
        data: The GOES satellite data to use.
        scan: The GOES scan to use.
        region (ee.Geometry, optional): The region of interest.
        merge: Whether to merge the fire timeseries with GOES CMI timeseries.

    Raises:
        ValueError: The data must be either GOES-16 or GOES-20.
        ValueError: The scan must be either full_disk or conus.

    Returns:
        ee.ImageCollection: GOES fire timeseries.
    """

    if data not in _GOES_SATELLITES:
        raise ValueError(
            f"data must be one of {', '.join(_GOES_SATELLITES[:-1])}, or {_GOES_SATELLITES[-1]}"
        )

    scan_types = {
        "full_disk": "FDCF",
        "conus": "FDCC",
    }

    if scan.lower() not in scan_types:
        raise ValueError("The scan must be either full_disk or conus.")

    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=None, 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.
https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

Parameters:

Name	Type	Description	Default
`roi`	`Geometry`	The region of interest.	`None`
`out_gif`	`str \| None`	The file path to save the gif.	`None`
`start_date`	`str`	Start date of the time series.	`'2021-10-24T14:00:00'`
`end_date`	`str`	End date of the time series.	`'2021-10-25T01:00:00'`
`data`	`str`	The GOES satellite data to use.	`'GOES-17'`
`scan`	`str`	The GOES scan to use.	`'full_disk'`
`bands`	`list[str] \| None`	The bands to visualize. Defaults to ["CMI_C02", "CMI_GREEN", "CMI_C01"].	`None`
`dimensions`		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.	`768`
`framesPerSecond`	`int`	Animation speed.	`10`
`date_format`	`str`	The date format to use.	`'YYYY-MM-dd HH:mm'`
`xy`	`tuple`	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%').	`('3%', '3%')`
`text_sequence`	`(int, str, list)`	Text to be drawn. It can be an integer number, a string, or a list of strings.	`None`
`font_type`	`str`	Font type.	`'arial.ttf'`
`font_size`	`int`	Font size.	`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').	`'#ffffff'`
`add_progress_bar`	`bool`	Whether to add a progress bar at the bottom of the GIF.	`True`
`progress_bar_color`	`str`	Color for the progress bar.	`'white'`
`progress_bar_height`	`int`	Height of the progress bar.	`5`
`loop`	`int`	controls how many times the animation repeats. 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.	`0`
`crs`	`str \| None`	Coordinate reference system to use, e.g., "EPSG:3857".	`None`
`overlay_data`	`(int, str, list)`	Administrative boundary to be drawn on the timelapse.	`None`
`overlay_color`	`str`	Color for the overlay data. Can be any color name or hex color code.	`'black'`
`overlay_width`	`int`	Line width of the overlay.	`1`
`overlay_opacity`	`float`	Opacity of the overlay.	`1.0`
`mp4`	`bool`	Whether to save the animation as an mp4 file.	`False`
`fading`	`bool \| int`	If True, add fading effect to the timelapse. Defaults to 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_timelapse(
    roi=None,
    out_gif: str | None = None,
    start_date: str = "2021-10-24T14:00:00",
    end_date: str = "2021-10-25T01:00:00",
    data: str = "GOES-17",
    scan: str = "full_disk",
    bands: list[str] | None = None,
    dimensions=768,
    framesPerSecond: int = 10,
    date_format: str = "YYYY-MM-dd HH:mm",
    xy=("3%", "3%"),
    text_sequence=None,
    font_type: str = "arial.ttf",
    font_size: int = 20,
    font_color: str = "#ffffff",
    add_progress_bar: bool = True,
    progress_bar_color: str = "white",
    progress_bar_height: int = 5,
    loop: int = 0,
    crs: str | None = None,
    overlay_data=None,
    overlay_color: str = "black",
    overlay_width: int = 1,
    overlay_opacity: float = 1.0,
    mp4: bool = False,
    fading: bool | int = False,
    **kwargs,
):
    """Create a timelapse of GOES data.

    The code is adapted from Justin Braaten's code:

    * https://code.earthengine.google.com/57245f2d3d04233765c42fb5ef19c1f4.
    * https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

    Args:
        roi (ee.Geometry, optional): The region of interest.
        out_gif: The file path to save the gif.
        start_date: Start date of the time series.
        end_date: End date of the time series.
        data: The GOES satellite data to use.
        scan: The GOES scan to use.
        bands: The bands to visualize. Defaults to ["CMI_C02", "CMI_GREEN", "CMI_C01"].
        dimensions: 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.
        framesPerSecond: Animation speed.
        date_format: The date format to use.
        xy (tuple, optional): Top left corner of the text. It can be formatted like
            this: (10, 10) or ('15%', '25%').
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer
            number, a string, or a list of strings.
        font_type: Font type.
        font_size: Font size.
        font_color: Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255,
            127, 0)), or hex code (e.g., '#ff00ff').
        add_progress_bar: Whether to add a progress bar at the bottom of the GIF.
        progress_bar_color: Color for the progress bar.
        progress_bar_height: Height of the progress bar.
        loop: controls how many times the animation repeats. 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.
        crs: Coordinate reference system to use, e.g., "EPSG:3857".
        overlay_data (int, str, list, optional): Administrative boundary to be drawn on
            the timelapse.
        overlay_color: Color for the overlay data. Can be any color name or hex color
            code.
        overlay_width: Line width of the overlay.
        overlay_opacity: Opacity of the overlay.
        mp4: Whether to save the animation as an mp4 file.
        fading: If True, add fading effect to the timelapse. Defaults to 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.
    """
    bands = bands or ["CMI_C02", "CMI_GREEN", "CMI_C01"]

    if "region" in kwargs:
        roi = kwargs["region"]

    if out_gif is None:
        out_gif = os.path.abspath(f"goes_{coreutils.random_string(3)}.gif")

    visParams = {
        "bands": bands,
        "min": 0,
        "max": 0.8,
    }
    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,
        )

    print("Generating GOES timelapse...")
    col = goes_timeseries(start_date, end_date, data, scan, roi)
    print(f"Number of images in the collection: {col.size().getInfo()}")
    col = col.select(bands).map(
        lambda img: img.visualize(**visParams)
        .setDefaultProjection(img.projection())
        .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, roi
        )

    if crs is None:
        if overlay_data is not None:
            # Use EPSG:3857 when overlay_data is provided because the native.
            # GEOS projection doesn't work well with overlay during video rendering.
            crs = "EPSG:3857"
        else:
            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,
        )

        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

`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'])` ¶

Creates a time series of GOES data.

The code is adapted from Justin Braaten's code:

https://code.earthengine.google.com/57245f2d3d04233765c42fb5ef19c1f4
https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

Parameters:

Name	Type	Description	Default
`start_date`	`str`	The start date of the time series.	`'2021-10-24T14:00:00'`
`end_date`	`str`	The end date of the time series.	`'2021-10-25T01:00:00'`
`data`	`str`	The GOES satellite data to use.	`'GOES-17'`
`scan`	`str`	The GOES scan to use.	`'full_disk'`
`region`	`Geometry`	The region of interest.	`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']`

Raises:

Type	Description
`ValueError`	The data must be either GOES-16 ... GOES-20.
`ValueError`	The scan must be either full_disk, conus, or mesoscale.

Returns:

Type	Description
	ee.ImageCollection: GOES timeseries.

Source code in geemap/timelapse.py

def goes_timeseries(
    start_date: str = "2021-10-24T14:00:00",
    end_date: str = "2021-10-25T01:00:00",
    data: str = "GOES-17",
    scan: str = "full_disk",
    region=None,
    show_night=[False, "a_mode"],
):
    """Creates a time series of GOES data.

    The code is adapted from Justin Braaten's code:

    * https://code.earthengine.google.com/57245f2d3d04233765c42fb5ef19c1f4
    * https://jstnbraaten.medium.com/goes-in-earth-engine-53fbc8783c16

    Args:
        start_date: The start date of the time series.
        end_date: The end date of the time series.
        data: The GOES satellite data to use.
        scan: The GOES scan to use.
        region (ee.Geometry, optional): The region of interest.
        show_night (list): 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 ... GOES-20.
        ValueError: The scan must be either full_disk, conus, or mesoscale.

    Returns:
        ee.ImageCollection: GOES timeseries.
    """
    if data not in _GOES_SATELLITES:
        raise ValueError(
            f"data must be one of {', '.join(_GOES_SATELLITES[:-1])}, or {_GOES_SATELLITES[-1]}"
        )

    scan_types = {
        "full_disk": "MCMIPF",
        "conus": "MCMIPC",
        "mesoscale": "MCMIPM",
    }

    if scan.lower() not in scan_types:
        raise ValueError("The scan must be either full_disk, conus, or mesoscale.")

    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`		A PIL Image object.	required

Returns:

Type	Description
`bool`	True if it has transparency, False otherwise.

Source code in geemap/common.py

def has_transparency(img) -> bool:
    """Checks whether an image has transparency.

    Args:
        img: A PIL Image object.

    Returns:
        True if it has transparency, False otherwise.
    """
    if img.mode == "P":
        transparent = img.info.get("transparency", -1)
        for _, index in img.getcolors():
            if index == transparent:
                return True
    elif img.mode == "RGBA":
        extrema = img.getextrema()
        if extrema[3][0] < 255:
            return True

    return False

`hex_to_rgba(hex_color, opacity)` ¶

Converts a hex color code to an RGBA color string.

Parameters:

Name	Type	Description	Default
`hex_color`	`str`	The hex color code to convert. It can be in the format '#RRGGBB' or 'RRGGBB'. Does not support alpha or 'RGB'.	required
`opacity`	`float`	The opacity value for the RGBA color. It should be a float between 0.0 (completely transparent) and 1.0 (completely opaque).	required

Returns:

Type	Description
`str`	The RGBA color string in the format 'rgba(R, G, B, A)'.

Source code in geemap/common.py

def hex_to_rgba(hex_color: str, opacity: float) -> str:
    """Converts a hex color code to an RGBA color string.

    Args:
        hex_color: The hex color code to convert. It can be in the format
            '#RRGGBB' or 'RRGGBB'. Does not support alpha or 'RGB'.
        opacity: The opacity value for the RGBA color. It should be a
            float between 0.0 (completely transparent) and 1.0 (completely opaque).

    Returns:
        The RGBA color string in the format 'rgba(R, G, B, A)'.
    """
    hex_color = hex_color.lstrip("#")
    h_len = len(hex_color)
    r, g, b = (
        int(hex_color[i : i + h_len // 3], 16) for i in range(0, h_len, h_len // 3)
    )
    return f"rgba({r},{g},{b},{opacity})"

`histogram(data=None, x=None, y=None, color=None, descending=None, max_rows=None, x_label=None, y_label=None, title=None, width=None, height=500, layout_args=None, **kwargs)` ¶

Create a line 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 \| None`	Whether to sort the data in descending order.	`None`
`max_rows`	`int \| None`	Maximum number of rows to display.	`None`
`x_label`	`str \| None`	Label for the x axis.	`None`
`y_label`	`str \| None`	Label for the y axis.	`None`
`title`	`str \| None`	Title for the plot.	`None`
`width`	`int \| None`	Width of the plot in pixels.	`None`
`height`	`int`	Height of the plot in pixels.	`500`
`layout_args`	`dict \| None`	Layout arguments for the plot to be passed to fig.update_layout(), such as {'title':'Plot Title', 'title_x':0.5}.	`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:

Type	Description
	plotly.graph_objs._figure.Figure: A plotly figure object.

Source code in geemap/plot.py

def histogram(
    data=None,
    x=None,
    y=None,
    color=None,
    descending: bool | None = None,
    max_rows: int | None = None,
    x_label: str | None = None,
    y_label: str | None = None,
    title: str | None = None,
    width: int | None = None,
    height: int = 500,
    layout_args: dict | None = None,
    **kwargs,
):
    """Create a line 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: Whether to sort the data in descending order.
        max_rows: Maximum number of rows to display.
        x_label: Label for the x axis.
        y_label: Label for the y axis.
        title: Title for the plot.
        width: Width of the plot in pixels.
        height: Height of the plot in pixels.
        layout_args: Layout arguments for the plot to be passed to fig.update_layout(),
            such as {'title':'Plot Title', 'title_x':0.5}.
        **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://", "https://")):
            data = coreutils.github_raw_url(data)
            data = common.get_direct_url(data)
        data = pd.read_csv(data)

    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:
        data.sort_values([y, x], ascending=not (descending), inplace=True)

    if isinstance(max_rows, int):
        data = data.head(max_rows)

    labels = kwargs.pop("labels", {})

    if x_label is not None:
        labels[x] = x_label
    if y_label is not None:
        labels[y] = y_label

    fig = px.histogram(
        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

`html_to_gradio(html, 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
`html`	`str \| list[str]`	The HTML string or list of strings to convert.	required
`width`	`str`	The width of the map. Defaults to '100%'.	`'100%'`
`height`	`str`	The height of the map. Defaults to '500px'.	`'500px'`

Returns:

Type	Description
`str`	The HTML string to use in Gradio.

Source code in geemap/common.py

def html_to_gradio(
    html: str | list[str], width: str = "100%", height: str = "500px", **kwargs
) -> str:
    """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:
        html: The HTML string or list of strings to convert.
        width: The width of the map. Defaults to '100%'.
        height: The height of the map. Defaults to '500px'.

    Returns:
        The HTML string to use in Gradio.
    """
    del kwargs  # Unused.

    if isinstance(width, int):
        width = f"{width}px"

    if isinstance(height, int):
        height = f"{height}px"

    if isinstance(html, str):
        with open(html) as f:
            lines = f.readlines()
    elif isinstance(html, list):
        lines = html
    else:
        raise TypeError("html must be a file path or a list of strings")

    output = []
    skipped_lines = []
    for index, line in enumerate(lines):
        if index in skipped_lines:
            continue
        if line.lstrip().startswith('{"attribution":'):
            continue
        elif "on(L.Draw.Event.CREATED, function(e)" in line:
            for i in range(14):
                skipped_lines.append(index + i)
        elif "L.Control.geocoder" in line:
            for i in range(5):
                skipped_lines.append(index + i)
        elif "function(e)" in line:
            print(
                f"Warning: The folium plotting backend does not support functions in code blocks. Please delete line {index + 1}."
            )
        else:
            output.append(line + "\n")

    return f"""<iframe style="width: {width}; height: {height}" name="result" allow="midi; geolocation; microphone; camera;
    display-capture; encrypted-media;" sandbox="allow-modals allow-forms
    allow-scripts allow-same-origin allow-popups
    allow-top-navigation-by-user-activation allow-downloads" allowfullscreen=""
    allowpaymentrequest="" frameborder="0" srcdoc='{"".join(output)}'></iframe>"""

`html_to_streamlit(filename, width=None, height=None, scrolling=False, replace_dict=None)` ¶

Renders an HTML file as a Streamlit component. Args: filename: The filename of the HTML file. width: Width of the map. Defaults to None. height: Height of the map. Defaults to 600. scrolling: Whether to allow the map to scroll. Defaults to False. replace_dict: A dictionary of strings to replace in the HTML file. Defaults to {}.

Raises:

Type	Description
`ValueError`	If the filename does not exist.

Returns:

Type	Description
	streamlit.components: components.html object.

Source code in geemap/common.py

def html_to_streamlit(
    filename: str,
    width: int | None = None,
    height: int | None = None,
    scrolling: bool = False,
    replace_dict: dict | None = None,
):
    """Renders an HTML file as a Streamlit component.
    Args:
        filename: The filename of the HTML file.
        width: Width of the map. Defaults to None.
        height: Height of the map. Defaults to 600.
        scrolling: Whether to allow the map to scroll. Defaults to False.
        replace_dict: A dictionary of strings to replace in the HTML file. Defaults to {}.

    Raises:
        ValueError: If the filename does not exist.

    Returns:
        streamlit.components: components.html object.
    """
    import streamlit.components.v1 as components

    replace_dict = replace_dict or {}

    if not os.path.exists(filename):
        raise ValueError("filename must exist.")

    f = open(filename)

    html = f.read()

    for key, value in replace_dict.items():
        html = html.replace(key, value)

    f.close()
    return components.html(html, width=width, height=height, scrolling=scrolling)

`image_area(img, region=None, scale=None, denominator=1.0)` ¶

Calculates the area of an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	ee.Image	required
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`
`denominator`	`float`	The denominator to use for converting size from square meters to other units. Defaults to 1.0.	`1.0`

Returns:

Name	Type	Description
`object`		ee.Dictionary

Source code in geemap/common.py

def image_area(img, region=None, scale=None, denominator=1.0):
    """Calculates the area of an image.

    Args:
        img (object): ee.Image
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.
        denominator (float, optional): The denominator to use for converting size from square meters to other units. Defaults to 1.0.

    Returns:
        object: ee.Dictionary
    """
    if region is None:
        region = img.geometry()

    if scale is None:
        scale = image_scale(img)

    pixel_area = (
        img.unmask().neq(ee.Image(0)).multiply(ee.Image.pixelArea()).divide(denominator)
    )

    return pixel_area.reduceRegion(
        **{
            "geometry": region,
            "reducer": ee.Reducer.sum(),
            "scale": scale,
            "maxPixels": 1e12,
        }
    )

`image_area_by_group(img, groups=None, region=None, scale=None, denominator=1.0, out_csv=None, labels=None, decimal_places=4, verbose=True)` ¶

Calculates the area of each class of an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	ee.Image	required
`groups`	`object`	The groups to use for the area calculation. Defaults to None.	`None`
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`		A nominal scale in meters of the projection to work in. Defaults to None.	`None`
`denominator`	`float`	The denominator to use for converting size from square meters to other units. Defaults to 1.0.	`1.0`
`out_csv`	`str \| None`	The path to the output CSV file. Defaults to None.	`None`
`labels`	`object`	The class labels to use in the output CSV file. Defaults to None.	`None`
`decimal_places`	`int`	The number of decimal places to use for the output. Defaults to 2.	`4`
`verbose`	`bool`	If True, print the progress. Defaults to True.	`True`

Returns:

Type	Description
`DataFrame \| None`	pandas.DataFrame or none if out_csv is not None.

Source code in geemap/common.py

def image_area_by_group(
    img,
    groups=None,
    region=None,
    scale=None,
    denominator: float = 1.0,
    out_csv: str | None = None,
    labels=None,
    decimal_places: int = 4,
    verbose: bool = True,
) -> pd.DataFrame | None:
    """Calculates the area of each class of an image.

    Args:
        img (object): ee.Image
        groups (object, optional): The groups to use for the area calculation. Defaults to None.
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale: A nominal scale in meters of the projection to work in. Defaults to None.
        denominator: The denominator to use for converting size from square meters to other units. Defaults to 1.0.
        out_csv: The path to the output CSV file. Defaults to None.
        labels (object, optional): The class labels to use in the output CSV file. Defaults to None.
        decimal_places: The number of decimal places to use for the output. Defaults to 2.
        verbose: If True, print the progress. Defaults to True.

    Returns:
        pandas.DataFrame or none if out_csv is not None.
    """
    values = []
    if region is None:
        region = ee.Geometry.BBox(-179.9, -89.5, 179.9, 89.5)

    if groups is None:
        groups = image_value_list(img, region, scale)

    if not isinstance(groups, list):
        groups = groups.getInfo()

    groups.sort(key=int)

    for group in groups:
        if verbose:
            print(f"Calculating area for group {group} ...")
        area = image_area(img.eq(float(group)), region, scale, denominator)
        values.append(area.values().get(0).getInfo())

    d = {"group": groups, "area": values}
    df = pd.DataFrame(data=d)
    df = df.set_index("group")
    df["percentage"] = df["area"] / df["area"].sum()
    df = df.astype(float).round(decimal_places)
    if isinstance(labels, list) and len(labels) == len(values):
        df["labels"] = labels

    if out_csv is not None:
        df.to_csv(out_csv)
    else:
        return df

`image_band_names(img)` ¶

Gets image band names.

Parameters:

Name	Type	Description	Default
`img`	`Image`	The input image.	required

Returns:

Type	Description
	ee.List: The returned list of image band names.

Source code in geemap/common.py

def image_band_names(img):
    """Gets image band names.

    Args:
        img (ee.Image): The input image.

    Returns:
        ee.List: The returned list of image band names.
    """
    return img.bandNames()

`image_bandcount(image, **kwargs)` ¶

Returns the number of bands in an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Source code in geemap/common.py

def image_bandcount(image: str, **kwargs) -> int:
    """Returns the number of bands in an image.

    Args:
        image: The input image filepath or URL.
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image
    return len(client.metadata()["bands"])

`image_bounds(image, **kwargs)` ¶

Get the bounds of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Returns:

Type	Description
`list[tuple[float, float]]`	A list of bounds in the form of [(south, west), (north, east)].

Source code in geemap/common.py

def image_bounds(image: str, **kwargs) -> list[tuple[float, float]]:
    """Get the bounds of an image.

    Args:
        image: The input image filepath or URL.

    Returns:
        A list of bounds in the form of [(south, west), (north, east)].
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image
    bounds = client.bounds()
    return [(bounds[0], bounds[2]), (bounds[1], bounds[3])]

`image_cell_size(img)` ¶

Retrieves the image cell size (e.g., spatial resolution)

Parameters:

Name	Type	Description	Default
`img`	`object`	ee.Image	required

Returns:

Name	Type	Description
`float`		The nominal scale in meters.

Source code in geemap/common.py

def image_cell_size(img):
    """Retrieves the image cell size (e.g., spatial resolution)

    Args:
        img (object): ee.Image

    Returns:
        float: The nominal scale in meters.
    """
    bands = img.bandNames()
    scales = bands.map(lambda b: img.select([b]).projection().nominalScale())

    return ee.Algorithms.If(
        scales.distinct().size().gt(1),
        ee.Dictionary.fromLists(bands.getInfo(), scales),
        scales.get(0),
    )

`image_center(image, **kwargs)` ¶

Get the center of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Returns:

Name	Type	Description
`tuple`		A tuple of (latitude, longitude).

Source code in geemap/common.py

def image_center(image: str, **kwargs):
    """Get the center of an image.

    Args:
        image: The input image filepath or URL.

    Returns:
        tuple: A tuple of (latitude, longitude).
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image
    return client.center()

`image_client(image, **kwargs)` ¶

Get a LocalTileserver TileClient from an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Returns:

Name	Type	Description
`TileClient`		A LocalTileserver TileClient.

Source code in geemap/common.py

def image_client(image, **kwargs):
    """Get a LocalTileserver TileClient from an image.

    Args:
        image (str): The input image filepath or URL.

    Returns:
        TileClient: A LocalTileserver TileClient.
    """
    image_check(image)

    _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    return client

`image_convolution(image, kernel=None, resample=None, projection='EPSG:3857', **kwargs)` ¶

Performs a convolution on an image.

Parameters:

Name	Type	Description	Default
`image`	`Image \| ImageCollection`	The image to convolve.	required
`kernel`	`Kernel`	The kernel to convolve with. Defaults to None, a 7x7 gaussian kernel.	`None`
`resample`	`str`	The resample method to use. It can be either 'bilinear' or 'bicubic'". Defaults to None, which uses the image's resample method.	`None`
`projection`	`str`	The projection to use. Defaults to 'EPSG:3857'.	`'EPSG:3857'`

Returns:

Type	Description
	ee.Image: The convolved image.

Source code in geemap/common.py

def image_convolution(
    image, kernel=None, resample=None, projection="EPSG:3857", **kwargs
):
    """Performs a convolution on an image.

    Args:
        image (ee.Image | ee.ImageCollection): The image to convolve.
        kernel (ee.Kernel, optional): The kernel to convolve with. Defaults to None, a 7x7 gaussian kernel.
        resample (str, optional): The resample method to use. It can be either 'bilinear' or 'bicubic'". Defaults to None, which uses the image's resample method.
        projection (str, optional): The projection to use. Defaults to 'EPSG:3857'.

    Returns:
        ee.Image: The convolved image.
    """
    if isinstance(image, ee.ImageCollection):
        image = image.mosaic()
    elif not isinstance(image, ee.Image):
        raise ValueError("image must be an ee.Image or ee.ImageCollection.")

    if kernel is None:
        kernel = ee.Kernel.gaussian(radius=3, sigma=2, units="pixels", normalize=True)
    elif not isinstance(kernel, ee.Kernel):
        raise ValueError("kernel must be an ee.Kernel.")

    if resample is not None:
        if resample not in ["bilinear", "bicubic"]:
            raise ValueError("resample must be one of 'bilinear' or 'bicubic'")

    result = image.convolve(kernel)

    if resample is not None:
        result = result.resample(resample)

    return result.setDefaultProjection(projection)

`image_count(collection, region=None, band=None, start_date=None, end_date=None, clip=False)` ¶

Create an image with the number of available images for a specific region. Args: collection (ee.ImageCollection): The collection to be queried. region (ee.Geometry | ee.FeatureCollection, optional): The region to be queried. start_date (str | ee.Date, optional): The start date of the query. band (str, optional): The band to be queried. end_date (str | ee.Date, optional): The end date of the query. clip (bool, optional): Whether to clip the image to the region.

Returns:

Type	Description
	ee.Image: The image with each pixel value representing the number of available images.

Source code in geemap/common.py

def image_count(
    collection, region=None, band=None, start_date=None, end_date=None, clip=False
):
    """Create an image with the number of available images for a specific region.
    Args:
        collection (ee.ImageCollection): The collection to be queried.
        region (ee.Geometry | ee.FeatureCollection, optional): The region to be queried.
        start_date (str | ee.Date, optional): The start date of the query.
        band (str, optional): The band to be queried.
        end_date (str | ee.Date, optional): The end date of the query.
        clip (bool, optional): Whether to clip the image to the region.

    Returns:
        ee.Image: The image with each pixel value representing the number of available images.
    """
    if not isinstance(collection, ee.ImageCollection):
        raise TypeError("collection must be an ee.ImageCollection.")

    if region is not None:
        if isinstance(region, (ee.Geometry, ee.FeatureCollection)):
            pass
        else:
            raise TypeError("region must be an ee.Geometry or ee.FeatureCollection.")

    if (start_date is not None) and (end_date is not None):
        pass
    elif (start_date is None) and (end_date is None):
        pass
    else:
        raise ValueError("start_date and end_date must be provided.")

    if band is None:
        first_image = collection.first()
        band = first_image.bandNames().get(0)

    if region is not None:
        collection = collection.filterBounds(region)

    if start_date is not None and end_date is not None:
        collection = collection.filterDate(start_date, end_date)

    image = (
        collection.filter(ee.Filter.listContains("system:band_names", band))
        .select([band])
        .reduce(ee.Reducer.count())
    )

    if clip:
        image = image.clip(region)

    return image

`image_date(img, date_format='YYYY-MM-dd')` ¶

Retrieves the image acquisition date.

Parameters:

Name	Type	Description	Default
`img`	`object`	ee.Image	required
`date_format`	`str`	The date format to use. Defaults to 'YYYY-MM-dd'.	`'YYYY-MM-dd'`

Returns:

Name	Type	Description
`str`		A string representing the acquisition of the image.

Source code in geemap/common.py

def image_date(img, date_format="YYYY-MM-dd"):
    """Retrieves the image acquisition date.

    Args:
        img (object): ee.Image
        date_format (str, optional): The date format to use. Defaults to 'YYYY-MM-dd'.

    Returns:
        str: A string representing the acquisition of the image.
    """
    return ee.Date(img.get("system:time_start")).format(date_format)

`image_dates(img_col, date_format='YYYY-MM-dd')` ¶

Get image dates of all images in an ImageCollection.

Parameters:

Name	Type	Description	Default
`img_col`	`object`	ee.ImageCollection	required
`date_format`	`str`	A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html; if omitted will use ISO standard date formatting. Defaults to 'YYYY-MM-dd'.	`'YYYY-MM-dd'`

Returns:

Name	Type	Description
`object`		ee.List

Source code in geemap/common.py

def image_dates(img_col, date_format="YYYY-MM-dd"):
    """Get image dates of all images in an ImageCollection.

    Args:
        img_col (object): ee.ImageCollection
        date_format (str, optional): A pattern, as described at http://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html; if omitted will use ISO standard date formatting. Defaults to 'YYYY-MM-dd'.

    Returns:
        object: ee.List
    """
    dates = img_col.aggregate_array("system:time_start")

    return dates.map(lambda d: ee.Date(d).format(date_format))

`image_geotransform(image, **kwargs)` ¶

Returns the list geotransform values of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Source code in geemap/common.py

def image_geotransform(image: str, **kwargs) -> list[float]:
    """Returns the list geotransform values of an image.

    Args:
        image: The input image filepath or URL.
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image
    return client.metadata()["GeoTransform"]

`image_histogram(img, region=None, scale=None, x_label=None, y_label=None, title=None, width=None, height=500, plot_args=None, layout_args=None, return_df=False, **kwargs)` ¶

Create a histogram of an image.

Parameters:

Name	Type	Description	Default
`img`	`Image`	The image to calculate the histogram.	required
`region`	`Geometry \| FeatureCollection`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`
`x_label`	`str \| None`	Label for the x axis. Defaults to None.	`None`
`y_label`	`str \| None`	Label for the y axis. Defaults to None.	`None`
`title`	`str \| None`	Title for the plot. Defaults to None.	`None`
`width`	`int \| None`	Width of the plot in pixels. Defaults to None.	`None`
`height`	`int`	Height of the plot in pixels. Defaults to 500.	`500`
`plot_args`	`dict \| None`	TODO.	`None`
`layout_args`	`dict \| None`	Layout arguments for the plot to be passed to fig.update_layout().	`None`
`return_df`	`bool`	If True, return a pandas dataframe. Defaults to False.	`False`

Returns:

Type	Description
	pandas DataFrame \| plotly figure object: A dataframe or plotly figure object.

Source code in geemap/common.py

def image_histogram(
    img,
    region=None,
    scale=None,
    x_label: str | None = None,
    y_label: str | None = None,
    title: str | None = None,
    width: int | None = None,
    height: int = 500,
    plot_args: dict | None = None,
    layout_args: dict | None = None,
    return_df: bool = False,
    **kwargs,
):
    """Create a histogram of an image.

    Args:
        img (ee.Image): The image to calculate the histogram.
        region (ee.Geometry | ee.FeatureCollection, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.
        x_label: Label for the x axis. Defaults to None.
        y_label: Label for the y axis. Defaults to None.
        title: Title for the plot. Defaults to None.
        width: Width of the plot in pixels. Defaults to None.
        height: Height of the plot in pixels. Defaults to 500.
        plot_args: TODO.
        layout_args: Layout arguments for the plot to be passed to fig.update_layout().
        return_df: If True, return a pandas dataframe. Defaults to False.

    Returns:
        pandas DataFrame | plotly figure object: A dataframe or plotly figure object.
    """
    plot_args = plot_args or {}
    layout_args = layout_args or {}

    hist = image_value_list(img, region, scale, return_hist=True, **kwargs).getInfo()
    keys = sorted(hist, key=int)
    values = [hist.get(key) for key in keys]

    data = pd.DataFrame({"key": keys, "value": values})

    if return_df:
        return data

    labels = {}

    if x_label is not None:
        labels["key"] = x_label
    if y_label is not None:
        labels["value"] = y_label

    fig = px.bar(
        data,
        x="key",
        y="value",
        labels=labels,
        title=title,
        width=width,
        height=height,
        **plot_args,
    )

    if isinstance(layout_args, dict):
        fig.update_layout(**layout_args)

    return fig

`image_max_value(img, region=None, scale=None)` ¶

Retrieves the maximum value of an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	The image to calculate the maximum value.	required
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`

Returns:

Name	Type	Description
`object`	`Dictionary`	ee.Number

Source code in geemap/common.py

def image_max_value(
    img: ee.Image, region=None, scale: float | None = None
) -> ee.Dictionary:
    """Retrieves the maximum value of an image.

    Args:
        img (object): The image to calculate the maximum value.
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.

    Returns:
        object: ee.Number
    """
    if region is None:
        region = img.geometry()

    if scale is None:
        scale = image_scale(img)

    return img.reduceRegion(
        **{
            "reducer": ee.Reducer.max(),
            "geometry": region,
            "scale": scale,
            "maxPixels": 1e12,
            "bestEffort": True,
        }
    )

`image_mean_value(img, region=None, scale=None)` ¶

Retrieves the mean value of an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	The image to calculate the mean value.	required
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`

Returns:

Name	Type	Description
`object`		ee.Number

Source code in geemap/common.py

def image_mean_value(img, region=None, scale=None):
    """Retrieves the mean value of an image.

    Args:
        img (object): The image to calculate the mean value.
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.

    Returns:
        object: ee.Number
    """
    if region is None:
        region = img.geometry()

    if scale is None:
        scale = image_scale(img)

    return img.reduceRegion(
        **{
            "reducer": ee.Reducer.mean(),
            "geometry": region,
            "scale": scale,
            "maxPixels": 1e12,
            "bestEffort": True,
        }
    )

`image_metadata(image, **kwargs)` ¶

Returns a dictionary of the metadata of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Source code in geemap/common.py

def image_metadata(image: str, **kwargs) -> dict[str, Any]:
    """Returns a dictionary of the metadata of an image.

    Args:
        image: The input image filepath or URL.
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image
    return client.metadata()

`image_min_value(img, region=None, scale=None)` ¶

Retrieves the minimum value of an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	The image to calculate the minimum value.	required
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`

Returns:

Name	Type	Description
`object`		ee.Number

Source code in geemap/common.py

def image_min_value(img, region=None, scale=None):
    """Retrieves the minimum value of an image.

    Args:
        img (object): The image to calculate the minimum value.
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.

    Returns:
        object: ee.Number
    """
    if region is None:
        region = img.geometry()

    if scale is None:
        scale = image_scale(img)

    return img.reduceRegion(
        **{
            "reducer": ee.Reducer.min(),
            "geometry": region,
            "scale": scale,
            "maxPixels": 1e12,
            "bestEffort": True,
        }
    )

`image_projection(image, **kwargs)` ¶

Returns the projection of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Source code in geemap/common.py

def image_projection(image: str, **kwargs) -> str:
    """Returns the projection of an image.

    Args:
        image: The input image filepath or URL.
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image
    return client.metadata()["Projection"]

`image_props(img, date_format='YYYY-MM-dd')` ¶

Gets image properties.

Parameters:

Name	Type	Description	Default
`img`	`Image`	The input image.	required
`date_format`	`str`	The output date format. Defaults to 'YYYY-MM-dd HH:mm:ss'.	`'YYYY-MM-dd'`

Returns:

Type	Description
`Dictionary \| None`	A dictionary containing image properties.

Source code in geemap/common.py

def image_props(img: ee.Image, date_format: str = "YYYY-MM-dd") -> ee.Dictionary | None:
    """Gets image properties.

    Args:
        img: The input image.
        date_format: The output date format. Defaults to 'YYYY-MM-dd HH:mm:ss'.

    Returns:
        A dictionary containing image properties.
    """
    if not isinstance(img, ee.Image):
        print("The input object must be an ee.Image.")
        return

    keys = img.propertyNames().remove("system:footprint").remove("system:bands")
    values = keys.map(lambda p: img.get(p))
    props = ee.Dictionary.fromLists(keys, values)

    names = keys.getInfo()

    bands = img.bandNames()
    scales = bands.map(lambda b: img.select([b]).projection().nominalScale())
    scale = ee.Algorithms.If(
        scales.distinct().size().gt(1),
        ee.Dictionary.fromLists(bands.getInfo(), scales),
        scales.get(0),
    )

    props = props.set("NOMINAL_SCALE", scale)

    if "system:time_start" in names:
        image_date = ee.Date(img.get("system:time_start")).format(date_format)
        time_start = ee.Date(img.get("system:time_start")).format("YYYY-MM-dd HH:mm:ss")
        time_end = ee.Algorithms.If(
            ee.List(img.propertyNames()).contains("system:time_end"),
            ee.Date(img.get("system:time_end")).format("YYYY-MM-dd HH:mm:ss"),
            time_start,
        )
        props = props.set("system:time_start", time_start)
        props = props.set("system:time_end", time_end)
        props = props.set("IMAGE_DATE", image_date)

    if "system:asset_size" in names:
        asset_size = (
            ee.Number(img.get("system:asset_size"))
            .divide(1e6)
            .format()
            .cat(ee.String(" MB"))
        )

        props = props.set("system:asset_size", asset_size)

    return props

`image_reclassify(img, in_list, out_list)` ¶

Reclassify an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	The image to which the remapping is applied.	required
`in_list`	`list`	The source values (numbers or EEArrays). All values in this list will be mapped to the corresponding value in 'out_list'.	required
`out_list`	`list`	The destination values (numbers or EEArrays). These are used to replace the corresponding values in 'from'. Must have the same number of values as 'in_list'.	required

Returns:

Name	Type	Description
`object`		ee.Image

Source code in geemap/common.py

def image_reclassify(img, in_list, out_list):
    """Reclassify an image.

    Args:
        img (object): The image to which the remapping is applied.
        in_list (list): The source values (numbers or EEArrays). All values in this list will be mapped to the corresponding value in 'out_list'.
        out_list (list): The destination values (numbers or EEArrays). These are used to replace the corresponding values in 'from'. Must have the same number of values as 'in_list'.

    Returns:
        object: ee.Image
    """
    return img.remap(in_list, out_list)

`image_resolution(image, **kwargs)` ¶

Returns the resolution of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Source code in geemap/common.py

def image_resolution(image: str, **kwargs) -> float:
    """Returns the resolution of an image.

    Args:
        image: The input image filepath or URL.
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image
    return client.metadata()["GeoTransform"][1]

`image_scale(img)` ¶

Retrieves the image cell size (e.g., spatial resolution)

Parameters:

Name	Type	Description	Default
`img`	`object`	ee.Image	required

Returns:

Name	Type	Description
`float`		The nominal scale in meters.

Source code in geemap/common.py

def image_scale(img):
    """Retrieves the image cell size (e.g., spatial resolution)

    Args:
        img (object): ee.Image

    Returns:
        float: The nominal scale in meters.
    """
    return img.select(0).projection().nominalScale()

`image_set_crs(image, epsg)` ¶

Define the CRS of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath	required
`epsg`	`int`	The EPSG code of the CRS to set.	required

Source code in geemap/common.py

def image_set_crs(image: str, epsg: int) -> None:
    """Define the CRS of an image.

    Args:
        image: The input image filepath
        epsg: The EPSG code of the CRS to set.
    """
    from rasterio.crs import CRS
    import rasterio

    with rasterio.open(image, "r+") as rds:
        rds.crs = CRS.from_epsg(epsg)

`image_size(image, **kwargs)` ¶

Returns the size (width, height) of an image.

Parameters:

Name	Type	Description	Default
`image`	`str`	The input image filepath or URL.	required

Source code in geemap/common.py

def image_size(image: str, **kwargs) -> tuple[int, int]:
    """Returns the size (width, height) of an image.

    Args:
        image: The input image filepath or URL.
    """
    image_check(image)

    if isinstance(image, str):
        _, client = get_local_tile_layer(image, return_client=True, **kwargs)
    else:
        client = image

    metadata = client.metadata()
    return metadata["sourceSizeX"], metadata["sourceSizeY"]

`image_smoothing(img, reducer, kernel)` ¶

Smooths an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	The image to be smoothed.	required
`reducer`	`object`	ee.Reducer	required
`kernel`	`object`	ee.Kernel	required

Returns:

Name	Type	Description
`object`		ee.Image

Source code in geemap/common.py

def image_smoothing(img, reducer, kernel):
    """Smooths an image.

    Args:
        img (object): The image to be smoothed.
        reducer (object): ee.Reducer
        kernel (object): ee.Kernel

    Returns:
        object: ee.Image
    """
    image = img.reduceNeighborhood(
        **{
            "reducer": reducer,
            "kernel": kernel,
        }
    )
    return image

`image_stats(img, region=None, scale=None)` ¶

Gets image descriptive statistics.

Parameters:

Name	Type	Description	Default
`img`	`Image`	The input image to calculate descriptive statistics.	required
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float \| None`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`

Returns:

Type	Description
`Dictionary`	ee.Dictionary: A dictionary containing the description statistics of the input image.

Source code in geemap/common.py

def image_stats(
    img: ee.Image, region=None, scale: float | None = None
) -> ee.Dictionary:
    """Gets image descriptive statistics.

    Args:
        img: The input image to calculate descriptive statistics.
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale: A nominal scale in meters of the projection to work in. Defaults to None.

    Returns:
        ee.Dictionary: A dictionary containing the description statistics of the input image.
    """

    if not isinstance(img, ee.Image):
        print("The input object must be an ee.Image")
        return

    stat_types = ["min", "max", "mean", "std", "sum"]

    image_min = image_min_value(img, region, scale)
    image_max = image_max_value(img, region, scale)
    image_mean = image_mean_value(img, region, scale)
    image_std = image_std_value(img, region, scale)
    image_sum = image_sum_value(img, region, scale)

    stat_results = ee.List([image_min, image_max, image_mean, image_std, image_sum])

    return ee.Dictionary.fromLists(stat_types, stat_results)

`image_stats_by_zone(image, zones, out_csv=None, labels=None, region=None, scale=None, reducer='MEAN', bestEffort=True, **kwargs)` ¶

Calculate statistics for an image by zone.

Parameters:

Name	Type	Description	Default
`image`	`Image`	The image to calculate statistics for.	required
`zones`	`Image`	The zones to calculate statistics for.	required
`out_csv`	`str \| None`	The path to the output CSV file. Defaults to None.	`None`
`labels`	`list[str] \| None`	The list of zone labels to use for the output CSV. Defaults to None.	`None`
`region`	`Geometry`	The region over which to reduce data. Defaults to the footprint of zone image.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`
`reducer`	`str \| Reducer`	The reducer to use. It can be one of MEAN, MAXIMUM, MINIMUM, MODE, STD, MIN_MAX, SUM, VARIANCE. Defaults to MEAN.	`'MEAN'`
`bestEffort`	`bool`	If the polygon would contain too many pixels at the given scale, compute and use a larger scale which would allow the operation to succeed. Defaults to True.	`True`

Returns:

Type	Description
`str \| DataFrame`	The path to the output CSV file or a pandas DataFrame.

Source code in geemap/common.py

def image_stats_by_zone(
    image,
    zones,
    out_csv: str | None = None,
    labels: list[str] | None = None,
    region=None,
    scale=None,
    reducer: str | ee.Reducer = "MEAN",
    bestEffort: bool = True,
    **kwargs,
) -> str | pd.DataFrame:
    """Calculate statistics for an image by zone.

    Args:
        image (ee.Image): The image to calculate statistics for.
        zones (ee.Image): The zones to calculate statistics for.
        out_csv: The path to the output CSV file. Defaults to None.
        labels: The list of zone labels to use for the output CSV. Defaults to None.
        region (ee.Geometry, optional): The region over which to reduce data. Defaults to the footprint of zone image.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.
        reducer: The reducer to use. It can be one of MEAN, MAXIMUM, MINIMUM, MODE, STD, MIN_MAX, SUM, VARIANCE. Defaults to MEAN.
        bestEffort: If the polygon would contain too many pixels at the given scale, compute and use a larger scale which would allow the operation to succeed. Defaults to True.

    Returns:
        The path to the output CSV file or a pandas DataFrame.
    """
    if region is not None:
        if isinstance(region, ee.Geometry):
            pass
        elif isinstance(region, ee.FeatureCollection):
            region = region.geometry()
        else:
            raise ValueError("region must be an ee.Geometry or ee.FeatureCollection")

    if scale is None:
        scale = image_scale(image)

    allowed_stats = {
        "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 isinstance(reducer, str):
        if reducer.upper() not in allowed_stats:
            raise ValueError(
                "reducer must be one of: {}".format(", ".join(allowed_stats.keys()))
            )
        else:
            reducer = allowed_stats[reducer.upper()]
    elif isinstance(reducer, ee.Reducer):
        pass
    else:
        raise ValueError(
            "reducer must be one of: {}".format(", ".join(allowed_stats.keys()))
        )

    values = image_value_list(zones, region=region)
    values = values.map(lambda x: ee.Number.parse(x))

    def get_stats(value):
        img = image.updateMask(zones.eq(ee.Number(value)))
        kwargs["reducer"] = reducer
        kwargs["scale"] = scale
        kwargs["geometry"] = region
        kwargs["bestEffort"] = bestEffort
        stat = img.reduceRegion(**kwargs)
        return ee.Image().set({"zone": value}).set({"stat": stat.values().get(0)})

    collection = ee.ImageCollection(values.map(lambda x: get_stats(x)))
    keys = collection.aggregate_array("zone").getInfo()
    values = collection.aggregate_array("stat").getInfo()

    if labels is not None and isinstance(labels, list):
        if len(labels) != len(keys):
            warnings.warn("labels are not the same length as keys, ignoring labels.")
            df = pd.DataFrame({"zone": keys, "stat": values})
        else:
            df = pd.DataFrame({"zone": keys, "label": labels, "stat": values})
    else:
        df = pd.DataFrame({"zone": keys, "stat": values})

    if out_csv is not None:
        check_file_path(out_csv)
        df.to_csv(out_csv, index=False)
        return out_csv

    return df

`image_std_value(img, region=None, scale=None)` ¶

Retrieves the standard deviation of an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	The image to calculate the standard deviation.	required
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`

Returns:

Name	Type	Description
`object`		ee.Number

Source code in geemap/common.py

def image_std_value(img, region=None, scale=None):
    """Retrieves the standard deviation of an image.

    Args:
        img (object): The image to calculate the standard deviation.
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.

    Returns:
        object: ee.Number
    """
    if region is None:
        region = img.geometry()

    if scale is None:
        scale = image_scale(img)

    return img.reduceRegion(
        **{
            "reducer": ee.Reducer.stdDev(),
            "geometry": region,
            "scale": scale,
            "maxPixels": 1e12,
            "bestEffort": True,
        }
    )

`image_sum_value(img, region=None, scale=None)` ¶

Retrieves the sum of an image.

Parameters:

Name	Type	Description	Default
`img`	`object`	The image to calculate the standard deviation.	required
`region`	`object`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`

Returns:

Name	Type	Description
`object`		ee.Number

Source code in geemap/common.py

def image_sum_value(img, region=None, scale=None):
    """Retrieves the sum of an image.

    Args:
        img (object): The image to calculate the standard deviation.
        region (object, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.

    Returns:
        object: ee.Number
    """
    if region is None:
        region = img.geometry()

    if scale is None:
        scale = image_scale(img)

    return img.reduceRegion(
        **{
            "reducer": ee.Reducer.sum(),
            "geometry": region,
            "scale": scale,
            "maxPixels": 1e12,
            "bestEffort": True,
        }
    )

`image_to_cog(source, dst_path=None, profile='deflate', **kwargs)` ¶

Converts an image to a COG file.

Parameters:

Name	Type	Description	Default
`source`	`str`	A dataset path, URL or rasterio.io.DatasetReader object.	required
`dst_path`	`str`	An output dataset path or or PathLike object. Defaults to None.	`None`
`profile`	`str`	COG profile. More at https://cogeotiff.github.io/rio-cogeo/profile. Defaults to "deflate".	`'deflate'`

Raises:

Type	Description
`ImportError`	If rio-cogeo is not installed.
`FileNotFoundError`	If the source file could not be found.

Source code in geemap/common.py

def image_to_cog(source, dst_path=None, profile="deflate", **kwargs):
    """Converts an image to a COG file.

    Args:
        source (str): A dataset path, URL or rasterio.io.DatasetReader object.
        dst_path (str, optional): An output dataset path or or PathLike object. Defaults to None.
        profile (str, optional): COG profile. More at https://cogeotiff.github.io/rio-cogeo/profile. Defaults to "deflate".

    Raises:
        ImportError: If rio-cogeo is not installed.
        FileNotFoundError: If the source file could not be found.
    """
    from rio_cogeo.cogeo import cog_translate
    from rio_cogeo.profiles import cog_profiles

    if not source.startswith(("http://", "https://")):
        source = check_file_path(source)

        if not os.path.exists(source):
            raise FileNotFoundError("The provided input file could not be found.")

    if dst_path is None:
        if not source.startswith(("http://", "https://")):
            dst_path = os.path.splitext(source)[0] + "_cog.tif"
        else:
            dst_path = coreutils.temp_file_path(extension=".tif")

    dst_path = check_file_path(dst_path)

    dst_profile = cog_profiles.get(profile)
    cog_translate(source, dst_path, dst_profile, **kwargs)

`image_to_numpy(image)` ¶

Converts an image to a numpy array.

Parameters:

Name	Type	Description	Default
`image`	`str`	A dataset path, URL or rasterio.io.DatasetReader object.	required

Raises:

Type	Description
`FileNotFoundError`	If the provided file could not be found.

Returns:

Type	Description
	np.array: A numpy array.

Source code in geemap/common.py

def image_to_numpy(image):
    """Converts an image to a numpy array.

    Args:
        image (str): A dataset path, URL or rasterio.io.DatasetReader object.

    Raises:
        FileNotFoundError: If the provided file could not be found.

    Returns:
        np.array: A numpy array.
    """
    import rasterio
    from osgeo import gdal

    @contextlib.contextmanager
    def gdal_error_handler():
        """Context manager for GDAL error handler."""
        gdal.PushErrorHandler("CPLQuietErrorHandler")
        try:
            yield
        finally:
            gdal.PopErrorHandler()

    gdal.UseExceptions()

    with gdal_error_handler():

        if not os.path.exists(image):
            raise FileNotFoundError("The provided input file could not be found.")

        with rasterio.open(image, "r") as ds:
            arr = ds.read()  # read all raster values

    return arr

`image_value_list(img, region=None, scale=None, return_hist=False, **kwargs)` ¶

Get the unique values of an image.

Parameters:

Name	Type	Description	Default
`img`	`Image`	The image to calculate the unique values.	required
`region`	`Geometry \| FeatureCollection`	The region over which to reduce data. Defaults to the footprint of the image's first band.	`None`
`scale`	`float`	A nominal scale in meters of the projection to work in. Defaults to None.	`None`
`return_hist`	`bool`	If True, return a histogram of the values. Defaults to False.	`False`

Returns:

Type	Description
	ee.List \| ee.Dictionary: A list of unique values or a dictionary containing a list of unique values and a histogram.

Source code in geemap/common.py

def image_value_list(img, region=None, scale=None, return_hist=False, **kwargs):
    """Get the unique values of an image.

    Args:
        img (ee.Image): The image to calculate the unique values.
        region (ee.Geometry | ee.FeatureCollection, optional): The region over which to reduce data. Defaults to the footprint of the image's first band.
        scale (float, optional): A nominal scale in meters of the projection to work in. Defaults to None.
        return_hist (bool, optional): If True, return a histogram of the values. Defaults to False.

    Returns:
        ee.List | ee.Dictionary: A list of unique values or a dictionary containing a list of unique values and a histogram.
    """
    if region is None:
        geom = img.geometry().bounds()
        region = ee.FeatureCollection([ee.Feature(geom)])
    elif isinstance(region, ee.Geometry):
        region = ee.FeatureCollection([ee.Feature(region)])
    elif isinstance(region, ee.FeatureCollection):
        pass
    else:
        raise ValueError("region must be an ee.Geometry or ee.FeatureCollection")

    if scale is None:
        scale = img.select(0).projection().nominalScale().multiply(10)

    reducer = ee.Reducer.frequencyHistogram()
    kwargs["scale"] = scale
    kwargs["reducer"] = reducer
    kwargs["collection"] = region

    result = img.reduceRegions(**kwargs)
    hist = ee.Dictionary(result.first().get("histogram"))
    if return_hist:
        return hist

    return hist.keys()

`install_from_github(url)` ¶

Install a package from a GitHub repository.

Parameters:

Name	Type	Description	Default
`url`	`str`	The URL of the GitHub repository.	required

Source code in geemap/common.py

def install_from_github(url: str) -> None:
    """Install a package from a GitHub repository.

    Args:
        url: The URL of the GitHub repository.
    """
    download_dir = os.path.join(os.path.expanduser("~"), "Downloads")
    if not os.path.exists(download_dir):
        os.makedirs(download_dir)

    repo_name = os.path.basename(url)
    zip_url = os.path.join(url, "archive/master.zip")
    filename = repo_name + "-master.zip"
    download_from_url(
        url=zip_url, out_file_name=filename, out_dir=download_dir, unzip=True
    )

    pkg_dir = os.path.join(download_dir, repo_name + "-master")
    pkg_name = os.path.basename(url)
    work_dir = os.getcwd()
    os.chdir(pkg_dir)
    print(f"Installing {pkg_name}...")
    cmd = "pip install ."
    os.system(cmd)
    os.chdir(work_dir)
    print(f"{pkg_name} has been installed successfully.")

`install_package(package)` ¶

Install a Python package.

Parameters:

Name	Type	Description	Default
`package`	`str \| list[str]`	Package name or a GitHub URL or a list of package names or GitHub URLs.	required

Source code in geemap/common.py

def install_package(package: str | list[str]) -> None:
    """Install a Python package.

    Args:
        package: Package name or a GitHub URL or a list of package names or GitHub URLs.
    """
    if isinstance(package, str):
        packages = [package]
    elif isinstance(package, list):
        packages = package
    else:
        raise ValueError("Invalid package type. Please provide a string or a list.")

    for package in packages:
        if package.startswith("https"):
            package = f"git+{package}"

        # Execute pip install command and show output in real-time
        command = f"pip install {package}"
        process = subprocess.Popen(command.split(), stdout=subprocess.PIPE)

        # Print output in real-time
        while True:
            output = process.stdout.readline()  # pytype: disable=attribute-error
            if output == b"" and process.poll() is not None:
                break
            if output:
                print(output.decode("utf-8").strip())

        # Wait for process to complete
        process.wait()

`is_arcpy()` ¶

Check if arcpy is available.

Returns:

Name	Type	Description
`book`		True if arcpy is available, False otherwise.

Source code in geemap/common.py

def is_arcpy():
    """Check if arcpy is available.

    Returns:
        book: True if arcpy is available, False otherwise.
    """
    if "arcpy" in sys.modules:
        return True
    else:
        return False

`is_drive_mounted()` ¶

Returns True if Google Drive is mounted, False otherwise.

Source code in geemap/common.py

def is_drive_mounted() -> bool:
    """Returns True if Google Drive is mounted, False otherwise."""
    drive_path = "/content/drive/My Drive"
    return os.path.exists(drive_path)

`is_latlon_valid(location)` ¶

Checks whether a pair of coordinates is valid.

Parameters:

Name	Type	Description	Default
`location`	`str`	A pair of latlon coordinates separated by comma or space.	required

Returns:

Type	Description
`bool`	Returns True if valid.

Source code in geemap/common.py

def is_latlon_valid(location: str) -> bool:
    """Checks whether a pair of coordinates is valid.

    Args:
        location: A pair of latlon coordinates separated by comma or space.

    Returns:
        Returns True if valid.
    """
    if "," in location:
        latlon = [float(x) for x in location.split(",")]
    elif " " in location:
        latlon = [float(x) for x in location.split(" ")]
    else:
        print(
            "The coordinates should be numbers only and separated by comma or space, such as 40.2, -100.3"
        )
        return False

    try:
        lat, lon = float(latlon[0]), float(latlon[1])
        return lat >= -90 and lat <= 90 and lon >= -180 and lon <= 180
    except Exception as e:
        print(e)
        return False

`is_on_aws()` ¶

Returns True if the notebook is running on AWS.

Source code in geemap/common.py

def is_on_aws() -> bool:
    """Returns True if the notebook is running on AWS."""
    import psutil

    parent = psutil.Process().parent()
    assert parent  # For pytype.
    output = parent.cmdline()

    for item in output:
        if item.endswith(".aws") or "ec2-user" in item:
            return True
    return False

`is_studio_lab()` ¶

Returns True if the notebook is running on Studio Lab.

Source code in geemap/common.py

def is_studio_lab() -> bool:
    """Returns True if the notebook is running on Studio Lab."""
    import psutil

    parent = psutil.Process().parent()
    assert parent  # For pytype.
    output = parent.cmdline()

    for item in output:
        if "studiolab/bin" in item:
            return True
    return False

`is_tool(name)` ¶

Check whether name is on PATH and marked as executable.

Source code in geemap/common.py

def is_tool(name: str) -> bool:
    """Check whether `name` is on PATH and marked as executable."""

    return shutil.which(name) is not None

`jpg_to_gif(in_dir, out_gif, fps=10, loop=0)` ¶

Convert a list of jpg images to gif.

Parameters:

Name	Type	Description	Default
`in_dir`	`str`	The input directory containing jpg images.	required
`out_gif`	`str`	The output file path to the gif.	required
`fps`	`int`	Frames per second. Defaults to 10.	`10`
`loop`	`bool`	controls how many times the animation repeats. 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`

Raises:

Type	Description
`FileNotFoundError`	No jpg images could be found.

Source code in geemap/common.py

def jpg_to_gif(in_dir, out_gif, fps=10, loop=0):
    """Convert a list of jpg images to gif.

    Args:
        in_dir (str): The input directory containing jpg images.
        out_gif (str): The output file path to the gif.
        fps (int, optional): Frames per second. Defaults to 10.
        loop (bool, optional): controls how many times the animation repeats. 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.

    Raises:
        FileNotFoundError: No jpg images could be found.
    """
    from PIL import Image

    if not out_gif.endswith(".gif"):
        raise ValueError("The out_gif must be a gif file.")

    out_gif = os.path.abspath(out_gif)

    out_dir = os.path.dirname(out_gif)
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    # Create the frames
    frames = []
    imgs = list(glob.glob(os.path.join(in_dir, "*.jpg")))
    imgs.sort()

    if len(imgs) == 0:
        raise FileNotFoundError(f"No jpg could be found in {in_dir}.")

    for i in imgs:
        new_frame = Image.open(i)
        frames.append(new_frame)

    # Save into a GIF file that loops forever
    frames[0].save(
        out_gif,
        format="GIF",  # pylint: disable=redefined-builtin
        append_images=frames[1:],
        save_all=True,
        duration=1000 / fps,
        loop=loop,
    )

`jrc_hist_monthly_history(collection=None, region=None, start_date='1984-03-16', end_date=None, start_month=1, end_month=12, scale=None, frequency='year', reducer='mean', denominator=int(10000.0), x_label=None, y_label=None, title=None, width=None, height=None, layout_args=None, return_df=False, **kwargs)` ¶

Create a JRC monthly history plot.

Parameters:

Name	Type	Description	Default
`collection`	`ImageCollection`	The image collection of JRC surface water monthly history. Default to ee.ImageCollection('JRC/GSW1_4/MonthlyHistory')	`None`
`region`	`Geometry \| FeatureCollection`	The region to plot. Default to None.	`None`
`start_date`	`str`	The start date of the plot. Default to '1984-03-16'.	`'1984-03-16'`
`end_date`	`str \| None`	The end date of the plot. Default to the current date.	`None`
`start_month`	`int`	The start month of the plot. Default to 1.	`1`
`end_month`	`int`	The end month of the plot. Default to 12.	`12`
`scale`	`float \| None`	The scale to compute the statistics. Default to None.	`None`
`frequency`	`str`	The frequency of the plot. Can be either 'year' or 'month', Default to 'year'.	`'year'`
`reducer`	`str`	The reducer to compute the statistics. Can be either 'mean', 'min', 'max', 'median', etc. Default to 'mean'.	`'mean'`
`denominator`	`int`	The denominator to convert area from square meters to other units. Default to 1e4, converting to hectares.	`int(10000.0)`
`x_label`	`str \| None`	Label for the x axis. Defaults to None.	`None`
`y_label`	`str \| None`	Label for the y axis. Defaults to None.	`None`
`title`	`str \| None`	Title for the plot. Defaults to None.	`None`
`width`	`int \| None`	Width of the plot in pixels. Defaults to None.	`None`
`height`	`int \| None`	Height of the plot in pixels. Defaults to 500.	`None`
`layout_args`	`dict \| None`	Layout arguments for the plot to be passed to fig.update_layout().	`None`
`return_df`	`bool`	Whether to return the dataframe of the plot. Defaults to False.	`False`

Returns:

Type	Description
	pd.DataFrame: Pandas dataframe of the plot.

Source code in geemap/common.py

def jrc_hist_monthly_history(
    collection=None,
    region=None,
    start_date: str = "1984-03-16",
    end_date: str | None = None,
    start_month: int = 1,
    end_month: int = 12,
    scale: float | None = None,
    frequency: str = "year",
    reducer: str = "mean",
    denominator: int = int(1e4),
    x_label: str | None = None,
    y_label: str | None = None,
    title: str | None = None,
    width: int | None = None,
    height: int | None = None,
    layout_args: dict | None = None,
    return_df: bool = False,
    **kwargs,
):
    """Create a JRC monthly history plot.

    Args:
        collection (ee.ImageCollection, optional): The image collection of JRC surface water monthly history.
            Default to ee.ImageCollection('JRC/GSW1_4/MonthlyHistory')
        region (ee.Geometry | ee.FeatureCollection, optional): The region to plot. Default to None.
        start_date: The start date of the plot. Default to '1984-03-16'.
        end_date: The end date of the plot. Default to the current date.
        start_month: The start month of the plot. Default to 1.
        end_month: The end month of the plot. Default to 12.
        scale: The scale to compute the statistics. Default to None.
        frequency: The frequency of the plot. Can be either 'year' or 'month', Default to 'year'.
        reducer: The reducer to compute the statistics. Can be either 'mean', 'min', 'max', 'median', etc. Default to 'mean'.
        denominator: The denominator to convert area from square meters to other units. Default to 1e4, converting to hectares.
        x_label: Label for the x axis. Defaults to None.
        y_label: Label for the y axis. Defaults to None.
        title: Title for the plot. Defaults to None.
        width: Width of the plot in pixels. Defaults to None.
        height: Height of the plot in pixels. Defaults to 500.
        layout_args: Layout arguments for the plot to be passed to fig.update_layout().
        return_df: Whether to return the dataframe of the plot. Defaults to False.

    Returns:
        pd.DataFrame: Pandas dataframe of the plot.
    """
    layout_args = layout_args or {}

    if end_date is None:
        end_date = datetime.date.today().strftime("%Y-%m-%d")

    if collection is None:
        collection = ee.ImageCollection("JRC/GSW1_4/MonthlyHistory")

    if frequency not in ["year", "month"]:
        raise ValueError("frequency must be 'year' or 'month'.")

    images = (
        collection.filterDate(start_date, end_date)
        .filter(ee.Filter.calendarRange(start_month, end_month, "month"))
        .map(lambda img: img.eq(2).selfMask())
    )

    def cal_area(img):
        pixel_area = img.multiply(ee.Image.pixelArea()).divide(denominator)
        img_area = pixel_area.reduceRegion(
            **{
                "geometry": region,
                "reducer": ee.Reducer.sum(),
                "scale": scale,
                "maxPixels": 1e12,
                "bestEffort": True,
            }
        )
        return img.set({"area": img_area})

    areas = images.map(cal_area)
    stats = areas.aggregate_array("area").getInfo()
    values = [item["water"] for item in stats]
    labels = areas.aggregate_array("system:index").getInfo()
    months = [label.split("_")[1] for label in labels]

    if frequency == "month":
        area_df = pd.DataFrame({"Month": labels, "Area": values, "month": months})
    else:
        dates = [d[:4] for d in labels]
        data_dict = {"Date": labels, "Year": dates, "Area": values}
        df = pd.DataFrame(data_dict)
        result = df.groupby("Year").agg(reducer)
        area_df = pd.DataFrame({"Year": result.index, "Area": result["Area"]})
        area_df = area_df.reset_index(drop=True)

    if return_df:
        return area_df
    else:
        labels = {}

        if x_label is not None:
            labels[frequency.title()] = x_label
        if y_label is not None:
            labels["Area"] = y_label

        fig = px.bar(
            area_df,
            x=frequency.title(),
            y="Area",
            labels=labels,
            title=title,
            width=width,
            height=height,
            **kwargs,
        )

        fig.update_layout(**layout_args)

        return fig

`js_snippet_to_py(in_js_snippet, add_new_cell=True, import_ee=True, import_geemap=False, show_map=True, Map='m')` ¶

EE JavaScript snippet wrapped in triple quotes to Python in a notebook.

Parameters:

Name	Type	Description	Default
`in_js_snippet`	`str`	Earth Engine JavaScript within triple quotes.	required
`add_new_cell`	`bool`	Whether add the converted Python to a new cell.	`True`
`import_ee`	`bool`	Whether to import ee.	`True`
`import_geemap`	`bool`	Whether to import geemap.	`False`
`show_map`	`bool`	Whether to show the map.	`True`
`Map`	`str`	The name of the map variable.	`'m'`

Returns:

Type	Description
`list[str] \| None`	A list of lines of Python script.

Source code in geemap/conversion.py

def js_snippet_to_py(
    in_js_snippet: str,
    add_new_cell: bool = True,
    import_ee: bool = True,
    import_geemap: bool = False,
    show_map: bool = True,
    Map: str = "m",
) -> list[str] | None:
    """EE JavaScript snippet wrapped in triple quotes to Python in a notebook.

    Args:
        in_js_snippet: Earth Engine JavaScript within triple quotes.
        add_new_cell: Whether add the converted Python to a new cell.
        import_ee: Whether to import ee.
        import_geemap: Whether to import geemap.
        show_map: Whether to show the map.
        Map: The name of the map variable.

    Returns:
        A list of lines of Python script.
    """

    in_js = coreutils.temp_file_path(".js")
    out_py = coreutils.temp_file_path(".py")

    # Add quotes around keys.
    in_js_snippet = re.sub(r"([a-zA-Z0-9_]+)\s*:", r'"\1":', in_js_snippet)

    with open(in_js, "w", encoding="utf-8") as f:
        f.write(in_js_snippet)
    js_to_python(
        in_js,
        out_file=out_py,
        use_qgis=False,
        show_map=show_map,
        import_geemap=import_geemap,
        Map=Map,
    )

    out_lines = []
    if import_ee:
        out_lines.append("import ee\n")

    with open(out_py, encoding="utf-8") as f:
        lines = f.readlines()
        for index, line in enumerate(lines):
            if index < (len(lines) - 1):
                if line.strip() == "import ee":
                    continue

                next_line = lines[index + 1]
                if line.strip() == "" and next_line.strip() == "":
                    continue

                if ".style(" in line and (".style(**" not in line):
                    line = line.replace(".style(", ".style(**")
                    out_lines.append(line)
                elif "({" in line:
                    line = line.replace("({", "(**{")
                    out_lines.append(line)
                else:
                    out_lines.append(line)
            elif index == (len(lines) - 1) and lines[index].strip() != "":
                out_lines.append(line)

    os.remove(in_js)
    os.remove(out_py)

    if add_new_cell:
        contents = "".join(out_lines).strip()
        create_new_cell(contents)
    else:
        return out_lines

`js_to_python(in_file, out_file=None, use_qgis=True, github_repo=None, show_map=True, import_geemap=False, Map='m')` ¶

Converts an Earth Engine JavaScript to Python script.

Parameters:

Name	Type	Description	Default
`in_file`	`str`	File path of the input JavaScript.	required
`out_file`	`str \| None`	File path of the output Python script.	`None`
`use_qgis`	`bool`	Whether to add "from ee_plugin import Map" to the output script.	`True`
`github_repo`	`str \| None`	GitHub repo url.	`None`
`show_map`	`bool`	Whether to add "Map" to the output script.	`True`
`import_geemap`	`bool`	Whether to add "import geemap" to the output script.	`False`
`Map`	`str`	The name of the map variable.	`'m'`

Returns:

Type	Description
`str \| None`	Python script.

Source code in geemap/conversion.py

def js_to_python(
    in_file: str,
    out_file: str | None = None,
    use_qgis: bool = True,
    github_repo: str | None = None,
    show_map: bool = True,
    import_geemap: bool = False,
    Map: str = "m",
) -> str | None:
    """Converts an Earth Engine JavaScript to Python script.

    Args:
        in_file: File path of the input JavaScript.
        out_file: File path of the output Python script.
        use_qgis: Whether to add "from ee_plugin import Map" to the output script.
        github_repo: GitHub repo url.
        show_map: Whether to add "Map" to the output script.
        import_geemap: Whether to add "import geemap" to the output script.
        Map: The name of the map variable.

    Returns:
        Python script.
    """
    in_file = os.path.abspath(in_file)
    if out_file is None:
        out_file = in_file.replace(".js", ".py")

    root_dir = os.path.dirname(os.path.abspath(__file__))
    if not os.path.isfile(in_file):
        in_file = os.path.join(root_dir, in_file)
    if not os.path.isfile(out_file):
        out_file = os.path.join(root_dir, out_file)

    is_python = False

    if use_qgis and import_geemap:
        raise Exception(
            "use_qgis and import_geemap cannot be both True. "
            "Please set one of them to False."
        )

    import_str = ""
    if use_qgis:
        import_str = "from ee_plugin import Map\n"
    if import_geemap:
        import_str = f"import geemap\n\n{Map} = geemap.Map()\n"

    github_url = ""
    if github_repo is not None:
        github_url = "# GitHub URL: " + github_repo + in_file + "\n\n"

    math_import = False
    math_import_str = ""

    lines = []
    with open(in_file, encoding="utf-8") as f:
        lines = f.readlines()

        math_import = use_math(lines)

        for line in lines:
            line = line.strip()
            if line == "import ee":
                is_python = True

    if math_import:
        math_import_str = "import math\n"

    output = ""

    if is_python:  # Only update the GitHub URL if it is already a GEE Python script.
        output = github_url + "".join(map(str, lines))
    else:  # Deal with JavaScript.
        header = github_url + "import ee \n" + math_import_str + import_str
        # function_defs = []
        output = header + "\n"

        with open(in_file, encoding="utf-8") as f:
            lines = f.readlines()

            num_incorrect_parameters = 0
            check_next_line_for_print = False
            should_check_for_empty_lines = False
            current_dictionary_scope_depth = 0
            current_num_of_nested_funcs = 0

            # We need to remove all spaces from the beginning of each line to accurately
            # format the indentation.
            lines = remove_all_indentation(lines)

            lines = check_map_functions(lines)

            for index, line in enumerate(lines):

                if "Map.setOptions" in line:
                    # Regular expression to remove everything after the comma and before
                    # ');'.
                    line = re.sub(r",[^)]+(?=\);)", "", line)

                if ("/* color" in line) and ("*/" in line):
                    line = (
                        line[: line.index("/*")].lstrip()
                        + line[(line.index("*/") + 2) :]
                    )

                if (
                    ("= function" in line)
                    or ("=function" in line)
                    or line.strip().startswith("function")
                ):
                    try:
                        bracket_index = line.index("{")

                        (
                            matching_line_index,
                            matching_char_index,
                        ) = find_matching_bracket(lines, index, bracket_index)

                        if "func_" not in line:
                            current_num_of_nested_funcs += 1

                            for sub_index, tmp_line in enumerate(
                                lines[index + 1 : matching_line_index]
                            ):
                                if "{" in tmp_line and "function" not in line:
                                    current_num_of_nested_funcs += 1
                                if "}" in tmp_line and "function" not in line:
                                    current_num_of_nested_funcs -= 1
                                lines[index + 1 + sub_index] = (
                                    "    " * current_num_of_nested_funcs
                                ) + lines[index + 1 + sub_index]

                            current_num_of_nested_funcs -= 1

                        line = line[:bracket_index] + line[bracket_index + 1 :]
                        if matching_line_index == index:
                            line = (
                                line[:matching_char_index]
                                + line[matching_char_index + 1 :]
                            )
                        else:
                            tmp_line = lines[matching_line_index]
                            lines[matching_line_index] = (
                                tmp_line[:matching_char_index]
                                + tmp_line[matching_char_index + 1 :]
                            )

                    except Exception as e:
                        print(
                            f"An error occurred when processing {in_file}. "
                            "The closing curly bracket could not be found in "
                            f"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."
                        )
                        print(e)
                        return

                    line = (
                        line.replace(" = function", "")
                        .replace("=function", "")
                        .replace("function ", "")
                    )
                    if line.lstrip().startswith("//"):
                        line = line.replace("//", "").lstrip()
                        line = (
                            " " * (len(line) - len(line.lstrip()))
                            + "# def "
                            + line.strip()
                            + ":"
                        )
                    else:
                        line = (
                            " " * (len(line) - len(line.lstrip()))
                            + "def "
                            + line.strip()
                            + ":"
                        )
                elif "{" in line and "({" not in line:
                    bracket_index = line.index("{")
                    (
                        matching_line_index,
                        matching_char_index,
                    ) = find_matching_bracket(lines, index, bracket_index)

                    current_num_of_nested_funcs += 1

                    for sub_index, tmp_line in enumerate(
                        lines[index + 1 : matching_line_index]
                    ):
                        lines[index + 1 + sub_index] = (
                            "    " * current_num_of_nested_funcs
                        ) + lines[index + 1 + sub_index]
                        if "{" in tmp_line and "if" not in line and "for" not in line:
                            current_num_of_nested_funcs += 1
                        if "}" in tmp_line and "if" not in line and "for" not in line:
                            current_num_of_nested_funcs -= 1

                    current_num_of_nested_funcs -= 1

                    if (matching_line_index == index) and (":" in line):
                        pass
                    elif (
                        ("for (" in line)
                        or ("for(" in line)
                        or ("if (" in line)
                        or ("if(" in line)
                    ):
                        if "if" not in line:
                            line = convert_for_loop(line)
                        else:
                            start_index = line.index("(")
                            end_index = line.index(")")
                            line = "if " + line[start_index:end_index] + "):{"
                        lines[index] = line
                        bracket_index = line.index("{")
                        (
                            matching_line_index,
                            matching_char_index,
                        ) = find_matching_bracket(lines, index, bracket_index)
                        tmp_line = lines[matching_line_index]
                        lines[matching_line_index] = (
                            tmp_line[:matching_char_index]
                            + tmp_line[matching_char_index + 1 :]
                        )
                        line = line.replace("{", "")

                if line is None:
                    line = ""

                line = line.replace("//", "#")
                line = line.replace("var ", "", 1)
                line = line.replace("/*", "#")
                line = line.replace("*/", "#")
                line = line.replace("true", "True").replace("false", "False")
                line = line.replace("null", "None")
                line = line.replace(".or", ".Or")
                line = line.replace(".and", ".And")
                line = line.replace(".not", ".Not")
                line = line.replace("visualize({", "visualize(**{")
                line = line.replace("Math.PI", "math.pi")
                line = line.replace("Math.", "math.")
                line = line.replace("parseInt", "int")
                line = line.replace("NotNull", "notNull")
                line = line.replace("= new", "=")
                line = line.replace("exports.", "")
                line = line.replace("Map.", f"{Map}.")
                line = line.replace(
                    "Export.table.toDrive", "geemap.ee_export_vector_to_drive"
                )
                line = line.replace(
                    "Export.table.toAsset", "geemap.ee_export_vector_to_asset"
                )
                line = line.replace(
                    "Export.image.toAsset", "geemap.ee_export_image_to_asset"
                )
                line = line.replace(
                    "Export.video.toDrive", "geemap.ee_export_video_to_drive"
                )
                line = line.replace("||", "or")
                line = line.replace(r"\****", "#")
                line = line.replace("def =", "_def =")
                line = line.replace(", def, ", ", _def, ")
                line = line.replace("(def, ", "(_def, ")
                line = line.replace(", def)", ", _def)")
                line = line.replace("===", "==")

                # Replaces all javascript operators with python operators.
                if "!" in line:
                    try:
                        if (line.replace(" ", ""))[line.find("!") + 1] != "=":
                            line = line.replace("!", "not ")
                    except:
                        print("continue...")

                line = line.rstrip()

                # If the function concat is used, replace it with python's
                # concatenation.
                if "concat" in line:
                    line = line.replace(".concat(", "+")
                    line = line.replace(",", "+")
                    line = line.replace(")", "")

                # Checks if an equal sign is at the end of a line. If so, add
                # backslashes.
                if should_check_for_empty_lines:
                    if line.strip() == "" or "#" in line:
                        if line.strip().endswith("["):
                            line = "["
                            should_check_for_empty_lines = False
                        else:
                            line = "\\"
                    else:
                        should_check_for_empty_lines = False

                if line.strip().endswith("="):
                    line = line + " \\"
                    should_check_for_empty_lines = True

                # Adds getInfo at the end of print statements involving maps
                end_of_print_replaced = False

                if ("print(" in line and "=" not in line) or check_next_line_for_print:
                    for i in range(len(line) - 1):
                        if line[len(line) - i - 1] == ")":
                            line = line[: len(line) - i - 1] + ".getInfo())"
                            # print(line)
                            end_of_print_replaced = True
                            break
                    if end_of_print_replaced:
                        check_next_line_for_print = False
                    else:
                        check_next_line_for_print = True

                # Removes potential commas after imports. Causes tuple type errors.
                if line.endswith(","):
                    if "=" in lines[index + 1] and not lines[
                        index + 1
                    ].strip().startswith("'"):
                        line = line[:-1]

                # Changes object argument to individual parameters.
                if (
                    line.strip().endswith("({")
                    and not "ee.Dictionary" in line
                    and not ".set(" in line
                    and ".addLayer" not in line
                    and "cast" not in line
                ):
                    line = line.rstrip()[:-1]
                    num_incorrect_parameters = num_incorrect_parameters + 1

                if num_incorrect_parameters > 0:
                    if line.strip().startswith("})"):
                        line = line.replace("})", ")")
                        num_incorrect_parameters = num_incorrect_parameters - 1
                    else:
                        if current_dictionary_scope_depth < 1:
                            line = line.replace(": ", "=")
                            line = line.replace(":", " =")

                if "= {" in line and "({" not in line:
                    current_dictionary_scope_depth += 1

                if "}" in line and current_dictionary_scope_depth > 0:
                    current_dictionary_scope_depth -= 1

                if line.endswith("+"):
                    line = line + " \\"
                elif line.endswith(";"):
                    line = line[:-1]

                if line.lstrip().startswith("*"):
                    line = line.replace("*", "#")

                if (
                    (":" in line)
                    and (not line.strip().startswith("#"))
                    and (not line.strip().startswith("def"))
                    and (not line.strip().startswith("."))
                    and (not line.strip().startswith("if"))
                ):
                    line = format_params(line)

                if (
                    index < (len(lines) - 1)
                    and line.lstrip().startswith("#")
                    and lines[index + 1].lstrip().startswith(".")
                ):
                    line = ""

                if (
                    "#" in line
                    and not line.strip().startswith("#")
                    and not line[line.index("#") - 1] == "'"
                ):
                    line = line[: line.index("#")]

                if line.lstrip().startswith("."):
                    if lines[index - 1].strip().endswith("\\") and lines[
                        index - 1
                    ].strip().startswith("#"):
                        lines[index - 1] = "\\"
                    if "#" in line:
                        line = line[: line.index("#")]
                    output = output.rstrip() + " " + "\\" + "\n" + line + "\n"
                else:
                    output += line + "\n"

    if show_map:
        output += Map

    out_dir = os.path.dirname(out_file)
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    with open(out_file, "w", encoding="utf-8") as f:
        f.write(output)

    return output

`js_to_python_dir(in_dir, out_dir=None, use_qgis=True, github_repo=None, import_geemap=False, Map='m')` ¶

Converts EE JavaScript files in a folder recursively to Python scripts.

Parameters:

Name	Type	Description	Default
`in_dir`	`str`	The input folder containing Earth Engine JavaScript files.	required
`out_dir`	`str \| None`	The output folder containing Earth Engine Python files.	`None`
`use_qgis`	`bool`	Whether to add "from ee_plugin import Map" to the output file.	`True`
`github_repo`	`str \| None`	GitHub repo url.	`None`
`import_geemap`	`bool`	Whether to add "import geemap" to the output file.	`False`
`Map`	`str`	The name of the map variable.	`'m'`

Source code in geemap/conversion.py

def js_to_python_dir(
    in_dir: str,
    out_dir: str | None = None,
    use_qgis: bool = True,
    github_repo: str | None = None,
    import_geemap: bool = False,
    Map: str = "m",
) -> None:
    """Converts EE JavaScript files in a folder recursively to Python scripts.

    Args:
        in_dir: The input folder containing Earth Engine JavaScript files.
        out_dir: The output folder containing Earth Engine Python files.
        use_qgis: Whether to add "from ee_plugin import Map" to the output file.
        github_repo: GitHub repo url.
        import_geemap: Whether to add "import geemap" to the output file.
        Map: The name of the map variable.
    """
    print("Converting Earth Engine JavaScripts to Python scripts...")
    in_dir = os.path.abspath(in_dir)
    if out_dir is None:
        out_dir = in_dir
    elif not os.path.exists(out_dir):
        out_dir = os.path.abspath(out_dir)
        os.makedirs(out_dir)
    else:
        out_dir = os.path.abspath(out_dir)

    files = list(pathlib.Path(in_dir).rglob("*.js"))

    for index, in_file in enumerate(files):
        print(f"Processing {index + 1}/{len(files)}: {in_file}")
        out_file = os.path.splitext(in_file)[0] + "_geemap.py"
        out_file = out_file.replace(in_dir, out_dir)
        js_to_python(  # pytype: disable=wrong-arg-types
            in_file,
            out_file,
            use_qgis,
            github_repo,
            import_geemap=import_geemap,
            Map=Map,
        )

`jslink_slider_label(slider, label)` ¶

Link a slider and a label.

Source code in geemap/common.py

def jslink_slider_label(
    slider: ipywidgets.IntSlider | ipywidgets.FloatSlider, label: ipywidgets.Label
) -> None:
    """Link a slider and a label."""

    def update_label(change):
        if change["name"]:
            label.value = str(change["new"])

    slider.observe(update_label, "value")

`kml_to_ee(in_kml, **kwargs)` ¶

Converts a KML to ee.FeatureCollection.

Parameters:

Name	Type	Description	Default
`in_kml`	`str`	The file path to the input KML.	required

Raises:

Type	Description
`FileNotFoundError`	The input KML could not be found.

Returns:

Name	Type	Description
`object`		ee.FeatureCollection

Source code in geemap/common.py

def kml_to_ee(in_kml: str, **kwargs):
    """Converts a KML to ee.FeatureCollection.

    Args:
        in_kml: The file path to the input KML.

    Raises:
        FileNotFoundError: The input KML could not be found.

    Returns:
        object: ee.FeatureCollection
    """
    warnings.filterwarnings("ignore")

    in_kml = os.path.abspath(in_kml)
    if not os.path.exists(in_kml):
        raise FileNotFoundError("The input KML could not be found.")

    out_json = os.path.join(os.getcwd(), "tmp.geojson")

    kml_to_geojson(in_kml, out_json, **kwargs)
    ee_object = coreutils.geojson_to_ee(out_json)
    os.remove(out_json)
    return ee_object

`kml_to_geojson(in_kml, out_geojson=None, **kwargs)` ¶

Converts a KML to GeoJSON.

Parameters:

Name	Type	Description	Default
`in_kml`	`str`	The file path to the input KML.	required
`out_geojson`	`str \| None`	The file path to the output GeoJSON. Defaults to None.	`None`

Raises:

Type	Description
`FileNotFoundError`	The input KML could not be found.
`TypeError`	The output must be a GeoJSON.

Source code in geemap/common.py

def kml_to_geojson(in_kml: str, out_geojson: str | None = None, **kwargs):
    """Converts a KML to GeoJSON.

    Args:
        in_kml: The file path to the input KML.
        out_geojson: The file path to the output GeoJSON. Defaults to None.

    Raises:
        FileNotFoundError: The input KML could not be found.
        TypeError: The output must be a GeoJSON.
    """
    import geopandas as gpd

    warnings.filterwarnings("ignore")

    in_kml = os.path.abspath(in_kml)
    if not os.path.exists(in_kml):
        raise FileNotFoundError("The input KML could not be found.")

    if out_geojson is not None:
        out_geojson = os.path.abspath(out_geojson)
        ext = os.path.splitext(out_geojson)[1].lower()
        if ext not in [".json", ".geojson"]:
            raise TypeError("The output file must be a GeoJSON.")

        out_dir = os.path.dirname(out_geojson)
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)

    gdf = gpd.read_file(in_kml, driver="KML", **kwargs)

    if out_geojson is not None:
        gdf.to_file(out_geojson, driver="GeoJSON", **kwargs)
    else:
        return gdf.__geo_interface__

`kml_to_shp(in_kml, out_shp, **kwargs)` ¶

Converts a KML to shapefile.

Parameters:

Name	Type	Description	Default
`in_kml`	`str`	The file path to the input KML.	required
`out_shp`	`str`	The file path to the output shapefile.	required

Raises:

Type	Description
`FileNotFoundError`	The input KML could not be found.
`TypeError`	The output must be a shapefile.

Source code in geemap/common.py

def kml_to_shp(in_kml, out_shp, **kwargs):
    """Converts a KML to shapefile.

    Args:
        in_kml (str): The file path to the input KML.
        out_shp (str): The file path to the output shapefile.

    Raises:
        FileNotFoundError: The input KML could not be found.
        TypeError: The output must be a shapefile.
    """
    import geopandas as gpd
    import fiona

    warnings.filterwarnings("ignore")

    in_kml = os.path.abspath(in_kml)
    if not os.path.exists(in_kml):
        raise FileNotFoundError("The input KML could not be found.")

    out_shp = os.path.abspath(out_shp)
    if not out_shp.endswith(".shp"):
        raise TypeError("The output must be a shapefile.")

    out_dir = os.path.dirname(out_shp)
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    df = gpd.read_file(in_kml, driver="KML", **kwargs)
    df.to_file(out_shp, **kwargs)

`kmz_to_ee(in_kmz, **kwargs)` ¶

Converts a KMZ to ee.FeatureCollection.

Parameters:

Name	Type	Description	Default
`in_kmz`	`str`	The file path to the input KMZ.	required

Raises:

Type	Description
`FileNotFoundError`	The input KMZ could not be found.

Returns:

Name	Type	Description
`object`		ee.FeatureCollection

Source code in geemap/common.py

def kmz_to_ee(in_kmz: str, **kwargs):
    """Converts a KMZ to ee.FeatureCollection.

    Args:
        in_kmz: The file path to the input KMZ.

    Raises:
        FileNotFoundError: The input KMZ could not be found.

    Returns:
        object: ee.FeatureCollection
    """
    in_kmz = os.path.abspath(in_kmz)
    if not os.path.exists(in_kmz):
        raise FileNotFoundError("The input KMZ could not be found.")

    out_dir = os.path.dirname(in_kmz)
    out_kml = os.path.join(out_dir, "doc.kml")
    with zipfile.ZipFile(in_kmz, "r") as zip_ref:
        zip_ref.extractall(out_dir)

    fc = kml_to_ee(out_kml, **kwargs)
    os.remove(out_kml)
    return fc

`landsat_scaling(image, thermal_bands=True, apply_fmask=False)` ¶

Apply scaling factors to a Landsat image.

Example https://developers.google.com/earth-engine/datasets/catalog/LANDSAT_LC09_C02_T1_L2

Parameters:

Name	Type	Description	Default
`image`	`Image`	The input Landsat image.	required
`thermal_bands`	`bool`	Whether to apply scaling to thermal bands. Defaults to True.	`True`
`apply_fmask`	`bool`	Whether to apply Fmask cloud mask. Defaults to False.	`False`

Returns:

Type	Description
`Image`	The scaled Landsat image.

Source code in geemap/common.py

def landsat_scaling(
    image, thermal_bands: bool = True, apply_fmask: bool = False
) -> ee.Image:
    """Apply scaling factors to a Landsat image.

    Example
        https://developers.google.com/earth-engine/datasets/catalog/LANDSAT_LC09_C02_T1_L2

    Args:
        image (ee.Image): The input Landsat image.
        thermal_bands: Whether to apply scaling to thermal bands. Defaults to True.
        apply_fmask: Whether to apply Fmask cloud mask. Defaults to False.

    Returns:
        The scaled Landsat image.
    """
    # Apply the scaling factors to the appropriate bands.
    opticalBands = image.select("SR_B.").multiply(0.0000275).add(-0.2)
    if thermal_bands:
        thermalBands = image.select("ST_B.*").multiply(0.00341802).add(149)

    if apply_fmask:
        # Replace the original bands with the scaled ones and apply the masks.
        # Bit 0 - Fill
        # Bit 1 - Dilated Cloud
        # Bit 2 - Cirrus
        # Bit 3 - Cloud
        # Bit 4 - Cloud Shadow
        qaMask = image.select("QA_PIXEL").bitwiseAnd(int("11111", 2)).eq(0)
        if thermal_bands:
            return (
                image.addBands(thermalBands, None, True)
                .addBands(opticalBands, None, True)
                .updateMask(qaMask)
            )
        else:
            return image.addBands(opticalBands, None, True).updateMask(qaMask)

    else:
        if thermal_bands:
            return image.addBands(thermalBands, None, True).addBands(
                opticalBands, None, True
            )
        else:
            return image.addBands(opticalBands, None, True)

landsat_timelapse(roi=None, out_gif=None, start_year=1984, end_year=None, start_date='06-10', end_date='09-20', bands=None, vis_params=None, dimensions=768, frames_per_second=5, crs='EPSG:3857', apply_fmask=True, nd_bands=None, nd_threshold=0, nd_palette=['black', 'blue'], overlay_data=None, overlay_color='black', overlay_width=1, overlay_opacity=1.0, frequency='year', date_format=None, 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, loop=0, mp4=False, fading=False, step=1) ¶

Generates a Landsat timelapse GIF image.

Adapted from https://emaprlab.users.earthengine.app/view/lt-gee-time-series-animator by Justin Braaten.

Parameters:

Name	Type	Description	Default
`roi`	`object`	Region of interest to create the timelapse.	`None`
`out_gif`	`str \| None`	File path to the output animated GIF.	`None`
`start_year`	`int`	Starting year for the timelapse.	`1984`
`end_year`	`int \| None`	Ending year for the timelapse. Defaults to the current year.	`None`
`start_date`	`str`	Starting date (month-day) each year for filtering ImageCollection.	`'06-10'`
`end_date`	`str`	Ending date (month-day) each year for filtering ImageCollection.	`'09-20'`
`bands`	`list`	Three bands selected from ['Blue', 'Green', 'Red', 'NIR', 'SWIR1', 'SWIR2', 'pixel_qa']. Defaults to ['NIR', 'Red', 'Green'].	`None`
`vis_params`	`dict`	Visualization parameters.	`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.	`768`
`frames_per_second`	`int`	Animation speed.	`5`
`crs`	`str`	The coordinate reference system to use.	`'EPSG:3857'`
`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`	`list`	The color palette to use for displaying the normalized difference band.	`['black', 'blue']`
`overlay_data`	`(int, str, list)`	Administrative boundary to be drawn on the timelapse.	`None`
`overlay_color`	`str`	Color for the overlay data. Can be any color name or hex color code.	`'black'`
`overlay_width`	`int`	Line width of the overlay.	`1`
`overlay_opacity`	`float`	Opacity of the overlay.	`1.0`
`frequency`	`str`	Frequency of the timelapse.	`'year'`
`date_format`	`str \| None`	Date format for the timelapse.	`None`
`title`	`str \| None`	The title of the timelapse.	`None`
`title_xy`	`tuple`	Lower left corner of the title. It can be formatted like this: (10, 10) or ('15%', '25%').	`('2%', '90%')`
`add_text`	`bool`	Whether to add animated text to the timelapse.	`True`
`title_xy`	`tuple`	Lower left corner of the text sequency. It can be formatted like this: (10, 10) or ('15%', '25%').	`('2%', '90%')`
`text_sequence`	`(int, str, list)`	Text to be drawn. It can be an integer number, a string, or a list of strings.	`None`
`font_type`	`str`	Font type.	`'arial.ttf'`
`font_size`	`int`	Font size.	`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').	`'white'`
`add_progress_bar`	`bool`	Whether to add a progress bar at the bottom of the GIF.	`True`
`progress_bar_color`	`str`	Color for the progress bar.	`'white'`
`progress_bar_height`	`int`	Height of the progress bar.	`5`
`loop`	`int`	Controls how many times the animation repeats. The 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.	`0`
`mp4`	`bool`	Whether to convert the GIF to MP4.	`False`
`fading`	`bool \| int`	If True, add fading effect to the timelapse. Defaults to no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).	`False`
`step`	`int`	Step size for the timelapse.	`1`

Returns:

Type	Description
`str`	File path to the output GIF image.

Source code in geemap/timelapse.py

def landsat_timelapse(
    roi=None,
    out_gif: str | None = None,
    start_year: int = 1984,
    end_year: int | None = None,
    start_date: str = "06-10",
    end_date: str = "09-20",
    bands: list[str] | None = None,
    vis_params=None,
    dimensions=768,
    frames_per_second: int = 5,
    crs: str = "EPSG:3857",
    apply_fmask: bool = True,
    nd_bands=None,
    nd_threshold: float = 0,
    nd_palette=["black", "blue"],
    overlay_data=None,
    overlay_color: str = "black",
    overlay_width: int = 1,
    overlay_opacity: float = 1.0,
    frequency: str = "year",
    date_format: str | None = None,
    title: str | None = None,
    title_xy=("2%", "90%"),
    add_text: bool = True,
    text_xy=("2%", "2%"),
    text_sequence=None,
    font_type: str = "arial.ttf",
    font_size: int = 20,
    font_color: str = "white",
    add_progress_bar: bool = True,
    progress_bar_color: str = "white",
    progress_bar_height: int = 5,
    loop: int = 0,
    mp4: bool = False,
    fading: bool | int = False,
    step: int = 1,
) -> str:
    """Generates a Landsat timelapse GIF image.

    Adapted from https://emaprlab.users.earthengine.app/view/lt-gee-time-series-animator by Justin Braaten.

    Args:
        roi (object, optional): Region of interest to create the timelapse.
        out_gif: File path to the output animated GIF.
        start_year: Starting year for the timelapse.
        end_year: Ending year for the timelapse. Defaults to the current year.
        start_date: Starting date (month-day) each year for filtering ImageCollection.
        end_date: Ending date (month-day) each year for filtering ImageCollection.
        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.
        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.
        frames_per_second: Animation speed.
        crs: The coordinate reference system to use.
        apply_fmask: 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: The threshold for extracting pixels from the normalized difference band.
        nd_palette (list, optional): The color palette to use for displaying the normalized difference band.
        overlay_data (int, str, list, optional): Administrative boundary to be drawn on the timelapse.
        overlay_color: Color for the overlay data. Can be any color name or hex color code.
        overlay_width: Line width of the overlay.
        overlay_opacity: Opacity of the overlay.
        frequency: Frequency of the timelapse.
        date_format: Date format for the timelapse.
        title: The title of the timelapse.
        title_xy (tuple, optional): Lower left corner of the title. It can be formatted like this: (10, 10) or ('15%', '25%').
        add_text: Whether to add animated text to the timelapse.
        title_xy (tuple, optional): Lower left corner of the text sequency. It can be formatted like this: (10, 10) or ('15%', '25%').
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer number, a string, or a list of strings.
        font_type: Font type.
        font_size: Font size.
        font_color: Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff').
        add_progress_bar: Whether to add a progress bar at the bottom of the GIF.
        progress_bar_color: Color for the progress bar.
        progress_bar_height: Height of the progress bar.
        loop: Controls how many times the animation repeats. The 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.
        mp4: Whether to convert the GIF to MP4.
        fading: If True, add fading effect to the timelapse. Defaults to no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).
        step: Step size for the timelapse.

    Returns:
        File path to the output GIF image.
    """
    bands = bands or ["NIR", "Red", "Green"]

    if roi is None:
        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, ee.FeatureCollection)):
        roi = roi.geometry()
    elif isinstance(roi, ee.Geometry):
        pass
    else:
        raise ValueError("The provided roi is invalid. It must be an ee.Geometry")

    if out_gif is None:
        out_gif = coreutils.temp_file_path(".gif")
    elif not out_gif.endswith(".gif"):
        raise ValueError("The output file must end with .gif")
    else:
        out_gif = os.path.abspath(out_gif)
    out_dir = os.path.dirname(out_gif)

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if end_year is None:
        end_year = get_current_year()

    allowed_bands = ["Blue", "Green", "Red", "NIR", "SWIR1", "SWIR2", "pixel_qa"]

    if len(bands) == 3 and all(x in allowed_bands for x in bands):
        pass
    else:
        raise Exception(
            "You can only select 3 bands from the following: {}".format(
                ", ".join(allowed_bands)
            )
        )

    if nd_bands is not None:
        if len(nd_bands) == 2 and all(x in allowed_bands[:-1] for x in nd_bands):
            pass
        else:
            raise Exception(
                "You can only select two bands from the following: {}".format(
                    ", ".join(allowed_bands[:-1])
                )
            )

    if vis_params is None:
        vis_params = {}
        vis_params["bands"] = bands
        vis_params["min"] = 0
        vis_params["max"] = 0.4
        vis_params["gamma"] = [1, 1, 1]
    raw_col = landsat_timeseries(
        roi,
        start_year,
        end_year,
        start_date,
        end_date,
        apply_fmask,
        frequency,
        date_format,
        step,
    )

    # pytype: disable=attribute-error
    col = raw_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"),
            }
        )
    )
    # pytype: enable=attribute-error
    if overlay_data is not None:
        col = add_overlay(
            col, overlay_data, overlay_color, overlay_width, overlay_opacity
        )

    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": ["vis-red", "vis-green", "vis-blue"],
            },
            dimensions=dimensions,
            names=names,
        )
        make_gif(
            names,
            out_gif,
            fps=frames_per_second,
            loop=loop,
            mp4=False,
            clean_up=True,
        )

    else:
        video_args = vis_params.copy()
        video_args["dimensions"] = dimensions
        video_args["region"] = roi
        video_args["framesPerSecond"] = frames_per_second
        video_args["crs"] = crs
        video_args["bands"] = ["vis-red", "vis-green", "vis-blue"]
        video_args["min"] = 0
        video_args["max"] = 255

        download_ee_video(col, video_args, out_gif)

    if os.path.exists(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 nd_bands is not None:
        nd_images = landsat_ts_norm_diff(
            raw_col, bands=nd_bands, threshold=nd_threshold
        )
        out_nd_gif = out_gif.replace(".gif", "_nd.gif")
        landsat_ts_norm_diff_gif(
            nd_images,
            out_gif=out_nd_gif,
            vis_params=None,
            palette=nd_palette,
            dimensions=dimensions,
            frames_per_second=frames_per_second,
        )

    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

landsat_timelapse_legacy(roi=None, out_gif=None, start_year=1984, end_year=None, start_date='06-10', end_date='09-20', bands=None, vis_params=None, dimensions=768, frames_per_second=5, crs='EPSG:3857', apply_fmask=True, nd_bands=None, nd_threshold=0, nd_palette=['black', 'blue'], overlay_data=None, overlay_color='black', overlay_width=1, overlay_opacity=1.0, frequency='year', date_format=None, 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, loop=0, mp4=False, fading=False) ¶

Generates a Landsat timelapse GIF image.

Adapted from https://emaprlab.users.earthengine.app/view/lt-gee-time-series-animator by Justin Braaten.

Parameters:

Name	Type	Description	Default
`roi`	`object`	Region of interest to create the timelapse.	`None`
`out_gif`		File path to the output animated GIF.	`None`
`start_year`	`int`	Starting year for the timelapse.	`1984`
`end_year`	`int \| None`	Ending year for the timelapse. Defaults to the current year.	`None`
`start_date`	`str`	Starting date (month-day) each year for filtering ImageCollection.	`'06-10'`
`end_date`	`str`	Ending date (month-day) each year for filtering ImageCollection.	`'09-20'`
`bands`	`list`	Three bands selected from ['Blue', 'Green', 'Red', 'NIR', 'SWIR1', 'SWIR2', 'pixel_qa']. Defaults to ['NIR', 'Red', 'Green'].	`None`
`vis_params`	`dict`	Visualization parameters.	`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.	`768`
`frames_per_second`	`int`	Animation speed.	`5`
`crs`	`str`	The coordinate reference system to use.	`'EPSG:3857'`
`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`	`list`	The color palette to use for displaying the normalized difference band.	`['black', 'blue']`
`overlay_data`	`(int, str, list)`	Administrative boundary to be drawn on the timelapse.	`None`
`overlay_color`	`str`	Color for the overlay data. Can be any color name or hex color code.	`'black'`
`overlay_width`	`int`	Line width of the overlay.	`1`
`overlay_opacity`	`float`	Opacity of the overlay.	`1.0`
`frequency`	`str`	Frequency of the timelapse.	`'year'`
`date_format`	`str \| None`	Date format for the timelapse.	`None`
`title`	`str \| None`	The title of the timelapse.	`None`
`title_xy`	`tuple`	Lower left corner of the title. It can be formatted like this: (10, 10) or ('15%', '25%').	`('2%', '90%')`
`add_text`	`bool`	Whether to add animated text to the timelapse.	`True`
`title_xy`	`tuple`	Lower left corner of the text sequency. It can be formatted like this: (10, 10) or ('15%', '25%').	`('2%', '90%')`
`text_sequence`	`(int, str, list)`	Text to be drawn. It can be an integer number, a string, or a list of strings.	`None`
`font_type`	`str`	Font type.	`'arial.ttf'`
`font_size`	`int`	Font size.	`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').	`'white'`
`add_progress_bar`	`bool`	Whether to add a progress bar at the bottom of the GIF.	`True`
`progress_bar_color`	`str`	Color for the progress bar.	`'white'`
`progress_bar_height`	`int`	Height of the progress bar.	`5`
`loop`	`int`	Controls how many times the animation repeats. 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.	`0`
`mp4`	`bool`	Whether to convert the GIF to MP4.	`False`
`fading`	`bool \| int`	If True, add fading effect to the timelapse. Defaults to no fading. To add fading effect, set it to True (1 second fading duration) or to an integer value (fading duration).	`False`

Returns:

Type	Description
`str`	File path to the output GIF image.

Source code in geemap/timelapse.py

def landsat_timelapse_legacy(
    roi=None,
    out_gif=None,
    start_year: int = 1984,
    end_year: int | None = None,
    start_date: str = "06-10",
    

foliumap module¶

CustomControl ¶

__init__(html, position='bottomleft') ¶

FloatText ¶

Map ¶

add_basemap(basemap='HYBRID', show=True, **kwargs) ¶

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

add_circle_markers_from_xy(data, x='longitude', y='latitude', radius=10, popup=None, tooltip=None, min_width=100, max_width=200, **kwargs) ¶

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

add_colorbar(vis_params, index=None, label='', categorical=False, step=None, background_color=None, **kwargs) ¶

add_colormap(width=4.0, height=0.3, vmin=0.0, vmax=1.0, palette=None, vis_params=None, cmap='gray', discrete=False, label=None, label_size=10, label_weight='normal', tick_size=8, bg_color='white', orientation='horizontal', dpi='figure', transparent=False, position=(70, 5), **kwargs) ¶

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, style_function=None, highlight_function=None, layer_name='Untitled', info_mode='on_hover', encoding='utf-8', **kwargs) ¶

add_gdf(gdf, layer_name='Untitled', zoom_to_layer=True, info_mode='on_hover', fields=None, **kwargs) ¶

add_gdf_from_postgis(sql, con, layer_name='Untitled', zoom_to_layer=True, **kwargs) ¶

add_geojson(in_geojson, layer_name='Untitled', encoding='utf-8', info_mode='on_hover', fields=None, **kwargs) ¶

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

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

add_image(image, position=(0, 0), **kwargs) ¶

add_kml(in_kml, layer_name='Untitled', info_mode='on_hover', fields=None, **kwargs) ¶

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) ¶

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

add_layer_control() ¶

add_legend(title='Legend', labels=None, colors=None, legend_dict=None, builtin_legend=None, opacity=1.0, position='bottomright', draggable=True, style=None) ¶

add_marker(location, popup=None, tooltip=None, icon=None, draggable=False, **kwargs) ¶

add_markers_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Markers', icon=None, icon_shape='circle-dot', border_width=3, border_color='#0000ff', **kwargs) ¶

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) ¶

add_osm(query, layer_name='Untitled', which_result=None, by_osmid=False, to_ee=False, geodesic=True, **kwargs) ¶

add_osm_from_address(address, tags, dist=1000, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover') ¶

add_osm_from_bbox(north, south, east, west, tags, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover') ¶

add_osm_from_geocode(query, which_result=None, by_osmid=False, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover') ¶

add_osm_from_place(query, tags, which_result=None, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover') ¶

add_osm_from_point(center_point, tags, dist=1000, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover') ¶

add_osm_from_polygon(polygon, tags, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover') ¶

add_planet_by_month(year=2016, month=1, name=None, api_key=None, token_name='PLANET_API_KEY') ¶

add_planet_by_quarter(year=2016, quarter=1, name=None, api_key=None, token_name='PLANET_API_KEY') ¶

add_points_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Marker Cluster', color_column=None, marker_colors=None, icon_colors=['white'], icon_names=['info'], angle=0, prefix='fa', add_legend=True, max_cluster_radius=80, **kwargs) ¶

add_raster(source, indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Raster', array_args=None, **kwargs) ¶

add_remote_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name=None, **kwargs) ¶

add_shapefile(in_shp, layer_name='Untitled', **kwargs) ¶

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) ¶

add_styled_vector(ee_object, column, palette, layer_name='Untitled', shown=True, opacity=1.0, **kwargs) ¶

add_text(text, fontsize=20, fontcolor='black', bold=False, padding='5px', background=True, bg_color='white', border_radius='5px', position='bottomright', **kwargs) ¶

add_tile_layer(tiles='OpenStreetMap', name='Untitled', attribution='.', overlay=True, control=True, shown=True, opacity=1.0, API_key=None, **kwargs) ¶

add_widget(content, position='bottomright', **kwargs) ¶

add_wms_layer(url, layers, name=None, attribution='', overlay=True, control=True, shown=True, format='image/png', transparent=True, version='1.1.1', styles='', **kwargs) ¶

add_xyz_service(provider, **kwargs) ¶

basemap_demo() ¶

center_object(ee_object, zoom=None, max_error=0.001) ¶

publish(name='Folium Map', description='', source_url='', tags=None, source_file=None, open=True, formatting=None, token=None, **kwargs) ¶

remove_labels(**kwargs) ¶

setOptions(mapTypeId='HYBRID', styles=None, types=None) ¶

set_center(lon, lat, zoom=10) ¶

set_control_visibility(layerControl=True, fullscreenControl=True, latLngPopup=True) ¶

set_plot_options(**kwargs) ¶

split_map(left_layer='TERRAIN', right_layer='OpenTopoMap', left_args=None, right_args=None, left_label=None, right_label=None, left_position='bottomleft', right_position='bottomright', **kwargs) ¶

st_draw_features(st_component) ¶

st_fit_bounds() ¶

st_last_click(st_component) ¶

st_last_draw(st_component) ¶

st_map_bounds(st_component) ¶

st_map_center(st_component) ¶

to_gradio(width='100%', height='500px', **kwargs) ¶

to_html(filename=None, **kwargs) ¶

to_streamlit(width=None, height=600, scrolling=False, add_layer_control=True, bidirectional=False, **kwargs) ¶

zoom_to_bounds(bounds) ¶

zoom_to_gdf(gdf) ¶

PlanetaryComputerEndpoint ¶

__init__(endpoint='https://planetarycomputer.microsoft.com/api/data/v1', name='item', TileMatrixSetId='WebMercatorQuad') ¶

SideBySideLayers ¶

SplitControl ¶

TitilerEndpoint ¶

__init__(endpoint='https://giswqs-titiler-endpoint.hf.space', name='stac', TileMatrixSetId='WebMercatorQuad') ¶

add_crs(filename, epsg) ¶

add_image_to_gif(in_gif, out_gif, in_image, xy=None, image_size=(80, 80), circle_mask=False) ¶

add_overlay(collection, overlay_data, color='black', width=1, opacity=1.0, region=None) ¶

add_progress_bar_to_gif(in_gif, out_gif, progress_bar_color='blue', progress_bar_height=5, duration=100, loop=0) ¶

add_sample_markers_to_gif(in_gif, out_gif, sample_points, marker_colors, marker_size, marker_style, roi_bounds, gif_dimensions) ¶

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) ¶

adjust_longitude(in_fc) ¶

annual_NAIP(year, region) ¶

`CustomControl` ¶

`init(html, position='bottomleft')` ¶

`FloatText` ¶

`Map` ¶

`add_basemap(basemap='HYBRID', show=True, **kwargs)` ¶

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

`add_circle_markers_from_xy(data, x='longitude', y='latitude', radius=10, popup=None, tooltip=None, min_width=100, max_width=200, **kwargs)` ¶

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

`add_colorbar(vis_params, index=None, label='', categorical=False, step=None, background_color=None, **kwargs)` ¶

`add_colormap(width=4.0, height=0.3, vmin=0.0, vmax=1.0, palette=None, vis_params=None, cmap='gray', discrete=False, label=None, label_size=10, label_weight='normal', tick_size=8, bg_color='white', orientation='horizontal', dpi='figure', transparent=False, position=(70, 5), **kwargs)` ¶

`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, style_function=None, highlight_function=None, layer_name='Untitled', info_mode='on_hover', encoding='utf-8', **kwargs)` ¶

`add_gdf(gdf, layer_name='Untitled', zoom_to_layer=True, info_mode='on_hover', fields=None, **kwargs)` ¶

`add_gdf_from_postgis(sql, con, layer_name='Untitled', zoom_to_layer=True, **kwargs)` ¶

`add_geojson(in_geojson, layer_name='Untitled', encoding='utf-8', info_mode='on_hover', fields=None, **kwargs)` ¶

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

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

`add_image(image, position=(0, 0), **kwargs)` ¶

`add_kml(in_kml, layer_name='Untitled', info_mode='on_hover', fields=None, **kwargs)` ¶

`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)` ¶

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

`add_layer_control()` ¶

`add_legend(title='Legend', labels=None, colors=None, legend_dict=None, builtin_legend=None, opacity=1.0, position='bottomright', draggable=True, style=None)` ¶

`add_marker(location, popup=None, tooltip=None, icon=None, draggable=False, **kwargs)` ¶

`add_markers_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Markers', icon=None, icon_shape='circle-dot', border_width=3, border_color='#0000ff', **kwargs)` ¶

`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)` ¶

`add_osm(query, layer_name='Untitled', which_result=None, by_osmid=False, to_ee=False, geodesic=True, **kwargs)` ¶

`add_osm_from_address(address, tags, dist=1000, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover')` ¶

`add_osm_from_bbox(north, south, east, west, tags, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover')` ¶

`add_osm_from_geocode(query, which_result=None, by_osmid=False, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover')` ¶

`add_osm_from_place(query, tags, which_result=None, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover')` ¶

`add_osm_from_point(center_point, tags, dist=1000, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover')` ¶

`add_osm_from_polygon(polygon, tags, layer_name='Untitled', style=None, hover_style=None, style_callback=None, fill_colors=['black'], info_mode='on_hover')` ¶

`add_planet_by_month(year=2016, month=1, name=None, api_key=None, token_name='PLANET_API_KEY')` ¶

`add_planet_by_quarter(year=2016, quarter=1, name=None, api_key=None, token_name='PLANET_API_KEY')` ¶

`add_points_from_xy(data, x='longitude', y='latitude', popup=None, min_width=100, max_width=200, layer_name='Marker Cluster', color_column=None, marker_colors=None, icon_colors=['white'], icon_names=['info'], angle=0, prefix='fa', add_legend=True, max_cluster_radius=80, **kwargs)` ¶

`add_raster(source, indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Raster', array_args=None, **kwargs)` ¶

`add_remote_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name=None, **kwargs)` ¶

`add_shapefile(in_shp, layer_name='Untitled', **kwargs)` ¶

`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)` ¶

`add_styled_vector(ee_object, column, palette, layer_name='Untitled', shown=True, opacity=1.0, **kwargs)` ¶

`add_text(text, fontsize=20, fontcolor='black', bold=False, padding='5px', background=True, bg_color='white', border_radius='5px', position='bottomright', **kwargs)` ¶

`add_tile_layer(tiles='OpenStreetMap', name='Untitled', attribution='.', overlay=True, control=True, shown=True, opacity=1.0, API_key=None, **kwargs)` ¶

`add_widget(content, position='bottomright', **kwargs)` ¶

`add_wms_layer(url, layers, name=None, attribution='', overlay=True, control=True, shown=True, format='image/png', transparent=True, version='1.1.1', styles='', **kwargs)` ¶

`add_xyz_service(provider, **kwargs)` ¶

`basemap_demo()` ¶

`center_object(ee_object, zoom=None, max_error=0.001)` ¶

`publish(name='Folium Map', description='', source_url='', tags=None, source_file=None, open=True, formatting=None, token=None, **kwargs)` ¶

`remove_labels(**kwargs)` ¶

`setOptions(mapTypeId='HYBRID', styles=None, types=None)` ¶

`set_center(lon, lat, zoom=10)` ¶

`set_control_visibility(layerControl=True, fullscreenControl=True, latLngPopup=True)` ¶

`set_plot_options(**kwargs)` ¶

`split_map(left_layer='TERRAIN', right_layer='OpenTopoMap', left_args=None, right_args=None, left_label=None, right_label=None, left_position='bottomleft', right_position='bottomright', **kwargs)` ¶

`st_draw_features(st_component)` ¶

`st_fit_bounds()` ¶

`st_last_click(st_component)` ¶

`st_last_draw(st_component)` ¶

`st_map_bounds(st_component)` ¶

`st_map_center(st_component)` ¶

`to_gradio(width='100%', height='500px', **kwargs)` ¶

`to_html(filename=None, **kwargs)` ¶

`to_streamlit(width=None, height=600, scrolling=False, add_layer_control=True, bidirectional=False, **kwargs)` ¶

`zoom_to_bounds(bounds)` ¶

`zoom_to_gdf(gdf)` ¶

`PlanetaryComputerEndpoint` ¶

`init(endpoint='https://planetarycomputer.microsoft.com/api/data/v1', name='item', TileMatrixSetId='WebMercatorQuad')` ¶

`SideBySideLayers` ¶

`SplitControl` ¶

`TitilerEndpoint` ¶

`init(endpoint='https://giswqs-titiler-endpoint.hf.space', name='stac', TileMatrixSetId='WebMercatorQuad')` ¶

`add_crs(filename, epsg)` ¶

`add_image_to_gif(in_gif, out_gif, in_image, xy=None, image_size=(80, 80), circle_mask=False)` ¶

`add_overlay(collection, overlay_data, color='black', width=1, opacity=1.0, region=None)` ¶

`add_progress_bar_to_gif(in_gif, out_gif, progress_bar_color='blue', progress_bar_height=5, duration=100, loop=0)` ¶

`add_sample_markers_to_gif(in_gif, out_gif, sample_points, marker_colors, marker_size, marker_style, roi_bounds, gif_dimensions)` ¶

`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)` ¶

`adjust_longitude(in_fc)` ¶

`annual_NAIP(year, region)` ¶

`api_docs()` ¶