ee_tile_layers module

Tile layers that show EE objects.

EEFoliumTileLayer

Bases: TileLayer

A Folium raster TileLayer that shows an EE object.

Source code in geemap/ee_tile_layers.py

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

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

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

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

Initialize the folium tile layer.

Parameters:

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

Source code in geemap/ee_tile_layers.py

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

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

EELeafletTileLayer

Bases: TileLayer

An ipyleaflet TileLayer that shows an EE object.

Source code in geemap/ee_tile_layers.py

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

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

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

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

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

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

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

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

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

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

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

        return (min_val, max_val, std_dev, mean)

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

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

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

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

        return (stretch_min, stretch_max)

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

Initialize the ipyleaflet tile layer.

Parameters:

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

Source code in geemap/ee_tile_layers.py

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

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

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

Calculate the min and max clip values for visualization.

Parameters:

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

Returns:

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

Source code in geemap/ee_tile_layers.py

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

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

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

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

    return (stretch_min, stretch_max)