voxcity.downloader.gee ====================== .. py:module:: voxcity.downloader.gee .. autoapi-nested-parse:: Module for interacting with Google Earth Engine API and downloading geospatial data. This module provides functionality to initialize Earth Engine, create regions of interest, download various types of satellite imagery and terrain data, and save them as GeoTIFF files. It supports multiple data sources including DEMs, land cover maps, and building footprints. The module offers the following main functionalities: 1. Earth Engine initialization and region of interest (ROI) management 2. Digital Elevation Model (DEM) data access from multiple sources 3. Land cover data retrieval from ESA WorldCover, Dynamic World, and ESRI 4. Building footprint and height data extraction 5. GeoTIFF export with customizable parameters Dependencies: - ee: Google Earth Engine Python API - geemap: Python package for interactive mapping with Earth Engine Note: Most functions require Earth Engine authentication to be set up beforehand. Functions --------- .. autoapisummary:: voxcity.downloader.gee.initialize_earth_engine voxcity.downloader.gee.get_roi voxcity.downloader.gee.get_center_point voxcity.downloader.gee.get_ee_image_collection voxcity.downloader.gee.get_ee_image voxcity.downloader.gee.save_geotiff voxcity.downloader.gee.get_dem_image voxcity.downloader.gee.save_geotiff_esa_land_cover voxcity.downloader.gee.save_geotiff_dynamic_world_v1 voxcity.downloader.gee.save_geotiff_esri_landcover voxcity.downloader.gee.save_geotiff_open_buildings_temporal voxcity.downloader.gee.save_geotiff_dsm_minus_dtm Module Contents --------------- .. py:function:: initialize_earth_engine(**initialize_kwargs) Initialize the Earth Engine API if not already initialized. Uses a public-behavior check to determine whether Earth Engine is already initialized by attempting to access asset roots. If that call fails, it will initialize Earth Engine using the provided keyword arguments. Arguments are passed through to ``ee.Initialize`` to support contexts such as specifying a ``project`` or service account credentials. .. py:function:: get_roi(input_coords) Create an Earth Engine region of interest polygon from coordinates. :param input_coords: List of coordinate pairs defining the polygon vertices in (lon, lat) format. The coordinates should form a valid polygon (non-self-intersecting). :returns: Earth Engine polygon geometry representing the ROI :rtype: ee.Geometry.Polygon .. note:: The function automatically closes the polygon by connecting the last vertex to the first vertex if they are not the same. .. py:function:: get_center_point(roi) Get the centroid coordinates of a region of interest. :param roi: Earth Engine geometry object representing the region of interest :returns: (longitude, latitude) coordinates of the centroid :rtype: tuple .. note:: The centroid is calculated using Earth Engine's geometric centroid algorithm, which may not always fall within the geometry for complex shapes. .. py:function:: get_ee_image_collection(collection_name, roi) Get the first image from an Earth Engine ImageCollection filtered by region. :param collection_name: Name of the Earth Engine ImageCollection (e.g., 'LANDSAT/LC08/C02/T1_TOA') :param roi: Earth Engine geometry to filter by :returns: First image from collection clipped to ROI, with any masked pixels unmasked :rtype: ee.Image .. note:: The function sorts images by time (earliest first) and unmasks any masked pixels in the final image. This is useful for ensuring complete coverage of the ROI. .. py:function:: get_ee_image(collection_name, roi) Get an Earth Engine Image clipped to a region. :param collection_name: Name of the Earth Engine Image asset :param roi: Earth Engine geometry to clip to :returns: Image clipped to ROI with masked pixels unmasked to 0 :rtype: ee.Image .. note:: Unlike get_ee_image_collection(), this function works with single image assets rather than image collections. It's useful for static datasets like DEMs. Masked pixels are replaced with 0 via unmask() so that downstream consumers receive numeric values instead of dataset-specific nodata sentinels (e.g. 255). .. py:function:: save_geotiff(image, filename, resolution=1, scale=None, region=None, crs=None) Save an Earth Engine image as a GeoTIFF file. This function provides flexible options for exporting Earth Engine images to GeoTIFF format. It handles different export scenarios based on the provided parameters. :param image: Earth Engine image to save :param filename: Output filename for the GeoTIFF :param resolution: Output resolution in degrees (default: 1), used when scale is not provided :param scale: Output scale in meters (overrides resolution if provided) :param region: Region to export (required if scale is provided) :param crs: Coordinate reference system (e.g., 'EPSG:4326') .. note:: - If scale and region are provided, uses ee_export_image() - Otherwise, uses ee_to_geotiff() with resolution parameter - The function automatically converts output to Cloud Optimized GeoTIFF (COG) format when using ee_to_geotiff() .. py:function:: get_dem_image(roi_buffered, source) Get a digital elevation model (DEM) image for a region. This function provides access to various global and regional Digital Elevation Model (DEM) datasets through Earth Engine. Each source has different coverage areas and resolutions. :param roi_buffered: Earth Engine geometry with buffer - should be larger than the actual area of interest to ensure smooth interpolation at edges :param source: DEM source, one of: - 'NASA': SRTM 30m global DEM - 'COPERNICUS': Copernicus 30m global DEM - 'DeltaDTM': Deltares global DTM - 'FABDEM': Forest And Buildings removed MERIT DEM - 'England 1m DTM': UK Environment Agency 1m terrain model - 'DEM France 5m': IGN RGE ALTI 5m France coverage - 'DEM France 1m': IGN RGE ALTI 1m France coverage - 'AUSTRALIA 5M DEM': Geoscience Australia 5m DEM - 'USGS 3DEP 1m': USGS 3D Elevation Program 1m DEM :returns: DEM image clipped to region :rtype: ee.Image .. note:: Some sources may have limited coverage or require special access permissions. The function will raise an error if the selected source is not available for the specified region. .. py:function:: save_geotiff_esa_land_cover(roi, geotiff_path) Save ESA WorldCover land cover data as a colored GeoTIFF. Downloads and exports the ESA WorldCover 10m resolution global land cover map. The output is a colored GeoTIFF where each land cover class is represented by a unique color as defined in the color_map. :param roi: Earth Engine geometry defining region of interest :param geotiff_path: Output path for GeoTIFF file Land cover classes and their corresponding colors: - Trees (10): Dark green - Shrubland (20): Orange - Grassland (30): Yellow - Cropland (40): Purple - Built-up (50): Red - Barren/sparse vegetation (60): Gray - Snow and ice (70): White - Open water (80): Blue - Herbaceous wetland (90): Teal - Mangroves (95): Light green - Moss and lichen (100): Beige .. note:: The output GeoTIFF is exported at 10m resolution, which is the native resolution of the ESA WorldCover dataset. .. py:function:: save_geotiff_dynamic_world_v1(roi, geotiff_path, date=None) Save Dynamic World land cover data as a colored GeoTIFF. Downloads and exports Google's Dynamic World near real-time land cover classification. The data is available globally at 10m resolution from 2015 onwards, updated every 2-5 days. :param roi: Earth Engine geometry defining region of interest :param geotiff_path: Output path for GeoTIFF file :param date: Optional date string (YYYY-MM-DD) to get data for specific time. If None, uses the most recent available image. Land cover classes and their colors: - water: Blue (#419bdf) - trees: Dark green (#397d49) - grass: Light green (#88b053) - flooded_vegetation: Purple (#7a87c6) - crops: Orange (#e49635) - shrub_and_scrub: Tan (#dfc35a) - built: Red (#c4281b) - bare: Gray (#a59b8f) - snow_and_ice: Light purple (#b39fe1) .. note:: If a specific date is provided but no image is available, the function will use the closest available date and print a message indicating the actual date used. .. py:function:: save_geotiff_esri_landcover(roi, geotiff_path, year=None) Save ESRI Land Cover data as a colored GeoTIFF. Downloads and exports ESRI's 10m resolution global land cover classification. This dataset is updated annually and provides consistent global coverage. :param roi: Earth Engine geometry defining region of interest :param geotiff_path: Output path for GeoTIFF file :param year: Optional year (YYYY) to get data for specific time. If None, uses the most recent available year. Land cover classes and colors: - Water (#1A5BAB): Water bodies - Trees (#358221): Tree cover - Flooded Vegetation (#87D19E): Vegetation in water-logged areas - Crops (#FFDB5C): Agricultural areas - Built Area (#ED022A): Urban and built-up areas - Bare Ground (#EDE9E4): Exposed soil and rock - Snow/Ice (#F2FAFF): Permanent snow and ice - Clouds (#C8C8C8): Cloud cover - Rangeland (#C6AD8D): Natural vegetation .. note:: The function will print the year of the data actually used, which may differ from the requested year if data is not available for that time. .. py:function:: save_geotiff_open_buildings_temporal(aoi, geotiff_path) Save Open Buildings temporal data as a GeoTIFF. Downloads and exports building height data from Google's Open Buildings dataset. This dataset provides building footprints and heights derived from satellite imagery. :param aoi: Earth Engine geometry defining area of interest :param geotiff_path: Output path for GeoTIFF file .. note:: - The output GeoTIFF contains building heights in meters - The dataset is updated periodically and may not cover all regions - Resolution is fixed at 4 meters per pixel - Areas without buildings will have no-data values .. py:function:: save_geotiff_dsm_minus_dtm(roi, geotiff_path, meshsize, source) Get the height difference between DSM and DTM from terrain data. Calculates the difference between Digital Surface Model (DSM) and Digital Terrain Model (DTM) to estimate heights of buildings, vegetation, and other above-ground features. :param roi: Earth Engine geometry defining area of interest :param geotiff_path: Output path for GeoTIFF file :param meshsize: Size of each grid cell in meters - determines output resolution :param source: Source of terrain data, one of: - 'England 1m DSM - DTM': UK Environment Agency 1m resolution - 'Netherlands 0.5m DSM - DTM': AHN4 0.5m resolution .. note:: - A 100m buffer is automatically added around the ROI to ensure smooth interpolation at edges - The output represents height above ground level in meters - Negative values may indicate data artifacts or actual below-ground features - The function requires both DSM and DTM data to be available for the region