leafmap module

Main module.

GoogleMapsTileProvider

Bases: TileProvider

Google Maps TileProvider.

Source code in leafmap/common.py

class GoogleMapsTileProvider(xyzservices.TileProvider):
    """Google Maps TileProvider."""

    MAP_TYPE_CONFIG = {
        "roadmap": {"mapType": "roadmap"},
        "satellite": {"mapType": "satellite"},
        "terrain": {
            "mapType": "terrain",
            "layerTypes": ["layerRoadmap"],
        },
        "hybrid": {
            "mapType": "satellite",
            "layerTypes": ["layerRoadmap"],
        },
    }

    def __init__(
        self,
        map_type: str = "roadmap",
        language: str = "en-Us",
        region: str = "US",
        api_key: Optional[str] = None,
        **kwargs: Any,
    ):
        """
        Generates Google Map tiles using the provided parameters. To get an API key
            and enable Map Tiles API, visit
            https://developers.google.com/maps/get-started#create-project.
            You can set the API key using the environment variable
            `GOOGLE_MAPS_API_KEY` or by passing it as an argument.

        Args:
            map_type (str, optional): The type of map to generate. Options are
                'roadmap', 'satellite', 'terrain', 'hybrid', 'traffic', 'streetview'.
                Defaults to 'roadmap'.
            language (str, optional): An IETF language tag that specifies the
                language used to display information on the tiles, such as 'zh-Cn'.
                Defaults to 'en-Us'.
            region (str, optional): A Common Locale Data Repository region
                identifier (two uppercase letters) that represents the physical
                location of the user. Defaults to 'US'.
            api_key (str, optional): The API key to use for the Google Maps API.
                If not provided, it will try to get it from the environment or
                Colab user data with the key 'GOOGLE_MAPS_API_KEY'. Defaults to None.
            **kwargs (Any): Additional parameters to pass to the map generation. For more
                info, visit https://bit.ly/3UhbZKU

        Raises:
            ValueError: If the API key is not provided and cannot be found in the
                environment or Colab user data.
            ValueError: If the map_type is not one of the allowed types.

        Example:
            >>> from leafmap.basemaps import GoogleMapsTileProvider
            >>> m = leafmap.Map()
            >>> basemap = GoogleMapsTileProvider(map_type='roadmap',
                language="en-Us", region="US", scale="scaleFactor2x", highDpi=True)
            >>> m.add_basemap(basemap)
        """

        key = api_key or get_google_maps_api_key()
        if key is None:
            raise ValueError(
                "API key is required to access Google Maps API. To get an API "
                "key and enable Map Tiles API, visit "
                "https://developers.google.com/maps/get-started#create-project"
            )

        if map_type not in self.MAP_TYPE_CONFIG:
            raise ValueError(f"map_type must be one of: {self.MAP_TYPE_CONFIG.keys()}")

        request_url = f"https://tile.googleapis.com/v1/createSession?key={key}"
        response = requests.post(
            url=request_url,
            headers={"Content-Type": "application/json"},
            json={
                **self.MAP_TYPE_CONFIG[map_type],
                "language": language,
                "region": region,
                **kwargs,
            },
            timeout=3,
        )

        if response.status_code == requests.codes.ok:
            json = response.json()
            map_name = map_type.capitalize()
            super().__init__(
                {
                    "url": f"https://tile.googleapis.com/v1/2dtiles/{{z}}/{{x}}/{{y}}?session={json['session']}&key={{accessToken}}",
                    "attribution": f"© Google {map_name}",
                    "accessToken": key,
                    "name": f"Google.{map_name}",
                    "ext": json["imageFormat"],
                    "tileSize": json["tileWidth"],
                }
            )
            self["url"] = self.build_url()
        else:
            raise RuntimeError(
                f"Error creating a Maps API session:\n{response.json()}."
            )

__init__(map_type='roadmap', language='en-Us', region='US', api_key=None, **kwargs)

Generates Google Map tiles using the provided parameters. To get an API key and enable Map Tiles API, visit https://developers.google.com/maps/get-started#create-project. You can set the API key using the environment variable GOOGLE_MAPS_API_KEY or by passing it as an argument.

Parameters:

Name	Type	Description	Default
map_type	str	The type of map to generate. Options are 'roadmap', 'satellite', 'terrain', 'hybrid', 'traffic', 'streetview'. Defaults to 'roadmap'.	'roadmap'
language	str	An IETF language tag that specifies the language used to display information on the tiles, such as 'zh-Cn'. Defaults to 'en-Us'.	'en-Us'
region	str	A Common Locale Data Repository region identifier (two uppercase letters) that represents the physical location of the user. Defaults to 'US'.	'US'
api_key	str	The API key to use for the Google Maps API. If not provided, it will try to get it from the environment or Colab user data with the key 'GOOGLE_MAPS_API_KEY'. Defaults to None.	None
**kwargs	Any	Additional parameters to pass to the map generation. For more info, visit https://bit.ly/3UhbZKU	{}

Raises:

Type	Description
ValueError	If the API key is not provided and cannot be found in the environment or Colab user data.
ValueError	If the map_type is not one of the allowed types.

Example

from leafmap.basemaps import GoogleMapsTileProvider m = leafmap.Map() basemap = GoogleMapsTileProvider(map_type='roadmap', language="en-Us", region="US", scale="scaleFactor2x", highDpi=True) m.add_basemap(basemap)

Source code in leafmap/common.py

def __init__(
    self,
    map_type: str = "roadmap",
    language: str = "en-Us",
    region: str = "US",
    api_key: Optional[str] = None,
    **kwargs: Any,
):
    """
    Generates Google Map tiles using the provided parameters. To get an API key
        and enable Map Tiles API, visit
        https://developers.google.com/maps/get-started#create-project.
        You can set the API key using the environment variable
        `GOOGLE_MAPS_API_KEY` or by passing it as an argument.

    Args:
        map_type (str, optional): The type of map to generate. Options are
            'roadmap', 'satellite', 'terrain', 'hybrid', 'traffic', 'streetview'.
            Defaults to 'roadmap'.
        language (str, optional): An IETF language tag that specifies the
            language used to display information on the tiles, such as 'zh-Cn'.
            Defaults to 'en-Us'.
        region (str, optional): A Common Locale Data Repository region
            identifier (two uppercase letters) that represents the physical
            location of the user. Defaults to 'US'.
        api_key (str, optional): The API key to use for the Google Maps API.
            If not provided, it will try to get it from the environment or
            Colab user data with the key 'GOOGLE_MAPS_API_KEY'. Defaults to None.
        **kwargs (Any): Additional parameters to pass to the map generation. For more
            info, visit https://bit.ly/3UhbZKU

    Raises:
        ValueError: If the API key is not provided and cannot be found in the
            environment or Colab user data.
        ValueError: If the map_type is not one of the allowed types.

    Example:
        >>> from leafmap.basemaps import GoogleMapsTileProvider
        >>> m = leafmap.Map()
        >>> basemap = GoogleMapsTileProvider(map_type='roadmap',
            language="en-Us", region="US", scale="scaleFactor2x", highDpi=True)
        >>> m.add_basemap(basemap)
    """

    key = api_key or get_google_maps_api_key()
    if key is None:
        raise ValueError(
            "API key is required to access Google Maps API. To get an API "
            "key and enable Map Tiles API, visit "
            "https://developers.google.com/maps/get-started#create-project"
        )

    if map_type not in self.MAP_TYPE_CONFIG:
        raise ValueError(f"map_type must be one of: {self.MAP_TYPE_CONFIG.keys()}")

    request_url = f"https://tile.googleapis.com/v1/createSession?key={key}"
    response = requests.post(
        url=request_url,
        headers={"Content-Type": "application/json"},
        json={
            **self.MAP_TYPE_CONFIG[map_type],
            "language": language,
            "region": region,
            **kwargs,
        },
        timeout=3,
    )

    if response.status_code == requests.codes.ok:
        json = response.json()
        map_name = map_type.capitalize()
        super().__init__(
            {
                "url": f"https://tile.googleapis.com/v1/2dtiles/{{z}}/{{x}}/{{y}}?session={json['session']}&key={{accessToken}}",
                "attribution": f"© Google {map_name}",
                "accessToken": key,
                "name": f"Google.{map_name}",
                "ext": json["imageFormat"],
                "tileSize": json["tileWidth"],
            }
        )
        self["url"] = self.build_url()
    else:
        raise RuntimeError(
            f"Error creating a Maps API session:\n{response.json()}."
        )

ImageOverlay

Bases: ImageOverlay

ImageOverlay class.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

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

        from PIL import Image, ImageSequence

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

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

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

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

        super().__init__(**kwargs)

Map

Bases: Map

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

Returns:

Name	Type	Description
object		ipyleaflet map object.

Source code in leafmap/leafmap.py

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

    Returns:
        object: ipyleaflet map object.
    """

    @property
    def _layer_editor(self) -> Optional[map_widgets.LayerEditor]:
        return self._find_widget_of_type(map_widgets.LayerEditor)

    def __init__(self, **kwargs):
        if "center" not in kwargs:
            kwargs["center"] = [20, 0]

        if "zoom" not in kwargs:
            kwargs["zoom"] = 2

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

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

        if "basemap" in kwargs:
            if isinstance(kwargs["basemap"], str):
                kwargs["basemap"] = get_basemap(kwargs["basemap"])

        super().__init__(**kwargs)
        self.baseclass = "ipyleaflet"
        self.toolbar = None
        self.toolbar_button = None
        self.tool_output = None
        self.tool_output_ctrl = None
        self.layer_control = None
        self.draw_control = None
        self.search_control = None
        self.user_roi = None
        self.user_rois = None
        self.draw_features = []
        self.api_keys = {}
        self.geojson_layers = []
        self.edit_mode = False
        self.edit_props = []
        self._layer_manager_widget = widgets.VBox()

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

        if "height" not in kwargs:
            self.layout.height = "600px"
        else:
            if isinstance(kwargs["height"], int):
                kwargs["height"] = str(kwargs["height"]) + "px"
            self.layout.height = kwargs["height"]
        if "width" in kwargs:
            if isinstance(kwargs["width"], int):
                kwargs["width"] = str(kwargs["width"]) + "px"
            self.layout.width = kwargs["width"]

        if "layers_control" not in kwargs:
            kwargs["layers_control"] = False
        if kwargs["layers_control"]:
            self.add(ipyleaflet.LayersControl(position="topright"))

        if "fullscreen_control" not in kwargs:
            kwargs["fullscreen_control"] = True
        if kwargs["fullscreen_control"]:
            self.add(ipyleaflet.FullScreenControl())

        if "search_control" not in kwargs:
            kwargs["search_control"] = False
        if kwargs["search_control"]:
            url = "https://nominatim.openstreetmap.org/search?format=json&q={s}"
            search_control = ipyleaflet.SearchControl(
                position="topleft",
                url=url,
                zoom=12,
                marker=None,
            )
            self.add(search_control)
            self.search_control = search_control

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

        if "repeat_mode" not in kwargs:
            repeat_mode = False
        else:
            repeat_mode = kwargs["repeat_mode"]
            kwargs.pop("repeat_mode")

        if kwargs["draw_control"]:
            draw_control = ipyleaflet.DrawControl(
                polyline={"repeatMode": repeat_mode},
                polygon={"repeatMode": repeat_mode},
                marker={
                    "shapeOptions": {"color": "#3388ff"},
                    "repeatMode": repeat_mode,
                },
                rectangle={
                    "shapeOptions": {"color": "#3388ff"},
                    "repeatMode": repeat_mode,
                },
                circle={
                    "shapeOptions": {"color": "#3388ff"},
                    "repeatMode": repeat_mode,
                },
                # circlemarker={"repeatMode": repeat_mode},
                edit=True,
                remove=True,
                position="topleft",
            )
            draw_control.circlemarker = {}
            self.add(draw_control)
            self.draw_control = draw_control

            def handle_draw(_, action, geo_json):
                if "style" in geo_json["properties"]:
                    del geo_json["properties"]["style"]
                self.user_roi = geo_json

                if action in ["created", "edited"]:
                    # feature = {
                    #     "type": "Feature",
                    #     "geometry": geo_json["geometry"],
                    # }
                    self.draw_features.append(geo_json)

                elif action == "deleted":
                    geometries = [
                        feature["geometry"] for feature in self.draw_control.data
                    ]
                    for geom in geometries:
                        if geom == geo_json["geometry"]:
                            geometries.remove(geom)
                    for feature in self.draw_features:
                        if feature["geometry"] not in geometries:
                            self.draw_features.remove(feature)

                if self.edit_mode:
                    import ipysheet

                    with self.edit_output:
                        self.edit_output.outputs = ()
                        self.edit_output.clear_output()
                        self.edit_sheet = ipysheet.from_dataframe(
                            self.get_draw_props(n=self.num_attributes, return_df=True)
                        )
                        self.edit_output.append_display_data(self.edit_sheet)

                self.user_rois = {
                    "type": "FeatureCollection",
                    "features": self.draw_features,
                }

            draw_control.on_draw(handle_draw)

        if "measure_control" not in kwargs:
            kwargs["measure_control"] = False
        if kwargs["measure_control"]:
            self.add(ipyleaflet.MeasureControl(position="topleft"))

        if "scale_control" not in kwargs:
            kwargs["scale_control"] = True
        if kwargs["scale_control"]:
            self.add(ipyleaflet.ScaleControl(position="bottomleft"))

        self.layers[0].name = "OpenStreetMap"

        if "toolbar_control" not in kwargs:
            kwargs["toolbar_control"] = True
        if kwargs["toolbar_control"]:
            from .toolbar import main_toolbar

            main_toolbar(self)

        if "use_voila" not in kwargs:
            kwargs["use_voila"] = False

        if "catalog_source" in kwargs:
            self.set_catalog_source(kwargs["catalog_source"])

    def add(self, obj, index=None, **kwargs) -> None:
        """Adds a layer to the map.

        Args:
            layer (object): The layer to add to the map.
            index (int, optional): The index at which to add the layer. Defaults to None.
        """
        if isinstance(obj, str):
            if obj in basemaps.keys():
                obj = get_basemap(obj)
            else:
                if obj == "nasa_earth_data":
                    from .toolbar import nasa_data_gui

                    nasa_data_gui(self, **kwargs)
                elif obj == "NASA_OPERA":
                    from .toolbar import nasa_opera_gui

                    nasa_opera_gui(self, **kwargs)
                elif obj == "inspector":
                    from .toolbar import inspector_gui

                    inspector_gui(self, **kwargs)

                elif obj == "stac":
                    self.add_stac_gui(**kwargs)
                elif obj == "basemap":
                    self.add_basemap_gui(**kwargs)
                elif obj == "inspector":
                    self.add_inspector_gui(**kwargs)
                elif obj == "layer_manager":
                    self.add_layer_manager(**kwargs)
                elif obj == "oam":
                    self.add_oam_gui(**kwargs)
                return

        super().add(obj, index=index)

        if hasattr(self, "_layer_manager_widget"):
            self.update_layer_manager()

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

        Args:
            lon (float): The longitude of the center, in degrees.
            lat (float): The latitude of the center, in degrees.
            zoom (int, optional): The zoom level, from 1 to 24. Defaults to None.
        """
        self.center = (lat, lon)
        if zoom is not None:
            self.zoom = zoom

    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 ipyleaflet fit_bounds method takes lat/lon bounds in the form [[south, west], [north, east]].
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

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

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

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

        Returns:
            float: Map resolution in meters.
        """
        import math

        zoom_level = self.zoom
        # Reference: https://blogs.bing.com/maps/2006/02/25/map-control-zoom-levels-gt-resolution
        resolution = 156543.04 * math.cos(0) / math.pow(2, zoom_level)
        return resolution

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

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

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

        return layer_names

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

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

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

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

        Args:
            basemap (str, optional): Can be one of string from basemaps. Defaults to 'HYBRID'.
            visible (bool, optional): Whether the basemap is visible or not. Defaults to True.
            **kwargs: Keyword arguments for the TileLayer.
        """
        import xyzservices

        try:
            layer_names = self.get_layer_names()

            map_dict = {
                "ROADMAP": "Google Maps",
                "SATELLITE": "Google Satellite",
                "TERRAIN": "Google Terrain",
                "HYBRID": "Google Hybrid",
            }

            if isinstance(basemap, str):
                if basemap.upper() in map_dict:
                    layer = common.get_google_map(basemap.upper(), **kwargs)
                    layer.visible = show
                    self.add(layer)
                    return

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

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

    def find_layer(self, name):
        """Finds layer by name

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

        Returns:
            object: ipyleaflet layer object.
        """
        layers = self.layers

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

    def find_layer_index(self, name) -> int:
        """Finds layer index by name

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

        Returns:
            int: Index of the layer with the specified name
        """
        layers = self.layers

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

        return -1

    def add_layer(self, layer) -> None:
        """Adds a layer to the map.

        Args:
            layer (ipyleaflet layer): The layer to be added.
        """
        existing_layer = self.find_layer(layer.name)
        if existing_layer is not None:
            self.remove_layer(existing_layer)
        super().add(layer)

    def add_ee_layer(
        self,
        ee_object=None,
        vis_params={},
        asset_id: str = None,
        name: str = None,
        attribution: str = "Google Earth Engine",
        shown: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """
        Adds a Google Earth Engine tile layer to the map based on the tile layer URL from
            https://github.com/opengeos/ee-tile-layers/blob/main/datasets.tsv.

        Args:
            ee_object (object): The Earth Engine object to display.
            vis_params (dict): Visualization parameters. For example, {'min': 0, 'max': 100}.
            asset_id (str): The ID of the Earth Engine asset.
            name (str, optional): The name of the tile layer. If not provided, the asset ID will be used. Default is None.
            attribution (str, optional): The attribution text to be displayed. Default is "Google Earth Engine".
            shown (bool, optional): Whether the tile layer should be shown on the map. Default is True.
            opacity (float, optional): The opacity of the tile layer. Default is 1.0.
            **kwargs: Additional keyword arguments to be passed to the underlying `add_tile_layer` method.

        Returns:
            None
        """
        import pandas as pd

        if isinstance(asset_id, str):

            df = pd.read_csv(
                "https://raw.githubusercontent.com/opengeos/ee-tile-layers/main/datasets.tsv",
                sep="\t",
            )

            asset_id = asset_id.strip()
            if name is None:
                name = asset_id

            if asset_id in df["id"].values:
                url = df.loc[df["id"] == asset_id, "url"].values[0]
                self.add_tile_layer(
                    url,
                    name,
                    attribution=attribution,
                    shown=shown,
                    opacity=opacity,
                    **kwargs,
                )
            else:
                print(f"The provided EE tile layer {asset_id} does not exist.")
                return
        elif ee_object is not None:
            url = get_ee_tile_url(ee_object, vis_params)
            if url is None:
                print(f"The provided EE tile layer {ee_object} does not exist.")
                return
            if name is None:
                name = "EE Layer"
            self.add_tile_layer(
                url,
                name,
                attribution=attribution,
                shown=shown,
                opacity=opacity,
                **kwargs,
            )

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

        Args:
            position (str, optional): The position of the layer control. Defaults to 'topright'.
        """

        self.add(ipyleaflet.LayersControl(position=position))

    def layer_opacity(self, name, value=1.0) -> None:
        """Changes layer opacity.

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

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

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

        if name is None:
            name = str(layers)

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

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

    def add_tile_layer(
        self,
        url,
        name,
        attribution,
        opacity=1.0,
        shown=True,
        layer_index=None,
        **kwargs,
    ) -> None:
        """Adds a TileLayer to the map.

        Args:
            url (str): The URL of the tile layer.
            name (str): The layer name to use for the layer.
            attribution (str): The attribution to use.
            opacity (float, optional): The opacity of the layer. Defaults to 1.
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
            layer_index (int, optional): The index at which to add the layer. Defaults to None.
        """
        if "max_zoom" not in kwargs:
            kwargs["max_zoom"] = 30
        if "max_native_zoom" not in kwargs:
            kwargs["max_native_zoom"] = 30
        try:
            tile_layer = ipyleaflet.TileLayer(
                url=url,
                name=name,
                attribution=attribution,
                opacity=opacity,
                visible=shown,
                **kwargs,
            )
            self.add(tile_layer, index=layer_index)

            common.arc_add_layer(url, name, shown, opacity)

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

    def add_vector_tile(
        self,
        url,
        styles: Optional[dict] = {},
        layer_name: Optional[str] = "Vector Tile",
        **kwargs,
    ) -> None:
        """Adds a VectorTileLayer to the map. It wraps the ipyleaflet.VectorTileLayer class. See
            https://ipyleaflet.readthedocs.io/en/latest/layers/vector_tile.html

        Args:
            url (str, optional): The URL of the tile layer
            styles (dict,optional): Style dict, specific to the vector tile source.
            layer_name (str, optional): The layer name to use for the layer. Defaults to 'Vector Tile'.
            kwargs: Additional keyword arguments to pass to the ipyleaflet.VectorTileLayer class.
        """
        if "vector_tile_layer_styles" in kwargs:
            styles = kwargs["vector_tile_layer_styles"]
            del kwargs["vector_tile_layer_styles"]
        try:
            vector_tile_layer = ipyleaflet.VectorTileLayer(
                url=url,
                vector_tile_layer_styles=styles,
                **kwargs,
            )
            vector_tile_layer.name = layer_name
            self.add(vector_tile_layer)

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

    add_vector_tile_layer = add_vector_tile

    def add_pmtiles(
        self,
        url,
        style=None,
        name="PMTiles",
        show=True,
        zoom_to_layer=True,
        **kwargs,
    ) -> None:
        """
        Adds a PMTiles layer to the map. This function is not officially supported yet by ipyleaflet yet.
        Install it with the following command:
        pip install git+https://github.com/giswqs/ipyleaflet.git@pmtiles

        Args:
            url (str): The URL of the PMTiles file.
            style (str, optional): The CSS style to apply to the layer. Defaults to None.
                See https://docs.mapbox.com/style-spec/reference/layers/ for more info.
            name (str, optional): The name of the layer. Defaults to None.
            show (bool, optional): Whether the layer should be shown initially. Defaults to True.
            zoom_to_layer (bool, optional): Whether to zoom to the layer extent. Defaults to True.
            **kwargs: Additional keyword arguments to pass to the PMTilesLayer constructor.

        Returns:
            None
        """

        try:
            if "sources" in kwargs:
                del kwargs["sources"]

            if "version" in kwargs:
                del kwargs["version"]

            if style is None:
                style = common.pmtiles_style(url)

            layer = ipyleaflet.PMTilesLayer(
                url=url,
                style=style,
                name=name,
                visible=show,
                **kwargs,
            )
            self.add(layer)

            if zoom_to_layer:
                metadata = common.pmtiles_metadata(url)
                bounds = metadata["bounds"]
                self.zoom_to_bounds(bounds)
        except Exception as e:
            print(e)

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

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

        """

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

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

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

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

        """
        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,
        which_result=None,
        buffer_dist=None,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=None,
        info_mode="on_hover",
    ) -> None:
        """Adds OSM entities within boundaries of geocodable place(s) to the map.

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

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

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

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

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

        """
        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,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=None,
        info_mode="on_hover",
    ) -> None:
        """Adds OSM entities within boundaries of a (multi)polygon to the map.

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

        """
        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,
        south,
        east,
        west,
        tags,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=None,
        info_mode="on_hover",
    ) -> None:
        """Adds OSM entities within a N, S, E, W bounding box to the map.


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

        """
        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_osm_from_view(
        self,
        tags,
        layer_name="Untitled",
        style={},
        hover_style={},
        style_callback=None,
        fill_colors=None,
        info_mode="on_hover",
    ) -> None:
        """Adds OSM entities within the current map view to the map.

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

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

        gdf = osm.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_cog_layer(
        self,
        url,
        name="Untitled",
        attribution="",
        opacity=1.0,
        shown=True,
        bands=None,
        titiler_endpoint=None,
        zoom_to_layer=True,
        layer_index=None,
        overwrite=False,
        **kwargs,
    ) -> None:
        """Adds a COG TileLayer to the map.

        Args:
            url (str): The URL of the COG tile layer.
            name (str, optional): The layer name to use for the layer. Defaults to 'Untitled'.
            attribution (str, optional): The attribution to use. Defaults to ''.
            opacity (float, optional): The opacity of the layer. Defaults to 1.
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
            bands (list, optional): A list of bands to use for the layer. Defaults to None.
            titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".
            zoom_to_layer (bool, optional): Whether to zoom to the layer extent. Defaults to True.
            layer_index (int, optional): The index at which to add the layer. Defaults to None.
            overwrite (bool, optional): Whether to overwrite the layer if it already exists. Defaults to False.
            **kwargs: Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale,
                color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/
                and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3].
                apply a rescaling to multiple bands, use something like `rescale=["164,223","130,211","99,212"]`.
        """
        if os.environ.get("USE_MKDOCS") is not None:
            return

        band_names = common.cog_bands(url, titiler_endpoint)
        if len(band_names) == 0:
            return

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

            if all(isinstance(x, str) for x in bands):
                kwargs["bidx"] = [band_names.index(x) + 1 for x in bands]

            elif all(isinstance(x, int) for x in bands):
                kwargs["bidx"] = bands
            else:
                raise ValueError("Bands must be a list of integers or strings.")
        elif "bidx" not in kwargs:
            if len(band_names) == 1:
                kwargs["bidx"] = [1]
            else:
                kwargs["bidx"] = [1, 2, 3]

        vis_bands = [band_names[idx - 1] for idx in kwargs["bidx"]]

        if len(kwargs["bidx"]) > 1:
            if "colormap_name" in kwargs:
                kwargs.pop("colormap_name")
            if "colormap" in kwargs:
                kwargs.pop("colormap")

        tile_url = common.cog_tile(url, bands, titiler_endpoint, **kwargs)
        bounds = common.cog_bounds(url, titiler_endpoint)

        name = self._check_layer_name(name, overwrite=overwrite)
        if overwrite and name in self.get_layer_names():
            layer = self.find_layer(name)
            if layer is not None:
                self.remove_layer(layer)

        self.add_tile_layer(tile_url, name, attribution, opacity, shown, layer_index)
        if zoom_to_layer and bounds is not None:
            self.center = common.cog_center(url, titiler_endpoint)
            self.zoom = 19
            self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])
            common.arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

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

        try:
            vmin, vmax = common.cog_tile_vmin_vmax(
                url, bands=bands, titiler_endpoint=titiler_endpoint
            )
        except Exception:
            vmin, vmax = None, None

        if "colormap_name" in kwargs:
            colormap = kwargs["colormap_name"]
        else:
            colormap = None

        if "nodata" in kwargs:
            nodata = kwargs["nodata"]
        else:
            nodata = None

        params = {
            "url": url,
            "titiler_endpoint": titiler_endpoint,
            "tile_layer": self.find_layer(name),
            "bounds": bounds,
            "indexes": kwargs["bidx"],
            "vis_bands": vis_bands,
            "band_names": band_names,
            "vmin": vmin,
            "vmax": vmax,
            "nodata": nodata,
            "colormap": colormap,
            "opacity": opacity,
            "layer_name": name,
            "type": "COG",
        }
        if vmin is None and vmax is None:
            params.pop("vmin")
            params.pop("vmax")

        self.cog_layer_dict[name] = params

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

    def add_cog_mosaic_from_file(self, **kwargs) -> None:
        raise NotImplementedError(
            "This function is no longer supported.See https://github.com/opengeos/leafmap/issues/180."
        )

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

        Args:
            url (str): HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json
            collection (str): The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.
            item (str): The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.
            assets (str | list): The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"].
            bands (list): A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]
            titiler_endpoint (str, optional): TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space", "https://planetarycomputer.microsoft.com/api/data/v1", "planetary-computer", "pc". Defaults to None.
            name (str, optional): The layer name to use for the layer. Defaults to 'STAC Layer'.
            attribution (str, optional): The attribution to use. Defaults to ''.
            opacity (float, optional): The opacity of the layer. Defaults to 1.
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
            fit_bounds (bool, optional): A flag indicating whether the map should be zoomed to the layer extent. Defaults to True.
            layer_index (int, optional): The index at which to add the layer. Defaults to None.
        """

        if os.environ.get("USE_MKDOCS") is not None:
            return

        if "colormap_name" in kwargs and kwargs["colormap_name"] is None:
            kwargs.pop("colormap_name")

        tile_url = common.stac_tile(
            url, collection, item, assets, bands, titiler_endpoint, **kwargs
        )
        if tile_url is None:
            return
        bounds = common.stac_bounds(url, collection, item, titiler_endpoint)
        self.add_tile_layer(tile_url, name, attribution, opacity, shown, layer_index)
        if fit_bounds and bounds is not None:
            self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])
            common.arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

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

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

        if isinstance(assets, str) and "," in assets:
            assets = assets.split(",")

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

        if "rescale" in kwargs:
            rescale = kwargs["rescale"]
            vmin, vmax = [float(v) for v in rescale.split(",")]
        else:
            vmin, vmax = common.stac_min_max(
                url, collection, item, assets, titiler_endpoint
            )

        if "nodata" in kwargs:
            nodata = kwargs["nodata"]
        else:
            nodata = None

        band_names = common.stac_bands(url, collection, item, titiler_endpoint)

        if assets is not None:
            indexes = [band_names.index(band) + 1 for band in assets]
        else:
            indexes = None

        params = {
            "url": url,
            "titiler_endpoint": titiler_endpoint,
            "collection": collection,
            "item": item,
            "assets": assets,
            "tile_layer": self.find_layer(name),
            "indexes": indexes,
            "vis_bands": assets,
            "band_names": band_names,
            "bounds": bounds,
            "vmin": vmin,
            "vmax": vmax,
            "nodata": nodata,
            "opacity": opacity,
            "layer_name": name,
            "type": "STAC",
        }

        self.cog_layer_dict[name] = params

    def add_mosaic_layer(
        self,
        url=None,
        titiler_endpoint=None,
        name="Mosaic Layer",
        attribution="",
        opacity=1.0,
        shown=True,
        **kwargs,
    ) -> None:
        """Adds a STAC TileLayer to the map.

        Args:
            url (str): HTTP URL to a MosaicJSON.
            titiler_endpoint (str, optional): TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space". Defaults to None.
            name (str, optional): The layer name to use for the layer. Defaults to 'Mosaic Layer'.
            attribution (str, optional): The attribution to use. Defaults to ''.
            opacity (float, optional): The opacity of the layer. Defaults to 1.
            shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        """
        tile_url = common.mosaic_tile(url, titiler_endpoint, **kwargs)

        bounds = common.mosaic_bounds(url, titiler_endpoint)
        self.add_tile_layer(tile_url, name, attribution, opacity, shown)
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

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

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

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

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

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

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

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

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

    def add_circle_markers_from_xy(
        self,
        data,
        x="lon",
        y="lat",
        radius=10,
        popup=None,
        font_size=2,
        stroke=True,
        color="#0033FF",
        weight=2,
        fill=True,
        fill_color=None,
        fill_opacity=0.2,
        opacity=1.0,
        layer_name="Circle Markers",
        **kwargs,
    ) -> None:
        """Adds a marker cluster to the map. For a list of options, see https://ipyleaflet.readthedocs.io/en/latest/_modules/ipyleaflet/leaflet.html#Path

        Args:
            data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
            x (str, optional): The column name for the x values. Defaults to "lon".
            y (str, optional): The column name for the y values. Defaults to "lat".
            radius (int, optional): The radius of the circle. Defaults to 10.
            popup (list, optional): A list of column names to be used as the popup. Defaults to None.
            font_size (int, optional): The font size of the popup. Defaults to 2.
            stroke (bool, optional): Whether to stroke the path. Defaults to True.
            color (str, optional): The color of the path. Defaults to "#0033FF".
            weight (int, optional): The weight of the path. Defaults to 2.
            fill (bool, optional): Whether to fill the path with color. Defaults to True.
            fill_color (str, optional): The fill color of the path. Defaults to None.
            fill_opacity (float, optional): The fill opacity of the path. Defaults to 0.2.
            opacity (float, optional): The opacity of the path. Defaults to 1.0.
            layer_name (str, optional): The layer name to use for the marker cluster. Defaults to "Circle Markers".

        """
        import geopandas as gpd
        import pandas as pd

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

        col_names = df.columns.values.tolist()
        if "geometry" in col_names:
            col_names.remove("geometry")

        if popup is None:
            popup = col_names

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

        if x not in col_names:
            if isinstance(df, gpd.GeoDataFrame):
                df[x] = df.geometry.x
            else:
                raise ValueError(
                    f"x must be one of the following: {', '.join(col_names)}"
                )

        if y not in col_names:
            if isinstance(df, gpd.GeoDataFrame):
                df[y] = df.geometry.y
            else:
                raise ValueError(
                    f"y must be one of the following: {', '.join(col_names)}"
                )

        if fill_color is None:
            fill_color = color

        if isinstance(color, str):
            colors = [color] * len(df)
        elif isinstance(color, list):
            colors = color
        else:
            raise ValueError("color must be either a string or a list.")

        if isinstance(fill_color, str):
            fill_colors = [fill_color] * len(df)
        elif isinstance(fill_color, list):
            fill_colors = fill_color
        else:
            raise ValueError("fill_color must be either a string or a list.")

        if isinstance(radius, int):
            radius = [radius] * len(df)
        elif isinstance(radius, list):
            radius = radius
        else:
            raise ValueError("radius must be either an integer or a list.")

        index = 0

        layers = []
        for idx, row in df.iterrows():
            html = ""
            for p in popup:
                html = (
                    html
                    + f"<font size='{font_size}'><b>"
                    + p
                    + "</b>"
                    + ": "
                    + str(row[p])
                    + "<br></font>"
                )
            popup_html = widgets.HTML(html)

            marker = ipyleaflet.CircleMarker(
                location=[row[y], row[x]],
                radius=radius[index],
                popup=popup_html,
                stroke=stroke,
                color=colors[index],
                weight=weight,
                fill=fill,
                fill_color=fill_colors[index],
                fill_opacity=fill_opacity,
                opacity=opacity,
                **kwargs,
            )
            layers.append(marker)
            index += 1

        group = ipyleaflet.LayerGroup(layers=tuple(layers), name=layer_name)
        self.add(group)

    def add_markers(
        self,
        markers: Union[List[List[Union[int, float]]], List[Union[int, float]]],
        x: str = "lon",
        y: str = "lat",
        radius: int = 10,
        popup: Optional[str] = None,
        font_size: int = 2,
        stroke: bool = True,
        color: str = "#0033FF",
        weight: int = 2,
        fill: bool = True,
        fill_color: Optional[str] = None,
        fill_opacity: float = 0.2,
        opacity: float = 1.0,
        shape: str = "circle",
        layer_name: str = "Markers",
        **kwargs,
    ) -> None:
        """
        Adds markers to the map.

        Args:
            markers (Union[List[List[Union[int, float]]], List[Union[int, float]]]): List of markers.
                Each marker can be defined as a list of [x, y] coordinates or as a single [x, y] coordinate.
            x (str, optional): Name of the x-coordinate column in the marker data. Defaults to "lon".
            y (str, optional): Name of the y-coordinate column in the marker data. Defaults to "lat".
            radius (int, optional): Radius of the markers. Defaults to 10.
            popup (str, optional): Popup text for the markers. Defaults to None.
            font_size (int, optional): Font size of the popup text. Defaults to 2.
            stroke (bool, optional): Whether to display marker stroke. Defaults to True.
            color (str, optional): Color of the marker stroke. Defaults to "#0033FF".
            weight (int, optional): Weight of the marker stroke. Defaults to 2.
            fill (bool, optional): Whether to fill markers. Defaults to True.
            fill_color (str, optional): Fill color of the markers. Defaults to None.
            fill_opacity (float, optional): Opacity of the marker fill. Defaults to 0.2.
            opacity (float, optional): Opacity of the markers. Defaults to 1.0.
            shape (str, optional): Shape of the markers. Options are "circle" or "marker". Defaults to "circle".
            layer_name (str, optional): Name of the marker layer. Defaults to "Markers".
            **kwargs: Additional keyword arguments to pass to the marker plotting function.

        Returns:
            None: This function does not return any value.
        """
        import geopandas as gpd
        import pandas as pd

        if (
            isinstance(markers, list)
            and len(markers) == 2
            and isinstance(markers[0], (int, float))
            and isinstance(markers[1], (int, float))
        ):
            markers = [markers]

        if isinstance(markers, list) and all(
            isinstance(item, list) and len(item) == 2 for item in markers
        ):
            df = pd.DataFrame(markers, columns=[y, x])
            markers = gpd.GeoDataFrame(df, geometry=gpd.points_from_xy(df[x], df[y]))

        if shape == "circle":
            self.add_circle_markers_from_xy(
                markers,
                x,
                y,
                radius,
                popup,
                font_size,
                stroke,
                color,
                weight,
                fill,
                fill_color,
                fill_opacity,
                opacity,
                layer_name,
                **kwargs,
            )

        elif shape == "marker":
            self.add_gdf(markers, **kwargs)

    def split_map(
        self,
        left_layer: Optional[str] = "TERRAIN",
        right_layer: Optional[str] = "OpenTopoMap",
        left_args: Optional[dict] = {},
        right_args: Optional[dict] = {},
        left_array_args: Optional[dict] = {},
        right_array_args: Optional[dict] = {},
        zoom_control: Optional[bool] = True,
        fullscreen_control: Optional[bool] = True,
        layer_control: Optional[bool] = True,
        add_close_button: Optional[bool] = False,
        left_label: Optional[str] = None,
        right_label: Optional[str] = None,
        left_position: Optional[str] = "bottomleft",
        right_position: Optional[str] = "bottomright",
        widget_layout: Optional[dict] = None,
        draggable: Optional[bool] = True,
    ) -> None:
        """Adds split map.

        Args:
            left_layer (str, optional): The left tile layer. Can be a local file path, HTTP URL, or a basemap name. Defaults to 'TERRAIN'.
            right_layer (str, optional): The right tile layer. Can be a local file path, HTTP URL, or a basemap name. Defaults to 'OpenTopoMap'.
            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_array_args (dict, optional): The arguments for array_to_image for the left layer. Defaults to {}.
            right_array_args (dict, optional): The arguments for array_to_image for the right layer. Defaults to {}.
            zoom_control (bool, optional): Whether to add zoom control. Defaults to True.
            fullscreen_control (bool, optional): Whether to add fullscreen control. Defaults to True.
            layer_control (bool, optional): Whether to add layer control. Defaults to True.
            add_close_button (bool, optional): Whether to add a close button. Defaults to False.
            left_label (str, optional): The label for the left layer. Defaults to None.
            right_label (str, optional): The label for the right layer. Defaults to None.
            left_position (str, optional): The position for the left label. Defaults to "bottomleft".
            right_position (str, optional): The position for the right label. Defaults to "bottomright".
            widget_layout (dict, optional): The layout for the widget. Defaults to None.
            draggable (bool, optional): Whether the split map is draggable. Defaults to True.
        """
        import geopandas as gpd

        if os.environ.get("USE_MKDOCS") is not None:
            return

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

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

        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:
            controls = self.controls
            layers = self.layers
            self.clear()

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

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

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

            if isinstance(left_layer, str):
                if left_layer in basemaps.keys():
                    left_layer = get_basemap(left_layer)
                elif left_layer.startswith("http") and left_layer.endswith(".tif"):
                    url = common.cog_tile(left_layer, **left_args)
                    bbox = common.cog_bounds(left_layer)
                    if bbox is not None:
                        bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                    left_layer = ipyleaflet.TileLayer(
                        url=url,
                        name=left_name,
                        attribution=" ",
                        **left_args,
                    )
                elif left_layer.startswith("http") and left_layer.endswith(".json"):
                    left_tile_url = common.stac_tile(left_layer, **left_args)
                    bbox = common.stac_bounds(left_layer)
                    if bbox is not None:
                        bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                    left_layer = ipyleaflet.TileLayer(
                        url=left_tile_url,
                        name=left_name,
                        attribution=" ",
                        **left_args,
                    )
                elif left_layer.startswith("http") and left_layer.endswith(".geojson"):
                    if "max_zoom" in left_args:
                        del left_args["max_zoom"]
                    if "max_native_zoom" in left_args:
                        del left_args["max_native_zoom"]
                    left_layer = geojson_layer(left_layer, **left_args)
                elif os.path.exists(left_layer):
                    if left_layer.endswith(".geojson"):
                        if "max_zoom" in left_args:
                            del left_args["max_zoom"]
                        if "max_native_zoom" in left_args:
                            del left_args["max_native_zoom"]
                        left_layer = geojson_layer(left_layer, **left_args)
                    else:
                        left_layer, left_client = common.get_local_tile_layer(
                            left_layer,
                            tile_format="ipyleaflet",
                            return_client=True,
                            **left_args,
                        )
                        bounds = common.image_bounds(left_client)
                else:
                    left_layer = ipyleaflet.TileLayer(
                        url=left_layer,
                        name=left_name,
                        attribution=" ",
                        **left_args,
                    )
            elif isinstance(left_layer, ipyleaflet.TileLayer) or isinstance(
                left_layer, ipyleaflet.GeoJSON
            ):
                pass
            elif common.is_array(left_layer):
                left_layer = common.array_to_image(left_layer, **left_array_args)
                left_layer, _ = common.get_local_tile_layer(
                    left_layer,
                    return_client=True,
                    **left_args,
                )
            elif isinstance(left_layer, gpd.GeoDataFrame):
                left_layer = left_layer.to_crs("EPSG:4326").__geo_interface__
                if "max_zoom" in left_args:
                    del left_args["max_zoom"]
                if "max_native_zoom" in left_args:
                    del left_args["max_native_zoom"]
                left_layer = geojson_layer(left_layer, **left_args)
            else:
                raise ValueError(
                    f"left_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
                )

            if isinstance(right_layer, str):
                if right_layer in basemaps.keys():
                    right_layer = get_basemap(right_layer)
                elif right_layer.startswith("http") and right_layer.endswith(".tif"):
                    url = common.cog_tile(
                        right_layer,
                        **right_args,
                    )
                    bbox = common.cog_bounds(right_layer)
                    if bbox is not None:
                        bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                    right_layer = ipyleaflet.TileLayer(
                        url=url,
                        name=right_name,
                        attribution=" ",
                        **right_args,
                    )

                elif right_layer.startswith("http") and right_layer.endswith(".json"):
                    right_tile_url = common.stac_tile(right_layer, **left_args)
                    bbox = common.stac_bounds(right_layer)
                    if bbox is not None:
                        bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                    right_layer = ipyleaflet.TileLayer(
                        url=right_tile_url,
                        name=right_name,
                        attribution=" ",
                        **right_args,
                    )
                elif right_layer.startswith("http") and right_layer.endswith(
                    ".geojson"
                ):
                    if "max_zoom" in right_args:
                        del right_args["max_zoom"]
                    if "max_native_zoom" in right_args:
                        del right_args["max_native_zoom"]
                    right_layer = geojson_layer(right_layer, **right_args)
                elif os.path.exists(right_layer):
                    if "max_zoom" in right_args:
                        del right_args["max_zoom"]
                    if "max_native_zoom" in right_args:
                        del right_args["max_native_zoom"]
                    if right_layer.endswith(".geojson"):
                        right_layer = geojson_layer(right_layer, **right_args)
                    else:
                        right_layer, right_client = common.get_local_tile_layer(
                            right_layer,
                            tile_format="ipyleaflet",
                            return_client=True,
                            **right_args,
                        )
                        bounds = common.image_bounds(right_client)
                else:
                    right_layer = ipyleaflet.TileLayer(
                        url=right_layer,
                        name=right_name,
                        attribution=" ",
                        **right_args,
                    )
            elif isinstance(right_layer, ipyleaflet.TileLayer) or isinstance(
                right_layer, ipyleaflet.GeoJSON
            ):
                pass
            elif common.is_array(right_layer):
                right_layer = common.array_to_image(right_layer, **right_array_args)
                right_layer, _ = common.get_local_tile_layer(
                    right_layer,
                    return_client=True,
                    **right_args,
                )
            elif isinstance(right_layer, gpd.GeoDataFrame):
                right_layer = right_layer.to_crs("EPSG:4326").__geo_interface__
                if "max_zoom" in right_args:
                    del right_args["max_zoom"]
                if "max_native_zoom" in right_args:
                    del right_args["max_native_zoom"]
                right_layer = geojson_layer(right_layer, **right_args)
            else:
                raise ValueError(
                    f"right_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
                )
            control = ipyleaflet.SplitMapControl(
                left_layer=left_layer, right_layer=right_layer
            )
            self.add(control)

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

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

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

            if bounds is not None:
                self.fit_bounds(bounds)

            self.dragging = draggable

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

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

                if left_label in self.controls:
                    self.remove_control(left_control)

                if right_label in self.controls:
                    self.remove_control(right_control)

                self.dragging = True

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

            if add_close_button:
                self.add(close_control)

            if layer_control:
                self.add_layer_control()

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

    def basemap_demo(self) -> None:
        """A demo for using leafmap basemaps."""
        dropdown = widgets.Dropdown(
            options=list(basemaps.keys()),
            value="Esri.WorldImagery",
            description="Basemaps",
        )

        def on_click(change):
            basemap_name = change["new"]
            old_basemap = self.layers[-1]
            self.substitute_layer(old_basemap, get_basemap(basemap_name))

        dropdown.observe(on_click, "value")
        basemap_control = ipyleaflet.WidgetControl(widget=dropdown, position="topright")
        self.add(basemap_control)

    def add_legend(
        self,
        title: Optional[str] = "Legend",
        legend_dict: Optional[dict] = None,
        labels: Optional[list] = None,
        colors: Optional[list] = None,
        position: Optional[str] = "bottomright",
        builtin_legend: Optional[str] = None,
        layer_name: Optional[str] = None,
        shape_type: Optional[str] = "rectangle",
        **kwargs,
    ) -> None:
        """Adds a customized basemap to the map.

        Args:
            title (str, optional): Title of the legend. Defaults to 'Legend'.
            legend_dict (dict, optional): A dictionary containing legend items as keys and color as values. If provided, legend_keys and legend_colors will be ignored. Defaults to None.
            labels (list, optional): A list of legend keys. Defaults to None.
            colors (list, optional): A list of legend colors. Defaults to None.
            position (str, optional): Position of the legend. Defaults to 'bottomright'.
            builtin_legend (str, optional): Name of the builtin legend to add to the map. Defaults to None.
            layer_name (str, optional): Layer name of the legend to be associated with. Defaults to None.

        """
        import importlib.resources

        from IPython.display import display

        pkg_dir = os.path.dirname(importlib.resources.files("leafmap") / "leafmap.py")
        legend_template = os.path.join(pkg_dir, "data/template/legend.html")

        if "min_width" not in kwargs.keys():
            min_width = None
        if "max_width" not in kwargs.keys():
            max_width = None
        else:
            max_width = kwargs["max_width"]
        if "min_height" not in kwargs.keys():
            min_height = None
        else:
            min_height = kwargs["min_height"]
        if "max_height" not in kwargs.keys():
            max_height = None
        else:
            max_height = kwargs["max_height"]
        if "height" not in kwargs.keys():
            height = None
        else:
            height = kwargs["height"]
        if "width" not in kwargs.keys():
            width = None
        else:
            width = kwargs["width"]

        if width is None:
            max_width = "300px"
        if height is None:
            max_height = "400px"

        if not os.path.exists(legend_template):
            print("The legend template does not exist.")
            return

        if labels is not None:
            if not isinstance(labels, list):
                print("The legend keys must be a list.")
                return
        else:
            labels = ["One", "Two", "Three", "Four", "etc"]

        if colors is not None:
            if not isinstance(colors, list):
                print("The legend colors must be a list.")
                return
            elif all(isinstance(item, tuple) for item in colors):
                try:
                    colors = [common.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 = [common.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:
            print(
                "The position must be one of the following: {}".format(
                    ", ".join(allowed_positions)
                )
            )
            return

        header = []
        content = []
        footer = []

        with open(legend_template) as f:
            lines = f.readlines()
            lines[3] = lines[3].replace("Legend", title)
            header = lines[:6]
            footer = lines[11:]

        for index, key in enumerate(labels):
            color = colors[index]
            if not color.startswith("#"):
                color = "#" + color
            item = "      <li><span style='background:{};'></span>{}</li>\n".format(
                color, key
            )
            content.append(item)

        legend_html = header + content + footer
        legend_text = "".join(legend_html)

        if shape_type == "circle":
            legend_text = legend_text.replace("width: 30px", "width: 16px")
            legend_text = legend_text.replace(
                "border: 1px solid #999;",
                "border-radius: 50%;\n      border: 1px solid #999;",
            )
        elif shape_type == "line":
            legend_text = legend_text.replace("height: 16px", "height: 3px")

        try:

            legend_widget = widgets.HTML(value=legend_text)
            legend_control = ipyleaflet.WidgetControl(
                widget=legend_widget, position=position
            )

            self.legend_widget = legend_widget
            self.legend_control = legend_control
            self.add(legend_control)

        except Exception as e:
            raise Exception(e)

    def add_colorbar(
        self,
        colors: Union[list[int], tuple[int]],
        vmin: Optional[int] = 0,
        vmax: Optional[float] = 1.0,
        index: Optional[list] = None,
        caption: Optional[str] = "",
        categorical: Optional[bool] = False,
        step: Optional[int] = None,
        height: Optional[str] = "45px",
        transparent_bg: Optional[bool] = False,
        position: Optional[str] = "bottomright",
        **kwargs,
    ) -> None:
        """Add a branca colorbar to the map.

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

        """
        from box import Box
        from branca.colormap import LinearColormap

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

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

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

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

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

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

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

        self.colorbar = colormap_ctrl
        self.add(colormap_ctrl)

    def add_colormap(
        self,
        cmap: Optional[str] = "gray",
        colors: Optional[list] = None,
        discrete: Optional[bool] = False,
        label: Optional[str] = None,
        width: Optional[float] = 3,
        height: Optional[float] = 0.25,
        orientation: Optional[str] = "horizontal",
        vmin: Optional[float] = 0,
        vmax: Optional[float] = 1.0,
        axis_off: Optional[bool] = False,
        show_name: Optional[bool] = False,
        font_size: Optional[int] = 8,
        transparent_bg: Optional[bool] = False,
        position: Optional[str] = "bottomright",
        **kwargs,
    ) -> None:
        """Adds a matplotlib colormap to the map.

        Args:
            cmap (str, optional): Matplotlib colormap. Defaults to "gray". See https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py for options.
            colors (list, optional): A list of custom colors to create a colormap. Defaults to None.
            discrete (bool, optional): Whether to create a discrete colorbar. Defaults to False.
            label (str, optional): Label for the colorbar. Defaults to None.
            width (float, optional): The width of the colormap. Defaults to 8.0.
            height (float, optional): The height of the colormap. Defaults to 0.4.
            orientation (str, optional): The orientation of the colormap. Defaults to "horizontal".
            vmin (float, optional): The minimum value range. Defaults to 0.
            vmax (float, optional): The maximum value range. Defaults to 1.0.
            axis_off (bool, optional): Whether to turn axis off. Defaults to False.
            show_name (bool, optional): Whether to show the colormap name. Defaults to False.
            font_size (int, optional): Font size of the text. Defaults to 12.
            transparent_bg (bool, optional): Whether to use transparent background for the colormap widget. Defaults to True.
            position (str, optional): The position for the colormap widget. Defaults to "bottomright".
        """
        from .colormaps import plot_colormap

        output = widgets.Output()

        colormap_ctrl = ipyleaflet.WidgetControl(
            widget=output,
            position=position,
            transparent_bg=transparent_bg,
        )
        with output:
            output.clear_output()
            with output:
                plot_colormap(
                    cmap,
                    colors,
                    discrete,
                    label,
                    width,
                    height,
                    orientation,
                    vmin,
                    vmax,
                    axis_off,
                    show_name,
                    font_size,
                    **kwargs,
                )

        self.colorbar = colormap_ctrl
        self.add(colormap_ctrl)

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

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

        from PIL import Image, ImageSequence

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

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

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

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

    def video_overlay(
        self, url: str, bounds: Tuple, layer_name: str = None, **kwargs
    ) -> None:
        """Overlays a video from the Internet on the map.

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

    def to_html(
        self,
        outfile: Optional[str] = None,
        title: Optional[str] = "My Map",
        width: Optional[str] = "100%",
        height: Optional[str] = "880px",
        add_layer_control: Optional[bool] = True,
        **kwargs,
    ) -> None:
        """Saves the map as an HTML file.

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

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

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

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

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

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

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

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

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

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

        except Exception as e:
            raise Exception(e)

    def to_image(
        self, outfile: Optional[str] = None, monitor: Optional[int] = 1
    ) -> None:
        """Saves the map as a PNG or JPG image.

        Args:
            outfile (str, optional): The output file path to the image. Defaults to None.
            monitor (int, optional): The monitor to take the screenshot. Defaults to 1.
        """
        if outfile is None:
            outfile = os.path.join(os.getcwd(), "my_map.png")

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

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

        screenshot = common.screen_capture(outfile, monitor)
        self.screenshot = screenshot

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

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

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

        try:
            import streamlit.components.v1 as components  # pylint: disable=E0401

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

        except Exception as e:
            raise Exception(e)

    def toolbar_reset(self) -> None:
        """Reset the toolbar so that no tool is selected."""
        toolbar_grid = self.toolbar
        for tool in toolbar_grid.children:
            tool.value = False

    def _check_layer_name(self, layer_name: str, overwrite: bool = False) -> str:
        """Checks and ensures the uniqueness of a layer name.

        If the provided layer name already exists in the map, this function appends
        a numeric suffix to make it unique unless `overwrite` is set to True.

        Args:
            layer_name (str): The name of the layer to check.
            overwrite (bool, optional): Whether to overwrite an existing layer with the same name. Defaults to False.

        Returns:
            str: A unique layer name.
        """
        names = self.get_layer_names()
        if layer_name in names:
            if not overwrite:
                base_name = layer_name
                suffix = 1
                while f"{base_name}_{suffix}" in names:
                    suffix += 1
                layer_name = f"{base_name}_{suffix}"
                return layer_name
            else:
                return layer_name
        else:
            return layer_name

    def add_raster(
        self,
        source: str,
        indexes: Optional[int] = None,
        colormap: Optional[str] = None,
        vmin: Optional[float] = None,
        vmax: Optional[float] = None,
        nodata: Optional[float] = None,
        attribution: Optional[str] = None,
        layer_name: Optional[str] = "Raster",
        layer_index: Optional[int] = None,
        zoom_to_layer: Optional[bool] = True,
        visible: Optional[bool] = True,
        opacity: Optional[float] = 1.0,
        array_args: Optional[Dict] = {},
        client_args: Optional[Dict] = {"cors_all": False},
        overwrite: Optional[bool] = False,
        **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 (str): The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
            indexes (int, optional): The band(s) to use. Band indexing starts at 1. Defaults to None.
            colormap (str, optional): The name of the colormap from `matplotlib` to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.
            vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
            vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
            nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
            attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
            layer_name (str, optional): The layer name to use. Defaults to 'Raster'.
            layer_index (int, optional): The index of the layer. Defaults to None.
            zoom_to_layer (bool, optional): Whether to zoom to the extent of the layer. Defaults to True.
            visible (bool, optional): Whether the layer is visible. Defaults to True.
            opacity (float, optional): The opacity of the layer. Defaults to 1.0.
            array_args (dict, optional): Additional arguments to pass to `array_to_memory_file` when reading the raster. Defaults to {}.
            client_args (dict, optional): Additional arguments to pass to localtileserver.TileClient. Defaults to { "cors_all": False }.
            overwrite (bool, optional): Whether to overwrite an existing layer with the same name. Defaults to False.
        """
        import numpy as np
        import xarray as xr

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

        tile_layer = common.get_local_tile_layer(
            source,
            indexes=indexes,
            colormap=colormap,
            vmin=vmin,
            vmax=vmax,
            nodata=nodata,
            opacity=opacity,
            attribution=attribution,
            layer_name=layer_name,
            client_args=client_args,
            return_client=False,
            **kwargs,
        )
        tile_layer.visible = visible
        tile_client = tile_layer.tile_server
        tile_layer.name = self._check_layer_name(layer_name, overwrite=overwrite)

        if overwrite and layer_name in self.get_layer_names():
            layer = self.find_layer(tile_layer.name)
            if layer is not None:
                self.remove(layer)

        self.add(tile_layer, index=layer_index)
        if zoom_to_layer:
            self.center = tile_client.center()
            try:
                self.zoom = tile_client.default_zoom
            except AttributeError:
                self.zoom = 15

        common.arc_add_layer(tile_layer.url, tile_layer.name, True, 1.0)

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

        if indexes is None:
            if len(tile_client.band_names) == 1:
                indexes = [1]
            else:
                indexes = [1, 2, 3]

        vis_bands = [tile_client.band_names[i - 1] for i in indexes]

        params = {
            "tile_layer": tile_layer,
            "tile_client": tile_client,
            "indexes": indexes,
            "vis_bands": vis_bands,
            "band_names": tile_client.band_names,
            "vmin": vmin,
            "vmax": vmax,
            "nodata": nodata,
            "colormap": colormap,
            "opacity": opacity,
            "layer_name": tile_layer.name,
            "filename": tile_client.filename,
            "type": "LOCAL",
        }
        self.cog_layer_dict[tile_layer.name] = params
        self.tile_client = tile_client

    add_local_tile = add_raster

    def add_geotiff(
        self,
        url: str,
        name: str = "GeoTIFF",
        attribution: str = "",
        opacity: float = 1.0,
        shown: bool = True,
        bands: Optional[Sequence[Union[int, str]]] = None,
        titiler_endpoint: Optional[str] = None,
        zoom_to_layer: bool = True,
        layer_index: Optional[int] = None,
        overwrite: bool = False,
        **kwargs,
    ) -> None:
        """Adds a Cloud Optimized GeoTIFF (COG) to the map.

        This helper wraps :meth:`add_cog_layer` so that users can quickly load a
        remote GeoTIFF/COG by simply providing its URL. By default it relies on
        the TiTiler endpoint configured for the map (the public demo endpoint is
        used when none is provided).

        Args:
            url (str): The HTTP URL of the GeoTIFF/COG.
            name (str, optional): Layer name to display in the layer tree.
                Defaults to ``"GeoTIFF"``.
            attribution (str, optional): Attribution text for the layer.
                Defaults to ``""``.
            opacity (float, optional): Layer opacity between 0.0 and 1.0.
                Defaults to 1.0.
            shown (bool, optional): Whether the layer should be visible when
                first added. Defaults to True.
            bands (Sequence[Union[int, str]], optional): Specific band indices
                (1-based) or band names to render. Defaults to None which lets
                Leafmap pick sensible defaults.
            titiler_endpoint (str, optional): Custom TiTiler endpoint to use.
                Defaults to the library's configured endpoint.
            zoom_to_layer (bool, optional): Whether to fit the map view to the
                layer bounds after it loads. Defaults to True.
            layer_index (int, optional): Stack index at which to insert the
                layer. Defaults to None (append).
            overwrite (bool, optional): When True, an existing layer with the
                same name is replaced. Defaults to False.
            **kwargs: Additional keyword arguments forwarded to
                :meth:`add_cog_layer` (e.g., ``bidx``, ``expression``,
                ``rescale``).
        """
        self.add_cog_layer(
            url,
            name=name,
            attribution=attribution,
            opacity=opacity,
            shown=shown,
            bands=bands,
            titiler_endpoint=titiler_endpoint,
            zoom_to_layer=zoom_to_layer,
            layer_index=layer_index,
            overwrite=overwrite,
            **kwargs,
        )

    def add_opacity_control(
        self,
        layer: Optional[Union[str, ipyleaflet.Layer]] = None,
        position: str = "topright",
        min_opacity: float = 0.0,
        max_opacity: float = 1.0,
        step: float = 0.05,
    ) -> None:
        """Adds an interactive opacity control panel to the map.

        The panel provides a dropdown to choose from the map layers that expose
        an ``opacity`` attribute and a slider to adjust the selected layer's
        transparency.

        Args:
            layer (str | ipyleaflet.Layer, optional): Layer (or layer name) to
                select initially. Defaults to the first available layer.
            position (str, optional): Location for the widget control.
                Defaults to ``"topright"``.
            min_opacity (float, optional): Minimum slider value. Defaults to 0.0.
            max_opacity (float, optional): Maximum slider value. Defaults to 1.0.
            step (float, optional): Slider step size. Defaults to 0.05.
        """

        def build_label(base: str, count: int) -> str:
            return f"{base} ({count})" if count else base

        layer_lookup: Dict[str, ipyleaflet.Layer] = {}
        occurrence: Dict[str, int] = {}

        for lyr in self.layers:
            if hasattr(lyr, "opacity"):
                base = getattr(lyr, "name", None) or lyr.__class__.__name__
                occurrence.setdefault(base, 0)
                label = build_label(base, occurrence[base])
                occurrence[base] += 1
                layer_lookup[label] = lyr

        if not layer_lookup:
            raise RuntimeError(
                "No map layers with an 'opacity' attribute are available."
            )

        if isinstance(layer, ipyleaflet.Layer):
            default_label = next(
                (lbl for lbl, lyr in layer_lookup.items() if lyr is layer), None
            )
        elif isinstance(layer, str):
            default_label = next((lbl for lbl in layer_lookup if lbl == layer), None)
            if default_label is None:
                default_label = next(
                    (lbl for lbl in layer_lookup if lbl.startswith(layer)), None
                )
        else:
            default_label = None

        if default_label is None:
            default_label = list(layer_lookup.keys())[-1]

        dropdown = widgets.Dropdown(
            options=list(layer_lookup.keys()),
            value=default_label,
            description="Layer",
            layout=widgets.Layout(width="260px"),
        )

        selected_layer = layer_lookup[dropdown.value]
        current_opacity = getattr(selected_layer, "opacity", max_opacity)
        slider = widgets.FloatSlider(
            value=max(min(current_opacity, max_opacity), min_opacity),
            min=min_opacity,
            max=max_opacity,
            step=step,
            description="Opacity",
            readout=True,
            readout_format=".2f",
            layout=widgets.Layout(width="260px"),
        )

        status = widgets.Label()

        def set_status(msg: str) -> None:
            status.value = msg

        def apply_opacity(target: ipyleaflet.Layer, value: float) -> None:
            try:
                setattr(target, "opacity", value)
            except Exception as exc:  # pragma: no cover - defensive
                set_status(f"Failed to set opacity: {exc}")
            else:
                set_status(f"{target.__class__.__name__} opacity: {value:.2f}")

        def on_slider(change: Dict[str, Any]) -> None:
            if change["name"] != "value" or change["new"] == change["old"]:
                return
            lyr = layer_lookup[dropdown.value]
            apply_opacity(lyr, change["new"])

        def on_dropdown(change: Dict[str, Any]) -> None:
            if change["name"] != "value" or change["new"] == change["old"]:
                return
            lyr = layer_lookup[change["new"]]
            slider.value = max(
                min(getattr(lyr, "opacity", slider.value), max_opacity), min_opacity
            )
            apply_opacity(lyr, slider.value)

        slider.observe(on_slider, "value")
        dropdown.observe(on_dropdown, "value")

        apply_opacity(selected_layer, slider.value)

        panel = widgets.VBox([dropdown, slider])
        control = ipyleaflet.WidgetControl(widget=panel, position=position)
        self.add(control)
        self.opacity_control = control

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

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

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

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

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

        tif, vars = common.netcdf_to_tif(
            filename,
            shift_lon=shift_lon,
            lat=lat,
            lon=lon,
            lev=lev,
            level_index=level_index,
            time=time,
            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_shp(
        self,
        in_shp: str,
        layer_name: Optional[str] = "Untitled",
        style: Optional[Dict] = {},
        hover_style: Optional[Dict] = {},
        style_callback: Optional[Callable] = None,
        fill_colors: Optional[list[str]] = None,
        info_mode: Optional[str] = "on_hover",
        zoom_to_layer: Optional[bool] = False,
        encoding: Optional[str] = "utf-8",
        **kwargs,
    ) -> None:
        """Adds a shapefile to the map.

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

        Raises:
            FileNotFoundError: The provided shapefile could not be found.
        """

        import geopandas as gpd

        gdf = gpd.read_file(in_shp, encoding=encoding)
        self.add_gdf(
            gdf,
            layer_name,
            style,
            hover_style,
            style_callback,
            fill_colors,
            info_mode,
            zoom_to_layer,
            encoding,
            **kwargs,
        )

    def add_geojson(
        self,
        in_geojson: Union[str, Dict],
        layer_name: Optional[str] = "Untitled",
        style: Optional[dict] = {},
        hover_style: Optional[dict] = {},
        style_callback: Optional[Callable] = None,
        fill_colors: Optional[list[str]] = None,
        info_mode: Optional[str] = "on_hover",
        zoom_to_layer: Optional[bool] = False,
        encoding: Optional[str] = "utf-8",
        **kwargs,
    ) -> None:
        """Adds a GeoJSON file to the map.

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

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

        import geopandas as gpd

        gdf = None

        try:
            if isinstance(in_geojson, str):
                if in_geojson.startswith("http"):
                    if common.is_jupyterlite():
                        import pyodide  # pylint: disable=E0401

                        output = os.path.basename(in_geojson)

                        output = os.path.abspath(output)
                        obj = pyodide.http.open_url(in_geojson)
                        with open(output, "w") as fd:
                            shutil.copyfileobj(obj, fd)
                        with open(output, "r") as fd:
                            data = json.load(fd)
                    else:
                        gdf = gpd.read_file(in_geojson, encoding=encoding)

                else:
                    gdf = gpd.read_file(in_geojson, encoding=encoding)

            elif isinstance(in_geojson, dict):
                if in_geojson.get("type") == "Feature":
                    gdf = gpd.GeoDataFrame.from_features([in_geojson])
                else:
                    gdf = gpd.GeoDataFrame.from_features(in_geojson)
            elif isinstance(in_geojson, gpd.GeoDataFrame):
                gdf = in_geojson
            else:
                raise TypeError("The input geojson must be a type of str or dict.")
        except Exception as e:
            raise Exception(e)

        if gdf.crs is None:
            # print(
            #     f"Warning: The dataset does not have a CRS defined. Assuming EPSG:4326."
            # )
            gdf.crs = "EPSG:4326"
        elif gdf.crs != "EPSG:4326":
            gdf = gdf.to_crs("EPSG:4326")
        data = gdf.__geo_interface__

        try:
            first_feature = data["features"][0]
            if isinstance(first_feature["properties"].get("style"), str):
                # Loop through the features and update the style
                for feature in data["features"]:
                    fstyle = feature["properties"].get("style")
                    if isinstance(fstyle, str):
                        feature["properties"]["style"] = json.loads(fstyle)
        except Exception as e:
            print(e)
            pass

        geom_type = gdf.reset_index().geom_type[0]

        if style is None and (style_callback is None):
            style = {
                # "stroke": True,
                "color": "#3388ff",
                "weight": 2,
                "opacity": 1,
                "fill": True,
                "fillColor": "#3388ff",
                "fillOpacity": 0.2,
                # "dashArray": "9"
                # "clickable": True,
            }

            if geom_type in ["LineString", "MultiLineString"]:
                style["fill"] = False

        elif "weight" not in style:
            style["weight"] = 1

        if not hover_style:
            hover_style = {
                "weight": style["weight"] + 2,
                "fillOpacity": 0,
                "color": "yellow",
            }

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

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

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

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

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

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

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

        toolbar_button.observe(toolbar_btn_click, "value")

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

        close_button.observe(close_btn_click, "value")

        if "fields" in kwargs:
            fields = kwargs["fields"]
            kwargs.pop("fields")
        else:
            fields = None

        def update_html(feature, fields=fields, **kwargs):
            if fields is None:
                fields = list(feature["properties"].keys())
                if "style" in fields:
                    fields.remove("style")

            value = [
                "<b>{}: </b>{}<br>".format(prop, feature["properties"][prop])
                for prop in fields
            ]

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

        if fill_colors is not None:
            style_callback = random_color

        if style_callback is None:
            geojson = ipyleaflet.GeoJSON(
                data=data,
                style=style,
                hover_style=hover_style,
                name=layer_name,
                **kwargs,
            )
        else:
            geojson = ipyleaflet.GeoJSON(
                data=data,
                style=style,
                hover_style=hover_style,
                name=layer_name,
                style_callback=style_callback,
                **kwargs,
            )

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

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

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

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

        if zoom_to_layer:
            try:
                bounds = gdf.total_bounds
                west, south, east, north = bounds
                self.fit_bounds([[south, east], [north, west]])
            except Exception as e:
                print(e)

    def add_search_control(
        self,
        url: str,
        marker: Optional[ipyleaflet.Marker] = None,
        zoom: Optional[int] = None,
        position: Optional[str] = "topleft",
        **kwargs,
    ) -> None:
        """Adds a search control to the map.

        Args:
            url (str): The url to the search API. For example, "https://nominatim.openstreetmap.org/search?format=json&q={s}".
            marker (ipyleaflet.Marker, optional): The marker to be used for the search result. Defaults to None.
            zoom (int, optional): The zoom level to be used for the search result. Defaults to None.
            position (str, optional): The position of the search control. Defaults to "topleft".
            kwargs (dict, optional): Additional keyword arguments to be passed to the search control. See https://ipyleaflet.readthedocs.io/en/latest/api_reference/search_control.html
        """
        if marker is None:
            marker = ipyleaflet.Marker(
                icon=ipyleaflet.AwesomeIcon(
                    name="check", marker_color="green", icon_color="darkred"
                )
            )
        search_control = ipyleaflet.SearchControl(
            position=position,
            url=url,
            zoom=zoom,
            marker=marker,
        )
        self.add(search_control)
        self.search_control = search_control

    def add_gdf(
        self,
        gdf,
        layer_name: Optional[str] = "Untitled",
        style: Optional[dict] = {},
        hover_style: Optional[dict] = {},
        style_callback: Optional[Callable] = None,
        fill_colors: Optional[list[str]] = None,
        info_mode: Optional[str] = "on_hover",
        zoom_to_layer: Optional[bool] = False,
        encoding: Optional[str] = "utf-8",
        **kwargs,
    ) -> None:
        """Adds a GeoDataFrame to the map.

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

        self.add_geojson(
            gdf,
            layer_name,
            style,
            hover_style,
            style_callback,
            fill_colors,
            info_mode,
            zoom_to_layer,
            encoding,
            **kwargs,
        )

    def add_gdf_time_slider(
        self,
        gdf: "gpd.GeoDataFrame",
        time_columns: Optional[List[str]] = None,
        labels: Optional[List[str]] = None,
        time_interval: Optional[int] = 1,
        position: Optional[str] = "bottomright",
        slider_length: Optional[str] = "150px",
        zoom_to_layer: Optional[bool] = False,
        style: Optional[Dict] = None,
        **kwargs,
    ):
        from .toolbar import time_slider_for_gdf

        time_slider_for_gdf(
            self,
            gdf,
            time_columns,
            labels,
            time_interval,
            position,
            slider_length,
            zoom_to_layer,
            style,
            **kwargs,
        )

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

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

    def add_kml(
        self,
        in_kml: str,
        layer_name: Optional[str] = "Untitled",
        style: Optional[dict] = {},
        hover_style: Optional[dict] = {},
        style_callback: Optional[Callable] = None,
        fill_colors: Optional[list[str]] = None,
        info_mode: Optional[str] = "on_hover",
        **kwargs,
    ) -> None:
        """Adds a KML file to the map.

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

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

        if in_kml.startswith("http") and in_kml.endswith(".kml"):
            out_dir = os.path.abspath("./cache")
            if not os.path.exists(out_dir):
                os.makedirs(out_dir)
            in_kml = common.download_file(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.")

        self.add_vector(
            in_kml,
            layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            fill_colors=fill_colors,
            info_mode=info_mode,
            **kwargs,
        )

    def add_vector(
        self,
        filename: str,
        layer_name: Optional[str] = "Untitled",
        bbox: Optional[tuple] = None,
        mask: Optional[dict] = None,
        rows: Optional[tuple[int]] = None,
        style: Optional[dict] = {},
        hover_style: Optional[dict] = {},
        style_callback: Optional[Callable] = None,
        fill_colors: list[str] = None,
        info_mode: Optional[str] = "on_hover",
        zoom_to_layer: Optional[bool] = False,
        encoding: Optional[str] = "utf-8",
        **kwargs,
    ) -> None:
        """Adds any geopandas-supported vector dataset to the map.

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

        """
        import fiona
        import geopandas as gpd

        if isinstance(filename, str) and filename.endswith(".kml"):
            fiona.drvsupport.supported_drivers["KML"] = "rw"
            kwargs["driver"] = "KML"

        gdf = gpd.read_file(
            filename, bbox=bbox, mask=mask, rows=rows, encoding=encoding, **kwargs
        )

        self.add_gdf(
            gdf,
            layer_name,
            style,
            hover_style,
            style_callback,
            fill_colors,
            info_mode,
            zoom_to_layer,
            encoding,
            **kwargs,
        )

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

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

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

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

        col_names = df.columns.values.tolist()

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

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

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

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

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

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

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

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

    def add_point_layer(
        self,
        filename: str,
        popup: Optional[Union[list, str]] = None,
        layer_name: Optional[str] = "Marker Cluster",
        **kwargs,
    ) -> None:
        """Adds a point layer to the map with a popup attribute.

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

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

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

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

        if isinstance(filename, gpd.GeoDataFrame):
            gdf = filename
        else:
            if not filename.startswith("http"):
                filename = os.path.abspath(filename)
            ext = os.path.splitext(filename)[1].lower()
            if ext == ".kml":
                fiona.drvsupport.supported_drivers["KML"] = "rw"
                gdf = gpd.read_file(filename, driver="KML", **kwargs)
            else:
                gdf = gpd.read_file(filename, **kwargs)
        df = gdf.to_crs(epsg="4326")
        col_names = df.columns.values.tolist()
        if popup is not None:
            if isinstance(popup, str) and (popup not in col_names):
                raise ValueError(
                    f"popup must be one of the following: {', '.join(col_names)}"
                )
            elif isinstance(popup, list) and (
                not all(item in col_names for item in popup)
            ):
                raise ValueError(
                    f"All popup items must be select from: {', '.join(col_names)}"
                )

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

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

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

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

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

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

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

    def add_points_from_xy(
        self,
        data: Optional[Union[pd.DataFrame, str]],
        x: Optional[str] = "longitude",
        y: Optional[str] = "latitude",
        popup: Optional[list] = None,
        layer_name: Optional[str] = "Marker Cluster",
        color_column: Optional[str] = None,
        marker_colors: Optional[str] = None,
        icon_colors: Optional[list[str]] = ["white"],
        icon_names: Optional[list[str]] = ["info"],
        spin: Optional[bool] = False,
        add_legend: Optional[bool] = True,
        max_cluster_radius: Optional[int] = 80,
        **kwargs,
    ) -> None:
        """Adds a marker cluster to the map.

        Args:
            data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
            x (str, optional): The column name for the x values. Defaults to "longitude".
            y (str, optional): The column name for the y values. Defaults to "latitude".
            popup (list, optional): A list of column names to be used as the popup. Defaults to None.
            layer_name (str, optional): The name of the layer. Defaults to "Marker Cluster".
            color_column (str, optional): The column name for the color values. Defaults to None.
            marker_colors (list, optional): A list of colors to be used for the markers. Defaults to None.
            icon_colors (list, optional): A list of colors to be used for the icons. Defaults to ['white'].
            icon_names (list, optional): A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons. Defaults to ['info'].
            spin (bool, optional): If True, the icon will spin. Defaults to False.
            add_legend (bool, optional): If True, a legend will be added to the map. Defaults to True.
            max_cluster_radius (int, optional): The maximum cluster radius. Defaults to 80.
            **kwargs: Other keyword arguments to pass to ipyleaflet.MarkerCluster(). For a list of available options,
                see https://github.com/Leaflet/Leaflet.markercluster.

        """
        import pandas as pd

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

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

            gdf = gpd.read_file(data)
            df = common.gdf_to_df(gdf)

        df = common.points_from_xy(df, x, y)

        col_names = df.columns.values.tolist()

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

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

        else:
            items = None

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    add_marker_cluster = add_points_from_xy

    def add_heatmap(
        self,
        data: Union[str, list, pd.DataFrame],
        latitude: Optional[str] = "latitude",
        longitude: Optional[str] = "longitude",
        value: Optional[str] = "value",
        name: Optional[str] = "Heat map",
        radius: Optional[int] = 25,
        **kwargs,
    ) -> None:
        """Adds a heat map to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/heatmap.html

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

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

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

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

        except Exception as e:
            raise Exception(e)

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

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

        """
        import warnings

        import pandas as pd

        warnings.filterwarnings("ignore")

        if isinstance(data, pd.DataFrame):
            df = data
            if "geometry" in data.columns or ("geom" in data.columns):
                df[x] = df.centroid.x
                df[y] = df.centroid.y

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

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

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

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

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

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

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

    def add_planet_by_month(
        self,
        year: Optional[int] = 2016,
        month: Optional[int] = 1,
        layer_name: Optional[str] = None,
        api_key: Optional[str] = None,
        token_name: Optional[str] = "PLANET_API_KEY",
        **kwargs,
    ) -> 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 (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
            month (int, optional): The month of Planet global mosaic, must be 1-12. Defaults to 1.
            layer_name (str, optional): The layer name to use. Defaults to None.
            api_key (str, optional): The Planet API key. Defaults to None.
            token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
        """
        if layer_name is None and "name" in kwargs:
            layer_name = kwargs.pop("name")
        layer = common.planet_tile_by_month(
            year, month, layer_name, api_key, token_name
        )
        self.add(layer)

    def add_planet_by_quarter(
        self,
        year: Optional[int] = 2016,
        quarter: Optional[int] = 1,
        layer_name: Optional[str] = None,
        api_key: Optional[str] = None,
        token_name: Optional[str] = "PLANET_API_KEY",
        **kwargs,
    ) -> 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 (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
            quarter (int, optional): The quarter of Planet global mosaic, must be 1-12. Defaults to 1.
            layer_name (str, optional): The layer name to use. Defaults to None.
            api_key (str, optional): The Planet API key. Defaults to None.
            token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
        """
        if layer_name is None and "name" in kwargs:
            layer_name = kwargs.pop("name")
        layer = common.planet_tile_by_quarter(
            year, quarter, layer_name, api_key, token_name
        )
        self.add(layer)

    def add_time_slider(
        self,
        layers: dict = {},
        labels: list = None,
        time_interval: int = 1,
        position: str = "bottomright",
        slider_length: str = "150px",
        zoom_to_layer: Optional[bool] = False,
        tile_args: Optional[Dict] = None,
        **kwargs,
    ) -> None:
        """Adds a time slider to the map.

        Args:
            layers (dict, optional): The dictionary containing a set of XYZ tile layers.
            labels (list, optional): The list of labels to be used for the time series. Defaults to None.
            time_interval (int, optional): Time interval in seconds. Defaults to 1.
            position (str, optional): Position to place the time slider, can be any of ['topleft', 'topright', 'bottomleft', 'bottomright']. Defaults to "bottomright".
            slider_length (str, optional): Length of the time slider. Defaults to "150px".
            zoom_to_layer (bool, optional): Whether to zoom to the extent of the selected layer. Defaults to False.
            tile_args (dict, optional): Additional arguments to pass to the get_local_tile_layer function. Defaults to None.
        """
        from .toolbar import time_slider

        time_slider(
            self,
            layers,
            labels,
            time_interval,
            position,
            slider_length,
            zoom_to_layer,
            tile_args,
            **kwargs,
        )

    def static_map(
        self,
        width: int = 950,
        height: int = 600,
        out_file: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Display an ipyleaflet static map in a Jupyter Notebook.

        Args
            m (ipyleaflet.Map): An ipyleaflet map.
            width (int, optional): Width of the map. Defaults to 950.
            height (int, optional): Height of the map. Defaults to 600.
            read_only (bool, optional): Whether to hide the side panel to disable map customization. Defaults to False.
            out_file (str, optional): Output html file path. Defaults to None.
        """
        if isinstance(self, ipyleaflet.Map):
            if out_file is None:
                out_file = "./cache/" + "leafmap_" + common.random_string(3) + ".html"
            out_dir = os.path.abspath(os.path.dirname(out_file))
            if not os.path.exists(out_dir):
                os.makedirs(out_dir)

            self.to_html(out_file)
            common.display_html(out_file, width=width, height=height)
        else:
            raise TypeError("The provided map is not an ipyleaflet map.")

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

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

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

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

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

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

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

        except Exception as e:
            raise Exception(e)

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

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

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

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

    def add_title(
        self,
        title: str,
        align: str = "center",
        font_size: str = "16px",
        style=None,
        **kwargs,
    ) -> None:
        print("The ipyleaflet map does not support titles.")

    def get_pc_collections(self) -> None:
        """Get the list of Microsoft Planetary Computer collections."""
        if not hasattr(self, "pc_collections"):
            setattr(self, "pc_collections", pc.get_pc_collections())

    def save_draw_features(
        self, out_file: str, crs: Optional[str] = "EPSG:4326", **kwargs
    ) -> None:
        """Save the draw features to a file.

        Args:
            out_file (str): The output file path.
            crs (str, optional): The CRS of the output GeoJSON. Defaults to "EPSG:4326".
        """

        if self.user_rois is not None:
            import geopandas as gpd

            out_file = common.check_file_path(out_file)

            self.update_draw_features()
            geojson = {
                "type": "FeatureCollection",
                "features": self.draw_features,
            }

            gdf = gpd.GeoDataFrame.from_features(geojson, crs="EPSG:4326")
            if crs != "EPSG:4326":
                gdf = gdf.to_crs(crs)
            gdf.to_file(out_file, **kwargs)
        else:
            print("No draw features to save.")

    def update_draw_features(self) -> None:
        """Update the draw features by removing features that have been edited and no longer exist."""

        geometries = [feature["geometry"] for feature in self.draw_control.data]

        for feature in self.draw_features:
            if feature["geometry"] not in geometries:
                self.draw_features.remove(feature)

    def get_draw_props(
        self, n: Optional[int] = None, return_df: bool = False
    ) -> pd.DataFrame:
        """Get the properties of the draw features.

        Args:
            n (int, optional): The maximum number of attributes to return. Defaults to None.
            return_df (bool, optional): If True, return a pandas dataframe. Defaults to False.

        Returns:
            pd.DataFrame: A pandas dataframe containing the properties of the draw features.
        """

        import pandas as pd

        props = self.edit_props[:]

        for feature in self.draw_features:
            for prop in feature["properties"]:
                if prop not in self.edit_props:
                    self.edit_props.append(prop)
                    props.append(prop)

        if return_df:
            if isinstance(n, int) and n > len(props):
                props = props + [""] * (n - len(props))

            df = pd.DataFrame({"Key": props, "Value": [""] * len(props)})
            df.index += 1
            return df
        else:
            return props

    def update_draw_props(self, df: pd.DataFrame) -> None:
        """Update the draw features properties.

        Args:
            df (pd.DataFrame): A pandas dataframe containing the properties of the draw features.
        """

        df.dropna(inplace=True)
        df = df[df["Key"].astype(bool)]
        if len(df) > 0:
            props = df.set_index("Key").to_dict()["Value"]
            if self.draw_control.last_action == "edited":
                self.update_draw_features()
            if len(self.draw_features) > 0:
                if self.draw_control.last_action == "created":
                    self.draw_features[-1]["properties"] = props
                elif self.draw_control.last_action == "edited":
                    for feature in self.draw_features:
                        if (
                            self.draw_control.last_draw["geometry"]
                            == feature["geometry"]
                        ):
                            feature["properties"] = props
            for prop in list(props.keys()):
                if prop not in self.edit_props:
                    self.edit_props.append(prop)

    def edit_vector(self, data: Union[dict, str], **kwargs) -> None:
        """Edit a vector layer.

        Args:
            data (dict | str): The data to edit. It can be a GeoJSON dictionary or a file path.
        """
        if isinstance(data, str):
            common.check_package("geopandas", "https://geopandas.org")
            import geopandas as gpd

            gdf = gpd.read_file(data, **kwargs)
            geojson = common.gdf_to_geojson(gdf, epsg=4326, tuple_to_list=True)
        elif isinstance(data, dict):
            geojson = data
        else:
            raise ValueError(
                "The data must be a GeoJSON dictionary or a file path to a vector dataset."
            )
        self.draw_control.data = self.draw_control.data + (geojson["features"])
        self.draw_features = self.draw_features + (geojson["features"])

    def add_velocity(
        self,
        data: str,
        zonal_speed: str,
        meridional_speed: str,
        latitude_dimension: str = "lat",
        longitude_dimension: str = "lon",
        level_dimension: Optional[str] = "lev",
        level_index: int = 0,
        time_index: int = 0,
        velocity_scale: float = 0.01,
        max_velocity: int = 20,
        display_options: Optional[dict] = {},
        name: Optional[str] = "Velocity",
        color_scale: Optional[list] = None,
    ) -> None:
        """Add a velocity layer to the map.

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

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

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

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

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

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

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

        if color_scale is None:
            color_scale = [
                "rgb(36,104, 180)",
                "rgb(60,157, 194)",
                "rgb(128,205,193)",
                "rgb(151,218,168)",
                "rgb(198,231,181)",
                "rgb(238,247,217)",
                "rgb(255,238,159)",
                "rgb(252,217,125)",
                "rgb(255,182,100)",
                "rgb(252,150,75)",
                "rgb(250,112,52)",
                "rgb(245,64,32)",
                "rgb(237,45,28)",
                "rgb(220,24,32)",
                "rgb(180,0,35)",
            ]

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

    def add_data(
        self,
        data: Union[str, pd.DataFrame],
        column: str,
        colors: Optional[str] = None,
        labels: Optional[str] = None,
        cmap: Optional[str] = None,
        scheme: Optional[str] = "Quantiles",
        k: int = 5,
        add_legend: Optional[bool] = True,
        legend_title: Optional[bool] = None,
        legend_position: Optional[str] = "bottomright",
        legend_kwds: Optional[dict] = None,
        classification_kwds: Optional[dict] = None,
        layer_name: Optional[str] = "Untitled",
        style: Optional[dict] = None,
        hover_style: Optional[dict] = None,
        style_callback: Optional[dict] = None,
        marker_radius: int = 10,
        marker_args=None,
        info_mode: Optional[str] = "on_hover",
        encoding: Optional[str] = "utf-8",
        **kwargs,
    ) -> None:
        """Add vector data to the map with a variety of classification schemes.

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

        """

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

        if legend_title is None:
            legend_title = column

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

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

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

        if gdf.geometry.geom_type.unique().tolist()[0] == "Point":
            columns = gdf.columns.tolist()
            if "category" in columns:
                columns.remove("category")
            if "color" in columns:
                columns.remove("color")
            if marker_args is None:
                marker_args = {}
            if "fill_color" not in marker_args:
                marker_args["fill_color"] = gdf["color"].tolist()
            if "stroke" not in marker_args:
                marker_args["stroke"] = False
            if "fill_opacity" not in marker_args:
                marker_args["fill_opacity"] = 0.8

            marker_args["radius"] = marker_radius

            self.add_markers(gdf[columns], layer_name=layer_name, **marker_args)
        else:
            self.add_gdf(
                gdf,
                layer_name=layer_name,
                style=style,
                hover_style=hover_style,
                style_callback=style_callback,
                info_mode=info_mode,
                encoding=encoding,
                **kwargs,
            )
        if add_legend:
            self.add_legend(
                title=legend_title, legend_dict=legend_dict, position=legend_position
            )

    def user_roi_bounds(self, decimals: int = 4) -> list:
        """Get the bounds of the user drawn ROI as a tuple of (minx, miny, maxx, maxy).

        Args:
            decimals (int, optional): The number of decimals to round the coordinates to. Defaults to 4.

        Returns:
            list: The bounds of the user drawn ROI as a tuple of (minx, miny, maxx, maxy).
        """
        if self.user_roi is not None:
            return common.geometry_bounds(self.user_roi, decimals=decimals)
        else:
            return None

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

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

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

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

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

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

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

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

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

        """
        import requests

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

        self.add_widget(image, position=position)

    def add_html(
        self, html: str, position: Optional[str] = "bottomright", **kwargs
    ) -> None:
        """Add HTML to the map.

        Args:
            html (str): The HTML to add.
            position (str, optional): The position of the HTML, can be one of "topleft",
                "topright", "bottomleft", "bottomright". Defaults to "bottomright".
        """
        # Check if an HTML string contains local images and convert them to base64.
        html = common.check_html_string(html)
        self.add_widget(html, position=position, **kwargs)

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

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

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

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

    def add_bbox(
        self,
        bbox: Union[List[float], Tuple[float, float, float, float], Sequence[float]],
        layer_name: str = "Bounding Box",
        color: str = "blue",
        fill_color: Optional[str] = None,
        fill_opacity: float = 0.1,
        weight: int = 2,
        **kwargs,
    ) -> None:
        """
        Add a bbox defined by [x_min, y_min, x_max, y_max] to the map.

        Args:
            bbox: A list or tuple containing four numbers representing the
                  bounding box: [x_min, y_min, x_max, y_max]. Assumed to be
                  in longitude/latitude coordinates.
            layer_name: The name to assign to the GeoJSON layer.
                        Defaults to "Bounding Box".
            color: The color of the bounding box outline (stroke).
                   Defaults to "blue".
            fill_color: The fill color of the bounding box. If None, the box
                        will not be filled. Defaults to None.
            fill_opacity: The opacity of the fill color (only used if
                          fill_color is provided). Value should be between
                          0.0 and 1.0. Defaults to 0.1.
            weight: The thickness of the bounding box outline (stroke).
                    Defaults to 2.
            **kwargs: Additional keyword arguments to pass directly to the
                      underlying `add_geojson` method (e.g., `popup`,
                      `tooltip`, `hover_style`).
        Raises:
            ValueError: If `bbox` is not a list or tuple of exactly four numbers,
                        if the coordinates cannot be converted to floats, or if
                        x_min > x_max or y_min > y_max.
        """
        if not isinstance(bbox, (list, tuple)) or len(bbox) != 4:
            raise ValueError(
                "bbox must be a list or tuple of four numbers [minx, miny, maxx, maxy]"
            )

        try:
            x_min, y_min, x_max, y_max = map(float, bbox)
        except (ValueError, TypeError) as e:
            raise ValueError(f"bbox coordinates must be valid numbers. Error {e}.")

        if x_min > x_max or y_min > y_max:
            raise ValueError(
                "x_min must be less than or equal to x_max and y_min must be less than or equal to y_max."
            )

        # define the 4 (+ closing point) corners in counter-clockwise order [longitude, latitude].
        coordinates = [
            [
                [x_min, y_min],  # bottom-left
                [x_max, y_min],  # bottom-right
                [x_max, y_max],  # top-right
                [x_min, y_max],  # top-left
                [x_min, y_min],
            ]
        ]

        # create a FeatureCollection (required by add_geojson).
        geojson_data = {
            "type": "FeatureCollection",
            "features": [
                # add the bbox feature.
                {
                    "type": "Feature",
                    "properties": {},
                    "geometry": {"type": "Polygon", "coordinates": coordinates},
                }
            ],
        }

        style = {
            "stroke": True,
            "color": color,
            "weight": weight,
            "opacity": 1,
            "fillColor": fill_color if fill_color else color,
            "fillOpacity": fill_opacity if fill_color else 0,
            "fill": fill_color is not None,
        }

        self.add_geojson(geojson_data, style=style, layer_name=layer_name, **kwargs)

    def get_bbox(self) -> list:
        """Get the bounds of the map as a list of [(]minx, miny, maxx, maxy].

        Returns:
            list: The bounds of the map as a list of [(]minx, miny, maxx, maxy].
        """
        bounds = self.bounds
        bbox = [bounds[0][1], bounds[0][0], bounds[1][1], bounds[1][0]]
        return bbox

    def oam_search(
        self,
        bbox: Optional[Union[list, str]] = None,
        start_date: str = None,
        end_date: str = None,
        limit: int = 100,
        info_mode: str = "on_click",
        layer_args: Optional[dict] = {},
        add_image: Optional[bool] = True,
        **kwargs,
    ) -> None:
        """Search OpenAerialMap for images within a bounding box and time range.

        Args:
            bbox (list | str, optional): The bounding box [xmin, ymin, xmax, ymax] to search within. Defaults to None.
            start_date (str, optional): The start date to search within, such as "2015-04-20T00:00:00.000Z". Defaults to None.
            end_date (str, optional): The end date to search within, such as "2015-04-21T00:00:00.000Z". Defaults to None.
            limit (int, optional): The maximum number of results to return. Defaults to 100.
            info_mode (str, optional): The mode to use for the info popup. Can be 'on_hover' or 'on_click'. Defaults to 'on_click'.
            layer_args (dict, optional): The layer arguments for add_gdf() function. Defaults to {}.
            add_image (bool, optional): Whether to add the first 10 images to the map. Defaults to True.
            **kwargs: Additional keyword arguments to pass to the API. See https://hotosm.github.io/oam-api/
        """

        bounds = self.bounds
        if bbox is None:
            if self.user_roi is not None:
                bbox = self.user_roi_bounds()
            else:
                bbox = [bounds[0][1], bounds[0][0], bounds[1][1], bounds[1][0]]

        if self.zoom <= 4:
            print("Zoom in to search for images")
            return None

        gdf = common.oam_search(
            bbox=bbox, start_date=start_date, end_date=end_date, limit=limit, **kwargs
        )

        if "layer_name" not in layer_args:
            layer_args["layer_name"] = "Footprints"

        if "style" not in layer_args:
            layer_args["style"] = {
                # "stroke": True,
                "color": "#3388ff",
                "weight": 2,
                "opacity": 1,
                # "fill": True,
                # "fillColor": "#ffffff",
                "fillOpacity": 0,
                # "dashArray": "9"
                # "clickable": True,
            }

        if "hover_style" not in layer_args:
            layer_args["hover_style"] = {"weight": layer_args["style"]["weight"] + 2}

        if gdf is not None:
            setattr(self, "oam_gdf", gdf)
            self.add_gdf(gdf, info_mode=info_mode, **layer_args)

            if add_image:
                ids = gdf["_id"].tolist()
                images = gdf["tms"].tolist()

                if len(images) > 5:
                    print(f"Found {len(images)} images. \nShowing the first 5.")

                for index, image in enumerate(images):
                    if index == 5:
                        break
                    self.add_tile_layer(
                        url=image, name=ids[index], attribution="OpenAerialMap"
                    )
        else:
            print("No images found.")

    def set_catalog_source(self, source: Optional[str]) -> None:
        """Set the catalog source.

        Args:
            catalog_source (str, optional): The catalog source. Defaults to "landsat".
        """
        if not isinstance(source, dict):
            raise TypeError(
                "The source must be a dictionary in the format of {label: url, label2:url2}, \
                such as {'Element84': 'https://earth-search.aws.element84.com/v1'}"
            )
        if not hasattr(self, "_STAC_CATALOGS"):
            self.catalog_source = {}

        self._STAC_CATALOGS = source

    def clear_drawings(self) -> None:
        """Clear drawings on the map."""
        self.draw_control.clear()
        self.draw_features = []
        self.user_rois = None
        self.user_roi = None

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

        Args:
            position (str, optional): The position of the Layer Manager. Defaults to "topright".
        """
        from .toolbar import layer_manager_gui

        layer_manager_gui(self, position, opened)

    def update_layer_manager(self) -> None:
        """Update the Layer Manager."""
        from .toolbar import layer_manager_gui

        self._layer_manager_widget.children = layer_manager_gui(
            self, return_widget=True
        )

    def add_oam_gui(
        self, position: Optional[str] = "topright", opened: bool = True
    ) -> None:
        """Add the OpenAerialMap search widget to the map.

        Args:
            position (str, optional): The position of the widget. Defaults to "topright".
            opened (bool, optional): Whether the widget is open. Defaults to True.
        """
        from .toolbar import oam_search_gui

        oam_search_gui(self, position, opened)

    def add_stac_gui(self, position: str = "topright", opened: bool = True) -> None:
        """Add the STAC search widget to the map.

        Args:
            position (str, optional): The position of the widget. Defaults to "topright".
            opened (bool, optional): Whether the widget is open. Defaults to True.
        """
        from .toolbar import stac_gui

        stac_gui(self, position, opened)

    def add_inspector_gui(
        self, position: Optional[str] = "topright", opened: bool = True
    ) -> None:
        """Add the Inspector widget to the map.

        Args:
            position (str, optional): The position of the widget. Defaults to "topright".
            opened (bool, optional): Whether the widget is open. Defaults to True.
        """

        from .toolbar import inspector_gui

        inspector_gui(self, position, opened)

    def add_basemap_gui(self, position: Optional[str] = "topright") -> None:
        """Add the basemap widget to the map.

        Args:
            position (str, optional): The position of the widget. Defaults to "topright".
        """
        from .toolbar import change_basemap

        change_basemap(self, position)

    def _add_layer_editor(self, position: str, **kwargs) -> None:
        if self._layer_editor:
            return

        widget = map_widgets.LayerEditor(self, **kwargs)
        widget.on_close = lambda: self.remove("layer_editor")
        control = ipyleaflet.WidgetControl(widget=widget, position=position)
        super().add(control)

    def _find_widget_of_type(
        self, widget_type: Type, return_control: bool = False
    ) -> Optional[Any]:
        """Finds a widget in the controls with the passed in type."""
        for widget in self.controls:
            if isinstance(widget, ipyleaflet.WidgetControl):
                if isinstance(widget.widget, widget_type):
                    return widget if return_control else widget.widget
            elif isinstance(widget, widget_type):
                return widget
        return None

    def remove(self, widget: Any) -> None:
        """Removes a widget to the map."""

        basic_controls: Dict[str, ipyleaflet.Control] = {
            "layer_editor": map_widgets.LayerEditor,
        }
        if widget_type := basic_controls.get(widget, None):
            if control := self._find_widget_of_type(widget_type, return_control=True):
                self.remove(control)
                control.close()
            return

        super().remove(widget)
        if isinstance(widget, widgets.Widget):
            widget.close()

    def edit_points(
        self,
        data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
        display_props: Optional[List[str]] = None,
        widget_width: str = "250px",
        name: str = "Points",
        radius: int = 5,
        color: str = "white",
        weight: int = 1,
        fill_color: str = "#3388ff",
        fill_opacity: float = 0.6,
        **kwargs: Any,
    ) -> None:
        """
        Edit points on a map by creating interactive circle markers with popups.

        Args:
            data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data source,
                which can be a file path, GeoDataFrame, or GeoJSON dictionary.
            display_props (Optional[List[str]], optional): List of properties to
                display in the popup. Defaults to None.
            widget_width (str, optional): Width of the widget in the popup.
                Defaults to "250px".
            name (str, optional): Name of the layer group. Defaults to "Points".
            radius (int, optional): Initial radius of the circle markers. Defaults to 5.
            color (str, optional): Outline color of the circle markers. Defaults to "white".
            weight (int, optional): Outline weight of the circle markers. Defaults to 1.
            fill_color (str, optional): Fill color of the circle markers. Defaults to "#3388ff".
            fill_opacity (float, optional): Fill opacity of the circle markers. Defaults to 0.6.
            **kwargs (Any): Additional arguments for the CircleMarker.

        Returns:
            None
        """

        import geopandas as gpd
        from ipyleaflet import CircleMarker, Popup

        if isinstance(data, gpd.GeoDataFrame):
            if data.crs != "EPSG:4326":
                data = data.to_crs("EPSG:4326")
            geojson_data = data.__geo_interface__
        elif isinstance(data, str):
            data = gpd.read_file(data)
            if data.crs != "EPSG:4326":
                data = data.to_crs("EPSG:4326")
            geojson_data = data.__geo_interface__
        elif isinstance(data, dict):
            geojson_data = data
        else:
            raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

        self._geojson_data = geojson_data

        def create_popup_widget(
            circle_marker, properties, original_properties, display_properties=None
        ):
            """Create a popup widget to change circle properties and edit feature attributes."""
            # Widgets for circle properties
            radius_slider = widgets.IntSlider(
                value=circle_marker.radius,
                min=1,
                max=50,
                description="Radius:",
                continuous_update=False,
                layout=widgets.Layout(width=widget_width),
            )

            color_picker = widgets.ColorPicker(
                value=circle_marker.color,
                description="Color:",
                continuous_update=False,
                layout=widgets.Layout(width=widget_width),
            )

            fill_color_picker = widgets.ColorPicker(
                value=circle_marker.fill_color,
                description="Fill color:",
                continuous_update=False,
                layout=widgets.Layout(width=widget_width),
            )

            # Widgets for feature properties
            property_widgets = {}
            display_properties = display_properties or properties.keys()
            for key in display_properties:
                value = properties.get(key, "")
                if isinstance(value, str):
                    widget = widgets.Text(
                        value=value,
                        description=f"{key}:",
                        continuous_update=False,
                        layout=widgets.Layout(width=widget_width),
                    )
                elif isinstance(value, (int, float)):
                    widget = widgets.FloatText(
                        value=value,
                        description=f"{key}:",
                        continuous_update=False,
                        layout=widgets.Layout(width=widget_width),
                    )
                else:
                    widget = widgets.Label(
                        value=f"{key}: {value}",
                        layout=widgets.Layout(width=widget_width),
                    )

                property_widgets[key] = widget

            def update_circle(change):
                """Update circle properties based on widget values."""
                circle_marker.radius = radius_slider.value
                circle_marker.color = color_picker.value
                circle_marker.fill_color = fill_color_picker.value
                for key, widget in property_widgets.items():
                    properties[key] = widget.value

            def reset_circle(change):
                """Reset circle properties to their original values."""
                circle_marker.radius = original_properties["radius"]
                circle_marker.color = original_properties["color"]
                circle_marker.fill_color = original_properties["fill_color"]
                radius_slider.value = original_properties["radius"]
                color_picker.value = original_properties["color"]
                fill_color_picker.value = original_properties["fill_color"]
                for key, widget in property_widgets.items():
                    widget.value = original_properties["properties"].get(key, "")

            # Link widgets to update the circle marker properties and point attributes
            radius_slider.observe(update_circle, "value")
            color_picker.observe(update_circle, "value")
            fill_color_picker.observe(update_circle, "value")
            for widget in property_widgets.values():
                widget.observe(update_circle, "value")

            # Reset button
            reset_button = widgets.Button(
                description="Reset", layout=widgets.Layout(width=widget_width)
            )
            reset_button.on_click(reset_circle)

            # Arrange widgets in a vertical box with increased width
            vbox = widgets.VBox(
                [radius_slider, color_picker, fill_color_picker]
                + list(property_widgets.values())
                + [reset_button],
                layout=widgets.Layout(
                    width="310px"
                ),  # Set the width of the popup widget
            )
            return vbox

        def create_on_click_handler(circle_marker, properties, display_properties=None):
            """Create an on_click handler with the circle_marker bound."""
            # Save the original properties for reset
            original_properties = {
                "radius": circle_marker.radius,
                "color": circle_marker.color,
                "fill_color": circle_marker.fill_color,
                "properties": properties.copy(),
            }

            def on_click(**kwargs):
                if kwargs.get("type") == "click":
                    # Create a popup widget with controls
                    popup_widget = create_popup_widget(
                        circle_marker,
                        properties,
                        original_properties,
                        display_properties,
                    )
                    popup = Popup(
                        location=circle_marker.location,
                        child=popup_widget,
                        close_button=True,
                        auto_close=False,
                        close_on_escape_key=True,
                        min_width=int(widget_width[:-2]) + 10,
                    )
                    self.add_layer(popup)
                    popup.open = True

            return on_click

        layers = []

        # Iterate over each feature in the GeoJSON data and create a CircleMarker
        for feature in geojson_data["features"]:
            coordinates = feature["geometry"]["coordinates"]
            properties = feature["properties"]

            circle_marker = CircleMarker(
                location=(coordinates[1], coordinates[0]),  # (lat, lon)
                radius=radius,  # Initial radius of the circle
                color=color,  # Outline color
                weight=weight,  # Outline
                fill_color=fill_color,  # Fill color
                fill_opacity=fill_opacity,
                **kwargs,
            )

            # Create and bind the on_click handler for each circle_marker
            circle_marker.on_click(
                create_on_click_handler(circle_marker, properties, display_props)
            )

            # Add the circle marker to the map
            layers.append(circle_marker)

        group = ipyleaflet.LayerGroup(layers=tuple(layers), name=name)
        self.add(group)

    def edit_polygons(
        self,
        data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
        style: Optional[Dict[str, Any]] = None,
        hover_style: Optional[Dict[str, Any]] = None,
        name: str = "GeoJSON",
        widget_width: str = "250px",
        info_mode: str = "on_click",
        zoom_to_layer: bool = True,
        **kwargs: Any,
    ) -> None:
        """Edit polygons on the map.

        Args:
            data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
                edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
            style (Optional[Dict[str, Any]], optional): The style dictionary for
                the polygons. Defaults to None.
            hover_style (Optional[Dict[str, Any]], optional): The hover style
                dictionary for the polygons. Defaults to None.
            name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
            widget_width (str, optional): The width of the widgets. Defaults to "250px".
            info_mode (str, optional): The mode for displaying information,
                either "on_click" or "on_hover". Defaults to "on_click".
            zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
                Defaults to True.
            **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

        Raises:
            ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
        """
        import copy
        import json

        import geopandas as gpd
        from ipyleaflet import GeoJSON, Popup
        from shapely.geometry import shape

        bounds = None

        if isinstance(data, str):
            gdf = gpd.read_file(data)
            if gdf.crs != "EPSG:4326":
                gdf = gdf.to_crs("EPSG:4326")
            bounds = gdf.total_bounds
            temp_geojson = common.temp_file_path("geojson")
            gdf.to_file(temp_geojson, driver="GeoJSON")
            with open(temp_geojson) as f:
                data = json.load(f)
        elif isinstance(data, gpd.GeoDataFrame):
            if data.crs != "EPSG:4326":
                data = data.to_crs("EPSG:4326")
            bounds = data.total_bounds
            temp_geojson = common.temp_file_path("geojson")
            data.to_file(temp_geojson, driver="GeoJSON")
            with open(temp_geojson) as f:
                data = json.load(f)

        if isinstance(data, dict):
            geojson_data = data
            if zoom_to_layer and (bounds is not None):
                bounds = gpd.GeoDataFrame.from_features(data).total_bounds
        else:
            raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

        layout = widgets.Layout(width=widget_width)

        if style is None:
            style = {"color": "#3388ff"}
        if hover_style is None:
            hover_style = {"color": "yellow", "weight": 5}

        def calculate_centroid(polygon_coordinates, geom_type):
            polygon = shape({"type": geom_type, "coordinates": polygon_coordinates})
            centroid = polygon.centroid
            return centroid.y, centroid.x  # Return as (lat, lon)

        def create_property_widgets(properties):
            """Dynamically create widgets for each property."""
            widgets_list = []
            for key, value in properties.items():
                if key == "style":
                    continue
                if isinstance(value, (int, float)):
                    widget = widgets.FloatText(
                        value=value, description=f"{key}:", layout=layout
                    )
                else:
                    widget = widgets.Text(
                        value=str(value), description=f"{key}:", layout=layout
                    )
                widget._property_key = (
                    key  # Store the key in the widget for easy access later
                )
                widgets_list.append(widget)
            return widgets_list

        def on_click(event, feature, **kwargs):
            # Dynamically create input widgets for each property
            property_widgets = create_property_widgets(feature["properties"])
            save_button = widgets.Button(description="Save", layout=layout)
            geom_type = feature["geometry"]["type"]
            centroid = calculate_centroid(feature["geometry"]["coordinates"], geom_type)

            # Create and open the popup
            popup_content = widgets.VBox(property_widgets + [save_button])

            popup = Popup(
                location=centroid,
                child=popup_content,
                close_button=True,
                auto_close=True,
                close_on_escape_key=True,
                min_width=int(widget_width[:-2]) + 5,
            )

            self.add_layer(popup)

            def save_changes(_):

                original_data = copy.deepcopy(geojson_layer.data)
                original_feature = copy.deepcopy(feature)
                # Update the properties with the new values
                for widget in property_widgets:
                    feature["properties"][widget._property_key] = widget.value

                for i, f in enumerate(original_data["features"]):
                    if f == original_feature:
                        original_data["features"][i] = feature
                        break

                # Update the GeoJSON layer to reflect the changes

                geojson_layer.data = original_data
                self._geojson_data = original_data

                self.remove_layer(popup)  # Close the popup by removing it from the map

            save_button.on_click(save_changes)

        # Add GeoJSON layer to the map
        geojson_layer = GeoJSON(
            data=geojson_data, style=style, hover_style=hover_style, name=name, **kwargs
        )

        # Attach event to the GeoJSON layer
        if info_mode == "on_click":
            geojson_layer.on_click(on_click)
        elif info_mode == "on_hover":
            geojson_layer.on_hover(on_click)

        # Add layers to map
        self.add_layer(geojson_layer)
        self._geojson_data = geojson_layer.data

        if bounds is not None and zoom_to_layer:
            west, south, east, north = bounds
            self.fit_bounds([[south, east], [north, west]])

    def edit_lines(
        self,
        data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
        style: Optional[Dict[str, Any]] = None,
        hover_style: Optional[Dict[str, Any]] = None,
        name: str = "GeoJSON",
        widget_width: str = "250px",
        info_mode: str = "on_click",
        zoom_to_layer: bool = True,
        **kwargs: Any,
    ) -> None:
        """Edit lines on the map.

        Args:
            data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
                edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
            style (Optional[Dict[str, Any]], optional): The style dictionary for
                the lines. Defaults to None.
            hover_style (Optional[Dict[str, Any]], optional): The hover style
                dictionary for the lines. Defaults to None.
            name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
            widget_width (str, optional): The width of the widgets. Defaults to "250px".
            info_mode (str, optional): The mode for displaying information,
                either "on_click" or "on_hover". Defaults to "on_click".
            zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
                Defaults to True.
            **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

        Raises:
            ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
        """
        self.edit_polygons(
            data=data,
            style=style,
            hover_style=hover_style,
            name=name,
            widget_width=widget_width,
            info_mode=info_mode,
            zoom_to_layer=zoom_to_layer,
            **kwargs,
        )

    def save_edits(
        self, filename: str, drop_style: bool = True, crs="EPSG:4326", **kwargs: Any
    ) -> None:
        """
        Save the edited GeoJSON data to a file.

        Args:
            filename (str): The name of the file to save the edited GeoJSON data.
            drop_style (bool, optional): Whether to drop the style properties
                from the GeoJSON data. Defaults to True.
            crs (str, optional): The CRS of the GeoJSON data. Defaults to "EPSG:4326".
            **kwargs (Any): Additional arguments passed to the GeoDataFrame `to_file` method.

        Returns:
            None
        """
        import geopandas as gpd

        if not hasattr(self, "_geojson_data"):
            print("No GeoJSON data to save.")
            return

        gdf = gpd.GeoDataFrame.from_features(self._geojson_data)
        if drop_style and "style" in gdf.columns:
            gdf = gdf.drop(columns=["style"])
            gdf.crs = "EPSG:4326"

        if crs != "EPSG:4326":
            gdf = gdf.to_crs(crs)
        gdf.to_file(filename, **kwargs)

    def batch_edit_points(
        self,
        data: Union[str, dict],
        style: Optional[Dict[str, Any]] = None,
        hover_style: Optional[Dict[str, Any]] = None,
        changed_style: Optional[Dict[str, Any]] = None,
        display_props: Optional[List[str]] = None,
        name: str = "Points",
        text_width: str = "250px",
        zoom_to_layer: bool = True,
        **kwargs: Any,
    ) -> None:
        """Batch editing points (CircleMarkers) on the map from GeoJSON data.

        Args:
            data (Union[str, dict]): The GeoJSON data or path to the GeoJSON file.
            style (Optional[Dict[str, Any]]): Style for the CircleMarkers.
            hover_style (Optional[Dict[str, Any]]): Style for the CircleMarkers on hover.
            changed_style (Optional[Dict[str, Any]]): Style for the CircleMarkers when changed.
            display_props (Optional[List[str]]): List of properties to display in the attribute editor.
            name (str): Name of the layer group.
            text_width (str): Width of the text widgets in the attribute editor.
            zoom_to_layer (bool): Whether to zoom to the layer bounds.
            **kwargs (Any): Additional keyword arguments for the LayerGroup.

        Raises:
            ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
            ValueError: If the GeoJSON data does not contain only Point geometries.
        """
        import json

        import geopandas as gpd

        bounds = None

        if isinstance(data, str):
            gdf = gpd.read_file(data)
            if gdf.crs != "EPSG:4326":
                gdf = gdf.to_crs("EPSG:4326")
            bounds = gdf.total_bounds
            temp_geojson = common.temp_file_path("geojson")
            gdf.to_file(temp_geojson, driver="GeoJSON")
            with open(temp_geojson) as f:
                data = json.load(f)
        elif isinstance(data, gpd.GeoDataFrame):
            if data.crs != "EPSG:4326":
                data = data.to_crs("EPSG:4326")
            bounds = data.total_bounds
            temp_geojson = common.temp_file_path("geojson")
            data.to_file(temp_geojson, driver="GeoJSON")
            with open(temp_geojson) as f:
                data = json.load(f)

        if isinstance(data, dict):
            geojson_data = data
            if zoom_to_layer and (bounds is not None):
                bounds = gpd.GeoDataFrame.from_features(data).total_bounds
        else:
            raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

        # Ensure the data contains Point geometries
        if not all(
            feature["geometry"]["type"] == "Point"
            for feature in geojson_data["features"]
        ):
            raise ValueError("The GeoJSON data must contain only Point geometries.")

        highlighted_markers = []
        attribute_widgets = {}

        # Create CircleMarker objects for each point in the GeoJSON data
        markers = []

        if style is None:
            style = {
                "radius": 5,
                "weight": 1,
                "color": "white",
                "fill_color": "#3388ff",
                "fill_opacity": 0.6,
            }

        if hover_style is None:
            hover_style = {"color": "purple", "fill_color": "yellow"}

        if changed_style is None:
            changed_style = {"color": "cyan", "fill_color": "red"}

        for feature in data["features"]:
            coords = feature["geometry"]["coordinates"]
            properties = feature["properties"]

            marker = ipyleaflet.CircleMarker(
                location=(
                    coords[1],
                    coords[0],
                ),  # GeoJSON coordinates are (longitude, latitude)
                radius=style.get("radius", 5),
                weight=style.get("weight", 1),
                color=style.get("color", "white"),
                fill_color=style.get("fill_color", "#3388ff"),
                fill_opacity=style.get("fill_opacity", 0.6),
            )
            setattr(marker, "properties", properties)
            markers.append(marker)

        # Create a LayerGroup to hold the markers
        layer_group = ipyleaflet.LayerGroup(layers=markers, name=name, **kwargs)

        # Get the keys from the first feature's properties
        first_feature = data["features"][0]["properties"]

        # If display_props is not provided, show all attributes
        if display_props is None:
            display_props = first_feature.keys()

        text_layout = widgets.Layout(width=text_width)

        # Loop through the specified properties in display_props
        for key in display_props:
            if key in first_feature:  # Ensure the property exists
                attribute_widgets[key] = widgets.Text(
                    description=f"{key}:", layout=text_layout
                )

        # Update button and clear selection button
        button_width = "80px"
        button_layout = widgets.Layout(width=button_width)
        update_button = widgets.Button(description="Update", layout=button_layout)
        clear_button = widgets.Button(description="Clear", layout=button_layout)
        close_button = widgets.Button(description="Close", layout=button_layout)
        output_widget = widgets.Output()

        # Function to highlight the clicked marker and clear attribute fields
        def highlight_marker(marker, **kwargs):
            nonlocal highlighted_markers

            if marker in highlighted_markers:
                highlighted_markers.remove(marker)
                marker.color = style.get("color", "white")
                marker.fill_color = style.get("fill_color", "#3388ff")

            else:
                highlighted_markers.append(marker)
                marker.color = hover_style.get("color", "purple")
                marker.fill_color = hover_style.get("fill_color", "yellow")

        # Function to clear the selection
        def clear_selection(_):
            for marker in highlighted_markers:
                if marker.color != changed_style.get(
                    "color", "cyan"
                ) and marker.fill_color != changed_style.get("fill_color", "red"):
                    marker.color = style.get("color", "white")
                    marker.fill_color = style.get("fill_color", "#3388ff")
            for key, widget in attribute_widgets.items():
                widget.value = ""
                widget.placeholder = ""
            highlighted_markers.clear()

        def get_geojson_data():
            geojson_data = {"type": "FeatureCollection", "features": []}
            for layer in layer_group.layers:
                feature = {
                    "type": "Feature",
                    "properties": layer.properties,
                    "geometry": {
                        "type": "Point",
                        "coordinates": [layer.location[1], layer.location[0]],
                    },
                }

                geojson_data["features"].append(feature)
                self._geojson_data = geojson_data

        # Function to apply changes to highlighted markers
        def update_highlighted_markers(_):
            output_widget.clear_output()

            changed = False
            for index, marker in enumerate(highlighted_markers):
                for key, widget in attribute_widgets.items():
                    if widget.value.strip() != "":
                        changed = True
                        if isinstance(marker.properties[key], int):
                            try:
                                marker.properties[key] = int(widget.value)
                            except ValueError as e:
                                if index == 0:
                                    with output_widget:
                                        print(f"{key} must be an integer.")
                        elif isinstance(marker.properties[key], float):
                            try:
                                marker.properties[key] = float(widget.value)
                            except ValueError as e:
                                if index == 0:
                                    with output_widget:
                                        print(f"{key} must be a float.")
                        else:
                            marker.properties[key] = widget.value

                # Apply changed_style if defined
                if changed:
                    marker.color = changed_style.get("color", "cyan")
                    marker.fill_color = changed_style.get("fill_color", "red")
                else:
                    if index == 0:
                        with output_widget:
                            print("No changes to apply.")

            if changed:
                clear_selection(None)
                for key, widget in attribute_widgets.items():
                    widget.value = ""
                get_geojson_data()

        # Function to populate attribute fields on hover
        def populate_hover_attributes(marker, **kwargs):
            for key, widget in attribute_widgets.items():
                widget.value = ""
                widget.placeholder = str(marker.properties.get(key, ""))

        # Register click event to highlight markers
        for marker in markers:
            marker.on_click(lambda m=marker, **kwargs: highlight_marker(m))
            marker.on_mouseover(lambda m=marker, **kwargs: populate_hover_attributes(m))

        # Add the LayerGroup of markers to the map
        self.add_layer(layer_group)

        # Add event listeners to the buttons
        update_button.on_click(update_highlighted_markers)
        clear_button.on_click(clear_selection)

        # Create a VBox to hold the widgets for editing attributes and the buttons
        buttons = widgets.HBox([update_button, clear_button, close_button])
        attribute_editor = widgets.VBox(
            [*attribute_widgets.values(), buttons, output_widget]
        )

        # Embed the attribute editor inside the map using WidgetControl
        widget_control = ipyleaflet.WidgetControl(
            widget=attribute_editor, position="topright"
        )
        self.add(widget_control)

        def close_widget_control(_):
            self.remove(widget_control)

        close_button.on_click(close_widget_control)

        # Optionally zoom to the bounds of the points
        if zoom_to_layer:
            bounds = gpd.GeoDataFrame.from_features(data).total_bounds
            west, south, east, north = bounds
            self.fit_bounds([[south, west], [north, east]])

    def batch_edit_polygons(
        self,
        data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
        style: Optional[Dict[str, Any]] = None,
        hover_style: Optional[Dict[str, Any]] = None,
        highlight_style: Optional[Dict[str, Any]] = None,
        changed_style: Optional[Dict[str, Any]] = None,
        display_props: Optional[List[str]] = None,
        name: str = "GeoJSON",
        text_width: str = "250px",
        zoom_to_layer: bool = True,
        **kwargs: Any,
    ) -> None:
        """Batch editing polygons on the map.

        Args:
            data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
                edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
            style (Optional[Dict[str, Any]], optional): The style dictionary for
                the polygons. Defaults to None.
            hover_style (Optional[Dict[str, Any]], optional): The hover style
                dictionary for the polygons. Defaults to None.
            name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
            widget_width (str, optional): The width of the widgets. Defaults to "250px".
            info_mode (str, optional): The mode for displaying information,
                either "on_click" or "on_hover". Defaults to "on_click".
            zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
                Defaults to True.
            **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

        Raises:
            ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
        """
        import copy
        import json

        import geopandas as gpd
        from ipyleaflet import GeoJSON

        bounds = None
        if isinstance(data, str):
            gdf = gpd.read_file(data)
            if gdf.crs != "EPSG:4326":
                gdf = gdf.to_crs("EPSG:4326")
            bounds = gdf.total_bounds
            temp_geojson = common.temp_file_path("geojson")
            gdf.to_file(temp_geojson, driver="GeoJSON")
            with open(temp_geojson) as f:
                data = json.load(f)
        elif isinstance(data, gpd.GeoDataFrame):
            if data.crs != "EPSG:4326":
                data = data.to_crs("EPSG:4326")
            bounds = data.total_bounds
            temp_geojson = common.temp_file_path("geojson")
            data.to_file(temp_geojson, driver="GeoJSON")
            with open(temp_geojson) as f:
                data = json.load(f)

        if isinstance(data, dict):
            data = data
            if zoom_to_layer and (bounds is not None):
                bounds = gpd.GeoDataFrame.from_features(data).total_bounds
        else:
            raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

        if style is None:
            style = {"color": "#3388ff"}

        if hover_style is None:
            hover_style = {"color": "yellow", "dashArray": "0", "fillOpacity": 0.3}

        if highlight_style is None:
            highlight_style = {
                "color": "#3388ff",
                "fillColor": "yellow",
                "weight": 3,
                "fillOpacity": 0.5,
            }

        if changed_style is None:
            changed_style = {
                "color": "#3388ff",
                "fillColor": "red",
                "weight": 3,
                "fillOpacity": 0.3,
            }

        # List to store the IDs of highlighted features
        highlighted_features = []

        # Create a dictionary to hold attribute widgets
        attribute_widgets = {}

        # Get the keys from the first feature to dynamically create widgets
        first_feature = data["features"][0]["properties"]

        # If display_props is not provided, show all attributes
        if display_props is None:
            display_props = first_feature.keys()

        text_layout = widgets.Layout(width=text_width)
        # Loop through only the specified properties in display_props
        for key in display_props:
            if key in first_feature:  # Ensure the property exists
                attribute_widgets[key] = widgets.Text(
                    description=f"{key.capitalize()}:", layout=text_layout
                )

        # Update button and clear selection button
        button_width = "80px"
        button_layout = widgets.Layout(width=button_width)
        update_button = widgets.Button(description="Update", layout=button_layout)
        clear_button = widgets.Button(description="Clear", layout=button_layout)
        close_button = widgets.Button(description="Close", layout=button_layout)
        output_widget = widgets.Output()

        # Function to highlight the clicked feature and clear attribute fields
        def highlight_feature(event, feature, **kwargs):
            nonlocal highlighted_features
            original_data = copy.deepcopy(geojson_layer.data)

            for index, f in enumerate(original_data["features"]):
                if f == feature:
                    if index in highlighted_features:
                        highlighted_features.remove(index)
                        original_data["features"][index]["properties"]["style"] = style
                    else:
                        highlighted_features.append(index)
                        original_data["features"][index]["properties"][
                            "style"
                        ] = highlight_style

            geojson_layer.data = original_data

        # Function to clear the selection
        def clear_selection(_):
            original_data = copy.deepcopy(geojson_layer.data)

            # Reset the style for all highlighted features
            for index in highlighted_features:
                if (
                    original_data["features"][index]["properties"]["style"]
                    != changed_style
                ):
                    original_data["features"][index]["properties"]["style"] = style

            highlighted_features.clear()
            geojson_layer.data = original_data

        # Function to apply changes to highlighted features
        def update_highlighted_features(_):
            output_widget.clear_output()
            original_data = copy.deepcopy(geojson_layer.data)

            # Update the properties for all highlighted features
            for index in highlighted_features:
                for key, widget in attribute_widgets.items():
                    if widget.value.strip() != "":
                        dtype = type(
                            original_data["features"][index]["properties"][key]
                        )
                        if dtype == str:
                            value = str(widget.value)
                        elif dtype == int:
                            try:
                                value = int(widget.value)
                            except ValueError:
                                with output_widget:
                                    print(f"Invalid value for {key}")
                                    continue
                        elif dtype == float:
                            try:
                                value = float(widget.value)
                            except ValueError:
                                with output_widget:
                                    print(f"Invalid value for {key}")
                                    continue
                        else:
                            value = widget.value
                        original_data["features"][index]["properties"][key] = value
                        original_data["features"][index]["properties"][
                            "style"
                        ] = changed_style

            geojson_layer.data = original_data
            self._geojson_data = original_data
            clear_selection(None)
            for key, widget in attribute_widgets.items():
                widget.value = ""

        # Function to populate attribute fields on hover
        def populate_hover_attributes(event, feature, **kwargs):
            # Populate the widget fields with the hovered feature's attributes
            for key, widget in attribute_widgets.items():
                if widget.value.strip() == "":
                    widget.value = ""
                    widget.placeholder = str(feature["properties"].get(key, ""))

        # Create the GeoJSON layer
        geojson_layer = GeoJSON(
            data=data,
            style=style,
            hover_style=hover_style,
            name=name,
        )

        # Add click event to highlight features and clear attribute fields
        geojson_layer.on_click(highlight_feature)

        # Add hover event to populate attribute fields
        geojson_layer.on_hover(populate_hover_attributes)

        # Add the GeoJSON layer to the map
        self.add_layer(geojson_layer)

        # Add event listeners to the buttons
        update_button.on_click(update_highlighted_features)
        clear_button.on_click(clear_selection)

        # Create a VBox to hold the widgets for editing attributes and the buttons
        buttons = widgets.HBox([update_button, clear_button, close_button])
        attribute_editor = widgets.VBox(
            [*attribute_widgets.values(), buttons, output_widget]
        )

        # Embed the attribute editor inside the map using WidgetControl
        widget_control = ipyleaflet.WidgetControl(
            widget=attribute_editor, position="topright"
        )
        self.add(widget_control)

        def close_widget_control(_):
            self.remove(widget_control)

        close_button.on_click(close_widget_control)

        # Add layers to map
        self._geojson_data = geojson_layer.data

        if bounds is not None and zoom_to_layer:
            west, south, east, north = bounds
            self.fit_bounds([[south, east], [north, west]])

    def batch_edit_lines(
        self,
        data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
        style: Optional[Dict[str, Any]] = None,
        hover_style: Optional[Dict[str, Any]] = None,
        highlight_style: Optional[Dict[str, Any]] = None,
        changed_style: Optional[Dict[str, Any]] = None,
        display_props: Optional[List[str]] = None,
        name: str = "GeoJSON",
        text_width: str = "250px",
        zoom_to_layer: bool = True,
        **kwargs: Any,
    ) -> None:
        """Batch editing lines on the map.

        Args:
            data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
                edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
            style (Optional[Dict[str, Any]], optional): The style dictionary for
                the polygons. Defaults to None.
            hover_style (Optional[Dict[str, Any]], optional): The hover style
                dictionary for the polygons. Defaults to None.
            name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
            widget_width (str, optional): The width of the widgets. Defaults to "250px".
            info_mode (str, optional): The mode for displaying information,
                either "on_click" or "on_hover". Defaults to "on_click".
            zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
                Defaults to True.
            **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

        Raises:
            ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
        """
        self.batch_edit_polygons(
            data=data,
            style=style,
            hover_style=hover_style,
            highlight_style=highlight_style,
            changed_style=changed_style,
            display_props=display_props,
            name=name,
            text_width=text_width,
            zoom_to_layer=zoom_to_layer,
            **kwargs,
        )

    def add_nwi(
        self,
        data: Union[str, "gpd.GeoDataFrame"],
        col_name: str = "WETLAND_TY",
        add_legend: bool = True,
        style_callback: Optional[Callable[[dict], dict]] = None,
        layer_name: str = "Wetlands",
        **kwargs,
    ) -> None:
        """
        Adds National Wetlands Inventory (NWI) data to the map.

        Args:
            data (Union[str, gpd.GeoDataFrame]): The NWI data to add. It can be a file path or a GeoDataFrame.
            col_name (str): The column name in the GeoDataFrame that contains the wetland types.
            add_legend (bool): Whether to add a legend to the map. Defaults to True.
            style_callback (Optional[Callable[[dict], dict]]): A callback function to style the features. Defaults to None.
            layer_name (str): The name of the layer to add. Defaults to "Wetlands".
            **kwargs: Additional keyword arguments to pass to the add_vector or add_gdf method.

        Returns:
            None
        """

        nwi = {
            "Freshwater Forested/Shrub Wetland": "#008837",
            "Freshwater Emergent Wetland": "#7fc31c",
            "Freshwater Pond": "#688cc0",
            "Estuarine and Marine Wetland": "#66c2a5",
            "Riverine": "#0190bf",
            "Lake": "#13007c",
            "Estuarine and Marine Deepwater": "#007c88",
            "Other": "#b28656",
        }

        def nwi_color(feature):
            return {
                "color": "black",
                "fillColor": (
                    nwi[feature["properties"][col_name]]
                    if feature["properties"][col_name] in nwi
                    else "gray"
                ),
                "fillOpacity": 0.6,
                "weight": 1,
            }

        if style_callback is None:
            style_callback = nwi_color

        if isinstance(data, str):
            self.add_vector(
                data, style_callback=style_callback, layer_name=layer_name, **kwargs
            )
        else:
            self.add_gdf(
                data, style_callback=style_callback, layer_name=layer_name, **kwargs
            )
        if add_legend:
            self.add_legend(title="Wetland Type", builtin_legend="NWI")

    def add_nlcd(self, years: list = [2023], add_legend: bool = True, **kwargs) -> None:
        """
        Adds National Land Cover Database (NLCD) data to the map.

        Args:
            years (list): A list of years to add. It can be any of 1985-2023. Defaults to [2023].
            add_legend (bool): Whether to add a legend to the map. Defaults to True.
            **kwargs: Additional keyword arguments to pass to the add_cog_layer method.

        Returns:
            None
        """
        allowed_years = list(range(1985, 2024, 1))
        url = "https://www.mrlc.gov/downloads/sciweb1/shared/mrlc/data-bundles/Annual_NLCD_LndCov_{}_CU_C1V0.tif"

        if "colormap" not in kwargs:

            kwargs["colormap"] = {
                "11": "#466b9f",
                "12": "#d1def8",
                "21": "#dec5c5",
                "22": "#d99282",
                "23": "#eb0000",
                "24": "#ab0000",
                "31": "#b3ac9f",
                "41": "#68ab5f",
                "42": "#1c5f2c",
                "43": "#b5c58f",
                "51": "#af963c",
                "52": "#ccb879",
                "71": "#dfdfc2",
                "72": "#d1d182",
                "73": "#a3cc51",
                "74": "#82ba9e",
                "81": "#dcd939",
                "82": "#ab6c28",
                "90": "#b8d9eb",
                "95": "#6c9fb8",
            }

        if "zoom_to_layer" not in kwargs:
            kwargs["zoom_to_layer"] = False

        for year in years:
            if year not in allowed_years:
                raise ValueError(f"Year must be one of {allowed_years}.")
            year_url = url.format(year)
            self.add_cog_layer(year_url, name=f"NLCD {year}", **kwargs)
        if add_legend:
            self.add_legend(title="NLCD Land Cover Type", builtin_legend="NLCD")

    def add_nlcd_ts(
        self,
        left_year: int = 1985,
        right_layer: int = 2023,
        widget_width: str = "70px",
        add_legend: bool = True,
        add_layer_control: bool = True,
        **kwargs: Any,
    ) -> None:
        """
        Adds a time series comparison of NLCD (National Land Cover Database) layers to the map.

        Args:
            left_year (int, optional): The initial year for the left layer. Defaults to 1985.
            right_layer (int, optional): The initial year for the right layer. Defaults to 2023.
            widget_width (str, optional): The width of the dropdown widgets. Defaults to "70px".
            add_legend (bool, optional): If True, adds a legend to the map. Defaults to True.
            add_layer_control (bool, optional): If True, adds a layer control to the map. Defaults to True.
            **kwargs (Any): Additional keyword arguments to pass to the cog_tile function.

        Returns:
            None
        """

        allowed_years = list(range(1985, 2024, 1))

        left_widget = widgets.Dropdown(
            options=allowed_years,
            value=left_year,
            style={"description_width": "initial"},
            layout=widgets.Layout(width=widget_width),
        )
        right_widget = widgets.Dropdown(
            options=allowed_years,
            value=right_layer,
            style={"description_width": "initial"},
            layout=widgets.Layout(width=widget_width),
        )

        left_control = ipyleaflet.WidgetControl(widget=left_widget, position="topleft")
        right_control = ipyleaflet.WidgetControl(
            widget=right_widget, position="topright"
        )

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

        url = (
            "https://s3-us-west-2.amazonaws.com/mrlc/Annual_NLCD_LndCov_{}_CU_C1V0.tif"
        )

        colormap = {
            "11": "#466b9f",
            "12": "#d1def8",
            "21": "#dec5c5",
            "22": "#d99282",
            "23": "#eb0000",
            "24": "#ab0000",
            "31": "#b3ac9f",
            "41": "#68ab5f",
            "42": "#1c5f2c",
            "43": "#b5c58f",
            "51": "#af963c",
            "52": "#ccb879",
            "71": "#dfdfc2",
            "72": "#d1d182",
            "73": "#a3cc51",
            "74": "#82ba9e",
            "81": "#dcd939",
            "82": "#ab6c28",
            "90": "#b8d9eb",
            "95": "#6c9fb8",
        }
        left_url = url.format(left_year)
        right_url = url.format(right_layer)
        left_tile = common.cog_tile(left_url, colormap=colormap, **kwargs)
        right_tile = common.cog_tile(right_url, colormap=colormap, **kwargs)
        left_layer = ipyleaflet.TileLayer(url=left_tile, name=f"NLCD {left_year}")
        right_layer = ipyleaflet.TileLayer(url=right_tile, name=f"NLCD {right_layer}")
        split_control = ipyleaflet.SplitMapControl(
            left_layer=left_layer, right_layer=right_layer
        )
        self.add(split_control)

        if add_layer_control:
            self.add_layer_control()

        if add_legend:
            self.add_legend(title="NLCD Land Cover Type", builtin_legend="NLCD")

        def change_left_year(change):
            left_tile = common.cog_tile(
                url.format(change.new), colormap=colormap, **kwargs
            )
            left_layer.url = left_tile
            left_layer.name = f"NLCD {change.new}"

        def change_right_year(change):
            right_tile = common.cog_tile(
                url.format(change.new), colormap=colormap, **kwargs
            )
            right_layer.url = right_tile
            right_layer.name = f"NLCD {change.new}"

        left_widget.observe(change_left_year, names="value")
        right_widget.observe(change_right_year, names="value")

    def add_wayback_layer(
        self,
        date: str = None,
        name: str = None,
        attribution: str = "Esri",
        quiet: bool = False,
        **kwargs,
    ):
        """Adds a Wayback layer to the map.

        Args:
            date (str, optional): The date of the layer. Defaults to None.
            name (str, optional): The name of the layer. Defaults to None.
            attribution (str, optional): The attribution of the layer. Defaults to "Esri".
            **kwargs: Additional keyword arguments to pass to the add_tile_layer method.
        """
        layers = common.get_wayback_layers()
        if date not in layers.keys():
            new_date = common.find_closest_date(date, layers.keys())
            if not quiet:
                print(f"{date} is not available. Using the closest date: {new_date}")
            date = new_date

        url = common.get_wayback_tile_url(date, layers)
        if name is None:
            name = date
        self.add_tile_layer(url, name=name, attribution=attribution, **kwargs)

    def add_wayback_layers(
        self,
        left_date: str = "2014-02-20",
        right_date: str = None,
        widget_width: str = "120px",
        add_layer_control: bool = False,
        **kwargs: Any,
    ) -> None:
        """
        Adds a time series comparison of Wayback (ArcGIS Wayback) layers to the map.

        Args:
            left_date (str, optional): The initial date for the left layer in "YYYY-MM-DD" format. Defaults to "2014-02-20".
            right_date (str, optional): The initial date for the right layer in "YYYY-MM-DD" format. Defaults to None.
            widget_width (str, optional): The width of the date pickers. Defaults to "120px".
            add_layer_control (bool, optional): If True, adds a layer control to the map. Defaults to True.
            **kwargs (Any): Additional keyword arguments to pass to the cog_tile function.

        Returns:
            None
        """
        from datetime import datetime

        layers = common.get_wayback_layers()
        if right_date is None:
            right_date = list(layers.keys())[0]

        if left_date not in layers.keys():
            left_date = common.find_closest_date(left_date, layers.keys())

        if right_date is None:
            right_date = list(layers.keys())[0]
        elif right_date not in layers.keys():
            right_date = common.find_closest_date(right_date, layers.keys())

        left_widget = widgets.DatePicker(
            value=datetime.strptime(left_date, "%Y-%m-%d"),
            layout=widgets.Layout(width=widget_width),
        )
        right_widget = widgets.DatePicker(
            value=datetime.strptime(right_date, "%Y-%m-%d"),
            layout=widgets.Layout(width=widget_width),
        )
        left_control = ipyleaflet.WidgetControl(widget=left_widget, position="topleft")
        right_control = ipyleaflet.WidgetControl(
            widget=right_widget, position="topright"
        )
        self.add(left_control)
        self.add(right_control)

        left_tile_url = common.get_wayback_tile_url(left_date, layers)
        right_tile_url = common.get_wayback_tile_url(right_date, layers)
        left_layer = ipyleaflet.TileLayer(
            url=left_tile_url, name=f"{left_date}", attribution="Esri"
        )
        right_layer = ipyleaflet.TileLayer(
            url=right_tile_url, name=f"{right_date}", attribution="Esri"
        )
        split_control = ipyleaflet.SplitMapControl(
            left_layer=left_layer, right_layer=right_layer
        )
        self.add(split_control)
        if add_layer_control:
            self.add_layer_control()

        def change_left_date(change):
            left_date = change.new.strftime("%Y-%m-%d")
            new_date = common.find_closest_date(left_date, layers.keys())
            left_widget.value = datetime.strptime(new_date, "%Y-%m-%d")
            left_layer.url = common.get_wayback_tile_url(new_date, layers, quiet=True)
            left_layer.name = f"{new_date}"

        def change_right_date(change):
            right_date = change.new.strftime("%Y-%m-%d")
            new_date = common.find_closest_date(right_date, layers.keys())
            right_widget.value = datetime.strptime(new_date, "%Y-%m-%d")
            right_layer.url = common.get_wayback_tile_url(new_date, layers, quiet=True)
            right_layer.name = f"{new_date}"

        left_widget.observe(change_left_date, names="value")
        right_widget.observe(change_right_date, names="value")

    def add_wayback_time_slider(self, **kwargs):
        """Add a time slider for Wayback layers."""
        images = common.get_wayback_tile_dict()
        if "tile_args" not in kwargs:
            kwargs["tile_args"] = {"attribution": "Esri"}
        self.add_time_slider(images, **kwargs)

add(obj, index=None, **kwargs)

Adds a layer to the map.

Parameters:

Name	Type	Description	Default
layer	object	The layer to add to the map.	required
index	int	The index at which to add the layer. Defaults to None.	None

Source code in leafmap/leafmap.py

def add(self, obj, index=None, **kwargs) -> None:
    """Adds a layer to the map.

    Args:
        layer (object): The layer to add to the map.
        index (int, optional): The index at which to add the layer. Defaults to None.
    """
    if isinstance(obj, str):
        if obj in basemaps.keys():
            obj = get_basemap(obj)
        else:
            if obj == "nasa_earth_data":
                from .toolbar import nasa_data_gui

                nasa_data_gui(self, **kwargs)
            elif obj == "NASA_OPERA":
                from .toolbar import nasa_opera_gui

                nasa_opera_gui(self, **kwargs)
            elif obj == "inspector":
                from .toolbar import inspector_gui

                inspector_gui(self, **kwargs)

            elif obj == "stac":
                self.add_stac_gui(**kwargs)
            elif obj == "basemap":
                self.add_basemap_gui(**kwargs)
            elif obj == "inspector":
                self.add_inspector_gui(**kwargs)
            elif obj == "layer_manager":
                self.add_layer_manager(**kwargs)
            elif obj == "oam":
                self.add_oam_gui(**kwargs)
            return

    super().add(obj, index=index)

    if hasattr(self, "_layer_manager_widget"):
        self.update_layer_manager()

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 basemaps. Defaults to 'HYBRID'.	'HYBRID'
visible	bool	Whether the basemap is visible or not. Defaults to True.	required
**kwargs		Keyword arguments for the TileLayer.	{}

Source code in leafmap/leafmap.py

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

    Args:
        basemap (str, optional): Can be one of string from basemaps. Defaults to 'HYBRID'.
        visible (bool, optional): Whether the basemap is visible or not. Defaults to True.
        **kwargs: Keyword arguments for the TileLayer.
    """
    import xyzservices

    try:
        layer_names = self.get_layer_names()

        map_dict = {
            "ROADMAP": "Google Maps",
            "SATELLITE": "Google Satellite",
            "TERRAIN": "Google Terrain",
            "HYBRID": "Google Hybrid",
        }

        if isinstance(basemap, str):
            if basemap.upper() in map_dict:
                layer = common.get_google_map(basemap.upper(), **kwargs)
                layer.visible = show
                self.add(layer)
                return

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

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

add_basemap_gui(position='topright')

Add the basemap widget to the map.

Parameters:

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

Source code in leafmap/leafmap.py

def add_basemap_gui(self, position: Optional[str] = "topright") -> None:
    """Add the basemap widget to the map.

    Args:
        position (str, optional): The position of the widget. Defaults to "topright".
    """
    from .toolbar import change_basemap

    change_basemap(self, position)

add_bbox(bbox, layer_name='Bounding Box', color='blue', fill_color=None, fill_opacity=0.1, weight=2, **kwargs)

Add a bbox defined by [x_min, y_min, x_max, y_max] to the map.

Parameters:

Name	Type	Description	Default
bbox	Union[List[float], Tuple[float, float, float, float], Sequence[float]]	A list or tuple containing four numbers representing the bounding box: [x_min, y_min, x_max, y_max]. Assumed to be in longitude/latitude coordinates.	required
layer_name	str	The name to assign to the GeoJSON layer. Defaults to "Bounding Box".	'Bounding Box'
color	str	The color of the bounding box outline (stroke). Defaults to "blue".	'blue'
fill_color	Optional[str]	The fill color of the bounding box. If None, the box will not be filled. Defaults to None.	None
fill_opacity	float	The opacity of the fill color (only used if fill_color is provided). Value should be between 0.0 and 1.0. Defaults to 0.1.	0.1
weight	int	The thickness of the bounding box outline (stroke). Defaults to 2.	2
**kwargs		Additional keyword arguments to pass directly to the underlying add_geojson method (e.g., popup, tooltip, hover_style).	{}

Source code in leafmap/leafmap.py

def add_bbox(
    self,
    bbox: Union[List[float], Tuple[float, float, float, float], Sequence[float]],
    layer_name: str = "Bounding Box",
    color: str = "blue",
    fill_color: Optional[str] = None,
    fill_opacity: float = 0.1,
    weight: int = 2,
    **kwargs,
) -> None:
    """
    Add a bbox defined by [x_min, y_min, x_max, y_max] to the map.

    Args:
        bbox: A list or tuple containing four numbers representing the
              bounding box: [x_min, y_min, x_max, y_max]. Assumed to be
              in longitude/latitude coordinates.
        layer_name: The name to assign to the GeoJSON layer.
                    Defaults to "Bounding Box".
        color: The color of the bounding box outline (stroke).
               Defaults to "blue".
        fill_color: The fill color of the bounding box. If None, the box
                    will not be filled. Defaults to None.
        fill_opacity: The opacity of the fill color (only used if
                      fill_color is provided). Value should be between
                      0.0 and 1.0. Defaults to 0.1.
        weight: The thickness of the bounding box outline (stroke).
                Defaults to 2.
        **kwargs: Additional keyword arguments to pass directly to the
                  underlying `add_geojson` method (e.g., `popup`,
                  `tooltip`, `hover_style`).
    Raises:
        ValueError: If `bbox` is not a list or tuple of exactly four numbers,
                    if the coordinates cannot be converted to floats, or if
                    x_min > x_max or y_min > y_max.
    """
    if not isinstance(bbox, (list, tuple)) or len(bbox) != 4:
        raise ValueError(
            "bbox must be a list or tuple of four numbers [minx, miny, maxx, maxy]"
        )

    try:
        x_min, y_min, x_max, y_max = map(float, bbox)
    except (ValueError, TypeError) as e:
        raise ValueError(f"bbox coordinates must be valid numbers. Error {e}.")

    if x_min > x_max or y_min > y_max:
        raise ValueError(
            "x_min must be less than or equal to x_max and y_min must be less than or equal to y_max."
        )

    # define the 4 (+ closing point) corners in counter-clockwise order [longitude, latitude].
    coordinates = [
        [
            [x_min, y_min],  # bottom-left
            [x_max, y_min],  # bottom-right
            [x_max, y_max],  # top-right
            [x_min, y_max],  # top-left
            [x_min, y_min],
        ]
    ]

    # create a FeatureCollection (required by add_geojson).
    geojson_data = {
        "type": "FeatureCollection",
        "features": [
            # add the bbox feature.
            {
                "type": "Feature",
                "properties": {},
                "geometry": {"type": "Polygon", "coordinates": coordinates},
            }
        ],
    }

    style = {
        "stroke": True,
        "color": color,
        "weight": weight,
        "opacity": 1,
        "fillColor": fill_color if fill_color else color,
        "fillOpacity": fill_opacity if fill_color else 0,
        "fill": fill_color is not None,
    }

    self.add_geojson(geojson_data, style=style, layer_name=layer_name, **kwargs)

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 leafmap/leafmap.py

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

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

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

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

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

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

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

    except Exception as e:
        raise Exception(e)

add_circle_markers_from_xy(data, x='lon', y='lat', radius=10, popup=None, font_size=2, stroke=True, color='#0033FF', weight=2, fill=True, fill_color=None, fill_opacity=0.2, opacity=1.0, layer_name='Circle Markers', **kwargs)

Adds a marker cluster to the map. For a list of options, see https://ipyleaflet.readthedocs.io/en/latest/_modules/ipyleaflet/leaflet.html#Path

Parameters:

Name	Type	Description	Default
data	str | DataFrame	A csv or Pandas DataFrame containing x, y, z values.	required
x	str	The column name for the x values. Defaults to "lon".	'lon'
y	str	The column name for the y values. Defaults to "lat".	'lat'
radius	int	The radius of the circle. Defaults to 10.	10
popup	list	A list of column names to be used as the popup. Defaults to None.	None
font_size	int	The font size of the popup. Defaults to 2.	2
stroke	bool	Whether to stroke the path. Defaults to True.	True
color	str	The color of the path. Defaults to "#0033FF".	'#0033FF'
weight	int	The weight of the path. Defaults to 2.	2
fill	bool	Whether to fill the path with color. Defaults to True.	True
fill_color	str	The fill color of the path. Defaults to None.	None
fill_opacity	float	The fill opacity of the path. Defaults to 0.2.	0.2
opacity	float	The opacity of the path. Defaults to 1.0.	1.0
layer_name	str	The layer name to use for the marker cluster. Defaults to "Circle Markers".	'Circle Markers'

Source code in leafmap/leafmap.py

def add_circle_markers_from_xy(
    self,
    data,
    x="lon",
    y="lat",
    radius=10,
    popup=None,
    font_size=2,
    stroke=True,
    color="#0033FF",
    weight=2,
    fill=True,
    fill_color=None,
    fill_opacity=0.2,
    opacity=1.0,
    layer_name="Circle Markers",
    **kwargs,
) -> None:
    """Adds a marker cluster to the map. For a list of options, see https://ipyleaflet.readthedocs.io/en/latest/_modules/ipyleaflet/leaflet.html#Path

    Args:
        data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
        x (str, optional): The column name for the x values. Defaults to "lon".
        y (str, optional): The column name for the y values. Defaults to "lat".
        radius (int, optional): The radius of the circle. Defaults to 10.
        popup (list, optional): A list of column names to be used as the popup. Defaults to None.
        font_size (int, optional): The font size of the popup. Defaults to 2.
        stroke (bool, optional): Whether to stroke the path. Defaults to True.
        color (str, optional): The color of the path. Defaults to "#0033FF".
        weight (int, optional): The weight of the path. Defaults to 2.
        fill (bool, optional): Whether to fill the path with color. Defaults to True.
        fill_color (str, optional): The fill color of the path. Defaults to None.
        fill_opacity (float, optional): The fill opacity of the path. Defaults to 0.2.
        opacity (float, optional): The opacity of the path. Defaults to 1.0.
        layer_name (str, optional): The layer name to use for the marker cluster. Defaults to "Circle Markers".

    """
    import geopandas as gpd
    import pandas as pd

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

    col_names = df.columns.values.tolist()
    if "geometry" in col_names:
        col_names.remove("geometry")

    if popup is None:
        popup = col_names

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

    if x not in col_names:
        if isinstance(df, gpd.GeoDataFrame):
            df[x] = df.geometry.x
        else:
            raise ValueError(
                f"x must be one of the following: {', '.join(col_names)}"
            )

    if y not in col_names:
        if isinstance(df, gpd.GeoDataFrame):
            df[y] = df.geometry.y
        else:
            raise ValueError(
                f"y must be one of the following: {', '.join(col_names)}"
            )

    if fill_color is None:
        fill_color = color

    if isinstance(color, str):
        colors = [color] * len(df)
    elif isinstance(color, list):
        colors = color
    else:
        raise ValueError("color must be either a string or a list.")

    if isinstance(fill_color, str):
        fill_colors = [fill_color] * len(df)
    elif isinstance(fill_color, list):
        fill_colors = fill_color
    else:
        raise ValueError("fill_color must be either a string or a list.")

    if isinstance(radius, int):
        radius = [radius] * len(df)
    elif isinstance(radius, list):
        radius = radius
    else:
        raise ValueError("radius must be either an integer or a list.")

    index = 0

    layers = []
    for idx, row in df.iterrows():
        html = ""
        for p in popup:
            html = (
                html
                + f"<font size='{font_size}'><b>"
                + p
                + "</b>"
                + ": "
                + str(row[p])
                + "<br></font>"
            )
        popup_html = widgets.HTML(html)

        marker = ipyleaflet.CircleMarker(
            location=[row[y], row[x]],
            radius=radius[index],
            popup=popup_html,
            stroke=stroke,
            color=colors[index],
            weight=weight,
            fill=fill,
            fill_color=fill_colors[index],
            fill_opacity=fill_opacity,
            opacity=opacity,
            **kwargs,
        )
        layers.append(marker)
        index += 1

    group = ipyleaflet.LayerGroup(layers=tuple(layers), name=layer_name)
    self.add(group)

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

Adds a COG TileLayer to the map.

Parameters:

Name	Type	Description	Default
url	str	The URL of the COG tile layer.	required
name	str	The layer name to use for the layer. Defaults to 'Untitled'.	'Untitled'
attribution	str	The attribution to use. Defaults to ''.	''
opacity	float	The opacity of the layer. Defaults to 1.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
bands	list	A list of bands to use for the layer. Defaults to None.	None
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None
zoom_to_layer	bool	Whether to zoom to the layer extent. Defaults to True.	True
layer_index	int	The index at which to add the layer. Defaults to None.	None
overwrite	bool	Whether to overwrite the layer if it already exists. Defaults to False.	False
**kwargs		Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale, color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/ and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3]. apply a rescaling to multiple bands, use something like rescale=["164,223","130,211","99,212"].	{}

Source code in leafmap/leafmap.py

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

    Args:
        url (str): The URL of the COG tile layer.
        name (str, optional): The layer name to use for the layer. Defaults to 'Untitled'.
        attribution (str, optional): The attribution to use. Defaults to ''.
        opacity (float, optional): The opacity of the layer. Defaults to 1.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        bands (list, optional): A list of bands to use for the layer. Defaults to None.
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".
        zoom_to_layer (bool, optional): Whether to zoom to the layer extent. Defaults to True.
        layer_index (int, optional): The index at which to add the layer. Defaults to None.
        overwrite (bool, optional): Whether to overwrite the layer if it already exists. Defaults to False.
        **kwargs: Arbitrary keyword arguments, including bidx, expression, nodata, unscale, resampling, rescale,
            color_formula, colormap, colormap_name, return_mask. See https://developmentseed.org/titiler/endpoints/cog/
            and https://cogeotiff.github.io/rio-tiler/colormap/. To select a certain bands, use bidx=[1, 2, 3].
            apply a rescaling to multiple bands, use something like `rescale=["164,223","130,211","99,212"]`.
    """
    if os.environ.get("USE_MKDOCS") is not None:
        return

    band_names = common.cog_bands(url, titiler_endpoint)
    if len(band_names) == 0:
        return

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

        if all(isinstance(x, str) for x in bands):
            kwargs["bidx"] = [band_names.index(x) + 1 for x in bands]

        elif all(isinstance(x, int) for x in bands):
            kwargs["bidx"] = bands
        else:
            raise ValueError("Bands must be a list of integers or strings.")
    elif "bidx" not in kwargs:
        if len(band_names) == 1:
            kwargs["bidx"] = [1]
        else:
            kwargs["bidx"] = [1, 2, 3]

    vis_bands = [band_names[idx - 1] for idx in kwargs["bidx"]]

    if len(kwargs["bidx"]) > 1:
        if "colormap_name" in kwargs:
            kwargs.pop("colormap_name")
        if "colormap" in kwargs:
            kwargs.pop("colormap")

    tile_url = common.cog_tile(url, bands, titiler_endpoint, **kwargs)
    bounds = common.cog_bounds(url, titiler_endpoint)

    name = self._check_layer_name(name, overwrite=overwrite)
    if overwrite and name in self.get_layer_names():
        layer = self.find_layer(name)
        if layer is not None:
            self.remove_layer(layer)

    self.add_tile_layer(tile_url, name, attribution, opacity, shown, layer_index)
    if zoom_to_layer and bounds is not None:
        self.center = common.cog_center(url, titiler_endpoint)
        self.zoom = 19
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])
        common.arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

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

    try:
        vmin, vmax = common.cog_tile_vmin_vmax(
            url, bands=bands, titiler_endpoint=titiler_endpoint
        )
    except Exception:
        vmin, vmax = None, None

    if "colormap_name" in kwargs:
        colormap = kwargs["colormap_name"]
    else:
        colormap = None

    if "nodata" in kwargs:
        nodata = kwargs["nodata"]
    else:
        nodata = None

    params = {
        "url": url,
        "titiler_endpoint": titiler_endpoint,
        "tile_layer": self.find_layer(name),
        "bounds": bounds,
        "indexes": kwargs["bidx"],
        "vis_bands": vis_bands,
        "band_names": band_names,
        "vmin": vmin,
        "vmax": vmax,
        "nodata": nodata,
        "colormap": colormap,
        "opacity": opacity,
        "layer_name": name,
        "type": "COG",
    }
    if vmin is None and vmax is None:
        params.pop("vmin")
        params.pop("vmax")

    self.cog_layer_dict[name] = params

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

Add a branca colorbar to the map.

Parameters:

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

Source code in leafmap/leafmap.py

def add_colorbar(
    self,
    colors: Union[list[int], tuple[int]],
    vmin: Optional[int] = 0,
    vmax: Optional[float] = 1.0,
    index: Optional[list] = None,
    caption: Optional[str] = "",
    categorical: Optional[bool] = False,
    step: Optional[int] = None,
    height: Optional[str] = "45px",
    transparent_bg: Optional[bool] = False,
    position: Optional[str] = "bottomright",
    **kwargs,
) -> None:
    """Add a branca colorbar to the map.

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

    """
    from box import Box
    from branca.colormap import LinearColormap

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

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

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

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

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

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

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

    self.colorbar = colormap_ctrl
    self.add(colormap_ctrl)

add_colormap(cmap='gray', colors=None, discrete=False, label=None, width=3, height=0.25, orientation='horizontal', vmin=0, vmax=1.0, axis_off=False, show_name=False, font_size=8, transparent_bg=False, position='bottomright', **kwargs)

Adds a matplotlib colormap to the map.

Parameters:

Name	Type	Description	Default
cmap	str	Matplotlib colormap. Defaults to "gray". See https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py for options.	'gray'
colors	list	A list of custom colors to create a colormap. Defaults to None.	None
discrete	bool	Whether to create a discrete colorbar. Defaults to False.	False
label	str	Label for the colorbar. Defaults to None.	None
width	float	The width of the colormap. Defaults to 8.0.	3
height	float	The height of the colormap. Defaults to 0.4.	0.25
orientation	str	The orientation of the colormap. Defaults to "horizontal".	'horizontal'
vmin	float	The minimum value range. Defaults to 0.	0
vmax	float	The maximum value range. Defaults to 1.0.	1.0
axis_off	bool	Whether to turn axis off. Defaults to False.	False
show_name	bool	Whether to show the colormap name. Defaults to False.	False
font_size	int	Font size of the text. Defaults to 12.	8
transparent_bg	bool	Whether to use transparent background for the colormap widget. Defaults to True.	False
position	str	The position for the colormap widget. Defaults to "bottomright".	'bottomright'

Source code in leafmap/leafmap.py

def add_colormap(
    self,
    cmap: Optional[str] = "gray",
    colors: Optional[list] = None,
    discrete: Optional[bool] = False,
    label: Optional[str] = None,
    width: Optional[float] = 3,
    height: Optional[float] = 0.25,
    orientation: Optional[str] = "horizontal",
    vmin: Optional[float] = 0,
    vmax: Optional[float] = 1.0,
    axis_off: Optional[bool] = False,
    show_name: Optional[bool] = False,
    font_size: Optional[int] = 8,
    transparent_bg: Optional[bool] = False,
    position: Optional[str] = "bottomright",
    **kwargs,
) -> None:
    """Adds a matplotlib colormap to the map.

    Args:
        cmap (str, optional): Matplotlib colormap. Defaults to "gray". See https://matplotlib.org/3.3.4/tutorials/colors/colormaps.html#sphx-glr-tutorials-colors-colormaps-py for options.
        colors (list, optional): A list of custom colors to create a colormap. Defaults to None.
        discrete (bool, optional): Whether to create a discrete colorbar. Defaults to False.
        label (str, optional): Label for the colorbar. Defaults to None.
        width (float, optional): The width of the colormap. Defaults to 8.0.
        height (float, optional): The height of the colormap. Defaults to 0.4.
        orientation (str, optional): The orientation of the colormap. Defaults to "horizontal".
        vmin (float, optional): The minimum value range. Defaults to 0.
        vmax (float, optional): The maximum value range. Defaults to 1.0.
        axis_off (bool, optional): Whether to turn axis off. Defaults to False.
        show_name (bool, optional): Whether to show the colormap name. Defaults to False.
        font_size (int, optional): Font size of the text. Defaults to 12.
        transparent_bg (bool, optional): Whether to use transparent background for the colormap widget. Defaults to True.
        position (str, optional): The position for the colormap widget. Defaults to "bottomright".
    """
    from .colormaps import plot_colormap

    output = widgets.Output()

    colormap_ctrl = ipyleaflet.WidgetControl(
        widget=output,
        position=position,
        transparent_bg=transparent_bg,
    )
    with output:
        output.clear_output()
        with output:
            plot_colormap(
                cmap,
                colors,
                discrete,
                label,
                width,
                height,
                orientation,
                vmin,
                vmax,
                axis_off,
                show_name,
                font_size,
                **kwargs,
            )

    self.colorbar = colormap_ctrl
    self.add(colormap_ctrl)

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

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

Parameters:

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

Source code in leafmap/leafmap.py

def add_data(
    self,
    data: Union[str, pd.DataFrame],
    column: str,
    colors: Optional[str] = None,
    labels: Optional[str] = None,
    cmap: Optional[str] = None,
    scheme: Optional[str] = "Quantiles",
    k: int = 5,
    add_legend: Optional[bool] = True,
    legend_title: Optional[bool] = None,
    legend_position: Optional[str] = "bottomright",
    legend_kwds: Optional[dict] = None,
    classification_kwds: Optional[dict] = None,
    layer_name: Optional[str] = "Untitled",
    style: Optional[dict] = None,
    hover_style: Optional[dict] = None,
    style_callback: Optional[dict] = None,
    marker_radius: int = 10,
    marker_args=None,
    info_mode: Optional[str] = "on_hover",
    encoding: Optional[str] = "utf-8",
    **kwargs,
) -> None:
    """Add vector data to the map with a variety of classification schemes.

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

    """

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

    if legend_title is None:
        legend_title = column

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

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

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

    if gdf.geometry.geom_type.unique().tolist()[0] == "Point":
        columns = gdf.columns.tolist()
        if "category" in columns:
            columns.remove("category")
        if "color" in columns:
            columns.remove("color")
        if marker_args is None:
            marker_args = {}
        if "fill_color" not in marker_args:
            marker_args["fill_color"] = gdf["color"].tolist()
        if "stroke" not in marker_args:
            marker_args["stroke"] = False
        if "fill_opacity" not in marker_args:
            marker_args["fill_opacity"] = 0.8

        marker_args["radius"] = marker_radius

        self.add_markers(gdf[columns], layer_name=layer_name, **marker_args)
    else:
        self.add_gdf(
            gdf,
            layer_name=layer_name,
            style=style,
            hover_style=hover_style,
            style_callback=style_callback,
            info_mode=info_mode,
            encoding=encoding,
            **kwargs,
        )
    if add_legend:
        self.add_legend(
            title=legend_title, legend_dict=legend_dict, position=legend_position
        )

add_ee_layer(ee_object=None, vis_params={}, asset_id=None, name=None, attribution='Google Earth Engine', shown=True, opacity=1.0, **kwargs)

Adds a Google Earth Engine tile layer to the map based on the tile layer URL from https://github.com/opengeos/ee-tile-layers/blob/main/datasets.tsv.

Parameters:

Name	Type	Description	Default
ee_object	object	The Earth Engine object to display.	None
vis_params	dict	Visualization parameters. For example, {'min': 0, 'max': 100}.	{}
asset_id	str	The ID of the Earth Engine asset.	None
name	str	The name of the tile layer. If not provided, the asset ID will be used. Default is None.	None
attribution	str	The attribution text to be displayed. Default is "Google Earth Engine".	'Google Earth Engine'
shown	bool	Whether the tile layer should be shown on the map. Default is True.	True
opacity	float	The opacity of the tile layer. Default is 1.0.	1.0
**kwargs		Additional keyword arguments to be passed to the underlying add_tile_layer method.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def add_ee_layer(
    self,
    ee_object=None,
    vis_params={},
    asset_id: str = None,
    name: str = None,
    attribution: str = "Google Earth Engine",
    shown: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """
    Adds a Google Earth Engine tile layer to the map based on the tile layer URL from
        https://github.com/opengeos/ee-tile-layers/blob/main/datasets.tsv.

    Args:
        ee_object (object): The Earth Engine object to display.
        vis_params (dict): Visualization parameters. For example, {'min': 0, 'max': 100}.
        asset_id (str): The ID of the Earth Engine asset.
        name (str, optional): The name of the tile layer. If not provided, the asset ID will be used. Default is None.
        attribution (str, optional): The attribution text to be displayed. Default is "Google Earth Engine".
        shown (bool, optional): Whether the tile layer should be shown on the map. Default is True.
        opacity (float, optional): The opacity of the tile layer. Default is 1.0.
        **kwargs: Additional keyword arguments to be passed to the underlying `add_tile_layer` method.

    Returns:
        None
    """
    import pandas as pd

    if isinstance(asset_id, str):

        df = pd.read_csv(
            "https://raw.githubusercontent.com/opengeos/ee-tile-layers/main/datasets.tsv",
            sep="\t",
        )

        asset_id = asset_id.strip()
        if name is None:
            name = asset_id

        if asset_id in df["id"].values:
            url = df.loc[df["id"] == asset_id, "url"].values[0]
            self.add_tile_layer(
                url,
                name,
                attribution=attribution,
                shown=shown,
                opacity=opacity,
                **kwargs,
            )
        else:
            print(f"The provided EE tile layer {asset_id} does not exist.")
            return
    elif ee_object is not None:
        url = get_ee_tile_url(ee_object, vis_params)
        if url is None:
            print(f"The provided EE tile layer {ee_object} does not exist.")
            return
        if name is None:
            name = "EE Layer"
        self.add_tile_layer(
            url,
            name,
            attribution=attribution,
            shown=shown,
            opacity=opacity,
            **kwargs,
        )

add_gdf(gdf, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover', zoom_to_layer=False, encoding='utf-8', **kwargs)

Adds a GeoDataFrame to the map.

Parameters:

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

Source code in leafmap/leafmap.py

def add_gdf(
    self,
    gdf,
    layer_name: Optional[str] = "Untitled",
    style: Optional[dict] = {},
    hover_style: Optional[dict] = {},
    style_callback: Optional[Callable] = None,
    fill_colors: Optional[list[str]] = None,
    info_mode: Optional[str] = "on_hover",
    zoom_to_layer: Optional[bool] = False,
    encoding: Optional[str] = "utf-8",
    **kwargs,
) -> None:
    """Adds a GeoDataFrame to the map.

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

    self.add_geojson(
        gdf,
        layer_name,
        style,
        hover_style,
        style_callback,
        fill_colors,
        info_mode,
        zoom_to_layer,
        encoding,
        **kwargs,
    )

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

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

Parameters:

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

Source code in leafmap/leafmap.py

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

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

add_geojson(in_geojson, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover', zoom_to_layer=False, encoding='utf-8', **kwargs)

Adds a GeoJSON file to the map.

Parameters:

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

Raises:

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

Source code in leafmap/leafmap.py

def add_geojson(
    self,
    in_geojson: Union[str, Dict],
    layer_name: Optional[str] = "Untitled",
    style: Optional[dict] = {},
    hover_style: Optional[dict] = {},
    style_callback: Optional[Callable] = None,
    fill_colors: Optional[list[str]] = None,
    info_mode: Optional[str] = "on_hover",
    zoom_to_layer: Optional[bool] = False,
    encoding: Optional[str] = "utf-8",
    **kwargs,
) -> None:
    """Adds a GeoJSON file to the map.

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

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

    import geopandas as gpd

    gdf = None

    try:
        if isinstance(in_geojson, str):
            if in_geojson.startswith("http"):
                if common.is_jupyterlite():
                    import pyodide  # pylint: disable=E0401

                    output = os.path.basename(in_geojson)

                    output = os.path.abspath(output)
                    obj = pyodide.http.open_url(in_geojson)
                    with open(output, "w") as fd:
                        shutil.copyfileobj(obj, fd)
                    with open(output, "r") as fd:
                        data = json.load(fd)
                else:
                    gdf = gpd.read_file(in_geojson, encoding=encoding)

            else:
                gdf = gpd.read_file(in_geojson, encoding=encoding)

        elif isinstance(in_geojson, dict):
            if in_geojson.get("type") == "Feature":
                gdf = gpd.GeoDataFrame.from_features([in_geojson])
            else:
                gdf = gpd.GeoDataFrame.from_features(in_geojson)
        elif isinstance(in_geojson, gpd.GeoDataFrame):
            gdf = in_geojson
        else:
            raise TypeError("The input geojson must be a type of str or dict.")
    except Exception as e:
        raise Exception(e)

    if gdf.crs is None:
        # print(
        #     f"Warning: The dataset does not have a CRS defined. Assuming EPSG:4326."
        # )
        gdf.crs = "EPSG:4326"
    elif gdf.crs != "EPSG:4326":
        gdf = gdf.to_crs("EPSG:4326")
    data = gdf.__geo_interface__

    try:
        first_feature = data["features"][0]
        if isinstance(first_feature["properties"].get("style"), str):
            # Loop through the features and update the style
            for feature in data["features"]:
                fstyle = feature["properties"].get("style")
                if isinstance(fstyle, str):
                    feature["properties"]["style"] = json.loads(fstyle)
    except Exception as e:
        print(e)
        pass

    geom_type = gdf.reset_index().geom_type[0]

    if style is None and (style_callback is None):
        style = {
            # "stroke": True,
            "color": "#3388ff",
            "weight": 2,
            "opacity": 1,
            "fill": True,
            "fillColor": "#3388ff",
            "fillOpacity": 0.2,
            # "dashArray": "9"
            # "clickable": True,
        }

        if geom_type in ["LineString", "MultiLineString"]:
            style["fill"] = False

    elif "weight" not in style:
        style["weight"] = 1

    if not hover_style:
        hover_style = {
            "weight": style["weight"] + 2,
            "fillOpacity": 0,
            "color": "yellow",
        }

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

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

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

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

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

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

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

    toolbar_button.observe(toolbar_btn_click, "value")

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

    close_button.observe(close_btn_click, "value")

    if "fields" in kwargs:
        fields = kwargs["fields"]
        kwargs.pop("fields")
    else:
        fields = None

    def update_html(feature, fields=fields, **kwargs):
        if fields is None:
            fields = list(feature["properties"].keys())
            if "style" in fields:
                fields.remove("style")

        value = [
            "<b>{}: </b>{}<br>".format(prop, feature["properties"][prop])
            for prop in fields
        ]

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

    if fill_colors is not None:
        style_callback = random_color

    if style_callback is None:
        geojson = ipyleaflet.GeoJSON(
            data=data,
            style=style,
            hover_style=hover_style,
            name=layer_name,
            **kwargs,
        )
    else:
        geojson = ipyleaflet.GeoJSON(
            data=data,
            style=style,
            hover_style=hover_style,
            name=layer_name,
            style_callback=style_callback,
            **kwargs,
        )

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

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

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

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

    if zoom_to_layer:
        try:
            bounds = gdf.total_bounds
            west, south, east, north = bounds
            self.fit_bounds([[south, east], [north, west]])
        except Exception as e:
            print(e)

add_geotiff(url, name='GeoTIFF', attribution='', opacity=1.0, shown=True, bands=None, titiler_endpoint=None, zoom_to_layer=True, layer_index=None, overwrite=False, **kwargs)

Adds a Cloud Optimized GeoTIFF (COG) to the map.

This helper wraps :meth:add_cog_layer so that users can quickly load a remote GeoTIFF/COG by simply providing its URL. By default it relies on the TiTiler endpoint configured for the map (the public demo endpoint is used when none is provided).

Parameters:

Name	Type	Description	Default
url	str	The HTTP URL of the GeoTIFF/COG.	required
name	str	Layer name to display in the layer tree. Defaults to "GeoTIFF".	'GeoTIFF'
attribution	str	Attribution text for the layer. Defaults to "".	''
opacity	float	Layer opacity between 0.0 and 1.0. Defaults to 1.0.	1.0
shown	bool	Whether the layer should be visible when first added. Defaults to True.	True
bands	Sequence[Union[int, str]]	Specific band indices (1-based) or band names to render. Defaults to None which lets Leafmap pick sensible defaults.	None
titiler_endpoint	str	Custom TiTiler endpoint to use. Defaults to the library's configured endpoint.	None
zoom_to_layer	bool	Whether to fit the map view to the layer bounds after it loads. Defaults to True.	True
layer_index	int	Stack index at which to insert the layer. Defaults to None (append).	None
overwrite	bool	When True, an existing layer with the same name is replaced. Defaults to False.	False
**kwargs		Additional keyword arguments forwarded to :meth:add_cog_layer (e.g., bidx, expression, rescale).	{}

Source code in leafmap/leafmap.py

def add_geotiff(
    self,
    url: str,
    name: str = "GeoTIFF",
    attribution: str = "",
    opacity: float = 1.0,
    shown: bool = True,
    bands: Optional[Sequence[Union[int, str]]] = None,
    titiler_endpoint: Optional[str] = None,
    zoom_to_layer: bool = True,
    layer_index: Optional[int] = None,
    overwrite: bool = False,
    **kwargs,
) -> None:
    """Adds a Cloud Optimized GeoTIFF (COG) to the map.

    This helper wraps :meth:`add_cog_layer` so that users can quickly load a
    remote GeoTIFF/COG by simply providing its URL. By default it relies on
    the TiTiler endpoint configured for the map (the public demo endpoint is
    used when none is provided).

    Args:
        url (str): The HTTP URL of the GeoTIFF/COG.
        name (str, optional): Layer name to display in the layer tree.
            Defaults to ``"GeoTIFF"``.
        attribution (str, optional): Attribution text for the layer.
            Defaults to ``""``.
        opacity (float, optional): Layer opacity between 0.0 and 1.0.
            Defaults to 1.0.
        shown (bool, optional): Whether the layer should be visible when
            first added. Defaults to True.
        bands (Sequence[Union[int, str]], optional): Specific band indices
            (1-based) or band names to render. Defaults to None which lets
            Leafmap pick sensible defaults.
        titiler_endpoint (str, optional): Custom TiTiler endpoint to use.
            Defaults to the library's configured endpoint.
        zoom_to_layer (bool, optional): Whether to fit the map view to the
            layer bounds after it loads. Defaults to True.
        layer_index (int, optional): Stack index at which to insert the
            layer. Defaults to None (append).
        overwrite (bool, optional): When True, an existing layer with the
            same name is replaced. Defaults to False.
        **kwargs: Additional keyword arguments forwarded to
            :meth:`add_cog_layer` (e.g., ``bidx``, ``expression``,
            ``rescale``).
    """
    self.add_cog_layer(
        url,
        name=name,
        attribution=attribution,
        opacity=opacity,
        shown=shown,
        bands=bands,
        titiler_endpoint=titiler_endpoint,
        zoom_to_layer=zoom_to_layer,
        layer_index=layer_index,
        overwrite=overwrite,
        **kwargs,
    )

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

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

Parameters:

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

Raises:

Type	Description
ValueError	If data is not a list.

Source code in leafmap/leafmap.py

def add_heatmap(
    self,
    data: Union[str, list, pd.DataFrame],
    latitude: Optional[str] = "latitude",
    longitude: Optional[str] = "longitude",
    value: Optional[str] = "value",
    name: Optional[str] = "Heat map",
    radius: Optional[int] = 25,
    **kwargs,
) -> None:
    """Adds a heat map to the map. Reference: https://ipyleaflet.readthedocs.io/en/latest/api_reference/heatmap.html

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

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

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

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

    except Exception as e:
        raise Exception(e)

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

Add HTML to the map.

Parameters:

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

Source code in leafmap/leafmap.py

def add_html(
    self, html: str, position: Optional[str] = "bottomright", **kwargs
) -> None:
    """Add HTML to the map.

    Args:
        html (str): The HTML to add.
        position (str, optional): The position of the HTML, can be one of "topleft",
            "topright", "bottomleft", "bottomright". Defaults to "bottomright".
    """
    # Check if an HTML string contains local images and convert them to base64.
    html = common.check_html_string(html)
    self.add_widget(html, position=position, **kwargs)

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

Add an image to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

    """
    import requests

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

    self.add_widget(image, position=position)

add_inspector_gui(position='topright', opened=True)

Add the Inspector widget to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the widget. Defaults to "topright".	'topright'
opened	bool	Whether the widget is open. Defaults to True.	True

Source code in leafmap/leafmap.py

def add_inspector_gui(
    self, position: Optional[str] = "topright", opened: bool = True
) -> None:
    """Add the Inspector widget to the map.

    Args:
        position (str, optional): The position of the widget. Defaults to "topright".
        opened (bool, optional): Whether the widget is open. Defaults to True.
    """

    from .toolbar import inspector_gui

    inspector_gui(self, position, opened)

add_kml(in_kml, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover', **kwargs)

Adds a KML file to the map.

Parameters:

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

Raises:

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

Source code in leafmap/leafmap.py

def add_kml(
    self,
    in_kml: str,
    layer_name: Optional[str] = "Untitled",
    style: Optional[dict] = {},
    hover_style: Optional[dict] = {},
    style_callback: Optional[Callable] = None,
    fill_colors: Optional[list[str]] = None,
    info_mode: Optional[str] = "on_hover",
    **kwargs,
) -> None:
    """Adds a KML file to the map.

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

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

    if in_kml.startswith("http") and in_kml.endswith(".kml"):
        out_dir = os.path.abspath("./cache")
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)
        in_kml = common.download_file(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.")

    self.add_vector(
        in_kml,
        layer_name,
        style=style,
        hover_style=hover_style,
        style_callback=style_callback,
        fill_colors=fill_colors,
        info_mode=info_mode,
        **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://ipyleaflet.readthedocs.io/en/latest/api_reference/divicon.html

Parameters:

Name	Type	Description	Default
data	DataFrame | GeoDataFrame | str	The input data to label.	required
column	str	The column name of the data to label.	required
font_size	str	The font size of the labels. Defaults to "12pt".	'12pt'
font_color	str	The font color of the labels. Defaults to "black".	'black'
font_family	str	The font family of the labels. Defaults to "arial".	'arial'
font_weight	str	The font weight of the labels, can be normal, bold. Defaults to "normal".	'normal'
x	str	The column name of the longitude. Defaults to "longitude".	'longitude'
y	str	The column name of the latitude. Defaults to "latitude".	'latitude'
draggable	bool	Whether the labels are draggable. Defaults to True.	True
layer_name	str	Layer name to use. Defaults to "Labels".	'Labels'

Source code in leafmap/leafmap.py

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

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

    """
    import warnings

    import pandas as pd

    warnings.filterwarnings("ignore")

    if isinstance(data, pd.DataFrame):
        df = data
        if "geometry" in data.columns or ("geom" in data.columns):
            df[x] = df.centroid.x
            df[y] = df.centroid.y

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

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

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

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

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

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

add_layer(layer)

Adds a layer to the map.

Parameters:

Name	Type	Description	Default
layer	ipyleaflet layer	The layer to be added.	required

Source code in leafmap/leafmap.py

def add_layer(self, layer) -> None:
    """Adds a layer to the map.

    Args:
        layer (ipyleaflet layer): The layer to be added.
    """
    existing_layer = self.find_layer(layer.name)
    if existing_layer is not None:
        self.remove_layer(existing_layer)
    super().add(layer)

add_layer_control(position='topright')

Adds a layer control to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the layer control. Defaults to 'topright'.	'topright'

Source code in leafmap/leafmap.py

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

    Args:
        position (str, optional): The position of the layer control. Defaults to 'topright'.
    """

    self.add(ipyleaflet.LayersControl(position=position))

add_layer_manager(position='topright', opened=True)

Add the Layer Manager to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the Layer Manager. Defaults to "topright".	'topright'

Source code in leafmap/leafmap.py

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

    Args:
        position (str, optional): The position of the Layer Manager. Defaults to "topright".
    """
    from .toolbar import layer_manager_gui

    layer_manager_gui(self, position, opened)

add_legend(title='Legend', legend_dict=None, labels=None, colors=None, position='bottomright', builtin_legend=None, layer_name=None, shape_type='rectangle', **kwargs)

Adds a customized basemap to the map.

Parameters:

Name	Type	Description	Default
title	str	Title of the legend. Defaults to 'Legend'.	'Legend'
legend_dict	dict	A dictionary containing legend items as keys and color as values. If provided, legend_keys and legend_colors will be ignored. Defaults to None.	None
labels	list	A list of legend keys. Defaults to None.	None
colors	list	A list of legend colors. Defaults to None.	None
position	str	Position of the legend. Defaults to 'bottomright'.	'bottomright'
builtin_legend	str	Name of the builtin legend to add to the map. Defaults to None.	None
layer_name	str	Layer name of the legend to be associated with. Defaults to None.	None

Source code in leafmap/leafmap.py

def add_legend(
    self,
    title: Optional[str] = "Legend",
    legend_dict: Optional[dict] = None,
    labels: Optional[list] = None,
    colors: Optional[list] = None,
    position: Optional[str] = "bottomright",
    builtin_legend: Optional[str] = None,
    layer_name: Optional[str] = None,
    shape_type: Optional[str] = "rectangle",
    **kwargs,
) -> None:
    """Adds a customized basemap to the map.

    Args:
        title (str, optional): Title of the legend. Defaults to 'Legend'.
        legend_dict (dict, optional): A dictionary containing legend items as keys and color as values. If provided, legend_keys and legend_colors will be ignored. Defaults to None.
        labels (list, optional): A list of legend keys. Defaults to None.
        colors (list, optional): A list of legend colors. Defaults to None.
        position (str, optional): Position of the legend. Defaults to 'bottomright'.
        builtin_legend (str, optional): Name of the builtin legend to add to the map. Defaults to None.
        layer_name (str, optional): Layer name of the legend to be associated with. Defaults to None.

    """
    import importlib.resources

    from IPython.display import display

    pkg_dir = os.path.dirname(importlib.resources.files("leafmap") / "leafmap.py")
    legend_template = os.path.join(pkg_dir, "data/template/legend.html")

    if "min_width" not in kwargs.keys():
        min_width = None
    if "max_width" not in kwargs.keys():
        max_width = None
    else:
        max_width = kwargs["max_width"]
    if "min_height" not in kwargs.keys():
        min_height = None
    else:
        min_height = kwargs["min_height"]
    if "max_height" not in kwargs.keys():
        max_height = None
    else:
        max_height = kwargs["max_height"]
    if "height" not in kwargs.keys():
        height = None
    else:
        height = kwargs["height"]
    if "width" not in kwargs.keys():
        width = None
    else:
        width = kwargs["width"]

    if width is None:
        max_width = "300px"
    if height is None:
        max_height = "400px"

    if not os.path.exists(legend_template):
        print("The legend template does not exist.")
        return

    if labels is not None:
        if not isinstance(labels, list):
            print("The legend keys must be a list.")
            return
    else:
        labels = ["One", "Two", "Three", "Four", "etc"]

    if colors is not None:
        if not isinstance(colors, list):
            print("The legend colors must be a list.")
            return
        elif all(isinstance(item, tuple) for item in colors):
            try:
                colors = [common.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 = [common.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:
        print(
            "The position must be one of the following: {}".format(
                ", ".join(allowed_positions)
            )
        )
        return

    header = []
    content = []
    footer = []

    with open(legend_template) as f:
        lines = f.readlines()
        lines[3] = lines[3].replace("Legend", title)
        header = lines[:6]
        footer = lines[11:]

    for index, key in enumerate(labels):
        color = colors[index]
        if not color.startswith("#"):
            color = "#" + color
        item = "      <li><span style='background:{};'></span>{}</li>\n".format(
            color, key
        )
        content.append(item)

    legend_html = header + content + footer
    legend_text = "".join(legend_html)

    if shape_type == "circle":
        legend_text = legend_text.replace("width: 30px", "width: 16px")
        legend_text = legend_text.replace(
            "border: 1px solid #999;",
            "border-radius: 50%;\n      border: 1px solid #999;",
        )
    elif shape_type == "line":
        legend_text = legend_text.replace("height: 16px", "height: 3px")

    try:

        legend_widget = widgets.HTML(value=legend_text)
        legend_control = ipyleaflet.WidgetControl(
            widget=legend_widget, position=position
        )

        self.legend_widget = legend_widget
        self.legend_control = legend_control
        self.add(legend_control)

    except Exception as e:
        raise Exception(e)

add_marker(location, **kwargs)

Adds a marker to the map. More info about marker at https://ipyleaflet.readthedocs.io/en/latest/api_reference/marker.html.

Parameters:

Name	Type	Description	Default
location	list | tuple	The location of the marker in the format of [lat, lng].	required
**kwargs		Keyword arguments for the marker.	{}

Source code in leafmap/leafmap.py

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

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

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

add_markers(markers, x='lon', y='lat', radius=10, popup=None, font_size=2, stroke=True, color='#0033FF', weight=2, fill=True, fill_color=None, fill_opacity=0.2, opacity=1.0, shape='circle', layer_name='Markers', **kwargs)

Adds markers to the map.

Parameters:

Name	Type	Description	Default
markers	Union[List[List[Union[int, float]]], List[Union[int, float]]]	List of markers. Each marker can be defined as a list of [x, y] coordinates or as a single [x, y] coordinate.	required
x	str	Name of the x-coordinate column in the marker data. Defaults to "lon".	'lon'
y	str	Name of the y-coordinate column in the marker data. Defaults to "lat".	'lat'
radius	int	Radius of the markers. Defaults to 10.	10
popup	str	Popup text for the markers. Defaults to None.	None
font_size	int	Font size of the popup text. Defaults to 2.	2
stroke	bool	Whether to display marker stroke. Defaults to True.	True
color	str	Color of the marker stroke. Defaults to "#0033FF".	'#0033FF'
weight	int	Weight of the marker stroke. Defaults to 2.	2
fill	bool	Whether to fill markers. Defaults to True.	True
fill_color	str	Fill color of the markers. Defaults to None.	None
fill_opacity	float	Opacity of the marker fill. Defaults to 0.2.	0.2
opacity	float	Opacity of the markers. Defaults to 1.0.	1.0
shape	str	Shape of the markers. Options are "circle" or "marker". Defaults to "circle".	'circle'
layer_name	str	Name of the marker layer. Defaults to "Markers".	'Markers'
**kwargs		Additional keyword arguments to pass to the marker plotting function.	{}

Returns:

Name	Type	Description
None	None	This function does not return any value.

Source code in leafmap/leafmap.py

def add_markers(
    self,
    markers: Union[List[List[Union[int, float]]], List[Union[int, float]]],
    x: str = "lon",
    y: str = "lat",
    radius: int = 10,
    popup: Optional[str] = None,
    font_size: int = 2,
    stroke: bool = True,
    color: str = "#0033FF",
    weight: int = 2,
    fill: bool = True,
    fill_color: Optional[str] = None,
    fill_opacity: float = 0.2,
    opacity: float = 1.0,
    shape: str = "circle",
    layer_name: str = "Markers",
    **kwargs,
) -> None:
    """
    Adds markers to the map.

    Args:
        markers (Union[List[List[Union[int, float]]], List[Union[int, float]]]): List of markers.
            Each marker can be defined as a list of [x, y] coordinates or as a single [x, y] coordinate.
        x (str, optional): Name of the x-coordinate column in the marker data. Defaults to "lon".
        y (str, optional): Name of the y-coordinate column in the marker data. Defaults to "lat".
        radius (int, optional): Radius of the markers. Defaults to 10.
        popup (str, optional): Popup text for the markers. Defaults to None.
        font_size (int, optional): Font size of the popup text. Defaults to 2.
        stroke (bool, optional): Whether to display marker stroke. Defaults to True.
        color (str, optional): Color of the marker stroke. Defaults to "#0033FF".
        weight (int, optional): Weight of the marker stroke. Defaults to 2.
        fill (bool, optional): Whether to fill markers. Defaults to True.
        fill_color (str, optional): Fill color of the markers. Defaults to None.
        fill_opacity (float, optional): Opacity of the marker fill. Defaults to 0.2.
        opacity (float, optional): Opacity of the markers. Defaults to 1.0.
        shape (str, optional): Shape of the markers. Options are "circle" or "marker". Defaults to "circle".
        layer_name (str, optional): Name of the marker layer. Defaults to "Markers".
        **kwargs: Additional keyword arguments to pass to the marker plotting function.

    Returns:
        None: This function does not return any value.
    """
    import geopandas as gpd
    import pandas as pd

    if (
        isinstance(markers, list)
        and len(markers) == 2
        and isinstance(markers[0], (int, float))
        and isinstance(markers[1], (int, float))
    ):
        markers = [markers]

    if isinstance(markers, list) and all(
        isinstance(item, list) and len(item) == 2 for item in markers
    ):
        df = pd.DataFrame(markers, columns=[y, x])
        markers = gpd.GeoDataFrame(df, geometry=gpd.points_from_xy(df[x], df[y]))

    if shape == "circle":
        self.add_circle_markers_from_xy(
            markers,
            x,
            y,
            radius,
            popup,
            font_size,
            stroke,
            color,
            weight,
            fill,
            fill_color,
            fill_opacity,
            opacity,
            layer_name,
            **kwargs,
        )

    elif shape == "marker":
        self.add_gdf(markers, **kwargs)

add_minimap(zoom=5, position='bottomright')

Adds a minimap (overview) to the ipyleaflet map.

Parameters:

Name	Type	Description	Default
zoom	int	Initial map zoom level. Defaults to 5.	5
position	str	Position of the minimap. Defaults to "bottomright".	'bottomright'

Source code in leafmap/leafmap.py

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

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

add_mosaic_layer(url=None, titiler_endpoint=None, name='Mosaic Layer', attribution='', opacity=1.0, shown=True, **kwargs)

Adds a STAC TileLayer to the map.

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a MosaicJSON.	None
titiler_endpoint	str	TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space". Defaults to None.	None
name	str	The layer name to use for the layer. Defaults to 'Mosaic Layer'.	'Mosaic Layer'
attribution	str	The attribution to use. Defaults to ''.	''
opacity	float	The opacity of the layer. Defaults to 1.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True

Source code in leafmap/leafmap.py

def add_mosaic_layer(
    self,
    url=None,
    titiler_endpoint=None,
    name="Mosaic Layer",
    attribution="",
    opacity=1.0,
    shown=True,
    **kwargs,
) -> None:
    """Adds a STAC TileLayer to the map.

    Args:
        url (str): HTTP URL to a MosaicJSON.
        titiler_endpoint (str, optional): TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space". Defaults to None.
        name (str, optional): The layer name to use for the layer. Defaults to 'Mosaic Layer'.
        attribution (str, optional): The attribution to use. Defaults to ''.
        opacity (float, optional): The opacity of the layer. Defaults to 1.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
    """
    tile_url = common.mosaic_tile(url, titiler_endpoint, **kwargs)

    bounds = common.mosaic_bounds(url, titiler_endpoint)
    self.add_tile_layer(tile_url, name, attribution, opacity, shown)
    self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

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', lev='lev', level_index=0, time=0, **kwargs)

Generate an ipyleaflet/folium TileLayer from a netCDF file. If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer), try adding to following two lines to the beginning of the notebook if the raster does not render properly.

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

Parameters:

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

Source code in leafmap/leafmap.py

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

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

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

    tif, vars = common.netcdf_to_tif(
        filename,
        shift_lon=shift_lon,
        lat=lat,
        lon=lon,
        lev=lev,
        level_index=level_index,
        time=time,
        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_nlcd(years=[2023], add_legend=True, **kwargs)

Adds National Land Cover Database (NLCD) data to the map.

Parameters:

Name	Type	Description	Default
years	list	A list of years to add. It can be any of 1985-2023. Defaults to [2023].	[2023]
add_legend	bool	Whether to add a legend to the map. Defaults to True.	True
**kwargs		Additional keyword arguments to pass to the add_cog_layer method.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def add_nlcd(self, years: list = [2023], add_legend: bool = True, **kwargs) -> None:
    """
    Adds National Land Cover Database (NLCD) data to the map.

    Args:
        years (list): A list of years to add. It can be any of 1985-2023. Defaults to [2023].
        add_legend (bool): Whether to add a legend to the map. Defaults to True.
        **kwargs: Additional keyword arguments to pass to the add_cog_layer method.

    Returns:
        None
    """
    allowed_years = list(range(1985, 2024, 1))
    url = "https://www.mrlc.gov/downloads/sciweb1/shared/mrlc/data-bundles/Annual_NLCD_LndCov_{}_CU_C1V0.tif"

    if "colormap" not in kwargs:

        kwargs["colormap"] = {
            "11": "#466b9f",
            "12": "#d1def8",
            "21": "#dec5c5",
            "22": "#d99282",
            "23": "#eb0000",
            "24": "#ab0000",
            "31": "#b3ac9f",
            "41": "#68ab5f",
            "42": "#1c5f2c",
            "43": "#b5c58f",
            "51": "#af963c",
            "52": "#ccb879",
            "71": "#dfdfc2",
            "72": "#d1d182",
            "73": "#a3cc51",
            "74": "#82ba9e",
            "81": "#dcd939",
            "82": "#ab6c28",
            "90": "#b8d9eb",
            "95": "#6c9fb8",
        }

    if "zoom_to_layer" not in kwargs:
        kwargs["zoom_to_layer"] = False

    for year in years:
        if year not in allowed_years:
            raise ValueError(f"Year must be one of {allowed_years}.")
        year_url = url.format(year)
        self.add_cog_layer(year_url, name=f"NLCD {year}", **kwargs)
    if add_legend:
        self.add_legend(title="NLCD Land Cover Type", builtin_legend="NLCD")

add_nlcd_ts(left_year=1985, right_layer=2023, widget_width='70px', add_legend=True, add_layer_control=True, **kwargs)

Adds a time series comparison of NLCD (National Land Cover Database) layers to the map.

Parameters:

Name	Type	Description	Default
left_year	int	The initial year for the left layer. Defaults to 1985.	1985
right_layer	int	The initial year for the right layer. Defaults to 2023.	2023
widget_width	str	The width of the dropdown widgets. Defaults to "70px".	'70px'
add_legend	bool	If True, adds a legend to the map. Defaults to True.	True
add_layer_control	bool	If True, adds a layer control to the map. Defaults to True.	True
**kwargs	Any	Additional keyword arguments to pass to the cog_tile function.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def add_nlcd_ts(
    self,
    left_year: int = 1985,
    right_layer: int = 2023,
    widget_width: str = "70px",
    add_legend: bool = True,
    add_layer_control: bool = True,
    **kwargs: Any,
) -> None:
    """
    Adds a time series comparison of NLCD (National Land Cover Database) layers to the map.

    Args:
        left_year (int, optional): The initial year for the left layer. Defaults to 1985.
        right_layer (int, optional): The initial year for the right layer. Defaults to 2023.
        widget_width (str, optional): The width of the dropdown widgets. Defaults to "70px".
        add_legend (bool, optional): If True, adds a legend to the map. Defaults to True.
        add_layer_control (bool, optional): If True, adds a layer control to the map. Defaults to True.
        **kwargs (Any): Additional keyword arguments to pass to the cog_tile function.

    Returns:
        None
    """

    allowed_years = list(range(1985, 2024, 1))

    left_widget = widgets.Dropdown(
        options=allowed_years,
        value=left_year,
        style={"description_width": "initial"},
        layout=widgets.Layout(width=widget_width),
    )
    right_widget = widgets.Dropdown(
        options=allowed_years,
        value=right_layer,
        style={"description_width": "initial"},
        layout=widgets.Layout(width=widget_width),
    )

    left_control = ipyleaflet.WidgetControl(widget=left_widget, position="topleft")
    right_control = ipyleaflet.WidgetControl(
        widget=right_widget, position="topright"
    )

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

    url = (
        "https://s3-us-west-2.amazonaws.com/mrlc/Annual_NLCD_LndCov_{}_CU_C1V0.tif"
    )

    colormap = {
        "11": "#466b9f",
        "12": "#d1def8",
        "21": "#dec5c5",
        "22": "#d99282",
        "23": "#eb0000",
        "24": "#ab0000",
        "31": "#b3ac9f",
        "41": "#68ab5f",
        "42": "#1c5f2c",
        "43": "#b5c58f",
        "51": "#af963c",
        "52": "#ccb879",
        "71": "#dfdfc2",
        "72": "#d1d182",
        "73": "#a3cc51",
        "74": "#82ba9e",
        "81": "#dcd939",
        "82": "#ab6c28",
        "90": "#b8d9eb",
        "95": "#6c9fb8",
    }
    left_url = url.format(left_year)
    right_url = url.format(right_layer)
    left_tile = common.cog_tile(left_url, colormap=colormap, **kwargs)
    right_tile = common.cog_tile(right_url, colormap=colormap, **kwargs)
    left_layer = ipyleaflet.TileLayer(url=left_tile, name=f"NLCD {left_year}")
    right_layer = ipyleaflet.TileLayer(url=right_tile, name=f"NLCD {right_layer}")
    split_control = ipyleaflet.SplitMapControl(
        left_layer=left_layer, right_layer=right_layer
    )
    self.add(split_control)

    if add_layer_control:
        self.add_layer_control()

    if add_legend:
        self.add_legend(title="NLCD Land Cover Type", builtin_legend="NLCD")

    def change_left_year(change):
        left_tile = common.cog_tile(
            url.format(change.new), colormap=colormap, **kwargs
        )
        left_layer.url = left_tile
        left_layer.name = f"NLCD {change.new}"

    def change_right_year(change):
        right_tile = common.cog_tile(
            url.format(change.new), colormap=colormap, **kwargs
        )
        right_layer.url = right_tile
        right_layer.name = f"NLCD {change.new}"

    left_widget.observe(change_left_year, names="value")
    right_widget.observe(change_right_year, names="value")

add_nwi(data, col_name='WETLAND_TY', add_legend=True, style_callback=None, layer_name='Wetlands', **kwargs)

Adds National Wetlands Inventory (NWI) data to the map.

Parameters:

Name	Type	Description	Default
data	Union[str, GeoDataFrame]	The NWI data to add. It can be a file path or a GeoDataFrame.	required
col_name	str	The column name in the GeoDataFrame that contains the wetland types.	'WETLAND_TY'
add_legend	bool	Whether to add a legend to the map. Defaults to True.	True
style_callback	Optional[Callable[[dict], dict]]	A callback function to style the features. Defaults to None.	None
layer_name	str	The name of the layer to add. Defaults to "Wetlands".	'Wetlands'
**kwargs		Additional keyword arguments to pass to the add_vector or add_gdf method.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def add_nwi(
    self,
    data: Union[str, "gpd.GeoDataFrame"],
    col_name: str = "WETLAND_TY",
    add_legend: bool = True,
    style_callback: Optional[Callable[[dict], dict]] = None,
    layer_name: str = "Wetlands",
    **kwargs,
) -> None:
    """
    Adds National Wetlands Inventory (NWI) data to the map.

    Args:
        data (Union[str, gpd.GeoDataFrame]): The NWI data to add. It can be a file path or a GeoDataFrame.
        col_name (str): The column name in the GeoDataFrame that contains the wetland types.
        add_legend (bool): Whether to add a legend to the map. Defaults to True.
        style_callback (Optional[Callable[[dict], dict]]): A callback function to style the features. Defaults to None.
        layer_name (str): The name of the layer to add. Defaults to "Wetlands".
        **kwargs: Additional keyword arguments to pass to the add_vector or add_gdf method.

    Returns:
        None
    """

    nwi = {
        "Freshwater Forested/Shrub Wetland": "#008837",
        "Freshwater Emergent Wetland": "#7fc31c",
        "Freshwater Pond": "#688cc0",
        "Estuarine and Marine Wetland": "#66c2a5",
        "Riverine": "#0190bf",
        "Lake": "#13007c",
        "Estuarine and Marine Deepwater": "#007c88",
        "Other": "#b28656",
    }

    def nwi_color(feature):
        return {
            "color": "black",
            "fillColor": (
                nwi[feature["properties"][col_name]]
                if feature["properties"][col_name] in nwi
                else "gray"
            ),
            "fillOpacity": 0.6,
            "weight": 1,
        }

    if style_callback is None:
        style_callback = nwi_color

    if isinstance(data, str):
        self.add_vector(
            data, style_callback=style_callback, layer_name=layer_name, **kwargs
        )
    else:
        self.add_gdf(
            data, style_callback=style_callback, layer_name=layer_name, **kwargs
        )
    if add_legend:
        self.add_legend(title="Wetland Type", builtin_legend="NWI")

add_oam_gui(position='topright', opened=True)

Add the OpenAerialMap search widget to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the widget. Defaults to "topright".	'topright'
opened	bool	Whether the widget is open. Defaults to True.	True

Source code in leafmap/leafmap.py

def add_oam_gui(
    self, position: Optional[str] = "topright", opened: bool = True
) -> None:
    """Add the OpenAerialMap search widget to the map.

    Args:
        position (str, optional): The position of the widget. Defaults to "topright".
        opened (bool, optional): Whether the widget is open. Defaults to True.
    """
    from .toolbar import oam_search_gui

    oam_search_gui(self, position, opened)

add_opacity_control(layer=None, position='topright', min_opacity=0.0, max_opacity=1.0, step=0.05)

Adds an interactive opacity control panel to the map.

The panel provides a dropdown to choose from the map layers that expose an opacity attribute and a slider to adjust the selected layer's transparency.

Parameters:

Name	Type	Description	Default
layer	str | Layer	Layer (or layer name) to select initially. Defaults to the first available layer.	None
position	str	Location for the widget control. Defaults to "topright".	'topright'
min_opacity	float	Minimum slider value. Defaults to 0.0.	0.0
max_opacity	float	Maximum slider value. Defaults to 1.0.	1.0
step	float	Slider step size. Defaults to 0.05.	0.05

Source code in leafmap/leafmap.py

def add_opacity_control(
    self,
    layer: Optional[Union[str, ipyleaflet.Layer]] = None,
    position: str = "topright",
    min_opacity: float = 0.0,
    max_opacity: float = 1.0,
    step: float = 0.05,
) -> None:
    """Adds an interactive opacity control panel to the map.

    The panel provides a dropdown to choose from the map layers that expose
    an ``opacity`` attribute and a slider to adjust the selected layer's
    transparency.

    Args:
        layer (str | ipyleaflet.Layer, optional): Layer (or layer name) to
            select initially. Defaults to the first available layer.
        position (str, optional): Location for the widget control.
            Defaults to ``"topright"``.
        min_opacity (float, optional): Minimum slider value. Defaults to 0.0.
        max_opacity (float, optional): Maximum slider value. Defaults to 1.0.
        step (float, optional): Slider step size. Defaults to 0.05.
    """

    def build_label(base: str, count: int) -> str:
        return f"{base} ({count})" if count else base

    layer_lookup: Dict[str, ipyleaflet.Layer] = {}
    occurrence: Dict[str, int] = {}

    for lyr in self.layers:
        if hasattr(lyr, "opacity"):
            base = getattr(lyr, "name", None) or lyr.__class__.__name__
            occurrence.setdefault(base, 0)
            label = build_label(base, occurrence[base])
            occurrence[base] += 1
            layer_lookup[label] = lyr

    if not layer_lookup:
        raise RuntimeError(
            "No map layers with an 'opacity' attribute are available."
        )

    if isinstance(layer, ipyleaflet.Layer):
        default_label = next(
            (lbl for lbl, lyr in layer_lookup.items() if lyr is layer), None
        )
    elif isinstance(layer, str):
        default_label = next((lbl for lbl in layer_lookup if lbl == layer), None)
        if default_label is None:
            default_label = next(
                (lbl for lbl in layer_lookup if lbl.startswith(layer)), None
            )
    else:
        default_label = None

    if default_label is None:
        default_label = list(layer_lookup.keys())[-1]

    dropdown = widgets.Dropdown(
        options=list(layer_lookup.keys()),
        value=default_label,
        description="Layer",
        layout=widgets.Layout(width="260px"),
    )

    selected_layer = layer_lookup[dropdown.value]
    current_opacity = getattr(selected_layer, "opacity", max_opacity)
    slider = widgets.FloatSlider(
        value=max(min(current_opacity, max_opacity), min_opacity),
        min=min_opacity,
        max=max_opacity,
        step=step,
        description="Opacity",
        readout=True,
        readout_format=".2f",
        layout=widgets.Layout(width="260px"),
    )

    status = widgets.Label()

    def set_status(msg: str) -> None:
        status.value = msg

    def apply_opacity(target: ipyleaflet.Layer, value: float) -> None:
        try:
            setattr(target, "opacity", value)
        except Exception as exc:  # pragma: no cover - defensive
            set_status(f"Failed to set opacity: {exc}")
        else:
            set_status(f"{target.__class__.__name__} opacity: {value:.2f}")

    def on_slider(change: Dict[str, Any]) -> None:
        if change["name"] != "value" or change["new"] == change["old"]:
            return
        lyr = layer_lookup[dropdown.value]
        apply_opacity(lyr, change["new"])

    def on_dropdown(change: Dict[str, Any]) -> None:
        if change["name"] != "value" or change["new"] == change["old"]:
            return
        lyr = layer_lookup[change["new"]]
        slider.value = max(
            min(getattr(lyr, "opacity", slider.value), max_opacity), min_opacity
        )
        apply_opacity(lyr, slider.value)

    slider.observe(on_slider, "value")
    dropdown.observe(on_dropdown, "value")

    apply_opacity(selected_layer, slider.value)

    panel = widgets.VBox([dropdown, slider])
    control = ipyleaflet.WidgetControl(widget=panel, position=position)
    self.add(control)
    self.opacity_control = control

add_osm_from_address(address, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover')

Adds OSM entities within some distance N, S, E, W of address to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

    """
    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={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover')

Adds OSM entities within a N, S, E, W bounding box to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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


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

    """
    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, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover')

Adds OSM data of place(s) by name or ID to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

    """

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

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

add_osm_from_place(query, tags, which_result=None, buffer_dist=None, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover')

Adds OSM entities within boundaries of geocodable place(s) to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

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

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

add_osm_from_point(center_point, tags, dist=1000, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover')

Adds OSM entities within some distance N, S, E, W of a point to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

    """
    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={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover')

Adds OSM entities within boundaries of a (multi)polygon to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

    """
    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_osm_from_view(tags, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover')

Adds OSM entities within the current map view to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

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

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

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

add_planet_by_month(year=2016, month=1, layer_name=None, api_key=None, token_name='PLANET_API_KEY', **kwargs)

Adds a Planet global mosaic by month to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

Name	Type	Description	Default
year	int	The year of Planet global mosaic, must be >=2016. Defaults to 2016.	2016
month	int	The month of Planet global mosaic, must be 1-12. Defaults to 1.	1
layer_name	str	The layer name to use. Defaults to None.	None
api_key	str	The Planet API key. Defaults to None.	None
token_name	str	The environment variable name of the API key. Defaults to "PLANET_API_KEY".	'PLANET_API_KEY'

Source code in leafmap/leafmap.py

def add_planet_by_month(
    self,
    year: Optional[int] = 2016,
    month: Optional[int] = 1,
    layer_name: Optional[str] = None,
    api_key: Optional[str] = None,
    token_name: Optional[str] = "PLANET_API_KEY",
    **kwargs,
) -> 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 (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
        month (int, optional): The month of Planet global mosaic, must be 1-12. Defaults to 1.
        layer_name (str, optional): The layer name to use. Defaults to None.
        api_key (str, optional): The Planet API key. Defaults to None.
        token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
    """
    if layer_name is None and "name" in kwargs:
        layer_name = kwargs.pop("name")
    layer = common.planet_tile_by_month(
        year, month, layer_name, api_key, token_name
    )
    self.add(layer)

add_planet_by_quarter(year=2016, quarter=1, layer_name=None, api_key=None, token_name='PLANET_API_KEY', **kwargs)

Adds a Planet global mosaic by quarter to the map. To get a Planet API key, see https://developers.planet.com/quickstart/apis

Parameters:

Name	Type	Description	Default
year	int	The year of Planet global mosaic, must be >=2016. Defaults to 2016.	2016
quarter	int	The quarter of Planet global mosaic, must be 1-12. Defaults to 1.	1
layer_name	str	The layer name to use. Defaults to None.	None
api_key	str	The Planet API key. Defaults to None.	None
token_name	str	The environment variable name of the API key. Defaults to "PLANET_API_KEY".	'PLANET_API_KEY'

Source code in leafmap/leafmap.py

def add_planet_by_quarter(
    self,
    year: Optional[int] = 2016,
    quarter: Optional[int] = 1,
    layer_name: Optional[str] = None,
    api_key: Optional[str] = None,
    token_name: Optional[str] = "PLANET_API_KEY",
    **kwargs,
) -> 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 (int, optional): The year of Planet global mosaic, must be >=2016. Defaults to 2016.
        quarter (int, optional): The quarter of Planet global mosaic, must be 1-12. Defaults to 1.
        layer_name (str, optional): The layer name to use. Defaults to None.
        api_key (str, optional): The Planet API key. Defaults to None.
        token_name (str, optional): The environment variable name of the API key. Defaults to "PLANET_API_KEY".
    """
    if layer_name is None and "name" in kwargs:
        layer_name = kwargs.pop("name")
    layer = common.planet_tile_by_quarter(
        year, quarter, layer_name, api_key, token_name
    )
    self.add(layer)

add_pmtiles(url, style=None, name='PMTiles', show=True, zoom_to_layer=True, **kwargs)

Adds a PMTiles layer to the map. This function is not officially supported yet by ipyleaflet yet. Install it with the following command: pip install git+https://github.com/giswqs/ipyleaflet.git@pmtiles

Parameters:

Name	Type	Description	Default
url	str	The URL of the PMTiles file.	required
style	str	The CSS style to apply to the layer. Defaults to None. See https://docs.mapbox.com/style-spec/reference/layers/ for more info.	None
name	str	The name of the layer. Defaults to None.	'PMTiles'
show	bool	Whether the layer should be shown initially. Defaults to True.	True
zoom_to_layer	bool	Whether to zoom to the layer extent. Defaults to True.	True
**kwargs		Additional keyword arguments to pass to the PMTilesLayer constructor.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def add_pmtiles(
    self,
    url,
    style=None,
    name="PMTiles",
    show=True,
    zoom_to_layer=True,
    **kwargs,
) -> None:
    """
    Adds a PMTiles layer to the map. This function is not officially supported yet by ipyleaflet yet.
    Install it with the following command:
    pip install git+https://github.com/giswqs/ipyleaflet.git@pmtiles

    Args:
        url (str): The URL of the PMTiles file.
        style (str, optional): The CSS style to apply to the layer. Defaults to None.
            See https://docs.mapbox.com/style-spec/reference/layers/ for more info.
        name (str, optional): The name of the layer. Defaults to None.
        show (bool, optional): Whether the layer should be shown initially. Defaults to True.
        zoom_to_layer (bool, optional): Whether to zoom to the layer extent. Defaults to True.
        **kwargs: Additional keyword arguments to pass to the PMTilesLayer constructor.

    Returns:
        None
    """

    try:
        if "sources" in kwargs:
            del kwargs["sources"]

        if "version" in kwargs:
            del kwargs["version"]

        if style is None:
            style = common.pmtiles_style(url)

        layer = ipyleaflet.PMTilesLayer(
            url=url,
            style=style,
            name=name,
            visible=show,
            **kwargs,
        )
        self.add(layer)

        if zoom_to_layer:
            metadata = common.pmtiles_metadata(url)
            bounds = metadata["bounds"]
            self.zoom_to_bounds(bounds)
    except Exception as e:
        print(e)

add_point_layer(filename, popup=None, layer_name='Marker Cluster', **kwargs)

Adds a point layer to the map with a popup attribute.

Parameters:

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

Raises:

Type	Description
ValueError	If the specified column name does not exist.
ValueError	If the specified column names do not exist.

Source code in leafmap/leafmap.py

def add_point_layer(
    self,
    filename: str,
    popup: Optional[Union[list, str]] = None,
    layer_name: Optional[str] = "Marker Cluster",
    **kwargs,
) -> None:
    """Adds a point layer to the map with a popup attribute.

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

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

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

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

    if isinstance(filename, gpd.GeoDataFrame):
        gdf = filename
    else:
        if not filename.startswith("http"):
            filename = os.path.abspath(filename)
        ext = os.path.splitext(filename)[1].lower()
        if ext == ".kml":
            fiona.drvsupport.supported_drivers["KML"] = "rw"
            gdf = gpd.read_file(filename, driver="KML", **kwargs)
        else:
            gdf = gpd.read_file(filename, **kwargs)
    df = gdf.to_crs(epsg="4326")
    col_names = df.columns.values.tolist()
    if popup is not None:
        if isinstance(popup, str) and (popup not in col_names):
            raise ValueError(
                f"popup must be one of the following: {', '.join(col_names)}"
            )
        elif isinstance(popup, list) and (
            not all(item in col_names for item in popup)
        ):
            raise ValueError(
                f"All popup items must be select from: {', '.join(col_names)}"
            )

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

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

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

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

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

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

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

add_points_from_xy(data, x='longitude', y='latitude', popup=None, layer_name='Marker Cluster', color_column=None, marker_colors=None, icon_colors=['white'], icon_names=['info'], spin=False, add_legend=True, 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. Defaults to "longitude".	'longitude'
y	str	The column name for the y values. Defaults to "latitude".	'latitude'
popup	list	A list of column names to be used as the popup. Defaults to None.	None
layer_name	str	The name of the layer. Defaults to "Marker Cluster".	'Marker Cluster'
color_column	str	The column name for the color values. Defaults to None.	None
marker_colors	list	A list of colors to be used for the markers. Defaults to None.	None
icon_colors	list	A list of colors to be used for the icons. Defaults to ['white'].	['white']
icon_names	list	A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons. Defaults to ['info'].	['info']
spin	bool	If True, the icon will spin. Defaults to False.	False
add_legend	bool	If True, a legend will be added to the map. Defaults to True.	True
max_cluster_radius	int	The maximum cluster radius. Defaults to 80.	80
**kwargs		Other keyword arguments to pass to ipyleaflet.MarkerCluster(). For a list of available options, see https://github.com/Leaflet/Leaflet.markercluster.	{}

Source code in leafmap/leafmap.py

def add_points_from_xy(
    self,
    data: Optional[Union[pd.DataFrame, str]],
    x: Optional[str] = "longitude",
    y: Optional[str] = "latitude",
    popup: Optional[list] = None,
    layer_name: Optional[str] = "Marker Cluster",
    color_column: Optional[str] = None,
    marker_colors: Optional[str] = None,
    icon_colors: Optional[list[str]] = ["white"],
    icon_names: Optional[list[str]] = ["info"],
    spin: Optional[bool] = False,
    add_legend: Optional[bool] = True,
    max_cluster_radius: Optional[int] = 80,
    **kwargs,
) -> None:
    """Adds a marker cluster to the map.

    Args:
        data (str | pd.DataFrame): A csv or Pandas DataFrame containing x, y, z values.
        x (str, optional): The column name for the x values. Defaults to "longitude".
        y (str, optional): The column name for the y values. Defaults to "latitude".
        popup (list, optional): A list of column names to be used as the popup. Defaults to None.
        layer_name (str, optional): The name of the layer. Defaults to "Marker Cluster".
        color_column (str, optional): The column name for the color values. Defaults to None.
        marker_colors (list, optional): A list of colors to be used for the markers. Defaults to None.
        icon_colors (list, optional): A list of colors to be used for the icons. Defaults to ['white'].
        icon_names (list, optional): A list of names to be used for the icons. More icons can be found at https://fontawesome.com/v4/icons. Defaults to ['info'].
        spin (bool, optional): If True, the icon will spin. Defaults to False.
        add_legend (bool, optional): If True, a legend will be added to the map. Defaults to True.
        max_cluster_radius (int, optional): The maximum cluster radius. Defaults to 80.
        **kwargs: Other keyword arguments to pass to ipyleaflet.MarkerCluster(). For a list of available options,
            see https://github.com/Leaflet/Leaflet.markercluster.

    """
    import pandas as pd

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

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

        gdf = gpd.read_file(data)
        df = common.gdf_to_df(gdf)

    df = common.points_from_xy(df, x, y)

    col_names = df.columns.values.tolist()

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

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

    else:
        items = None

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

add_raster(source, indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name='Raster', layer_index=None, zoom_to_layer=True, visible=True, opacity=1.0, array_args={}, client_args={'cors_all': False}, overwrite=False, **kwargs)

Add a local raster dataset to the map. If you are using this function in JupyterHub on a remote server (e.g., Binder, Microsoft Planetary Computer) and if the raster does not render properly, try installing jupyter-server-proxy using pip install jupyter-server-proxy, then running the following code before calling this function. For more info, see https://bit.ly/3JbmF93.

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

Parameters:

Name	Type	Description	Default
source	str	The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.	required
indexes	int	The band(s) to use. Band indexing starts at 1. Defaults to None.	None
colormap	str	The name of the colormap from matplotlib to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.	None
vmin	float	The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
vmax	float	The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
nodata	float	The value from the band to use to interpret as not valid data. Defaults to None.	None
attribution	str	Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.	None
layer_name	str	The layer name to use. Defaults to 'Raster'.	'Raster'
layer_index	int	The index of the layer. Defaults to None.	None
zoom_to_layer	bool	Whether to zoom to the extent of the layer. Defaults to True.	True
visible	bool	Whether the layer is visible. Defaults to True.	True
opacity	float	The opacity of the layer. Defaults to 1.0.	1.0
array_args	dict	Additional arguments to pass to array_to_memory_file when reading the raster. Defaults to {}.	{}
client_args	dict	Additional arguments to pass to localtileserver.TileClient. Defaults to { "cors_all": False }.	{'cors_all': False}
overwrite	bool	Whether to overwrite an existing layer with the same name. Defaults to False.	False

Source code in leafmap/leafmap.py

def add_raster(
    self,
    source: str,
    indexes: Optional[int] = None,
    colormap: Optional[str] = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    nodata: Optional[float] = None,
    attribution: Optional[str] = None,
    layer_name: Optional[str] = "Raster",
    layer_index: Optional[int] = None,
    zoom_to_layer: Optional[bool] = True,
    visible: Optional[bool] = True,
    opacity: Optional[float] = 1.0,
    array_args: Optional[Dict] = {},
    client_args: Optional[Dict] = {"cors_all": False},
    overwrite: Optional[bool] = False,
    **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 (str): The path to the GeoTIFF file or the URL of the Cloud Optimized GeoTIFF.
        indexes (int, optional): The band(s) to use. Band indexing starts at 1. Defaults to None.
        colormap (str, optional): The name of the colormap from `matplotlib` to use when plotting a single band. See https://matplotlib.org/stable/gallery/color/colormap_reference.html. Default is greyscale.
        vmin (float, optional): The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.
        vmax (float, optional): The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.
        nodata (float, optional): The value from the band to use to interpret as not valid data. Defaults to None.
        attribution (str, optional): Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.
        layer_name (str, optional): The layer name to use. Defaults to 'Raster'.
        layer_index (int, optional): The index of the layer. Defaults to None.
        zoom_to_layer (bool, optional): Whether to zoom to the extent of the layer. Defaults to True.
        visible (bool, optional): Whether the layer is visible. Defaults to True.
        opacity (float, optional): The opacity of the layer. Defaults to 1.0.
        array_args (dict, optional): Additional arguments to pass to `array_to_memory_file` when reading the raster. Defaults to {}.
        client_args (dict, optional): Additional arguments to pass to localtileserver.TileClient. Defaults to { "cors_all": False }.
        overwrite (bool, optional): Whether to overwrite an existing layer with the same name. Defaults to False.
    """
    import numpy as np
    import xarray as xr

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

    tile_layer = common.get_local_tile_layer(
        source,
        indexes=indexes,
        colormap=colormap,
        vmin=vmin,
        vmax=vmax,
        nodata=nodata,
        opacity=opacity,
        attribution=attribution,
        layer_name=layer_name,
        client_args=client_args,
        return_client=False,
        **kwargs,
    )
    tile_layer.visible = visible
    tile_client = tile_layer.tile_server
    tile_layer.name = self._check_layer_name(layer_name, overwrite=overwrite)

    if overwrite and layer_name in self.get_layer_names():
        layer = self.find_layer(tile_layer.name)
        if layer is not None:
            self.remove(layer)

    self.add(tile_layer, index=layer_index)
    if zoom_to_layer:
        self.center = tile_client.center()
        try:
            self.zoom = tile_client.default_zoom
        except AttributeError:
            self.zoom = 15

    common.arc_add_layer(tile_layer.url, tile_layer.name, True, 1.0)

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

    if indexes is None:
        if len(tile_client.band_names) == 1:
            indexes = [1]
        else:
            indexes = [1, 2, 3]

    vis_bands = [tile_client.band_names[i - 1] for i in indexes]

    params = {
        "tile_layer": tile_layer,
        "tile_client": tile_client,
        "indexes": indexes,
        "vis_bands": vis_bands,
        "band_names": tile_client.band_names,
        "vmin": vmin,
        "vmax": vmax,
        "nodata": nodata,
        "colormap": colormap,
        "opacity": opacity,
        "layer_name": tile_layer.name,
        "filename": tile_client.filename,
        "type": "LOCAL",
    }
    self.cog_layer_dict[tile_layer.name] = params
    self.tile_client = tile_client

add_remote_tile(source, band=None, palette=None, vmin=None, vmax=None, nodata=None, attribution=None, layer_name=None, **kwargs)

Add a remote Cloud Optimized GeoTIFF (COG) to the map.

Parameters:

Name	Type	Description	Default
source	str	The path to the remote Cloud Optimized GeoTIFF.	required
band	int	The band to use. Band indexing starts at 1. Defaults to None.	None
palette	str	The name of the color palette from palettable to use when plotting a single band. See https://jiffyclub.github.io/palettable. Default is greyscale	None
vmin	float	The minimum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
vmax	float	The maximum value to use when colormapping the palette when plotting a single band. Defaults to None.	None
nodata	float	The value from the band to use to interpret as not valid data. Defaults to None.	None
attribution	str	Attribution for the source raster. This defaults to a message about it being a local file.. Defaults to None.	None
layer_name	str	The layer name to use. Defaults to None.	None

Source code in leafmap/leafmap.py

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

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

add_search_control(url, marker=None, zoom=None, position='topleft', **kwargs)

Adds a search control to the map.

Parameters:

Name	Type	Description	Default
url	str	The url to the search API. For example, "https://nominatim.openstreetmap.org/search?format=json&q={s}".	required
marker	Marker	The marker to be used for the search result. Defaults to None.	None
zoom	int	The zoom level to be used for the search result. Defaults to None.	None
position	str	The position of the search control. Defaults to "topleft".	'topleft'
kwargs	dict	Additional keyword arguments to be passed to the search control. See https://ipyleaflet.readthedocs.io/en/latest/api_reference/search_control.html	{}

Source code in leafmap/leafmap.py

def add_search_control(
    self,
    url: str,
    marker: Optional[ipyleaflet.Marker] = None,
    zoom: Optional[int] = None,
    position: Optional[str] = "topleft",
    **kwargs,
) -> None:
    """Adds a search control to the map.

    Args:
        url (str): The url to the search API. For example, "https://nominatim.openstreetmap.org/search?format=json&q={s}".
        marker (ipyleaflet.Marker, optional): The marker to be used for the search result. Defaults to None.
        zoom (int, optional): The zoom level to be used for the search result. Defaults to None.
        position (str, optional): The position of the search control. Defaults to "topleft".
        kwargs (dict, optional): Additional keyword arguments to be passed to the search control. See https://ipyleaflet.readthedocs.io/en/latest/api_reference/search_control.html
    """
    if marker is None:
        marker = ipyleaflet.Marker(
            icon=ipyleaflet.AwesomeIcon(
                name="check", marker_color="green", icon_color="darkred"
            )
        )
    search_control = ipyleaflet.SearchControl(
        position=position,
        url=url,
        zoom=zoom,
        marker=marker,
    )
    self.add(search_control)
    self.search_control = search_control

add_shp(in_shp, layer_name='Untitled', style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover', zoom_to_layer=False, encoding='utf-8', **kwargs)

Adds a shapefile to the map.

Parameters:

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

Raises:

Type	Description
FileNotFoundError	The provided shapefile could not be found.

Source code in leafmap/leafmap.py

def add_shp(
    self,
    in_shp: str,
    layer_name: Optional[str] = "Untitled",
    style: Optional[Dict] = {},
    hover_style: Optional[Dict] = {},
    style_callback: Optional[Callable] = None,
    fill_colors: Optional[list[str]] = None,
    info_mode: Optional[str] = "on_hover",
    zoom_to_layer: Optional[bool] = False,
    encoding: Optional[str] = "utf-8",
    **kwargs,
) -> None:
    """Adds a shapefile to the map.

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

    Raises:
        FileNotFoundError: The provided shapefile could not be found.
    """

    import geopandas as gpd

    gdf = gpd.read_file(in_shp, encoding=encoding)
    self.add_gdf(
        gdf,
        layer_name,
        style,
        hover_style,
        style_callback,
        fill_colors,
        info_mode,
        zoom_to_layer,
        encoding,
        **kwargs,
    )

add_stac_gui(position='topright', opened=True)

Add the STAC search widget to the map.

Parameters:

Name	Type	Description	Default
position	str	The position of the widget. Defaults to "topright".	'topright'
opened	bool	Whether the widget is open. Defaults to True.	True

Source code in leafmap/leafmap.py

def add_stac_gui(self, position: str = "topright", opened: bool = True) -> None:
    """Add the STAC search widget to the map.

    Args:
        position (str, optional): The position of the widget. Defaults to "topright".
        opened (bool, optional): Whether the widget is open. Defaults to True.
    """
    from .toolbar import stac_gui

    stac_gui(self, position, opened)

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, fit_bounds=True, layer_index=None, **kwargs)

Adds a STAC TileLayer to the map.

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json	None
collection	str	The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.	None
item	str	The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.	None
assets	str | list	The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"].	None
bands	list	A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]	None
titiler_endpoint	str	TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space", "https://planetarycomputer.microsoft.com/api/data/v1", "planetary-computer", "pc". Defaults to None.	None
name	str	The layer name to use for the layer. Defaults to 'STAC Layer'.	'STAC Layer'
attribution	str	The attribution to use. Defaults to ''.	''
opacity	float	The opacity of the layer. Defaults to 1.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
fit_bounds	bool	A flag indicating whether the map should be zoomed to the layer extent. Defaults to True.	True
layer_index	int	The index at which to add the layer. Defaults to None.	None

Source code in leafmap/leafmap.py

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

    Args:
        url (str): HTTP URL to a STAC item, e.g., https://canada-spot-ortho.s3.amazonaws.com/canada_spot_orthoimages/canada_spot5_orthoimages/S5_2007/S5_11055_6057_20070622/S5_11055_6057_20070622.json
        collection (str): The Microsoft Planetary Computer STAC collection ID, e.g., landsat-8-c2-l2.
        item (str): The Microsoft Planetary Computer STAC item ID, e.g., LC08_L2SP_047027_20201204_02_T1.
        assets (str | list): The Microsoft Planetary Computer STAC asset ID, e.g., ["SR_B7", "SR_B5", "SR_B4"].
        bands (list): A list of band names, e.g., ["SR_B7", "SR_B5", "SR_B4"]
        titiler_endpoint (str, optional): TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space", "https://planetarycomputer.microsoft.com/api/data/v1", "planetary-computer", "pc". Defaults to None.
        name (str, optional): The layer name to use for the layer. Defaults to 'STAC Layer'.
        attribution (str, optional): The attribution to use. Defaults to ''.
        opacity (float, optional): The opacity of the layer. Defaults to 1.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        fit_bounds (bool, optional): A flag indicating whether the map should be zoomed to the layer extent. Defaults to True.
        layer_index (int, optional): The index at which to add the layer. Defaults to None.
    """

    if os.environ.get("USE_MKDOCS") is not None:
        return

    if "colormap_name" in kwargs and kwargs["colormap_name"] is None:
        kwargs.pop("colormap_name")

    tile_url = common.stac_tile(
        url, collection, item, assets, bands, titiler_endpoint, **kwargs
    )
    if tile_url is None:
        return
    bounds = common.stac_bounds(url, collection, item, titiler_endpoint)
    self.add_tile_layer(tile_url, name, attribution, opacity, shown, layer_index)
    if fit_bounds and bounds is not None:
        self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])
        common.arc_zoom_to_extent(bounds[0], bounds[1], bounds[2], bounds[3])

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

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

    if isinstance(assets, str) and "," in assets:
        assets = assets.split(",")

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

    if "rescale" in kwargs:
        rescale = kwargs["rescale"]
        vmin, vmax = [float(v) for v in rescale.split(",")]
    else:
        vmin, vmax = common.stac_min_max(
            url, collection, item, assets, titiler_endpoint
        )

    if "nodata" in kwargs:
        nodata = kwargs["nodata"]
    else:
        nodata = None

    band_names = common.stac_bands(url, collection, item, titiler_endpoint)

    if assets is not None:
        indexes = [band_names.index(band) + 1 for band in assets]
    else:
        indexes = None

    params = {
        "url": url,
        "titiler_endpoint": titiler_endpoint,
        "collection": collection,
        "item": item,
        "assets": assets,
        "tile_layer": self.find_layer(name),
        "indexes": indexes,
        "vis_bands": assets,
        "band_names": band_names,
        "bounds": bounds,
        "vmin": vmin,
        "vmax": vmax,
        "nodata": nodata,
        "opacity": opacity,
        "layer_name": name,
        "type": "STAC",
    }

    self.cog_layer_dict[name] = params

add_text(text, fontsize=20, fontcolor='black', bold=False, padding='5px', background=True, bg_color='white', border_radius='5px', position='bottomright', **kwargs)

Add text to the map.

Parameters:

Name	Type	Description	Default
text	str	The text to add.	required
fontsize	int	The font size. Defaults to 20.	20
fontcolor	str	The font color. Defaults to "black".	'black'
bold	bool	Whether to use bold font. Defaults to False.	False
padding	str	The padding. Defaults to "5px".	'5px'
background	bool	Whether to use background. Defaults to True.	True
bg_color	str	The background color. Defaults to "white".	'white'
border_radius	str	The border radius. Defaults to "5px".	'5px'
position	str	The position of the widget. Defaults to "bottomright".	'bottomright'

Source code in leafmap/leafmap.py

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

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

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

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

add_tile_layer(url, name, attribution, opacity=1.0, shown=True, layer_index=None, **kwargs)

Adds a TileLayer to the map.

Parameters:

Name	Type	Description	Default
url	str	The URL of the tile layer.	required
name	str	The layer name to use for the layer.	required
attribution	str	The attribution to use.	required
opacity	float	The opacity of the layer. Defaults to 1.	1.0
shown	bool	A flag indicating whether the layer should be on by default. Defaults to True.	True
layer_index	int	The index at which to add the layer. Defaults to None.	None

Source code in leafmap/leafmap.py

def add_tile_layer(
    self,
    url,
    name,
    attribution,
    opacity=1.0,
    shown=True,
    layer_index=None,
    **kwargs,
) -> None:
    """Adds a TileLayer to the map.

    Args:
        url (str): The URL of the tile layer.
        name (str): The layer name to use for the layer.
        attribution (str): The attribution to use.
        opacity (float, optional): The opacity of the layer. Defaults to 1.
        shown (bool, optional): A flag indicating whether the layer should be on by default. Defaults to True.
        layer_index (int, optional): The index at which to add the layer. Defaults to None.
    """
    if "max_zoom" not in kwargs:
        kwargs["max_zoom"] = 30
    if "max_native_zoom" not in kwargs:
        kwargs["max_native_zoom"] = 30
    try:
        tile_layer = ipyleaflet.TileLayer(
            url=url,
            name=name,
            attribution=attribution,
            opacity=opacity,
            visible=shown,
            **kwargs,
        )
        self.add(tile_layer, index=layer_index)

        common.arc_add_layer(url, name, shown, opacity)

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

add_time_slider(layers={}, labels=None, time_interval=1, position='bottomright', slider_length='150px', zoom_to_layer=False, tile_args=None, **kwargs)

Adds a time slider to the map.

Parameters:

Name	Type	Description	Default
layers	dict	The dictionary containing a set of XYZ tile layers.	{}
labels	list	The list of labels to be used for the time series. Defaults to None.	None
time_interval	int	Time interval in seconds. Defaults to 1.	1
position	str	Position to place the time slider, can be any of ['topleft', 'topright', 'bottomleft', 'bottomright']. Defaults to "bottomright".	'bottomright'
slider_length	str	Length of the time slider. Defaults to "150px".	'150px'
zoom_to_layer	bool	Whether to zoom to the extent of the selected layer. Defaults to False.	False
tile_args	dict	Additional arguments to pass to the get_local_tile_layer function. Defaults to None.	None

Source code in leafmap/leafmap.py

def add_time_slider(
    self,
    layers: dict = {},
    labels: list = None,
    time_interval: int = 1,
    position: str = "bottomright",
    slider_length: str = "150px",
    zoom_to_layer: Optional[bool] = False,
    tile_args: Optional[Dict] = None,
    **kwargs,
) -> None:
    """Adds a time slider to the map.

    Args:
        layers (dict, optional): The dictionary containing a set of XYZ tile layers.
        labels (list, optional): The list of labels to be used for the time series. Defaults to None.
        time_interval (int, optional): Time interval in seconds. Defaults to 1.
        position (str, optional): Position to place the time slider, can be any of ['topleft', 'topright', 'bottomleft', 'bottomright']. Defaults to "bottomright".
        slider_length (str, optional): Length of the time slider. Defaults to "150px".
        zoom_to_layer (bool, optional): Whether to zoom to the extent of the selected layer. Defaults to False.
        tile_args (dict, optional): Additional arguments to pass to the get_local_tile_layer function. Defaults to None.
    """
    from .toolbar import time_slider

    time_slider(
        self,
        layers,
        labels,
        time_interval,
        position,
        slider_length,
        zoom_to_layer,
        tile_args,
        **kwargs,
    )

add_vector(filename, layer_name='Untitled', bbox=None, mask=None, rows=None, style={}, hover_style={}, style_callback=None, fill_colors=None, info_mode='on_hover', zoom_to_layer=False, encoding='utf-8', **kwargs)

Adds any geopandas-supported vector dataset to the map.

Parameters:

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

Source code in leafmap/leafmap.py

def add_vector(
    self,
    filename: str,
    layer_name: Optional[str] = "Untitled",
    bbox: Optional[tuple] = None,
    mask: Optional[dict] = None,
    rows: Optional[tuple[int]] = None,
    style: Optional[dict] = {},
    hover_style: Optional[dict] = {},
    style_callback: Optional[Callable] = None,
    fill_colors: list[str] = None,
    info_mode: Optional[str] = "on_hover",
    zoom_to_layer: Optional[bool] = False,
    encoding: Optional[str] = "utf-8",
    **kwargs,
) -> None:
    """Adds any geopandas-supported vector dataset to the map.

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

    """
    import fiona
    import geopandas as gpd

    if isinstance(filename, str) and filename.endswith(".kml"):
        fiona.drvsupport.supported_drivers["KML"] = "rw"
        kwargs["driver"] = "KML"

    gdf = gpd.read_file(
        filename, bbox=bbox, mask=mask, rows=rows, encoding=encoding, **kwargs
    )

    self.add_gdf(
        gdf,
        layer_name,
        style,
        hover_style,
        style_callback,
        fill_colors,
        info_mode,
        zoom_to_layer,
        encoding,
        **kwargs,
    )

add_vector_tile(url, styles={}, layer_name='Vector Tile', **kwargs)

Adds a VectorTileLayer to the map. It wraps the ipyleaflet.VectorTileLayer class. See https://ipyleaflet.readthedocs.io/en/latest/layers/vector_tile.html

Parameters:

Name	Type	Description	Default
url	str	The URL of the tile layer	required
styles	(dict, optional)	Style dict, specific to the vector tile source.	{}
layer_name	str	The layer name to use for the layer. Defaults to 'Vector Tile'.	'Vector Tile'
kwargs		Additional keyword arguments to pass to the ipyleaflet.VectorTileLayer class.	{}

Source code in leafmap/leafmap.py

def add_vector_tile(
    self,
    url,
    styles: Optional[dict] = {},
    layer_name: Optional[str] = "Vector Tile",
    **kwargs,
) -> None:
    """Adds a VectorTileLayer to the map. It wraps the ipyleaflet.VectorTileLayer class. See
        https://ipyleaflet.readthedocs.io/en/latest/layers/vector_tile.html

    Args:
        url (str, optional): The URL of the tile layer
        styles (dict,optional): Style dict, specific to the vector tile source.
        layer_name (str, optional): The layer name to use for the layer. Defaults to 'Vector Tile'.
        kwargs: Additional keyword arguments to pass to the ipyleaflet.VectorTileLayer class.
    """
    if "vector_tile_layer_styles" in kwargs:
        styles = kwargs["vector_tile_layer_styles"]
        del kwargs["vector_tile_layer_styles"]
    try:
        vector_tile_layer = ipyleaflet.VectorTileLayer(
            url=url,
            vector_tile_layer_styles=styles,
            **kwargs,
        )
        vector_tile_layer.name = layer_name
        self.add(vector_tile_layer)

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

add_velocity(data, zonal_speed, meridional_speed, latitude_dimension='lat', longitude_dimension='lon', level_dimension='lev', level_index=0, time_index=0, velocity_scale=0.01, max_velocity=20, display_options={}, name='Velocity', color_scale=None)

Add a velocity layer to the map.

Parameters:

Name	Type	Description	Default
data	str | Dataset	The data to use for the velocity layer. It can be a file path to a NetCDF file or an xarray Dataset.	required
zonal_speed	str	Name of the zonal speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.	required
meridional_speed	str	Name of the meridional speed in the dataset. See https://en.wikipedia.org/wiki/Zonal_and_meridional_flow.	required
latitude_dimension	str	Name of the latitude dimension in the dataset. Defaults to 'lat'.	'lat'
longitude_dimension	str	Name of the longitude dimension in the dataset. Defaults to 'lon'.	'lon'
level_dimension	str	Name of the level dimension in the dataset. Defaults to 'lev'.	'lev'
level_index	int	The index of the level dimension to display. Defaults to 0.	0
time_index	int	The index of the time dimension to display. Defaults to 0.	0
velocity_scale	float	The scale of the velocity. Defaults to 0.01.	0.01
max_velocity	int	The maximum velocity to display. Defaults to 20.	20
display_options	dict	The display options for the velocity layer. Defaults to {}. See https://bit.ly/3uf8t6w.	{}
name	str	Layer name to use . Defaults to 'Velocity'.	'Velocity'
color_scale	list	List of RGB color values for the velocity vector color scale. Defaults to []. See https://bit.ly/3uf8t6w.	None

Raises:

Type	Description
ImportError	If the xarray package is not installed.
ValueError	If the data is not a NetCDF file or an xarray Dataset.

Source code in leafmap/leafmap.py

def add_velocity(
    self,
    data: str,
    zonal_speed: str,
    meridional_speed: str,
    latitude_dimension: str = "lat",
    longitude_dimension: str = "lon",
    level_dimension: Optional[str] = "lev",
    level_index: int = 0,
    time_index: int = 0,
    velocity_scale: float = 0.01,
    max_velocity: int = 20,
    display_options: Optional[dict] = {},
    name: Optional[str] = "Velocity",
    color_scale: Optional[list] = None,
) -> None:
    """Add a velocity layer to the map.

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

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

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

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

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

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

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

    if color_scale is None:
        color_scale = [
            "rgb(36,104, 180)",
            "rgb(60,157, 194)",
            "rgb(128,205,193)",
            "rgb(151,218,168)",
            "rgb(198,231,181)",
            "rgb(238,247,217)",
            "rgb(255,238,159)",
            "rgb(252,217,125)",
            "rgb(255,182,100)",
            "rgb(252,150,75)",
            "rgb(250,112,52)",
            "rgb(245,64,32)",
            "rgb(237,45,28)",
            "rgb(220,24,32)",
            "rgb(180,0,35)",
        ]

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

add_wayback_layer(date=None, name=None, attribution='Esri', quiet=False, **kwargs)

Adds a Wayback layer to the map.

Parameters:

Name	Type	Description	Default
date	str	The date of the layer. Defaults to None.	None
name	str	The name of the layer. Defaults to None.	None
attribution	str	The attribution of the layer. Defaults to "Esri".	'Esri'
**kwargs		Additional keyword arguments to pass to the add_tile_layer method.	{}

Source code in leafmap/leafmap.py

def add_wayback_layer(
    self,
    date: str = None,
    name: str = None,
    attribution: str = "Esri",
    quiet: bool = False,
    **kwargs,
):
    """Adds a Wayback layer to the map.

    Args:
        date (str, optional): The date of the layer. Defaults to None.
        name (str, optional): The name of the layer. Defaults to None.
        attribution (str, optional): The attribution of the layer. Defaults to "Esri".
        **kwargs: Additional keyword arguments to pass to the add_tile_layer method.
    """
    layers = common.get_wayback_layers()
    if date not in layers.keys():
        new_date = common.find_closest_date(date, layers.keys())
        if not quiet:
            print(f"{date} is not available. Using the closest date: {new_date}")
        date = new_date

    url = common.get_wayback_tile_url(date, layers)
    if name is None:
        name = date
    self.add_tile_layer(url, name=name, attribution=attribution, **kwargs)

add_wayback_layers(left_date='2014-02-20', right_date=None, widget_width='120px', add_layer_control=False, **kwargs)

Adds a time series comparison of Wayback (ArcGIS Wayback) layers to the map.

Parameters:

Name	Type	Description	Default
left_date	str	The initial date for the left layer in "YYYY-MM-DD" format. Defaults to "2014-02-20".	'2014-02-20'
right_date	str	The initial date for the right layer in "YYYY-MM-DD" format. Defaults to None.	None
widget_width	str	The width of the date pickers. Defaults to "120px".	'120px'
add_layer_control	bool	If True, adds a layer control to the map. Defaults to True.	False
**kwargs	Any	Additional keyword arguments to pass to the cog_tile function.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def add_wayback_layers(
    self,
    left_date: str = "2014-02-20",
    right_date: str = None,
    widget_width: str = "120px",
    add_layer_control: bool = False,
    **kwargs: Any,
) -> None:
    """
    Adds a time series comparison of Wayback (ArcGIS Wayback) layers to the map.

    Args:
        left_date (str, optional): The initial date for the left layer in "YYYY-MM-DD" format. Defaults to "2014-02-20".
        right_date (str, optional): The initial date for the right layer in "YYYY-MM-DD" format. Defaults to None.
        widget_width (str, optional): The width of the date pickers. Defaults to "120px".
        add_layer_control (bool, optional): If True, adds a layer control to the map. Defaults to True.
        **kwargs (Any): Additional keyword arguments to pass to the cog_tile function.

    Returns:
        None
    """
    from datetime import datetime

    layers = common.get_wayback_layers()
    if right_date is None:
        right_date = list(layers.keys())[0]

    if left_date not in layers.keys():
        left_date = common.find_closest_date(left_date, layers.keys())

    if right_date is None:
        right_date = list(layers.keys())[0]
    elif right_date not in layers.keys():
        right_date = common.find_closest_date(right_date, layers.keys())

    left_widget = widgets.DatePicker(
        value=datetime.strptime(left_date, "%Y-%m-%d"),
        layout=widgets.Layout(width=widget_width),
    )
    right_widget = widgets.DatePicker(
        value=datetime.strptime(right_date, "%Y-%m-%d"),
        layout=widgets.Layout(width=widget_width),
    )
    left_control = ipyleaflet.WidgetControl(widget=left_widget, position="topleft")
    right_control = ipyleaflet.WidgetControl(
        widget=right_widget, position="topright"
    )
    self.add(left_control)
    self.add(right_control)

    left_tile_url = common.get_wayback_tile_url(left_date, layers)
    right_tile_url = common.get_wayback_tile_url(right_date, layers)
    left_layer = ipyleaflet.TileLayer(
        url=left_tile_url, name=f"{left_date}", attribution="Esri"
    )
    right_layer = ipyleaflet.TileLayer(
        url=right_tile_url, name=f"{right_date}", attribution="Esri"
    )
    split_control = ipyleaflet.SplitMapControl(
        left_layer=left_layer, right_layer=right_layer
    )
    self.add(split_control)
    if add_layer_control:
        self.add_layer_control()

    def change_left_date(change):
        left_date = change.new.strftime("%Y-%m-%d")
        new_date = common.find_closest_date(left_date, layers.keys())
        left_widget.value = datetime.strptime(new_date, "%Y-%m-%d")
        left_layer.url = common.get_wayback_tile_url(new_date, layers, quiet=True)
        left_layer.name = f"{new_date}"

    def change_right_date(change):
        right_date = change.new.strftime("%Y-%m-%d")
        new_date = common.find_closest_date(right_date, layers.keys())
        right_widget.value = datetime.strptime(new_date, "%Y-%m-%d")
        right_layer.url = common.get_wayback_tile_url(new_date, layers, quiet=True)
        right_layer.name = f"{new_date}"

    left_widget.observe(change_left_date, names="value")
    right_widget.observe(change_right_date, names="value")

add_wayback_time_slider(**kwargs)

Add a time slider for Wayback layers.

Source code in leafmap/leafmap.py

def add_wayback_time_slider(self, **kwargs):
    """Add a time slider for Wayback layers."""
    images = common.get_wayback_tile_dict()
    if "tile_args" not in kwargs:
        kwargs["tile_args"] = {"attribution": "Esri"}
    self.add_time_slider(images, **kwargs)

add_widget(content, position='bottomright', add_header=False, opened=True, show_close_button=True, widget_icon='gear', close_button_icon='times', widget_args={}, close_button_args={}, display_widget=None, **kwargs)

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

Parameters:

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

Source code in leafmap/leafmap.py

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

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

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

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

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

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

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

add_wms_layer(url, layers, name=None, attribution='', format='image/png', transparent=True, opacity=1.0, shown=True, **kwargs)

Add a WMS layer to the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

    if name is None:
        name = str(layers)

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

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

add_xy_data(in_csv, x='longitude', y='latitude', label=None, layer_name='Marker cluster')

Adds points from a CSV file containing lat/lon information and display data on the map.

Parameters:

Name	Type	Description	Default
in_csv	str	The file path to the input CSV file.	required
x	str	The name of the column containing longitude coordinates. Defaults to "longitude".	'longitude'
y	str	The name of the column containing latitude coordinates. Defaults to "latitude".	'latitude'
label	str	The name of the column containing label information to used for marker popup. Defaults to None.	None
layer_name	str	The layer name to use. Defaults to "Marker cluster".	'Marker cluster'

Raises:

Type	Description
FileNotFoundError	The specified input csv does not exist.
ValueError	The specified x column does not exist.
ValueError	The specified y column does not exist.
ValueError	The specified label column does not exist.

Source code in leafmap/leafmap.py

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

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

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

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

    col_names = df.columns.values.tolist()

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

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

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

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

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

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

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

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

add_xyz_service(provider, **kwargs)

Add a XYZ tile layer to the map.

Parameters:

Name	Type	Description	Default
provider	str	A tile layer name starts with xyz or qms. For example, xyz.OpenTopoMap,	required

Raises:

Type	Description
ValueError	The provider is not valid. It must start with xyz or qms.

Source code in leafmap/leafmap.py

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

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

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

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

basemap_demo()

A demo for using leafmap basemaps.

Source code in leafmap/leafmap.py

def basemap_demo(self) -> None:
    """A demo for using leafmap basemaps."""
    dropdown = widgets.Dropdown(
        options=list(basemaps.keys()),
        value="Esri.WorldImagery",
        description="Basemaps",
    )

    def on_click(change):
        basemap_name = change["new"]
        old_basemap = self.layers[-1]
        self.substitute_layer(old_basemap, get_basemap(basemap_name))

    dropdown.observe(on_click, "value")
    basemap_control = ipyleaflet.WidgetControl(widget=dropdown, position="topright")
    self.add(basemap_control)

batch_edit_lines(data, style=None, hover_style=None, highlight_style=None, changed_style=None, display_props=None, name='GeoJSON', text_width='250px', zoom_to_layer=True, **kwargs)

Batch editing lines on the map.

Parameters:

Name	Type	Description	Default
data	Union[str, GeoDataFrame, Dict[str, Any]]	The data to be edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.	required
style	Optional[Dict[str, Any]]	The style dictionary for the polygons. Defaults to None.	None
hover_style	Optional[Dict[str, Any]]	The hover style dictionary for the polygons. Defaults to None.	None
name	str	The name of the GeoJSON layer. Defaults to "GeoJSON".	'GeoJSON'
widget_width	str	The width of the widgets. Defaults to "250px".	required
info_mode	str	The mode for displaying information, either "on_click" or "on_hover". Defaults to "on_click".	required
zoom_to_layer	bool	Whether to zoom to the layer bounds. Defaults to True.	True
**kwargs	Any	Additional keyword arguments for the GeoJSON layer.	{}

Raises:

Type	Description
ValueError	If the data is not a GeoDataFrame or a GeoJSON dictionary.

Source code in leafmap/leafmap.py

def batch_edit_lines(
    self,
    data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
    style: Optional[Dict[str, Any]] = None,
    hover_style: Optional[Dict[str, Any]] = None,
    highlight_style: Optional[Dict[str, Any]] = None,
    changed_style: Optional[Dict[str, Any]] = None,
    display_props: Optional[List[str]] = None,
    name: str = "GeoJSON",
    text_width: str = "250px",
    zoom_to_layer: bool = True,
    **kwargs: Any,
) -> None:
    """Batch editing lines on the map.

    Args:
        data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
            edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
        style (Optional[Dict[str, Any]], optional): The style dictionary for
            the polygons. Defaults to None.
        hover_style (Optional[Dict[str, Any]], optional): The hover style
            dictionary for the polygons. Defaults to None.
        name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
        widget_width (str, optional): The width of the widgets. Defaults to "250px".
        info_mode (str, optional): The mode for displaying information,
            either "on_click" or "on_hover". Defaults to "on_click".
        zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
            Defaults to True.
        **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

    Raises:
        ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
    """
    self.batch_edit_polygons(
        data=data,
        style=style,
        hover_style=hover_style,
        highlight_style=highlight_style,
        changed_style=changed_style,
        display_props=display_props,
        name=name,
        text_width=text_width,
        zoom_to_layer=zoom_to_layer,
        **kwargs,
    )

batch_edit_points(data, style=None, hover_style=None, changed_style=None, display_props=None, name='Points', text_width='250px', zoom_to_layer=True, **kwargs)

Batch editing points (CircleMarkers) on the map from GeoJSON data.

Parameters:

Name	Type	Description	Default
data	Union[str, dict]	The GeoJSON data or path to the GeoJSON file.	required
style	Optional[Dict[str, Any]]	Style for the CircleMarkers.	None
hover_style	Optional[Dict[str, Any]]	Style for the CircleMarkers on hover.	None
changed_style	Optional[Dict[str, Any]]	Style for the CircleMarkers when changed.	None
display_props	Optional[List[str]]	List of properties to display in the attribute editor.	None
name	str	Name of the layer group.	'Points'
text_width	str	Width of the text widgets in the attribute editor.	'250px'
zoom_to_layer	bool	Whether to zoom to the layer bounds.	True
**kwargs	Any	Additional keyword arguments for the LayerGroup.	{}

Raises:

Type	Description
ValueError	If the data is not a GeoDataFrame or a GeoJSON dictionary.
ValueError	If the GeoJSON data does not contain only Point geometries.

Source code in leafmap/leafmap.py

def batch_edit_points(
    self,
    data: Union[str, dict],
    style: Optional[Dict[str, Any]] = None,
    hover_style: Optional[Dict[str, Any]] = None,
    changed_style: Optional[Dict[str, Any]] = None,
    display_props: Optional[List[str]] = None,
    name: str = "Points",
    text_width: str = "250px",
    zoom_to_layer: bool = True,
    **kwargs: Any,
) -> None:
    """Batch editing points (CircleMarkers) on the map from GeoJSON data.

    Args:
        data (Union[str, dict]): The GeoJSON data or path to the GeoJSON file.
        style (Optional[Dict[str, Any]]): Style for the CircleMarkers.
        hover_style (Optional[Dict[str, Any]]): Style for the CircleMarkers on hover.
        changed_style (Optional[Dict[str, Any]]): Style for the CircleMarkers when changed.
        display_props (Optional[List[str]]): List of properties to display in the attribute editor.
        name (str): Name of the layer group.
        text_width (str): Width of the text widgets in the attribute editor.
        zoom_to_layer (bool): Whether to zoom to the layer bounds.
        **kwargs (Any): Additional keyword arguments for the LayerGroup.

    Raises:
        ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
        ValueError: If the GeoJSON data does not contain only Point geometries.
    """
    import json

    import geopandas as gpd

    bounds = None

    if isinstance(data, str):
        gdf = gpd.read_file(data)
        if gdf.crs != "EPSG:4326":
            gdf = gdf.to_crs("EPSG:4326")
        bounds = gdf.total_bounds
        temp_geojson = common.temp_file_path("geojson")
        gdf.to_file(temp_geojson, driver="GeoJSON")
        with open(temp_geojson) as f:
            data = json.load(f)
    elif isinstance(data, gpd.GeoDataFrame):
        if data.crs != "EPSG:4326":
            data = data.to_crs("EPSG:4326")
        bounds = data.total_bounds
        temp_geojson = common.temp_file_path("geojson")
        data.to_file(temp_geojson, driver="GeoJSON")
        with open(temp_geojson) as f:
            data = json.load(f)

    if isinstance(data, dict):
        geojson_data = data
        if zoom_to_layer and (bounds is not None):
            bounds = gpd.GeoDataFrame.from_features(data).total_bounds
    else:
        raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

    # Ensure the data contains Point geometries
    if not all(
        feature["geometry"]["type"] == "Point"
        for feature in geojson_data["features"]
    ):
        raise ValueError("The GeoJSON data must contain only Point geometries.")

    highlighted_markers = []
    attribute_widgets = {}

    # Create CircleMarker objects for each point in the GeoJSON data
    markers = []

    if style is None:
        style = {
            "radius": 5,
            "weight": 1,
            "color": "white",
            "fill_color": "#3388ff",
            "fill_opacity": 0.6,
        }

    if hover_style is None:
        hover_style = {"color": "purple", "fill_color": "yellow"}

    if changed_style is None:
        changed_style = {"color": "cyan", "fill_color": "red"}

    for feature in data["features"]:
        coords = feature["geometry"]["coordinates"]
        properties = feature["properties"]

        marker = ipyleaflet.CircleMarker(
            location=(
                coords[1],
                coords[0],
            ),  # GeoJSON coordinates are (longitude, latitude)
            radius=style.get("radius", 5),
            weight=style.get("weight", 1),
            color=style.get("color", "white"),
            fill_color=style.get("fill_color", "#3388ff"),
            fill_opacity=style.get("fill_opacity", 0.6),
        )
        setattr(marker, "properties", properties)
        markers.append(marker)

    # Create a LayerGroup to hold the markers
    layer_group = ipyleaflet.LayerGroup(layers=markers, name=name, **kwargs)

    # Get the keys from the first feature's properties
    first_feature = data["features"][0]["properties"]

    # If display_props is not provided, show all attributes
    if display_props is None:
        display_props = first_feature.keys()

    text_layout = widgets.Layout(width=text_width)

    # Loop through the specified properties in display_props
    for key in display_props:
        if key in first_feature:  # Ensure the property exists
            attribute_widgets[key] = widgets.Text(
                description=f"{key}:", layout=text_layout
            )

    # Update button and clear selection button
    button_width = "80px"
    button_layout = widgets.Layout(width=button_width)
    update_button = widgets.Button(description="Update", layout=button_layout)
    clear_button = widgets.Button(description="Clear", layout=button_layout)
    close_button = widgets.Button(description="Close", layout=button_layout)
    output_widget = widgets.Output()

    # Function to highlight the clicked marker and clear attribute fields
    def highlight_marker(marker, **kwargs):
        nonlocal highlighted_markers

        if marker in highlighted_markers:
            highlighted_markers.remove(marker)
            marker.color = style.get("color", "white")
            marker.fill_color = style.get("fill_color", "#3388ff")

        else:
            highlighted_markers.append(marker)
            marker.color = hover_style.get("color", "purple")
            marker.fill_color = hover_style.get("fill_color", "yellow")

    # Function to clear the selection
    def clear_selection(_):
        for marker in highlighted_markers:
            if marker.color != changed_style.get(
                "color", "cyan"
            ) and marker.fill_color != changed_style.get("fill_color", "red"):
                marker.color = style.get("color", "white")
                marker.fill_color = style.get("fill_color", "#3388ff")
        for key, widget in attribute_widgets.items():
            widget.value = ""
            widget.placeholder = ""
        highlighted_markers.clear()

    def get_geojson_data():
        geojson_data = {"type": "FeatureCollection", "features": []}
        for layer in layer_group.layers:
            feature = {
                "type": "Feature",
                "properties": layer.properties,
                "geometry": {
                    "type": "Point",
                    "coordinates": [layer.location[1], layer.location[0]],
                },
            }

            geojson_data["features"].append(feature)
            self._geojson_data = geojson_data

    # Function to apply changes to highlighted markers
    def update_highlighted_markers(_):
        output_widget.clear_output()

        changed = False
        for index, marker in enumerate(highlighted_markers):
            for key, widget in attribute_widgets.items():
                if widget.value.strip() != "":
                    changed = True
                    if isinstance(marker.properties[key], int):
                        try:
                            marker.properties[key] = int(widget.value)
                        except ValueError as e:
                            if index == 0:
                                with output_widget:
                                    print(f"{key} must be an integer.")
                    elif isinstance(marker.properties[key], float):
                        try:
                            marker.properties[key] = float(widget.value)
                        except ValueError as e:
                            if index == 0:
                                with output_widget:
                                    print(f"{key} must be a float.")
                    else:
                        marker.properties[key] = widget.value

            # Apply changed_style if defined
            if changed:
                marker.color = changed_style.get("color", "cyan")
                marker.fill_color = changed_style.get("fill_color", "red")
            else:
                if index == 0:
                    with output_widget:
                        print("No changes to apply.")

        if changed:
            clear_selection(None)
            for key, widget in attribute_widgets.items():
                widget.value = ""
            get_geojson_data()

    # Function to populate attribute fields on hover
    def populate_hover_attributes(marker, **kwargs):
        for key, widget in attribute_widgets.items():
            widget.value = ""
            widget.placeholder = str(marker.properties.get(key, ""))

    # Register click event to highlight markers
    for marker in markers:
        marker.on_click(lambda m=marker, **kwargs: highlight_marker(m))
        marker.on_mouseover(lambda m=marker, **kwargs: populate_hover_attributes(m))

    # Add the LayerGroup of markers to the map
    self.add_layer(layer_group)

    # Add event listeners to the buttons
    update_button.on_click(update_highlighted_markers)
    clear_button.on_click(clear_selection)

    # Create a VBox to hold the widgets for editing attributes and the buttons
    buttons = widgets.HBox([update_button, clear_button, close_button])
    attribute_editor = widgets.VBox(
        [*attribute_widgets.values(), buttons, output_widget]
    )

    # Embed the attribute editor inside the map using WidgetControl
    widget_control = ipyleaflet.WidgetControl(
        widget=attribute_editor, position="topright"
    )
    self.add(widget_control)

    def close_widget_control(_):
        self.remove(widget_control)

    close_button.on_click(close_widget_control)

    # Optionally zoom to the bounds of the points
    if zoom_to_layer:
        bounds = gpd.GeoDataFrame.from_features(data).total_bounds
        west, south, east, north = bounds
        self.fit_bounds([[south, west], [north, east]])

batch_edit_polygons(data, style=None, hover_style=None, highlight_style=None, changed_style=None, display_props=None, name='GeoJSON', text_width='250px', zoom_to_layer=True, **kwargs)

Batch editing polygons on the map.

Parameters:

Name	Type	Description	Default
data	Union[str, GeoDataFrame, Dict[str, Any]]	The data to be edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.	required
style	Optional[Dict[str, Any]]	The style dictionary for the polygons. Defaults to None.	None
hover_style	Optional[Dict[str, Any]]	The hover style dictionary for the polygons. Defaults to None.	None
name	str	The name of the GeoJSON layer. Defaults to "GeoJSON".	'GeoJSON'
widget_width	str	The width of the widgets. Defaults to "250px".	required
info_mode	str	The mode for displaying information, either "on_click" or "on_hover". Defaults to "on_click".	required
zoom_to_layer	bool	Whether to zoom to the layer bounds. Defaults to True.	True
**kwargs	Any	Additional keyword arguments for the GeoJSON layer.	{}

Raises:

Type	Description
ValueError	If the data is not a GeoDataFrame or a GeoJSON dictionary.

Source code in leafmap/leafmap.py

def batch_edit_polygons(
    self,
    data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
    style: Optional[Dict[str, Any]] = None,
    hover_style: Optional[Dict[str, Any]] = None,
    highlight_style: Optional[Dict[str, Any]] = None,
    changed_style: Optional[Dict[str, Any]] = None,
    display_props: Optional[List[str]] = None,
    name: str = "GeoJSON",
    text_width: str = "250px",
    zoom_to_layer: bool = True,
    **kwargs: Any,
) -> None:
    """Batch editing polygons on the map.

    Args:
        data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
            edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
        style (Optional[Dict[str, Any]], optional): The style dictionary for
            the polygons. Defaults to None.
        hover_style (Optional[Dict[str, Any]], optional): The hover style
            dictionary for the polygons. Defaults to None.
        name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
        widget_width (str, optional): The width of the widgets. Defaults to "250px".
        info_mode (str, optional): The mode for displaying information,
            either "on_click" or "on_hover". Defaults to "on_click".
        zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
            Defaults to True.
        **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

    Raises:
        ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
    """
    import copy
    import json

    import geopandas as gpd
    from ipyleaflet import GeoJSON

    bounds = None
    if isinstance(data, str):
        gdf = gpd.read_file(data)
        if gdf.crs != "EPSG:4326":
            gdf = gdf.to_crs("EPSG:4326")
        bounds = gdf.total_bounds
        temp_geojson = common.temp_file_path("geojson")
        gdf.to_file(temp_geojson, driver="GeoJSON")
        with open(temp_geojson) as f:
            data = json.load(f)
    elif isinstance(data, gpd.GeoDataFrame):
        if data.crs != "EPSG:4326":
            data = data.to_crs("EPSG:4326")
        bounds = data.total_bounds
        temp_geojson = common.temp_file_path("geojson")
        data.to_file(temp_geojson, driver="GeoJSON")
        with open(temp_geojson) as f:
            data = json.load(f)

    if isinstance(data, dict):
        data = data
        if zoom_to_layer and (bounds is not None):
            bounds = gpd.GeoDataFrame.from_features(data).total_bounds
    else:
        raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

    if style is None:
        style = {"color": "#3388ff"}

    if hover_style is None:
        hover_style = {"color": "yellow", "dashArray": "0", "fillOpacity": 0.3}

    if highlight_style is None:
        highlight_style = {
            "color": "#3388ff",
            "fillColor": "yellow",
            "weight": 3,
            "fillOpacity": 0.5,
        }

    if changed_style is None:
        changed_style = {
            "color": "#3388ff",
            "fillColor": "red",
            "weight": 3,
            "fillOpacity": 0.3,
        }

    # List to store the IDs of highlighted features
    highlighted_features = []

    # Create a dictionary to hold attribute widgets
    attribute_widgets = {}

    # Get the keys from the first feature to dynamically create widgets
    first_feature = data["features"][0]["properties"]

    # If display_props is not provided, show all attributes
    if display_props is None:
        display_props = first_feature.keys()

    text_layout = widgets.Layout(width=text_width)
    # Loop through only the specified properties in display_props
    for key in display_props:
        if key in first_feature:  # Ensure the property exists
            attribute_widgets[key] = widgets.Text(
                description=f"{key.capitalize()}:", layout=text_layout
            )

    # Update button and clear selection button
    button_width = "80px"
    button_layout = widgets.Layout(width=button_width)
    update_button = widgets.Button(description="Update", layout=button_layout)
    clear_button = widgets.Button(description="Clear", layout=button_layout)
    close_button = widgets.Button(description="Close", layout=button_layout)
    output_widget = widgets.Output()

    # Function to highlight the clicked feature and clear attribute fields
    def highlight_feature(event, feature, **kwargs):
        nonlocal highlighted_features
        original_data = copy.deepcopy(geojson_layer.data)

        for index, f in enumerate(original_data["features"]):
            if f == feature:
                if index in highlighted_features:
                    highlighted_features.remove(index)
                    original_data["features"][index]["properties"]["style"] = style
                else:
                    highlighted_features.append(index)
                    original_data["features"][index]["properties"][
                        "style"
                    ] = highlight_style

        geojson_layer.data = original_data

    # Function to clear the selection
    def clear_selection(_):
        original_data = copy.deepcopy(geojson_layer.data)

        # Reset the style for all highlighted features
        for index in highlighted_features:
            if (
                original_data["features"][index]["properties"]["style"]
                != changed_style
            ):
                original_data["features"][index]["properties"]["style"] = style

        highlighted_features.clear()
        geojson_layer.data = original_data

    # Function to apply changes to highlighted features
    def update_highlighted_features(_):
        output_widget.clear_output()
        original_data = copy.deepcopy(geojson_layer.data)

        # Update the properties for all highlighted features
        for index in highlighted_features:
            for key, widget in attribute_widgets.items():
                if widget.value.strip() != "":
                    dtype = type(
                        original_data["features"][index]["properties"][key]
                    )
                    if dtype == str:
                        value = str(widget.value)
                    elif dtype == int:
                        try:
                            value = int(widget.value)
                        except ValueError:
                            with output_widget:
                                print(f"Invalid value for {key}")
                                continue
                    elif dtype == float:
                        try:
                            value = float(widget.value)
                        except ValueError:
                            with output_widget:
                                print(f"Invalid value for {key}")
                                continue
                    else:
                        value = widget.value
                    original_data["features"][index]["properties"][key] = value
                    original_data["features"][index]["properties"][
                        "style"
                    ] = changed_style

        geojson_layer.data = original_data
        self._geojson_data = original_data
        clear_selection(None)
        for key, widget in attribute_widgets.items():
            widget.value = ""

    # Function to populate attribute fields on hover
    def populate_hover_attributes(event, feature, **kwargs):
        # Populate the widget fields with the hovered feature's attributes
        for key, widget in attribute_widgets.items():
            if widget.value.strip() == "":
                widget.value = ""
                widget.placeholder = str(feature["properties"].get(key, ""))

    # Create the GeoJSON layer
    geojson_layer = GeoJSON(
        data=data,
        style=style,
        hover_style=hover_style,
        name=name,
    )

    # Add click event to highlight features and clear attribute fields
    geojson_layer.on_click(highlight_feature)

    # Add hover event to populate attribute fields
    geojson_layer.on_hover(populate_hover_attributes)

    # Add the GeoJSON layer to the map
    self.add_layer(geojson_layer)

    # Add event listeners to the buttons
    update_button.on_click(update_highlighted_features)
    clear_button.on_click(clear_selection)

    # Create a VBox to hold the widgets for editing attributes and the buttons
    buttons = widgets.HBox([update_button, clear_button, close_button])
    attribute_editor = widgets.VBox(
        [*attribute_widgets.values(), buttons, output_widget]
    )

    # Embed the attribute editor inside the map using WidgetControl
    widget_control = ipyleaflet.WidgetControl(
        widget=attribute_editor, position="topright"
    )
    self.add(widget_control)

    def close_widget_control(_):
        self.remove(widget_control)

    close_button.on_click(close_widget_control)

    # Add layers to map
    self._geojson_data = geojson_layer.data

    if bounds is not None and zoom_to_layer:
        west, south, east, north = bounds
        self.fit_bounds([[south, east], [north, west]])

clear_drawings()

Clear drawings on the map.

Source code in leafmap/leafmap.py

def clear_drawings(self) -> None:
    """Clear drawings on the map."""
    self.draw_control.clear()
    self.draw_features = []
    self.user_rois = None
    self.user_roi = None

edit_lines(data, style=None, hover_style=None, name='GeoJSON', widget_width='250px', info_mode='on_click', zoom_to_layer=True, **kwargs)

Edit lines on the map.

Parameters:

Name	Type	Description	Default
data	Union[str, GeoDataFrame, Dict[str, Any]]	The data to be edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.	required
style	Optional[Dict[str, Any]]	The style dictionary for the lines. Defaults to None.	None
hover_style	Optional[Dict[str, Any]]	The hover style dictionary for the lines. Defaults to None.	None
name	str	The name of the GeoJSON layer. Defaults to "GeoJSON".	'GeoJSON'
widget_width	str	The width of the widgets. Defaults to "250px".	'250px'
info_mode	str	The mode for displaying information, either "on_click" or "on_hover". Defaults to "on_click".	'on_click'
zoom_to_layer	bool	Whether to zoom to the layer bounds. Defaults to True.	True
**kwargs	Any	Additional keyword arguments for the GeoJSON layer.	{}

Raises:

Type	Description
ValueError	If the data is not a GeoDataFrame or a GeoJSON dictionary.

Source code in leafmap/leafmap.py

def edit_lines(
    self,
    data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
    style: Optional[Dict[str, Any]] = None,
    hover_style: Optional[Dict[str, Any]] = None,
    name: str = "GeoJSON",
    widget_width: str = "250px",
    info_mode: str = "on_click",
    zoom_to_layer: bool = True,
    **kwargs: Any,
) -> None:
    """Edit lines on the map.

    Args:
        data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
            edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
        style (Optional[Dict[str, Any]], optional): The style dictionary for
            the lines. Defaults to None.
        hover_style (Optional[Dict[str, Any]], optional): The hover style
            dictionary for the lines. Defaults to None.
        name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
        widget_width (str, optional): The width of the widgets. Defaults to "250px".
        info_mode (str, optional): The mode for displaying information,
            either "on_click" or "on_hover". Defaults to "on_click".
        zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
            Defaults to True.
        **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

    Raises:
        ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
    """
    self.edit_polygons(
        data=data,
        style=style,
        hover_style=hover_style,
        name=name,
        widget_width=widget_width,
        info_mode=info_mode,
        zoom_to_layer=zoom_to_layer,
        **kwargs,
    )

edit_points(data, display_props=None, widget_width='250px', name='Points', radius=5, color='white', weight=1, fill_color='#3388ff', fill_opacity=0.6, **kwargs)

Edit points on a map by creating interactive circle markers with popups.

Parameters:

Name	Type	Description	Default
data	Union[str, GeoDataFrame, Dict[str, Any]]	The data source, which can be a file path, GeoDataFrame, or GeoJSON dictionary.	required
display_props	Optional[List[str]]	List of properties to display in the popup. Defaults to None.	None
widget_width	str	Width of the widget in the popup. Defaults to "250px".	'250px'
name	str	Name of the layer group. Defaults to "Points".	'Points'
radius	int	Initial radius of the circle markers. Defaults to 5.	5
color	str	Outline color of the circle markers. Defaults to "white".	'white'
weight	int	Outline weight of the circle markers. Defaults to 1.	1
fill_color	str	Fill color of the circle markers. Defaults to "#3388ff".	'#3388ff'
fill_opacity	float	Fill opacity of the circle markers. Defaults to 0.6.	0.6
**kwargs	Any	Additional arguments for the CircleMarker.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def edit_points(
    self,
    data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
    display_props: Optional[List[str]] = None,
    widget_width: str = "250px",
    name: str = "Points",
    radius: int = 5,
    color: str = "white",
    weight: int = 1,
    fill_color: str = "#3388ff",
    fill_opacity: float = 0.6,
    **kwargs: Any,
) -> None:
    """
    Edit points on a map by creating interactive circle markers with popups.

    Args:
        data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data source,
            which can be a file path, GeoDataFrame, or GeoJSON dictionary.
        display_props (Optional[List[str]], optional): List of properties to
            display in the popup. Defaults to None.
        widget_width (str, optional): Width of the widget in the popup.
            Defaults to "250px".
        name (str, optional): Name of the layer group. Defaults to "Points".
        radius (int, optional): Initial radius of the circle markers. Defaults to 5.
        color (str, optional): Outline color of the circle markers. Defaults to "white".
        weight (int, optional): Outline weight of the circle markers. Defaults to 1.
        fill_color (str, optional): Fill color of the circle markers. Defaults to "#3388ff".
        fill_opacity (float, optional): Fill opacity of the circle markers. Defaults to 0.6.
        **kwargs (Any): Additional arguments for the CircleMarker.

    Returns:
        None
    """

    import geopandas as gpd
    from ipyleaflet import CircleMarker, Popup

    if isinstance(data, gpd.GeoDataFrame):
        if data.crs != "EPSG:4326":
            data = data.to_crs("EPSG:4326")
        geojson_data = data.__geo_interface__
    elif isinstance(data, str):
        data = gpd.read_file(data)
        if data.crs != "EPSG:4326":
            data = data.to_crs("EPSG:4326")
        geojson_data = data.__geo_interface__
    elif isinstance(data, dict):
        geojson_data = data
    else:
        raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

    self._geojson_data = geojson_data

    def create_popup_widget(
        circle_marker, properties, original_properties, display_properties=None
    ):
        """Create a popup widget to change circle properties and edit feature attributes."""
        # Widgets for circle properties
        radius_slider = widgets.IntSlider(
            value=circle_marker.radius,
            min=1,
            max=50,
            description="Radius:",
            continuous_update=False,
            layout=widgets.Layout(width=widget_width),
        )

        color_picker = widgets.ColorPicker(
            value=circle_marker.color,
            description="Color:",
            continuous_update=False,
            layout=widgets.Layout(width=widget_width),
        )

        fill_color_picker = widgets.ColorPicker(
            value=circle_marker.fill_color,
            description="Fill color:",
            continuous_update=False,
            layout=widgets.Layout(width=widget_width),
        )

        # Widgets for feature properties
        property_widgets = {}
        display_properties = display_properties or properties.keys()
        for key in display_properties:
            value = properties.get(key, "")
            if isinstance(value, str):
                widget = widgets.Text(
                    value=value,
                    description=f"{key}:",
                    continuous_update=False,
                    layout=widgets.Layout(width=widget_width),
                )
            elif isinstance(value, (int, float)):
                widget = widgets.FloatText(
                    value=value,
                    description=f"{key}:",
                    continuous_update=False,
                    layout=widgets.Layout(width=widget_width),
                )
            else:
                widget = widgets.Label(
                    value=f"{key}: {value}",
                    layout=widgets.Layout(width=widget_width),
                )

            property_widgets[key] = widget

        def update_circle(change):
            """Update circle properties based on widget values."""
            circle_marker.radius = radius_slider.value
            circle_marker.color = color_picker.value
            circle_marker.fill_color = fill_color_picker.value
            for key, widget in property_widgets.items():
                properties[key] = widget.value

        def reset_circle(change):
            """Reset circle properties to their original values."""
            circle_marker.radius = original_properties["radius"]
            circle_marker.color = original_properties["color"]
            circle_marker.fill_color = original_properties["fill_color"]
            radius_slider.value = original_properties["radius"]
            color_picker.value = original_properties["color"]
            fill_color_picker.value = original_properties["fill_color"]
            for key, widget in property_widgets.items():
                widget.value = original_properties["properties"].get(key, "")

        # Link widgets to update the circle marker properties and point attributes
        radius_slider.observe(update_circle, "value")
        color_picker.observe(update_circle, "value")
        fill_color_picker.observe(update_circle, "value")
        for widget in property_widgets.values():
            widget.observe(update_circle, "value")

        # Reset button
        reset_button = widgets.Button(
            description="Reset", layout=widgets.Layout(width=widget_width)
        )
        reset_button.on_click(reset_circle)

        # Arrange widgets in a vertical box with increased width
        vbox = widgets.VBox(
            [radius_slider, color_picker, fill_color_picker]
            + list(property_widgets.values())
            + [reset_button],
            layout=widgets.Layout(
                width="310px"
            ),  # Set the width of the popup widget
        )
        return vbox

    def create_on_click_handler(circle_marker, properties, display_properties=None):
        """Create an on_click handler with the circle_marker bound."""
        # Save the original properties for reset
        original_properties = {
            "radius": circle_marker.radius,
            "color": circle_marker.color,
            "fill_color": circle_marker.fill_color,
            "properties": properties.copy(),
        }

        def on_click(**kwargs):
            if kwargs.get("type") == "click":
                # Create a popup widget with controls
                popup_widget = create_popup_widget(
                    circle_marker,
                    properties,
                    original_properties,
                    display_properties,
                )
                popup = Popup(
                    location=circle_marker.location,
                    child=popup_widget,
                    close_button=True,
                    auto_close=False,
                    close_on_escape_key=True,
                    min_width=int(widget_width[:-2]) + 10,
                )
                self.add_layer(popup)
                popup.open = True

        return on_click

    layers = []

    # Iterate over each feature in the GeoJSON data and create a CircleMarker
    for feature in geojson_data["features"]:
        coordinates = feature["geometry"]["coordinates"]
        properties = feature["properties"]

        circle_marker = CircleMarker(
            location=(coordinates[1], coordinates[0]),  # (lat, lon)
            radius=radius,  # Initial radius of the circle
            color=color,  # Outline color
            weight=weight,  # Outline
            fill_color=fill_color,  # Fill color
            fill_opacity=fill_opacity,
            **kwargs,
        )

        # Create and bind the on_click handler for each circle_marker
        circle_marker.on_click(
            create_on_click_handler(circle_marker, properties, display_props)
        )

        # Add the circle marker to the map
        layers.append(circle_marker)

    group = ipyleaflet.LayerGroup(layers=tuple(layers), name=name)
    self.add(group)

edit_polygons(data, style=None, hover_style=None, name='GeoJSON', widget_width='250px', info_mode='on_click', zoom_to_layer=True, **kwargs)

Edit polygons on the map.

Parameters:

Name	Type	Description	Default
data	Union[str, GeoDataFrame, Dict[str, Any]]	The data to be edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.	required
style	Optional[Dict[str, Any]]	The style dictionary for the polygons. Defaults to None.	None
hover_style	Optional[Dict[str, Any]]	The hover style dictionary for the polygons. Defaults to None.	None
name	str	The name of the GeoJSON layer. Defaults to "GeoJSON".	'GeoJSON'
widget_width	str	The width of the widgets. Defaults to "250px".	'250px'
info_mode	str	The mode for displaying information, either "on_click" or "on_hover". Defaults to "on_click".	'on_click'
zoom_to_layer	bool	Whether to zoom to the layer bounds. Defaults to True.	True
**kwargs	Any	Additional keyword arguments for the GeoJSON layer.	{}

Raises:

Type	Description
ValueError	If the data is not a GeoDataFrame or a GeoJSON dictionary.

Source code in leafmap/leafmap.py

def edit_polygons(
    self,
    data: Union[str, "gpd.GeoDataFrame", Dict[str, Any]],
    style: Optional[Dict[str, Any]] = None,
    hover_style: Optional[Dict[str, Any]] = None,
    name: str = "GeoJSON",
    widget_width: str = "250px",
    info_mode: str = "on_click",
    zoom_to_layer: bool = True,
    **kwargs: Any,
) -> None:
    """Edit polygons on the map.

    Args:
        data (Union[str, gpd.GeoDataFrame, Dict[str, Any]]): The data to be
            edited, either as a file path, GeoDataFrame, or GeoJSON dictionary.
        style (Optional[Dict[str, Any]], optional): The style dictionary for
            the polygons. Defaults to None.
        hover_style (Optional[Dict[str, Any]], optional): The hover style
            dictionary for the polygons. Defaults to None.
        name (str, optional): The name of the GeoJSON layer. Defaults to "GeoJSON".
        widget_width (str, optional): The width of the widgets. Defaults to "250px".
        info_mode (str, optional): The mode for displaying information,
            either "on_click" or "on_hover". Defaults to "on_click".
        zoom_to_layer (bool, optional): Whether to zoom to the layer bounds.
            Defaults to True.
        **kwargs (Any): Additional keyword arguments for the GeoJSON layer.

    Raises:
        ValueError: If the data is not a GeoDataFrame or a GeoJSON dictionary.
    """
    import copy
    import json

    import geopandas as gpd
    from ipyleaflet import GeoJSON, Popup
    from shapely.geometry import shape

    bounds = None

    if isinstance(data, str):
        gdf = gpd.read_file(data)
        if gdf.crs != "EPSG:4326":
            gdf = gdf.to_crs("EPSG:4326")
        bounds = gdf.total_bounds
        temp_geojson = common.temp_file_path("geojson")
        gdf.to_file(temp_geojson, driver="GeoJSON")
        with open(temp_geojson) as f:
            data = json.load(f)
    elif isinstance(data, gpd.GeoDataFrame):
        if data.crs != "EPSG:4326":
            data = data.to_crs("EPSG:4326")
        bounds = data.total_bounds
        temp_geojson = common.temp_file_path("geojson")
        data.to_file(temp_geojson, driver="GeoJSON")
        with open(temp_geojson) as f:
            data = json.load(f)

    if isinstance(data, dict):
        geojson_data = data
        if zoom_to_layer and (bounds is not None):
            bounds = gpd.GeoDataFrame.from_features(data).total_bounds
    else:
        raise ValueError("The data must be a GeoDataFrame or a GeoJSON dictionary.")

    layout = widgets.Layout(width=widget_width)

    if style is None:
        style = {"color": "#3388ff"}
    if hover_style is None:
        hover_style = {"color": "yellow", "weight": 5}

    def calculate_centroid(polygon_coordinates, geom_type):
        polygon = shape({"type": geom_type, "coordinates": polygon_coordinates})
        centroid = polygon.centroid
        return centroid.y, centroid.x  # Return as (lat, lon)

    def create_property_widgets(properties):
        """Dynamically create widgets for each property."""
        widgets_list = []
        for key, value in properties.items():
            if key == "style":
                continue
            if isinstance(value, (int, float)):
                widget = widgets.FloatText(
                    value=value, description=f"{key}:", layout=layout
                )
            else:
                widget = widgets.Text(
                    value=str(value), description=f"{key}:", layout=layout
                )
            widget._property_key = (
                key  # Store the key in the widget for easy access later
            )
            widgets_list.append(widget)
        return widgets_list

    def on_click(event, feature, **kwargs):
        # Dynamically create input widgets for each property
        property_widgets = create_property_widgets(feature["properties"])
        save_button = widgets.Button(description="Save", layout=layout)
        geom_type = feature["geometry"]["type"]
        centroid = calculate_centroid(feature["geometry"]["coordinates"], geom_type)

        # Create and open the popup
        popup_content = widgets.VBox(property_widgets + [save_button])

        popup = Popup(
            location=centroid,
            child=popup_content,
            close_button=True,
            auto_close=True,
            close_on_escape_key=True,
            min_width=int(widget_width[:-2]) + 5,
        )

        self.add_layer(popup)

        def save_changes(_):

            original_data = copy.deepcopy(geojson_layer.data)
            original_feature = copy.deepcopy(feature)
            # Update the properties with the new values
            for widget in property_widgets:
                feature["properties"][widget._property_key] = widget.value

            for i, f in enumerate(original_data["features"]):
                if f == original_feature:
                    original_data["features"][i] = feature
                    break

            # Update the GeoJSON layer to reflect the changes

            geojson_layer.data = original_data
            self._geojson_data = original_data

            self.remove_layer(popup)  # Close the popup by removing it from the map

        save_button.on_click(save_changes)

    # Add GeoJSON layer to the map
    geojson_layer = GeoJSON(
        data=geojson_data, style=style, hover_style=hover_style, name=name, **kwargs
    )

    # Attach event to the GeoJSON layer
    if info_mode == "on_click":
        geojson_layer.on_click(on_click)
    elif info_mode == "on_hover":
        geojson_layer.on_hover(on_click)

    # Add layers to map
    self.add_layer(geojson_layer)
    self._geojson_data = geojson_layer.data

    if bounds is not None and zoom_to_layer:
        west, south, east, north = bounds
        self.fit_bounds([[south, east], [north, west]])

edit_vector(data, **kwargs)

Edit a vector layer.

Parameters:

Name	Type	Description	Default
data	dict | str	The data to edit. It can be a GeoJSON dictionary or a file path.	required

Source code in leafmap/leafmap.py

def edit_vector(self, data: Union[dict, str], **kwargs) -> None:
    """Edit a vector layer.

    Args:
        data (dict | str): The data to edit. It can be a GeoJSON dictionary or a file path.
    """
    if isinstance(data, str):
        common.check_package("geopandas", "https://geopandas.org")
        import geopandas as gpd

        gdf = gpd.read_file(data, **kwargs)
        geojson = common.gdf_to_geojson(gdf, epsg=4326, tuple_to_list=True)
    elif isinstance(data, dict):
        geojson = data
    else:
        raise ValueError(
            "The data must be a GeoJSON dictionary or a file path to a vector dataset."
        )
    self.draw_control.data = self.draw_control.data + (geojson["features"])
    self.draw_features = self.draw_features + (geojson["features"])

find_layer(name)

Finds layer by name

Parameters:

Name	Type	Description	Default
name	str	Name of the layer to find.	required

Returns:

Name	Type	Description
object		ipyleaflet layer object.

Source code in leafmap/leafmap.py

def find_layer(self, name):
    """Finds layer by name

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

    Returns:
        object: ipyleaflet layer object.
    """
    layers = self.layers

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

find_layer_index(name)

Finds layer index by name

Parameters:

Name	Type	Description	Default
name	str	Name of the layer to find.	required

Returns:

Name	Type	Description
int	int	Index of the layer with the specified name

Source code in leafmap/leafmap.py

def find_layer_index(self, name) -> int:
    """Finds layer index by name

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

    Returns:
        int: Index of the layer with the specified name
    """
    layers = self.layers

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

    return -1

get_bbox()

Get the bounds of the map as a list of [(]minx, miny, maxx, maxy].

Returns:

Name	Type	Description
list	list	The bounds of the map as a list of [(]minx, miny, maxx, maxy].

Source code in leafmap/leafmap.py

def get_bbox(self) -> list:
    """Get the bounds of the map as a list of [(]minx, miny, maxx, maxy].

    Returns:
        list: The bounds of the map as a list of [(]minx, miny, maxx, maxy].
    """
    bounds = self.bounds
    bbox = [bounds[0][1], bounds[0][0], bounds[1][1], bounds[1][0]]
    return bbox

get_draw_props(n=None, return_df=False)

Get the properties of the draw features.

Parameters:

Name	Type	Description	Default
n	int	The maximum number of attributes to return. Defaults to None.	None
return_df	bool	If True, return a pandas dataframe. Defaults to False.	False

Returns:

Type	Description
DataFrame	pd.DataFrame: A pandas dataframe containing the properties of the draw features.

Source code in leafmap/leafmap.py

def get_draw_props(
    self, n: Optional[int] = None, return_df: bool = False
) -> pd.DataFrame:
    """Get the properties of the draw features.

    Args:
        n (int, optional): The maximum number of attributes to return. Defaults to None.
        return_df (bool, optional): If True, return a pandas dataframe. Defaults to False.

    Returns:
        pd.DataFrame: A pandas dataframe containing the properties of the draw features.
    """

    import pandas as pd

    props = self.edit_props[:]

    for feature in self.draw_features:
        for prop in feature["properties"]:
            if prop not in self.edit_props:
                self.edit_props.append(prop)
                props.append(prop)

    if return_df:
        if isinstance(n, int) and n > len(props):
            props = props + [""] * (n - len(props))

        df = pd.DataFrame({"Key": props, "Value": [""] * len(props)})
        df.index += 1
        return df
    else:
        return props

get_layer_names()

Gets layer names as a list.

Returns:

Name	Type	Description
list	list	A list of layer names.

Source code in leafmap/leafmap.py

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

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

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

    return layer_names

get_pc_collections()

Get the list of Microsoft Planetary Computer collections.

Source code in leafmap/leafmap.py

def get_pc_collections(self) -> None:
    """Get the list of Microsoft Planetary Computer collections."""
    if not hasattr(self, "pc_collections"):
        setattr(self, "pc_collections", pc.get_pc_collections())

get_scale()

Returns the approximate pixel scale of the current map view, in meters.

Returns:

Name	Type	Description
float	float	Map resolution in meters.

Source code in leafmap/leafmap.py

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

    Returns:
        float: Map resolution in meters.
    """
    import math

    zoom_level = self.zoom
    # Reference: https://blogs.bing.com/maps/2006/02/25/map-control-zoom-levels-gt-resolution
    resolution = 156543.04 * math.cos(0) / math.pow(2, zoom_level)
    return resolution

image_overlay(url, bounds, name)

Overlays an image from the Internet or locally on the map.

Parameters:

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

Source code in leafmap/leafmap.py

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

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

    from PIL import Image, ImageSequence

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

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

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

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

layer_opacity(name, value=1.0)

Changes layer opacity.

Parameters:

Name	Type	Description	Default
name	str	The name of the layer to change opacity.	required
value	float	The opacity value to set. Defaults to 1.0.	1.0

Source code in leafmap/leafmap.py

def layer_opacity(self, name, value=1.0) -> None:
    """Changes layer opacity.

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

marker_cluster(event='click', add_marker=True)

Captures user inputs and add markers to the map.

Parameters:

Name	Type	Description	Default
event	str	[description]. Defaults to 'click'.	'click'
add_marker	bool	If True, add markers to the map. Defaults to True.	True

Returns:

Name	Type	Description
object		a marker cluster.

Source code in leafmap/leafmap.py

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

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

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

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

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

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

oam_search(bbox=None, start_date=None, end_date=None, limit=100, info_mode='on_click', layer_args={}, add_image=True, **kwargs)

Search OpenAerialMap for images within a bounding box and time range.

Parameters:

Name	Type	Description	Default
bbox	list | str	The bounding box [xmin, ymin, xmax, ymax] to search within. Defaults to None.	None
start_date	str	The start date to search within, such as "2015-04-20T00:00:00.000Z". Defaults to None.	None
end_date	str	The end date to search within, such as "2015-04-21T00:00:00.000Z". Defaults to None.	None
limit	int	The maximum number of results to return. Defaults to 100.	100
info_mode	str	The mode to use for the info popup. Can be 'on_hover' or 'on_click'. Defaults to 'on_click'.	'on_click'
layer_args	dict	The layer arguments for add_gdf() function. Defaults to {}.	{}
add_image	bool	Whether to add the first 10 images to the map. Defaults to True.	True
**kwargs		Additional keyword arguments to pass to the API. See https://hotosm.github.io/oam-api/	{}

Source code in leafmap/leafmap.py

def oam_search(
    self,
    bbox: Optional[Union[list, str]] = None,
    start_date: str = None,
    end_date: str = None,
    limit: int = 100,
    info_mode: str = "on_click",
    layer_args: Optional[dict] = {},
    add_image: Optional[bool] = True,
    **kwargs,
) -> None:
    """Search OpenAerialMap for images within a bounding box and time range.

    Args:
        bbox (list | str, optional): The bounding box [xmin, ymin, xmax, ymax] to search within. Defaults to None.
        start_date (str, optional): The start date to search within, such as "2015-04-20T00:00:00.000Z". Defaults to None.
        end_date (str, optional): The end date to search within, such as "2015-04-21T00:00:00.000Z". Defaults to None.
        limit (int, optional): The maximum number of results to return. Defaults to 100.
        info_mode (str, optional): The mode to use for the info popup. Can be 'on_hover' or 'on_click'. Defaults to 'on_click'.
        layer_args (dict, optional): The layer arguments for add_gdf() function. Defaults to {}.
        add_image (bool, optional): Whether to add the first 10 images to the map. Defaults to True.
        **kwargs: Additional keyword arguments to pass to the API. See https://hotosm.github.io/oam-api/
    """

    bounds = self.bounds
    if bbox is None:
        if self.user_roi is not None:
            bbox = self.user_roi_bounds()
        else:
            bbox = [bounds[0][1], bounds[0][0], bounds[1][1], bounds[1][0]]

    if self.zoom <= 4:
        print("Zoom in to search for images")
        return None

    gdf = common.oam_search(
        bbox=bbox, start_date=start_date, end_date=end_date, limit=limit, **kwargs
    )

    if "layer_name" not in layer_args:
        layer_args["layer_name"] = "Footprints"

    if "style" not in layer_args:
        layer_args["style"] = {
            # "stroke": True,
            "color": "#3388ff",
            "weight": 2,
            "opacity": 1,
            # "fill": True,
            # "fillColor": "#ffffff",
            "fillOpacity": 0,
            # "dashArray": "9"
            # "clickable": True,
        }

    if "hover_style" not in layer_args:
        layer_args["hover_style"] = {"weight": layer_args["style"]["weight"] + 2}

    if gdf is not None:
        setattr(self, "oam_gdf", gdf)
        self.add_gdf(gdf, info_mode=info_mode, **layer_args)

        if add_image:
            ids = gdf["_id"].tolist()
            images = gdf["tms"].tolist()

            if len(images) > 5:
                print(f"Found {len(images)} images. \nShowing the first 5.")

            for index, image in enumerate(images):
                if index == 5:
                    break
                self.add_tile_layer(
                    url=image, name=ids[index], attribution="OpenAerialMap"
                )
    else:
        print("No images found.")

remove(widget)

Removes a widget to the map.

Source code in leafmap/leafmap.py

def remove(self, widget: Any) -> None:
    """Removes a widget to the map."""

    basic_controls: Dict[str, ipyleaflet.Control] = {
        "layer_editor": map_widgets.LayerEditor,
    }
    if widget_type := basic_controls.get(widget, None):
        if control := self._find_widget_of_type(widget_type, return_control=True):
            self.remove(control)
            control.close()
        return

    super().remove(widget)
    if isinstance(widget, widgets.Widget):
        widget.close()

remove_labels()

Removes all labels from the map.

Source code in leafmap/leafmap.py

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

save_draw_features(out_file, crs='EPSG:4326', **kwargs)

Save the draw features to a file.

Parameters:

Name	Type	Description	Default
out_file	str	The output file path.	required
crs	str	The CRS of the output GeoJSON. Defaults to "EPSG:4326".	'EPSG:4326'

Source code in leafmap/leafmap.py

def save_draw_features(
    self, out_file: str, crs: Optional[str] = "EPSG:4326", **kwargs
) -> None:
    """Save the draw features to a file.

    Args:
        out_file (str): The output file path.
        crs (str, optional): The CRS of the output GeoJSON. Defaults to "EPSG:4326".
    """

    if self.user_rois is not None:
        import geopandas as gpd

        out_file = common.check_file_path(out_file)

        self.update_draw_features()
        geojson = {
            "type": "FeatureCollection",
            "features": self.draw_features,
        }

        gdf = gpd.GeoDataFrame.from_features(geojson, crs="EPSG:4326")
        if crs != "EPSG:4326":
            gdf = gdf.to_crs(crs)
        gdf.to_file(out_file, **kwargs)
    else:
        print("No draw features to save.")

save_edits(filename, drop_style=True, crs='EPSG:4326', **kwargs)

Save the edited GeoJSON data to a file.

Parameters:

Name	Type	Description	Default
filename	str	The name of the file to save the edited GeoJSON data.	required
drop_style	bool	Whether to drop the style properties from the GeoJSON data. Defaults to True.	True
crs	str	The CRS of the GeoJSON data. Defaults to "EPSG:4326".	'EPSG:4326'
**kwargs	Any	Additional arguments passed to the GeoDataFrame to_file method.	{}

Returns:

Type	Description
None	None

Source code in leafmap/leafmap.py

def save_edits(
    self, filename: str, drop_style: bool = True, crs="EPSG:4326", **kwargs: Any
) -> None:
    """
    Save the edited GeoJSON data to a file.

    Args:
        filename (str): The name of the file to save the edited GeoJSON data.
        drop_style (bool, optional): Whether to drop the style properties
            from the GeoJSON data. Defaults to True.
        crs (str, optional): The CRS of the GeoJSON data. Defaults to "EPSG:4326".
        **kwargs (Any): Additional arguments passed to the GeoDataFrame `to_file` method.

    Returns:
        None
    """
    import geopandas as gpd

    if not hasattr(self, "_geojson_data"):
        print("No GeoJSON data to save.")
        return

    gdf = gpd.GeoDataFrame.from_features(self._geojson_data)
    if drop_style and "style" in gdf.columns:
        gdf = gdf.drop(columns=["style"])
        gdf.crs = "EPSG:4326"

    if crs != "EPSG:4326":
        gdf = gdf.to_crs(crs)
    gdf.to_file(filename, **kwargs)

set_catalog_source(source)

Set the catalog source.

Parameters:

Name	Type	Description	Default
catalog_source	str	The catalog source. Defaults to "landsat".	required

Source code in leafmap/leafmap.py

def set_catalog_source(self, source: Optional[str]) -> None:
    """Set the catalog source.

    Args:
        catalog_source (str, optional): The catalog source. Defaults to "landsat".
    """
    if not isinstance(source, dict):
        raise TypeError(
            "The source must be a dictionary in the format of {label: url, label2:url2}, \
            such as {'Element84': 'https://earth-search.aws.element84.com/v1'}"
        )
    if not hasattr(self, "_STAC_CATALOGS"):
        self.catalog_source = {}

    self._STAC_CATALOGS = source

set_center(lon, lat, zoom=None)

Centers the map view at a given coordinates with the given zoom level.

Parameters:

Name	Type	Description	Default
lon	float	The longitude of the center, in degrees.	required
lat	float	The latitude of the center, in degrees.	required
zoom	int	The zoom level, from 1 to 24. Defaults to None.	None

Source code in leafmap/leafmap.py

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

    Args:
        lon (float): The longitude of the center, in degrees.
        lat (float): The latitude of the center, in degrees.
        zoom (int, optional): The zoom level, from 1 to 24. Defaults to None.
    """
    self.center = (lat, lon)
    if zoom is not None:
        self.zoom = zoom

split_map(left_layer='TERRAIN', right_layer='OpenTopoMap', left_args={}, right_args={}, left_array_args={}, right_array_args={}, zoom_control=True, fullscreen_control=True, layer_control=True, add_close_button=False, left_label=None, right_label=None, left_position='bottomleft', right_position='bottomright', widget_layout=None, draggable=True)

Adds split 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. Defaults to 'TERRAIN'.	'TERRAIN'
right_layer	str	The right tile layer. Can be a local file path, HTTP URL, or a basemap name. Defaults to 'OpenTopoMap'.	'OpenTopoMap'
left_args	dict	The arguments for the left tile layer. Defaults to {}.	{}
right_args	dict	The arguments for the right tile layer. Defaults to {}.	{}
left_array_args	dict	The arguments for array_to_image for the left layer. Defaults to {}.	{}
right_array_args	dict	The arguments for array_to_image for the right layer. Defaults to {}.	{}
zoom_control	bool	Whether to add zoom control. Defaults to True.	True
fullscreen_control	bool	Whether to add fullscreen control. Defaults to True.	True
layer_control	bool	Whether to add layer control. Defaults to True.	True
add_close_button	bool	Whether to add a close button. Defaults to False.	False
left_label	str	The label for the left layer. Defaults to None.	None
right_label	str	The label for the right layer. Defaults to None.	None
left_position	str	The position for the left label. Defaults to "bottomleft".	'bottomleft'
right_position	str	The position for the right label. Defaults to "bottomright".	'bottomright'
widget_layout	dict	The layout for the widget. Defaults to None.	None
draggable	bool	Whether the split map is draggable. Defaults to True.	True

Source code in leafmap/leafmap.py

def split_map(
    self,
    left_layer: Optional[str] = "TERRAIN",
    right_layer: Optional[str] = "OpenTopoMap",
    left_args: Optional[dict] = {},
    right_args: Optional[dict] = {},
    left_array_args: Optional[dict] = {},
    right_array_args: Optional[dict] = {},
    zoom_control: Optional[bool] = True,
    fullscreen_control: Optional[bool] = True,
    layer_control: Optional[bool] = True,
    add_close_button: Optional[bool] = False,
    left_label: Optional[str] = None,
    right_label: Optional[str] = None,
    left_position: Optional[str] = "bottomleft",
    right_position: Optional[str] = "bottomright",
    widget_layout: Optional[dict] = None,
    draggable: Optional[bool] = True,
) -> None:
    """Adds split map.

    Args:
        left_layer (str, optional): The left tile layer. Can be a local file path, HTTP URL, or a basemap name. Defaults to 'TERRAIN'.
        right_layer (str, optional): The right tile layer. Can be a local file path, HTTP URL, or a basemap name. Defaults to 'OpenTopoMap'.
        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_array_args (dict, optional): The arguments for array_to_image for the left layer. Defaults to {}.
        right_array_args (dict, optional): The arguments for array_to_image for the right layer. Defaults to {}.
        zoom_control (bool, optional): Whether to add zoom control. Defaults to True.
        fullscreen_control (bool, optional): Whether to add fullscreen control. Defaults to True.
        layer_control (bool, optional): Whether to add layer control. Defaults to True.
        add_close_button (bool, optional): Whether to add a close button. Defaults to False.
        left_label (str, optional): The label for the left layer. Defaults to None.
        right_label (str, optional): The label for the right layer. Defaults to None.
        left_position (str, optional): The position for the left label. Defaults to "bottomleft".
        right_position (str, optional): The position for the right label. Defaults to "bottomright".
        widget_layout (dict, optional): The layout for the widget. Defaults to None.
        draggable (bool, optional): Whether the split map is draggable. Defaults to True.
    """
    import geopandas as gpd

    if os.environ.get("USE_MKDOCS") is not None:
        return

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

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

    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:
        controls = self.controls
        layers = self.layers
        self.clear()

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

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

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

        if isinstance(left_layer, str):
            if left_layer in basemaps.keys():
                left_layer = get_basemap(left_layer)
            elif left_layer.startswith("http") and left_layer.endswith(".tif"):
                url = common.cog_tile(left_layer, **left_args)
                bbox = common.cog_bounds(left_layer)
                if bbox is not None:
                    bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                left_layer = ipyleaflet.TileLayer(
                    url=url,
                    name=left_name,
                    attribution=" ",
                    **left_args,
                )
            elif left_layer.startswith("http") and left_layer.endswith(".json"):
                left_tile_url = common.stac_tile(left_layer, **left_args)
                bbox = common.stac_bounds(left_layer)
                if bbox is not None:
                    bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                left_layer = ipyleaflet.TileLayer(
                    url=left_tile_url,
                    name=left_name,
                    attribution=" ",
                    **left_args,
                )
            elif left_layer.startswith("http") and left_layer.endswith(".geojson"):
                if "max_zoom" in left_args:
                    del left_args["max_zoom"]
                if "max_native_zoom" in left_args:
                    del left_args["max_native_zoom"]
                left_layer = geojson_layer(left_layer, **left_args)
            elif os.path.exists(left_layer):
                if left_layer.endswith(".geojson"):
                    if "max_zoom" in left_args:
                        del left_args["max_zoom"]
                    if "max_native_zoom" in left_args:
                        del left_args["max_native_zoom"]
                    left_layer = geojson_layer(left_layer, **left_args)
                else:
                    left_layer, left_client = common.get_local_tile_layer(
                        left_layer,
                        tile_format="ipyleaflet",
                        return_client=True,
                        **left_args,
                    )
                    bounds = common.image_bounds(left_client)
            else:
                left_layer = ipyleaflet.TileLayer(
                    url=left_layer,
                    name=left_name,
                    attribution=" ",
                    **left_args,
                )
        elif isinstance(left_layer, ipyleaflet.TileLayer) or isinstance(
            left_layer, ipyleaflet.GeoJSON
        ):
            pass
        elif common.is_array(left_layer):
            left_layer = common.array_to_image(left_layer, **left_array_args)
            left_layer, _ = common.get_local_tile_layer(
                left_layer,
                return_client=True,
                **left_args,
            )
        elif isinstance(left_layer, gpd.GeoDataFrame):
            left_layer = left_layer.to_crs("EPSG:4326").__geo_interface__
            if "max_zoom" in left_args:
                del left_args["max_zoom"]
            if "max_native_zoom" in left_args:
                del left_args["max_native_zoom"]
            left_layer = geojson_layer(left_layer, **left_args)
        else:
            raise ValueError(
                f"left_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
            )

        if isinstance(right_layer, str):
            if right_layer in basemaps.keys():
                right_layer = get_basemap(right_layer)
            elif right_layer.startswith("http") and right_layer.endswith(".tif"):
                url = common.cog_tile(
                    right_layer,
                    **right_args,
                )
                bbox = common.cog_bounds(right_layer)
                if bbox is not None:
                    bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                right_layer = ipyleaflet.TileLayer(
                    url=url,
                    name=right_name,
                    attribution=" ",
                    **right_args,
                )

            elif right_layer.startswith("http") and right_layer.endswith(".json"):
                right_tile_url = common.stac_tile(right_layer, **left_args)
                bbox = common.stac_bounds(right_layer)
                if bbox is not None:
                    bounds = [(bbox[1], bbox[0]), (bbox[3], bbox[2])]
                right_layer = ipyleaflet.TileLayer(
                    url=right_tile_url,
                    name=right_name,
                    attribution=" ",
                    **right_args,
                )
            elif right_layer.startswith("http") and right_layer.endswith(
                ".geojson"
            ):
                if "max_zoom" in right_args:
                    del right_args["max_zoom"]
                if "max_native_zoom" in right_args:
                    del right_args["max_native_zoom"]
                right_layer = geojson_layer(right_layer, **right_args)
            elif os.path.exists(right_layer):
                if "max_zoom" in right_args:
                    del right_args["max_zoom"]
                if "max_native_zoom" in right_args:
                    del right_args["max_native_zoom"]
                if right_layer.endswith(".geojson"):
                    right_layer = geojson_layer(right_layer, **right_args)
                else:
                    right_layer, right_client = common.get_local_tile_layer(
                        right_layer,
                        tile_format="ipyleaflet",
                        return_client=True,
                        **right_args,
                    )
                    bounds = common.image_bounds(right_client)
            else:
                right_layer = ipyleaflet.TileLayer(
                    url=right_layer,
                    name=right_name,
                    attribution=" ",
                    **right_args,
                )
        elif isinstance(right_layer, ipyleaflet.TileLayer) or isinstance(
            right_layer, ipyleaflet.GeoJSON
        ):
            pass
        elif common.is_array(right_layer):
            right_layer = common.array_to_image(right_layer, **right_array_args)
            right_layer, _ = common.get_local_tile_layer(
                right_layer,
                return_client=True,
                **right_args,
            )
        elif isinstance(right_layer, gpd.GeoDataFrame):
            right_layer = right_layer.to_crs("EPSG:4326").__geo_interface__
            if "max_zoom" in right_args:
                del right_args["max_zoom"]
            if "max_native_zoom" in right_args:
                del right_args["max_native_zoom"]
            right_layer = geojson_layer(right_layer, **right_args)
        else:
            raise ValueError(
                f"right_layer must be one of the following: {', '.join(basemaps.keys())} or a string url to a tif file."
            )
        control = ipyleaflet.SplitMapControl(
            left_layer=left_layer, right_layer=right_layer
        )
        self.add(control)

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

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

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

        if bounds is not None:
            self.fit_bounds(bounds)

        self.dragging = draggable

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

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

            if left_label in self.controls:
                self.remove_control(left_control)

            if right_label in self.controls:
                self.remove_control(right_control)

            self.dragging = True

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

        if add_close_button:
            self.add(close_control)

        if layer_control:
            self.add_layer_control()

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

static_map(width=950, height=600, out_file=None, **kwargs)

Display an ipyleaflet static map in a Jupyter Notebook.

Args m (ipyleaflet.Map): An ipyleaflet map. width (int, optional): Width of the map. Defaults to 950. height (int, optional): Height of the map. Defaults to 600. read_only (bool, optional): Whether to hide the side panel to disable map customization. Defaults to False. out_file (str, optional): Output html file path. Defaults to None.

Source code in leafmap/leafmap.py

def static_map(
    self,
    width: int = 950,
    height: int = 600,
    out_file: Optional[str] = None,
    **kwargs,
) -> None:
    """Display an ipyleaflet static map in a Jupyter Notebook.

    Args
        m (ipyleaflet.Map): An ipyleaflet map.
        width (int, optional): Width of the map. Defaults to 950.
        height (int, optional): Height of the map. Defaults to 600.
        read_only (bool, optional): Whether to hide the side panel to disable map customization. Defaults to False.
        out_file (str, optional): Output html file path. Defaults to None.
    """
    if isinstance(self, ipyleaflet.Map):
        if out_file is None:
            out_file = "./cache/" + "leafmap_" + common.random_string(3) + ".html"
        out_dir = os.path.abspath(os.path.dirname(out_file))
        if not os.path.exists(out_dir):
            os.makedirs(out_dir)

        self.to_html(out_file)
        common.display_html(out_file, width=width, height=height)
    else:
        raise TypeError("The provided map is not an ipyleaflet map.")

to_html(outfile=None, title='My Map', width='100%', height='880px', add_layer_control=True, **kwargs)

Saves the map as an HTML file.

Parameters:

Name	Type	Description	Default
outfile	str	The output file path to the HTML file.	None
title	str	The title of the HTML file. Defaults to 'My Map'.	'My Map'
width	str	The width of the map in pixels or percentage. Defaults to '100%'.	'100%'
height	str	The height of the map in pixels. Defaults to '880px'.	'880px'
add_layer_control	bool	Whether to add the LayersControl. Defaults to True.	True

Source code in leafmap/leafmap.py

def to_html(
    self,
    outfile: Optional[str] = None,
    title: Optional[str] = "My Map",
    width: Optional[str] = "100%",
    height: Optional[str] = "880px",
    add_layer_control: Optional[bool] = True,
    **kwargs,
) -> None:
    """Saves the map as an HTML file.

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

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

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

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

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

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

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

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

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

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

    except Exception as e:
        raise Exception(e)

to_image(outfile=None, monitor=1)

Saves the map as a PNG or JPG image.

Parameters:

Name	Type	Description	Default
outfile	str	The output file path to the image. Defaults to None.	None
monitor	int	The monitor to take the screenshot. Defaults to 1.	1

Source code in leafmap/leafmap.py

def to_image(
    self, outfile: Optional[str] = None, monitor: Optional[int] = 1
) -> None:
    """Saves the map as a PNG or JPG image.

    Args:
        outfile (str, optional): The output file path to the image. Defaults to None.
        monitor (int, optional): The monitor to take the screenshot. Defaults to 1.
    """
    if outfile is None:
        outfile = os.path.join(os.getcwd(), "my_map.png")

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

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

    screenshot = common.screen_capture(outfile, monitor)
    self.screenshot = screenshot

to_streamlit(width=None, height=600, scrolling=False, **kwargs)

Renders map figure in a Streamlit app.

Parameters:

Name	Type	Description	Default
width	int	Width of the map. Defaults to None.	None
height	int	Height of the map. Defaults to 600.	600
responsive	bool	Whether to make the map responsive. Defaults to True.	required
scrolling	bool	If True, show a scrollbar when the content is larger than the iframe. Otherwise, do not show a scrollbar. Defaults to False.	False

Returns:

Type	Description
	streamlit.components: components.html object.

Source code in leafmap/leafmap.py

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

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

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

    try:
        import streamlit.components.v1 as components  # pylint: disable=E0401

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

    except Exception as e:
        raise Exception(e)

toolbar_reset()

Reset the toolbar so that no tool is selected.

Source code in leafmap/leafmap.py

def toolbar_reset(self) -> None:
    """Reset the toolbar so that no tool is selected."""
    toolbar_grid = self.toolbar
    for tool in toolbar_grid.children:
        tool.value = False

update_draw_features()

Update the draw features by removing features that have been edited and no longer exist.

Source code in leafmap/leafmap.py

def update_draw_features(self) -> None:
    """Update the draw features by removing features that have been edited and no longer exist."""

    geometries = [feature["geometry"] for feature in self.draw_control.data]

    for feature in self.draw_features:
        if feature["geometry"] not in geometries:
            self.draw_features.remove(feature)

update_draw_props(df)

Update the draw features properties.

Parameters:

Name	Type	Description	Default
df	DataFrame	A pandas dataframe containing the properties of the draw features.	required

Source code in leafmap/leafmap.py

def update_draw_props(self, df: pd.DataFrame) -> None:
    """Update the draw features properties.

    Args:
        df (pd.DataFrame): A pandas dataframe containing the properties of the draw features.
    """

    df.dropna(inplace=True)
    df = df[df["Key"].astype(bool)]
    if len(df) > 0:
        props = df.set_index("Key").to_dict()["Value"]
        if self.draw_control.last_action == "edited":
            self.update_draw_features()
        if len(self.draw_features) > 0:
            if self.draw_control.last_action == "created":
                self.draw_features[-1]["properties"] = props
            elif self.draw_control.last_action == "edited":
                for feature in self.draw_features:
                    if (
                        self.draw_control.last_draw["geometry"]
                        == feature["geometry"]
                    ):
                        feature["properties"] = props
        for prop in list(props.keys()):
            if prop not in self.edit_props:
                self.edit_props.append(prop)

update_layer_manager()

Update the Layer Manager.

Source code in leafmap/leafmap.py

def update_layer_manager(self) -> None:
    """Update the Layer Manager."""
    from .toolbar import layer_manager_gui

    self._layer_manager_widget.children = layer_manager_gui(
        self, return_widget=True
    )

user_roi_bounds(decimals=4)

Get the bounds of the user drawn ROI as a tuple of (minx, miny, maxx, maxy).

Parameters:

Name	Type	Description	Default
decimals	int	The number of decimals to round the coordinates to. Defaults to 4.	4

Returns:

Name	Type	Description
list	list	The bounds of the user drawn ROI as a tuple of (minx, miny, maxx, maxy).

Source code in leafmap/leafmap.py

def user_roi_bounds(self, decimals: int = 4) -> list:
    """Get the bounds of the user drawn ROI as a tuple of (minx, miny, maxx, maxy).

    Args:
        decimals (int, optional): The number of decimals to round the coordinates to. Defaults to 4.

    Returns:
        list: The bounds of the user drawn ROI as a tuple of (minx, miny, maxx, maxy).
    """
    if self.user_roi is not None:
        return common.geometry_bounds(self.user_roi, decimals=decimals)
    else:
        return None

video_overlay(url, bounds, layer_name=None, **kwargs)

Overlays a video from the Internet on the map.

Parameters:

Name	Type	Description	Default
url	str	http URL of the video, such as "https://www.mapbox.com/bites/00188/patricia_nasa.webm"	required
bounds	tuple	bounding box of the video in the format of (lower_left(lat, lon), upper_right(lat, lon)), such as ((13, -130), (32, -100)).	required
layer_name	str	name of the layer to show on the layer control.	None

Source code in leafmap/leafmap.py

def video_overlay(
    self, url: str, bounds: Tuple, layer_name: str = None, **kwargs
) -> None:
    """Overlays a video from the Internet on the map.

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

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 leafmap/leafmap.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 ipyleaflet fit_bounds method takes lat/lon bounds in the form [[south, west], [north, east]].
    self.fit_bounds([[bounds[1], bounds[0]], [bounds[3], bounds[2]]])

zoom_to_gdf(gdf)

Zooms to the bounding box of a GeoPandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoPandas GeoDataFrame.	required

Source code in leafmap/leafmap.py

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

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

PlanetaryComputerEndpoint

Bases: TitilerEndpoint

This class contains the methods for the Microsoft Planetary Computer endpoint.

Source code in leafmap/stac.py

class PlanetaryComputerEndpoint(TitilerEndpoint):
    """This class contains the methods for the Microsoft Planetary Computer endpoint."""

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

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

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

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

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

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

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

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

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

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

    def url_for_collection_bbox_assets(self, minx, miny, maxx, maxy):
        return f"{self.endpoint}/collection/{minx},{miny},{maxx},{maxy}/assets"

    def url_for_stac_mosaic(self, searchid):
        return f"{self.endpoint}/mosaic/{searchid}/{self.TileMatrixSetId}/tilejson.json"

    def url_for_mosaic_info(self, searchid):
        return f"{self.endpoint}/mosaic/{searchid}/info"

    def url_for_mosaic_lat_lon_assets(self, searchid, lon, lat):
        return f"{self.endpoint}/mosaic/{searchid}/{lon},{lat}/assets"

__init__(endpoint='https://planetarycomputer.microsoft.com/api/data/v1', name='item', TileMatrixSetId='WebMercatorQuad')

Initialize the PlanetaryComputerEndpoint object.

Parameters:

Name	Type	Description	Default
endpoint	str	The endpoint of the titiler server. Defaults to "https://planetarycomputer.microsoft.com/api/data/v1".	'https://planetarycomputer.microsoft.com/api/data/v1'
name	str	The name to be used in the file path. Defaults to "item".	'item'
TileMatrixSetId	str	The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".	'WebMercatorQuad'

Source code in leafmap/stac.py

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

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

The_national_map_USGS

The national map is a collection of topological datasets, maintained by the USGS.

It provides an API endpoint which can be used to find downloadable links for the products offered. - Full description of datasets available can retrieved. This consists of metadata such as detail description and publication dates. - A wide range of dataformats are available

This class is a tiny wrapper to find and download files using the API.

More complete documentation for the API can be found at https://apps.nationalmap.gov/tnmaccess/#/

Source code in leafmap/common.py

class The_national_map_USGS:
    """
    The national map is a collection of topological datasets, maintained by the USGS.

    It provides an API endpoint which can be used to find downloadable links for the products offered.
        - Full description of datasets available can retrieved.
          This consists of metadata such as detail description and publication dates.
        - A wide range of dataformats are available

    This class is a tiny wrapper to find and download files using the API.

    More complete documentation for the API can be found at
        https://apps.nationalmap.gov/tnmaccess/#/
    """

    def __init__(self):
        self.api_endpoint = r"https://tnmaccess.nationalmap.gov/api/v1/"
        self.DS = self.datasets_full

    @property
    def datasets_full(self) -> list:
        """
        Full description of datasets provided.
        Returns a JSON or empty list.
        """
        link = f"{self.api_endpoint}datasets?"
        try:
            return requests.get(link).json()
        except Exception:
            print(f"Failed to load metadata from The National Map API endpoint\n{link}")
            return []

    @property
    def prodFormats(self) -> list:
        """
        Return all datatypes available in any of the collections.
        Note that "All" is only peculiar to one dataset.
        """
        return set(i["displayName"] for ds in self.DS for i in ds["formats"])

    @property
    def datasets(self) -> list:
        """
        Returns a list of dataset tags (most common human readable self description for specific datasets).
        """
        return set(y["sbDatasetTag"] for x in self.DS for y in x["tags"])

    def parse_region(self, region, geopandas_args={}) -> list:
        """

        Translate a Vector dataset to its bounding box.

        Args:
            region (str | list): an URL|filepath to a vector dataset to a polygon
            geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
                Used for reading a region URL|filepath.
        """
        import geopandas as gpd

        if isinstance(region, str):
            if region.startswith("http"):
                region = github_raw_url(region)
                region = download_file(region)
            elif not os.path.exists(region):
                raise ValueError("region must be a path or a URL to a vector dataset.")

            roi = gpd.read_file(region, **geopandas_args)
            roi = roi.to_crs(epsg=4326)
            return roi.total_bounds
        return region

    def download_tiles(
        self, region=None, out_dir=None, download_args={}, geopandas_args={}, API={}
    ) -> None:
        """

        Download the US National Elevation Datasets (NED) for a region.

        Args:
            region (str | list, optional): An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy].
                Alternatively you could use API parameters such as polygon or bbox.
            out_dir (str, optional): The directory to download the files to. Defaults to None, which uses the current working directory.
            download_args (dict, optional): A dictionary of arguments to pass to the download_file function. Defaults to {}.
            geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
                Used for reading a region URL|filepath.
            API (dict, optional): A dictionary of arguments to pass to the self.find_details() function.
                Exposes most of the documented API. Defaults to {}.

        Returns:
            None
        """

        if os.environ.get("USE_MKDOCS") is not None:
            return

        if out_dir is None:
            out_dir = os.getcwd()
        else:
            out_dir = os.path.abspath(out_dir)

        tiles = self.find_tiles(
            region, return_type="list", geopandas_args=geopandas_args, API=API
        )
        T = len(tiles)
        errors = 0
        done = 0

        for i, link in enumerate(tiles):
            file_name = os.path.basename(link)
            out_name = os.path.join(out_dir, file_name)
            if i < 5 or (i < 50 and not (i % 5)) or not (i % 20):
                print(f"Downloading {i+1} of {T}: {file_name}")
            try:
                download_file(link, out_name, **download_args)
                done += 1
            except KeyboardInterrupt:
                print("Cancelled download")
                break
            except Exception:
                errors += 1
                print(f"Failed to download {i+1} of {T}: {file_name}")

        print(
            f"{done} Downloads completed, {errors} downloads failed, {T} files available"
        )
        return

    def find_tiles(
        self, region=None, return_type="list", geopandas_args={}, API={}
    ) -> Union[List[str], Dict]:
        """
        Find a list of downloadable files.

        Args:
            region (str | list, optional): An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy].
                Alternatively you could use API parameters such as polygon or bbox.
            return_type (str): list | dict. Defaults to list. Changes the return output type and content.
            geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
                Used for reading a region URL|filepath.
            API (dict, optional): A dictionary of arguments to pass to the self.find_details() function.
                Exposes most of the documented API parameters. Defaults to {}.

        Returns:
            A list of download URLs if return_type is 'list', otherwise a dictionary with URLs and related metadata.
        """
        assert region or API, "Provide a region or use the API"

        if region:
            API["bbox"] = self.parse_region(region, geopandas_args)

        results = self.find_details(**API)
        if return_type == "list":
            return [i["downloadURL"] for i in results.get("items")]
        return results

    def find_details(
        self,
        bbox: List[float] = None,
        polygon: List[Tuple[float, float]] = None,
        datasets: str = None,
        prodFormats: str = None,
        prodExtents: str = None,
        q: str = None,
        dateType: str = None,
        start: str = None,
        end: str = None,
        offset: int = 0,
        max: int = None,
        outputFormat: str = "JSON",
        polyType: str = None,
        polyCode: str = None,
        extentQuery: int = None,
    ) -> Dict:
        """
        Possible search parameters (kwargs) support by API

        Parameter               Values
            Description
        ---------------------------------------------------------------------------------------------------
        bbox                    'minx, miny, maxx, maxy'
            Geographic longitude/latitude values expressed in  decimal degrees in a comma-delimited list.
        polygon                 '[x,y x,y x,y x,y x,y]'
            Polygon, longitude/latitude values expressed in decimal degrees in a space-delimited list.
        datasets                See: Datasets (Optional)
            Dataset tag name (sbDatasetTag)
            From https://apps.nationalmap.gov/tnmaccess/#/product
        prodFormats             See: Product Formats (Optional)
            Dataset-specific format

        prodExtents             See: Product Extents (Optional)
            Dataset-specific extent
        q                       free text
            Text input which can be used to filter by product titles and text descriptions.
        dateType                dateCreated | lastUpdated | Publication
            Type of date to search by.
        start                   'YYYY-MM-DD'
            Start date
        end                     'YYYY-MM-DD'
            End date (required if start date is provided)
        offset                  integer
            Offset into paginated results - default=0
        max                     integer
            Number of results returned
        outputFormat            JSON | CSV | pjson
            Default=JSON
        polyType                state | huc2 | huc4 | huc8
            Well Known Polygon Type. Use this parameter to deliver data by state or HUC
            (hydrologic unit codes defined by the Watershed Boundary Dataset/WBD)
        polyCode                state FIPS code or huc number
            Well Known Polygon Code. This value needs to coordinate with the polyType parameter.
        extentQuery             integer
            A Polygon code in the science base system, typically from an uploaded shapefile
        """

        try:
            # call locals before creating new locals
            used_locals = {k: v for k, v in locals().items() if v and k != "self"}

            # Parsing
            if polygon:
                used_locals["polygon"] = ",".join(
                    " ".join(map(str, point)) for point in polygon
                )
            if bbox:
                used_locals["bbox"] = str(bbox)[1:-1]

            if max:
                max += 2

            # Fetch response
            response = requests.get(f"{self.api_endpoint}products?", params=used_locals)
            if response.status_code // 100 == 2:
                return response.json()
            else:
                # Parameter validation handled by API endpoint error responses
                print(response.json())
            return {}
        except Exception as e:
            print(e)
            return {}

datasets property

Returns a list of dataset tags (most common human readable self description for specific datasets).

datasets_full property

Full description of datasets provided. Returns a JSON or empty list.

prodFormats property

Return all datatypes available in any of the collections. Note that "All" is only peculiar to one dataset.

download_tiles(region=None, out_dir=None, download_args={}, geopandas_args={}, API={})

Download the US National Elevation Datasets (NED) for a region.

Parameters:

Name	Type	Description	Default
region	str | list	An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy]. Alternatively you could use API parameters such as polygon or bbox.	None
out_dir	str	The directory to download the files to. Defaults to None, which uses the current working directory.	None
download_args	dict	A dictionary of arguments to pass to the download_file function. Defaults to {}.	{}
geopandas_args	dict	A dictionary of arguments to pass to the geopandas.read_file() function. Used for reading a region URL|filepath.	{}
API	dict	A dictionary of arguments to pass to the self.find_details() function. Exposes most of the documented API. Defaults to {}.	{}

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def download_tiles(
    self, region=None, out_dir=None, download_args={}, geopandas_args={}, API={}
) -> None:
    """

    Download the US National Elevation Datasets (NED) for a region.

    Args:
        region (str | list, optional): An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy].
            Alternatively you could use API parameters such as polygon or bbox.
        out_dir (str, optional): The directory to download the files to. Defaults to None, which uses the current working directory.
        download_args (dict, optional): A dictionary of arguments to pass to the download_file function. Defaults to {}.
        geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
            Used for reading a region URL|filepath.
        API (dict, optional): A dictionary of arguments to pass to the self.find_details() function.
            Exposes most of the documented API. Defaults to {}.

    Returns:
        None
    """

    if os.environ.get("USE_MKDOCS") is not None:
        return

    if out_dir is None:
        out_dir = os.getcwd()
    else:
        out_dir = os.path.abspath(out_dir)

    tiles = self.find_tiles(
        region, return_type="list", geopandas_args=geopandas_args, API=API
    )
    T = len(tiles)
    errors = 0
    done = 0

    for i, link in enumerate(tiles):
        file_name = os.path.basename(link)
        out_name = os.path.join(out_dir, file_name)
        if i < 5 or (i < 50 and not (i % 5)) or not (i % 20):
            print(f"Downloading {i+1} of {T}: {file_name}")
        try:
            download_file(link, out_name, **download_args)
            done += 1
        except KeyboardInterrupt:
            print("Cancelled download")
            break
        except Exception:
            errors += 1
            print(f"Failed to download {i+1} of {T}: {file_name}")

    print(
        f"{done} Downloads completed, {errors} downloads failed, {T} files available"
    )
    return

find_details(bbox=None, polygon=None, datasets=None, prodFormats=None, prodExtents=None, q=None, dateType=None, start=None, end=None, offset=0, max=None, outputFormat='JSON', polyType=None, polyCode=None, extentQuery=None)

Possible search parameters (kwargs) support by API

Parameter Values Description

---

bbox 'minx, miny, maxx, maxy' Geographic longitude/latitude values expressed in decimal degrees in a comma-delimited list. polygon '[x,y x,y x,y x,y x,y]' Polygon, longitude/latitude values expressed in decimal degrees in a space-delimited list. datasets See: Datasets (Optional) Dataset tag name (sbDatasetTag) From https://apps.nationalmap.gov/tnmaccess/#/product prodFormats See: Product Formats (Optional) Dataset-specific format

Product Extents (Optional)

Dataset-specific extent

q free text Text input which can be used to filter by product titles and text descriptions. dateType dateCreated | lastUpdated | Publication Type of date to search by. start 'YYYY-MM-DD' Start date end 'YYYY-MM-DD' End date (required if start date is provided) offset integer Offset into paginated results - default=0 max integer Number of results returned outputFormat JSON | CSV | pjson Default=JSON polyType state | huc2 | huc4 | huc8 Well Known Polygon Type. Use this parameter to deliver data by state or HUC (hydrologic unit codes defined by the Watershed Boundary Dataset/WBD) polyCode state FIPS code or huc number Well Known Polygon Code. This value needs to coordinate with the polyType parameter. extentQuery integer A Polygon code in the science base system, typically from an uploaded shapefile

Source code in leafmap/common.py

def find_details(
    self,
    bbox: List[float] = None,
    polygon: List[Tuple[float, float]] = None,
    datasets: str = None,
    prodFormats: str = None,
    prodExtents: str = None,
    q: str = None,
    dateType: str = None,
    start: str = None,
    end: str = None,
    offset: int = 0,
    max: int = None,
    outputFormat: str = "JSON",
    polyType: str = None,
    polyCode: str = None,
    extentQuery: int = None,
) -> Dict:
    """
    Possible search parameters (kwargs) support by API

    Parameter               Values
        Description
    ---------------------------------------------------------------------------------------------------
    bbox                    'minx, miny, maxx, maxy'
        Geographic longitude/latitude values expressed in  decimal degrees in a comma-delimited list.
    polygon                 '[x,y x,y x,y x,y x,y]'
        Polygon, longitude/latitude values expressed in decimal degrees in a space-delimited list.
    datasets                See: Datasets (Optional)
        Dataset tag name (sbDatasetTag)
        From https://apps.nationalmap.gov/tnmaccess/#/product
    prodFormats             See: Product Formats (Optional)
        Dataset-specific format

    prodExtents             See: Product Extents (Optional)
        Dataset-specific extent
    q                       free text
        Text input which can be used to filter by product titles and text descriptions.
    dateType                dateCreated | lastUpdated | Publication
        Type of date to search by.
    start                   'YYYY-MM-DD'
        Start date
    end                     'YYYY-MM-DD'
        End date (required if start date is provided)
    offset                  integer
        Offset into paginated results - default=0
    max                     integer
        Number of results returned
    outputFormat            JSON | CSV | pjson
        Default=JSON
    polyType                state | huc2 | huc4 | huc8
        Well Known Polygon Type. Use this parameter to deliver data by state or HUC
        (hydrologic unit codes defined by the Watershed Boundary Dataset/WBD)
    polyCode                state FIPS code or huc number
        Well Known Polygon Code. This value needs to coordinate with the polyType parameter.
    extentQuery             integer
        A Polygon code in the science base system, typically from an uploaded shapefile
    """

    try:
        # call locals before creating new locals
        used_locals = {k: v for k, v in locals().items() if v and k != "self"}

        # Parsing
        if polygon:
            used_locals["polygon"] = ",".join(
                " ".join(map(str, point)) for point in polygon
            )
        if bbox:
            used_locals["bbox"] = str(bbox)[1:-1]

        if max:
            max += 2

        # Fetch response
        response = requests.get(f"{self.api_endpoint}products?", params=used_locals)
        if response.status_code // 100 == 2:
            return response.json()
        else:
            # Parameter validation handled by API endpoint error responses
            print(response.json())
        return {}
    except Exception as e:
        print(e)
        return {}

find_tiles(region=None, return_type='list', geopandas_args={}, API={})

Find a list of downloadable files.

Parameters:

Name	Type	Description	Default
region	str | list	An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy]. Alternatively you could use API parameters such as polygon or bbox.	None
return_type	str	list | dict. Defaults to list. Changes the return output type and content.	'list'
geopandas_args	dict	A dictionary of arguments to pass to the geopandas.read_file() function. Used for reading a region URL|filepath.	{}
API	dict	A dictionary of arguments to pass to the self.find_details() function. Exposes most of the documented API parameters. Defaults to {}.	{}

Returns:

Type	Description
Union[List[str], Dict]	A list of download URLs if return_type is 'list', otherwise a dictionary with URLs and related metadata.

Source code in leafmap/common.py

def find_tiles(
    self, region=None, return_type="list", geopandas_args={}, API={}
) -> Union[List[str], Dict]:
    """
    Find a list of downloadable files.

    Args:
        region (str | list, optional): An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy].
            Alternatively you could use API parameters such as polygon or bbox.
        return_type (str): list | dict. Defaults to list. Changes the return output type and content.
        geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
            Used for reading a region URL|filepath.
        API (dict, optional): A dictionary of arguments to pass to the self.find_details() function.
            Exposes most of the documented API parameters. Defaults to {}.

    Returns:
        A list of download URLs if return_type is 'list', otherwise a dictionary with URLs and related metadata.
    """
    assert region or API, "Provide a region or use the API"

    if region:
        API["bbox"] = self.parse_region(region, geopandas_args)

    results = self.find_details(**API)
    if return_type == "list":
        return [i["downloadURL"] for i in results.get("items")]
    return results

parse_region(region, geopandas_args={})

Translate a Vector dataset to its bounding box.

Parameters:

Name	Type	Description	Default
region	str | list	an URL|filepath to a vector dataset to a polygon	required
geopandas_args	dict	A dictionary of arguments to pass to the geopandas.read_file() function. Used for reading a region URL|filepath.	{}

Source code in leafmap/common.py

def parse_region(self, region, geopandas_args={}) -> list:
    """

    Translate a Vector dataset to its bounding box.

    Args:
        region (str | list): an URL|filepath to a vector dataset to a polygon
        geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
            Used for reading a region URL|filepath.
    """
    import geopandas as gpd

    if isinstance(region, str):
        if region.startswith("http"):
            region = github_raw_url(region)
            region = download_file(region)
        elif not os.path.exists(region):
            raise ValueError("region must be a path or a URL to a vector dataset.")

        roi = gpd.read_file(region, **geopandas_args)
        roi = roi.to_crs(epsg=4326)
        return roi.total_bounds
    return region

TitilerEndpoint

This class contains the methods for the titiler endpoint.

Source code in leafmap/stac.py

class TitilerEndpoint:
    """This class contains the methods for the titiler endpoint."""

    def __init__(
        self,
        endpoint: Optional[str] = None,
        name: Optional[str] = "stac",
        TileMatrixSetId: Optional[str] = "WebMercatorQuad",
    ):
        """Initialize the TiTilerEndpoint object.

        Args:
            endpoint (str, optional): The endpoint of the titiler server. Defaults to "https://giswqs-titiler-endpoint.hf.space".
            name (str, optional): The name to be used in the file path. Defaults to "stac".
            TileMatrixSetId (str, optional): The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".
        """
        self.endpoint = endpoint
        self.name = name
        self.TileMatrixSetId = TileMatrixSetId

    def url_for_stac_item(self):
        return f"{self.endpoint}/{self.name}/{self.TileMatrixSetId}/tilejson.json"

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

    def url_for_stac_bounds(self):
        return f"{self.endpoint}/{self.name}/info.geojson"

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

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

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

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

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

__init__(endpoint=None, 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".	None
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 leafmap/stac.py

def __init__(
    self,
    endpoint: Optional[str] = None,
    name: Optional[str] = "stac",
    TileMatrixSetId: Optional[str] = "WebMercatorQuad",
):
    """Initialize the TiTilerEndpoint object.

    Args:
        endpoint (str, optional): The endpoint of the titiler server. Defaults to "https://giswqs-titiler-endpoint.hf.space".
        name (str, optional): The name to be used in the file path. Defaults to "stac".
        TileMatrixSetId (str, optional): The TileMatrixSetId to be used in the file path. Defaults to "WebMercatorQuad".
    """
    self.endpoint = endpoint
    self.name = name
    self.TileMatrixSetId = TileMatrixSetId

WhiteboxTools

Bases: WhiteboxTools

This class inherits the whitebox WhiteboxTools class.

Source code in leafmap/common.py

class WhiteboxTools(whitebox.WhiteboxTools):
    """This class inherits the whitebox WhiteboxTools class."""

    def __init__(self, **kwargs: Any):
        super().__init__(**kwargs)

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 leafmap/common.py

def add_crs(filename, epsg):
    """Add a CRS to a raster dataset.

    Args:
        filename (str): The filename of the raster dataset.
        epsg (int | str): The EPSG code of the CRS.

    """
    try:
        import rasterio
    except ImportError:
        raise ImportError(
            "rasterio is required for adding a CRS to a raster. Please install it using 'pip install rasterio'."
        )

    if not os.path.exists(filename):
        raise ValueError("filename must exist.")

    if isinstance(epsg, int):
        epsg = f"EPSG:{epsg}"
    elif isinstance(epsg, str):
        epsg = "EPSG:" + epsg
    else:
        raise ValueError("epsg must be an integer or string.")

    crs = rasterio.crs.CRS({"init": epsg})
    with rasterio.open(filename, mode="r+") as src:
        src.crs = crs

add_image_to_gif(in_gif, out_gif, in_image, xy=None, image_size=(80, 80), circle_mask=False)

Adds an image logo to a GIF image.

Parameters:

Name	Type	Description	Default
in_gif	str	Input file path to the GIF image.	required
out_gif	str	Output file path to the GIF image.	required
in_image	str	Input file path to the image.	required
xy	tuple	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	None
image_size	tuple	Resize image. Defaults to (80, 80).	(80, 80)
circle_mask	bool	Whether to apply a circle mask to the image. This only works with non-png images. Defaults to False.	False

Source code in leafmap/common.py

def add_image_to_gif(
    in_gif, out_gif, in_image, xy=None, image_size=(80, 80), circle_mask=False
):
    """Adds an image logo to a GIF image.

    Args:
        in_gif (str): Input file path to the GIF image.
        out_gif (str): Output file path to the GIF image.
        in_image (str): Input file path to the image.
        xy (tuple, optional): Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        image_size (tuple, optional): Resize image. Defaults to (80, 80).
        circle_mask (bool, optional): Whether to apply a circle mask to the image. This only works with non-png images. Defaults to False.
    """
    import io

    from PIL import Image, ImageDraw, ImageSequence

    warnings.simplefilter("ignore")

    in_gif = os.path.abspath(in_gif)

    is_url = False
    if in_image.startswith("http"):
        is_url = True

    if not os.path.exists(in_gif):
        print("The input gif file does not exist.")
        return

    if (not is_url) and (not os.path.exists(in_image)):
        print("The provided logo file does not exist.")
        return

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

    try:
        gif = Image.open(in_gif)
    except Exception as e:
        print("An error occurred while opening the image.")
        print(e)
        return

    logo_raw_image = None
    try:
        if in_image.startswith("http"):
            logo_raw_image = open_image_from_url(in_image)
        else:
            in_image = os.path.abspath(in_image)
            logo_raw_image = Image.open(in_image)
    except Exception as e:
        print(e)

    logo_raw_size = logo_raw_image.size

    ratio = max(
        logo_raw_size[0] / image_size[0],
        logo_raw_size[1] / image_size[1],
    )
    image_resize = (int(logo_raw_size[0] / ratio), int(logo_raw_size[1] / ratio))
    image_size = min(logo_raw_size[0], image_size[0]), min(
        logo_raw_size[1], image_size[1]
    )

    logo_image = logo_raw_image.convert("RGBA")
    logo_image.thumbnail(image_size, Image.ANTIALIAS)

    gif_width, gif_height = gif.size
    mask_im = None

    if circle_mask:
        mask_im = Image.new("L", image_size, 0)
        draw = ImageDraw.Draw(mask_im)
        draw.ellipse((0, 0, image_size[0], image_size[1]), fill=255)

    if has_transparency(logo_raw_image):
        mask_im = logo_image.copy()

    if xy is None:
        # default logo location is 5% width and 5% height of the image.
        delta = 10
        xy = (gif_width - image_resize[0] - delta, gif_height - image_resize[1] - delta)
        # xy = (int(0.05 * gif_width), int(0.05 * gif_height))
    elif (xy is not None) and (not isinstance(xy, tuple)) and (len(xy) == 2):
        print("xy must be a tuple, e.g., (10, 10), ('10%', '10%')")
        return
    elif all(isinstance(item, int) for item in xy) and (len(xy) == 2):
        x, y = xy
        if (x > 0) and (x < gif_width) and (y > 0) and (y < gif_height):
            pass
        else:
            print(
                "xy is out of bounds. x must be within [0, {}], and y must be within [0, {}]".format(
                    gif_width, gif_height
                )
            )
            return
    elif all(isinstance(item, str) for item in xy) and (len(xy) == 2):
        x, y = xy
        if ("%" in x) and ("%" in y):
            try:
                x = int(float(x.replace("%", "")) / 100.0 * gif_width)
                y = int(float(y.replace("%", "")) / 100.0 * gif_height)
                xy = (x, y)
            except Exception:
                raise Exception(
                    "The specified xy is invalid. It must be formatted like this ('10%', '10%')"
                )

    else:
        raise Exception(
            "The specified xy is invalid. It must be formatted like this: (10, 10) or ('10%', '10%')"
        )

    try:
        frames = []
        for _, frame in enumerate(ImageSequence.Iterator(gif)):
            frame = frame.convert("RGBA")
            frame.paste(logo_image, xy, mask_im)

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

        frames[0].save(out_gif, save_all=True, append_images=frames[1:])
    except Exception as e:
        print(e)

add_mask_to_image(image, mask, output, color='red')

Overlay a binary mask (e.g., roads, building footprints, etc) on an image. Credits to Xingjian Shi for the sample code.

Parameters:

Name	Type	Description	Default
image	str	A local path or HTTP URL to an image.	required
mask	str	A local path or HTTP URL to a binary mask.	required
output	str	A local path to the output image.	required
color	str	Color of the mask. Defaults to 'red'.	'red'

Raises:

Type	Description
ImportError	If rasterio and detectron2 are not installed.

Source code in leafmap/common.py

def add_mask_to_image(image, mask, output, color="red"):
    """Overlay a binary mask (e.g., roads, building footprints, etc) on an image. Credits to Xingjian Shi for the sample code.

    Args:
        image (str): A local path or HTTP URL to an image.
        mask (str): A local path or HTTP URL to a binary mask.
        output (str): A local path to the output image.
        color (str, optional): Color of the mask. Defaults to 'red'.

    Raises:
        ImportError: If rasterio and detectron2 are not installed.
    """
    try:
        import rasterio
        from detectron2.utils.visualizer import Visualizer
        from PIL import Image
    except ImportError:
        raise ImportError(
            "Please install rasterio and detectron2 to use this function. See https://detectron2.readthedocs.io/en/latest/tutorials/install.html"
        )

    ds = rasterio.open(image)
    image_arr = ds.read()

    mask_arr = rasterio.open(mask).read()

    vis = Visualizer(image_arr.transpose((1, 2, 0)))
    vis.draw_binary_mask(mask_arr[0] > 0, color=color)

    out_arr = Image.fromarray(vis.get_output().get_image())

    out_arr.save(output)

    if ds.crs is not None:
        numpy_to_cog(output, output, profile=image)

add_progress_bar_to_gif(in_gif, out_gif, progress_bar_color='blue', progress_bar_height=5, duration=100, loop=0)

Adds a progress bar to a GIF image.

Parameters:

Name	Type	Description	Default
in_gif	str	The file path to the input GIF image.	required
out_gif	str	The file path to the output GIF image.	required
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'blue'
progress_bar_height	int	Height of the progress bar. Defaults to 5.	5
duration	int	controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation. Defaults to 100.	100
loop	int	controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.	0

Source code in leafmap/common.py

def add_progress_bar_to_gif(
    in_gif,
    out_gif,
    progress_bar_color="blue",
    progress_bar_height=5,
    duration=100,
    loop=0,
):
    """Adds a progress bar to a GIF image.

    Args:
        in_gif (str): The file path to the input GIF image.
        out_gif (str): The file path to the output GIF image.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
        duration (int, optional): controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation. Defaults to 100.
        loop (int, optional): controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.

    """
    import io

    from PIL import Image, ImageDraw, ImageSequence

    warnings.simplefilter("ignore")

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

    if not os.path.exists(in_gif):
        print("The input gif file does not exist.")
        return

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

    progress_bar_color = check_color(progress_bar_color)

    try:
        image = Image.open(in_gif)
    except Exception as e:
        raise Exception("An error occurred while opening the gif.")

    count = image.n_frames
    W, H = image.size
    progress_bar_widths = [i * 1.0 / count * W for i in range(1, count + 1)]
    progress_bar_shapes = [
        [(0, H - progress_bar_height), (x, H)] for x in progress_bar_widths
    ]

    try:
        frames = []
        # Loop over each frame in the animated image
        for index, frame in enumerate(ImageSequence.Iterator(image)):
            # Draw the text on the frame
            frame = frame.convert("RGB")
            draw = ImageDraw.Draw(frame)
            # w, h = draw.textsize(text[index])
            draw.rectangle(progress_bar_shapes[index], fill=progress_bar_color)
            del draw

            b = io.BytesIO()
            frame.save(b, format="GIF")
            frame = Image.open(b)

            frames.append(frame)
        # https://www.pythoninformer.com/python-libraries/pillow/creating-animated-gif/
        # Save the frames as a new image

        frames[0].save(
            out_gif,
            save_all=True,
            append_images=frames[1:],
            duration=duration,
            loop=loop,
            optimize=True,
        )
    except Exception as e:
        raise Exception(e)

add_text_to_gif(in_gif, out_gif, xy=None, text_sequence=None, font_type='arial.ttf', font_size=20, font_color='#000000', add_progress_bar=True, progress_bar_color='white', progress_bar_height=5, duration=100, loop=0)

Adds animated text to a GIF image.

Parameters:

Name	Type	Description	Default
in_gif	str	The file path to the input GIF image.	required
out_gif	str	The file path to the output GIF image.	required
xy	tuple	Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.	None
text_sequence	(int, str, list)	Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.	None
font_type	str	Font type. Defaults to "arial.ttf".	'arial.ttf'
font_size	int	Font size. Defaults to 20.	20
font_color	str	Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff'). Defaults to '#000000'.	'#000000'
add_progress_bar	bool	Whether to add a progress bar at the bottom of the GIF. Defaults to True.	True
progress_bar_color	str	Color for the progress bar. Defaults to 'white'.	'white'
progress_bar_height	int	Height of the progress bar. Defaults to 5.	5
duration	int	controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation.. Defaults to 100.	100
loop	int	controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.	0

Source code in leafmap/common.py

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

    Args:
        in_gif (str): The file path to the input GIF image.
        out_gif (str): The file path to the output GIF image.
        xy (tuple, optional): Top left corner of the text. It can be formatted like this: (10, 10) or ('15%', '25%'). Defaults to None.
        text_sequence (int, str, list, optional): Text to be drawn. It can be an integer number, a string, or a list of strings. Defaults to None.
        font_type (str, optional): Font type. Defaults to "arial.ttf".
        font_size (int, optional): Font size. Defaults to 20.
        font_color (str, optional): Font color. It can be a string (e.g., 'red'), rgb tuple (e.g., (255, 127, 0)), or hex code (e.g., '#ff00ff').  Defaults to '#000000'.
        add_progress_bar (bool, optional): Whether to add a progress bar at the bottom of the GIF. Defaults to True.
        progress_bar_color (str, optional): Color for the progress bar. Defaults to 'white'.
        progress_bar_height (int, optional): Height of the progress bar. Defaults to 5.
        duration (int, optional): controls how long each frame will be displayed for, in milliseconds. It is the inverse of the frame rate. Setting it to 100 milliseconds gives 10 frames per second. You can decrease the duration to give a smoother animation.. Defaults to 100.
        loop (int, optional): controls how many times the animation repeats. The default, 1, means that the animation will play once and then stop (displaying the last frame). A value of 0 means that the animation will repeat forever. Defaults to 0.

    """
    import importlib.resources
    import io

    from PIL import Image, ImageDraw, ImageFont, ImageSequence

    warnings.simplefilter("ignore")
    pkg_dir = os.path.dirname(importlib.resources.files("leafmap") / "leafmap.py")
    default_font = os.path.join(pkg_dir, "data/fonts/arial.ttf")

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

    if not os.path.exists(in_gif):
        print("The input gif file does not exist.")
        return

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

    if font_type == "arial.ttf":
        font = ImageFont.truetype(default_font, font_size)
    elif font_type == "alibaba.otf":
        default_font = os.path.join(pkg_dir, "data/fonts/alibaba.otf")
        font = ImageFont.truetype(default_font, font_size)
    else:
        try:
            font_list = system_fonts(show_full_path=True)
            font_names = [os.path.basename(f) for f in font_list]
            if (font_type in font_list) or (font_type in font_names):
                font = ImageFont.truetype(font_type, font_size)
            else:
                print(
                    "The specified font type could not be found on your system. Using the default font instead."
                )
                font = ImageFont.truetype(default_font, font_size)
        except Exception as e:
            print(e)
            font = ImageFont.truetype(default_font, font_size)

    color = check_color(font_color)
    progress_bar_color = check_color(progress_bar_color)

    try:
        image = Image.open(in_gif)
    except Exception as e:
        print("An error occurred while opening the gif.")
        print(e)
        return

    count = image.n_frames
    W, H = image.size
    progress_bar_widths = [i * 1.0 / count * W for i in range(1, count + 1)]
    progress_bar_shapes = [
        [(0, H - progress_bar_height), (x, H)] for x in progress_bar_widths
    ]

    if xy is None:
        # default text location is 5% width and 5% height of the image.
        xy = (int(0.05 * W), int(0.05 * H))
    elif (xy is not None) and (not isinstance(xy, tuple)) and (len(xy) == 2):
        print("xy must be a tuple, e.g., (10, 10), ('10%', '10%')")
        return
    elif all(isinstance(item, int) for item in xy) and (len(xy) == 2):
        x, y = xy
        if (x > 0) and (x < W) and (y > 0) and (y < H):
            pass
        else:
            print(
                f"xy is out of bounds. x must be within [0, {W}], and y must be within [0, {H}]"
            )
            return
    elif all(isinstance(item, str) for item in xy) and (len(xy) == 2):
        x, y = xy
        if ("%" in x) and ("%" in y):
            try:
                x = int(float(x.replace("%", "")) / 100.0 * W)
                y = int(float(y.replace("%", "")) / 100.0 * H)
                xy = (x, y)
            except Exception:
                raise Exception(
                    "The specified xy is invalid. It must be formatted like this ('10%', '10%')"
                )
    else:
        print(
            "The specified xy is invalid. It must be formatted like this: (10, 10) or ('10%', '10%')"
        )
        return

    if text_sequence is None:
        text = [str(x) for x in range(1, count + 1)]
    elif isinstance(text_sequence, int):
        text = [str(x) for x in range(text_sequence, text_sequence + count + 1)]
    elif isinstance(text_sequence, str):
        try:
            text_sequence = int(text_sequence)
            text = [str(x) for x in range(text_sequence, text_sequence + count + 1)]
        except Exception:
            text = [text_sequence] * count
    elif isinstance(text_sequence, list) and len(text_sequence) != count:
        print(
            f"The length of the text sequence must be equal to the number ({count}) of frames in the gif."
        )
        return
    else:
        text = [str(x) for x in text_sequence]

    try:
        frames = []
        # Loop over each frame in the animated image
        for index, frame in enumerate(ImageSequence.Iterator(image)):
            # Draw the text on the frame
            frame = frame.convert("RGB")
            draw = ImageDraw.Draw(frame)
            # w, h = draw.textsize(text[index])
            draw.text(xy, text[index], font=font, fill=color)
            if add_progress_bar:
                draw.rectangle(progress_bar_shapes[index], fill=progress_bar_color)
            del draw

            b = io.BytesIO()
            frame.save(b, format="GIF")
            frame = Image.open(b)

            frames.append(frame)
        # https://www.pythoninformer.com/python-libraries/pillow/creating-animated-gif/
        # Save the frames as a new image

        frames[0].save(
            out_gif,
            save_all=True,
            append_images=frames[1:],
            duration=duration,
            loop=loop,
            optimize=True,
        )
    except Exception as e:
        print(e)

add_unique_class(data, column, class_column='class', mapping=None)

Add a unique integer class column to a vector dataset based on an existing column.

Parameters:

Name	Type	Description	Default
data	str or GeoDataFrame	Input vector data as file path or GeoDataFrame.	required
column	str	The column name used for generating unique classes.	required
class_column	str	The name of the new column to store integer classes. Default is "class".	'class'
mapping	dict	A dictionary mapping original values to integer classes. If not provided, a mapping will be generated automatically starting from 1.	None

Returns:

Type	Description
GeoDataFrame	The updated GeoDataFrame with the new class column.

Source code in leafmap/common.py

def add_unique_class(
    data: Union[str, "gpd.GeoDataFrame"],
    column: str,
    class_column: str = "class",
    mapping: Optional[Dict[str, int]] = None,
) -> "gpd.GeoDataFrame":
    """
    Add a unique integer class column to a vector dataset based on an existing column.

    Args:
        data (str or GeoDataFrame): Input vector data as file path or GeoDataFrame.
        column (str): The column name used for generating unique classes.
        class_column (str): The name of the new column to store integer classes. Default is "class".
        mapping (dict, optional): A dictionary mapping original values to integer classes.
            If not provided, a mapping will be generated automatically starting from 1.

    Returns:
        The updated GeoDataFrame with the new class column.
    """
    import geopandas as gpd

    gdf = gpd.read_file(data) if isinstance(data, str) else data.copy()

    if column not in gdf.columns:
        raise ValueError(f"Column '{column}' not found in the input data.")

    if mapping is None:
        unique_values = sorted(gdf[column].dropna().unique())
        mapping = {val: idx + 1 for idx, val in enumerate(unique_values)}

    gdf[class_column] = gdf[column].map(mapping)

    return gdf

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:

Type	Description
Optional[dict]	A dictionary containing the converted longitudes.

Source code in leafmap/common.py

def adjust_longitude(in_fc) -> Optional[dict]:
    """Adjusts longitude if it is less than -180 or greater than 180.

    Args:
        in_fc (dict): The input dictionary containing coordinates.

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

arc_active_map()

Get the active map in ArcGIS Pro.

Returns:

Type	Description
Optional[Any]	The active map in ArcGIS Pro.

Source code in leafmap/common.py

def arc_active_map() -> Optional[Any]:
    """Get the active map in ArcGIS Pro.

    Returns:
        The active map in ArcGIS Pro.
    """
    if is_arcpy():
        import arcpy  # pylint: disable=E0401

        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
Optional[Any]	The active view in ArcGIS Pro.

Source code in leafmap/common.py

def arc_active_view() -> Optional[Any]:
    """Get the active view in ArcGIS Pro.

    Returns:
        The active view in ArcGIS Pro.
    """
    if is_arcpy():
        import arcpy  # pylint: disable=E0401

        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 leafmap/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_bounds(bounds)

Zoom to a bounding box.

Parameters:

Name	Type	Description	Default
bounds	list	The bounding box to zoom to in the form [xmin, ymin, xmax, ymax] or [(ymin, xmin), (ymax, xmax)].	required

Raises:

Type	Description
ValueError	description

Source code in leafmap/common.py

def arc_zoom_to_bounds(bounds):
    """Zoom to a bounding box.

    Args:
        bounds (list): The bounding box to zoom to in the form [xmin, ymin, xmax, ymax] or [(ymin, xmin), (ymax, xmax)].

    Raises:
        ValueError: _description_
    """

    if len(bounds) == 4:
        xmin, ymin, xmax, ymax = bounds
    elif len(bounds) == 2:
        (ymin, xmin), (ymax, xmax) = bounds
    else:
        raise ValueError("bounds must be a tuple of length 2 or 4.")

    arc_zoom_to_extent(xmin, ymin, xmax, ymax)

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 leafmap/common.py

def arc_zoom_to_extent(xmin, ymin, xmax, ymax):
    """Zoom to an extent in ArcGIS Pro.

    Args:
        xmin (float): The minimum x value of the extent.
        ymin (float): The minimum y value of the extent.
        xmax (float): The maximum x value of the extent.
        ymax (float): The maximum y value of the extent.
    """
    if is_arcpy():
        import arcpy  # pylint: disable=E0401

        view = arc_active_view()
        if view is not None:
            view.camera.setExtent(
                arcpy.Extent(
                    xmin,
                    ymin,
                    xmax,
                    ymax,
                    spatial_reference=arcpy.SpatialReference(4326),
                )
            )

array_to_image(array, output=None, source=None, dtype=None, compress='deflate', transpose=True, cellsize=None, crs=None, transform=None, driver='COG', colormap=None, **kwargs)

Save a NumPy array as a GeoTIFF using the projection information from an existing GeoTIFF file.

Parameters:

Name	Type	Description	Default
array	ndarray	The NumPy array to be saved as a GeoTIFF.	required
output	str	The path to the output image. If None, a temporary file will be created. Defaults to None.	None
source	str	The path to an existing GeoTIFF file with map projection information. Defaults to None.	None
dtype	dtype	The data type of the output array. Defaults to None.	None
compress	str	The compression method. Can be one of the following: "deflate", "lzw", "packbits", "jpeg". Defaults to "deflate".	'deflate'
transpose	bool	Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.	True
cellsize	float	The resolution of the output image in meters. Defaults to None.	None
crs	str	The CRS of the output image. Defaults to None.	None
transform	tuple	The affine transformation matrix, can be rio.transform() or a tuple like (0.5, 0.0, -180.25, 0.0, -0.5, 83.780361). Defaults to None.	None
driver	str	The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".	'COG'
colormap	dict	A dictionary defining the colormap (value: (R, G, B, A)).	None
**kwargs	Any	Additional keyword arguments to be passed to the rasterio.open() function.	{}

Source code in leafmap/common.py

def array_to_image(
    array,
    output: str = None,
    source: str = None,
    dtype: str = None,
    compress: str = "deflate",
    transpose: bool = True,
    cellsize: float = None,
    crs: str = None,
    transform: tuple = None,
    driver: str = "COG",
    colormap: dict = None,
    **kwargs: Any,
) -> str:
    """Save a NumPy array as a GeoTIFF using the projection information from an existing GeoTIFF file.

    Args:
        array (np.ndarray): The NumPy array to be saved as a GeoTIFF.
        output (str): The path to the output image. If None, a temporary file will be created. Defaults to None.
        source (str, optional): The path to an existing GeoTIFF file with map projection information. Defaults to None.
        dtype (np.dtype, optional): The data type of the output array. Defaults to None.
        compress (str, optional): The compression method. Can be one of the following: "deflate", "lzw", "packbits", "jpeg". Defaults to "deflate".
        transpose (bool, optional): Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.
        cellsize (float, optional): The resolution of the output image in meters. Defaults to None.
        crs (str, optional): The CRS of the output image. Defaults to None.
        transform (tuple, optional): The affine transformation matrix, can be rio.transform() or a tuple like (0.5, 0.0, -180.25, 0.0, -0.5, 83.780361).
            Defaults to None.
        driver (str, optional): The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".
        colormap (dict, optional): A dictionary defining the colormap (value: (R, G, B, A)).
        **kwargs (Any): Additional keyword arguments to be passed to the rasterio.open() function.
    """

    import numpy as np
    import rasterio
    import rioxarray
    import xarray as xr
    from rasterio.transform import Affine

    if output is None:
        return array_to_memory_file(
            array,
            source,
            dtype,
            compress,
            transpose,
            cellsize,
            crs=crs,
            transform=transform,
            driver=driver,
            colormap=colormap,
            **kwargs,
        )

    if isinstance(array, xr.DataArray):
        if (
            hasattr(array, "rio")
            and (array.rio.crs is not None)
            and (array.rio.transform() is not None)
        ):

            if "latitude" in array.dims and "longitude" in array.dims:
                array = array.rename({"latitude": "y", "longitude": "x"})
            elif "lat" in array.dims and "lon" in array.dims:
                array = array.rename({"lat": "y", "lon": "x"})

            if array.ndim == 2 and ("x" in array.dims) and ("y" in array.dims):
                array = array.transpose("y", "x")
            elif array.ndim == 3 and ("x" in array.dims) and ("y" in array.dims):
                dims = list(array.dims)
                dims.remove("x")
                dims.remove("y")
                array = array.transpose(dims[0], "y", "x")
            if "long_name" in array.attrs:
                array.attrs.pop("long_name")

            array.rio.to_raster(
                output, driver=driver, compress=compress, dtype=dtype, **kwargs
            )
            if colormap:
                write_image_colormap(output, colormap, output)
            return output

    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)

    ext = os.path.splitext(output)[-1].lower()
    if ext == "":
        output += ".tif"
        driver = "COG"
    elif ext == ".png":
        driver = "PNG"
    elif ext == ".jpg" or ext == ".jpeg":
        driver = "JPEG"
    elif ext == ".jp2":
        driver = "JP2OpenJPEG"
    elif ext == ".tiff":
        driver = "GTiff"
    else:
        driver = "COG"

    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 is None:
            # 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]
            )
        elif isinstance(transform, Affine):
            pass
        elif isinstance(transform, (tuple, list)):
            transform = Affine(*transform)

        kwargs["transform"] = 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 and (driver in ["GTiff", "COG"]):
        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)
            if colormap:
                dst.write_colormap(1, colormap)
        elif array.ndim == 3:
            for i in range(array.shape[2]):
                dst.write(array[:, :, i], i + 1)
                if colormap:
                    dst.write_colormap(i + 1, colormap)
    return output

array_to_memory_file(array, source=None, dtype=None, compress='deflate', transpose=True, cellsize=None, crs=None, transform=None, driver='COG', colormap=None, **kwargs)

Convert a NumPy array to a memory file.

Parameters:

Name	Type	Description	Default
array	ndarray	The input NumPy array.	required
source	str	Path to the source file to extract metadata from. Defaults to None.	None
dtype	str	The desired data type of the array. Defaults to None.	None
compress	str	The compression method for the output file. Defaults to "deflate".	'deflate'
transpose	bool	Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.	True
cellsize	float	The cell size of the array if source is not provided. Defaults to None.	None
crs	str	The coordinate reference system of the array if source is not provided. Defaults to None.	None
transform	tuple	The affine transformation matrix if source is not provided. Can be rio.transform() or a tuple like (0.5, 0.0, -180.25, 0.0, -0.5, 83.780361). Defaults to None.	None
driver	str	The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".	'COG'
colormap	dict	A dictionary defining the colormap (value: (R, G, B, A)).	None
**kwargs	Any	Additional keyword arguments to be passed to the rasterio.open() function.	{}

Returns:

Type	Description
Any	The rasterio dataset reader object for the converted array.

Source code in leafmap/common.py

def array_to_memory_file(
    array,
    source: str = None,
    dtype: str = None,
    compress: str = "deflate",
    transpose: bool = True,
    cellsize: float = None,
    crs: str = None,
    transform: tuple = None,
    driver="COG",
    colormap: dict = None,
    **kwargs: Any,
) -> Any:
    """Convert a NumPy array to a memory file.

    Args:
        array (numpy.ndarray): The input NumPy array.
        source (str, optional): Path to the source file to extract metadata from. Defaults to None.
        dtype (str, optional): The desired data type of the array. Defaults to None.
        compress (str, optional): The compression method for the output file. Defaults to "deflate".
        transpose (bool, optional): Whether to transpose the array from (bands, rows, columns) to (rows, columns, bands). Defaults to True.
        cellsize (float, optional): The cell size of the array if source is not provided. Defaults to None.
        crs (str, optional): The coordinate reference system of the array if source is not provided. Defaults to None.
        transform (tuple, optional): The affine transformation matrix if source is not provided.
            Can be rio.transform() or a tuple like (0.5, 0.0, -180.25, 0.0, -0.5, 83.780361). Defaults to None.
        driver (str, optional): The driver to use for creating the output file, such as 'GTiff'. Defaults to "COG".
        colormap (dict, optional): A dictionary defining the colormap (value: (R, G, B, A)).
        **kwargs (Any): Additional keyword arguments to be passed to the rasterio.open() function.

    Returns:
        The rasterio dataset reader object for the converted array.
    """
    import numpy as np
    import rasterio
    import xarray as xr
    from rasterio.transform import Affine

    if isinstance(array, xr.DataArray):
        coords = [coord for coord in array.coords]
        if coords[0] == "time":
            x_dim = coords[1]
            y_dim = coords[2]
            array = (
                array.isel(time=0).rename({y_dim: "y", x_dim: "x"}).transpose("y", "x")
            )
        if hasattr(array, "rio"):
            if hasattr(array.rio, "crs"):
                if array.rio.crs is not None:
                    crs = array.rio.crs
            if transform is None and hasattr(array.rio, "transform"):
                transform = array.rio.transform()
        elif source is None:
            if hasattr(array, "encoding"):
                if "source" in array.encoding:
                    source = array.encoding["source"]
        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 crs is None:
            raise ValueError(
                "crs must be provided if source is not provided, such as EPSG:3857"
            )

        if transform is None:
            if cellsize is None:
                raise ValueError("cellsize must be provided if source is not provided")
            # 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]
            )
        elif isinstance(transform, Affine):
            pass
        elif isinstance(transform, (tuple, list)):
            transform = Affine(*transform)

        kwargs["transform"] = 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)

    # Check and sanitize colormap
    fixed_colormap = {}

    if colormap is None:
        colormap = {}

    for k, v in colormap.items():
        if not isinstance(k, int):
            k = int(k)
        if len(v) == 3:  # RGB
            fixed_colormap[k] = tuple(int(c) for c in v)
        elif len(v) == 4:  # RGBA
            fixed_colormap[k] = tuple(
                int(c) for c in v[:3]
            )  # Drop alpha for compatibility
        else:
            raise ValueError(f"Invalid colormap value: {v}")

    if array.ndim == 2:
        dst.write(array, 1)
        if colormap:
            dst.write_colormap(1, fixed_colormap)
    elif array.ndim == 3:
        for i in range(array.shape[2]):
            dst.write(array[:, :, i], i + 1)
            if colormap:
                dst.write_colormap(i + 1, fixed_colormap)

    dst.close()
    # Read the dataset from memory
    dataset_reader = rasterio.open(dst.name, mode="r")

    return dataset_reader

assign_continuous_colors(df, column, cmap=None, colors=None, labels=None, scheme='Quantiles', k=5, legend_kwds=None, classification_kwds=None, to_rgb=True, return_type='array', return_legend=False)

Assigns continuous colors to a DataFrame column based on a specified scheme.

Parameters:

Name	Type	Description	Default
df	DataFrame	A pandas DataFrame.	required
column	str	The name of the column to assign colors.	required
cmap	str	The name of the colormap to use.	None
colors	list	A list of custom colors.	None
labels	list	A list of custom labels for the legend.	None
scheme	str	The scheme for classifying the data. Default is 'Quantiles'.	'Quantiles'
k	int	The number of classes for classification.	5
legend_kwds	dict	Additional keyword arguments for configuring the legend.	None
classification_kwds	dict	Additional keyword arguments for configuring the classification.	None
to_rgb	bool	Whether to convert colors to RGB values. Default is True.	True
return_type	str	The type of the returned values. Default is 'array'.	'array'
return_legend	bool	Whether to return the legend. Default is False.	False

Returns:

Type	Description
Union[ndarray, Tuple[ndarray, dict]]	The assigned colors as a numpy array or a tuple containing the colors and the legend, depending on the value of return_legend.

Source code in leafmap/common.py

def assign_continuous_colors(
    df,
    column: str,
    cmap: str = None,
    colors: list = None,
    labels: list = None,
    scheme: str = "Quantiles",
    k: int = 5,
    legend_kwds: dict = None,
    classification_kwds: dict = None,
    to_rgb: bool = True,
    return_type: str = "array",
    return_legend: bool = False,
) -> Union[np.ndarray, Tuple[np.ndarray, dict]]:
    """Assigns continuous colors to a DataFrame column based on a specified scheme.

    Args:
        df (pd.DataFrame): A pandas DataFrame.
        column: The name of the column to assign colors.
        cmap: The name of the colormap to use.
        colors: A list of custom colors.
        labels: A list of custom labels for the legend.
        scheme: The scheme for classifying the data. Default is 'Quantiles'.
        k: The number of classes for classification.
        legend_kwds: Additional keyword arguments for configuring the legend.
        classification_kwds: Additional keyword arguments for configuring the classification.
        to_rgb: Whether to convert colors to RGB values. Default is True.
        return_type: The type of the returned values. Default is 'array'.
        return_legend: Whether to return the legend. Default is False.

    Returns:
        The assigned colors as a numpy array or a tuple containing the colors and the legend, depending on the value of return_legend.
    """
    import numpy as np

    data = df[[column]].copy()
    new_df, legend = classify(
        data, column, cmap, colors, labels, scheme, k, legend_kwds, classification_kwds
    )
    values = new_df["color"].values.tolist()

    if to_rgb:
        values = [hex_to_rgb(check_color(color)) for color in values]
        if return_type == "array":
            values = np.array(values, dtype=np.uint8)

    if return_legend:
        return values, legend
    else:
        return values

assign_discrete_colors(df, column, cmap, to_rgb=True, return_type='array')

Assigns unique colors to each category in a categorical column of a dataframe.

Parameters:

Name	Type	Description	Default
df	DataFrame	The input dataframe.	required
column	str	The name of the categorical column.	required
cmap	dict	A dictionary mapping categories to colors.	required
to_rgb	bool	Whether to convert the colors to RGB values. Defaults to True.	True
return_type	str	The type of the returned values. Can be 'list' or 'array'. Defaults to 'array'.	'array'

Returns:

Type	Description
Union[List, ndarray]	A list of colors for each category in the categorical column.

Source code in leafmap/common.py

def assign_discrete_colors(
    df, column, cmap, to_rgb=True, return_type="array"
) -> Union[List, "np.ndarray"]:
    """
    Assigns unique colors to each category in a categorical column of a dataframe.

    Args:
        df (pandas.DataFrame): The input dataframe.
        column (str): The name of the categorical column.
        cmap (dict): A dictionary mapping categories to colors.
        to_rgb (bool): Whether to convert the colors to RGB values. Defaults to True.
        return_type (str): The type of the returned values. Can be 'list' or 'array'. Defaults to 'array'.

    Returns:
        A list of colors for each category in the categorical column.
    """
    import numpy as np

    # Copy the categorical column from the original dataframe
    category_column = df[column].copy()

    # Map colors to the categorical values
    category_column = category_column.map(cmap)

    values = category_column.values.tolist()

    if to_rgb:
        values = [hex_to_rgb(check_color(color)) for color in values]
        if return_type == "array":
            values = np.array(values, dtype=np.uint8)

    return values

bar_chart(data=None, x=None, y=None, color=None, descending=True, sort_column=None, max_rows=None, x_label=None, y_label=None, title=None, legend_title=None, width=None, height=500, layout_args={}, **kwargs)

Create a bar chart with plotly.express,

Parameters:

Name	Type	Description	Default
data		DataFrame | array-like | dict | str (local file path or HTTP URL) This argument needs to be passed for column names (and not keyword names) to be used. Array-like and dict are transformed internally to a pandas DataFrame. Optional: if missing, a DataFrame gets constructed under the hood using the other arguments.	None
x		str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to position marks along the x axis in cartesian coordinates. Either x or y can optionally be a list of column references or array_likes, in which case the data will be treated as if it were 'wide' rather than 'long'.	None
y		str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to position marks along the y axis in cartesian coordinates. Either x or y can optionally be a list of column references or array_likes, in which case the data will be treated as if it were 'wide' rather than 'long'.	None
color		str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign color to marks.	None
descending	bool	Whether to sort the data in descending order. Defaults to True.	True
sort_column	str	The column to sort the data. Defaults to None.	None
max_rows	int	Maximum number of rows to display. Defaults to None.	None
x_label	str	Label for the x axis. Defaults to None.	None
y_label	str	Label for the y axis. Defaults to None.	None
title	str	Title for the plot. Defaults to None.	None
legend_title	str	Title for the legend. Defaults to None.	None
width	int	Width of the plot in pixels. Defaults to None.	None
height	int	Height of the plot in pixels. Defaults to 500.	500
layout_args	dict	Layout arguments for the plot to be passed to fig.update_layout(), such as {'title':'Plot Title', 'title_x':0.5}. Defaults to None.	{}
**kwargs		Any additional arguments to pass to plotly.express.bar(), such as: pattern_shape: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign pattern shapes to marks. facet_row: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign marks to facetted subplots in the vertical direction. facet_col: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign marks to facetted subplots in the horizontal direction. facet_col_wrap: int Maximum number of facet columns. Wraps the column variable at this width, so that the column facets span multiple rows. Ignored if 0, and forced to 0 if facet_row or a marginal is set. facet_row_spacing: float between 0 and 1 Spacing between facet rows, in paper units. Default is 0.03 or 0.0.7 when facet_col_wrap is used. facet_col_spacing: float between 0 and 1 Spacing between facet columns, in paper units Default is 0.02. hover_name: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like appear in bold in the hover tooltip. hover_data: list of str or int, or Series or array-like, or dict Either a list of names of columns in data_frame, or pandas Series, or array_like objects or a dict with column names as keys, with values True (for default formatting) False (in order to remove this column from hover information), or a formatting string, for example ':.3f' or '|%a' or list-like data to appear in the hover tooltip or tuples with a bool or formatting string as first element, and list-like data to appear in hover as second element Values from these columns appear as extra data in the hover tooltip. custom_data: list of str or int, or Series or array-like Either names of columns in data_frame, or pandas Series, or array_like objects Values from these columns are extra data, to be used in widgets or Dash callbacks for example. This data is not user-visible but is included in events emitted by the figure (lasso selection etc.) text: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like appear in the figure as text labels. base: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to position the base of the bar. error_x: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size x-axis error bars. If error_x_minus is None, error bars will be symmetrical, otherwise error_x is used for the positive direction only. error_x_minus: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size x-axis error bars in the negative direction. Ignored if error_x is None. error_y: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size y-axis error bars. If error_y_minus is None, error bars will be symmetrical, otherwise error_y is used for the positive direction only. error_y_minus: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to size y-axis error bars in the negative direction. Ignored if error_y is None. animation_frame: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to assign marks to animation frames. animation_group: str or int or Series or array-like Either a name of a column in data_frame, or a pandas Series or array_like object. Values from this column or array_like are used to provide object-constancy across animation frames: rows with matching animation_groups will be treated as if they describe the same object in each frame. category_orders: dict with str keys and list of str values (default {}) By default, in Python 3.6+, the order of categorical values in axes, legends and facets depends on the order in which these values are first encountered in data_frame (and no order is guaranteed by default in Python below 3.6). This parameter is used to force a specific ordering of values per column. The keys of this dict should correspond to column names, and the values should be lists of strings corresponding to the specific display order desired. labels: dict with str keys and str values (default {}) By default, column names are used in the figure for axis titles, legend entries and hovers. This parameter allows this to be overridden. The keys of this dict should correspond to column names, and the values should correspond to the desired label to be displayed. color_discrete_sequence: list of str Strings should define valid CSS-colors. When color is set and the values in the corresponding column are not numeric, values in that column are assigned colors by cycling through color_discrete_sequence in the order described in category_orders, unless the value of color is a key in color_discrete_map. Various useful color sequences are available in the plotly.express.colors submodules, specifically plotly.express.colors.qualitative. color_discrete_map: dict with str keys and str values (default {}) String values should define valid CSS-colors Used to override color_discrete_sequence to assign a specific colors to marks corresponding with specific values. Keys in color_discrete_map should be values in the column denoted by color. Alternatively, if the values of color are valid colors, the string 'identity' may be passed to cause them to be used directly. color_continuous_scale: list of str Strings should define valid CSS-colors This list is used to build a continuous color scale when the column denoted by color contains numeric data. Various useful color scales are available in the plotly.express.colors submodules, specifically plotly.express.colors.sequential, plotly.express.colors.diverging and plotly.express.colors.cyclical. pattern_shape_sequence: list of str Strings should define valid plotly.js patterns-shapes. When pattern_shape is set, values in that column are assigned patterns- shapes by cycling through pattern_shape_sequence in the order described in category_orders, unless the value of pattern_shape is a key in pattern_shape_map. pattern_shape_map: dict with str keys and str values (default {}) Strings values define plotly.js patterns-shapes. Used to override pattern_shape_sequences to assign a specific patterns-shapes to lines corresponding with specific values. Keys in pattern_shape_map should be values in the column denoted by pattern_shape. Alternatively, if the values of pattern_shape are valid patterns-shapes names, the string 'identity' may be passed to cause them to be used directly. range_color: list of two numbers If provided, overrides auto-scaling on the continuous color scale. color_continuous_midpoint: number (default None) If set, computes the bounds of the continuous color scale to have the desired midpoint. Setting this value is recommended when using plotly.express.colors.diverging color scales as the inputs to color_continuous_scale. opacity: float Value between 0 and 1. Sets the opacity for markers. orientation: str, one of 'h' for horizontal or 'v' for vertical. (default 'v' if x and y are provided and both continuous or both categorical, otherwise 'v'('h') if x(y) is categorical and y(x) is continuous, otherwise 'v'('h') if only x(y) is provided) barmode: str (default 'relative') One of 'group', 'overlay' or 'relative' In 'relative' mode, bars are stacked above zero for positive values and below zero for negative values. In 'overlay' mode, bars are drawn on top of one another. In 'group' mode, bars are placed beside each other. log_x: boolean (default False) If True, the x-axis is log-scaled in cartesian coordinates. log_y: boolean (default False) If True, the y-axis is log-scaled in cartesian coordinates. range_x: list of two numbers If provided, overrides auto-scaling on the x-axis in cartesian coordinates. range_y: list of two numbers If provided, overrides auto-scaling on the y-axis in cartesian coordinates. text_auto: bool or string (default False) If True or a string, the x or y or z values will be displayed as text, depending on the orientation A string like '.2f' will be interpreted as a texttemplate numeric formatting directive. template: str or dict or plotly.graph_objects.layout.Template instance The figure template name (must be a key in plotly.io.templates) or definition.	{}

Returns:

Type	Description
	plotly.graph_objs._figure.Figure: A plotly figure object.

Source code in leafmap/plot.py

def bar_chart(
    data=None,
    x=None,
    y=None,
    color=None,
    descending=True,
    sort_column=None,
    max_rows=None,
    x_label=None,
    y_label=None,
    title=None,
    legend_title=None,
    width=None,
    height=500,
    layout_args={},
    **kwargs,
):
    """Create a bar chart with plotly.express,

    Args:
        data: DataFrame | array-like | dict | str (local file path or HTTP URL)
            This argument needs to be passed for column names (and not keyword
            names) to be used. Array-like and dict are transformed internally to a
            pandas DataFrame. Optional: if missing, a DataFrame gets constructed
            under the hood using the other arguments.
        x: str or int or Series or array-like
            Either a name of a column in `data_frame`, or a pandas Series or
            array_like object. Values from this column or array_like are used to
            position marks along the x axis in cartesian coordinates. Either `x` or
            `y` can optionally be a list of column references or array_likes,  in
            which case the data will be treated as if it were 'wide' rather than
            'long'.
        y: str or int or Series or array-like
            Either a name of a column in `data_frame`, or a pandas Series or
            array_like object. Values from this column or array_like are used to
            position marks along the y axis in cartesian coordinates. Either `x` or
            `y` can optionally be a list of column references or array_likes,  in
            which case the data will be treated as if it were 'wide' rather than
            'long'.
        color: str or int or Series or array-like
            Either a name of a column in `data_frame`, or a pandas Series or
            array_like object. Values from this column or array_like are used to
            assign color to marks.
        descending (bool, optional): Whether to sort the data in descending order. Defaults to True.
        sort_column (str, optional): The column to sort the data. Defaults to None.
        max_rows (int, optional): Maximum number of rows to display. Defaults to None.
        x_label (str, optional): Label for the x axis. Defaults to None.
        y_label (str, optional): Label for the y axis. Defaults to None.
        title (str, optional): Title for the plot. Defaults to None.
        legend_title (str, optional): Title for the legend. Defaults to None.
        width (int, optional): Width of the plot in pixels. Defaults to None.
        height (int, optional): Height of the plot in pixels. Defaults to 500.
        layout_args (dict, optional): Layout arguments for the plot to be passed to fig.update_layout(),
            such as {'title':'Plot Title', 'title_x':0.5}. Defaults to None.
        **kwargs: Any additional arguments to pass to plotly.express.bar(), such as:

            pattern_shape: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign pattern shapes to marks.
            facet_row: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign marks to facetted subplots in the vertical direction.
            facet_col: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign marks to facetted subplots in the horizontal direction.
            facet_col_wrap: int
                Maximum number of facet columns. Wraps the column variable at this
                width, so that the column facets span multiple rows. Ignored if 0, and
                forced to 0 if `facet_row` or a `marginal` is set.
            facet_row_spacing: float between 0 and 1
                Spacing between facet rows, in paper units. Default is 0.03 or 0.0.7
                when facet_col_wrap is used.
            facet_col_spacing: float between 0 and 1
                Spacing between facet columns, in paper units Default is 0.02.
            hover_name: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like appear in bold
                in the hover tooltip.
            hover_data: list of str or int, or Series or array-like, or dict
                Either a list of names of columns in `data_frame`, or pandas Series, or
                array_like objects or a dict with column names as keys, with values
                True (for default formatting) False (in order to remove this column
                from hover information), or a formatting string, for example ':.3f' or
                '|%a' or list-like data to appear in the hover tooltip or tuples with a
                bool or formatting string as first element, and list-like data to
                appear in hover as second element Values from these columns appear as
                extra data in the hover tooltip.
            custom_data: list of str or int, or Series or array-like
                Either names of columns in `data_frame`, or pandas Series, or
                array_like objects Values from these columns are extra data, to be used
                in widgets or Dash callbacks for example. This data is not user-visible
                but is included in events emitted by the figure (lasso selection etc.)
            text: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like appear in the
                figure as text labels.
            base: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                position the base of the bar.
            error_x: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size x-axis error bars. If `error_x_minus` is `None`, error bars will
                be symmetrical, otherwise `error_x` is used for the positive direction
                only.
            error_x_minus: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size x-axis error bars in the negative direction. Ignored if `error_x`
                is `None`.
            error_y: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size y-axis error bars. If `error_y_minus` is `None`, error bars will
                be symmetrical, otherwise `error_y` is used for the positive direction
                only.
            error_y_minus: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                size y-axis error bars in the negative direction. Ignored if `error_y`
                is `None`.
            animation_frame: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                assign marks to animation frames.
            animation_group: str or int or Series or array-like
                Either a name of a column in `data_frame`, or a pandas Series or
                array_like object. Values from this column or array_like are used to
                provide object-constancy across animation frames: rows with matching
                `animation_group`s will be treated as if they describe the same object
                in each frame.
            category_orders: dict with str keys and list of str values (default `{}`)
                By default, in Python 3.6+, the order of categorical values in axes,
                legends and facets depends on the order in which these values are first
                encountered in `data_frame` (and no order is guaranteed by default in
                Python below 3.6). This parameter is used to force a specific ordering
                of values per column. The keys of this dict should correspond to column
                names, and the values should be lists of strings corresponding to the
                specific display order desired.
            labels: dict with str keys and str values (default `{}`)
                By default, column names are used in the figure for axis titles, legend
                entries and hovers. This parameter allows this to be overridden. The
                keys of this dict should correspond to column names, and the values
                should correspond to the desired label to be displayed.
            color_discrete_sequence: list of str
                Strings should define valid CSS-colors. When `color` is set and the
                values in the corresponding column are not numeric, values in that
                column are assigned colors by cycling through `color_discrete_sequence`
                in the order described in `category_orders`, unless the value of
                `color` is a key in `color_discrete_map`. Various useful color
                sequences are available in the `plotly.express.colors` submodules,
                specifically `plotly.express.colors.qualitative`.
            color_discrete_map: dict with str keys and str values (default `{}`)
                String values should define valid CSS-colors Used to override
                `color_discrete_sequence` to assign a specific colors to marks
                corresponding with specific values. Keys in `color_discrete_map` should
                be values in the column denoted by `color`. Alternatively, if the
                values of `color` are valid colors, the string `'identity'` may be
                passed to cause them to be used directly.
            color_continuous_scale: list of str
                Strings should define valid CSS-colors This list is used to build a
                continuous color scale when the column denoted by `color` contains
                numeric data. Various useful color scales are available in the
                `plotly.express.colors` submodules, specifically
                `plotly.express.colors.sequential`, `plotly.express.colors.diverging`
                and `plotly.express.colors.cyclical`.
            pattern_shape_sequence: list of str
                Strings should define valid plotly.js patterns-shapes. When
                `pattern_shape` is set, values in that column are assigned patterns-
                shapes by cycling through `pattern_shape_sequence` in the order
                described in `category_orders`, unless the value of `pattern_shape` is
                a key in `pattern_shape_map`.
            pattern_shape_map: dict with str keys and str values (default `{}`)
                Strings values define plotly.js patterns-shapes. Used to override
                `pattern_shape_sequences` to assign a specific patterns-shapes to lines
                corresponding with specific values. Keys in `pattern_shape_map` should
                be values in the column denoted by `pattern_shape`. Alternatively, if
                the values of `pattern_shape` are valid patterns-shapes names, the
                string `'identity'` may be passed to cause them to be used directly.
            range_color: list of two numbers
                If provided, overrides auto-scaling on the continuous color scale.
            color_continuous_midpoint: number (default `None`)
                If set, computes the bounds of the continuous color scale to have the
                desired midpoint. Setting this value is recommended when using
                `plotly.express.colors.diverging` color scales as the inputs to
                `color_continuous_scale`.
            opacity: float
                Value between 0 and 1. Sets the opacity for markers.
            orientation: str, one of `'h'` for horizontal or `'v'` for vertical.
                (default `'v'` if `x` and `y` are provided and both continuous or both
                categorical,  otherwise `'v'`(`'h'`) if `x`(`y`) is categorical and
                `y`(`x`) is continuous,  otherwise `'v'`(`'h'`) if only `x`(`y`) is
                provided)
            barmode: str (default `'relative'`)
                One of `'group'`, `'overlay'` or `'relative'` In `'relative'` mode,
                bars are stacked above zero for positive values and below zero for
                negative values. In `'overlay'` mode, bars are drawn on top of one
                another. In `'group'` mode, bars are placed beside each other.
            log_x: boolean (default `False`)
                If `True`, the x-axis is log-scaled in cartesian coordinates.
            log_y: boolean (default `False`)
                If `True`, the y-axis is log-scaled in cartesian coordinates.
            range_x: list of two numbers
                If provided, overrides auto-scaling on the x-axis in cartesian
                coordinates.
            range_y: list of two numbers
                If provided, overrides auto-scaling on the y-axis in cartesian
                coordinates.
            text_auto: bool or string (default `False`)
                If `True` or a string, the x or y or z values will be displayed as
                text, depending on the orientation A string like `'.2f'` will be
                interpreted as a `texttemplate` numeric formatting directive.
            template: str or dict or plotly.graph_objects.layout.Template instance
                The figure template name (must be a key in plotly.io.templates) or
                definition.


    Returns:
        plotly.graph_objs._figure.Figure: A plotly figure object.
    """

    if isinstance(data, str):
        if data.startswith("http"):
            data = github_raw_url(data)
            data = get_direct_url(data)

        try:
            data = pd.read_csv(data)
        except Exception as e:
            raise ValueError(f"Could not read data from {data}. {e}")

    if not isinstance(data, pd.DataFrame):
        raise ValueError(
            "data must be a pandas DataFrame, a string or an ee.FeatureCollection."
        )

    if descending is not None:
        if sort_column is None:
            if isinstance(y, str):
                sort_column = y
            elif isinstance(y, list):
                sort_column = y[0]
        data.sort_values([sort_column, x], ascending=not (descending), inplace=True)
        if "barmode" not in kwargs:
            kwargs["barmode"] = "group"

    if isinstance(max_rows, int):
        data = data.head(max_rows)

    if "labels" in kwargs:
        labels = kwargs["labels"]
        kwargs.pop("labels")
    else:
        labels = {}

    if x_label is not None:
        labels[x] = x_label
    if y_label is not None:
        if isinstance(y, str):
            labels[y] = y_label
        elif isinstance(y, list):
            labels[y[0]] = y_label

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

    try:
        fig = px.bar(
            data,
            x=x,
            y=y,
            color=color,
            labels=labels,
            title=title,
            width=width,
            height=height,
            **kwargs,
        )

        if isinstance(layout_args, dict):
            fig.update_layout(**layout_args)

        return fig
    except Exception as e:
        raise ValueError(f"Could not create bar plot. {e}")

basemap_xyz_tiles()

Returns a dictionary containing a set of basemaps that are XYZ tile layers.

Returns:

Type	Description
Dict[str, Any]	A dictionary of XYZ tile layers.

Source code in leafmap/common.py

def basemap_xyz_tiles() -> Dict[str, Any]:
    """Returns a dictionary containing a set of basemaps that are XYZ tile layers.

    Returns:
        A dictionary of XYZ tile layers.
    """
    from .leafmap import basemaps

    layers_dict = {}
    keys = dict(basemaps).keys()
    for key in keys:
        if isinstance(basemaps[key], ipyleaflet.WMSLayer):
            pass
        else:
            layers_dict[key] = basemaps[key]
    return layers_dict

bbox_to_gdf(bbox, crs='epsg:4326')

Convert a bounding box to a GeoPandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
bbox	list	A bounding box in the format of [minx, miny, maxx, maxy].	required
crs	str	The CRS of the bounding box. Defaults to 'epsg:4326'.	'epsg:4326'

Returns:

Type	Description
GeoDataFrame	A GeoDataFrame with a single polygon.

Source code in leafmap/common.py

def bbox_to_gdf(bbox, crs="epsg:4326") -> "gpd.GeoDataFrame":
    """Convert a bounding box to a GeoPandas GeoDataFrame.

    Args:
        bbox (list): A bounding box in the format of [minx, miny, maxx, maxy].
        crs (str, optional): The CRS of the bounding box. Defaults to 'epsg:4326'.

    Returns:
        A GeoDataFrame with a single polygon.
    """
    import geopandas as gpd
    from shapely.geometry import Polygon

    return gpd.GeoDataFrame(
        geometry=[Polygon.from_bounds(*bbox)],
        crs=crs,
    )

bbox_to_geojson(bounds)

Convert coordinates of a bounding box to a geojson.

Parameters:

Name	Type	Description	Default
bounds	list | tuple	A list of coordinates representing [left, bottom, right, top] or m.bounds.	required

Returns:

Type	Description
dict	A geojson feature.

Source code in leafmap/common.py

def bbox_to_geojson(bounds) -> dict:
    """Convert coordinates of a bounding box to a geojson.

    Args:
        bounds (list | tuple): A list of coordinates representing [left, bottom, right, top] or m.bounds.

    Returns:
        A geojson feature.
    """

    if isinstance(bounds, tuple) and len(bounds) == 2:
        bounds = [bounds[0][1], bounds[0][0], bounds[1][1], bounds[1][0]]

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

bbox_to_polygon(bbox)

Convert a bounding box to a shapely Polygon.

Parameters:

Name	Type	Description	Default
bbox	list	A bounding box in the format of [minx, miny, maxx, maxy].	required

Returns:

Type	Description
Any	A shapely Polygon.

Source code in leafmap/common.py

def bbox_to_polygon(bbox) -> Any:
    """Convert a bounding box to a shapely Polygon.

    Args:
        bbox (list): A bounding box in the format of [minx, miny, maxx, maxy].

    Returns:
        A shapely Polygon.
    """
    from shapely.geometry import Polygon

    return Polygon.from_bounds(*bbox)

blend_images(img1, img2, alpha=0.5, output=False, show=True, figsize=(12, 10), axis='off', **kwargs)

Blends two images together using the addWeighted function from the OpenCV library.

Parameters:

Name	Type	Description	Default
img1	ndarray	The first input image on top represented as a NumPy array.	required
img2	ndarray	The second input image at the bottom represented as a NumPy array.	required
alpha	float	The weighting factor for the first image in the blend. By default, this is set to 0.5.	0.5
output	str	The path to the output image. Defaults to False.	False
show	bool	Whether to display the blended image. Defaults to True.	True
figsize	tuple	The size of the figure. Defaults to (12, 10).	(12, 10)
axis	str	The axis of the figure. Defaults to "off".	'off'
**kwargs	Any	Additional keyword arguments to pass to the cv2.addWeighted() function.	{}

Returns:

Type	Description
Any	The blended image as a NumPy array.

Source code in leafmap/common.py

def blend_images(
    img1,
    img2,
    alpha=0.5,
    output=False,
    show=True,
    figsize=(12, 10),
    axis="off",
    **kwargs: Any,
) -> Any:
    """
    Blends two images together using the addWeighted function from the OpenCV library.

    Args:
        img1 (numpy.ndarray): The first input image on top represented as a NumPy array.
        img2 (numpy.ndarray): The second input image at the bottom represented as a NumPy array.
        alpha (float): The weighting factor for the first image in the blend. By default, this is set to 0.5.
        output (str, optional): The path to the output image. Defaults to False.
        show (bool, optional): Whether to display the blended image. Defaults to True.
        figsize (tuple, optional): The size of the figure. Defaults to (12, 10).
        axis (str, optional): The axis of the figure. Defaults to "off".
        **kwargs (Any): Additional keyword arguments to pass to the cv2.addWeighted() function.

    Returns:
        The blended image as a NumPy array.
    """
    import matplotlib.pyplot as plt
    import numpy as np

    try:
        import cv2
    except ImportError:
        raise ImportError("The blend_images function requires the OpenCV library.")

    # Resize the images to have the same dimensions
    if isinstance(img1, str):
        if img1.startswith("http"):
            img1 = download_file(img1)

        if not os.path.exists(img1):
            raise ValueError(f"Input path {img1} does not exist.")

        img1 = cv2.imread(img1)

    if isinstance(img2, str):
        if img2.startswith("http"):
            img2 = download_file(img2)

        if not os.path.exists(img2):
            raise ValueError(f"Input path {img2} does not exist.")

        img2 = cv2.imread(img2)

    if img1.dtype == np.float32:
        img1 = (img1 * 255).astype(np.uint8)

    if img2.dtype == np.float32:
        img2 = (img2 * 255).astype(np.uint8)

    if img1.dtype != img2.dtype:
        img2 = img2.astype(img1.dtype)

    img1 = cv2.resize(img1, (img2.shape[1], img2.shape[0]))

    # Blend the images using the addWeighted function
    beta = 1 - alpha
    blend_img = cv2.addWeighted(img1, alpha, img2, beta, 0, **kwargs)

    if output:
        array_to_image(blend_img, output, img2)

    if show:
        plt.figure(figsize=figsize)
        plt.imshow(blend_img)
        plt.axis(axis)
        plt.show()
    else:
        return blend_img

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	Union[List[Union[Tuple[float, float], float]], Tuple[float, float, float, float]]	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]]	Tuple[Tuple[float, float], Tuple[float, float]]: A tuple of (x_range, y_range).

Source code in leafmap/common.py

def bounds_to_xy_range(
    bounds: Union[
        List[Union[Tuple[float, float], float]], Tuple[float, float, float, float]
    ],
) -> Tuple[Tuple[float, float], Tuple[float, float]]:
    """
    Convert bounds to x and y range to be used as input to bokeh map.

    Args:
        bounds (Union[List[Union[Tuple[float, float], float]], Tuple[float, float, float, float]]):
            A list of bounds in the form [(south, west), (north, east)] or [xmin, ymin, xmax, ymax].

    Returns:
        Tuple[Tuple[float, float], Tuple[float, float]]: A tuple of (x_range, y_range).
    """
    if isinstance(bounds, tuple):
        if len(bounds) != 4:
            raise ValueError(
                "Tuple bounds must have exactly 4 elements (xmin, ymin, xmax, ymax)."
            )
        west, south, east, north = bounds
    elif isinstance(bounds, list):
        if len(bounds) == 2 and all(
            isinstance(coord, tuple) and len(coord) == 2 for coord in bounds
        ):
            (south, west), (north, east) = bounds
        elif len(bounds) == 4 and all(
            isinstance(coord, (int, float)) for coord in bounds
        ):
            west, south, east, north = bounds
        else:
            raise ValueError(
                "List bounds must be in the form [(south, west), (north, east)] or [xmin, ymin, xmax, ymax]."
            )
    else:
        raise TypeError("bounds must be a list or tuple")

    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

center_zoom_to_xy_range(center, zoom)

Convert center and zoom to x and y range to be used as input to bokeh map.

Parameters:

Name	Type	Description	Default
center	tuple	A tuple of (latitude, longitude).	required
zoom	int	The zoom level.	required

Returns:

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

Source code in leafmap/common.py

def center_zoom_to_xy_range(
    center, zoom
) -> 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 (tuple): A tuple of (latitude, longitude).
        zoom (int): The zoom level.

    Returns:
        A tuple of (x_range, y_range).
    """

    if isinstance(center, tuple) or isinstance(center, list):
        pass
    else:
        raise TypeError("center must be a tuple or list")

    if not isinstance(zoom, int):
        raise TypeError("zoom must be an integer")

    latitude, longitude = center
    x_range = (-179, 179)
    y_range = (-70, 70)
    x_full_length = x_range[1] - x_range[0]
    y_full_length = y_range[1] - y_range[0]

    x_length = x_full_length / 2 ** (zoom - 2)
    y_length = y_full_length / 2 ** (zoom - 2)

    south = latitude - y_length / 2
    north = latitude + y_length / 2
    west = longitude - x_length / 2
    east = longitude + x_length / 2

    xmin, ymin = lnglat_to_meters(west, south)
    xmax, ymax = lnglat_to_meters(east, north)

    x_range = (xmin, xmax)
    y_range = (ymin, ymax)

    return x_range, y_range

cesium_to_streamlit(html, width=800, height=600, responsive=True, scrolling=False, token_name=None, token_value=None, **kwargs)

Renders an cesium HTML file 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
html	str	The HTML file to render. It can a local file path or a URL.	required
width	int	Width of the map. Defaults to 800.	800
height	int	Height of the map. Defaults to 600.	600
responsive	bool	Whether to make the map responsive. Defaults to True.	True
scrolling	bool	Whether to allow the map to scroll. Defaults to False.	False
token_name	str	The name of the token in the HTML file to be replaced. Defaults to None.	None
token_value	str	The value of the token to pass to the HTML file. Defaults to None.	None

Returns:

Type	Description
Any	A Streamlit components.html object.

Source code in leafmap/common.py

def cesium_to_streamlit(
    html,
    width=800,
    height=600,
    responsive=True,
    scrolling=False,
    token_name=None,
    token_value=None,
    **kwargs: Any,
) -> Any:
    """Renders an cesium HTML file in a Streamlit app. This method is a static Streamlit Component, meaning, no information is passed back from Leaflet on browser interaction.

    Args:
        html (str): The HTML file to render. It can a local file path or a URL.
        width (int, optional): Width of the map. Defaults to 800.
        height (int, optional): Height of the map. Defaults to 600.
        responsive (bool, optional): Whether to make the map responsive. Defaults to True.
        scrolling (bool, optional): Whether to allow the map to scroll. Defaults to False.
        token_name (str, optional): The name of the token in the HTML file to be replaced. Defaults to None.
        token_value (str, optional): The value of the token to pass to the HTML file. Defaults to None.

    Returns:
        A Streamlit components.html object.
    """
    if token_name is None:
        token_name = "your_access_token"

    if token_value is None:
        token_value = os.environ.get("CESIUM_TOKEN")

    html_to_streamlit(
        html, width, height, responsive, scrolling, token_name, token_value
    )

check_cmap(cmap)

Check the colormap and return a list of colors.

Parameters:

Name	Type	Description	Default
cmap	str | list | Box	The colormap to check.	required

Returns:

Type	Description
List[str]	A list of colors.

Source code in leafmap/common.py

def check_cmap(cmap) -> List[str]:
    """Check the colormap and return a list of colors.

    Args:
        cmap (str | list | Box): The colormap to check.

    Returns:
        A list of colors.
    """

    from box import Box

    from .colormaps import get_palette

    if isinstance(cmap, str):
        try:
            return get_palette(cmap)
        except Exception as e:
            raise Exception(f"{cmap} is not a valid colormap.")
    elif isinstance(cmap, Box):
        return list(cmap["default"])
    elif isinstance(cmap, list) or isinstance(cmap, tuple):
        return cmap
    else:
        raise Exception(f"{cmap} is not a valid colormap.")

check_color(in_color)

Checks the input color and returns the corresponding hex color code.

Parameters:

Name	Type	Description	Default
in_color	str or tuple or list	It can be a string (e.g., 'red', '#ffff00', 'ffff00', 'ff0') or RGB tuple/list (e.g., (255, 127, 0)).	required

Returns:

Type	Description
str	A hex color code.

Source code in leafmap/common.py

def check_color(in_color: Union[str, Tuple, List]) -> str:
    """Checks the input color and returns the corresponding hex color code.

    Args:
        in_color (str or tuple or list): It can be a string (e.g., 'red', '#ffff00', 'ffff00', 'ff0') or RGB tuple/list (e.g., (255, 127, 0)).

    Returns:
        A hex color code.
    """
    from matplotlib import colors

    out_color = "#000000"  # default black color
    # Handle RGB tuple or list
    if isinstance(in_color, (tuple, list)) and len(in_color) == 3:
        # rescale color if necessary
        if all(isinstance(item, int) for item in in_color):
            # Ensure values are floats between 0 and 1 for to_hex
            in_color = [c / 255.0 for c in in_color]
        try:
            return colors.to_hex(in_color)
        except ValueError:
            print(
                f"The provided RGB color ({in_color}) is invalid. Using the default black color."
            )
            return out_color

    # Handle string color input
    elif isinstance(in_color, str):
        if in_color.startswith("rgba"):
            return in_color
        try:
            # Try converting directly (handles color names and hex with #)
            return colors.to_hex(in_color)
        except ValueError:
            try:
                # Try again by adding an extra # (handles hex without #)
                return colors.to_hex(f"#{in_color}")
            except ValueError:
                print(
                    f"The provided color string ({in_color}) is invalid. Using the default black color."
                )
                return out_color
    else:
        print(
            f"The provided color type ({type(in_color)}) is invalid. Using the default black color."
        )
        return out_color

check_dir(dir_path, make_dirs=True)

Checks if a directory exists and creates it if it does not.

Parameters:

Name	Type	Description	Default
dir_path	[str	The path to the directory.	required
make_dirs	bool	Whether to create the directory if it does not exist. Defaults to True.	True

Raises:

Type	Description
FileNotFoundError	If the directory could not be found.
TypeError	If the input directory path is not a string.

Returns:

Type	Description
str	The path to the directory.

Source code in leafmap/common.py

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

    Args:
        dir_path ([str): The path to the directory.
        make_dirs (bool, optional): Whether to create the directory if it does not exist. Defaults to True.

    Raises:
        FileNotFoundError: If the directory could not be found.
        TypeError: If the input directory path is not a string.

    Returns:
        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 leafmap/common.py

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

    Args:
        file_path (str): The path to the file.
        make_dirs (bool, optional): Whether to create the directory if it does not exist. Defaults to True.

    Raises:
        FileNotFoundError: If the directory could not be found.
        TypeError: If the input directory path is not a string.

    Returns:
        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_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:

Type	Description
str	The HTML string with local images converted to base64.

Source code in leafmap/common.py

def check_html_string(html_string) -> str:
    """Check if an HTML string contains local images and convert them to base64.

    Args:
        html_string (str): The HTML string.

    Returns:
        The HTML string with local images converted to base64.
    """
    import base64
    import re

    # Search for img tags with src attribute
    img_regex = r'<img[^>]+src\s*=\s*["\']([^"\':]+)["\'][^>]*>'

    for match in re.findall(img_regex, html_string):
        with open(match, "rb") as img_file:
            img_data = img_file.read()
            base64_data = base64.b64encode(img_data).decode("utf-8")
            html_string = html_string.replace(
                'src="{}"'.format(match),
                'src="data:image/png;base64,' + base64_data + '"',
            )

    return html_string

check_titiler_endpoint(titiler_endpoint=None)

Returns the default titiler endpoint.

Returns:

Type	Description
Any	The titiler endpoint.

Source code in leafmap/stac.py

def check_titiler_endpoint(titiler_endpoint: Optional[str] = None) -> Any:
    """Returns the default titiler endpoint.

    Returns:
        The titiler endpoint.
    """
    if titiler_endpoint is not None and titiler_endpoint.lower() == "local":
        titiler_endpoint = run_titiler(show_logs=False)
    elif titiler_endpoint is None:
        if os.environ.get("TITILER_ENDPOINT") is not None:
            titiler_endpoint = os.environ.get("TITILER_ENDPOINT")

            if titiler_endpoint == "planetary-computer":
                titiler_endpoint = PlanetaryComputerEndpoint()
        else:
            titiler_endpoint = "https://giswqs-titiler-endpoint.hf.space"
    elif titiler_endpoint in ["planetary-computer", "pc"]:
        titiler_endpoint = PlanetaryComputerEndpoint()

    return titiler_endpoint

check_url(url)

Check if an HTTP URL is working.

Parameters:

Name	Type	Description	Default
url	str	The URL to check.	required

Returns:

Type	Description
bool	True if the URL is working (returns a 200 status code), False otherwise.

Source code in leafmap/common.py

def check_url(url: str) -> bool:
    """Check if an HTTP URL is working.

    Args:
        url (str): The URL to check.

    Returns:
        True if the URL is working (returns a 200 status code), False otherwise.
    """
    try:
        response = requests.get(url)
        if response.status_code == 200:
            return True
        else:
            return False
    except requests.exceptions.RequestException:
        return False

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
Tuple[Any, Dict[str, Any]]	A pandas dataframe with the classification applied and a legend dictionary.

Source code in leafmap/common.py

def classify(
    data,
    column,
    cmap=None,
    colors=None,
    labels=None,
    scheme="Quantiles",
    k=5,
    legend_kwds=None,
    classification_kwds=None,
) -> Tuple[Any, Dict[str, Any]]:
    """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:
        A pandas dataframe with the classification applied and a legend dictionary.
    """

    import geopandas as gpd
    import matplotlib as mpl
    import matplotlib.pyplot as plt
    import numpy as np
    import pandas as pd

    try:
        import mapclassify
    except ImportError:
        raise ImportError(
            "mapclassify is required for this function. Install with `pip install mapclassify`."
        )

    if (
        isinstance(data, gpd.GeoDataFrame)
        or isinstance(data, pd.DataFrame)
        or isinstance(data, pd.Series)
    ):
        # copy user provided data to avoid pandas SettingWithCopy warnings
        df = data.copy()
    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.object_):
        value_list = df[column].unique().tolist()
        value_list.sort()
        df["category"] = df[column].replace(value_list, range(0, len(value_list)))
        init_column = column
        column = "category"
        k = len(value_list)

    if legend_kwds is not None:
        legend_kwds = legend_kwds.copy()

    # To accept pd.Series and np.arrays as column
    if isinstance(column, (np.ndarray, pd.Series)):
        if column.shape[0] != df.shape[0]:
            raise ValueError(
                "The dataframe and given column have different number of rows."
            )
        else:
            values = column

            # Make sure index of a Series matches index of df
            if isinstance(values, pd.Series):
                values = values.reindex(df.index)
    else:
        values = df[column]

    values = df[column]
    nan_idx = np.asarray(pd.isna(values), dtype="bool")

    if cmap is None:
        cmap = "Blues"
    try:
        cmap = plt.get_cmap(cmap, k)
    except:
        cmap = plt.cm.get_cmap(cmap, k)
    if colors is None:
        colors = [mpl.colors.rgb2hex(cmap(i))[1:] for i in range(cmap.N)]
        colors = ["#" + i for i in colors]
    elif isinstance(colors, list):
        colors = [check_color(i) for i in colors]
    elif isinstance(colors, str):
        colors = [check_color(colors)] * k

    allowed_schemes = [
        "BoxPlot",
        "EqualInterval",
        "FisherJenks",
        "FisherJenksSampled",
        "HeadTailBreaks",
        "JenksCaspall",
        "JenksCaspallForced",
        "JenksCaspallSampled",
        "MaxP",
        "MaximumBreaks",
        "NaturalBreaks",
        "Quantiles",
        "Percentiles",
        "StdMean",
        "UserDefined",
    ]

    if scheme.lower() not in [s.lower() for s in allowed_schemes]:
        raise ValueError(
            f"{scheme} is not a valid scheme. It must be one of {allowed_schemes}."
        )

    if classification_kwds is None:
        classification_kwds = {}
    if "k" not in classification_kwds:
        classification_kwds["k"] = k

    binning = mapclassify.classify(
        np.asarray(values[~nan_idx]), scheme, **classification_kwds
    )
    df["category"] = np.nan
    df.loc[~nan_idx, "category"] = binning.yb
    df["color"] = None
    df.loc[~nan_idx, "color"] = [colors[int(i)] for i in df.loc[~nan_idx, "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.loc[~nan_idx, "category"] = df.loc[~nan_idx, "category"] + 1
    return df, legend_dict

clip_image(image, mask, output, to_cog=True)

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
to_cog	bool	Flags to indicate if you want to convert the output to COG. Defaults to True.	True

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 leafmap/common.py

def clip_image(image, mask, output, to_cog=True):
    """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.
        to_cog (bool, optional): Flags to indicate if you want to convert the output to COG. Defaults to True.

    Raises:
        ImportError: If the fiona or rasterio package is not installed.
        FileNotFoundError: If the image is not found.
        ValueError: If the mask is not a valid GeoJSON or raster file.
        FileNotFoundError: If the mask file is not found.
    """
    try:
        import json

        import fiona
        import rasterio
        import rasterio.mask
    except ImportError as e:
        raise ImportError(e)

    if not os.path.exists(image):
        raise FileNotFoundError(f"{image} does not exist.")

    if not output.endswith(".tif"):
        raise ValueError("Output must be a tif file.")

    output = check_file_path(output)

    if isinstance(mask, str):
        if mask.startswith("http"):
            mask = download_file(mask, output)
        if not os.path.exists(mask):
            raise FileNotFoundError(f"{mask} does not exist.")
    elif isinstance(mask, list) or isinstance(mask, dict):
        if isinstance(mask, list):
            geojson = {
                "type": "FeatureCollection",
                "features": [
                    {
                        "type": "Feature",
                        "properties": {},
                        "geometry": {"type": "Polygon", "coordinates": [mask]},
                    }
                ],
            }
        else:
            geojson = {
                "type": "FeatureCollection",
                "features": [mask],
            }
        mask = temp_file_path(".geojson")
        with open(mask, "w") as f:
            json.dump(geojson, f)

    with fiona.open(mask, "r") as shapefile:
        shapes = [feature["geometry"] for feature in shapefile]

    with rasterio.open(image) as src:
        out_image, out_transform = rasterio.mask.mask(src, shapes, crop=True)
        out_meta = src.meta

    out_meta.update(
        {
            "driver": "GTiff",
            "height": out_image.shape[1],
            "width": out_image.shape[2],
            "transform": out_transform,
        }
    )

    with rasterio.open(output, "w", **out_meta) as dest:
        dest.write(out_image)

    if to_cog:
        image_to_cog(output, output)

clip_raster(image, geometry, geom_crs=None, dst_crs=None, resolution=None, driver='COG', compress='DEFLATE', bands=None, match_raster=None, output=None, verbose=True, **kwargs)

Clip a raster by a geometry.

Parameters:

Name	Type	Description	Default
image	str	Path to the image file in GeoTIFF format.	required
geometry	str | GeoDataFrame | dict | list	The geometry to clip the raster by. It can be a path to vector datasets (e.g., GeoJSON, Shapefile), a geopandas.GeoDataFrame, a dictionary, or a list of 4 numbers (minx, miny, maxx, maxy) representing a bounding box.	required
geom_crs	str	The coordinate reference system of the geometry. Defaults to None.	None
dst_crs	str	The coordinate reference system of the output raster. Defaults to None.	None
resolution	int	The resolution of the output raster. Defaults to None. If a single value is provided, the resolution will be the same in both x and y directions. If a tuple of two values is provided, the first value will be the resolution in the x direction and the second value will be the resolution in the y direction.	None
driver	str	The driver of the output raster. Defaults to "COG".	'COG'
compress	str	The compression of the output raster. Defaults to "DEFLATE".	'DEFLATE'
bands	list	The indices of the bands to clip. Defaults to None. Start from 1.	None
match_raster	str	Path to the raster to match the resolution and CRS of the output raster. Defaults to None.	None
output	str	Path to the output raster file. Defaults to None.	None
**kwargs	Any	Additional keyword arguments to pass to rasterio.reproject.	{}

Source code in leafmap/common.py

def clip_raster(
    image,
    geometry,
    geom_crs=None,
    dst_crs=None,
    resolution=None,
    driver="COG",
    compress="DEFLATE",
    bands=None,
    match_raster=None,
    output=None,
    verbose=True,
    **kwargs: Any,
):
    """Clip a raster by a geometry.

    Args:
        image (str): Path to the image file in GeoTIFF format.
        geometry (str | geopandas.GeoDataFrame | dict | list): The geometry to clip the raster by.
            It can be a path to vector datasets (e.g., GeoJSON, Shapefile), a geopandas.GeoDataFrame,
            a dictionary, or a list of 4 numbers (minx, miny, maxx, maxy) representing a bounding box.
        geom_crs (str, optional): The coordinate reference system of the geometry. Defaults to None.
        dst_crs (str, optional): The coordinate reference system of the output raster. Defaults to None.
        resolution (int, optional): The resolution of the output raster. Defaults to None.
            If a single value is provided, the resolution will be the same in both x and y directions.
            If a tuple of two values is provided, the first value will be the resolution in the x
            direction and the second value will be the resolution in the y direction.
        driver (str, optional): The driver of the output raster. Defaults to "COG".
        compress (str, optional): The compression of the output raster. Defaults to "DEFLATE".
        bands (list, optional): The indices of the bands to clip. Defaults to None. Start from 1.
        match_raster (str, optional): Path to the raster to match the resolution and CRS of the output raster. Defaults to None.
        output (str, optional): Path to the output raster file. Defaults to None.
        **kwargs: Additional keyword arguments to pass to rasterio.reproject.
    """
    import geopandas as gpd
    import rioxarray as rxr
    import xarray as xr

    if match_raster is not None:
        if isinstance(match_raster, str):
            match_raster = rxr.open_rasterio(match_raster)
        elif isinstance(match_raster, xr.DataArray):
            match_raster = match_raster
        else:
            raise ValueError("match_raster must be a string or xarray.DataArray")

    if isinstance(image, str):
        xds = rxr.open_rasterio(image)
    elif isinstance(image, xr.DataArray):
        xds = image
    else:
        raise ValueError("image must be a string or xarray.DataArray")

    if bands is not None:
        xds = xds.sel(band=bands)

    if match_raster is not None:
        xds = xds.rio.reproject_match(match_raster)

    if isinstance(geometry, str):
        gdf = gpd.read_file(geometry)
    elif isinstance(geometry, gpd.GeoDataFrame):
        gdf = geometry
    elif isinstance(geometry, dict) and geometry.get("type") == "FeatureCollection":
        gdf = gpd.GeoDataFrame.from_features(geometry)
    elif isinstance(geometry, dict) and geometry.get("type") == "Feature":
        gdf = gpd.GeoDataFrame.from_features([geometry])
    elif isinstance(geometry, list) and len(geometry) == 4:
        gdf = bbox_to_gdf(geometry)
    else:
        raise ValueError(
            "geometry must be a string, geopandas.GeoDataFrame, dict, or list of 4 numbers"
        )

    if geom_crs is not None:
        gdf.set_crs(geom_crs, inplace=True)

    if isinstance(resolution, (int, float)):
        resolution = (resolution, resolution)
    elif isinstance(resolution, tuple) and len(resolution) == 2:
        pass
    elif resolution is not None:
        raise ValueError("resolution must be a single value or a tuple of two values")

    if dst_crs is None:
        dst_crs = xds.rio.crs

    if resolution is not None and dst_crs is not None:
        if verbose:
            print(
                f"Reprojecting the raster to {dst_crs} at {resolution} resolution ..."
            )
        xds = xds.rio.reproject(dst_crs, resolution=resolution, **kwargs)
    elif resolution is not None:
        if verbose:
            print(
                f"Reprojecting the raster to {dst_crs} at {resolution} resolution ..."
            )
        xds = xds.rio.reproject(dst_crs, resolution=resolution, **kwargs)
    elif dst_crs is not None and dst_crs != xds.rio.crs:
        if verbose:
            print(f"Reprojecting the raster to {dst_crs} ...")
        xds = xds.rio.reproject(dst_crs, **kwargs)
    else:
        pass

    gdf = gdf.to_crs(dst_crs)

    if verbose:
        print(f"Clipping the raster to the geometry ...")
    xds = xds.rio.clip(gdf.geometry, gdf.crs)
    if output is not None:
        if verbose:
            print(f"Saving the raster to {output} ...")
        xds.rio.to_raster(output, driver=driver, compress=compress)
    if verbose:
        print(f"The output raster is saved to {output}")
    return xds

clip_vector(input_gdf, clip_geom=None, bbox=None, output=None)

Clip a vector dataset using either a bounding box or another vector dataset.

Parameters:

Name	Type	Description	Default
input_gdf	str | Path | GeoDataFrame	The input vector data, either as a file path or a GeoDataFrame.	required
clip_geom	str | Path | GeoDataFrame	A vector dataset used for clipping, either as a file path or GeoDataFrame.	None
bbox	tuple	Bounding box defined as (minx, miny, maxx, maxy).	None
output	str | Path	File path to save the clipped result. If None, the result is not saved.	None

Returns:

Type	Description
Any	The clipped GeoDataFrame.

Raises:

Type	Description
ValueError	If both clip_geom and bbox are provided or neither is provided.
ValueError	If bbox is not a 4-element tuple or list.

Source code in leafmap/common.py

def clip_vector(input_gdf, clip_geom=None, bbox=None, output=None) -> Any:
    """
    Clip a vector dataset using either a bounding box or another vector dataset.

    Args:
        input_gdf (str | Path | gpd.GeoDataFrame): The input vector data, either as a file path or a GeoDataFrame.
        clip_geom (str | Path | gpd.GeoDataFrame, optional): A vector dataset used for clipping, either as a file path or GeoDataFrame.
        bbox (tuple, optional): Bounding box defined as (minx, miny, maxx, maxy).
        output (str | Path, optional): File path to save the clipped result. If None, the result is not saved.

    Returns:
        The clipped GeoDataFrame.

    Raises:
        ValueError: If both `clip_geom` and `bbox` are provided or neither is provided.
        ValueError: If `bbox` is not a 4-element tuple or list.
    """
    from pathlib import Path

    import geopandas as gpd
    from shapely.geometry import box

    # Load input_gdf if it's a file path
    if isinstance(input_gdf, (str, Path)):
        input_gdf = gpd.read_file(input_gdf)

    # Load clip_geom if it's a file path
    if isinstance(clip_geom, (str, Path)):
        clip_geom = gpd.read_file(clip_geom)

    if clip_geom is not None and bbox is not None:
        raise ValueError("Specify either 'clip_geom' or 'bbox', not both.")

    if clip_geom is not None:
        if input_gdf.crs != clip_geom.crs:
            clip_geom = clip_geom.to_crs(input_gdf.crs)
        clipped = gpd.clip(input_gdf, clip_geom)

    elif bbox is not None:
        if not isinstance(bbox, (tuple, list)) or len(bbox) != 4:
            raise ValueError("bbox must be a tuple or list of (minx, miny, maxx, maxy)")
        minx, miny, maxx, maxy = bbox
        bbox_geom = gpd.GeoDataFrame(
            geometry=[box(minx, miny, maxx, maxy)], crs="EPSG:4326"
        )
        bbox_geom = bbox_geom.to_crs(input_gdf.crs)
        clipped = gpd.clip(input_gdf, bbox_geom)

    else:
        raise ValueError("You must provide either 'clip_geom' or 'bbox'.")

    if output:
        clipped.to_file(output)

    return clipped

close_duckdb_connections(database_path=None, quiet=True)

Close DuckDB connections for a specific database or all databases.

This function closes all connections in the connection pool for the specified database, allowing other programs to access the database file. This is useful when you're done using the database and want to release the file lock.

Parameters:

Name	Type	Description	Default
database_path	str	Path to the DuckDB database file. If None, closes connections for all databases. Defaults to None.	None
quiet	bool	If True, suppress status messages. Defaults to True.	True

Returns:

Type	Description
	None

Example

import leafmap

After using add_duckdb_layer

m = leafmap.Map() m.add_duckdb_layer("tiles.db")

Later, close the connections

leafmap.close_duckdb_connections()

Or close connections for a specific database

leafmap.close_duckdb_connections("tiles.db")

Source code in leafmap/common.py

def close_duckdb_connections(database_path: str = None, quiet: bool = True):
    """
    Close DuckDB connections for a specific database or all databases.

    This function closes all connections in the connection pool for the specified
    database, allowing other programs to access the database file. This is useful
    when you're done using the database and want to release the file lock.

    Args:
        database_path (str, optional): Path to the DuckDB database file.
            If None, closes connections for all databases. Defaults to None.
        quiet (bool, optional): If True, suppress status messages. Defaults to True.

    Returns:
        None

    Example:
        >>> import leafmap
        >>> # After using add_duckdb_layer
        >>> m = leafmap.Map()
        >>> m.add_duckdb_layer("tiles.db")
        >>> # Later, close the connections
        >>> leafmap.close_duckdb_connections()
        >>> # Or close connections for a specific database
        >>> leafmap.close_duckdb_connections("tiles.db")
    """
    global _duckdb_connection_pools

    if database_path is None:
        # Close all connections
        databases_to_close = list(_duckdb_connection_pools.keys())
    else:
        # Close connections for specific database
        databases_to_close = (
            [database_path] if database_path in _duckdb_connection_pools else []
        )

    for db_path in databases_to_close:
        pool_info = _duckdb_connection_pools.get(db_path)
        if pool_info:
            connection_pool = pool_info["pool"]
            pool_lock = pool_info["lock"]
            max_connections = pool_info["max_connections"]

            if not quiet:
                print(f"Closing DuckDB connections for: {db_path}")

            # Acquire the pool lock before closing connections
            with pool_lock:
                # Close all connections in the pool
                closed_count = 0
                while not connection_pool.empty():
                    try:
                        con = connection_pool.get_nowait()
                        con.close()
                        closed_count += 1
                    except Exception as e:
                        if not quiet:
                            print(f"Error closing connection: {e}")

                # Remove from registry
                del _duckdb_connection_pools[db_path]

                if not quiet:
                    print(
                        f"Closed {closed_count}/{max_connections} connections for {db_path}"
                    )

    if not quiet and len(databases_to_close) == 0:
        if database_path is None:
            print("No active DuckDB connections to close.")
        else:
            print(f"No active connections found for database: {database_path}")

cog_bands(url, titiler_endpoint=None)

Get band names of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None

Returns:

Type	Description
List	A list of band names.

Source code in leafmap/stac.py

def cog_bands(
    url: str,
    titiler_endpoint: Optional[str] = None,
) -> List:
    """Get band names of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".

    Returns:
        A list of band names.
    """

    if os.environ.get("USE_MKDOCS") is not None:
        return None

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    try:
        r = requests.get(
            f"{titiler_endpoint}/cog/info",
            params={
                "url": url,
            },
        ).json()

        bands = [b[0] for b in r["band_descriptions"]]
        return bands
    except Exception as e:
        print(e)
        return []

cog_bounds(url, titiler_endpoint=None)

Get the bounding box of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None

Returns:

Name	Type	Description
list	List	A list of values representing [left, bottom, right, top]

Source code in leafmap/stac.py

def cog_bounds(
    url: str,
    titiler_endpoint: Optional[str] = None,
) -> List:
    """Get the bounding box of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".

    Returns:
        list: A list of values representing [left, bottom, right, top]
    """
    if os.environ.get("USE_MKDOCS") is not None:
        return None

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    try:
        r = requests.get(
            f"{titiler_endpoint}/cog/info.geojson", params={"url": url}
        ).json()
        return r["bbox"]
    except Exception as e:
        print(e)
        return None

cog_center(url, titiler_endpoint=None)

Get the centroid of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None

Returns:

Type	Description
Tuple	A tuple representing (longitude, latitude).

Source code in leafmap/stac.py

def cog_center(
    url: str,
    titiler_endpoint: Optional[str] = None,
) -> Tuple:
    """Get the centroid of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".

    Returns:
        A tuple representing (longitude, latitude).
    """

    if os.environ.get("USE_MKDOCS") is not None:
        return None

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    bounds = cog_bounds(url, titiler_endpoint)
    if bounds is None:
        return (None, None)
    else:
        center = (
            (bounds[0] + bounds[2]) / 2,
            (bounds[1] + bounds[3]) / 2,
        )  # (lat, lon)
        return center

cog_info(url, titiler_endpoint=None, return_geojson=False)

Get band statistics of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None

Returns:

Name	Type	Description
list	List	A dictionary of band info.

Source code in leafmap/stac.py

def cog_info(
    url: str,
    titiler_endpoint: Optional[str] = None,
    return_geojson: Optional[bool] = False,
) -> List:
    """Get band statistics of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".

    Returns:
        list: A dictionary of band info.
    """
    if os.environ.get("USE_MKDOCS") is not None:
        return None

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    info = "info"
    if return_geojson:
        info = "info.geojson"

    try:
        r = requests.get(
            f"{titiler_endpoint}/cog/{info}",
            params={
                "url": url,
            },
            timeout=10,
        ).json()
    except Exception as e:
        titiler_endpoint = "https://giswqs-titiler-endpoint.hf.space"
        r = requests.get(
            f"{titiler_endpoint}/cog/{info}",
            params={
                "url": url,
            },
            timeout=10,
        ).json()

    return r

cog_mosaic(links, titiler_endpoint=None, username='anonymous', layername=None, overwrite=False, verbose=True, **kwargs)

Creates a COG mosaic from a list of COG URLs.

Parameters:

Name	Type	Description	Default
links	list	A list containing COG HTTP URLs.	required
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://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

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 leafmap/stac.py

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

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

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

    Returns:
        The tile URL for the COG mosaic.
    """

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    if layername is None:
        layername = "layer_X"

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

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

        # Create mosaic
        requests.post(
            f"{titiler_endpoint}/mosaicjson/create",
            json={
                "username": username,
                "layername": layername,
                "files": links,
                # "overwrite": overwrite
            },
            params={
                "access_token": token,
            },
        ).json()

        r2 = requests.get(
            f"{titiler_endpoint}/mosaicjson/{username}.{layername}/tilejson.json",
        ).json()

        tiles = r2["tiles"][0]

        # Convert 127.0.0.1 to localhost for Google Colab browser access
        if "google.colab" in sys.modules and "127.0.0.1" in tiles:
            tiles = tiles.replace("http://127.0.0.1", "https://localhost")

        return tiles

    except Exception as e:
        raise Exception(e)

cog_mosaic_from_file(filepath, skip_rows=0, titiler_endpoint=None, username='anonymous', layername=None, overwrite=False, verbose=True, **kwargs)

Creates a COG mosaic from a csv/txt file stored locally for through HTTP URL.

Parameters:

Name	Type	Description	Default
filepath	str	Local path or HTTP URL to the csv/txt file containing COG URLs.	required
skip_rows	int	The number of rows to skip in the file. Defaults to 0.	0
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://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 leafmap/stac.py

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

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

    Returns:
        The tile URL for the COG mosaic.
    """
    import urllib

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    links = []
    if filepath.startswith("http"):
        data = urllib.request.urlopen(filepath)
        for line in data:
            links.append(line.decode("utf-8").strip())

    else:
        with open(filepath) as f:
            links = [line.strip() for line in f.readlines()]

    links = links[skip_rows:]
    # print(links)
    mosaic = cog_mosaic(
        links, titiler_endpoint, username, layername, overwrite, verbose, **kwargs
    )
    return mosaic

cog_pixel_value(lon, lat, url, bidx, titiler_endpoint=None, verbose=True, **kwargs)

Get pixel value from COG.

Parameters:

Name	Type	Description	Default
lon	float	Longitude of the pixel.	required
lat	float	Latitude of the pixel.	required
url	str	HTTP URL to a COG, e.g., 'https://github.com/opengeos/data/releases/download/raster/Libya-2023-07-01.tif'	required
bidx	str	Dataset band indexes (e.g bidx=1, bidx=1&bidx=2&bidx=3). Defaults to None.	required
titiler_endpoint	str	TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space", "planetary-computer", "pc". Defaults to None.	None
verbose	bool	Print status messages. Defaults to True.	True

Returns:

Name	Type	Description
list	List	A dictionary of band info.

Source code in leafmap/stac.py

def cog_pixel_value(
    lon: float,
    lat: float,
    url: str,
    bidx: Optional[str],
    titiler_endpoint: Optional[str] = None,
    verbose: Optional[bool] = True,
    **kwargs,
) -> List:
    """Get pixel value from COG.

    Args:
        lon (float): Longitude of the pixel.
        lat (float): Latitude of the pixel.
        url (str): HTTP URL to a COG, e.g., 'https://github.com/opengeos/data/releases/download/raster/Libya-2023-07-01.tif'
        bidx (str, optional): Dataset band indexes (e.g bidx=1, bidx=1&bidx=2&bidx=3). Defaults to None.
        titiler_endpoint (str, optional): TiTiler endpoint, e.g., "https://giswqs-titiler-endpoint.hf.space", "planetary-computer", "pc". Defaults to None.
        verbose (bool, optional): Print status messages. Defaults to True.

    Returns:
        list: A dictionary of band info.
    """
    if os.environ.get("USE_MKDOCS") is not None:
        return None

    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).json()
    bands = cog_bands(url, titiler_endpoint)
    # if isinstance(titiler_endpoint, str):
    #     r = requests.get(f"{titiler_endpoint}/cog/point/{lon},{lat}", params=kwargs).json()
    # else:
    #     r = requests.get(
    #         titiler_endpoint.url_for_stac_pixel_value(lon, lat), params=kwargs
    #     ).json()

    if "detail" in r:
        if verbose:
            print(r["detail"])
        return None
    else:
        values = r["values"]
        result = dict(zip(bands, values))
        return result

cog_stats(url, titiler_endpoint=None)

Get band statistics of a Cloud Optimized GeoTIFF (COG).

Parameters:

Name	Type	Description	Default
url	str	HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif	required
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None

Returns:

Name	Type	Description
list	List	A dictionary of band statistics.

Source code in leafmap/stac.py

def cog_stats(
    url: str,
    titiler_endpoint: Optional[str] = None,
) -> List:
    """Get band statistics of a Cloud Optimized GeoTIFF (COG).

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".

    Returns:
        list: A dictionary of band statistics.
    """
    if os.environ.get("USE_MKDOCS") is not None:
        return None

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    try:
        r = requests.get(
            f"{titiler_endpoint}/cog/statistics",
            params={
                "url": url,
            },
            timeout=10,
        ).json()
        return r
    except Exception as e:
        print(e)
        return None

cog_tile(url, bands=None, titiler_endpoint=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. Default to None	required
bands	list	List of bands to use. Defaults to None.	None
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None
**kwargs	Any	Additional arguments to pass to the titiler endpoint. For more information about the available arguments, see https://developmentseed.org/titiler/endpoints/cog/#tiles. For example, to apply a rescaling to multiple bands, use something like rescale=["164,223","130,211","99,212"].	{}

Returns:

Type	Description
Tuple	The COG tile layer URL and bounds.

Source code in leafmap/stac.py

def cog_tile(
    url,
    bands: Optional[str] = None,
    titiler_endpoint: Optional[str] = None,
    **kwargs,
) -> Tuple:
    """Get a tile layer from a Cloud Optimized GeoTIFF (COG).
        Source code adapted from https://developmentseed.org/titiler/examples/notebooks/Working_with_CloudOptimizedGeoTIFF_simple/

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif. Default to None
        bands (list, optional): List of bands to use. Defaults to None.
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".
        **kwargs (Any): Additional arguments to pass to the titiler endpoint. For more information about the available arguments, see https://developmentseed.org/titiler/endpoints/cog/#tiles.
            For example, to apply a rescaling to multiple bands, use something like `rescale=["164,223","130,211","99,212"]`.

    Returns:
        The COG tile layer URL and bounds.
    """
    if os.environ.get("USE_MKDOCS") is not None:
        return None

    import json

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)

    kwargs["url"] = url

    try:
        band_names = cog_bands(url, titiler_endpoint)
    except Exception as e:
        titiler_endpoint = "https://giswqs-titiler-endpoint.hf.space"
        band_names = cog_bands(url, titiler_endpoint)

    if isinstance(bands, str):
        bands = [bands]

    if bands is None and "bidx" not in kwargs:
        if len(band_names) >= 3:
            kwargs["bidx"] = [1, 2, 3]
    elif isinstance(bands, list) and "bidx" not in kwargs:
        if all(isinstance(x, int) for x in bands):
            if len(set(bands)) == 1:
                bands = bands[0]
            kwargs["bidx"] = bands
        elif all(isinstance(x, str) for x in bands):
            if len(set(bands)) == 1:
                bands = bands[0]
            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["palette"].lower()
        del kwargs["palette"]

    if "bidx" not in kwargs:
        kwargs["bidx"] = [1]
    elif isinstance(kwargs["bidx"], int):
        kwargs["bidx"] = [kwargs["bidx"]]

    if len(kwargs["bidx"]) == 1 and ("colormap" not in kwargs):
        colormap = _get_image_colormap(url)
        if colormap is not None:
            kwargs["colormap"] = colormap

    if "rescale" not in kwargs and ("colormap" not in kwargs):
        try:
            stats = cog_stats(url, titiler_endpoint)
        except Exception as e:
            titiler_endpoint = "https://giswqs-titiler-endpoint.hf.space"
            stats = cog_stats(url, titiler_endpoint)

        if stats is not None and "message" not in stats:
            try:
                rescale = []
                for i in band_names:
                    rescale.append(
                        "{},{}".format(
                            stats[i]["percentile_2"],
                            stats[i]["percentile_98"],
                        )
                    )
                kwargs["rescale"] = rescale
            except Exception as e:
                pass

    if "colormap" in kwargs and isinstance(kwargs["colormap"], dict):
        kwargs["colormap"] = json.dumps(kwargs["colormap"])

    TileMatrixSetId = "WebMercatorQuad"
    if "TileMatrixSetId" in kwargs.keys():
        TileMatrixSetId = kwargs["TileMatrixSetId"]
        kwargs.pop("TileMatrixSetId")

    if "default_vis" in kwargs.keys() and kwargs["default_vis"]:
        kwargs = {"url": url}

    try:
        r = requests.get(
            f"{titiler_endpoint}/cog/{TileMatrixSetId}/tilejson.json",
            params=kwargs,
            timeout=10,
        ).json()
    except Exception as e:
        print(e)
        return None
    tiles = r["tiles"][0]
    if titiler_endpoint.startswith("https://") and tiles.startswith("http://"):
        tiles = tiles.replace("http://", "https://")

    # Convert 127.0.0.1 to localhost for Google Colab browser access
    if "google.colab" in sys.modules and "127.0.0.1" in tiles:
        tiles = tiles.replace("http://127.0.0.1", "https://localhost")

    return tiles

cog_tile_vmin_vmax(url, bands=None, titiler_endpoint=None, percentile=True, **kwargs)

Get a tile layer from a Cloud Optimized GeoTIFF (COG) and return the minimum and maximum values.

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	List of bands to use. Defaults to None.	None
titiler_endpoint	str	TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".	None
percentile	bool	Whether to use percentiles or not. Defaults to True.	True

Source code in leafmap/stac.py

def cog_tile_vmin_vmax(
    url: str,
    bands: Optional[List] = None,
    titiler_endpoint: Optional[str] = None,
    percentile: Optional[bool] = True,
    **kwargs,
) -> Tuple:
    """Get a tile layer from a Cloud Optimized GeoTIFF (COG) and return the minimum and maximum values.

    Args:
        url (str): HTTP URL to a COG, e.g., https://opendata.digitalglobe.com/events/mauritius-oil-spill/post-event/2020-08-12/105001001F1B5B00/105001001F1B5B00.tif
        bands (list, optional): List of bands to use. Defaults to None.
        titiler_endpoint (str, optional): TiTiler endpoint. Defaults to "https://giswqs-titiler-endpoint.hf.space".
        percentile (bool, optional): Whether to use percentiles or not. Defaults to True.
    Returns:
        tuple: Returns the minimum and maximum values.
    """
    if os.environ.get("USE_MKDOCS") is not None:
        return None

    titiler_endpoint = check_titiler_endpoint(titiler_endpoint)
    stats = cog_stats(url, titiler_endpoint)

    if isinstance(bands, str):
        bands = [bands]

    if bands is not None:
        stats = {s: stats[s] for s in stats if s in bands}

    if percentile:
        vmin = min([stats[s]["percentile_2"] for s in stats])
        vmax = max([stats[s]["percentile_98"] for s in stats])
    else:
        vmin = min([stats[s]["min"] for s in stats])
        vmax = max([stats[s]["max"] for s in stats])

    return vmin, vmax

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:

Type	Description
Tuple[bool, List[str], List[str]]	A tuple containing the validation results (True if src_path is a valid COG, list of validation errors, and a list of validation warnings).

Source code in leafmap/common.py

def cog_validate(source, verbose=False) -> Tuple[bool, List[str], List[str]]:
    """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:
        A tuple containing the validation results (True if src_path is a valid COG, list of validation errors, and a list of validation warnings).
    """
    try:
        from rio_cogeo.cogeo import cog_info, cog_validate
    except ImportError:
        raise ImportError(
            "The rio-cogeo package is not installed. Please install it with `pip install rio-cogeo` or `conda install rio-cogeo -c conda-forge`."
        )

    if not source.startswith("http"):
        source = check_file_path(source)

        if not os.path.exists(source):
            raise FileNotFoundError("The provided input file could not be found.")

    if verbose:
        return cog_info(source)
    else:
        return cog_validate(source)

color_code_dataframe(data, legend_dict)

Converts values in a dataframe to color codes based on a legend dictionary.

This function takes a dataframe (or path to a dataframe) and a legend dictionary and returns a new dataframe with values replaced by their corresponding color codes. It supports both numeric range legends and categorical legends.

Parameters:

Name	Type	Description	Default
data	Union[str, DataFrame, GeoDataFrame]	Input data source, can be: - Path to a CSV file or geospatial file - pandas DataFrame - geopandas GeoDataFrame	required
legend_dict	Dict[str, str]	Dictionary mapping values to colors, can be: - Numeric ranges ("[ 100000, 200000]") mapped to color codes - Categorical values ("low", "medium") mapped to color codes - Can include a "Nodata" key for None/NaN values	required

Returns:

Type	Description
Union[DataFrame, GeoDataFrame]	A new dataframe with values replaced by color codes, preserving the
Union[DataFrame, GeoDataFrame]	input data type (DataFrame or GeoDataFrame)

Raises:

Type	Description
TypeError	If the input data type is not supported
ValueError	If the file format is not supported

Examples:

>>> # Example with numeric ranges
>>> range_legend = {
...     "[ 0, 200000]": "#daeaf6",
...     "(200001, 400000]": "#9ecae1",
...     "Nodata": "#f0f0f0"
... }
>>> color_df = color_code_dataframe("housing_data.csv", range_legend)

>>> # Example with categorical values
>>> cat_legend = {
...     "low": "#daeaf6",
...     "medium": "#9ecae1",
...     "high": "#2171b5",
...     "Nodata": "#f0f0f0"
... }
>>> df = pd.DataFrame({"Risk": ["low", "medium", "high", None]})
>>> color_df = color_code_dataframe(df, cat_legend)

Source code in leafmap/common.py

def color_code_dataframe(
    data: Union[str, pd.DataFrame, "gpd.GeoDataFrame"], legend_dict: Dict[str, str]
) -> Union[pd.DataFrame, "gpd.GeoDataFrame"]:
    """Converts values in a dataframe to color codes based on a legend dictionary.

    This function takes a dataframe (or path to a dataframe) and a legend dictionary
    and returns a new dataframe with values replaced by their corresponding color codes.
    It supports both numeric range legends and categorical legends.

    Args:
        data: Input data source, can be:
            - Path to a CSV file or geospatial file
            - pandas DataFrame
            - geopandas GeoDataFrame
        legend_dict: Dictionary mapping values to colors, can be:
            - Numeric ranges ("[ 100000, 200000]") mapped to color codes
            - Categorical values ("low", "medium") mapped to color codes
            - Can include a "Nodata" key for None/NaN values

    Returns:
        A new dataframe with values replaced by color codes, preserving the
        input data type (DataFrame or GeoDataFrame)

    Raises:
        TypeError: If the input data type is not supported
        ValueError: If the file format is not supported

    Examples:
        >>> # Example with numeric ranges
        >>> range_legend = {
        ...     "[ 0, 200000]": "#daeaf6",
        ...     "(200001, 400000]": "#9ecae1",
        ...     "Nodata": "#f0f0f0"
        ... }
        >>> color_df = color_code_dataframe("housing_data.csv", range_legend)

        >>> # Example with categorical values
        >>> cat_legend = {
        ...     "low": "#daeaf6",
        ...     "medium": "#9ecae1",
        ...     "high": "#2171b5",
        ...     "Nodata": "#f0f0f0"
        ... }
        >>> df = pd.DataFrame({"Risk": ["low", "medium", "high", None]})
        >>> color_df = color_code_dataframe(df, cat_legend)
    """
    import re

    # Handle different input types
    if isinstance(data, str):
        # Input is a path to a file
        path = Path(data)
        if path.suffix.lower() == ".csv":
            df = pd.read_csv(data)
        elif path.suffix.lower() in [".geojson", ".shp"]:
            df = gpd.read_file(data)
        else:
            raise ValueError(f"Unsupported file format: {path.suffix}")
    elif isinstance(data, pd.DataFrame):
        # Input is already a pandas DataFrame
        df = data.copy()
    elif isinstance(data, gpd.GeoDataFrame):
        # Input is a GeoDataFrame
        df = data.copy()
    else:
        raise TypeError("Input must be a file path, pandas DataFrame, or GeoDataFrame")

    # Determine legend type: numeric ranges or categorical
    # Exclude "Nodata" key from this check
    legend_without_nodata = {
        k: v
        for k, v in legend_dict.items()
        if k != "Nodata" and not isinstance(k, str) or k.lower() != "nodata"
    }
    is_range_legend = any(
        "[" in key or "(" in key for key in legend_without_nodata.keys()
    )

    # Get the "Nodata" color if provided
    nodata_keys = ["Nodata", "nodata", "NODATA", "NoData"]
    nodata_color = None
    for key in nodata_keys:
        if key in legend_dict:
            nodata_color = legend_dict[key]
            break

    # Function to get color based on numeric value and range legend
    def get_color_for_numeric(value: Any) -> Optional[str]:
        """Maps a numeric value to a color based on the range legend.

        Args:
            value: The value to map to a color

        Returns:
            The corresponding color code or None if no match is found
        """
        if pd.isna(value) or value is None:
            return nodata_color

        if not isinstance(value, (int, float)):
            return nodata_color

        for range_str, color in legend_dict.items():
            # Skip the Nodata entry
            if isinstance(range_str, str) and range_str.lower() == "nodata":
                continue

            # Parse the range string like "[ 182913, 357522]" or "( 357522, 415584]"
            match = re.search(r"[\[\(]\s*(\d+),\s*(\d+)[\]\)]", range_str)
            if not match:
                continue

            lower_bound = int(match.group(1))
            upper_bound = int(match.group(2))
            lower_inclusive = range_str.startswith("[")
            upper_inclusive = range_str.endswith("]")

            # Check if the value is within the range
            above_lower = (
                value >= lower_bound if lower_inclusive else value > lower_bound
            )
            below_upper = (
                value <= upper_bound if upper_inclusive else value < upper_bound
            )

            if above_lower and below_upper:
                return color

        return None

    # Function to get color based on categorical value
    def get_color_for_categorical(value: Any) -> Optional[str]:
        """Maps a categorical value to a color.

        Args:
            value: The value to map to a color

        Returns:
            The corresponding color code or None if no match is found
        """
        if pd.isna(value) or value is None:
            return nodata_color

        # Convert to string for comparison
        str_value = str(value).lower()

        # Try direct matching
        if str_value in legend_dict:
            return legend_dict[str_value]

        # Try case-insensitive matching
        for cat, color in legend_dict.items():
            if isinstance(cat, str) and cat.lower() == "nodata":
                continue

            if isinstance(cat, str) and cat.lower() == str_value:
                return color

        return None

    # Select appropriate color mapping function
    get_color = get_color_for_numeric if is_range_legend else get_color_for_categorical

    # Identify columns to process
    if is_range_legend:
        # For numeric ranges, look for numeric columns and date-formatted columns
        columns_to_process: List[str] = []
        for col in df.columns:
            # Check if column name matches date pattern
            if isinstance(col, str) and re.match(r"^\d{4}-\d{2}-\d{2}$", col):
                columns_to_process.append(col)
                continue

            # Check if column contains numbers
            if pd.api.types.is_numeric_dtype(df[col]):
                # Exclude columns that are likely IDs or categorical codes
                if not (
                    col.lower().endswith("id")
                    or "code" in col.lower()
                    or "fips" in col.lower()
                ):
                    columns_to_process.append(col)
    else:
        # For categorical legend, look for object or category columns
        columns_to_process: List[str] = []
        for col in df.columns:
            if pd.api.types.is_object_dtype(
                df[col]
            ) or pd.api.types.is_categorical_dtype(df[col]):
                columns_to_process.append(col)
            # Also check if numeric columns might contain discrete categories
            elif pd.api.types.is_numeric_dtype(df[col]) and df[col].nunique() < 10:
                columns_to_process.append(col)

    # Replace each value with its corresponding color
    for col in columns_to_process:
        df[col] = df[col].apply(get_color)

    return df

configure_jupyterhub(base_url=None)

Auto-configure leafmap for JupyterHub environments.

This function automatically detects if running in a JupyterHub environment and configures the necessary environment variables for tile server proxying. It will be called automatically by add_duckdb_layer, so you typically don't need to call it manually.

Parameters:

Name	Type	Description	Default
base_url	str	The base URL of your JupyterHub instance (e.g., "https://jupyter.example.com"). Required for MapLibre vector tiles due to URL validation requirements. If not provided, vector tiles may not work.	None

Example

import leafmap

Specify your JupyterHub URL for vector tile support

leafmap.configure_jupyterhub("https://your-jupyterhub-domain.com")

Now add_duckdb_layer will work correctly

Note

MapLibre GL JS's vector tile sources require absolute URLs (with http:// or https://). Raster tiles (add_raster) work with relative URLs, but vector tiles (add_duckdb_layer) do not. This is a limitation of MapLibre GL JS, not leafmap.

Source code in leafmap/common.py

def configure_jupyterhub(base_url: str = None):
    """Auto-configure leafmap for JupyterHub environments.

    This function automatically detects if running in a JupyterHub environment
    and configures the necessary environment variables for tile server proxying.
    It will be called automatically by add_duckdb_layer, so you typically don't
    need to call it manually.

    Args:
        base_url (str, optional): The base URL of your JupyterHub instance
            (e.g., "https://jupyter.example.com"). Required for MapLibre vector tiles
            due to URL validation requirements. If not provided, vector tiles may not work.

    Example:
        >>> import leafmap
        >>> # Specify your JupyterHub URL for vector tile support
        >>> leafmap.configure_jupyterhub("https://your-jupyterhub-domain.com")
        >>> # Now add_duckdb_layer will work correctly

    Note:
        MapLibre GL JS's vector tile sources require absolute URLs (with http:// or https://).
        Raster tiles (add_raster) work with relative URLs, but vector tiles (add_duckdb_layer) do not.
        This is a limitation of MapLibre GL JS, not leafmap.
    """
    # Store base URL if provided
    if base_url:
        base_url = base_url.rstrip("/")
        os.environ["LEAFMAP_BASE_URL"] = base_url

    # Auto-configure proxy prefix if not already set (like get_local_tile_url does)
    if "LEAFMAP_CLIENT_PREFIX" not in os.environ:
        # Check for JupyterHub environment
        if "JUPYTERHUB_SERVICE_PREFIX" in os.environ:
            jupyterhub_prefix = os.environ["JUPYTERHUB_SERVICE_PREFIX"].rstrip("/")
            os.environ["LEAFMAP_CLIENT_PREFIX"] = f"{jupyterhub_prefix}/proxy/{{port}}"
        elif "JUPYTER_SERVER_ROOT" in os.environ or "JPY_SESSION_NAME" in os.environ:
            # Generic Jupyter environment
            os.environ["LEAFMAP_CLIENT_PREFIX"] = "proxy/{port}"

connect_points_as_line(gdf, sort_column=None, crs='EPSG:4326', single_line=True)

Connects points in a GeoDataFrame into either a single LineString or multiple LineStrings based on a specified sort column or the index if no column is provided. The resulting GeoDataFrame will have the specified CRS.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoDataFrame containing point geometries.	required
sort_column	Optional[str]	Column name to sort the points by (e.g., 'timestamp'). If None, the index is used for sorting. Defaults to None.	None
crs	str	The coordinate reference system (CRS) for the resulting GeoDataFrame. Defaults to "EPSG:4326".	'EPSG:4326'
single_line	bool	If True, generates a single LineString connecting all points. If False, generates multiple LineStrings, each connecting two consecutive points. Defaults to True.	True

Returns:

Type	Description
GeoDataFrame	A new GeoDataFrame containing either a single LineString or multiple LineString geometries. based on the single_line parameter, with the specified CRS.

Example

line_gdf = connect_points_as_line(gdf, 'timestamp', crs="EPSG:3857", single_line=True) line_gdf = connect_points_as_line(gdf, single_line=False) # Uses index and defaults to EPSG:4326

Source code in leafmap/common.py

def connect_points_as_line(
    gdf: "GeoDataFrame",
    sort_column: Optional[str] = None,
    crs: str = "EPSG:4326",
    single_line: bool = True,
) -> "GeoDataFrame":
    """
    Connects points in a GeoDataFrame into either a single LineString or multiple LineStrings
    based on a specified sort column or the index if no column is provided. The resulting
    GeoDataFrame will have the specified CRS.

    Args:
        gdf (GeoDataFrame): A GeoDataFrame containing point geometries.
        sort_column (Optional[str]): Column name to sort the points by (e.g., 'timestamp').
                                     If None, the index is used for sorting. Defaults to None.
        crs (str): The coordinate reference system (CRS) for the resulting GeoDataFrame.
                   Defaults to "EPSG:4326".
        single_line (bool): If True, generates a single LineString connecting all points.
                            If False, generates multiple LineStrings, each connecting two consecutive points.
                            Defaults to True.

    Returns:
        A new GeoDataFrame containing either a single LineString or multiple LineString geometries.
                      based on the single_line parameter, with the specified CRS.

    Example:
        >>> line_gdf = connect_points_as_line(gdf, 'timestamp', crs="EPSG:3857", single_line=True)
        >>> line_gdf = connect_points_as_line(gdf, single_line=False)  # Uses index and defaults to EPSG:4326
    """
    import geopandas as gpd
    from shapely.geometry import LineString

    # Sort the GeoDataFrame by the specified column or by index if None
    gdf_sorted = gdf.sort_values(by=sort_column) if sort_column else gdf.sort_index()

    if single_line:
        # Create a single LineString connecting all points
        line = LineString(gdf_sorted.geometry.tolist())
        line_gdf = gpd.GeoDataFrame(geometry=[line], crs=crs)
    else:
        # Generate LineStrings for each consecutive pair of points
        lines = [
            LineString([gdf_sorted.geometry.iloc[i], gdf_sorted.geometry.iloc[i + 1]])
            for i in range(len(gdf_sorted) - 1)
        ]
        line_gdf = gpd.GeoDataFrame(geometry=lines, crs=crs)

    return line_gdf

connect_postgis(database, host='localhost', user=None, password=None, port=5432, use_env_var=False)

Connects to a PostGIS database.

Parameters:

Name	Type	Description	Default
database	str	Name of the database	required
host	str	Hosting server for the database. Defaults to "localhost".	'localhost'
user	str	User name to access the database. Defaults to None.	None
password	str	Password to access the database. Defaults to None.	None
port	int	Port number to connect to at the server host. Defaults to 5432.	5432
use_env_var	bool	Whether to use environment variables. It set to True, user and password are treated as an environment variables with default values user="SQL_USER" and password="SQL_PASSWORD". Defaults to False.	False

Raises:

Type	Description
ValueError	If user is not specified.
ValueError	If password is not specified.

Returns:

Type	Description
Any	A SQLAlchemy engine connection string or engine object.

Source code in leafmap/common.py

def connect_postgis(
    database, host="localhost", user=None, password=None, port=5432, use_env_var=False
) -> Any:
    """Connects to a PostGIS database.

    Args:
        database (str): Name of the database
        host (str, optional): Hosting server for the database. Defaults to "localhost".
        user (str, optional): User name to access the database. Defaults to None.
        password (str, optional): Password to access the database. Defaults to None.
        port (int, optional): Port number to connect to at the server host. Defaults to 5432.
        use_env_var (bool, optional): Whether to use environment variables. It set to True, user and password are treated as an environment variables with default values user="SQL_USER" and password="SQL_PASSWORD". Defaults to False.

    Raises:
        ValueError: If user is not specified.
        ValueError: If password is not specified.

    Returns:
        A SQLAlchemy engine connection string or engine object.
    """
    check_package(name="geopandas", URL="https://geopandas.org")
    check_package(
        name="sqlalchemy",
        URL="https://docs.sqlalchemy.org/en/14/intro.html#installation",
    )

    from sqlalchemy import create_engine

    if use_env_var:
        if user is not None:
            user = os.getenv(user)
        else:
            user = os.getenv("SQL_USER")

        if password is not None:
            password = os.getenv(password)
        else:
            password = os.getenv("SQL_PASSWORD")

        if user is None:
            raise ValueError("user is not specified.")
        if password is None:
            raise ValueError("password is not specified.")

    connection_string = f"postgresql://{user}:{password}@{host}:{port}/{database}"
    engine = create_engine(connection_string)

    return engine

construct_bbox(*args, buffer=0.001, crs='EPSG:4326', return_gdf=False)

Construct a bounding box (bbox) geometry based on either a centroid point or bbox.

Parameters:

Name	Type	Description	Default
*args	Union[float, Tuple[float, float, float, float]]	Coordinates for the geometry. - If 2 arguments are provided, it is interpreted as a centroid (x, y) with a buffer. - If 4 arguments are provided, it is interpreted as a bbox (minx, miny, maxx, maxy).	()
buffer	float	The buffer distance around the centroid point (default is 0.01 degrees).	0.001
crs	str	The coordinate reference system (default is "EPSG:4326").	'EPSG:4326'
return_gdf	bool	Whether to return a GeoDataFrame (default is False).	False

Returns:

Type	Description
Union[Polygon, GeoDataFrame]	The constructed bounding box (Polygon).

Source code in leafmap/common.py

def construct_bbox(
    *args: Union[float, Tuple[float, float, float, float]],
    buffer: float = 0.001,
    crs: str = "EPSG:4326",
    return_gdf: bool = False,
) -> Union["Polygon", "gpd.GeoDataFrame"]:
    """
    Construct a bounding box (bbox) geometry based on either a centroid point or bbox.

    Args:
        *args: Coordinates for the geometry.
            - If 2 arguments are provided, it is interpreted as a centroid (x, y) with a buffer.
            - If 4 arguments are provided, it is interpreted as a bbox (minx, miny, maxx, maxy).
        buffer (float): The buffer distance around the centroid point (default is 0.01 degrees).
        crs (str): The coordinate reference system (default is "EPSG:4326").
        return_gdf (bool): Whether to return a GeoDataFrame (default is False).

    Returns:
        The constructed bounding box (Polygon).
    """
    from shapely.geometry import box

    if len(args) == 2:
        # Case 1: Create a bounding box around the centroid point with a buffer
        x, y = args
        minx, miny = x - buffer, y - buffer
        maxx, maxy = x + buffer, y + buffer
        geometry = box(minx, miny, maxx, maxy)

    elif len(args) == 4:
        # Case 2: Create a bounding box directly from the given coordinates
        geometry = box(args[0], args[1], args[2], args[3])

    else:
        raise ValueError(
            "Provide either 2 arguments for centroid (x, y) or 4 arguments for bbox (minx, miny, maxx, maxy)."
        )

    if return_gdf:
        return gpd.GeoDataFrame(geometry=[geometry], columns=["geometry"], crs=crs)
    else:
        return geometry

convert_coordinates(x, y, source_crs, target_crs='epsg:4326')

Convert coordinates from the source EPSG code to the target EPSG code.

Parameters:

Name	Type	Description	Default
x	float	The x-coordinate of the point.	required
y	float	The y-coordinate of the point.	required
source_crs	str	The EPSG code of the source coordinate system.	required
target_crs	str	The EPSG code of the target coordinate system. Defaults to '4326' (EPSG code for WGS84).	'epsg:4326'

Returns:

Type	Description
Tuple[float, float]	A tuple containing the converted longitude and latitude.

Source code in leafmap/common.py

def convert_coordinates(
    x, y, source_crs, target_crs="epsg:4326"
) -> Tuple[float, float]:
    """Convert coordinates from the source EPSG code to the target EPSG code.

    Args:
        x (float): The x-coordinate of the point.
        y (float): The y-coordinate of the point.
        source_crs (str): The EPSG code of the source coordinate system.
        target_crs (str, optional): The EPSG code of the target coordinate system.
            Defaults to '4326' (EPSG code for WGS84).

    Returns:
        A tuple containing the converted longitude and latitude.
    """
    import pyproj

    # Create the transformer
    transformer = pyproj.Transformer.from_crs(source_crs, target_crs, always_xy=True)

    # Perform the transformation
    lon, lat = transformer.transform(x, y)  # pylint: disable=E0633

    # Return the converted coordinates
    return lon, lat

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
Any	The converted LasData object.

Source code in leafmap/common.py

def convert_lidar(
    source, destination=None, point_format_id=None, file_version=None, **kwargs
) -> Any:
    """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:
        The converted LasData object.
    """
    try:
        import laspy
    except ImportError:
        print(
            "The laspy package is required for this function. Use `pip install laspy[lazrs,laszip]` to install it."
        )
        return

    if isinstance(source, str):
        source = read_lidar(source)

    las = laspy.convert(
        source, point_format_id=point_format_id, file_version=file_version
    )

    if destination is None:
        return las
    else:
        destination = check_file_path(destination)
        write_lidar(las, destination, **kwargs)
        return destination

convert_to_cog(images, output_dir, prefix='', suffix='_cog', extra_options=None)

Convert all .tif files in a directory to Cloud Optimized GeoTIFFs (COGs).

Parameters:

Name	Type	Description	Default
images	str | list	Input directory containing .tif files, or a list of .tif file paths.	required
output_dir	str	Path to the output directory where COGs will be saved.	required
prefix	str	Prefix to add to the output filenames.	''
suffix	str	Suffix to add to the output filenames before the .tif extension.	'_cog'
extra_options	List[str]	Additional gdal_translate options. Example: ["-co", "TILED=YES", "-co", "BLOCKSIZE=512"]	None

Source code in leafmap/common.py

def convert_to_cog(
    images: str,
    output_dir: str,
    prefix: str = "",
    suffix: str = "_cog",
    extra_options: Optional[List[str]] = None,
):
    """
    Convert all .tif files in a directory to Cloud Optimized GeoTIFFs (COGs).

    Args:
        images (str | list): Input directory containing .tif files, or a list of .tif file paths.
        output_dir (str): Path to the output directory where COGs will be saved.
        prefix (str): Prefix to add to the output filenames.
        suffix (str): Suffix to add to the output filenames before the .tif extension.
        extra_options (List[str], optional): Additional gdal_translate options.
            Example: ["-co", "TILED=YES", "-co", "BLOCKSIZE=512"]
    """
    import glob

    os.makedirs(output_dir, exist_ok=True)

    if isinstance(images, str):
        tif_files = glob.glob(os.path.join(images, "*.tif"))
    elif isinstance(images, list):
        tif_files = [tif for tif in images if tif.endswith(".tif")]
    else:
        raise ValueError("images must be a string or list of strings")

    if extra_options is None:
        extra_options = []

    for tif in tif_files:
        base = os.path.splitext(os.path.basename(tif))[0]
        out_file = os.path.join(output_dir, f"{prefix}{base}{suffix}.tif")

        cmd = ["gdal_translate", tif, out_file, "-of", "COG", "-co", "COMPRESS=DEFLATE"]
        cmd.extend(extra_options)

        print(f"Converting: {tif} -> {out_file}")
        subprocess.run(cmd, check=True)

convert_to_gdf(data, geometry=None, lat=None, lon=None, crs='EPSG:4326', included=None, excluded=None, obj_to_str=False, open_args=None, **kwargs)

Convert data to a GeoDataFrame.

Parameters:

Name	Type	Description	Default
data	Union[DataFrame, str]	The input data, either as a DataFrame or a file path.	required
geometry	Optional[str]	The column name containing geometry data. Defaults to None.	None
lat	Optional[str]	The column name containing latitude data. Defaults to None.	None
lon	Optional[str]	The column name containing longitude data. Defaults to None.	None
crs	str	The coordinate reference system to use. Defaults to "EPSG:4326".	'EPSG:4326'
included	Optional[List[str]]	List of columns to include. Defaults to None.	None
excluded	Optional[List[str]]	List of columns to exclude. Defaults to None.	None
obj_to_str	bool	Whether to convert object dtype columns to string. Defaults to False.	False
open_args	Optional[Dict[str, Any]]	Additional arguments for file opening functions. Defaults to None.	None
**kwargs	Any	Additional keyword arguments for GeoDataFrame creation.	{}

Returns:

Type	Description
GeoDataFrame	The converted GeoDataFrame.

Raises:

Type	Description
ValueError	If the file format is unsupported or required columns are not provided.

Source code in leafmap/common.py

def convert_to_gdf(
    data: Union[pd.DataFrame, str],
    geometry: Optional[str] = None,
    lat: Optional[str] = None,
    lon: Optional[str] = None,
    crs: str = "EPSG:4326",
    included: Optional[List[str]] = None,
    excluded: Optional[List[str]] = None,
    obj_to_str: bool = False,
    open_args: Optional[Dict[str, Any]] = None,
    **kwargs: Any,
) -> "gpd.GeoDataFrame":
    """Convert data to a GeoDataFrame.

    Args:
        data (Union[pd.DataFrame, str]): The input data, either as a DataFrame or a file path.
        geometry (Optional[str], optional): The column name containing geometry data. Defaults to None.
        lat (Optional[str], optional): The column name containing latitude data. Defaults to None.
        lon (Optional[str], optional): The column name containing longitude data. Defaults to None.
        crs (str, optional): The coordinate reference system to use. Defaults to "EPSG:4326".
        included (Optional[List[str]], optional): List of columns to include. Defaults to None.
        excluded (Optional[List[str]], optional): List of columns to exclude. Defaults to None.
        obj_to_str (bool, optional): Whether to convert object dtype columns to string. Defaults to False.
        open_args (Optional[Dict[str, Any]], optional): Additional arguments for file opening functions. Defaults to None.
        **kwargs (Any): Additional keyword arguments for GeoDataFrame creation.

    Returns:
        The converted GeoDataFrame.

    Raises:
        ValueError: If the file format is unsupported or required columns are not provided.
    """
    import geopandas as gpd
    from shapely.geometry import Point, shape

    if open_args is None:
        open_args = {}

    if not isinstance(data, pd.DataFrame):
        if isinstance(data, str):
            if data.endswith(".parquet"):
                data = pd.read_parquet(data, **open_args)
            elif data.endswith(".csv"):
                data = pd.read_csv(data, **open_args)
            elif data.endswith(".json"):
                data = pd.read_json(data, **open_args)
            elif data.endswith(".xlsx"):
                data = pd.read_excel(data, **open_args)
            else:
                raise ValueError(
                    "Unsupported file format. Only Parquet, CSV, JSON, and Excel files are supported."
                )

    # If include_cols is specified, filter the DataFrame to include only those columns
    if included:
        if geometry:
            included.append(geometry)
        elif lat and lon:
            included.append(lat)
            included.append(lon)
        data = data[included]

    # Exclude specified columns if provided
    if excluded:
        data = data.drop(columns=excluded)

    # Convert 'object' dtype columns to 'string' if obj_to_str is True
    if obj_to_str:
        data = data.astype(
            {col: "string" for col in data.select_dtypes(include="object").columns}
        )

    # Handle the creation of geometry
    if geometry:

        def convert_geometry(x):
            if isinstance(x, str):
                try:
                    # Parse the string as JSON and then convert to a geometry
                    return shape(json.loads(x))
                except (json.JSONDecodeError, TypeError) as e:
                    print(f"Error converting geometry: {e}")
                    return None
            return x

        data = data[data[geometry].notnull()]
        data[geometry] = data[geometry].apply(convert_geometry)
    elif lat and lon:
        # Create a geometry column from latitude and longitude
        data["geometry"] = data.apply(lambda row: Point(row[lon], row[lat]), axis=1)
        geometry = "geometry"
    else:
        raise ValueError(
            "Either geometry_col or both lat_col and lon_col must be provided."
        )

    # Convert the DataFrame to a GeoDataFrame
    gdf = gpd.GeoDataFrame(data, geometry=geometry, **kwargs)

    # Set CRS (assuming WGS84 by default, modify as needed)
    gdf.set_crs(crs, inplace=True)

    return gdf

coords_to_geojson(coords)

Convert a list of bbox coordinates representing [left, bottom, right, top] to geojson FeatureCollection.

Parameters:

Name	Type	Description	Default
coords	list	A list of bbox coordinates representing [left, bottom, right, top].	required

Returns:

Type	Description
Dict[str, Any]	A geojson FeatureCollection.

Source code in leafmap/common.py

def coords_to_geojson(coords: List[Any]) -> Dict[str, Any]:
    """Convert a list of bbox coordinates representing [left, bottom, right, top] to geojson FeatureCollection.

    Args:
        coords (list): A list of bbox coordinates representing [left, bottom, right, top].

    Returns:
        A geojson FeatureCollection.
    """

    features = []
    for bbox in coords:
        features.append(bbox_to_geojson(bbox))
    return {"type": "FeatureCollection", "features": features}

coords_to_vector(coords, output=None, crs='EPSG:4326', **kwargs)

Convert a list of coordinates to a GeoDataFrame or a vector file.

Parameters:

Name	Type	Description	Default
coords	list	A list of coordinates in the format of [(x1, y1), (x2, y2), ...].	required
output	str	The path to the output vector file. Defaults to None.	None
crs	str	The CRS of the coordinates. Defaults to "EPSG:4326".	'EPSG:4326'

Returns:

Type	Description
Any	A GeoDataFrame of the coordinates.

Source code in leafmap/common.py

def coords_to_vector(coords, output=None, crs="EPSG:4326", **kwargs: Any) -> Any:
    """Convert a list of coordinates to a GeoDataFrame or a vector file.

    Args:
        coords (list): A list of coordinates in the format of [(x1, y1), (x2, y2), ...].
        output (str, optional): The path to the output vector file. Defaults to None.
        crs (str, optional): The CRS of the coordinates. Defaults to "EPSG:4326".

    Returns:
        A GeoDataFrame of the coordinates.
    """
    import geopandas as gpd
    from shapely.geometry import Point

    if not isinstance(coords, (list, tuple)):
        raise TypeError("coords must be a list of coordinates")

    if isinstance(coords[0], int) or isinstance(coords[0], float):
        coords = [(coords[0], coords[1])]

    # convert the points to a GeoDataFrame
    geometry = [Point(xy) for xy in coords]
    gdf = gpd.GeoDataFrame(geometry=geometry, crs="EPSG:4326")
    gdf.to_crs(crs, inplace=True)

    if output is not None:
        gdf.to_file(output, **kwargs)
    else:
        return gdf

coords_to_xy(src_fp, coords, coord_crs='epsg:4326', request_payer='bucket-owner', env_args={}, open_args={}, **kwargs)

Converts a list of coordinates to pixel coordinates, i.e., (col, row) coordinates.

Parameters:

Name	Type	Description	Default
src_fp	str	The source raster file path.	required
coords	list	A list of coordinates in the format of [[x1, y1], [x2, y2], ...]	required
coord_crs	str	The coordinate CRS of the input coordinates. Defaults to "epsg:4326".	'epsg:4326'
request_payer	str	Specifies who pays for the download from S3. Can be "bucket-owner" or "requester". Defaults to "bucket-owner".	'bucket-owner'
env_args	dict	Additional keyword arguments to pass to rasterio.Env.	{}
open_args	dict	Additional keyword arguments to pass to rasterio.open.	{}
**kwargs	Any	Additional keyword arguments to pass to rasterio.transform.rowcol.	{}

Returns:

Type	Description
list	A list of pixel coordinates in the format of [[x1, y1], [x2, y2], ...]

Source code in leafmap/common.py

def coords_to_xy(
    src_fp: str,
    coords: list,
    coord_crs: str = "epsg:4326",
    request_payer="bucket-owner",
    env_args={},
    open_args={},
    **kwargs: Any,
) -> list:
    """Converts a list of coordinates to pixel coordinates, i.e., (col, row) coordinates.

    Args:
        src_fp (str): The source raster file path.
        coords (list): A list of coordinates in the format of [[x1, y1], [x2, y2], ...]
        coord_crs (str): The coordinate CRS of the input coordinates. Defaults to "epsg:4326".
        request_payer (str): Specifies who pays for the download from S3.
            Can be "bucket-owner" or "requester". Defaults to "bucket-owner".
        env_args (dict): Additional keyword arguments to pass to rasterio.Env.
        open_args (dict): Additional keyword arguments to pass to rasterio.open.
        **kwargs (Any): Additional keyword arguments to pass to rasterio.transform.rowcol.

    Returns:
        A list of pixel coordinates in the format of [[x1, y1], [x2, y2], ...]
    """
    import numpy as np
    import rasterio

    if isinstance(coords, np.ndarray):
        coords = coords.tolist()

    if len(coords) == 4 and all([isinstance(c, (int, float)) for c in coords]):
        coords = [[coords[0], coords[1]], [coords[2], coords[3]]]

    xs, ys = zip(*coords)
    with rasterio.Env(AWS_REQUEST_PAYER=request_payer, **env_args):
        with rasterio.open(src_fp, **open_args) as src:
            width = src.width
            height = src.height
            if coord_crs != src.crs:
                xs, ys = transform_coords(
                    xs, ys, coord_crs, src.crs, **kwargs
                )  # pylint: disable=E0633
            rows, cols = rasterio.transform.rowcol(src.transform, xs, ys, **kwargs)
        result = [[col, row] for col, row in zip(cols, rows)]

        result = [
            [x, y] for x, y in result if x >= 0 and y >= 0 and x < width and y < height
        ]
        if len(result) == 0:
            print("No valid pixel coordinates found.")
        elif len(result) < len(coords):
            print("Some coordinates are out of the image boundary.")

        return result

create_code_cell(code='', where='below')

Creates a code cell in the IPython Notebook.

Parameters:

Name	Type	Description	Default
code	str	Code to fill the new code cell with. Defaults to ''.	''
where	str	Where to add the new code cell. It can be one of the following: above, below, at_bottom. Defaults to 'below'.	'below'

Source code in leafmap/common.py

def create_code_cell(code: str = "", where: str = "below") -> None:
    """Creates a code cell in the IPython Notebook.

    Args:
        code (str, optional): Code to fill the new code cell with. Defaults to ''.
        where (str, optional): Where to add the new code cell. It can be one of the following: above, below, at_bottom. Defaults to 'below'.
    """

    import base64

    # try:
    #     import pyperclip
    # except ImportError:
    #     install_package("pyperclip")
    #     import pyperclip
    from IPython.display import Javascript, display

    # try:
    #     pyperclip.copy(str(code))
    # except Exception as e:
    #     pass

    encoded_code = (base64.b64encode(str.encode(code))).decode()
    display(Javascript("""
        var code = IPython.notebook.insert_cell_{0}('code');
        code.set_text(atob("{1}"));
    """.format(where, encoded_code)))

create_download_link(filename, title='Click here to download: ', basename=None)

Downloads a file from voila. Adopted from https://github.com/voila-dashboards/voila/issues/578

Parameters:

Name	Type	Description	Default
filename	str	The file path to the file to download	required
title	str	str. Defaults to "Click here to download: ".	'Click here to download: '

Returns:

Type	Description
Any	HTML download URL.

Source code in leafmap/common.py

def create_download_link(
    filename: str,
    title: str = "Click here to download: ",
    basename: Optional[str] = None,
) -> Any:
    """Downloads a file from voila. Adopted from https://github.com/voila-dashboards/voila/issues/578

    Args:
        filename (str): The file path to the file to download
        title (str, optional): str. Defaults to "Click here to download: ".

    Returns:
        HTML download URL.
    """
    import base64

    from IPython.display import HTML

    data = open(filename, "rb").read()
    b64 = base64.b64encode(data)
    payload = b64.decode()
    if basename is None:
        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_legend(title='Legend', labels=None, colors=None, legend_dict=None, builtin_legend=None, opacity=1.0, position='bottomright', draggable=True, output=None, style={}, shape_type='rectangle')

Create a legend in HTML format. Reference: https://bit.ly/3oV6vnH

Parameters:

Name	Type	Description	Default
title	str	Title of the legend. Defaults to 'Legend'. Defaults to "Legend".	'Legend'
colors	list	A list of legend colors. Defaults to None.	None
labels	list	A list of legend labels. Defaults to None.	None
legend_dict	dict	A dictionary containing legend items as keys and color as values. If provided, legend_keys and legend_colors will be ignored. Defaults to None.	None
builtin_legend	str	Name of the builtin legend to add to the map. Defaults to None.	None
opacity	float	The opacity of the legend. Defaults to 1.0.	1.0
position	str	The position of the legend, can be one of the following: "topleft", "topright", "bottomleft", "bottomright". Defaults to "bottomright".	'bottomright'
draggable	bool	If True, the legend can be dragged to a new position. Defaults to True.	True
output	str	The output file path (*.html) to save the legend. Defaults to None.	None
style	dict	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:

Type	Description
str	The HTML code of the legend.

Source code in leafmap/common.py

def create_legend(
    title="Legend",
    labels=None,
    colors=None,
    legend_dict=None,
    builtin_legend=None,
    opacity=1.0,
    position="bottomright",
    draggable=True,
    output=None,
    style={},
    shape_type="rectangle",
) -> str:
    """Create a legend in HTML format. Reference: https://bit.ly/3oV6vnH

    Args:
        title (str, optional): Title of the legend. Defaults to 'Legend'. Defaults to "Legend".
        colors (list, optional): A list of legend colors. Defaults to None.
        labels (list, optional): A list of legend labels. Defaults to None.
        legend_dict (dict, optional): A dictionary containing legend items as keys and color as values.
            If provided, legend_keys and legend_colors will be ignored. Defaults to None.
        builtin_legend (str, optional): Name of the builtin legend to add to the map. Defaults to None.
        opacity (float, optional): The opacity of the legend. Defaults to 1.0.
        position (str, optional): The position of the legend, can be one of the following:
            "topleft", "topright", "bottomleft", "bottomright". Defaults to "bottomright".
        draggable (bool, optional): If True, the legend can be dragged to a new position. Defaults to True.
        output (str, optional): The output file path (*.html) to save the legend. Defaults to None.
        style (dict): 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:
        The HTML code of the legend.
    """

    import importlib.resources

    from .legends import builtin_legends

    pkg_dir = os.path.dirname(importlib.resources.files("leafmap") / "leafmap.py")
    legend_template = os.path.join(pkg_dir, "data/template/legend_style.html")

    if draggable:
        legend_template = os.path.join(pkg_dir, "data/template/legend.txt")

    if not os.path.exists(legend_template):
        raise FileNotFoundError("The legend template does not exist.")

    if labels is not None:
        if not isinstance(labels, list):
            print("The legend keys must be a list.")
            return
    else:
        labels = ["One", "Two", "Three", "Four", "etc"]

    if colors is not None:
        if not isinstance(colors, list):
            print("The legend colors must be a list.")
            return
        elif all(isinstance(item, tuple) for item in colors):
            try:
                colors = [rgb_to_hex(x) for x in colors]
            except Exception as e:
                print(e)
        elif all((item.startswith("#") and len(item) == 7) for item in colors):
            pass
        elif all((len(item) == 6) for item in colors):
            pass
        else:
            print("The legend colors must be a list of tuples.")
            return
    else:
        colors = [
            "#8DD3C7",
            "#FFFFB3",
            "#BEBADA",
            "#FB8072",
            "#80B1D3",
        ]

    if len(labels) != len(colors):
        print("The legend keys and values must be the same length.")
        return

    allowed_builtin_legends = builtin_legends.keys()
    if builtin_legend is not None:
        if builtin_legend not in allowed_builtin_legends:
            print(
                "The builtin legend must be one of the following: {}".format(
                    ", ".join(allowed_builtin_legends)
                )
            )
            return
        else:
            legend_dict = builtin_legends[builtin_legend]
            labels = list(legend_dict.keys())
            colors = list(legend_dict.values())

    if legend_dict is not None:
        if not isinstance(legend_dict, dict):
            print("The legend dict must be a dictionary.")
            return
        else:
            labels = list(legend_dict.keys())
            colors = list(legend_dict.values())
            if all(isinstance(item, tuple) for item in colors):
                try:
                    colors = [rgb_to_hex(x) for x in colors]
                except Exception as e:
                    print(e)

    allowed_positions = [
        "topleft",
        "topright",
        "bottomleft",
        "bottomright",
    ]
    if position not in allowed_positions:
        raise ValueError(
            "The position must be one of the following: {}".format(
                ", ".join(allowed_positions)
            )
        )

    if position == "bottomright":
        if "bottom" not in style:
            style["bottom"] = "20px"
        if "right" not in style:
            style["right"] = "5px"
        if "left" in style:
            del style["left"]
        if "top" in style:
            del style["top"]
    elif position == "bottomleft":
        if "bottom" not in style:
            style["bottom"] = "5px"
        if "left" not in style:
            style["left"] = "5px"
        if "right" in style:
            del style["right"]
        if "top" in style:
            del style["top"]
    elif position == "topright":
        if "top" not in style:
            style["top"] = "5px"
        if "right" not in style:
            style["right"] = "5px"
        if "left" in style:
            del style["left"]
        if "bottom" in style:
            del style["bottom"]
    elif position == "topleft":
        if "top" not in style:
            style["top"] = "5px"
        if "left" not in style:
            style["left"] = "5px"
        if "right" in style:
            del style["right"]
        if "bottom" in style:
            del style["bottom"]

    if "position" not in style:
        style["position"] = "fixed"
    if "z-index" not in style:
        style["z-index"] = "9999"
    if "background-color" not in style:
        style["background-color"] = "rgba(255, 255, 255, 0.8)"
    if "padding" not in style:
        style["padding"] = "10px"
    if "border-radius" not in style:
        style["border-radius"] = "5px"
    if "font-size" not in style:
        style["font-size"] = "14px"

    content = []

    with open(legend_template) as f:
        lines = f.readlines()

    if draggable:
        for index, line in enumerate(lines):
            if index < 36:
                content.append(line)
            elif index == 36:
                line = lines[index].replace("Legend", title)
                content.append(line)
            elif index < 39:
                content.append(line)
            elif index == 39:
                for i, color in enumerate(colors):
                    item = f"    <li><span style='background:{check_color(color)};opacity:{opacity};'></span>{labels[i]}</li>\n"
                    content.append(item)
            elif index > 41:
                content.append(line)
        content = content[3:-1]

    else:
        for index, line in enumerate(lines):
            if index < 8:
                content.append(line)
            elif index == 8:
                for key, value in style.items():
                    content.append(
                        "              {}: {};\n".format(key.replace("_", "-"), value)
                    )
            elif index < 17:
                pass
            elif index < 19:
                content.append(line)
            elif index == 19:
                content.append(line.replace("Legend", title))
            elif index < 22:
                content.append(line)
            elif index == 22:
                for index, key in enumerate(labels):
                    color = colors[index]
                    if not color.startswith("#"):
                        color = "#" + color
                    item = "                    <li><span style='background:{};opacity:{};'></span>{}</li>\n".format(
                        color, opacity, key
                    )
                    content.append(item)
            elif index < 33:
                pass
            else:
                content.append(line)

    legend_text = "".join(content)
    if shape_type == "circle":
        legend_text = legend_text.replace("width: 30px", "width: 16px")
        legend_text = legend_text.replace(
            "border: 1px solid #999;",
            "border-radius: 50%;\n      border: 1px solid #999;",
        )
    elif shape_type == "line":
        legend_text = legend_text.replace("height: 16px", "height: 3px")

    if output is not None:
        with open(output, "w") as f:
            f.write(legend_text)
    else:
        return legend_text

create_lines_from_points(src_points, dst_points, col='id', distance_col='distance', decimal_places=2, return_gdf=False)

Create LineString features between matching point features from two GeoJSON FeatureCollections based on a shared column (default is 'id').

Parameters:

Name	Type	Description	Default
src_points	Union[dict, str, GeoDataFrame]	Source GeoJSON FeatureCollection with point features.	required
dst_points	Union[dict, str, GeoDataFrame]	Destination GeoJSON FeatureCollection with point features.	required
col	str	The property name to match features between the two collections.	'id'
distance_col	str	The name of the column to store the distance between the points.	'distance'
decimal_places	int	The number of decimal places to round the distance to.	2
return_gdf	bool	If True, returns a GeoDataFrame instead of a dictionary. Defaults to False.	False

Returns:

Type	Description
dict	A GeoJSON FeatureCollection containing LineString features.

Source code in leafmap/common.py

def create_lines_from_points(
    src_points: Union[dict, str, "gpd.GeoDataFrame"],
    dst_points: Union[dict, str, "gpd.GeoDataFrame"],
    col: str = "id",
    distance_col: str = "distance",
    decimal_places: int = 2,
    return_gdf: bool = False,
) -> dict:
    """
    Create LineString features between matching point features from two GeoJSON FeatureCollections
    based on a shared column (default is 'id').

    Parameters:
        src_points (Union[dict, str, gpd.GeoDataFrame]): Source GeoJSON FeatureCollection with point features.
        dst_points (Union[dict, str, gpd.GeoDataFrame]): Destination GeoJSON FeatureCollection with point features.
        col (str): The property name to match features between the two collections.
        distance_col (str): The name of the column to store the distance between the points.
        decimal_places (int): The number of decimal places to round the distance to.
        return_gdf (bool): If True, returns a GeoDataFrame instead of a dictionary. Defaults to False.

    Returns:
        A GeoJSON FeatureCollection containing LineString features.
    """
    import geopandas as gpd

    # Convert inputs to GeoJSON FeatureCollections if necessary
    if isinstance(src_points, str):
        src_points = read_vector(src_points).__geo_interface__
    elif isinstance(src_points, gpd.GeoDataFrame):
        src_points = src_points.__geo_interface__

    if isinstance(dst_points, str):
        dst_points = read_vector(dst_points).__geo_interface__
    elif isinstance(dst_points, gpd.GeoDataFrame):
        dst_points = dst_points.__geo_interface__

    # Build a lookup from col value to coordinates in dst_points
    dst_lookup = {
        feature[col] if col in feature else feature["properties"][col]: feature[
            "geometry"
        ]["coordinates"]
        for feature in dst_points["features"]
    }

    lines = []
    for feature in src_points["features"]:
        match_value = feature[col] if col in feature else feature["properties"][col]
        coords1 = feature["geometry"]["coordinates"]
        coords2 = dst_lookup.get(match_value)

        if coords2:
            line = {
                "type": "Feature",
                "geometry": {"type": "LineString", "coordinates": [coords1, coords2]},
                "properties": {col: match_value, **feature.get("properties", {})},
            }
            lines.append(line)

    gdf = gpd.GeoDataFrame.from_features(lines, crs="EPSG:4326")
    if distance_col:
        gdf_proj = gdf.to_crs("EPSG:3857")
        gdf[distance_col] = gdf_proj.length.round(decimal_places)

    if return_gdf:
        return gdf
    else:
        return gdf.__geo_interface__

create_mosaicjson(images, output)

Create a mosaicJSON file from a list of images.

Parameters:

Name	Type	Description	Default
images	str | list	A list of image URLs or a URL to a text file containing a list of image URLs.	required
output	str	The output mosaicJSON file path.	required

Source code in leafmap/stac.py

def create_mosaicjson(images, output):
    """Create a mosaicJSON file from a list of images.

    Args:
        images (str | list): A list of image URLs or a URL to a text file containing a list of image URLs.
        output (str): The output mosaicJSON file path.

    """
    try:
        from cogeo_mosaic.backends import MosaicBackend
        from cogeo_mosaic.mosaic import MosaicJSON
    except ImportError:
        raise ImportError(
            "cogeo-mosaic is required to use this function. "
            "Install with `pip install cogeo-mosaic`."
        )

    if isinstance(images, str):
        if images.startswith("http"):
            import urllib.request

            with urllib.request.urlopen(images) as f:
                file_contents = f.read().decode("utf-8")
                images = file_contents.strip().split("\n")
        elif not os.path.exists(images):
            raise FileNotFoundError(f"{images} does not exist.")

    elif not isinstance(images, list):
        raise ValueError("images must be a list or a URL.")

    mosaic = MosaicJSON.from_urls(images)
    with MosaicBackend(output, mosaic_def=mosaic) as f:
        f.write(overwrite=True)

create_timelapse(images, out_gif, ext='.tif', bands=None, size=None, bbox=None, fps=5, loop=0, add_progress_bar=True, progress_bar_color='blue', progress_bar_height=5, add_text=False, text_xy=None, text_sequence=None, font_type='arial.ttf', font_size=20, font_color='black', mp4=False, quiet=True, reduce_size=False, clean_up=True, **kwargs)

Creates a timelapse gif from a list of images.

Parameters:

Name	Type	Description	Default
images	list | str	The list of images or input directory to create the gif from. For example, '/path/to/images/*.tif' or ['/path/to/image1.tif', '/path/to/image2.tif', ...]	required
out_gif	str	File path to the output gif.	required
ext	str	The extension of the images. Defaults to '.tif'.	'.tif'
bands	list	The bands to use for the gif. For example, [0, 1, 2] for RGB, and [0] for grayscale. Defaults to None.	None
size	tuple	The size of the gif. For example, (500, 500). Defaults to None, using the original size.	None
bbox	list	The bounding box of the gif. For example, [xmin, ymin, xmax, ymax]. Defaults to None, using the original bounding box.	None
fps	int	The frames per second of the gif. Defaults to 5.	5
loop	int	The number of times to loop the gif. Defaults to 0, looping forever.	0
add_progress_bar	bool	Whether to add a progress bar to the gif. Defaults to True.	True
progress_bar_color	str	The color of the progress bar, can be color name or hex code. Defaults to 'blue'.	'blue'
progress_bar_height	int	The height of the progress bar. Defaults to 5.	5
add_text	bool	Whether to add text to the gif. Defaults to False.	False
text_xy	tuple	The x, y coordinates of the text. For example, ('10%', '10%'). Defaults to None, using the bottom left corner.	None
text_sequence	list	The sequence of text to add to the gif. For example, ['year 1', 'year 2', ...].	None
font_type	str	The font type of the text, can be 'arial.ttf' or 'alibaba.otf', or any system font. Defaults to 'arial.ttf'.	'arial.ttf'
font_size	int	The font size of the text. Defaults to 20.	20
font_color	str	The color of the text, can be color name or hex code. Defaults to 'black'.	'black'
mp4	bool	Whether to convert the gif to mp4. Defaults to False.	False
quiet	bool	Whether to print the progress. Defaults to False.	True
reduce_size	bool	Whether to reduce the size of the gif using ffmpeg. Defaults to False.	False
clean_up	bool	Whether to clean up the temporary files. Defaults to True.	True

Source code in leafmap/common.py

def create_timelapse(
    images: Union[List, str],
    out_gif: str,
    ext: str = ".tif",
    bands: Optional[List] = None,
    size: Optional[Tuple] = None,
    bbox: Optional[List] = None,
    fps: int = 5,
    loop: int = 0,
    add_progress_bar: bool = True,
    progress_bar_color: str = "blue",
    progress_bar_height: int = 5,
    add_text: bool = False,
    text_xy: Optional[Tuple] = None,
    text_sequence: Optional[List] = None,
    font_type: str = "arial.ttf",
    font_size: int = 20,
    font_color: str = "black",
    mp4: bool = False,
    quiet: bool = True,
    reduce_size: bool = False,
    clean_up: bool = True,
    **kwargs: Any,
):
    """Creates a timelapse gif from a list of images.

    Args:
        images (list | str): The list of images or input directory to create the gif from.
            For example, '/path/to/images/*.tif' or ['/path/to/image1.tif', '/path/to/image2.tif', ...]
        out_gif (str): File path to the output gif.
        ext (str, optional): The extension of the images. Defaults to '.tif'.
        bands (list, optional): The bands to use for the gif. For example, [0, 1, 2] for RGB, and [0] for grayscale. Defaults to None.
        size (tuple, optional): The size of the gif. For example, (500, 500). Defaults to None, using the original size.
        bbox (list, optional): The bounding box of the gif. For example, [xmin, ymin, xmax, ymax]. Defaults to None, using the original bounding box.
        fps (int, optional): The frames per second of the gif. Defaults to 5.
        loop (int, optional): The number of times to loop the gif. Defaults to 0, looping forever.
        add_progress_bar (bool, optional): Whether to add a progress bar to the gif. Defaults to True.
        progress_bar_color (str, optional): The color of the progress bar, can be color name or hex code. Defaults to 'blue'.
        progress_bar_height (int, optional): The height of the progress bar. Defaults to 5.
        add_text (bool, optional): Whether to add text to the gif. Defaults to False.
        text_xy (tuple, optional): The x, y coordinates of the text. For example, ('10%', '10%').
            Defaults to None, using the bottom left corner.
        text_sequence (list, optional): The sequence of text to add to the gif. For example, ['year 1', 'year 2', ...].
        font_type (str, optional): The font type of the text, can be 'arial.ttf' or 'alibaba.otf', or any system font. Defaults to 'arial.ttf'.
        font_size (int, optional): The font size of the text. Defaults to 20.
        font_color (str, optional): The color of the text, can be color name or hex code. Defaults to 'black'.
        mp4 (bool, optional): Whether to convert the gif to mp4. Defaults to False.
        quiet (bool, optional): Whether to print the progress. Defaults to False.
        reduce_size (bool, optional): Whether to reduce the size of the gif using ffmpeg. Defaults to False.
        clean_up (bool, optional): Whether to clean up the temporary files. Defaults to True.

    """

    import glob
    import tempfile

    if isinstance(images, str):
        if not images.endswith(ext):
            images = os.path.join(images, f"*{ext}")
        images = list(glob.glob(images))

    if not isinstance(images, list):
        raise ValueError("images must be a list or a path to the image directory.")

    images.sort()

    temp_dir = os.path.join(tempfile.gettempdir(), "timelapse")
    if not os.path.exists(temp_dir):
        os.makedirs(temp_dir)

    if bbox is not None:
        clip_dir = os.path.join(tempfile.gettempdir(), "clip")
        if not os.path.exists(clip_dir):
            os.makedirs(clip_dir)

        if len(bbox) == 4:
            bbox = bbox_to_geojson(bbox)

    else:
        clip_dir = None

    output = widgets.Output()

    if "out_ext" in kwargs:
        out_ext = kwargs["out_ext"].lower()
    else:
        out_ext = ".jpg"

    try:
        for index, image in enumerate(images):
            if bbox is not None:
                clip_file = os.path.join(clip_dir, os.path.basename(image))
                with output:
                    clip_image(image, mask=bbox, output=clip_file, to_cog=False)
                image = clip_file

            if "add_prefix" in kwargs:
                basename = (
                    str(f"{index + 1}").zfill(len(str(len(images))))
                    + "-"
                    + os.path.basename(image).replace(ext, out_ext)
                )
            else:
                basename = os.path.basename(image).replace(ext, out_ext)
            if not quiet:
                print(f"Processing {index+1}/{len(images)}: {basename} ...")

            # ignore GDAL warnings
            with output:
                numpy_to_image(
                    image, os.path.join(temp_dir, basename), bands=bands, size=size
                )
        make_gif(
            temp_dir,
            out_gif,
            ext=out_ext,
            fps=fps,
            loop=loop,
            mp4=mp4,
            clean_up=clean_up,
        )

        if clip_dir is not None:
            shutil.rmtree(clip_dir)

        if add_text:
            add_text_to_gif(
                out_gif,
                out_gif,
                text_xy,
                text_sequence,
                font_type,
                font_size,
                font_color,
                add_progress_bar,
                progress_bar_color,
                progress_bar_height,
                1000 / fps,
                loop,
            )
        elif add_progress_bar:
            add_progress_bar_to_gif(
                out_gif,
                out_gif,
                progress_bar_color,
                progress_bar_height,
                1000 / fps,
                loop,
            )

        if reduce_size:
            reduce_gif_size(out_gif)
    except Exception as e:
        print(e)

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/opengeos/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 leafmap/common.py

def csv_points_to_shp(
    in_csv: str, out_shp: str, latitude: str = "latitude", longitude: str = "longitude"
) -> None:
    """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/opengeos/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'.

    """

    if in_csv.startswith("http") and in_csv.endswith(".csv"):
        out_dir = os.path.join(os.path.expanduser("~"), "Downloads")
        out_name = os.path.basename(in_csv)

        if not os.path.exists(out_dir):
            os.makedirs(out_dir)
        download_from_url(in_csv, out_dir=out_dir)
        in_csv = os.path.join(out_dir, out_name)

    wbt = whitebox.WhiteboxTools()
    in_csv = os.path.abspath(in_csv)
    out_shp = os.path.abspath(out_shp)

    if not os.path.exists(in_csv):
        raise Exception("The provided csv file does not exist.")

    with open(in_csv, encoding="utf-8") as csv_file:
        reader = csv.DictReader(csv_file)
        fields = reader.fieldnames
        xfield = fields.index(longitude)
        yfield = fields.index(latitude)

    wbt.csv_points_to_vector(in_csv, out_shp, xfield=xfield, yfield=yfield, epsg=4326)

csv_to_df(in_csv, **kwargs)

Converts a CSV file to pandas dataframe.

Parameters:

Name	Type	Description	Default
in_csv	str	File path to the input CSV.	required

Returns:

Type	Description
DataFrame	A pandas DataFrame.

Source code in leafmap/common.py

def csv_to_df(in_csv, **kwargs: Any) -> pd.DataFrame:
    """Converts a CSV file to pandas dataframe.

    Args:
        in_csv (str): File path to the input CSV.

    Returns:
        A pandas DataFrame.
    """
    import pandas as pd

    try:
        return pd.read_csv(in_csv, **kwargs)
    except Exception as e:
        raise Exception(e)

csv_to_gdf(in_csv, latitude='latitude', longitude='longitude', geometry=None, crs='EPSG:4326', encoding='utf-8', **kwargs)

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'
geometry	str	The name of the column containing geometry. Defaults to None.	None
crs	str	The coordinate reference system. Defaults to "EPSG:4326".	'EPSG:4326'
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'

Returns:

Type	Description
GeoDataFrame	A GeoDataFrame.

Source code in leafmap/common.py

def csv_to_gdf(
    in_csv,
    latitude="latitude",
    longitude="longitude",
    geometry=None,
    crs="EPSG:4326",
    encoding="utf-8",
    **kwargs: Any,
) -> "gpd.GeoDataFrame":
    """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".
        geometry (str, optional): The name of the column containing geometry. Defaults to None.
        crs (str, optional): The coordinate reference system. Defaults to "EPSG:4326".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".

    Returns:
        A GeoDataFrame.
    """

    check_package(name="geopandas", URL="https://geopandas.org")

    import geopandas as gpd
    import pandas as pd
    from shapely import wkt

    out_dir = os.getcwd()

    if geometry is None:
        out_geojson = os.path.join(out_dir, random_string() + ".geojson")
        csv_to_geojson(in_csv, out_geojson, latitude, longitude, encoding=encoding)

        gdf = gpd.read_file(out_geojson)
        os.remove(out_geojson)
    else:
        df = pd.read_csv(in_csv, encoding=encoding)
        df["geometry"] = df[geometry].apply(wkt.loads)
        gdf = gpd.GeoDataFrame(df, geometry="geometry", crs=crs, **kwargs)
    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 leafmap/common.py

def csv_to_geojson(
    in_csv: str,
    out_geojson: Optional[str] = None,
    latitude: str = "latitude",
    longitude: str = "longitude",
    encoding: str = "utf-8",
) -> Optional[Dict[str, Any]]:
    """Creates points for a CSV file and exports data as a GeoJSON.

    Args:
        in_csv (str): The file path to the input CSV file.
        out_geojson (str): The file path to the exported GeoJSON. Default to None.
        latitude (str, optional): The name of the column containing latitude coordinates. Defaults to "latitude".
        longitude (str, optional): The name of the column containing longitude coordinates. Defaults to "longitude".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".

    """

    import pandas as pd

    in_csv = github_raw_url(in_csv)

    if out_geojson is not None:
        out_geojson = check_file_path(out_geojson)

    df = pd.read_csv(in_csv)
    geojson = df_to_geojson(
        df, latitude=latitude, longitude=longitude, encoding=encoding
    )

    if out_geojson is None:
        return geojson
    else:
        with open(out_geojson, "w", encoding=encoding) as f:
            f.write(json.dumps(geojson))

csv_to_shp(in_csv, out_shp, latitude='latitude', longitude='longitude', encoding='utf-8')

Converts a csv file with latlon info to a point shapefile.

Parameters:

Name	Type	Description	Default
in_csv	str	The input csv file containing longitude and latitude columns.	required
out_shp	str	The file path to the output shapefile.	required
latitude	str	The column name of the latitude column. Defaults to 'latitude'.	'latitude'
longitude	str	The column name of the longitude column. Defaults to 'longitude'.	'longitude'

Source code in leafmap/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'.
    """
    try:
        import shapefile as shp
    except ImportError:
        install_package("pyshp")
        import shapefile as shp

    if in_csv.startswith("http") and in_csv.endswith(".csv"):
        in_csv = github_raw_url(in_csv)
        in_csv = download_file(in_csv, quiet=True, overwrite=True)

    try:
        points = shp.Writer(out_shp, shapeType=shp.POINT)
        with open(in_csv, encoding=encoding) as csvfile:
            csvreader = csv.DictReader(csvfile)
            header = csvreader.fieldnames
            [points.field(field) for field in header]
            for row in csvreader:
                points.point((float(row[longitude])), (float(row[latitude])))
                points.record(*tuple([row[f] for f in header]))

        out_prj = out_shp.replace(".shp", ".prj")
        with open(out_prj, "w") as f:
            prj_str = 'GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Degree",0.0174532925199433]] '
            f.write(prj_str)

    except Exception as e:
        raise Exception(e)

csv_to_vector(in_csv, output, latitude='latitude', longitude='longitude', geometry=None, crs='EPSG:4326', 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'
geometry	str	The name of the column containing geometry. Defaults to None.	None
crs	str	The coordinate reference system. Defaults to "EPSG:4326".	'EPSG:4326'
encoding	str	The encoding of characters. Defaults to "utf-8".	'utf-8'
**kwargs	Any	Additional keyword arguments to pass to gdf.to_file().	{}

Source code in leafmap/common.py

def csv_to_vector(
    in_csv,
    output,
    latitude="latitude",
    longitude="longitude",
    geometry=None,
    crs="EPSG:4326",
    encoding="utf-8",
    **kwargs: Any,
):
    """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".
        geometry (str, optional): The name of the column containing geometry. Defaults to None.
        crs (str, optional): The coordinate reference system. Defaults to "EPSG:4326".
        encoding (str, optional): The encoding of characters. Defaults to "utf-8".
        **kwargs: Additional keyword arguments to pass to gdf.to_file().

    """
    gdf = csv_to_gdf(in_csv, latitude, longitude, geometry, crs, encoding)
    gdf.to_file(output, **kwargs)

d2s_tile(url, titiler_endpoint=None, **kwargs)

Generate a D2S tile URL with optional API key.

Parameters:

Name	Type	Description	Default
url	str	The base URL for the tile.	required
titiler_endpoint	str	The endpoint for the titiler service. Defaults to "https://tt.d2s.org".	None
**kwargs	Any	Additional keyword arguments to pass to the cog_stats function.	{}

Returns:

Type	Description
str	The modified URL with the API key if required, otherwise the original URL.

Raises:

Type	Description
ValueError	If the API key is required but not set in the environment variables.

Source code in leafmap/common.py

def d2s_tile(url: str, titiler_endpoint: str = None, **kwargs: Any) -> str:
    """Generate a D2S tile URL with optional API key.

    Args:
        url (str): The base URL for the tile.
        titiler_endpoint (str, optional): The endpoint for the titiler service.
            Defaults to "https://tt.d2s.org".
        **kwargs (Any): Additional keyword arguments to pass to the cog_stats function.

    Returns:
        The modified URL with the API key if required, otherwise the original URL.

    Raises:
        ValueError: If the API key is required but not set in the environment variables.
    """

    if titiler_endpoint is None:
        titiler_endpoint = os.environ.get(
            "TITILER_ENDPOINT", "https://giswqs-titiler-endpoint.hf.space"
        )

    stats = cog_stats(url, titiler_endpoint=titiler_endpoint, **kwargs)
    if "detail" in stats:
        api_key = get_api_key("D2S_API_KEY")
        if api_key is None:
            raise ValueError("Please set the D2S_API_KEY environment variable.")
        else:
            return f"{url}?API_KEY={api_key}"
    else:
        return 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 True.	False

Source code in leafmap/common.py

def delete_shp(in_shp: str, verbose: bool = False) -> None:
    """Deletes a shapefile.

    Args:
        in_shp (str): The input shapefile to delete.
        verbose (bool, optional): Whether to print out descriptive text. Defaults to True.
    """
    from pathlib import Path

    in_shp = os.path.abspath(in_shp)
    in_dir = os.path.dirname(in_shp)
    basename = os.path.basename(in_shp).replace(".shp", "")

    files = Path(in_dir).rglob(basename + ".*")

    for file in files:
        filepath = os.path.join(in_dir, str(file))
        os.remove(filepath)
        if verbose:
            print(f"Deleted {filepath}")

df_to_gdf(df, geometry='geometry', src_crs='EPSG:4326', dst_crs=None, **kwargs)

Converts a pandas DataFrame to a GeoPandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	The pandas DataFrame to convert.	required
geometry	str	The name of the geometry column in the DataFrame.	'geometry'
src_crs	str	The coordinate reference system (CRS) of the GeoDataFrame. Default is "EPSG:4326".	'EPSG:4326'
dst_crs	str	The target CRS of the GeoDataFrame. Default is None	None

Returns:

Type	Description
Any	The converted GeoPandas GeoDataFrame.

Source code in leafmap/common.py

def df_to_gdf(
    df, geometry="geometry", src_crs="EPSG:4326", dst_crs=None, **kwargs: Any
) -> Any:
    """
    Converts a pandas DataFrame to a GeoPandas GeoDataFrame.

    Args:
        df (pandas.DataFrame): The pandas DataFrame to convert.
        geometry (str): The name of the geometry column in the DataFrame.
        src_crs (str): The coordinate reference system (CRS) of the GeoDataFrame. Default is "EPSG:4326".
        dst_crs (str): The target CRS of the GeoDataFrame. Default is None

    Returns:
        The converted GeoPandas GeoDataFrame.
    """
    import geopandas as gpd
    from shapely import wkt

    # Convert the geometry column to Shapely geometry objects
    df[geometry] = df[geometry].apply(lambda x: wkt.loads(x))

    # Convert the pandas DataFrame to a GeoPandas GeoDataFrame
    gdf = gpd.GeoDataFrame(df, geometry=geometry, crs=src_crs, **kwargs)
    if dst_crs is not None and dst_crs != src_crs:
        gdf = gdf.to_crs(dst_crs)

    return gdf

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 leafmap/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".

    """

    import json

    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_json(data, file_path, indent=4)

Writes a dictionary to a JSON file.

Parameters:

Name	Type	Description	Default
data	dict	A dictionary.	required
file_path	str	The path to the JSON file.	required
indent	int	The indentation of the JSON file. Defaults to 4.	4

Raises:

Type	Description
TypeError	If the input data is not a dictionary.

Source code in leafmap/common.py

def dict_to_json(data, file_path, indent=4):
    """Writes a dictionary to a JSON file.

    Args:
        data (dict): A dictionary.
        file_path (str): The path to the JSON file.
        indent (int, optional): The indentation of the JSON file. Defaults to 4.

    Raises:
        TypeError: If the input data is not a dictionary.
    """
    import json

    file_path = check_file_path(file_path)

    if isinstance(data, dict):
        with open(file_path, "w") as f:
            json.dump(data, f, indent=indent)
    else:
        raise TypeError("The provided data must be a dictionary.")

disjoint(input_features, selecting_features, output=None, **kwargs)

Find the features in the input_features that do not intersect the selecting_features.

Parameters:

Name	Type	Description	Default
input_features	str | GeoDataFrame	The input features to select from. Can be a file path or a GeoDataFrame.	required
selecting_features	str | GeoDataFrame	The features in the Input Features parameter will be selected based on their relationship to the features from this layer.	required
output	are	The output path to save the GeoDataFrame in a vector format (e.g., shapefile). Defaults to None.	None

Returns:

Type	Description
Any	The path to the output file or the GeoDataFrame.

Source code in leafmap/common.py

def disjoint(input_features, selecting_features, output=None, **kwargs: Any) -> Any:
    """Find the features in the input_features that do not intersect the selecting_features.

    Args:
        input_features (str | GeoDataFrame): The input features to select from. Can be a file path or a GeoDataFrame.
        selecting_features (str | GeoDataFrame): The features in the Input Features parameter will be selected based
            on their relationship to the features from this layer.
        output (are, optional): The output path to save the GeoDataFrame in a vector format (e.g., shapefile). Defaults to None.

    Returns:
        The path to the output file or the GeoDataFrame.
    """
    import geopandas as gpd

    if isinstance(input_features, str):
        input_features = gpd.read_file(input_features, **kwargs)
    elif not isinstance(input_features, gpd.GeoDataFrame):
        raise TypeError("input_features must be a file path or a GeoDataFrame")

    if isinstance(selecting_features, str):
        selecting_features = gpd.read_file(selecting_features, **kwargs)
    elif not isinstance(selecting_features, gpd.GeoDataFrame):
        raise TypeError("selecting_features must be a file path or a GeoDataFrame")

    selecting_features = selecting_features.to_crs(input_features.crs)

    input_features["savedindex"] = input_features.index
    intersecting = selecting_features.sjoin(input_features, how="inner")["savedindex"]
    results = input_features[~input_features.savedindex.isin(intersecting)].drop(
        columns=["savedindex"], axis=1
    )

    if output is not None:
        results.to_file(output, **kwargs)
    else:
        return results

display_html(html, width='100%', height=500)

Displays an HTML file or HTML string in a Jupyter Notebook.

Parameters:

Name	Type	Description	Default
html	Union[str, bytes]	Path to an HTML file or an HTML string.	required
width	str	Width of the displayed iframe. Default is '100%'.	'100%'
height	int	Height of the displayed iframe. Default is 500.	500

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def display_html(
    html: Union[str, bytes], width: str = "100%", height: int = 500
) -> None:
    """
    Displays an HTML file or HTML string in a Jupyter Notebook.

    Args:
        html (Union[str, bytes]): Path to an HTML file or an HTML string.
        width (str, optional): Width of the displayed iframe. Default is '100%'.
        height (int, optional): Height of the displayed iframe. Default is 500.

    Returns:
        None
    """
    from IPython.display import IFrame, display

    if isinstance(html, str) and html.startswith("<"):
        # If the input is an HTML string
        html_content = html
    elif isinstance(html, str):
        # If the input is a file path
        with open(html, "r") as file:
            html_content = file.read()
    elif isinstance(html, bytes):
        # If the input is a byte string
        html_content = html.decode("utf-8")
    else:
        raise ValueError("Invalid input type. Expected a file path or an HTML string.")

    display(IFrame(src=html_content, width=width, height=height))

download_data_catalogs(out_dir=None, quiet=True, overwrite=False)

Download geospatial data catalogs from https://github.com/giswqs/geospatial-data-catalogs.

Parameters:

Name	Type	Description	Default
out_dir	str	The output directory. Defaults to None.	None
quiet	bool	Whether to suppress the download progress bar. Defaults to True.	True
overwrite	bool	Whether to overwrite the existing data catalog. Defaults to False.	False

Returns:

Name	Type	Description
str	str	The path to the downloaded data catalog.

Source code in leafmap/stac.py

def download_data_catalogs(
    out_dir: Optional[str] = None,
    quiet: Optional[bool] = True,
    overwrite: Optional[bool] = False,
) -> str:
    """Download geospatial data catalogs from https://github.com/giswqs/geospatial-data-catalogs.

    Args:
        out_dir (str, optional): The output directory. Defaults to None.
        quiet (bool, optional): Whether to suppress the download progress bar. Defaults to True.
        overwrite (bool, optional): Whether to overwrite the existing data catalog. Defaults to False.

    Returns:
        str: The path to the downloaded data catalog.
    """
    import tempfile
    import zipfile

    import gdown

    if out_dir is None:
        out_dir = tempfile.gettempdir()
    elif not os.path.exists(out_dir):
        os.makedirs(out_dir)

    url = "https://github.com/giswqs/geospatial-data-catalogs/archive/refs/heads/master.zip"

    out_file = os.path.join(out_dir, "geospatial-data-catalogs.zip")
    work_dir = os.path.join(out_dir, "geospatial-data-catalogs-master")

    if os.path.exists(work_dir) and not overwrite:
        return work_dir
    else:
        gdown.download(url, out_file, quiet=quiet)
        with zipfile.ZipFile(out_file, "r") as zip_ref:
            zip_ref.extractall(out_dir)
        return work_dir

download_file(url=None, output=None, quiet=False, proxy=None, speed=None, use_cookies=True, verify=True, id=None, fuzzy=False, resume=False, unzip=True, overwrite=False, subfolder=False)

Download a file from URL, including Google Drive shared URL.

Parameters:

Name	Type	Description	Default
url	str	Google Drive URL is also supported. Defaults to None.	None
output	str	Output filename. Default is basename of URL.	None
quiet	bool	Suppress terminal output. Default is 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
verify	bool | str	Either a bool, in which case it controls whether the server's TLS certificate is verified, or a string, in which case it must be a path to a CA bundle to use. Default is True.. Defaults to True.	True
id	str	Google Drive's file ID. Defaults to None.	None
fuzzy	bool	Fuzzy extraction of Google Drive's file Id. Defaults to False.	False
resume	bool	Resume the download from existing tmp file if possible. Defaults to False.	False
unzip	bool	Unzip the file. Defaults to True.	True
overwrite	bool	Overwrite the file if it already exists. Defaults to False.	False
subfolder	bool	Create a subfolder with the same name as the file. Defaults to False.	False

Returns:

Type	Description
str	The output file path.

Source code in leafmap/common.py

def download_file(
    url=None,
    output=None,
    quiet=False,
    proxy=None,
    speed=None,
    use_cookies=True,
    verify=True,
    id=None,
    fuzzy=False,
    resume=False,
    unzip=True,
    overwrite=False,
    subfolder=False,
) -> str:
    """Download a file from URL, including Google Drive shared URL.

    Args:
        url (str, optional): Google Drive URL is also supported. Defaults to None.
        output (str, optional): Output filename. Default is basename of URL.
        quiet (bool, optional): Suppress terminal output. Default is 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.
        verify (bool | str, optional): Either a bool, in which case it controls whether the server's TLS certificate is verified, or a string,
            in which case it must be a path to a CA bundle to use. Default is True.. Defaults to True.
        id (str, optional): Google Drive's file ID. Defaults to None.
        fuzzy (bool, optional): Fuzzy extraction of Google Drive's file Id. Defaults to False.
        resume (bool, optional): Resume the download from existing tmp file if possible. Defaults to False.
        unzip (bool, optional): Unzip the file. Defaults to True.
        overwrite (bool, optional): Overwrite the file if it already exists. Defaults to False.
        subfolder (bool, optional): Create a subfolder with the same name as the file. Defaults to False.

    Returns:
        The output file path.
    """
    try:
        import gdown
    except ImportError:
        print(
            "The gdown package is required for this function. Use `pip install gdown` to install it."
        )
        return

    if output is None:
        if isinstance(url, str) and url.startswith("http"):
            output = os.path.basename(url)

    out_dir = os.path.abspath(os.path.dirname(output))
    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if isinstance(url, str):
        if os.path.exists(os.path.abspath(output)) and (not overwrite):
            print(
                f"{output} already exists. Skip downloading. Set overwrite=True to overwrite."
            )
            return os.path.abspath(output)
        else:
            url = github_raw_url(url)

    if "https://drive.google.com/file/d/" in url:
        fuzzy = True

    output = gdown.download(
        url, output, quiet, proxy, speed, use_cookies, verify, id, fuzzy, resume
    )

    if unzip:
        if output.endswith(".zip"):
            with zipfile.ZipFile(output, "r") as zip_ref:
                if not quiet:
                    print("Extracting files...")
                if subfolder:
                    basename = os.path.splitext(os.path.basename(output))[0]

                    output = os.path.join(out_dir, basename)
                    if not os.path.exists(output):
                        os.makedirs(output)
                    zip_ref.extractall(output)
                else:
                    zip_ref.extractall(os.path.dirname(output))
        elif output.endswith(".tar.gz") or output.endswith(".tar"):
            if output.endswith(".tar.gz"):
                mode = "r:gz"
            else:
                mode = "r"

            with tarfile.open(output, mode) as tar_ref:
                if not quiet:
                    print("Extracting files...")
                if subfolder:
                    basename = os.path.splitext(os.path.basename(output))[0]
                    output = os.path.join(out_dir, basename)
                    if not os.path.exists(output):
                        os.makedirs(output)
                    tar_ref.extractall(output)
                else:
                    tar_ref.extractall(os.path.dirname(output))

    return os.path.abspath(output)

download_file_lite(url, output=None, binary=False, overwrite=False, **kwargs) async

Download a file using Pyodide. This function is only available on JupyterLite. Call the function with await, such as await download_file_lite(url).

Parameters:

Name	Type	Description	Default
url	str	The URL of the file.	required
output	str	The local path to save the file. Defaults to None.	None
binary	bool	Whether the file is binary. Defaults to False.	False
overwrite	bool	Whether to overwrite the file if it exists. Defaults to False.	False

Source code in leafmap/common.py

async def download_file_lite(
    url, output=None, binary=False, overwrite=False, **kwargs: Any
):
    """Download a file using Pyodide. This function is only available on JupyterLite. Call the function with await, such as await download_file_lite(url).

    Args:
        url (str): The URL of the file.
        output (str, optional): The local path to save the file. Defaults to None.
        binary (bool, optional): Whether the file is binary. Defaults to False.
        overwrite (bool, optional): Whether to overwrite the file if it exists. Defaults to False.
    """
    import sys

    import pyodide  # pylint: disable=E0401

    if "pyodide" not in sys.modules:
        raise ValueError("Pyodide is not available.")

    if output is None:
        output = os.path.basename(url)

    output = os.path.abspath(output)

    ext = os.path.splitext(output)[1]

    if ext in [".png", "jpg", ".tif", ".tiff", "zip", "gz", "bz2", "xz"]:
        binary = True

    if os.path.exists(output) and not overwrite:
        print(f"{output} already exists, skip downloading.")
        return output

    if binary:
        response = await pyodide.http.pyfetch(url)
        with open(output, "wb") as f:
            f.write(await response.bytes())

    else:
        obj = pyodide.http.open_url(url)
        with open(output, "w") as fd:
            shutil.copyfileobj(obj, fd)

    return output

download_files(urls, out_dir=None, filenames=None, quiet=False, proxy=None, speed=None, use_cookies=True, verify=True, id=None, fuzzy=False, resume=False, unzip=True, overwrite=False, subfolder=False, multi_part=False)

Download files from URLs, including Google Drive shared URL.

Parameters:

Name	Type	Description	Default
urls	list	The list of urls to download. Google Drive URL is also supported.	required
out_dir	str	The output directory. Defaults to None.	None
filenames	list	Output filename. Default is basename of URL.	None
quiet	bool	Suppress terminal output. Default is 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
verify	bool | str	Either a bool, in which case it controls whether the server's TLS certificate is verified, or a string, in which case it must be a path to a CA bundle to use. Default is True.. Defaults to True.	True
id	str	Google Drive's file ID. Defaults to None.	None
fuzzy	bool	Fuzzy extraction of Google Drive's file Id. Defaults to False.	False
resume	bool	Resume the download from existing tmp file if possible. Defaults to False.	False
unzip	bool	Unzip the file. Defaults to True.	True
overwrite	bool	Overwrite the file if it already exists. Defaults to False.	False
subfolder	bool	Create a subfolder with the same name as the file. Defaults to False.	False
multi_part	bool	If the file is a multi-part file. Defaults to False.	False

files = ["sam_hq_vit_tiny.zip", "sam_hq_vit_tiny.z01", "sam_hq_vit_tiny.z02", "sam_hq_vit_tiny.z03"]
base_url = "https://github.com/opengeos/datasets/releases/download/models/"
urls = [base_url + f for f in files]
leafmap.download_files(urls, out_dir="models", multi_part=True)

Source code in leafmap/common.py

def download_files(
    urls,
    out_dir=None,
    filenames=None,
    quiet=False,
    proxy=None,
    speed=None,
    use_cookies=True,
    verify=True,
    id=None,
    fuzzy=False,
    resume=False,
    unzip=True,
    overwrite=False,
    subfolder=False,
    multi_part=False,
):
    """Download files from URLs, including Google Drive shared URL.

    Args:
        urls (list): The list of urls to download. Google Drive URL is also supported.
        out_dir (str, optional): The output directory. Defaults to None.
        filenames (list, optional): Output filename. Default is basename of URL.
        quiet (bool, optional): Suppress terminal output. Default is 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.
        verify (bool | str, optional): Either a bool, in which case it controls whether the server's TLS certificate is verified, or a string, in which case it must be a path to a CA bundle to use. Default is True.. Defaults to True.
        id (str, optional): Google Drive's file ID. Defaults to None.
        fuzzy (bool, optional): Fuzzy extraction of Google Drive's file Id. Defaults to False.
        resume (bool, optional): Resume the download from existing tmp file if possible. Defaults to False.
        unzip (bool, optional): Unzip the file. Defaults to True.
        overwrite (bool, optional): Overwrite the file if it already exists. Defaults to False.
        subfolder (bool, optional): Create a subfolder with the same name as the file. Defaults to False.
        multi_part (bool, optional): If the file is a multi-part file. Defaults to False.

    Examples:

        files = ["sam_hq_vit_tiny.zip", "sam_hq_vit_tiny.z01", "sam_hq_vit_tiny.z02", "sam_hq_vit_tiny.z03"]
        base_url = "https://github.com/opengeos/datasets/releases/download/models/"
        urls = [base_url + f for f in files]
        leafmap.download_files(urls, out_dir="models", multi_part=True)
    """

    if out_dir is None:
        out_dir = os.getcwd()

    if filenames is None:
        filenames = [None] * len(urls)

    filepaths = []
    for url, output in zip(urls, filenames):
        if output is None:
            filename = os.path.join(out_dir, os.path.basename(url))
        else:
            filename = os.path.join(out_dir, output)

        filepaths.append(filename)
        if multi_part:
            unzip = False

        download_file(
            url,
            filename,
            quiet,
            proxy,
            speed,
            use_cookies,
            verify,
            id,
            fuzzy,
            resume,
            unzip,
            overwrite,
            subfolder,
        )

    if multi_part:
        archive = os.path.splitext(filename)[0] + ".zip"
        out_dir = os.path.dirname(filename)
        extract_archive(archive, out_dir)

        for file in filepaths:
            os.remove(file)

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

Returns:

Type	Description
Optional[List[str]]	List of files downloaded, or None if failed.

Source code in leafmap/common.py

def download_folder(
    url=None,
    id=None,
    output=None,
    quiet=False,
    proxy=None,
    speed=None,
    use_cookies=True,
    remaining_ok=False,
) -> Optional[List[str]]:
    """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.

    Returns:
        List of files downloaded, or None if failed.
    """

    try:
        import gdown
    except ImportError:
        print(
            "The gdown package is required for this function. Use `pip install gdown` to install it."
        )
        return

    files = gdown.download_folder(
        url, id, output, quiet, proxy, speed, use_cookies, remaining_ok
    )
    return files

download_from_url(url, out_file_name=None, out_dir='.', unzip=True, verbose=True)

Download a file from a URL (e.g., https://github.com/opengeos/whitebox-python/raw/master/examples/testdata.zip)

Parameters:

Name	Type	Description	Default
url	str	The HTTP URL to download.	required
out_file_name	str	The output file name to use. Defaults to None.	None
out_dir	str	The output directory to use. Defaults to '.'.	'.'
unzip	bool	Whether to unzip the downloaded file if it is a zip file. Defaults to True.	True
verbose	bool	Whether to display or not the output of the function	True

Source code in leafmap/common.py

def download_from_url(
    url: str,
    out_file_name: Optional[str] = None,
    out_dir: Optional[str] = ".",
    unzip: Optional[bool] = True,
    verbose: Optional[bool] = True,
):
    """Download a file from a URL (e.g., https://github.com/opengeos/whitebox-python/raw/master/examples/testdata.zip)

    Args:
        url (str): The HTTP URL to download.
        out_file_name (str, optional): The output file name to use. Defaults to None.
        out_dir (str, optional): The output directory to use. Defaults to '.'.
        unzip (bool, optional): Whether to unzip the downloaded file if it is a zip file. Defaults to True.
        verbose (bool, optional): Whether to display or not the output of the function
    """
    in_file_name = os.path.basename(url)
    out_dir = check_dir(out_dir)

    if out_file_name is None:
        out_file_name = in_file_name
    out_file_path = os.path.join(out_dir, out_file_name)

    if verbose:
        print("Downloading {} ...".format(url))

    try:
        urllib.request.urlretrieve(url, out_file_path)
    except Exception:
        raise Exception("The URL is invalid. Please double check the URL.")

    final_path = out_file_path

    if unzip:
        # if it is a zip file
        if ".zip" in out_file_name:
            if verbose:
                print("Unzipping {} ...".format(out_file_name))
            with zipfile.ZipFile(out_file_path, "r") as zip_ref:
                zip_ref.extractall(out_dir)
            final_path = os.path.join(
                os.path.abspath(out_dir), out_file_name.replace(".zip", "")
            )

        # if it is a tar file
        if ".tar" in out_file_name:
            if verbose:
                print("Unzipping {} ...".format(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(".tart", "")
            )

    if verbose:
        print("Data downloaded to: {}".format(final_path))

download_google_buildings(location, out_dir=None, merge_output=None, head=None, keep_geojson=False, overwrite=False, quiet=False, **kwargs)

Download Google Open Building dataset for a specific location. Check the dataset links from https://sites.research.google/open-buildings.

Parameters:

Name	Type	Description	Default
location	str	The location name for which to download the dataset.	required
out_dir	Optional[str]	The output directory to save the downloaded files. If not provided, the current working directory is used.	None
merge_output	Optional[str]	Optional. The output file path for merging the downloaded files into a single GeoDataFrame.	None
head	Optional[int]	Optional. The number of files to download. If not provided, all files will be downloaded.	None
keep_geojson	bool	Optional. If True, the GeoJSON files will be kept after converting them to CSV files.	False
overwrite	bool	Optional. If True, overwrite the existing files.	False
quiet	bool	Optional. If True, suppresses the download progress messages.	False
**kwargs	Any	Additional keyword arguments to be passed to the gpd.to_file function.	{}

Returns:

Type	Description
List[str]	A list of file paths of the downloaded files.

Source code in leafmap/common.py

def download_google_buildings(
    location: str,
    out_dir: Optional[str] = None,
    merge_output: Optional[str] = None,
    head: Optional[int] = None,
    keep_geojson: bool = False,
    overwrite: bool = False,
    quiet: bool = False,
    **kwargs: Any,
) -> List[str]:
    """
    Download Google Open Building dataset for a specific location. Check the dataset links from
        https://sites.research.google/open-buildings.

    Args:
        location: The location name for which to download the dataset.
        out_dir: The output directory to save the downloaded files. If not provided, the current working directory is used.
        merge_output: Optional. The output file path for merging the downloaded files into a single GeoDataFrame.
        head: Optional. The number of files to download. If not provided, all files will be downloaded.
        keep_geojson: Optional. If True, the GeoJSON files will be kept after converting them to CSV files.
        overwrite: Optional. If True, overwrite the existing files.
        quiet: Optional. If True, suppresses the download progress messages.
        **kwargs: Additional keyword arguments to be passed to the `gpd.to_file` function.

    Returns:
        A list of file paths of the downloaded files.

    """

    import geopandas as gpd
    import pandas as pd
    from shapely import wkt

    building_url = "https://sites.research.google/open-buildings/tiles.geojson"
    country_url = (
        "https://naciscdn.org/naturalearth/110m/cultural/ne_110m_admin_0_countries.zip"
    )

    if out_dir is None:
        out_dir = os.getcwd()

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    building_gdf = gpd.read_file(building_url)
    country_gdf = gpd.read_file(country_url)

    country = country_gdf[country_gdf["NAME"] == location]

    if len(country) == 0:
        country = country_gdf[country_gdf["NAME_LONG"] == location]
        if len(country) == 0:
            raise ValueError(f"Could not find {location} in the Natural Earth dataset.")

    gdf = building_gdf[building_gdf.intersects(country.geometry.iloc[0])]
    gdf.sort_values(by="size_mb", inplace=True)

    print(f"Found {len(gdf)} links for {location}.")
    if head is not None:
        gdf = gdf.head(head)

    if len(gdf) > 0:
        links = gdf["tile_url"].tolist()
        download_files(links, out_dir=out_dir, quiet=quiet, **kwargs)
        filenames = [os.path.join(out_dir, os.path.basename(link)) for link in links]

        gdfs = []
        for filename in filenames:
            # Read the CSV file into a pandas DataFrame
            df = pd.read_csv(filename)

            # Create a geometry column from the "geometry" column in the DataFrame
            df["geometry"] = df["geometry"].apply(wkt.loads)

            # Convert the pandas DataFrame to a GeoDataFrame
            gdf = gpd.GeoDataFrame(df, geometry="geometry")
            gdf.crs = "EPSG:4326"
            if keep_geojson:
                gdf.to_file(
                    filename.replace(".csv.gz", ".geojson"), driver="GeoJSON", **kwargs
                )
            gdfs.append(gdf)

        if merge_output:
            if os.path.exists(merge_output) and not overwrite:
                print(f"File {merge_output} already exists, skip merging...")
            else:
                if not quiet:
                    print("Merging GeoDataFrames ...")
                gdf = gpd.GeoDataFrame(
                    pd.concat(gdfs, ignore_index=True), crs="EPSG:4326"
                )
                gdf.to_file(merge_output, **kwargs)

    else:
        print(f"No buildings found for {location}.")

download_mapillary_image(image_id, output=None, resolution='original', access_token=None, quiet=True, **kwargs)

Downloads a Mapillary image.

Parameters:

Name	Type	Description	Default
image_id	str	The ID of the Mapillary image.	required
output	str	The output file path. Defaults to None.	None
resolution	str	The resolution of the image. Can be 256, 1024, 2048, or original. Defaults to "original".	'original'
access_token	str	The access token for the Mapillary API. Defaults to None.	None
quiet	bool	Whether to suppress output. Defaults to True.	True
**kwargs	Any	Additional keyword arguments for the download.	{}

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def download_mapillary_image(
    image_id: str,
    output: Optional[str] = None,
    resolution: str = "original",
    access_token: Optional[str] = None,
    quiet: bool = True,
    **kwargs: Any,
) -> None:
    """
    Downloads a Mapillary image.

    Args:
        image_id (str): The ID of the Mapillary image.
        output (str, optional): The output file path. Defaults to None.
        resolution (str): The resolution of the image. Can be 256, 1024, 2048, or original.
            Defaults to "original".
        access_token (str, optional): The access token for the Mapillary API. Defaults to None.
        quiet (bool): Whether to suppress output. Defaults to True.
        **kwargs: Additional keyword arguments for the download.

    Returns:
        None
    """

    image_url = get_mapillary_image_url(
        image_id, resolution=resolution, access_token=access_token
    )
    if output is None:

        output = f"{image_id}.jpg"
    download_file(image_url, output, quiet=quiet, **kwargs)

download_mapillary_images(image_ids, output_dir=None, resolution='original', **kwargs)

Downloads multiple Mapillary images.

Parameters:

Name	Type	Description	Default
image_ids	List[str]	A list of Mapillary image IDs.	required
output_dir	str	The directory to save the images. Defaults to the current working directory.	None
resolution	str	The resolution of the images. Defaults to "original".	'original'
**kwargs	Any	Additional keyword arguments for the download.	{}

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def download_mapillary_images(
    image_ids: List[str],
    output_dir: Optional[str] = None,
    resolution: str = "original",
    **kwargs: Any,
) -> None:
    """
    Downloads multiple Mapillary images.

    Args:
        image_ids (List[str]): A list of Mapillary image IDs.
        output_dir (str, optional): The directory to save the images. Defaults
            to the current working directory.
        resolution (str): The resolution of the images. Defaults to "original".
        **kwargs: Additional keyword arguments for the download.

    Returns:
        None
    """
    if output_dir is None:
        output_dir = os.getcwd()

    for index, image_id in enumerate(image_ids):
        output = os.path.join(output_dir, f"{image_id}.jpg")
        print(f"Downloading {index + 1}/{len(image_ids)}: {image_id}.jpg ...")
        download_mapillary_image(
            image_id=image_id, output=output, resolution=resolution, **kwargs
        )

download_ms_buildings(location, out_dir=None, merge_output=None, head=None, quiet=False, **kwargs)

Download Microsoft Buildings dataset for a specific location. Check the dataset links from https://minedbuildings.blob.core.windows.net/global-buildings/dataset-links.csv.

Parameters:

Name	Type	Description	Default
location	str	The location name for which to download the dataset.	required
out_dir	str	The output directory to save the downloaded files. If not provided, the current working directory is used.	None
merge_output	str	The output file path for merging the downloaded files into a single GeoDataFrame.	None
head	int	The number of files to download. If not provided, all files will be downloaded.	None
quiet	bool	If True, suppresses the download progress messages.	False
**kwargs	Any	Additional keyword arguments to be passed to the gpd.to_file function.	{}

Returns:

Type	Description
List[str]	A list of file paths of the downloaded files.

Source code in leafmap/common.py

def download_ms_buildings(
    location: str,
    out_dir: Optional[str] = None,
    merge_output: Optional[str] = None,
    head=None,
    quiet: bool = False,
    **kwargs: Any,
) -> List[str]:
    """
    Download Microsoft Buildings dataset for a specific location. Check the dataset links from
        https://minedbuildings.blob.core.windows.net/global-buildings/dataset-links.csv.

    Args:
        location (str): The location name for which to download the dataset.
        out_dir (str, optional): The output directory to save the downloaded files. If not provided, the current working directory is used.
        merge_output (str, optional): The output file path for merging the downloaded files into a single GeoDataFrame.
        head (int, optional): The number of files to download. If not provided, all files will be downloaded.
        quiet (bool, optional): If True, suppresses the download progress messages.
        **kwargs (Any): Additional keyword arguments to be passed to the `gpd.to_file` function.

    Returns:
        A list of file paths of the downloaded files.

    """

    import geopandas as gpd
    import pandas as pd
    from shapely.geometry import shape

    if out_dir is None:
        out_dir = os.getcwd()

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    dataset_links = pd.read_csv(
        "https://minedbuildings.blob.core.windows.net/global-buildings/dataset-links.csv"
    )
    country_links = dataset_links[dataset_links.Location == location]

    if not quiet:
        print(f"Found {len(country_links)} links for {location}")
    if head is not None:
        country_links = country_links.head(head)

    filenames = []
    i = 1

    for _, row in country_links.iterrows():
        if not quiet:
            print(f"Downloading {i} of {len(country_links)}: {row.QuadKey}.geojson")
        i += 1
        filename = os.path.join(out_dir, f"{row.QuadKey}.geojson")
        filenames.append(filename)
        if os.path.exists(filename):
            print(f"File {filename} already exists, skipping...")
            continue
        df = pd.read_json(row.Url, lines=True)
        df["geometry"] = df["geometry"].apply(shape)
        gdf = gpd.GeoDataFrame(df, crs=4326)
        gdf.to_file(filename, driver="GeoJSON", **kwargs)

    if merge_output is not None:
        if os.path.exists(merge_output):
            print(f"File {merge_output} already exists, skip merging...")
            return filenames
        merge_vector(filenames, merge_output, quiet=quiet)

    return filenames

download_ned(region, out_dir=None, return_url=False, download_args={}, geopandas_args={}, query={})

Download the US National Elevation Datasets (NED) for a region.

Parameters:

Name	Type	Description	Default
region	str | list	A filepath to a vector dataset or a list of bounds in the form of [minx, miny, maxx, maxy].	required
out_dir	str	The directory to download the files to. Defaults to None, which uses the current working directory.	None
return_url	bool	Whether to return the download URLs of the files. Defaults to False.	False
download_args	dict	A dictionary of arguments to pass to the download_file function. Defaults to {}.	{}
geopandas_args	dict	A dictionary of arguments to pass to the geopandas.read_file() function. Used for reading a region URL|filepath.	{}
query	dict	A dictionary of arguments to pass to the The_national_map_USGS.find_details() function. See https://apps.nationalmap.gov/tnmaccess/#/product for more information.	{}

Returns:

Type	Description
Union[None, List]	A list of the download URLs of the files if return_url is True.

Source code in leafmap/common.py

def download_ned(
    region,
    out_dir=None,
    return_url=False,
    download_args={},
    geopandas_args={},
    query={},
) -> Union[None, List]:
    """Download the US National Elevation Datasets (NED) for a region.

    Args:
        region (str | list): A filepath to a vector dataset or a list of bounds in the form of [minx, miny, maxx, maxy].
        out_dir (str, optional): The directory to download the files to. Defaults to None, which uses the current working directory.
        return_url (bool, optional): Whether to return the download URLs of the files. Defaults to False.
        download_args (dict, optional): A dictionary of arguments to pass to the download_file function. Defaults to {}.
        geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
            Used for reading a region URL|filepath.
        query (dict, optional): A dictionary of arguments to pass to the The_national_map_USGS.find_details() function.
            See https://apps.nationalmap.gov/tnmaccess/#/product for more information.

    Returns:
        A list of the download URLs of the files if return_url is True.
    """

    if os.environ.get("USE_MKDOCS") is not None:
        return

    if not query:
        query = {
            "datasets": "National Elevation Dataset (NED) 1/3 arc-second",
            "prodFormats": "GeoTIFF",
        }

    TNM = The_national_map_USGS()
    if return_url:
        return TNM.find_tiles(region=region, geopandas_args=geopandas_args, API=query)
    return TNM.download_tiles(
        region=region,
        out_dir=out_dir,
        download_args=download_args,
        geopandas_args=geopandas_args,
        API=query,
    )

download_nlcd(years, out_dir=None, quiet=False, **kwargs)

Downloads NLCD (National Land Cover Database) files for the specified years.

Parameters:

Name	Type	Description	Default
years	List[int]	A list of years for which to download the NLCD files.	required
out_dir	str	The directory where the downloaded files will be saved. Defaults to the current working directory.	None
quiet	bool	If True, suppresses download progress messages. Defaults to False.	False
**kwargs	Any	Additional keyword arguments to pass to the download_file function.	{}

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def download_nlcd(
    years: List[int], out_dir: str = None, quiet: bool = False, **kwargs: Any
) -> None:
    """
    Downloads NLCD (National Land Cover Database) files for the specified years.

    Args:
        years (List[int]): A list of years for which to download the NLCD files.
        out_dir (str, optional): The directory where the downloaded files will be saved.
            Defaults to the current working directory.
        quiet (bool, optional): If True, suppresses download progress messages. Defaults to False.
        **kwargs (Any): Additional keyword arguments to pass to the download_file function.

    Returns:
        None
    """

    allow_years = list(range(1985, 2024, 1))
    url = "https://s3-us-west-2.amazonaws.com/mrlc/Annual_NLCD_LndCov_{}_CU_C1V0.tif"
    if out_dir is None:
        out_dir = os.getcwd()
    elif not os.path.exists(out_dir):
        os.makedirs(out_dir)
    for year in years:
        if year not in allow_years:
            print(f"Year {year} is not available. Skipping...")
            continue
        year_url = url.format(year)
        basename = os.path.basename(year_url)
        filepath = os.path.join(out_dir, basename)
        download_file(year_url, filepath, quiet=quiet, **kwargs)

download_tnm(region=None, out_dir=None, return_url=False, download_args={}, geopandas_args={}, API={})

Download the US National Elevation Datasets (NED) for a region.

Parameters:

Name	Type	Description	Default
region	str | list	An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy]. Alternatively you could use API parameters such as polygon or bbox.	None
out_dir	str	The directory to download the files to. Defaults to None, which uses the current working directory.	None
return_url	bool	Whether to return the download URLs of the files. Defaults to False.	False
download_args	dict	A dictionary of arguments to pass to the download_file function. Defaults to {}.	{}
geopandas_args	dict	A dictionary of arguments to pass to the geopandas.read_file() function. Used for reading a region URL|filepath.	{}
API	dict	A dictionary of arguments to pass to the The_national_map_USGS.find_details() function. Exposes most of the documented API. Defaults to {}	{}

Returns:

Type	Description
Union[None, List]	A list of the download URLs of the files if return_url is True.

Source code in leafmap/common.py

def download_tnm(
    region=None,
    out_dir=None,
    return_url=False,
    download_args={},
    geopandas_args={},
    API={},
) -> Union[None, List]:
    """Download the US National Elevation Datasets (NED) for a region.

    Args:
        region (str | list, optional): An URL|filepath to a vector dataset Or a list of bounds in the form of [minx, miny, maxx, maxy].
            Alternatively you could use API parameters such as polygon or bbox.
        out_dir (str, optional): The directory to download the files to. Defaults to None, which uses the current working directory.
        return_url (bool, optional): Whether to return the download URLs of the files. Defaults to False.
        download_args (dict, optional): A dictionary of arguments to pass to the download_file function. Defaults to {}.
        geopandas_args (dict, optional): A dictionary of arguments to pass to the geopandas.read_file() function.
            Used for reading a region URL|filepath.
        API (dict, optional): A dictionary of arguments to pass to the The_national_map_USGS.find_details() function.
            Exposes most of the documented API. Defaults to {}

    Returns:
        A list of the download URLs of the files if return_url is True.
    """

    if os.environ.get("USE_MKDOCS") is not None:
        return

    TNM = The_national_map_USGS()
    if return_url:
        return TNM.find_tiles(region=region, geopandas_args=geopandas_args, API=API)
    return TNM.download_tiles(
        region=region,
        out_dir=out_dir,
        download_args=download_args,
        geopandas_args=geopandas_args,
        API=API,
    )

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 leafmap/common.py

def edit_download_html(
    htmlWidget: Any, filename: str, title: str = "Click here to download: "
) -> None:
    """Downloads a file from voila. Adopted from https://github.com/voila-dashboards/voila/issues/578#issuecomment-617668058

    Args:
        htmlWidget (object): The HTML widget to display the URL.
        filename (str): File path to download.
        title (str, optional): Download description. Defaults to "Click here to download: ".
    """

    # from IPython.display import HTML
    # import ipywidgets as widgets
    import base64

    # Change widget html temporarily to a font-awesome spinner
    htmlWidget.value = '<i class="fa fa-spinner fa-spin fa-2x fa-fw"></i><span class="sr-only">Loading...</span>'

    # Process raw data
    data = open(filename, "rb").read()
    b64 = base64.b64encode(data)
    payload = b64.decode()

    basename = os.path.basename(filename)

    # Create and assign html to widget
    html = '<a download="{filename}" href="data:text/csv;base64,{payload}" target="_blank">{title}</a>'
    htmlWidget.value = html.format(
        payload=payload, title=title + basename, filename=basename
    )

ee_initialize(key_data=None, token_name='EE_SERVICE_ACCOUNT')

Initialize the Earth Engine API.

Parameters:

Name	Type	Description	Default
key_data	Optional[str]	The key data to use for authentication. Must be a JSON string containing service account credentials, with at least a 'client_email' field (e.g., the contents of a Google service account key file).	None
token_name	str	The name of the environment variable to use for authentication.	'EE_SERVICE_ACCOUNT'

Source code in leafmap/common.py

def ee_initialize(
    key_data: Optional[str] = None, token_name: str = "EE_SERVICE_ACCOUNT"
):
    """
    Initialize the Earth Engine API.

    Args:
        key_data: The key data to use for authentication. Must be a JSON string containing service account credentials,
            with at least a 'client_email' field (e.g., the contents of a Google service account key file).
        token_name: The name of the environment variable to use for authentication.
    """
    import ee

    if key_data is None:
        key_data = get_api_key(token_name)
    if key_data is None:
        raise ValueError(
            f'No key data found in parameter or environment variable "{token_name}"'
        )

    try:
        email = json.loads(key_data)["client_email"]
    except json.JSONDecodeError as e:
        raise ValueError(f"Invalid JSON for key_data: {e}")
    except KeyError:
        raise ValueError("key_data JSON does not contain 'client_email'")
    credentials = ee.ServiceAccountCredentials(email=email, key_data=key_data)
    ee.Initialize(credentials)

ee_tile_url(ee_object=None, vis_params={}, asset_id=None, ee_initialize=False, project_id=None, **kwargs)

Adds a Google Earth Engine tile layer to the map based on the tile layer URL from https://github.com/opengeos/ee-tile-layers/blob/main/datasets.tsv.

Parameters:

Name	Type	Description	Default
ee_object	object	The Earth Engine object to display.	None
vis_params	dict	Visualization parameters. For example, {'min': 0, 'max': 100}.	{}
asset_id	str	The ID of the Earth Engine asset.	None
ee_initialize	bool	Whether to initialize the Earth Engine	False

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def ee_tile_url(
    ee_object=None,
    vis_params={},
    asset_id: str = None,
    ee_initialize: bool = False,
    project_id=None,
    **kwargs: Any,
) -> None:
    """
    Adds a Google Earth Engine tile layer to the map based on the tile layer URL from
        https://github.com/opengeos/ee-tile-layers/blob/main/datasets.tsv.

    Args:
        ee_object (object): The Earth Engine object to display.
        vis_params (dict): Visualization parameters. For example, {'min': 0, 'max': 100}.
        asset_id (str): The ID of the Earth Engine asset.
        ee_initialize (bool, optional): Whether to initialize the Earth Engine

    Returns:
        None
    """
    import pandas as pd

    if isinstance(asset_id, str):
        df = pd.read_csv(
            "https://raw.githubusercontent.com/opengeos/ee-tile-layers/main/datasets.tsv",
            sep="\t",
        )

        asset_id = asset_id.strip()

        if asset_id in df["id"].values:
            url = df.loc[df["id"] == asset_id, "url"].values[0]
            return url
        else:
            print(f"The provided EE tile layer {asset_id} does not exist.")
            return None
    elif ee_object is not None:
        try:
            import geemap
            from geemap.ee_tile_layers import _get_tile_url_format

            if ee_initialize:
                geemap.ee_initialize(project=project_id, **kwargs)
            url = _get_tile_url_format(ee_object, vis_params)
            return url
        except Exception as e:
            print(e)
            return None

evaluate_model(df, y_col='y', y_pred_col='y_pred', metrics=None, drop_na=True, filter_nonzero=True)

Evaluates the model performance on the given dataframe with customizable options.

Parameters:

Name	Type	Description	Default
df	DataFrame	A pandas DataFrame with columns for actual and predicted values.	required
y_col	str	Column name for the actual values.	'y'
y_pred_col	str	Column name for the predicted values.	'y_pred'
metrics	list	A list of metrics to calculate. Available options: - 'r2': R-squared - 'r': Pearson correlation coefficient - 'rmse': Root Mean Squared Error - 'mae': Mean Absolute Error - 'mape': Mean Absolute Percentage Error Defaults to all metrics if None.	None
drop_na	bool	Whether to drop rows with NaN in the actual values column.	True
filter_nonzero	bool	Whether to filter out rows where actual values are zero.	True

Returns:

Type	Description
dict	A dictionary of the selected performance metrics.

Source code in leafmap/common.py

def evaluate_model(
    df: pd.DataFrame,
    y_col: str = "y",
    y_pred_col: str = "y_pred",
    metrics: list = None,
    drop_na: bool = True,
    filter_nonzero: bool = True,
) -> dict:
    """
    Evaluates the model performance on the given dataframe with customizable options.

    Args:
        df: A pandas DataFrame with columns for actual and predicted values.
        y_col: Column name for the actual values.
        y_pred_col: Column name for the predicted values.
        metrics: A list of metrics to calculate. Available options:
            - 'r2': R-squared
            - 'r': Pearson correlation coefficient
            - 'rmse': Root Mean Squared Error
            - 'mae': Mean Absolute Error
            - 'mape': Mean Absolute Percentage Error
            Defaults to all metrics if None.
        drop_na: Whether to drop rows with NaN in the actual values column.
        filter_nonzero: Whether to filter out rows where actual values are zero.

    Returns:
        A dictionary of the selected performance metrics.
    """

    import math

    try:
        from sklearn import metrics as skmetrics
    except ImportError:
        raise ImportError(
            "The scikit-learn package is required for this function. Install it using 'pip install scikit-learn'."
        )

    # Default metrics if none are provided
    if metrics is None:
        metrics = ["r2", "r", "rmse", "mae", "mape"]

    # Data preprocessing
    if drop_na:
        df = df.dropna(subset=[y_col])
    if filter_nonzero:
        df = df[df[y_col] != 0]

    # Metric calculations
    results = {}
    if "r2" in metrics:
        results["r2"] = skmetrics.r2_score(df[y_col], df[y_pred_col])
    if "r" in metrics:
        results["r"] = df[y_col].corr(df[y_pred_col])
    if "rmse" in metrics:
        results["rmse"] = math.sqrt(
            skmetrics.mean_squared_error(df[y_col], df[y_pred_col])
        )
    if "mae" in metrics:
        results["mae"] = skmetrics.mean_absolute_error(df[y_col], df[y_pred_col])
    if "mape" in metrics:
        results["mape"] = skmetrics.mean_absolute_percentage_error(
            df[y_col], df[y_pred_col]
        )

    return results

execute_maplibre_notebook_dir(in_dir, out_dir, delete_html=True, replace_api_key=True, recursive=False, keep_notebook=False, index_html=True, ignore_files=None)

Executes Jupyter notebooks found in a specified directory, optionally replacing API keys and deleting HTML outputs.

Parameters:

Name	Type	Description	Default
in_dir	str	The input directory containing Jupyter notebooks to be executed.	required
out_dir	str	The output directory where the executed notebooks and their HTML outputs will be saved.	required
delete_html	bool	If True, deletes any existing HTML files in the output directory before execution. Defaults to True.	True
replace_api_key	bool	If True, replaces the API key in the output HTML. Defaults to True. set "MAPTILER_KEY" and "MAPTILER_KEY_PUBLIC" to your MapTiler API key and public key, respectively.	True
recursive	bool	If True, searches for notebooks in the input directory recursively. Defaults to False.	False
keep_notebook	bool	If True, keeps the executed notebooks in the output directory. Defaults to False.	False
index_html	bool	If True, generates an index.html file in the output directory listing all files. Defaults to True.	True
ignore_files	list	A list of notebook files to ignore during execution. Defaults to None.	None

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def execute_maplibre_notebook_dir(
    in_dir: str,
    out_dir: str,
    delete_html: bool = True,
    replace_api_key: bool = True,
    recursive: bool = False,
    keep_notebook: bool = False,
    index_html: bool = True,
    ignore_files: Optional[List[str]] = None,
) -> None:
    """
    Executes Jupyter notebooks found in a specified directory, optionally replacing API keys and deleting HTML outputs.

    Args:
        in_dir (str): The input directory containing Jupyter notebooks to be executed.
        out_dir (str): The output directory where the executed notebooks and their HTML outputs will be saved.
        delete_html (bool, optional): If True, deletes any existing HTML files in the output directory before execution. Defaults to True.
        replace_api_key (bool, optional): If True, replaces the API key in the output HTML. Defaults to True.
            set "MAPTILER_KEY" and "MAPTILER_KEY_PUBLIC" to your MapTiler API key and public key, respectively.
        recursive (bool, optional): If True, searches for notebooks in the input directory recursively. Defaults to False.
        keep_notebook (bool, optional): If True, keeps the executed notebooks in the output directory. Defaults to False.
        index_html (bool, optional): If True, generates an index.html file in the output directory listing all files. Defaults to True.
        ignore_files (list, optional): A list of notebook files to ignore during execution. Defaults to None.

    Returns:
        None
    """
    import shutil

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if replace_api_key:
        os.environ["MAPTILER_REPLACE_KEY"] = "True"

    if delete_html:
        html_files = find_files(out_dir, "*.html", recursive=recursive)
        for file in html_files:
            os.remove(file)

    if ignore_files is not None:
        ignore_files = [os.path.join(in_dir, f) for f in ignore_files]

    files = find_files(in_dir, "*.ipynb", recursive=recursive)
    for index, file in enumerate(files):
        print(f"Processing {index + 1}/{len(files)}: {file} ...")

        if ignore_files is not None and file in ignore_files:
            print(f"Skipping {file} ...")
            continue

        basename = os.path.basename(file)
        out_file = os.path.join(out_dir, basename)
        shutil.copy(file, out_file)

        with open(out_file, "r") as f:
            lines = f.readlines()

        out_lines = []
        for line in lines:
            if line.strip() == '"m"':
                title = os.path.splitext(basename)[0].replace("_", " ")
                out_lines.append(line.replace("m", f"m.to_html(title='{title}')"))
            else:
                out_lines.append(line)

        with open(out_file, "w") as f:
            f.writelines(out_lines)

        out_html = os.path.basename(out_file).replace(".ipynb", ".html")
        os.environ["MAPLIBRE_OUTPUT"] = out_html
        execute_notebook(out_file)

    if not keep_notebook:
        all_files = find_files(out_dir, "*", recursive=recursive)
        for file in all_files:
            if not file.endswith(".html"):
                os.remove(file)

    if index_html:
        generate_index_html(out_dir)

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 leafmap/common.py

def execute_notebook(in_file):
    """Executes a Jupyter notebook and save output cells

    Args:
        in_file (str): Input Jupyter notebook.
    """
    # command = 'jupyter nbconvert --to notebook --execute ' + in_file + ' --inplace'
    command = 'jupyter nbconvert --to notebook --execute "{}" --inplace'.format(in_file)
    print(os.popen(command).read().rstrip())

execute_notebook_dir(in_dir)

Executes all Jupyter notebooks in the given directory recursively and save output cells.

Parameters:

Name	Type	Description	Default
in_dir	str	Input folder containing notebooks.	required

Source code in leafmap/common.py

def execute_notebook_dir(in_dir):
    """Executes all Jupyter notebooks in the given directory recursively and save output cells.

    Args:
        in_dir (str): Input folder containing notebooks.
    """
    from pathlib import Path

    in_dir = os.path.abspath(in_dir)

    files = list(Path(in_dir).rglob("*.ipynb"))
    files.sort()
    count = len(files)
    if files is not None:
        for index, file in enumerate(files):
            in_file = str(file)
            print(f"Processing {index + 1}/{count}: {file} ...")
            execute_notebook(in_file)

explode(coords)

Explode a GeoJSON geometry's coordinates object and yield coordinate tuples. As long as the input is conforming, the type of the geometry doesn't matter. From Fiona 1.4.8

Parameters:

Name	Type	Description	Default
coords	list	A list of coordinates.	required

Yields:

Type	Description
Any	Coordinate tuples extracted from the input.

Source code in leafmap/common.py

def explode(coords) -> 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 (list): A list of coordinates.

    Yields:
        Coordinate tuples extracted from the input.
    """

    for e in coords:
        if isinstance(e, (float, int)):
            yield coords
            break
        else:
            for f in explode(e):
                yield f

extract_archive(archive, outdir=None, **kwargs)

Extracts a multipart archive.

This function uses the patoolib library to extract a multipart archive. If the patoolib library is not installed, it attempts to install it. If the archive does not end with ".zip", it appends ".zip" to the archive name. If the extraction fails (for example, if the files already exist), it skips the extraction.

Parameters:

Name	Type	Description	Default
archive	str	The path to the archive file.	required
outdir	str	The directory where the archive should be extracted.	None
**kwargs	Any	Arbitrary keyword arguments for the patoolib.extract_archive function.	{}

Returns:

Type	Description
None	None

Raises:

Type	Description
Exception	An exception is raised if the extraction fails for reasons other than the files already existing.

files = ["sam_hq_vit_tiny.zip", "sam_hq_vit_tiny.z01", "sam_hq_vit_tiny.z02", "sam_hq_vit_tiny.z03"]
base_url = "https://github.com/opengeos/datasets/releases/download/models/"
urls = [base_url + f for f in files]
leafmap.download_files(urls, out_dir="models", multi_part=True)

Source code in leafmap/common.py

def extract_archive(archive, outdir=None, **kwargs) -> None:
    """
    Extracts a multipart archive.

    This function uses the patoolib library to extract a multipart archive.
    If the patoolib library is not installed, it attempts to install it.
    If the archive does not end with ".zip", it appends ".zip" to the archive name.
    If the extraction fails (for example, if the files already exist), it skips the extraction.

    Args:
        archive (str): The path to the archive file.
        outdir (str): The directory where the archive should be extracted.
        **kwargs (Any): Arbitrary keyword arguments for the patoolib.extract_archive function.

    Returns:
        None

    Raises:
        Exception: An exception is raised if the extraction fails for reasons other than the files already existing.

    Example:

        files = ["sam_hq_vit_tiny.zip", "sam_hq_vit_tiny.z01", "sam_hq_vit_tiny.z02", "sam_hq_vit_tiny.z03"]
        base_url = "https://github.com/opengeos/datasets/releases/download/models/"
        urls = [base_url + f for f in files]
        leafmap.download_files(urls, out_dir="models", multi_part=True)

    """
    try:
        import patoolib
    except ImportError:
        install_package("patool")
        import patoolib

    if not archive.endswith(".zip"):
        archive = archive + ".zip"

    if outdir is None:
        outdir = os.path.dirname(archive)

    try:
        patoolib.extract_archive(archive, outdir=outdir, **kwargs)
    except Exception as e:
        print("The unzipped files might already exist. Skipping extraction.")
        return

extract_parquet_by_bbox(input_parquet, bbox, output_file, geometry='geometry', driver='PARQUET')

Extract buildings that intersect with a specific bounding box in San Diego.

Uses DuckDB with spatial extension to query buildings that intersect with a bounding box and saves the results to a Parquet file.

Parameters:

Name	Type	Description	Default
input_parquet	str	Path to the input Parquet file.	required
bbox	tuple | list	Bounding box as (minx, miny, maxx, maxy).	required
output_file	str	Output file path for resulting Parquet/GeoParquet file.	required
geometry	str	Geometry column name. Defaults to "geometry".	'geometry'
driver	str	Output driver, e.g., "PARQUET". Defaults to "PARQUET".	'PARQUET'

Returns:

Type	Description
None	The function writes the results to the output file.

Source code in leafmap/common.py

def extract_parquet_by_bbox(
    input_parquet, bbox, output_file, geometry="geometry", driver="PARQUET"
) -> None:
    """
    Extract buildings that intersect with a specific bounding box in San Diego.

    Uses DuckDB with spatial extension to query buildings that intersect with
    a bounding box and saves the results to a Parquet file.

    Args:
        input_parquet (str): Path to the input Parquet file.
        bbox (tuple | list): Bounding box as (minx, miny, maxx, maxy).
        output_file (str): Output file path for resulting Parquet/GeoParquet file.
        geometry (str, optional): Geometry column name. Defaults to "geometry".
        driver (str, optional): Output driver, e.g., "PARQUET". Defaults to "PARQUET".

    Returns:
        The function writes the results to the output file.
    """
    import duckdb

    # Connect to DuckDB
    conn = duckdb.connect()

    # Install and load spatial extension
    conn.execute("INSTALL spatial")
    conn.execute("LOAD spatial")

    if driver.upper() == "PARQUET":
        fmt = "FORMAT PARQUET"
    else:
        fmt = f"FORMAT GDAL, DRIVER '{driver}'"

    # Run the query
    query = f"""
    COPY (
        WITH bbox AS (
            SELECT ST_MakeEnvelope({bbox[0]}, {bbox[1]}, {bbox[2]}, {bbox[3]}) AS geom2
        )

        SELECT * FROM '{input_parquet}'
        WHERE
            ST_Intersects(
                {geometry},
                (SELECT geom2 FROM bbox)
            )
    ) TO '{output_file}' ({fmt})
    """

    # Execute the query
    conn.execute(query)

    # Close the connection
    conn.close()

filter_bounds(data, bbox, within=False, align=True, **kwargs)

Filters a GeoDataFrame or GeoSeries by a bounding box.

Parameters:

Name	Type	Description	Default
data	str | GeoDataFrame	The input data to filter. Can be a file path or a GeoDataFrame.	required
bbox	list | GeoDataFrame	The bounding box to filter by. Can be a list of 4 coordinates or a file path or a GeoDataFrame.	required
within	bool	Whether to filter by the bounding box or the bounding box's interior. Defaults to False.	False
align	bool	If True, automatically aligns GeoSeries based on their indices. If False, the order of elements is preserved.	True

Returns:

Type	Description
Any	The filtered data.

Source code in leafmap/common.py

def filter_bounds(data, bbox, within=False, align=True, **kwargs: Any) -> Any:
    """Filters a GeoDataFrame or GeoSeries by a bounding box.

    Args:
        data (str | GeoDataFrame): The input data to filter. Can be a file path or a GeoDataFrame.
        bbox (list | GeoDataFrame): The bounding box to filter by. Can be a list of 4 coordinates or a file path or a GeoDataFrame.
        within (bool, optional): Whether to filter by the bounding box or the bounding box's interior. Defaults to False.
        align (bool, optional): If True, automatically aligns GeoSeries based on their indices. If False, the order of elements is preserved.

    Returns:
        The filtered data.
    """
    import geopandas as gpd

    if isinstance(data, str):
        data = gpd.read_file(data, **kwargs)
    elif not isinstance(data, (gpd.GeoDataFrame, gpd.GeoSeries)):
        raise TypeError("data must be a file path or a GeoDataFrame or GeoSeries")

    if isinstance(bbox, list):
        if len(bbox) != 4:
            raise ValueError("bbox must be a list of 4 coordinates")
        bbox = bbox_to_gdf(bbox)
    elif isinstance(bbox, str):
        bbox = gpd.read_file(bbox, **kwargs)

    if within:
        result = data[data.within(bbox.union_all(), align=align)]
    else:
        result = data[data.intersects(bbox.union_all(), align=align)]

    return result

filter_date(data, start_date=None, end_date=None, date_field='date', date_args={}, **kwargs)

Filters a DataFrame, GeoDataFrame or GeoSeries by a date range.

Parameters:

Name	Type	Description	Default
data	str | DataFrame | GeoDataFrame	The input data to filter. Can be a file path or a DataFrame or GeoDataFrame.	required
start_date	str	The start date, e.g., 2023-01-01. Defaults to None.	None
end_date	str	The end date, e.g., 2023-12-31. Defaults to None.	None
date_field	str	The name of the date field. Defaults to "date".	'date'
date_args	dict	Additional arguments for pd.to_datetime. Defaults to {}.	{}

Returns:

Type	Description
Any	The filtered data.

Source code in leafmap/common.py

def filter_date(
    data, start_date=None, end_date=None, date_field="date", date_args={}, **kwargs
) -> Any:
    """Filters a DataFrame, GeoDataFrame or GeoSeries by a date range.

    Args:
        data (str | DataFrame | GeoDataFrame): The input data to filter. Can be a file path or a DataFrame or GeoDataFrame.
        start_date (str, optional): The start date, e.g., 2023-01-01. Defaults to None.
        end_date (str, optional): The end date, e.g., 2023-12-31. Defaults to None.
        date_field (str, optional): The name of the date field. Defaults to "date".
        date_args (dict, optional): Additional arguments for pd.to_datetime. Defaults to {}.

    Returns:
        The filtered data.
    """

    import datetime

    import geopandas as gpd
    import pandas as pd

    if isinstance(data, str):
        data = gpd.read_file(data, **kwargs)
    elif not isinstance(
        data, (gpd.GeoDataFrame, gpd.GeoSeries, pd.DataFrame, pd.Series)
    ):
        raise TypeError("data must be a file path or a GeoDataFrame or GeoSeries")

    if date_field not in data.columns:
        raise ValueError(f"date_field must be one of {data.columns}")

    new_field = f"{date_field}_temp"
    data[new_field] = pd.to_datetime(data[date_field], **date_args)

    if end_date is None:
        end_date = datetime.datetime.now().strftime("%Y-%m-%d")

    if start_date is None:
        start_date = data[new_field].min()

    mask = (data[new_field] >= start_date) & (data[new_field] <= end_date)
    result = data.loc[mask]
    return result.drop(columns=[new_field], axis=1)

filter_geom_type(data, geom_type, output=None, **kwargs)

Filters a GeoDataFrame based on the geometry type.

Parameters:

Name	Type	Description	Default
data	Union[str, dict, GeoDataFrame]	The GeoDataFrame to filter.	required
geom_type	str	The geometry type to filter by.	required
output	Optional[str]	The file path to save the filtered GeoDataFrame. Defaults to None.	None
**kwargs	Any	Additional keyword arguments to pass to the GeoDataFrame.read_file method.	{}

Returns:

Type	Description
GeoDataFrame	The filtered GeoDataFrame.

Source code in leafmap/common.py

def filter_geom_type(
    data: Union[str, dict, "gpd.GeoDataFrame"],
    geom_type: str,
    output: Optional[str] = None,
    **kwargs: Any,
) -> "gpd.GeoDataFrame":
    """
    Filters a GeoDataFrame based on the geometry type.

    Args:
        data (Union[str, dict, gpd.GeoDataFrame]): The GeoDataFrame to filter.
        geom_type (str): The geometry type to filter by.
        output (Optional[str], optional): The file path to save the filtered GeoDataFrame. Defaults to None.
        **kwargs: Additional keyword arguments to pass to the GeoDataFrame.read_file method.

    Returns:
        The filtered GeoDataFrame.
    """

    if isinstance(data, str):
        data = read_vector(data)
    elif isinstance(data, dict):
        data = gpd.GeoDataFrame.from_features(data)
    elif isinstance(data, gpd.GeoDataFrame):
        pass
    else:
        raise ValueError(
            "Invalid data type. Must be a string, dictionary, or GeoDataFrame."
        )

    filtered = data[data.geom_type == geom_type]

    if output is not None:
        if os.path.exists(output):
            if len(filtered) < len(data):
                filtered.to_file(output, **kwargs)
        else:
            filtered.to_file(output, **kwargs)

    return filtered

find_closest_date(target_date, date_list, fmt='%Y-%m-%d')

Finds the closest date string in a list of date strings to a given target date.

Parameters:

Name	Type	Description	Default
target_date	str	The reference date string to compare against.	required
date_list	List[str]	A list of date strings to search.	required
fmt	str	The date format used for parsing. Defaults to "%Y-%m-%d".	'%Y-%m-%d'

Returns:

Type	Description
Optional[str]	Optional[str]: The date string from date_list that is closest to target_date, or None if date_list is empty or invalid.

Source code in leafmap/common.py

def find_closest_date(
    target_date: str, date_list: List[str], fmt: str = "%Y-%m-%d"
) -> Optional[str]:
    """Finds the closest date string in a list of date strings to a given target date.

    Args:
        target_date (str): The reference date string to compare against.
        date_list (List[str]): A list of date strings to search.
        fmt (str, optional): The date format used for parsing. Defaults to "%Y-%m-%d".

    Returns:
        Optional[str]: The date string from `date_list` that is closest to `target_date`,
            or None if `date_list` is empty or invalid.
    """
    from datetime import datetime
    from typing import List, Optional

    if not date_list:
        return None

    try:
        date_list = list(date_list)
    except Exception:
        print(f"date_list must be a list of date strings: {date_list}")
        return None

    if target_date is None:
        return date_list[0]

    try:
        target = datetime.strptime(target_date, fmt)
        parsed_dates = [(datetime.strptime(d, fmt), d) for d in date_list]
    except ValueError as e:
        print(f"Date parsing error: {e}")
        return None

    # Find the date with the smallest absolute time difference
    closest_date = min(parsed_dates, key=lambda x: abs(x[0] - target))[1]
    return closest_date

find_files(input_dir, ext=None, fullpath=True, recursive=True, include_hidden=False)

Find files in a directory.

Parameters:

Name	Type	Description	Default
input_dir	str	The input directory.	required
ext	str	The file extension to match. Defaults to None.	None
fullpath	bool	Whether to return the full path. Defaults to True.	True
recursive	bool	Whether to search recursively. Defaults to True.	True
include_hidden	bool	Whether to include hidden files. Defaults to False.	False

Source code in leafmap/common.py

def find_files(
    input_dir, ext=None, fullpath=True, recursive=True, include_hidden=False
):
    """Find files in a directory.

    Args:
        input_dir (str): The input directory.
        ext (str, optional): The file extension to match. Defaults to None.
        fullpath (bool, optional): Whether to return the full path. Defaults to True.
        recursive (bool, optional): Whether to search recursively. Defaults to True.
        include_hidden (bool, optional): Whether to include hidden files. Defaults to False.
    Returns:
        A list of matching files.
    """

    from pathlib import Path

    files = []

    if ext is None:
        ext = "*"
    else:
        ext = ext.replace(".", "")

    ext = f"*.{ext}"

    if recursive:
        if fullpath:
            files = [str(path.joinpath()) for path in Path(input_dir).rglob(ext)]
        else:
            files = [str(path.name) for path in Path(input_dir).rglob(ext)]
    else:
        if fullpath:
            files = [str(path.joinpath()) for path in Path(input_dir).glob(ext)]
        else:
            files = [path.name for path in Path(input_dir).glob(ext)]

    files.sort()
    if not include_hidden:
        files = [file for file in files if not os.path.basename(file).startswith(".")]
    return files

flatten_dict(my_dict, parent_key=False, sep='.')

Flattens a nested dictionary.

Parameters:

Name	Type	Description	Default
my_dict	dict	The dictionary to flatten.	required
parent_key	bool	Whether to include the parent key. Defaults to False.	False
sep	str	The separator to use. Defaults to '.'.	'.'

Returns:

Type	Description
Dict[str, Any]	The flattened dictionary.

Source code in leafmap/stac.py

def flatten_dict(
    my_dict: Dict[str, Any], parent_key: bool = False, sep: str = "."
) -> Dict[str, Any]:
    """Flattens a nested dictionary.

    Args:
        my_dict (dict): The dictionary to flatten.
        parent_key (bool, optional): Whether to include the parent key. Defaults to False.
        sep (str, optional): The separator to use. Defaults to '.'.

    Returns:
        The flattened dictionary.
    """

    flat_dict = {}
    for key, value in my_dict.items():
        if not isinstance(value, dict):
            flat_dict[key] = value
        else:
            sub_dict = flatten_dict(value)
            for sub_key, sub_value in sub_dict.items():
                if parent_key:
                    flat_dict[parent_key + sep + sub_key] = sub_value
                else:
                    flat_dict[sub_key] = sub_value

    return flat_dict

gdb_layer_names(gdb_path)

Get a list of layer names in a File Geodatabase (GDB).

Parameters:

Name	Type	Description	Default
gdb_path	str	The path to the File Geodatabase (GDB).	required

Returns:

Type	Description
List[str]	A list of layer names in the GDB.

Source code in leafmap/common.py

def gdb_layer_names(gdb_path: str) -> List[str]:
    """Get a list of layer names in a File Geodatabase (GDB).

    Args:
        gdb_path (str): The path to the File Geodatabase (GDB).

    Returns:
        A list of layer names in the GDB.
    """

    from osgeo import ogr

    # Open the GDB
    gdb_driver = ogr.GetDriverByName("OpenFileGDB")
    gdb_dataset = gdb_driver.Open(gdb_path, 0)

    # Get the number of layers in the GDB
    layer_count = gdb_dataset.GetLayerCount()
    # Iterate over the layers
    layer_names = []
    for i in range(layer_count):
        layer = gdb_dataset.GetLayerByIndex(i)
        feature_class_name = layer.GetName()
        layer_names.append(feature_class_name)

    # Close the GDB dataset
    gdb_dataset = None
    return layer_names

gdb_to_vector(gdb_path, out_dir, layers=None, filenames=None, gdal_driver='GPKG', file_extension=None, overwrite=False, quiet=False, **kwargs)

Converts layers from a File Geodatabase (GDB) to a vector format.

Parameters:

Name	Type	Description	Default
gdb_path	str	The path to the File Geodatabase (GDB).	required
out_dir	str	The output directory to save the converted files.	required
layers	Optional[List[str]]	A list of layer names to convert. If None, all layers will be converted. Default is None.	None
filenames	Optional[List[str]]	A list of output file names. If None, the layer names will be used as the file names. Default is None.	None
gdal_driver	str	The GDAL driver name for the output vector format. Default is "GPKG".	'GPKG'
file_extension	Optional[str]	The file extension for the output files. If None, it will be determined automatically based on the gdal_driver. Default is None.	None
overwrite	bool	Whether to overwrite the existing output files. Default is False.	False
quiet	bool	If True, suppress the log output. Defaults to False.	False

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def gdb_to_vector(
    gdb_path: str,
    out_dir: str,
    layers: Optional[List[str]] = None,
    filenames: Optional[List[str]] = None,
    gdal_driver: str = "GPKG",
    file_extension: Optional[str] = None,
    overwrite: bool = False,
    quiet=False,
    **kwargs: Any,
) -> None:
    """Converts layers from a File Geodatabase (GDB) to a vector format.

    Args:
        gdb_path (str): The path to the File Geodatabase (GDB).
        out_dir (str): The output directory to save the converted files.
        layers (Optional[List[str]]): A list of layer names to convert. If None, all layers will be converted. Default is None.
        filenames (Optional[List[str]]): A list of output file names. If None, the layer names will be used as the file names. Default is None.
        gdal_driver (str): The GDAL driver name for the output vector format. Default is "GPKG".
        file_extension (Optional[str]): The file extension for the output files. If None, it will be determined automatically based on the gdal_driver. Default is None.
        overwrite (bool): Whether to overwrite the existing output files. Default is False.
        quiet (bool): If True, suppress the log output. Defaults to False.

    Returns:
        None
    """
    from osgeo import ogr

    # Open the GDB
    gdb_driver = ogr.GetDriverByName("OpenFileGDB")
    gdb_dataset = gdb_driver.Open(gdb_path, 0)

    # Get the number of layers in the GDB
    layer_count = gdb_dataset.GetLayerCount()

    if isinstance(layers, str):
        layers = [layers]

    if isinstance(filenames, str):
        filenames = [filenames]

    if filenames is not None:
        if len(filenames) != len(layers):
            raise ValueError("The length of filenames must match the length of layers.")

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    ii = 0
    # Iterate over the layers
    for i in range(layer_count):
        layer = gdb_dataset.GetLayerByIndex(i)
        feature_class_name = layer.GetName()

        if layers is not None:
            if feature_class_name not in layers:
                continue

        if file_extension is None:
            file_extension = get_gdal_file_extension(gdal_driver)

        # Create the output file path
        if filenames is not None:
            output_file = os.path.join(out_dir, filenames[ii] + "." + file_extension)
            ii += 1
        else:
            output_file = os.path.join(
                out_dir, feature_class_name + "." + file_extension
            )

        if os.path.exists(output_file) and not overwrite:
            print(f"File {output_file} already exists. Skipping...")
            continue
        else:
            if not quiet:
                print(f"Converting layer {feature_class_name} to {output_file}...")

        # Create the output driver
        output_driver = ogr.GetDriverByName(gdal_driver)
        output_dataset = output_driver.CreateDataSource(output_file)

        # Copy the input layer to the output format
        output_dataset.CopyLayer(layer, feature_class_name)

        output_dataset = None

    # Close the GDB dataset
    gdb_dataset = None

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
	A bounding box in the form of a list (minx, miny, maxx, maxy) or GeoDataFrame.

Source code in leafmap/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:
        A bounding box in the form of a list (minx, miny, maxx, maxy) or GeoDataFrame.
    """
    bounds = gdf.total_bounds
    if return_geom:
        return bbox_to_gdf(bbox=bounds)
    else:
        return bounds

gdf_centroid(gdf, return_geom=False)

Returns the centroid of a GeoDataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoDataFrame.	required
return_geom	bool	Whether to return the bounding box as a GeoDataFrame. Defaults to False.	False

Returns:

Type	Description
	A bounding box in the form of a list (lon, lat) or GeoDataFrame.

Source code in leafmap/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:
        A bounding box in the form of a list (lon, lat) or GeoDataFrame.
    """

    warnings.filterwarnings("ignore")

    centroid = gdf_bounds(gdf, return_geom=True).centroid
    if return_geom:
        return centroid
    else:
        return centroid.x[0], centroid.y[0]

gdf_geom_type(gdf, first_only=True)

Returns the geometry type of a GeoDataFrame.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	A GeoDataFrame.	required
first_only	bool	Whether to return the geometry type of the f irst feature in the GeoDataFrame. Defaults to True.	True

Returns:

Type	Description
	The geometry type of the GeoDataFrame, such as Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon. For more info, see https://shapely.readthedocs.io/en/stable/manual.html

Source code in leafmap/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 f
            irst feature in the GeoDataFrame. Defaults to True.

    Returns:
        The geometry type of the GeoDataFrame, such as Point, LineString,
            Polygon, MultiPoint, MultiLineString, MultiPolygon.
            For more info, see https://shapely.readthedocs.io/en/stable/manual.html
    """
    import geopandas as gpd

    if first_only:
        return gdf.geometry.type[0]
    else:
        return gdf.geometry.type

gdf_to_bokeh(gdf)

Function to convert a GeoPandas GeoDataFrame to a Bokeh ColumnDataSource object.

:param: (GeoDataFrame) gdf: GeoPandas GeoDataFrame with polygon(s) under the column name 'geometry.'

:return: ColumnDataSource for Bokeh.

Source code in leafmap/common.py

def gdf_to_bokeh(gdf):
    """
    Function to convert a GeoPandas GeoDataFrame to a Bokeh
    ColumnDataSource object.

    :param: (GeoDataFrame) gdf: GeoPandas GeoDataFrame with polygon(s) under
                                the column name 'geometry.'

    :return: ColumnDataSource for Bokeh.
    """
    from bokeh.plotting import ColumnDataSource

    shape_type = gdf_geom_type(gdf)

    gdf_new = gdf.drop("geometry", axis=1).copy()
    gdf_new["x"] = gdf.apply(
        get_geometry_coords,
        geom="geometry",
        coord_type="x",
        shape_type=shape_type,
        mercator=True,
        axis=1,
    )

    gdf_new["y"] = gdf.apply(
        get_geometry_coords,
        geom="geometry",
        coord_type="y",
        shape_type=shape_type,
        mercator=True,
        axis=1,
    )

    return ColumnDataSource(gdf_new)

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
	A pandas DataFrame containing the GeoDataFrame.

Source code in leafmap/common.py

def gdf_to_df(gdf, drop_geom=True):
    """Converts a GeoDataFrame to a pandas DataFrame.

    Args:
        gdf (gpd.GeoDataFrame): A GeoDataFrame.
        drop_geom (bool, optional): Whether to drop the geometry column. Defaults to True.

    Returns:
        A pandas DataFrame containing the GeoDataFrame.
    """
    import pandas as pd

    if drop_geom:
        df = pd.DataFrame(gdf.drop(columns=["geometry"]))
    else:
        df = pd.DataFrame(gdf)

    return df

gdf_to_geojson(gdf, out_geojson=None, epsg=None, tuple_to_list=False, encoding='utf-8')

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
tuple_to_list	bool	Whether to convert tuples to lists. Defaults to False.	False
encoding	str	The encoding to use for the GeoJSON. Defaults to "utf-8".	'utf-8'

Raises:

Type	Description
TypeError	When the output file extension is incorrect.
Exception	When the conversion fails.

Returns:

Type	Description
Optional[dict]	When out_json is None returns a dict.

Source code in leafmap/common.py

def gdf_to_geojson(
    gdf, out_geojson=None, epsg=None, tuple_to_list=False, encoding="utf-8"
) -> Optional[dict]:
    """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.
        tuple_to_list (bool, optional): Whether to convert tuples to lists. Defaults to False.
        encoding (str, optional): The encoding to use for the GeoJSON. Defaults to "utf-8".

    Raises:
        TypeError: When the output file extension is incorrect.
        Exception: When the conversion fails.

    Returns:
        When out_json is None returns a dict.
    """
    check_package(name="geopandas", URL="https://geopandas.org")

    def listit(t):
        return list(map(listit, t)) if isinstance(t, (list, tuple)) else t

    try:
        if epsg is not None:
            if gdf.crs is not None and gdf.crs.to_epsg() != epsg:
                gdf = gdf.to_crs(epsg=epsg)
        geojson = gdf.__geo_interface__

        if tuple_to_list:
            for feature in geojson["features"]:
                feature["geometry"]["coordinates"] = listit(
                    feature["geometry"]["coordinates"]
                )

        if out_geojson is None:
            return geojson
        else:
            ext = os.path.splitext(out_geojson)[1]
            if ext.lower() not in [".json", ".geojson"]:
                raise TypeError(
                    "The output file extension must be either .json or .geojson"
                )
            out_dir = os.path.dirname(out_geojson)
            if not os.path.exists(out_dir):
                os.makedirs(out_dir)

            gdf.to_file(out_geojson, driver="GeoJSON", encoding=encoding)
    except Exception as e:
        raise Exception(e)

gedi_download_file(url, filename=None, username=None, password=None)

Downloads a file from the given URL and saves it to the specified filename. If no filename is provided, the name of the file from the URL will be used.

Parameters:

Name	Type	Description	Default
url	str	The URL of the file to download. e.g., https://daac.ornl.gov/daacdata/gedi/GEDI_L4A_AGB_Density_V2_1/data/GEDI04_A_2019298202754_O04921_01_T02899_02_002_02_V002.h5	required
filename	str	The name of the file to save the downloaded content to. Defaults to None.	None
username	str	Username for authentication. Can also be set using the EARTHDATA_USERNAME environment variable. Defaults to None. Create an account at https://urs.earthdata.nasa.gov	None
password	str	Password for authentication. Can also be set using the EARTHDATA_PASSWORD environment variable. Defaults to None.	None

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def gedi_download_file(
    url: str, filename: str = None, username: str = None, password: str = None
) -> None:
    """
    Downloads a file from the given URL and saves it to the specified filename.
    If no filename is provided, the name of the file from the URL will be used.

    Args:
        url (str): The URL of the file to download.
            e.g., https://daac.ornl.gov/daacdata/gedi/GEDI_L4A_AGB_Density_V2_1/data/GEDI04_A_2019298202754_O04921_01_T02899_02_002_02_V002.h5
        filename (str, optional): The name of the file to save the downloaded content to. Defaults to None.
        username (str, optional): Username for authentication. Can also be set using the EARTHDATA_USERNAME environment variable. Defaults to None.
            Create an account at https://urs.earthdata.nasa.gov
        password (str, optional): Password for authentication. Can also be set using the EARTHDATA_PASSWORD environment variable. Defaults to None.

    Returns:
        None
    """
    from urllib.parse import urlparse

    import requests
    from tqdm import tqdm

    if username is None:
        username = os.environ.get("EARTHDATA_USERNAME", None)
    if password is None:
        password = os.environ.get("EARTHDATA_PASSWORD", None)

    if username is None or password is None:
        raise ValueError(
            "Username and password must be provided. Create an account at https://urs.earthdata.nasa.gov."
        )

    with requests.Session() as session:
        r1 = session.request("get", url, stream=True)
        r = session.get(r1.url, auth=(username, password), stream=True)
        print(r.status_code)

        if r.status_code == 200:
            total_size = int(r.headers.get("content-length", 0))
            block_size = 1024  # 1 KB

            # Use the filename from the URL if not provided
            if not filename:
                parsed_url = urlparse(url)
                filename = parsed_url.path.split("/")[-1]

            progress_bar = tqdm(total=total_size, unit="B", unit_scale=True)

            with open(filename, "wb") as file:
                for data in r.iter_content(block_size):
                    progress_bar.update(len(data))
                    file.write(data)

            progress_bar.close()

gedi_download_files(urls, outdir=None, filenames=None, username=None, password=None, overwrite=False)

Downloads files from the given URLs and saves them to the specified directory. If no directory is provided, the current directory will be used. If no filenames are provided, the names of the files from the URLs will be used.

Parameters:

Name	Type	Description	Default
urls	List[str]	The URLs of the files to download. e.g., ["https://example.com/file1.txt", "https://example.com/file2.txt"]	required
outdir	str	The directory to save the downloaded files to. Defaults to None.	None
filenames	str	The names of the files to save the downloaded content to. Defaults to None.	None
username	str	Username for authentication. Can also be set using the EARTHDATA_USERNAME environment variable. Defaults to None. Create an account at https://urs.earthdata.nasa.gov	None
password	str	Password for authentication. Can also be set using the EARTHDATA_PASSWORD environment variable. Defaults to None.	None
overwrite	bool	Whether to overwrite the existing output files. Default is False.	False

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def gedi_download_files(
    urls: List[str],
    outdir: str = None,
    filenames: str = None,
    username: str = None,
    password: str = None,
    overwrite: bool = False,
) -> None:
    """
    Downloads files from the given URLs and saves them to the specified directory.
    If no directory is provided, the current directory will be used.
    If no filenames are provided, the names of the files from the URLs will be used.

    Args:
        urls (List[str]): The URLs of the files to download.
            e.g., ["https://example.com/file1.txt", "https://example.com/file2.txt"]
        outdir (str, optional): The directory to save the downloaded files to. Defaults to None.
        filenames (str, optional): The names of the files to save the downloaded content to. Defaults to None.
        username (str, optional): Username for authentication. Can also be set using the EARTHDATA_USERNAME environment variable. Defaults to None.
            Create an account at https://urs.earthdata.nasa.gov
        password (str, optional): Password for authentication. Can also be set using the EARTHDATA_PASSWORD environment variable. Defaults to None.
        overwrite (bool): Whether to overwrite the existing output files. Default is False.

    Returns:
        None
    """

    from urllib.parse import urlparse

    import geopandas as gpd
    import requests
    from tqdm import tqdm

    if isinstance(urls, gpd.GeoDataFrame):
        urls = urls["granule_url"].tolist()

    session = requests.Session()

    if username is None:
        username = os.environ.get("EARTHDATA_USERNAME", None)
    if password is None:
        password = os.environ.get("EARTHDATA_PASSWORD", None)

    if username is None or password is None:
        print("Username and password must be provided.")
        return

    if outdir is None:
        outdir = os.getcwd()

    if not os.path.exists(outdir):
        os.makedirs(outdir)

    for index, url in enumerate(urls):
        print(f"Downloading file {index+1} of {len(urls)}...")

        if url is None:
            continue

        # Use the filename from the URL if not provided
        if not filenames:
            parsed_url = urlparse(url)
            filename = parsed_url.path.split("/")[-1]
        else:
            filename = filenames.pop(0)

        filepath = os.path.join(outdir, filename)
        if os.path.exists(filepath) and not overwrite:
            print(f"File {filepath} already exists. Skipping...")
            continue

        r1 = session.request("get", url, stream=True)
        r = session.get(r1.url, auth=(username, password), stream=True)

        if r.status_code == 200:
            total_size = int(r.headers.get("content-length", 0))
            block_size = 1024  # 1 KB

            progress_bar = tqdm(total=total_size, unit="B", unit_scale=True)

            with open(filepath, "wb") as file:
                for data in r.iter_content(block_size):
                    progress_bar.update(len(data))
                    file.write(data)

            progress_bar.close()

    session.close()

gedi_search(roi, start_date=None, end_date=None, add_roi=False, return_type='gdf', output=None, sort_filesize=False, **kwargs)

Searches for GEDI data using the Common Metadata Repository (CMR) API. The source code for this function is adapted from https://github.com/ornldaac/gedi_tutorials. Credits to ORNL DAAC and Rupesh Shrestha.

Parameters:

Name	Type	Description	Default
roi	Any	A list, tuple, or file path representing the bounding box coordinates in the format (min_lon, min_lat, max_lon, max_lat), or a GeoDataFrame containing the region of interest geometry.	required
start_date	Optional[str]	The start date of the temporal range to search for data in the format 'YYYY-MM-DD'.	None
end_date	Optional[str]	The end date of the temporal range to search for data in the format 'YYYY-MM-DD'.	None
add_roi	bool	A boolean value indicating whether to include the region of interest as a granule in the search results. Default is False.	False
return_type	str	The type of the search results to return. Must be one of 'df' (DataFrame), 'gdf' (GeoDataFrame), or 'csv' (CSV file). Default is 'gdf'.	'gdf'
output	Optional[str]	The file path to save the CSV output when return_type is 'csv'. Optional and only applicable when return_type is 'csv'.	None
sort_filesize	bool	A boolean value indicating whether to sort the search results.	False
**kwargs	Any	Additional keyword arguments to be passed to the CMR API.	{}

Returns:

Type	Description
Union[DataFrame, None]	The search results as a pandas DataFrame (return_type='df'), geopandas GeoDataFrame
Union[DataFrame, None]	(return_type='gdf'), or a CSV file (return_type='csv').

Raises:

Type	Description
ValueError	If roi is not a list, tuple, or file path.

Source code in leafmap/common.py

def gedi_search(
    roi: Any,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    add_roi: bool = False,
    return_type: str = "gdf",
    output: Optional[str] = None,
    sort_filesize: bool = False,
    **kwargs: Any,
) -> Union[pd.DataFrame, None]:
    """
    Searches for GEDI data using the Common Metadata Repository (CMR) API.
    The source code for this function is adapted from https://github.com/ornldaac/gedi_tutorials.
    Credits to ORNL DAAC and Rupesh Shrestha.

    Args:
        roi: A list, tuple, or file path representing the bounding box coordinates
            in the format (min_lon, min_lat, max_lon, max_lat), or a GeoDataFrame
            containing the region of interest geometry.
        start_date: The start date of the temporal range to search for data
            in the format 'YYYY-MM-DD'.
        end_date: The end date of the temporal range to search for data
            in the format 'YYYY-MM-DD'.
        add_roi: A boolean value indicating whether to include the region of interest
            as a granule in the search results. Default is False.
        return_type: The type of the search results to return. Must be one of 'df'
            (DataFrame), 'gdf' (GeoDataFrame), or 'csv' (CSV file). Default is 'gdf'.
        output: The file path to save the CSV output when return_type is 'csv'.
            Optional and only applicable when return_type is 'csv'.
        sort_filesize: A boolean value indicating whether to sort the search results.
        **kwargs: Additional keyword arguments to be passed to the CMR API.

    Returns:
        The search results as a pandas DataFrame (return_type='df'), geopandas GeoDataFrame
        (return_type='gdf'), or a CSV file (return_type='csv').

    Raises:
        ValueError: If roi is not a list, tuple, or file path.

    """

    import datetime as dt

    import geopandas as gpd
    import pandas as pd
    import requests
    from shapely.geometry import MultiPolygon, Polygon, box
    from shapely.ops import orient

    # CMR API base url
    cmrurl = "https://cmr.earthdata.nasa.gov/search/"

    doi = "10.3334/ORNLDAAC/2056"  # GEDI L4A DOI

    # Construct the DOI search URL
    doisearch = cmrurl + "collections.json?doi=" + doi

    # Send a request to the CMR API to get the concept ID
    response = requests.get(doisearch)
    response.raise_for_status()
    concept_id = response.json()["feed"]["entry"][0]["id"]

    # CMR formatted start and end times
    if start_date is not None and end_date is not None:
        dt_format = "%Y-%m-%dT%H:%M:%SZ"
        start_date = dt.datetime.strptime(start_date, "%Y-%m-%d")
        end_date = dt.datetime.strptime(end_date, "%Y-%m-%d")
        temporal_str = (
            start_date.strftime(dt_format) + "," + end_date.strftime(dt_format)
        )
    else:
        temporal_str = None

    # CMR formatted bounding box
    if isinstance(roi, list) or isinstance(roi, tuple):
        bound_str = ",".join(map(str, roi))
    elif isinstance(roi, str):
        roi = gpd.read_file(roi)
        roi.geometry = roi.geometry.apply(orient, args=(1,))  # make counter-clockwise
    elif isinstance(roi, gpd.GeoDataFrame):
        roi.geometry = roi.geometry.apply(orient, args=(1,))  # make counter-clockwise
    else:
        raise ValueError("roi must be a list, tuple, or a file path.")

    page_num = 1
    page_size = 2000  # CMR page size limit

    granule_arr = []

    while True:
        # Define CMR search parameters
        cmr_param = {
            "collection_concept_id": concept_id,
            "page_size": page_size,
            "page_num": page_num,
        }

        if temporal_str is not None:
            cmr_param["temporal"] = temporal_str

        if kwargs:
            cmr_param.update(kwargs)

        granulesearch = cmrurl + "granules.json"

        if isinstance(roi, list) or isinstance(roi, tuple):
            cmr_param["bounding_box[]"] = bound_str
            response = requests.get(granulesearch, params=cmr_param)
            response.raise_for_status()
        else:
            cmr_param["simplify-shapefile"] = "true"
            geojson = {
                "shapefile": (
                    "region.geojson",
                    roi.geometry.to_json(),
                    "application/geo+json",
                )
            }
            response = requests.post(granulesearch, data=cmr_param, files=geojson)

        # Send a request to the CMR API to get the granules
        granules = response.json()["feed"]["entry"]

        if granules:
            for index, g in enumerate(granules):
                granule_url = ""
                granule_poly = ""

                # Read file size
                granule_size = float(g["granule_size"])

                # Read bounding geometries
                if "polygons" in g:
                    polygons = g["polygons"]
                    multipolygons = []
                    for poly in polygons:
                        i = iter(poly[0].split(" "))
                        ltln = list(map(" ".join, zip(i, i)))
                        multipolygons.append(
                            Polygon(
                                [
                                    [float(p.split(" ")[1]), float(p.split(" ")[0])]
                                    for p in ltln
                                ]
                            )
                        )
                    granule_poly = MultiPolygon(multipolygons)

                # Get URL to HDF5 files
                for links in g["links"]:
                    if (
                        "title" in links
                        and links["title"].startswith("Download")
                        and links["title"].endswith(".h5")
                    ):
                        granule_url = links["href"]

                granule_id = g["id"]
                title = g["title"]
                time_start = g["time_start"]
                time_end = g["time_end"]

                granule_arr.append(
                    [
                        granule_id,
                        title,
                        time_start,
                        time_end,
                        granule_size,
                        granule_url,
                        granule_poly,
                    ]
                )

            page_num += 1
        else:
            break

    # Add bound as the last row into the dataframe
    if add_roi:
        if isinstance(roi, list) or isinstance(roi, tuple):
            b = list(roi)
            granule_arr.append(
                ["roi", None, None, None, 0, None, box(b[0], b[1], b[2], b[3])]
            )
        else:
            granule_arr.append(["roi", None, None, None, 0, None, roi.geometry.item()])

    # Create a pandas dataframe
    columns = [
        "id",
        "title",
        "time_start",
        "time_end",
        "granule_size",
        "granule_url",
        "granule_poly",
    ]
    l4adf = pd.DataFrame(granule_arr, columns=columns)

    # Drop granules with empty geometry
    l4adf = l4adf[l4adf["granule_poly"] != ""]

    if sort_filesize:
        l4adf = l4adf.sort_values(by=["granule_size"], ascending=True)

    if return_type == "df":
        return l4adf
    elif return_type == "gdf":
        gdf = gpd.GeoDataFrame(l4adf, geometry="granule_poly")
        gdf.crs = "EPSG:4326"
        return gdf
    elif return_type == "csv":
        columns.remove("granule_poly")
        return l4adf.to_csv(output, index=False, columns=columns)
    else:
        raise ValueError("return_type must be one of 'df', 'gdf', or 'csv'.")

gedi_subset(spatial=None, start_date=None, end_date=None, out_dir=None, collection=None, variables=['all'], max_results=None, username=None, password=None, overwrite=False, **kwargs)

Subsets GEDI data using the Harmony API.

Parameters:

Name	Type	Description	Default
spatial	Union[str, GeoDataFrame, List[float]]	Spatial extent for subsetting. Can be a file path to a shapefile, a GeoDataFrame, or a list of bounding box coordinates [minx, miny, maxx, maxy]. Defaults to None.	None
start_date	str	Start date for subsetting in 'YYYY-MM-DD' format. Defaults to None.	None
end_date	str	End date for subsetting in 'YYYY-MM-DD' format. Defaults to None.	None
out_dir	str	Output directory to save the subsetted files. Defaults to None, which will use the current working directory.	None
collection	Collection	GEDI data collection. If not provided, the default collection with DOI '10.3334/ORNLDAAC/2056' will be used. Defaults to None.	None
variables	List[str]	List of variable names to subset. Defaults to ['all'], which subsets all available variables.	['all']
max_results	int	Maximum number of results to return. Defaults to None, which returns all results.	None
username	str	Earthdata username. Defaults to None, which will attempt to read from the 'EARTHDATA_USERNAME' environment variable.	None
password	str	Earthdata password. Defaults to None, which will attempt to read from the 'EARTHDATA_PASSWORD' environment variable.	None
overwrite	bool	Whether to overwrite existing files in the output directory. Defaults to False.	False
**kwargs	Any	Additional keyword arguments to pass to the Harmony API request.	{}

Raises:

Type	Description
ImportError	If the 'harmony' package is not installed.
ValueError	If the 'spatial', 'start_date', or 'end_date' arguments are not valid.

Returns:

Type	Description
	None.

Source code in leafmap/common.py

def gedi_subset(
    spatial=None,
    start_date=None,
    end_date=None,
    out_dir=None,
    collection=None,
    variables=["all"],
    max_results=None,
    username=None,
    password=None,
    overwrite=False,
    **kwargs: Any,
):
    """
    Subsets GEDI data using the Harmony API.

    Args:
        spatial (Union[str, gpd.GeoDataFrame, List[float]], optional): Spatial extent for subsetting.
            Can be a file path to a shapefile, a GeoDataFrame, or a list of bounding box coordinates [minx, miny, maxx, maxy].
            Defaults to None.
        start_date (str, optional): Start date for subsetting in 'YYYY-MM-DD' format.
            Defaults to None.
        end_date (str, optional): End date for subsetting in 'YYYY-MM-DD' format.
            Defaults to None.
        out_dir (str, optional): Output directory to save the subsetted files.
            Defaults to None, which will use the current working directory.
        collection (Collection, optional): GEDI data collection. If not provided,
            the default collection with DOI '10.3334/ORNLDAAC/2056' will be used.
            Defaults to None.
        variables (List[str], optional): List of variable names to subset.
            Defaults to ['all'], which subsets all available variables.
        max_results (int, optional): Maximum number of results to return.
            Defaults to None, which returns all results.
        username (str, optional): Earthdata username.
            Defaults to None, which will attempt to read from the 'EARTHDATA_USERNAME' environment variable.
        password (str, optional): Earthdata password.
            Defaults to None, which will attempt to read from the 'EARTHDATA_PASSWORD' environment variable.
        overwrite (bool, optional): Whether to overwrite existing files in the output directory.
            Defaults to False.
        **kwargs: Additional keyword arguments to pass to the Harmony API request.

    Raises:
        ImportError: If the 'harmony' package is not installed.
        ValueError: If the 'spatial', 'start_date', or 'end_date' arguments are not valid.

    Returns:
        None.
    """

    try:
        import harmony  # pylint: disable=E0401
    except ImportError:
        install_package("harmony-py")

    from datetime import datetime

    import geopandas as gpd
    import requests as re
    from harmony import (
        BBox,
        Client,
        Collection,  # pylint: disable=E0401
        Environment,
        Request,
    )

    if out_dir is None:
        out_dir = os.getcwd()

    if not os.path.exists(out_dir):
        os.makedirs(out_dir)

    if collection is None:
        # GEDI L4A DOI
        doi = "10.3334/ORNLDAAC/2056"

        # CMR API base url
        doisearch = f"https://cmr.earthdata.nasa.gov/search/collections.json?doi={doi}"
        concept_id = re.get(doisearch).json()["feed"]["entry"][0]["id"]
        concept_id
        collection = Collection(id=concept_id)

    if username is None:
        username = os.environ.get("EARTHDATA_USERNAME", None)
    if password is None:
        password = os.environ.get("EARTHDATA_PASSWORD", None)

    if username is None or password is None:
        raise ValueError("username and password must be provided.")

    harmony_client = Client(auth=(username, password))

    if isinstance(spatial, str):
        spatial = gpd.read_file(spatial)

    if isinstance(spatial, gpd.GeoDataFrame):
        spatial = spatial.total_bounds.tolist()

    if isinstance(spatial, list) and len(spatial) == 4:
        bounding_box = BBox(spatial[0], spatial[1], spatial[2], spatial[3])
    else:
        raise ValueError(
            "spatial must be a list of bounding box coordinates or a GeoDataFrame, or a file path."
        )

    if isinstance(start_date, str):
        start_date = datetime.strptime(start_date, "%Y-%m-%d")

    if isinstance(end_date, str):
        end_date = datetime.strptime(end_date, "%Y-%m-%d")

    if start_date is None or end_date is None:
        print("start_date and end_date must be provided.")
        temporal_range = None
    else:
        temporal_range = {"start": start_date, "end": end_date}

    request = Request(
        collection=collection,
        variables=variables,
        temporal=temporal_range,
        spatial=bounding_box,
        ignore_errors=True,
        max_results=max_results,
        **kwargs,
    )

    # submit harmony request, will return job id
    subset_job_id = harmony_client.submit(request)

    print(f"Processing job: {subset_job_id}")

    print(f"Waiting for the job to finish")
    results = harmony_client.result_json(subset_job_id, show_progress=True)

    print(f"Downloading subset files...")
    futures = harmony_client.download_all(
        subset_job_id, directory=out_dir, overwrite=overwrite
    )
    for f in futures:
        # all subsetted files have this suffix
        if f.result().endswith("subsetted.h5"):
            print(f"Downloaded: {f.result()}")

    print(f"Done downloading files.")

generate_index_html(directory, output='index.html')

Generates an HTML file named 'index.html' in the specified directory, listing all files in that directory as clickable links.

Parameters:

Name	Type	Description	Default
directory	str	The path to the directory for which to generate the index.html file.	required
output	str	The name of the output HTML file. Defaults to "index.html".	'index.html'

Returns:

Type	Description
None	None

Source code in leafmap/common.py

def generate_index_html(directory: str, output: str = "index.html") -> None:
    """
    Generates an HTML file named 'index.html' in the specified directory, listing
    all files in that directory as clickable links.

    Args:
        directory (str): The path to the directory for which to generate the index.html file.
        output (str, optional): The name of the output HTML file. Defaults to "index.html".

    Returns:
        None
    """
    # Get a list of files in the directory
    files = sorted(
        [f for f in os.listdir(directory) if os.path.isfile(os.path.join(directory, f))]
    )

    # Start the HTML content
    html_content = """<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Index of {directory}</title>
</head>
<body>
    <h1>Index of {directory}</h1>
    <ul>
""".format(directory=directory)

    # Add each file to the HTML list
    for file in files:
        html_content += '        <li><a href="{file}">{file}</a></li>\n'.format(
            file=file
        )

    # Close the HTML content
    html_content += """    </ul>
</body>
</html>"""

    # Write the HTML content to index.html in the specified directory
    with open(os.path.join(directory, output), "w") as f:
        f.write(html_content)

generate_latlon_grid(extent, dx=0.1, dy=0.1, crs='EPSG:4326', output=None)

Generate a rectangular lat/lon grid as polygons over a given extent.

Parameters

extent : tuple (xmin, ymin, xmax, ymax) in degrees, e.g. (-180, -60, 180, 85) dx : float Longitude interval in degrees (cell width) dy : float Latitude interval in degrees (cell height) crs : str or dict Coordinate reference system for the output GeoDataFrame

Returns

GeoDataFrame Columns: id, lon_min, lat_min, lon_max, lat_max, geometry

Source code in leafmap/common.py

def generate_latlon_grid(extent, dx=0.1, dy=0.1, crs="EPSG:4326", output=None):
    """
    Generate a rectangular lat/lon grid as polygons over a given extent.

    Parameters
    ----------
    extent : tuple
        (xmin, ymin, xmax, ymax) in degrees, e.g. (-180, -60, 180, 85)
    dx : float
        Longitude interval in degrees (cell width)
    dy : float
        Latitude interval in degrees (cell height)
    crs : str or dict
        Coordinate reference system for the output GeoDataFrame

    Returns
    -------
    GeoDataFrame
        Columns: id, lon_min, lat_min, lon_max, lat_max, geometry
    """

    import numpy as np
    import geopandas as gpd
    from shapely.geometry import Polygon

    xmin, ymin, xmax, ymax = extent

    # Ensure increasing order
    if xmax <= xmin or ymax <= ymin:
        raise ValueError("Invalid extent: xmax must be > xmin and ymax > ymin")

    # Generate grid coordinates (we’ll allow partial cells at the edges)
    lons = np.arange(xmin, xmax, dx)
    lats = np.arange(ymin, ymax, dy)

    polygons = []
    records = []

    cell_id = 0
    for lon in lons:
        for lat in lats:
            # Clip cells to the exact extent at the upper/right edges
            lon_max = min(lon + dx, xmax)
            lat_max = min(lat + dy, ymax)

            poly = Polygon(
                [
                    (lon, lat),
                    (lon_max, lat),
                    (lon_max, lat_max),
                    (lon, lat_max),
                    (lon, lat),
                ]
            )

            polygons.append(poly)
            records.append(
                {
                    "id": cell_id,
                    "lon_min": lon,
                    "lat_min": lat,
                    "lon_max": lon_max,
                    "lat_max": lat_max,
                }
            )
            cell_id += 1

    gdf = gpd.GeoDataFrame(records, geometry=polygons, crs=crs)

    if output is not None:
        gdf.to_file(output)

    return gdf

geojson_bounds(geojson)

Calculate the bounds of a GeoJSON object.

This function uses the shapely library to calculate the bounds of a GeoJSON object. If the shapely library is not installed, it will print a message and return None.

Parameters:

Name	Type	Description	Default
geojson	dict	A dictionary representing a GeoJSON object.	required

Returns:

Type	Description
Optional[list]	A list of bounds (minx, miny, maxx, maxy) if shapely is installed, None otherwise.

Source code in leafmap/common.py

def geojson_bounds(geojson: dict) -> Optional[list]:
    """
    Calculate the bounds of a GeoJSON object.

    This function uses the shapely library to calculate the bounds of a GeoJSON object.
    If the shapely library is not installed, it will print a message and return None.

    Args:
        geojson (dict): A dictionary representing a GeoJSON object.

    Returns:
        A list of bounds (minx, miny, maxx, maxy) if shapely is installed, None otherwise.
    """
    try:
        import shapely
    except ImportError:
        print("shapely is not installed")
        return

    if isinstance(geojson, str):
        geojson = json.loads(geojson)

    return list(shapely.bounds(shapely.from_geojson(json.dumps(geojson))))

geojson_layer(in_geojson, layer_name='GeoJSON', style={}, hover_style={}, style_callback=None, fill_colors=None, encoding='utf-8', **kwargs)

Adds a GeoJSON file to the map.

Parameters:

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

Raises:

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

Source code in leafmap/leafmap.py

def geojson_layer(
    in_geojson: Union[str, Dict],
    layer_name: Optional[str] = "GeoJSON",
    style: Optional[dict] = {},
    hover_style: Optional[dict] = {},
    style_callback: Optional[Callable] = None,
    fill_colors: Optional[list[str]] = None,
    encoding: Optional[str] = "utf-8",
    **kwargs,
) -> None:
    """Adds a GeoJSON file to the map.

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

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

    import geopandas as gpd

    gdf = None

    try:
        if isinstance(in_geojson, str):
            if in_geojson.startswith("http"):
                if common.is_jupyterlite():
                    import pyodide  # pylint: disable=E0401

                    output = os.path.basename(in_geojson)

                    output = os.path.abspath(output)
                    obj = pyodide.http.open_url(in_geojson)
                    with open(output, "w") as fd:
                        shutil.copyfileobj(obj, fd)
                    with open(output, "r") as fd:
                        data = json.load(fd)
                else:
                    gdf = gpd.read_file(in_geojson, encoding=encoding)

            else:
                gdf = gpd.read_file(in_geojson, encoding=encoding)

        elif isinstance(in_geojson, dict):
            gdf = gpd.GeoDataFrame.from_features(in_geojson)
        elif isinstance(in_geojson, gpd.GeoDataFrame):
            gdf = in_geojson
        else:
            raise TypeError("The input geojson must be a type of str or dict.")
    except Exception as e:
        raise Exception(e)

    if gdf.crs is None:
        # print(f"Warning: The dataset does not have a CRS defined. Assuming EPSG:4326.")
        gdf.crs = "EPSG:4326"
    elif gdf.crs != "EPSG:4326":
        gdf = gdf.to_crs("EPSG:4326")
    data = gdf.__geo_interface__

    try:
        first_feature = data["features"][0]
        if isinstance(first_feature["properties"].get("style"), str):
            # Loop through the features and update the style
            for feature in data["features"]:
                fstyle = feature["properties"].get("style")
                if isinstance(fstyle, str):
                    feature["properties"]["style"] = json.loads(fstyle)
    except Exception as e:
        print(e)
        pass

    geom_type = gdf.reset_index().geom_type[0]

    if style is None and (style_callback is None):
        style = {
            # "stroke": True,
            "color": "#3388ff",
            "weight": 2,
            "opacity": 1,
            "fill": True,
            "fillColor": "#3388ff",
            "fillOpacity": 0.2,
            # "dashArray": "9"
            # "clickable": True,
        }

        if geom_type in ["LineString", "MultiLineString"]:
            style["fill"] = False

    elif "weight" not in style:
        style["weight"] = 1

    if not hover_style:
        hover_style = {
            "weight": style["weight"] + 2,
            "fillOpacity": 0,
            "color": "yellow",
        }

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

    if fill_colors is not None:
        style_callback = random_color

    if style_callback is None:
        geojson = ipyleaflet.GeoJSON(
            data=data,
            style=style,
            hover_style=hover_style,
            name=layer_name,
            **kwargs,
        )
    else:
        geojson = ipyleaflet.GeoJSON(
            data=data,
            style=style,
            hover_style=hover_style,
            name=layer_name,
            style_callback=style_callback,
            **kwargs,
        )

    return geojson

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
	A pandas DataFrame containing the GeoJSON object.

Source code in leafmap/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:
        A pandas DataFrame containing the GeoJSON object.
    """

    import json
    from urllib.request import urlopen

    import pandas as pd

    if isinstance(in_geojson, str):
        if in_geojson.startswith("http"):
            with urlopen(in_geojson) as f:
                data = json.load(f)
        else:
            in_geojson = os.path.abspath(in_geojson)
            if not os.path.exists(in_geojson):
                raise FileNotFoundError("The provided GeoJSON file could not be found.")

            with open(in_geojson, encoding=encoding) as f:
                data = json.load(f)

    elif isinstance(in_geojson, dict):
        data = in_geojson

    df = pd.json_normalize(data["features"])
    df.columns = [col.replace("properties.", "") for col in df.columns]
    if drop_geometry:
        df = df[df.columns.drop(list(df.filter(regex="geometry")))]
    return df

geojson_to_gdf(in_geojson, encoding='utf-8', **kwargs)

Converts a GeoJSON object to a geopandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
in_geojson	str | dict	The input GeoJSON file or GeoJSON object as a dict.	required
encoding	str	The encoding of the GeoJSON object. Defaults to "utf-8".	'utf-8'

Returns:

Type	Description
	A GeoPandas GeoDataFrame containing the GeoJSON object.

Source code in leafmap/common.py

def geojson_to_gdf(in_geojson, encoding="utf-8", **kwargs: Any):
    """Converts a GeoJSON object to a geopandas GeoDataFrame.

    Args:
        in_geojson (str | dict): The input GeoJSON file or GeoJSON object as a dict.
        encoding (str, optional): The encoding of the GeoJSON object. Defaults to "utf-8".

    Returns:
        A GeoPandas GeoDataFrame containing the GeoJSON object.
    """

    import geopandas as gpd

    if isinstance(in_geojson, dict):
        out_file = temp_file_path(extension="geojson")
        with open(out_file, "w") as f:
            json.dump(in_geojson, f)
            in_geojson = out_file

    gdf = gpd.read_file(in_geojson, encoding=encoding, **kwargs)
    return gdf

geojson_to_gpkg(in_geojson, out_gpkg, **kwargs)

Converts a GeoJSON object to GeoPackage.

Parameters:

Name	Type	Description	Default
in_geojson	str | dict	The input GeoJSON file or dict.	required
out_gpkg	str	The output GeoPackage path.	required

Source code in leafmap/common.py

def geojson_to_gpkg(in_geojson, out_gpkg, **kwargs: Any):
    """Converts a GeoJSON object to GeoPackage.

    Args:
        in_geojson (str | dict): The input GeoJSON file or dict.
        out_gpkg (str): The output GeoPackage path.
    """
    import json

    import geopandas as gpd

    ext = os.path.splitext(out_gpkg)[1]
    if ext.lower() != ".gpkg":
        out_gpkg = out_gpkg + ".gpkg"
    out_gpkg = check_file_path(out_gpkg)

    if isinstance(in_geojson, dict):
        out_file = temp_file_path(extension="geojson")
        with open(out_file, "w") as f:
            json.dump(in_geojson, f)
            in_geojson = out_file

    gdf = gpd.read_file(in_geojson, **kwargs)
    name = os.path.splitext(os.path.basename(out_gpkg))[0]
    gdf.to_file(out_gpkg, layer=name, driver="GPKG")

geojson_to_mbtiles(input_file, output_file, layer_name=None, options=None, quiet=False)

Converts vector data to .mbtiles using Tippecanoe.

Parameters:

Name	Type	Description	Default
input_file	str	Path to the input vector data file (e.g., .geojson).	required
output_file	str	Path to the output .mbtiles file.	required
layer_name	Optional[str]	Optional name for the layer. Defaults to None.	None
options	Optional[List[str]]	List of additional arguments for tippecanoe. For example '-zg' for auto maxzoom. Defaults to None.	None
quiet	bool	If True, suppress the log output. Defaults to False.	False

Returns:

Type	Description
Optional[str]	Output from the Tippecanoe command, or None if there was an error or if Tippecanoe is not installed.

Raises:

Type	Description
CalledProcessError	If there's an error executing the tippecanoe command.

Source code in leafmap/common.py

def geojson_to_mbtiles(
    input_file: str,
    output_file: str,
    layer_name: Optional[str] = None,
    options: Optional[List[str]] = None,
    quiet: bool = False,
) -> Optional[str]:
    """
    Converts vector data to .mbtiles using Tippecanoe.

    Args:
        input_file (str): Path to the input vector data file (e.g., .geojson).
        output_file (str): Path to the output .mbtiles file.
        layer_name (Optional[str]): Optional name for the layer. Defaults to None.
        options (Optional[List[str]]): List of additional arguments for tippecanoe. For example '-zg' for auto maxzoom. Defaults to None.
        quiet (bool): If True, suppress the log output. Defaults to False.

    Returns:
        Output from the Tippecanoe command, or None if there was an error or if Tippecanoe is not installed.

    Raises:
        subprocess.CalledProcessError: If there's an error executing the tippecanoe command.
    """

    import shutil
    import subprocess

    # Check if tippecanoe exists
    if shutil.which("tippecanoe") is None:
        print("Error: tippecanoe is not installed.")
        print("You can install it using conda with the following command:")
        print("conda install -c conda-forge tippecanoe")
        return None

    command = ["tippecanoe", "-o", output_file]

    # Add layer name specification if provided
    if layer_name:
        command.extend(["-L", f"{layer_name}:{input_file}"])
    else:
        command.append(input_file)

    # Append additional arguments if provided
    if options:
        command.extend(options)

    try:
        process = subprocess.Popen(
            command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
        )

        if not quiet:
            for line in process.stdout:
                print(line, end="")

        exit_code = process.wait()
        if exit_code != 0:
            raise subprocess.CalledProcessError(exit_code, command)

    except subprocess.CalledProcessError as e:
        print(f"\nError executing tippecanoe: {e}")
        return None

    return "Tippecanoe process completed successfully."

geojson_to_pmtiles(input_file, output_file=None, layer_name=None, projection='EPSG:4326', overwrite=False, options=None, quiet=False)

Converts vector data to PMTiles using Tippecanoe.

Parameters:

Name	Type	Description	Default
input_file	str	Path to the input vector data file (e.g., .geojson).	required
output_file	str	Path to the output .mbtiles file.	None
layer_name	Optional[str]	Optional name for the layer. Defaults to None.	None
projection	Optional[str]	Projection for the output PMTiles file. Defaults to "EPSG:4326".	'EPSG:4326'
overwrite	bool	If True, overwrite the existing output file. Defaults to False.	False
options	Optional[List[str]]	List of additional arguments for tippecanoe. Defaults to None. To reduce the size of the output file, use '-zg' or '-z max-zoom'.	None
quiet	bool	If True, suppress the log output. Defaults to False.	False

Returns:

Type	Description
Optional[str]	Output from the Tippecanoe command, or None if there was an error or if Tippecanoe is not installed.

Raises:

Type	Description
CalledProcessError	If there's an error executing the tippecanoe command.

Source code in leafmap/common.py

def geojson_to_pmtiles(
    input_file: str,
    output_file: Optional[str] = None,
    layer_name: Optional[str] = None,
    projection: Optional[str] = "EPSG:4326",
    overwrite: bool = False,
    options: Optional[List[str]] = None,
    quiet: bool = False,
) -> Optional[str]:
    """
    Converts vector data to PMTiles using Tippecanoe.

    Args:
        input_file (str): Path to the input vector data file (e.g., .geojson).
        output_file (str): Path to the output .mbtiles file.
        layer_name (Optional[str]): Optional name for the layer. Defaults to None.
        projection (Optional[str]): Projection for the output PMTiles file. Defaults to "EPSG:4326".
        overwrite (bool): If True, overwrite the existing output file. Defaults to False.
        options (Optional[List[str]]): List of additional arguments for tippecanoe. Defaults to None.
            To reduce the size of the output file, use '-zg' or '-z max-zoom'.
        quiet (bool): If True, suppress the log output. Defaults to False.

    Returns:
        Output from the Tippecanoe command, or None if there was an error or if Tippecanoe is not installed.

    Raises:
        subprocess.CalledProcessError: If there's an error executing the tippecanoe command.
    """

    import shutil
    import subprocess

    # Check if tippecanoe exists
    if shutil.which("tippecanoe") is None:
        print("Error: tippecanoe is not installed.")
        print("You can install it using conda with the following command:")
        print("conda install -c conda-forge tippecanoe")
        return None

    if output_file is None:
        output_file = os.path.splitext(input_file)[0] + ".pmtiles"

    if not output_file.endswith(".pmtiles"):
        raise ValueError("Error: output file must be a .pmtiles file.")

    command = ["tippecanoe", "-o", output_file]

    # Add layer name specification if provided
    if layer_name:
        command.extend(["-L", f"{layer_name}:{input_file}"])
    else:
        command.append(input_file)

    command.extend(["--projection", projection])

    if options is None:
        options = []

    if overwrite:
        command.append("--force")

    # Append additional arguments if provided
    if options:
        command.extend(options)

    try:
        process = subprocess.Popen(
            command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
        )

        if not quiet:
            for line in process.stdout:
                print(line, end="")

        exit_code = process.wait()
        if exit_code != 0:
            raise subprocess.CalledProcessError(exit_code, command)

    except subprocess.CalledProcessError as e:
        print(f"\nError executing tippecanoe: {e}")
        return None

    return "Tippecanoe process completed successfully."

geojson_to_shp(in_geojson, out_shp, **kwargs)

Converts a GeoJSON object to GeoPandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
in_geojson	str | dict	The input GeoJSON file or dict.	required
out_shp	str	The output shapefile path.	required

Source code in leafmap/common.py

def geojson_to_shp(in_geojson, out_shp, **kwargs: Any):
    """Converts a GeoJSON object to GeoPandas GeoDataFrame.

    Args:
        in_geojson (str | dict): The input GeoJSON file or dict.
        out_shp (str): The output shapefile path.
    """
    import json

    import geopandas as gpd

    ext = os.path.splitext(out_shp)[1]
    if ext != ".shp":
        out_shp = out_shp + ".shp"
    out_shp = check_file_path(out_shp)

    if isinstance(in_geojson, dict):
        out_file = temp_file_path(extension="geojson")
        with open(out_file, "w") as f:
            json.dump(in_geojson, f)
            in_geojson = out_file

    gdf = gpd.read_file(in_geojson, **kwargs)
    gdf.to_file(out_shp)

geojsonl_to_parquet_batch(input_dir, output_dir, batch_size=50, file_ext='.json', filename_predix='batch_', **kwargs)

Convert JSON Lines files to multiple GeoParquet files, with each GeoParquet file containing data from a specified number of JSON Lines files.

Parameters:

Name	Type	Description	Default
input_dir	str	Directory containing JSON Lines files to convert	required
output_dir	str	Directory for output GeoParquet files	required
batch_size	int	Number of JSON Lines files to combine in each GeoParquet file. Defaults to 50.	50
file_ext	str	File extension of the input files. Defaults to ".json".	'.json'
filename_predix	str	Prefix for the output GeoParquet files. Defaults to "batch_".	'batch_'
**kwargs	Any	Additional keyword arguments to pass to the to_parquet function of GeoDataFrame.	{}

Source code in leafmap/common.py

def geojsonl_to_parquet_batch(
    input_dir,
    output_dir,
    batch_size=50,
    file_ext=".json",
    filename_predix="batch_",
    **kwargs: Any,
):
    """
    Convert JSON Lines files to multiple GeoParquet files, with each GeoParquet file
    containing data from a specified number of JSON Lines files.

    Args:
        input_dir (str): Directory containing JSON Lines files to convert
        output_dir (str): Directory for output GeoParquet files
        batch_size (int, optional): Number of JSON Lines files to combine in each GeoParquet file.
                                    Defaults to 50.
        file_ext (str, optional): File extension of the input files. Defaults to ".json".
        filename_predix (str, optional): Prefix for the output GeoParquet files. Defaults to "batch_".
        **kwargs: Additional keyword arguments to pass to the `to_parquet` function of GeoDataFrame.

    """
    import glob
    import math

    import geopandas as gpd
    from shapely.geometry import shape

    if not os.path.exists(input_dir):
        raise FileNotFoundError(f"Input directory not found: {input_dir}")

    # Get all JSON files
    json_files = glob.glob(os.path.join(input_dir, f"*.{file_ext.lstrip('.')}"))

    if not json_files:
        raise ValueError(f"No JSON files found in {input_dir}")

    # Create output directory if it doesn't exist
    os.makedirs(output_dir, exist_ok=True)

    # Calculate number of output files
    num_files = len(json_files)
    num_batches = math.ceil(num_files / batch_size)

    print(
        f"Processing {num_files} JSON Lines files into {num_batches} GeoParquet files"
    )

    # Track statistics
    processed_files = 0
    processed_records = 0
    failed_files = 0
    successful_parquets = 0

    # Process files in batches
    for batch_num in range(num_batches):
        print(f"\nProcessing batch {batch_num+1}/{num_batches}")

        # Generate output filename
        output_file = os.path.join(
            output_dir, f"{filename_predix}{batch_num+1:04d}.parquet"
        )
        if os.path.exists(output_file):
            print(f"Output file already exists: {output_file}")
            continue

        start_idx = batch_num * batch_size
        end_idx = min(start_idx + batch_size, num_files)
        batch_files = json_files[start_idx:end_idx]

        records = []

        for file_path in batch_files:
            try:
                file_records = 0

                # Process the file line by line (JSON Lines format)
                with open(file_path, "r", encoding="utf-8") as f:
                    for line in f:
                        if line.strip():  # Skip empty lines
                            try:
                                data = json.loads(line)

                                # Create a record with properties and geometry
                                record = {}

                                # Extract all properties except geometry
                                for key, value in data.items():
                                    if key != "geometry":
                                        record[key] = value

                                # Handle geometry
                                if "geometry" in data:
                                    # Convert the geometry to a Shapely object
                                    record["geometry"] = shape(data["geometry"])
                                else:
                                    continue  # Skip records without geometry

                                records.append(record)
                                file_records += 1
                            except json.JSONDecodeError as e:
                                print(
                                    f"Error decoding JSON in file {file_path}: {str(e)}"
                                )
                                continue  # Skip invalid JSON lines
                            except Exception as e:
                                print(
                                    f"Error processing record in file {file_path}: {str(e)}"
                                )
                                continue  # Skip problematic records

                # print(f"Processed {file_records} records from {file_path}")
                processed_records += file_records
                processed_files += 1

            except Exception as e:
                print(f"Error processing file {file_path}: {str(e)}")
                failed_files += 1

        if not records:
            print(f"No valid records found in batch {batch_num+1}")
            continue

        # Create a GeoDataFrame with the correct CRS
        gdf = gpd.GeoDataFrame(records, geometry="geometry", crs="EPSG:4326")

        # Write to GeoParquet
        gdf.to_parquet(output_file, index=False, **kwargs)
        successful_parquets += 1

        # Print summary for this batch
        print(f"Created GeoParquet file {batch_num+1}/{num_batches}: {output_file}")
        print(f"  - Number of features: {len(gdf)}")
        print(f"  - Columns: {list(gdf.columns)}")
        if len(gdf) > 0:
            print(
                f"  - First record attributes: {[k for k in gdf.iloc[0].keys() if k != 'geometry']}"
            )

    # Print final summary
    print(f"\nSummary:")
    print(f"Total files processed: {processed_files} of {num_files}")
    print(f"Failed files: {failed_files}")
    print(f"Total records processed: {processed_records}")
    print(f"GeoParquet files created: {successful_parquets}")

geom_type(in_geojson, encoding='utf-8')

Returns the geometry type of a GeoJSON object.

Parameters:

Name	Type	Description	Default
in_geojson	dict	A GeoJSON object.	required
encoding	str	The encoding of the GeoJSON object. Defaults to "utf-8".	'utf-8'

Returns:

Type	Description
	The geometry type of the GeoJSON object, such as Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon. For more info, see https://shapely.readthedocs.io/en/stable/manual.html

Source code in leafmap/common.py

def geom_type(in_geojson, encoding="utf-8"):
    """Returns the geometry type of a GeoJSON object.

    Args:
        in_geojson (dict): A GeoJSON object.
        encoding (str, optional): The encoding of the GeoJSON object. Defaults to "utf-8".

    Returns:
        The geometry type of the GeoJSON object, such as Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon.
            For more info, see https://shapely.readthedocs.io/en/stable/manual.html
    """
    import json

    try:
        if isinstance(in_geojson, str):
            if in_geojson.startswith("http"):
                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.")

        return data["features"][0]["geometry"]["type"]

    except Exception as e:
        raise Exception(e)

geometry_bounds(geometry, decimals=4)

Returns the bounds of a geometry.

Parameters:

Name	Type	Description	Default
geometry	dict	A GeoJSON geometry.	required
decimals	int	The number of decimal places to round the bounds to. Defaults to 4.	4

Returns:

Type	Description
	A list of bounds in the form of [minx, miny, maxx, maxy].

Source code in leafmap/common.py

def geometry_bounds(geometry, decimals=4):
    """Returns the bounds of a geometry.

    Args:
        geometry (dict): A GeoJSON geometry.
        decimals (int, optional): The number of decimal places to round the bounds to. Defaults to 4.

    Returns:
        A list of bounds in the form of [minx, miny, maxx, maxy].
    """
    if isinstance(geometry, dict):
        if "geometry" in geometry:
            coords = geometry["geometry"]["coordinates"][0]
        else:
            coords = geometry["coordinates"][0]

    else:
        raise ValueError("geometry must be a GeoJSON-like dictionary.")

    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]

get_3dep_dem(geometry, resolution=30, src_crs=None, output=None, dst_crs='EPSG:5070', to_cog=False, overwrite=False, **kwargs)

Get DEM data at any resolution from 3DEP.

Parameters:

Name	Type	Description	Default
geometry	Polygon | MultiPolygon | tuple	It can be a polygon or a bounding box of form (xmin, ymin, xmax, ymax).	required
resolution	int	arget DEM source resolution in meters. Defaults to 30.	30
src_crs	str	The spatial reference system of the input geometry. Defaults to "EPSG:4326".	None
output	str	The output GeoTIFF file. Defaults to None.	None
dst_crs	str	The spatial reference system of the output GeoTIFF file. Defaults to "EPSG:5070".	'EPSG:5070'
to_cog	bool	Convert to Cloud Optimized GeoTIFF. Defaults to False.	False
overwrite	bool	Whether to overwrite the output file if it exists. Defaults to False.	False

Returns:

Type	Description
	DEM at the specified resolution in meters and CRS as an xarray.DataArray.

Source code in leafmap/common.py

def get_3dep_dem(
    geometry,
    resolution=30,
    src_crs=None,
    output=None,
    dst_crs="EPSG:5070",
    to_cog=False,
    overwrite=False,
    **kwargs: Any,
):
    """Get DEM data at any resolution from 3DEP.

    Args:
        geometry (Polygon | MultiPolygon | tuple): It can be a polygon or a bounding
            box of form (xmin, ymin, xmax, ymax).
        resolution (int): arget DEM source resolution in meters. Defaults to 30.
        src_crs (str, optional): The spatial reference system of the input geometry. Defaults to "EPSG:4326".
        output (str, optional): The output GeoTIFF file. Defaults to None.
        dst_crs (str, optional): The spatial reference system of the output GeoTIFF file. Defaults to "EPSG:5070".
        to_cog (bool, optional): Convert to Cloud Optimized GeoTIFF. Defaults to False.
        overwrite (bool, optional): Whether to overwrite the output file if it exists. Defaults to False.

    Returns:
        DEM at the specified resolution in meters and CRS as an xarray.DataArray.
    """

    try:
        import py3dep
    except ImportError:
        print("py3dep is not installed. Installing py3dep...")
        install_package("py3dep")
        import py3dep

    import geopandas as gpd

    if output is not None and os.path.exists(output) and not overwrite:
        print(f"File {output} already exists. Set overwrite=True to overwrite it")
        return

    if isinstance(geometry, gpd.GeoDataFrame):
        if src_crs is None:
            src_crs = geometry.crs
        geometry = geometry.geometry.union_all()

    if src_crs is None:
        src_crs = "EPSG:4326"

    dem = py3dep.get_dem(geometry, resolution=resolution, crs=src_crs)
    dem = dem.rio.reproject(dst_crs)

    if output is not None:
        if not output.endswith(".tif"):
            output += ".tif"
        dem.rio.to_raster(output, **kwargs)

        if to_cog:
            try:
                image_to_cog(output, output)
            except Exception as e:
                print(e)

    return dem

get_api_key(name=None, key=None)

Retrieves an API key. If a key is provided, it is returned directly. If a name is provided, the function attempts to retrieve the key from user data (if running in Google Colab) or from environment variables.

Parameters:

Name	Type	Description	Default
name	Optional[str]	The name of the key to retrieve. Defaults to None.	None
key	Optional[str]	The key to return directly. Defaults to None.	None

Returns:

Type	Description
Optional[str]	The retrieved key, or None if no key was found.

Source code in leafmap/common.py

def get_api_key(name: Optional[str] = None, key: Optional[str] = None) -> Optional[str]:
    """
    Retrieves an API key. If a key is provided, it is returned directly. If a
    name is provided, the function attempts to retrieve the key from user data
    (if running in Google Colab) or from environment variables.

    Args:
        name (Optional[str], optional): The name of the key to retrieve. Defaults to None.
        key (Optional[str], optional): The key to return directly. Defaults to None.

    Returns:
        The retrieved key, or None if no key was found.
    """
    if key is not None:
        return key
    if name is not None:
        try:
            if _in_colab_shell():
                from google.colab import userdata  # pylint: disable=E0611

                return userdata.get(name)
        except Exception:
            pass
        return os.environ.get(name)
    return None

get_basemap(name)

Gets a basemap tile layer by name.

Parameters:

Name	Type	Description	Default
name	str	The name of the basemap.	required

Returns:

Type	Description
	ipylealfet.TileLayer | ipyleaflet.WMSLayer: The basemap layer.

Source code in leafmap/leafmap.py

def get_basemap(name: str):
    """Gets a basemap tile layer by name.

    Args:
        name (str): The name of the basemap.

    Returns:
        ipylealfet.TileLayer | ipyleaflet.WMSLayer: The basemap layer.
    """

    if isinstance(name, str):
        if name in basemaps.keys():
            basemap = basemaps[name]
            if basemap["type"] == "xyz":
                layer = ipyleaflet.TileLayer(
                    url=basemap["url"],
                    name=basemap["name"],
                    max_zoom=24,
                    attribution=basemap["attribution"],
                )
            elif basemap["type"] == "wms":
                layer = ipyleaflet.WMSLayer(
                    url=basemap["url"],
                    layers=basemap["layers"],
                    name=basemap["name"],
                    attribution=basemap["attribution"],
                    format=basemap["format"],
                    transparent=basemap["transparent"],
                )
            else:
                layer = None
            return layer
        else:
            raise ValueError(
                "Basemap must be a string. Please choose from: "
                + str(list(basemaps.keys()))
            )
    else:
        raise ValueError(
            "Basemap must be a string. Please choose from: "
            + str(list(basemaps.keys()))
        )

get_bounds(geometry, north_up=True, transform=None)

Bounding box of a GeoJSON geometry, GeometryCollection, or FeatureCollection. left, bottom, right, top not xmin, ymin, xmax, ymax If not north_up, y will be switched to guarantee the above. Source code adapted from https://github.com/mapbox/rasterio/blob/master/rasterio/features.py#L361

Parameters:

Name	Type	Description	Default
geometry	dict	A GeoJSON dict.	required
north_up	bool	. Defaults to True.	True
transform	[type]	. Defaults to None.	None

Returns:

Type	Description
Tuple[float, float, float, float]	A list of coordinates representing [left, bottom, right, top].

Source code in leafmap/common.py

def get_bounds(
    geometry, north_up=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.
    Source code adapted from https://github.com/mapbox/rasterio/blob/master/rasterio/features.py#L361

    Args:
        geometry (dict): A GeoJSON dict.
        north_up (bool, optional): . Defaults to True.
        transform ([type], optional): . Defaults to None.

    Returns:
        A list of coordinates representing [left, bottom, right, top].
    """

    if "bbox" in geometry:
        return tuple(geometry["bbox"])

    geometry = geometry.get("geometry") or geometry

    # geometry must be a geometry, GeometryCollection, or FeatureCollection
    if not (
        "coordinates" in geometry or "geometries" in geometry or "features" in geometry
    ):
        raise ValueError(
            "geometry must be a GeoJSON-like geometry, GeometryCollection, "
            "or FeatureCollection"
        )

    if "features" in geometry:
        # Input is a FeatureCollection
        xmins = []
        ymins = []
        xmaxs = []
        ymaxs = []
        for feature in geometry["features"]:
            xmin, ymin, xmax, ymax = get_bounds(feature["geometry"])
            xmins.append(xmin)
            ymins.append(ymin)
            xmaxs.append(xmax)
            ymaxs.append(ymax)
        if north_up:
            return min(xmins), min(ymins), max(xmaxs), max(ymaxs)
        else:
            return min(xmins), max(ymaxs), max(xmaxs), min(ymins)

    elif "geometries" in geometry:
        # Input is a geometry collection
        xmins = []
        ymins = []
        xmaxs = []
        ymaxs = []
        for geometry in geometry["geometries"]:
            xmin, ymin, xmax, ymax = get_bounds(geometry)
            xmins.append(xmin)
            ymins.append(ymin)
            xmaxs.append(xmax)
            ymaxs.append(ymax)
        if north_up:
            return min(xmins), min(ymins), max(xmaxs), max(ymaxs)
        else:
            return min(xmins), max(ymaxs), max(xmaxs), min(ymins)

    elif "coordinates" in geometry:
        # Input is a singular geometry object
        if transform is not None:
            xyz = list(explode(geometry["coordinates"]))
            xyz_px = [transform * point for point in xyz]
            xyz = tuple(zip(*xyz_px))
            return min(xyz[0]), max(xyz[1]), max(xyz[0]), min(xyz[1])
        else:
            xyz = tuple(zip(*list(explode(geometry["coordinates"]))))
            if north_up:
                return min(xyz[0]), min(xyz[1]), max(xyz[0]), max(xyz[1])
            else:
                return min(xyz[0]), max(xyz[1]), max(xyz[0]), min(xyz[1])

    # all valid inputs returned above, so whatever falls through is an error
    raise ValueError(
        "geometry must be a GeoJSON-like geometry, GeometryCollection, "
        "or FeatureCollection"
    )

get_census_dict(reset=False)

Returns a dictionary of Census data.

Parameters:

Name	Type	Description	Default
reset	bool	Reset the dictionary. Defaults to False.	False

Returns:

Type	Description
	A dictionary of Census data.

Source code in leafmap/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:
        A dictionary of Census data.
    """
    import importlib.resources
    import json

    pkg_dir = os.path.dirname(importlib.resources.files("leafmap") / "leafmap.py")
    census_data = os.path.join(pkg_dir, "data/census_data.json")

    if reset:
        try:
            from owslib.wms import WebMapService
        except ImportError:
            raise ImportError("Please install owslib using 'pip install owslib'.")

        census_dict = {}

        names = [
            "Current",
            "ACS 2021",
            "ACS 2019",
            "ACS 2018",
            "ACS 2017",
            "ACS 2016",
            "ACS 2015",
            "ACS 2014",
            "ACS 2013",
            "ACS 2012",
            "ECON 2012",
            "Census 2020",
            "Census 2010",
            "Physical Features",
            "Decennial Census 2020",
            "Decennial Census 2010",
            "Decennial Census 2000",
            "Decennial Physical Features",
        ]

        links = {}

        print("Retrieving data. Please wait ...")
        for name in names:
            if "Decennial" not in name:
                links[name] = (
                    f"https://tigerweb.geo.census.gov/arcgis/services/TIGERweb/tigerWMS_{name.replace(' ', '')}/MapServer/WMSServer"
                )
            else:
                links[name] = (
                    f"https://tigerweb.geo.census.gov/arcgis/services/Census2020/tigerWMS_{name.replace('Decennial', '').replace(' ', '')}/MapServer/WMSServer"
                )

            wms = WebMapService(links[name], timeout=300)
            layers = list(wms.contents)
            layers.sort()
            census_dict[name] = {
                "url": links[name],
                "layers": layers,
                # "title": wms.identification.title,
                # "abstract": wms.identification.abstract,
            }

        with open(census_data, "w") as f:
            json.dump(census_dict, f, indent=4)

    else:
        with open(census_data, "r") as f:
            census_dict = json.load(f)

    return census_dict

get_center(geometry, north_up=True, transform=None)

Get the centroid of a GeoJSON.

Parameters:

Name	Type	Description	Default
geometry	dict	A GeoJSON dict.	required
north_up	bool	. Defaults to True.	True
transform	[type]	. Defaults to None.	None

Returns:

Type	Description
Tuple[float, float]	A coordinate pair in the form [lon, lat].

Source code in leafmap/common.py

def get_center(geometry, north_up=True, transform=None) -> Tuple[float, float]:
    """Get the centroid of a GeoJSON.

    Args:
        geometry (dict): A GeoJSON dict.
        north_up (bool, optional): . Defaults to True.
        transform ([type], optional): . Defaults to None.

    Returns:
        A coordinate pair in the form [lon, lat].
    """
    bounds = get_bounds(geometry, north_up, transform)
    center = ((bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2)  # (lat, lon)
    return center

get_cog_link_from_stac_item(item_url)

Retrieve the URL of the GeoTIFF asset from a STAC Item.

Parameters:

Name	Type	Description	Default
item_url	str	The URL to a STAC Item JSON.	required

Returns:

Type	Description
str	URL of the first .tif asset, or None if not found.

Source code in leafmap/stac.py

def get_cog_link_from_stac_item(item_url: str) -> str:
    """
    Retrieve the URL of the GeoTIFF asset from a STAC Item.

    Args:
        item_url (str): The URL to a STAC Item JSON.

    Returns:
        URL of the first .tif asset, or None if not found.
    """
    try:
        response = requests.get(item_url)
        response.raise_for_status()
        item = response.json()

        # Look for any asset ending in .tif
        for asset_key, asset in item.get("assets", {}).items():
            href = asset.get("href", "")
            if href.endswith(".tif") or ".tif?" in href:
                return href

        print("No .tif asset found in item.")
        return None
    except Exception as e:
        print(f"Failed to retrieve STAC item: {e}")
        return None

get_direct_url(url)

Get the direct URL for a given URL.

Parameters:

Name	Type	Description	Default
url	str	The URL to get the direct URL for.	required

Returns:

Type	Description
	The direct URL.

Source code in leafmap/common.py

def get_direct_url(url):
    """Get the direct URL for a given URL.

    Args:
        url (str): The URL to get the direct URL for.

    Returns:
        The direct URL.
    """

    if not isinstance(url, str):
        raise ValueError("url must be a string.")

    if not url.startswith("http"):
        raise ValueError("url must start with http.")

    r = requests.head(url, allow_redirects=True)
    return r.url

get_ee_tile_url(asset_id, vis_params=None, endpoint=None)

Get the tile URL for an Earth Engine asset.

Parameters:

Name	Type	Description	Default
asset_id	str	The Earth Engine asset ID.	required
vis_params	Optional[Union[str, dict]]	The visualization parameters.	None
endpoint	Optional[str]	The endpoint to use for the tile request. Set to "default" to use the default endpoint.	None

Returns:

Type	Description
str	The tile URL.

Raises:

Type	Description
ValueError	If the asset ID is not a valid Earth Engine asset ID.
ValueError	If the visualization parameters are not a valid JSON string.
ValueError	If the endpoint is not a valid URL.
ValueError	If the data type is not supported.

Source code in leafmap/common.py

def get_ee_tile_url(
    asset_id: str,
    vis_params: Optional[Union[str, dict]] = None,
    endpoint: Optional[str] = None,
) -> str:
    """
    Get the tile URL for an Earth Engine asset.

    Args:
        asset_id: The Earth Engine asset ID.
        vis_params: The visualization parameters.
        endpoint: The endpoint to use for the tile request. Set to "default" to use the default endpoint.

    Returns:
        The tile URL.

    Raises:
        ValueError: If the asset ID is not a valid Earth Engine asset ID.
        ValueError: If the visualization parameters are not a valid JSON string.
        ValueError: If the endpoint is not a valid URL.
        ValueError: If the data type is not supported.
    """

    if isinstance(endpoint, str):

        if endpoint == "default":
            endpoint = "https://giswqs-ee-tile-request.hf.space/tile"

        payload = {"asset_id": asset_id, "vis_params": vis_params or {}}

        response = requests.post(endpoint, json=payload)
        response.raise_for_status()
        return response.json()["tile_url"]

    try:

        import ee
        from geemap.ee_tile_layers import _get_tile_url_format, _validate_palette

        if isinstance(asset_id, str):
            if asset_id.startswith("ee."):
                ee_object = eval(asset_id)
            else:
                data_dict = ee.data.getAsset(asset_id)
                data_type = data_dict["type"]
                if data_type == "IMAGE":
                    ee_object = ee.Image(asset_id)
                elif data_type == "IMAGE_COLLECTION":
                    ee_object = ee.ImageCollection(asset_id)
                elif data_type in ["TABLE", "TABLE_COLLECTION"]:
                    ee_object = ee.FeatureCollection(asset_id)
                else:
                    raise ValueError(f"Unsupported data type: {data_type}")
        else:
            ee_object = asset_id

        if vis_params is None:
            vis_params = {}
        if isinstance(vis_params, str):
            if len(vis_params) == 0:
                vis_params = "{}"
            if vis_params.startswith("{") and vis_params.endswith("}"):
                vis_params = json.loads(vis_params)
            else:
                raise ValueError(f"Unsupported vis_params type: {type(vis_params)}")
        elif isinstance(vis_params, dict):
            pass
        else:
            raise ValueError(f"Unsupported vis_params type: {type(vis_params)}")

        if "palette" in vis_params:
            vis_params["palette"] = _validate_palette(vis_params["palette"])

        url = _get_tile_url_format(ee_object, vis_params)
        return url
    except Exception as e:
        return f"Error: {str(e)}"

get_env_var(key)

Retrieves an environment variable or Colab secret for the given key.

Colab secrets have precedence over environment variables.

Parameters:

Name	Type	Description	Default
key	str	The key that's used to fetch the environment variable.	required

Returns:

Type	Description
Optional[str]	The retrieved key, or None if no environment variable was found.

Source code in leafmap/common.py

def get_env_var(key: str) -> Optional[str]:
    """Retrieves an environment variable or Colab secret for the given key.

    Colab secrets have precedence over environment variables.

    Args:
        key (str): The key that's used to fetch the environment variable.

    Returns:
        The retrieved key, or None if no environment variable was found.
    """
    if not key:
        return None

    if "google.colab" in sys.modules:
        from google.colab import userdata

        try:
            return userdata.get(key)
        except (userdata.SecretNotFoundError, userdata.NotebookAccessError):
            pass

    return os.environ.get(key)

get_gdal_drivers()

Get a list of available driver names in the GDAL library.

Returns:

Type	Description
List[str]	A list of available driver names.

Source code in leafmap/common.py

def get_gdal_drivers() -> List[str]:
    """Get a list of available driver names in the GDAL library.

    Returns:
        A list of available driver names.
    """
    from osgeo import ogr

    driver_list = []

    # Iterate over all registered drivers
    for i in range(ogr.GetDriverCount()):
        driver = ogr.GetDriver(i)
        driver_name = driver.GetName()
        driver_list.append(driver_name)

    return driver_list

get_gdal_file_extension(driver_name)

Get the file extension corresponding to a driver name in the GDAL library.

Parameters:

Name	Type	Description	Default
driver_name	str	The name of the driver.	required

Returns:

Type	Description
Optional[str]	The file extension corresponding to the driver name, or None if the driver is not found or does not have a specific file extension.

Source code in leafmap/common.py

def get_gdal_file_extension(driver_name: str) -> Optional[str]:
    """Get the file extension corresponding to a driver name in the GDAL library.

    Args:
        driver_name (str): The name of the driver.

    Returns:
        The file extension corresponding to the driver name, or None if the driver is not found or does not have a specific file extension.
    """
    from osgeo import ogr

    driver = ogr.GetDriverByName(driver_name)
    if driver is None:
        drivers = get_gdal_drivers()
        raise ValueError(
            f"Driver {driver_name} not found. Available drivers: {drivers}"
        )

    metadata = driver.GetMetadata()
    if "DMD_EXTENSION" in metadata:
        file_extension = driver.GetMetadataItem("DMD_EXTENSION")
    else:
        file_extensions = driver.GetMetadataItem("DMD_EXTENSIONS")
        if file_extensions == "json geojson":
            file_extension = "geojson"
        else:
            file_extension = file_extensions.split()[0].lower()

    return file_extension

get_geometry_coords(row, geom, coord_type, shape_type, mercator=False)

Returns the coordinates ('x' or 'y') of edges of a Polygon exterior.

:param: (GeoPandas Series) row : The row of each of the GeoPandas DataFrame. :param: (str) geom : The column name. :param: (str) coord_type : Whether it's 'x' or 'y' coordinate. :param: (str) shape_type

Source code in leafmap/common.py

def get_geometry_coords(row, geom, coord_type, shape_type, mercator=False):
    """
    Returns the coordinates ('x' or 'y') of edges of a Polygon exterior.

    :param: (GeoPandas Series) row : The row of each of the GeoPandas DataFrame.
    :param: (str) geom : The column name.
    :param: (str) coord_type : Whether it's 'x' or 'y' coordinate.
    :param: (str) shape_type
    """

    # Parse the exterior of the coordinate
    if shape_type.lower() in ["polygon", "multipolygon"]:
        exterior = row[geom].geoms[0].exterior
        if coord_type == "x":
            # Get the x coordinates of the exterior
            coords = list(exterior.coords.xy[0])
            if mercator:
                coords = [lnglat_to_meters(x, 0)[0] for x in coords]
            return coords

        elif coord_type == "y":
            # Get the y coordinates of the exterior
            coords = list(exterior.coords.xy[1])
            if mercator:
                coords = [lnglat_to_meters(0, y)[1] for y in coords]
            return coords

    elif shape_type.lower() in ["linestring", "multilinestring"]:
        if coord_type == "x":
            coords = list(row[geom].coords.xy[0])
            if mercator:
                coords = [lnglat_to_meters(x, 0)[0] for x in coords]
            return coords
        elif coord_type == "y":
            coords = list(row[geom].coords.xy[1])
            if mercator:
                coords = [lnglat_to_meters(0, y)[1] for y in coords]
            return coords

    elif shape_type.lower() in ["point", "multipoint"]:
        exterior = row[geom]

        if coord_type == "x":
            # Get the x coordinates of the exterior
            coords = exterior.coords.xy[0][0]
            if mercator:
                coords = lnglat_to_meters(coords, 0)[0]
            return coords

        elif coord_type == "y":
            # Get the y coordinates of the exterior
            coords = exterior.coords.xy[1][0]
            if mercator:
                coords = lnglat_to_meters(0, coords)[1]
            return coords

get_geometry_type(in_geojson)

Get the geometry type of a GeoJSON file.

Parameters:

Name	Type	Description	Default
in_geojson	str | dict	The path to the GeoJSON file or a GeoJSON dictionary.	required

Returns:

Type	Description
str	The geometry type. Can be one of "Point", "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon", "GeometryCollection", or "Unknown".

Source code in leafmap/common.py

def get_geometry_type(in_geojson: Union[str, Dict]) -> str:
    """Get the geometry type of a GeoJSON file.

    Args:
        in_geojson (str | dict): The path to the GeoJSON file or a GeoJSON dictionary.

    Returns:
        The geometry type. Can be one of "Point", "LineString", "Polygon", "MultiPoint",
            "MultiLineString", "MultiPolygon", "GeometryCollection", or "Unknown".
    """

    import geojson

    try:
        if isinstance(in_geojson, str):  # If input is a file path
            with open(in_geojson, "r") as geojson_file:
                geojson_data = geojson.load(geojson_file)
        elif isinstance(in_geojson, dict):  # If input is a GeoJSON dictionary
            geojson_data = in_geojson
        else:
            return "Invalid input type. Expected file path or dictionary."

        if "type" in geojson_data:
            if geojson_data["type"] == "FeatureCollection":
                features = geojson_data.get("features", [])
                if features:
                    first_feature = features[0]
                    geometry = first_feature.get("geometry")
                    if geometry and "type" in geometry:
                        return geometry["type"]
                    else:
                        return "No geometry type found in the first feature."
                else:
                    return "No features found in the FeatureCollection."
            elif geojson_data["type"] == "Feature":
                geometry = geojson_data.get("geometry")
                if geometry and "type" in geometry:
                    return geometry["type"]
                else:
                    return "No geometry type found in the Feature."
            else:
                return "Unsupported GeoJSON type."
        else:
            return "No 'type' field found in the GeoJSON data."
    except Exception as e:
        raise e

get_google_map(map_type='HYBRID', show=True, api_key=None, backend='ipyleaflet', **kwargs)

Gets Google basemap tile layer.

Parameters:

Name	Type	Description	Default
map_type	str	Can be one of "ROADMAP", "SATELLITE", "HYBRID" or "TERRAIN". Defaults to 'HYBRID'.	'HYBRID'
show	bool	Whether to add the layer to the map. Defaults to True.	True
api_key	str	The Google Maps API key. Defaults to None.	None
**kwargs	Any	Additional arguments to pass to ipyleaflet.TileLayer().	{}

Source code in leafmap/common.py

def get_google_map(
    map_type="HYBRID", show=True, api_key=None, backend="ipyleaflet", **kwargs
):
    """Gets Google basemap tile layer.

    Args:
        map_type (str, optional): Can be one of "ROADMAP", "SATELLITE", "HYBRID" or "TERRAIN". Defaults to 'HYBRID'.
        show (bool, optional): Whether to add the layer to the map. Defaults to True.
        api_key (str, optional): The Google Maps API key. Defaults to None.
        **kwargs (Any): Additional arguments to pass to ipyleaflet.TileLayer().
    """

    allow_types = ["ROADMAP", "SATELLITE", "HYBRID", "TERRAIN"]
    if map_type not in allow_types:
        print("map_type must be one of the following: {}".format(allow_types))
        return

    if api_key is None:
        api_key = os.environ.get("GOOGLE_MAPS_API_KEY", None)

    if api_key is None:
        MAP_TILES = {
            "ROADMAP": {
                "url": "https://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer/tile/{z}/{y}/{x}",
                "attribution": "Esri",
                "name": "Esri.WorldStreetMap",
            },
            "SATELLITE": {
                "url": "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
                "attribution": "Esri",
                "name": "Esri.WorldImagery",
            },
            "TERRAIN": {
                "url": "https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}",
                "attribution": "Esri",
                "name": "Esri.WorldTopoMap",
            },
            "HYBRID": {
                "url": "https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
                "attribution": "Esri",
                "name": "Esri.WorldImagery",
            },
        }

    else:
        MAP_TILES = {
            "ROADMAP": GoogleMapsTileProvider(map_type="roadmap"),
            "SATELLITE": GoogleMapsTileProvider(map_type="satellite"),
            "TERRAIN": GoogleMapsTileProvider(map_type="terrain"),
            "HYBRID": GoogleMapsTileProvider(map_type="hybrid"),
        }

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

    url = MAP_TILES[map_type]["url"]

    if backend == "ipyleaflet":
        import ipyleaflet

        layer = ipyleaflet.TileLayer(
            url=url,
            name=MAP_TILES[map_type]["name"],
            attribution=MAP_TILES[map_type]["attribution"],
            visible=show,
            **kwargs,
        )
    elif backend == "folium":
        import folium

        layer = folium.TileLayer(
            tiles=url,
            name=MAP_TILES[map_type]["name"],
            attr=MAP_TILES[map_type]["attribution"],
            overlay=True,
            control=True,
            show=show,
            **kwargs,
        )
    else:
        raise ValueError("backend must be either 'ipyleaflet' or 'folium'")

    return layer

get_google_map_tile_providers(language='en-Us', region='US', api_key=None, **kwargs)

Generates a dictionary of Google Map tile providers for different map types.

Parameters:

Name	Type	Description	Default
language	str	An IETF language tag that specifies the language used to display information on the tiles, such as 'zh-Cn'. Defaults to 'en-Us'.	'en-Us'
region	str	A Common Locale Data Repository region identifier (two uppercase letters) that represents the physical location of the user. Defaults to 'US'.	'US'
api_key	str	The API key to use for the Google Maps API. If not provided, it will try to get it from the environment or Colab user data with the key 'GOOGLE_MAPS_API_KEY'. Defaults to None.	None
**kwargs	Any	Additional parameters to pass to the map generation. For more info, visit https://bit.ly/3UhbZKU	{}

Returns:

Type	Description
Dict[str, Any]	A dictionary where the keys are the map types and the values are tile providers.
Dict[str, Any]	('roadmap', 'satellite', 'terrain', 'hybrid')
Dict[str, Any]	and the values are the corresponding GoogleMapsTileProvider objects.

Source code in leafmap/common.py

def get_google_map_tile_providers(
    language: str = "en-Us",
    region: str = "US",
    api_key: Optional[str] = None,
    **kwargs: Any,
) -> Dict[str, Any]:
    """
    Generates a dictionary of Google Map tile providers for different map types.

    Args:
        language (str, optional): An IETF language tag that specifies the
            language used to display information on the tiles, such as 'zh-Cn'.
            Defaults to 'en-Us'.
        region (str, optional): A Common Locale Data Repository region
            identifier (two uppercase letters) that represents the physical
            location of the user. Defaults to 'US'.
        api_key (str, optional): The API key to use for the Google Maps API.
            If not provided, it will try to get it from the environment or
            Colab user data with the key 'GOOGLE_MAPS_API_KEY'. Defaults to None.
        **kwargs: Additional parameters to pass to the map generation. For more
            info, visit https://bit.ly/3UhbZKU

    Returns:
        A dictionary where the keys are the map types and the values are tile providers.
        ('roadmap', 'satellite', 'terrain', 'hybrid')
        and the values are the corresponding GoogleMapsTileProvider objects.
    """
    gmap_providers = {}

    for m_type in GoogleMapsTileProvider.MAP_TYPE_CONFIG:
        gmap_providers[m_type] = GoogleMapsTileProvider(
            map_type=m_type, language=language, region=region, api_key=api_key, **kwargs
        )

    return gmap_providers

get_google_maps_api_key(key='GOOGLE_MAPS_API_KEY')

Retrieves the Google Maps API key from the environment or Colab user data.

Parameters:

Name	Type	Description	Default
key	str	The name of the environment variable or Colab user data key where the API key is stored. Defaults to 'GOOGLE_MAPS_API_KEY'.	'GOOGLE_MAPS_API_KEY'

Returns:

Type	Description
Optional[str]	The API key, or None if it could not be found.

Source code in leafmap/common.py

def get_google_maps_api_key(key: str = "GOOGLE_MAPS_API_KEY") -> Optional[str]:
    """
    Retrieves the Google Maps API key from the environment or Colab user data.

    Args:
        key (str, optional): The name of the environment variable or Colab user
            data key where the API key is stored. Defaults to
            'GOOGLE_MAPS_API_KEY'.

    Returns:
        The API key, or None if it could not be found.
    """
    if api_key := get_env_var(key):
        return api_key
    return os.environ.get(key, None)

get_image_colormap(image, index=1)

Retrieve the colormap from an image.

Parameters:

Name	Type	Description	Default
image	(str, DatasetReader, DataArray)	The input image. It can be: - A file path to a raster image (string). - A rasterio dataset. - A rioxarray DataArray.	required
index	int	The band index to retrieve the colormap from (default is 1).	1

Returns:

Type	Description
	A dictionary representing the colormap (value: (R, G, B, A)), or None if no colormap is found.

Raises:

Type	Description
ValueError	If the input image type is unsupported.

Source code in leafmap/common.py

def get_image_colormap(image, index=1):
    """
    Retrieve the colormap from an image.

    Args:
        image (str, rasterio.io.DatasetReader, rioxarray.DataArray):
            The input image. It can be:
            - A file path to a raster image (string).
            - A rasterio dataset.
            - A rioxarray DataArray.
        index (int): The band index to retrieve the colormap from (default is 1).

    Returns:
        A dictionary representing the colormap (value: (R, G, B, A)), or None if no colormap is found.

    Raises:
        ValueError: If the input image type is unsupported.
    """
    import rasterio
    import rioxarray
    import xarray as xr

    def remove_black_fills(d: dict) -> dict:
        """Remove keys with value (0, 0, 0, 255)."""
        return {str(k): v for k, v in d.items() if v != (0, 0, 0, 255)}

    dataset = None

    if isinstance(image, str):  # File path
        with rasterio.open(image) as ds:
            try:
                return remove_black_fills(ds.colormap(index)) if ds.count > 0 else None
            except:
                return None
    elif isinstance(image, rasterio.io.DatasetReader):  # rasterio dataset
        dataset = image
    elif isinstance(image, xr.DataArray) or isinstance(image, xr.Dataset):
        source = image.encoding.get("source")
        if source:
            with rasterio.open(source) as ds:
                return remove_black_fills(ds.colormap(index)) if ds.count > 0 else None
        else:
            raise ValueError(
                "Cannot extract colormap: DataArray does not have a source."
            )
    else:
        raise ValueError(
            "Unsupported input type. Provide a file path, rasterio dataset, or rioxarray DataArray."
        )

    if dataset:
        return (
            remove_black_fills(dataset.colormap(index)) if dataset.count > 0 else None
        )

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', client_args={'cors_all': False}, 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'
client_args	dict	Additional arguments to pass to the TileClient. Defaults to {}.	{'cors_all': False}
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
	An ipyleaflet.TileLayer or folium.TileLayer.

Source code in leafmap/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",
    client_args={"cors_all": False},
    return_client=False,
    quiet=False,
    **kwargs: Any,
):
    """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.
        client_args (dict, optional): Additional arguments to pass to the TileClient. Defaults to {}.
        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:
        An ipyleaflet.TileLayer or folium.TileLayer.
    """
    import rasterio

    check_package(
        "localtileserver", URL="https://github.com/banesullivan/localtileserver"
    )

    # Handle legacy localtileserver kwargs
    if "cmap" in kwargs:
        warnings.warn(
            "`cmap` is a deprecated keyword argument for get_local_tile_layer. Please use `colormap`."
        )
    if "palette" in kwargs:
        warnings.warn(
            "`palette` is a deprecated keyword argument for get_local_tile_layer. Please use `colormap`."
        )
    if "band" in kwargs or "bands" in kwargs:
        warnings.warn(
            "`band` and `bands` are deprecated keyword arguments for get_local_tile_layer. Please use `indexes`."
        )
    if "projection" in kwargs:
        warnings.warn(
            "`projection` is a deprecated keyword argument for get_local_tile_layer and will be ignored."
        )
    if "style" in kwargs:
        warnings.warn(
            "`style` is a deprecated keyword argument for get_local_tile_layer and will be ignored."
        )

    if "max_zoom" not in kwargs:
        kwargs["max_zoom"] = 30
    if "max_native_zoom" not in kwargs:
        kwargs["max_native_zoom"] = 30
    if "cmap" in kwargs:
        colormap = kwargs.pop("cmap")
    if "palette" in kwargs:
        colormap = kwargs.pop("palette")
    if "band" in kwargs:
        indexes = kwargs.pop("band")
    if "bands" in kwargs:
        indexes = kwargs.pop("bands")

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

    # Make it compatible with binder and JupyterHub
    if os.environ.get("JUPYTERHUB_SERVICE_PREFIX") is not None:
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = (
            f"{os.environ['JUPYTERHUB_SERVICE_PREFIX'].lstrip('/')}/proxy/{{port}}"
        )

    if is_studio_lab():
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = (
            f"studiolab/default/jupyter/proxy/{{port}}"
        )
    elif is_on_aws():
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = "proxy/{port}"
    elif "prefix" in kwargs:
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = kwargs["prefix"]
        kwargs.pop("prefix")

    from localtileserver import (
        TileClient,
        get_folium_tile_layer,
        get_leaflet_tile_layer,
    )

    # if "show_loading" not in kwargs:
    #     kwargs["show_loading"] = False

    if isinstance(source, str):
        if not source.startswith("http"):
            if source.startswith("~"):
                source = os.path.expanduser(source)
            # else:
            #     source = os.path.abspath(source)
            # if not os.path.exists(source):
            #     raise ValueError("The source path does not exist.")
        else:
            source = github_raw_url(source)
    elif isinstance(source, TileClient) or isinstance(
        source, rasterio.io.DatasetReader
    ):
        pass

    else:
        raise ValueError("The source must either be a string or TileClient")

    if tile_format not in ["ipyleaflet", "folium"]:
        raise ValueError("The tile format must be either ipyleaflet or folium.")

    if layer_name is None:
        if source.startswith("http"):
            layer_name = "RemoteTile_" + random_string(3)
        else:
            layer_name = "LocalTile_" + random_string(3)

    if nodata is None:
        nodata = get_api_key("NODATA")
        if isinstance(nodata, str):
            nodata = float(nodata)

    if isinstance(colormap, str):
        colormap = colormap.lower()

    if quiet:
        output = widgets.Output()
        with output:
            if tile_format == "ipyleaflet":
                tile_layer = get_leaflet_tile_layer(
                    source,
                    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(
                    source,
                    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(
                source,
                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(
                source,
                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_layer.tile_server
    else:
        return tile_layer

get_local_tile_url(source, port='default', indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, client_args={'cors_all': False}, return_client=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'
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
client_args	dict	Additional arguments to pass to the TileClient. Defaults to {}.	{'cors_all': False}
return_client	bool	If True, the tile client will be returned. Defaults to False.	False

Returns:

Type	Description
	An ipyleaflet.TileLayer or folium.TileLayer.

Source code in leafmap/common.py

def get_local_tile_url(
    source,
    port="default",
    indexes=None,
    colormap=None,
    vmin=None,
    vmax=None,
    nodata=None,
    client_args={"cors_all": False},
    return_client=False,
    **kwargs: Any,
):
    """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".
        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.
        client_args (dict, optional): Additional arguments to pass to the TileClient. Defaults to {}.
        return_client (bool, optional): If True, the tile client will be returned. Defaults to False.

    Returns:
        An ipyleaflet.TileLayer or folium.TileLayer.
    """
    import rasterio

    check_package(
        "localtileserver", URL="https://github.com/banesullivan/localtileserver"
    )

    # Handle legacy localtileserver kwargs
    if "cmap" in kwargs:
        warnings.warn(
            "`cmap` is a deprecated keyword argument for get_local_tile_layer. Please use `colormap`."
        )
    if "palette" in kwargs:
        warnings.warn(
            "`palette` is a deprecated keyword argument for get_local_tile_layer. Please use `colormap`."
        )
    if "band" in kwargs or "bands" in kwargs:
        warnings.warn(
            "`band` and `bands` are deprecated keyword arguments for get_local_tile_layer. Please use `indexes`."
        )
    if "projection" in kwargs:
        warnings.warn(
            "`projection` is a deprecated keyword argument for get_local_tile_layer and will be ignored."
        )
    if "style" in kwargs:
        warnings.warn(
            "`style` is a deprecated keyword argument for get_local_tile_layer and will be ignored."
        )

    if "max_zoom" not in kwargs:
        kwargs["max_zoom"] = 30
    if "max_native_zoom" not in kwargs:
        kwargs["max_native_zoom"] = 30
    if "cmap" in kwargs:
        colormap = kwargs.pop("cmap")
    if "palette" in kwargs:
        colormap = kwargs.pop("palette")
    if "band" in kwargs:
        indexes = kwargs.pop("band")
    if "bands" in kwargs:
        indexes = kwargs.pop("bands")

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

    # Make it compatible with binder and JupyterHub
    if os.environ.get("JUPYTERHUB_SERVICE_PREFIX") is not None:
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = (
            f"{os.environ['JUPYTERHUB_SERVICE_PREFIX'].lstrip('/')}/proxy/{{port}}"
        )

    if is_studio_lab():
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = (
            f"studiolab/default/jupyter/proxy/{{port}}"
        )
    elif is_on_aws():
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = "proxy/{port}"
    elif "prefix" in kwargs:
        os.environ["LOCALTILESERVER_CLIENT_PREFIX"] = kwargs["prefix"]
        kwargs.pop("prefix")

    from localtileserver import TileClient

    # if "show_loading" not in kwargs:
    #     kwargs["show_loading"] = False

    if isinstance(source, str):
        if not source.startswith("http"):
            if source.startswith("~"):
                source = os.path.expanduser(source)

        else:
            source = github_raw_url(source)
    elif isinstance(source, TileClient) or isinstance(
        source, rasterio.io.DatasetReader
    ):
        pass

    else:
        raise ValueError("The source must either be a string or TileClient")

    if nodata is None:
        nodata = get_api_key("NODATA")
        if isinstance(nodata, str):
            nodata = float(nodata)

    if isinstance(colormap, str):
        colormap = colormap.lower()

    client = TileClient(source, port=port, **client_args)
    url = client.get_tile_url(
        indexes=indexes,
        colormap=colormap,
        vmin=vmin,
        vmax=vmax,
        nodata=nodata,
    )

    if return_client:
        return url, client
    else:
        return url

get_mapillary_image_url(image_id, resolution='original', access_token=None, **kwargs)

Retrieves the URL of a Mapillary image.

Parameters:

Name	Type	Description	Default
image_id	str	The ID of the Mapillary image.	required
resolution	str	The resolution of the image. Can be 256, 1024, 2048, or original. Defaults to "original".	'original'
access_token	str	The access token for the Mapillary API. Defaults to None.	None
**kwargs	Any	Additional keyword arguments for the request.	{}

Raises:

Type	Description
ValueError	If no access token is provided.

Returns:

Type	Description
Optional[str]	The URL of the Mapillary image, or None if an error occurs.

Source code in leafmap/common.py

18310 18311 18312 18313 18314 18315 18316 18317 18318 18319 18320 18321 18322 18323 18324 18325 18326 18327 18328 18329