Getting Started with EEDL

At its core, EEDL does just a few things - it take an Earth Engine Image, exports it in tiles, downloads the pieces and reassembles on your local machine, giving you the ability to wait for the data to be available before proceeding. It further has options for running zonal statistics to output polygon-level summary data in addition to the image exports.

Most work is done with the EEDLImage class, which is your entry point to almost all functionality of the EEDL package, though EEDL also includes a set of helper classes that automate common tasks for larger processes, such as extraction of all dates in an image collection for multiple areas of interest.

EEDL requires three things in order to run exports

An installed copy of the eedl package

An installed and authenticated copy of the earthengine package

That you either have Google’s Drive client installed on the computer that you run your code on, or you have a Google Cloud account with billing set up and a Storage bucket created. See here for more considerations on how to run the export.

The simplest script using EEDL would look something like:

import ee
import eedl

# get the first image in the Landsat 9 collection
# you can do anything that gives you an ee.Image object here instead too.
image = ee.ImageCollection("LANDSAT/LC09/C02/T1_L2").first()

# set a download path - the image will be put in this folder
download_folder = r"C:\Users\your_account\data"

# instantiate the EEDLImage object
exporter = eedl.EEDLImage()

# starts the export of your image from Earth Engine to the chosen export location
# does not start the download to your computer or block your code execution after
# starting the export
exporter.export(image, export_type="Drive", drive_root_folder="G:\My Drive")

# tell your code to wait for all images you've exported
# so far to be downloaded and processed before proceeding
eedl.main_task_registry.wait_for_images(download_location=download_folder, callback="mosaic")

# print the path to the downloaded image that you can now use in following code
print(exporter.mosaic_image)

This is an oversimplified example, but it shows the complete workflow. You can export dozens or even hundreds of images before executing the last line to wait for the images to complete exporting, allowing for large batch exports, and the class and .export() method each support substantial arguments affecting their behavior.

In this example, we pulled an existing image from an Earth Engine collection by taking the first image in the Landsat 9 collection. But EEDL isn’t limited to existing assets and can also export computed images, exactly as you would if you were triggering an export in the online code environment, or from other Python code. Any valid ee.Image object can be exported with EEDL.

How EEDL Works

When you trigger an EEDL export or multiple exports, many things happen in sequence:

You kick off a standard Earth Engine export task - these tasks can be monitored in the Earth Engine Task Manager as usual
Earth Engine begins an export, in tiles, the image you provided for export. The tiling is automatically specified by EEDL, but you may need to tune the parameters for some images, especially multiband images.
During the export process, you will configure it to export to your Google Drive or to a Google Cloud Storage bucket as an intermediate location for the export.
After kicking off your export(s), you tell EEDL to wait for all the images you’ve exported to be available. EEDL automatically tracks their status, downloads any that are complete, and optionally begins postprocessing (mosaicking, zonal stats) on complete images while waiting for Earth Engine to export remaining images.
As part of this process, EEDL will automatically retrieves the images from Drive or Cloud storage. Each of these requires specific configuration for your Cloud storage or Google Drive setup. Multiple images (thousands, even) can be exported into the same folder in Drive or Cloud storage - EEDL tracks the tiles of each image by name to avoid mixing up pieces, so make sure to give each image a unique name or prefix. EEDL doesn’t currently add its own unique identifiers to export names (but we’d like to).

Points of Configuration

Note the main points of configuration in this example:

Creation of the image object: As stated above, here you can customize your image to any valid Earth Engine image - no need to save it out as an asset or into a collection first

When creating the EEDLImage object - The example above shows no arguments, but you can pass in information, such as CRS information, tiling parameters, and configuration options for running zonal statistics, here. You may want to adjust tiling parameters for multi-band exports, for example, since those can run into Earth Engine’s per-tile limits more easily. See documentation for eedl.image module for more information on arguments to the class.

When triggering the export: When running the export, you can specify image name information, as well as provide overrides for some class defaults. Additionally, you can provide any valid keyword argument to Earth Engine’s export methods directly as keywords to the EEDLImage export method and they’ll be passed directly through to Earth Engine.

And when waiting for images: The main points of configuration to set up when waiting are around where to save images on your device, how to handle errors encountered while processing images, how long to wait between polls of the Earth Engine image status endpoints, and whether to run a callback - a method on the EEDLImage class that does postprocessing. Callbacks are helpful because they make EEDL do work on images it has already downloaded while it waits for Earth Engine to export any remaining images. The end result is that your total processing time shouldn’t be much longer than Earth Engine’s total export time in most cases, even for hundreds of exports. The primary callback to access EEDL’s functionality is just the mosaic method, but there is also a mosaic_and_zonal method that will mosaic the image then run zonal stats. Note that mosaic_and_zonal requires that you provide additional configuration parameters when initializing EEDLImage, but mosaic can run without additional configuration.