geemap/GEMINI.md possible file

GEMINI.md

Preamble

Copyright 2025 Google LLC.
SPDX-License-Identifier: Apache-2.0

How geemap works

This document provides a high-level overview of the geemap library's architecture and functionality.

Core Concepts

geemap is a Python library for interactive mapping with Google Earth Engine (GEE). It is built on top of popular mapping libraries like ipyleaflet, folium, and plotly, and provides a high-level API for visualizing and analyzing GEE data in a Jupyter environment. The geemap API is inspired by the Earth Engine Code Editor API.

The core of the library is the Map class, which is implemented in several different files mentioned in the "Map Backends" section. Users can choose the map backends that suits their needs.

Core vs. Other Modules

The library's design separates "core" functionalities from other features. The geemap.py, foliumap.py, and plotlymap.py files contain the core Map class implementations for each backend. When adding new features or modifying existing ones, it's crucial to consider whether they belong in these core files or in separate modules.

New features should generally be implemented outside the core Map class files unless they are fundamental to the mapping functionality across all backends. This approach helps maintain a lean and stable core, ensuring backward compatibility and future-proofing. Changes to the core files require careful consideration of their impact on existing user workflows and the overall architecture.

Key Functionalities

1. Google Earth Engine Integration

geemap is tightly integrated with the GEE Python API. The Map class in each backend provides an add_ee_layer (or addLayer) method that allows users to add GEE objects (e.g., ee.Image, ee.ImageCollection, ee.FeatureCollection) directly to the map. The library handles the conversion of GEE objects to tile layers that can be displayed on the map.

2. Map Backends

As mentioned above, geemap supports three different mapping backends:

• ipyleaflet (geemap.py): This is the default backend and provides the most feature-rich interactive experience. It leverages ipywidgets to create a variety of UI controls and widgets.
• folium (foliumap.py): This backend is useful for creating standalone HTML maps that can be embedded in web pages. It provides a similar API to the ipyleaflet backend but with some limitations due to the static nature of folium maps.
• plotly (plotlymap.py): This backend allows users to create maps using Plotly's powerful visualization capabilities. It is well-suited for creating publication-quality maps and integrating them with other Plotly charts.

3. UI Components and Widgets

geemap provides a rich set of UI components and widgets for interacting with the map. These are primarily implemented in toolbar.py and map_widgets.py using ipywidgets and anywidget.

Key UI components include:

• Toolbar: A customizable toolbar with a variety of tools for interacting with the map.
• Layer Manager: A widget for managing map layers, including visibility, opacity, and deletion.
• Inspector: A tool for inspecting pixel values and object information of GEE data.
• Search Bar: A tool for searching for locations and datasets.
• Draw Control: A tool for drawing shapes on the map.
• Plotting Tools: Tools for creating interactive plots of GEE data.

4. Data Support

geemap supports a wide variety of data formats, including:

• Google Earth Engine objects: ee.Image, ee.ImageCollection, ee.FeatureCollection, etc.
• Vector data: Shapefiles, GeoJSON, KML, and PostGIS.
• Raster data: Cloud Optimized GeoTIFFs (COGs) and SpatioTemporal Asset Catalogs (STAC).
• Local files: The library can open and display local vector and raster datasets.

5. Time Series Analysis

geemap includes tools for visualizing and analyzing time-series data, such as:

• Time Slider: A widget for visualizing time-series imagery.
• Timelapse GIF Creator: A tool for creating animated GIFs from Landsat imagery.
• Time Series Inspector: A tool for inspecting time-series data at a specific point.

Code Structure

• core.py: Contains core functionalities and base classes used across different backends.
• geemap.py: Implements the core Map class using the ipyleaflet backend.
• foliumap.py: Implements the Map class using the folium backend.
• plotlymap.py: Implements the Map class using the plotly backend.
• toolbar.py: Defines the toolbars and GUI elements for the ipyleaflet backend.
• map_widgets.py: Defines the custom ipywidgets used in the toolbars.
• common.py: Contains common utility functions used throughout the library.
• conversion.py: Provides functions for converting between different data formats (e.g., JavaScript to Python, GeoJSON to Earth Engine).
• ee_tile_layers.py: Handles the conversion of GEE objects to tile layers.
• legends.py: Provides functions for creating map legends.
• osm.py: Contains functions for working with OpenStreetMap data.

Coding Style

• Code formatting is enforced in GitHub using black: https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html
• Formatting uses https://github.com/n8henrie/jupyter-black
• Indentation is 4 spaces.
• The code must work with Python 3.10-3.14.

Tests

• Prefer mock.patch.object over mock.patch.
• Tests must work in GitHub actions and on users' local machines.