geedim
Search, composite, and download Google Earth Engine imagery, without size limits.
Description
geedim
provides a command line interface and API for searching, compositing and downloading satellite imagery
from Google Earth Engine (EE). It optionally performs cloud/shadow masking, and cloud/shadow-free compositing on
supported collections. Images and composites can be downloaded, or exported to Google Drive. Images larger than the
EE size limit are split and downloaded
as separate tiles, then re-assembled into a single GeoTIFF.
See the documentation site for more detail: https://geedim.readthedocs.io/.
Cloud/shadow support
Any EE imagery can be searched, composited and downloaded by geedim
. Cloud/shadow masking, and cloud/shadow-free
compositing are supported on the following collections:
EE name | Description |
---|---|
LANDSAT/LT04/C02/T1_L2 | Landsat 4, collection 2, tier 1, level 2 surface reflectance. |
LANDSAT/LT05/C02/T1_L2 | Landsat 5, collection 2, tier 1, level 2 surface reflectance. |
LANDSAT/LE07/C02/T1_L2 | Landsat 7, collection 2, tier 1, level 2 surface reflectance. |
LANDSAT/LC08/C02/T1_L2 | Landsat 8, collection 2, tier 1, level 2 surface reflectance. |
LANDSAT/LC09/C02/T1_L2 | Landsat 9, collection 2, tier 1, level 2 surface reflectance. |
COPERNICUS/S2 | Sentinel-2, level 1C, top of atmosphere reflectance. |
COPERNICUS/S2_SR | Sentinel-2, level 2A, surface reflectance. |
COPERNICUS/S2_HARMONIZED | Harmonised Sentinel-2, level 1C, top of atmosphere reflectance. |
COPERNICUS/S2_SR_HARMONIZED | Harmonised Sentinel-2, level 2A, surface reflectance. |
Installation
Requirements
geedim
is a python 3 package, and requires users to be registered with Google Earth
Engine.
conda
Under Windows, using conda
is the easiest way to resolve binary dependencies. The
Miniconda installation provides a minimal conda
.
conda install -c conda-forge geedim
pip
pip install geedim
Authentication
Following installation, Earth Engine should be authenticated:
earthengine authenticate
Getting started
Command line interface
geedim
command line functionality is accessed through the commands:
search
: Search for images.composite
: Create a composite image.download
: Download image(s).export
: Export image(s) to Google Drive.config
: Configure cloud/shadow masking.
Get help on geedim
with:
geedim --help
and help on a geedim
command with:
geedim <command> --help
Examples
Search for Landsat-8 images.
geedim search -c l8-c2-l2 -s 2021-06-01 -e 2021-07-01 --bbox 24 -33 24.1 -33.1
Download a Landsat-8 image with cloud/shadow mask applied.
geedim download -i LANDSAT/LC08/C02/T1_L2/LC08_172083_20210610 --bbox 24 -33 24.1 -33.1 --mask
Command pipelines
Multiple geedim
commands can be chained together in a pipeline where image results from the previous command form
inputs to the current command. For example, if the composite
command is chained with download
command, the
created composite image will be downloaded, or if the search
command is chained with the composite
command, the
search result images will be composited.
Common command options are also piped between chained commands. For example, if the config
command is chained with
other commands, the configuration specified with config
will be applied to subsequent commands in the pipeline. Many
command combinations are possible.
Examples
Composite two Landsat-7 images and download the result:
geedim composite -i LANDSAT/LE07/C02/T1_L2/LE07_173083_20100203 -i LANDSAT/LE07/C02/T1_L2/LE07_173083_20100219 download --bbox 22 -33.1 22.1 -33 --crs EPSG:3857 --scale 30
Composite the results of a Landsat-8 search and download the result.
geedim search -c l8-c2-l2 -s 2019-02-01 -e 2019-03-01 --bbox 23 -33 23.2 -33.2 composite -cm q-mosaic download --scale 30 --crs EPSG:3857
Search for Sentinel-2 SR images with a cloudless portion of at least 60%, using the qa
mask-method to identify
clouds:
geedim config --mask-method qa search -c s2-sr --cloudless-portion 60 -s 2022-01-01 -e 2022-01-14 --bbox 24 -34 24.5 -33.5
API
Example
import geedim as gd
gd.Initialize() # initialise earth engine
# geojson region to search / download
region = {
"type": "Polygon",
"coordinates": [[[24, -33.6], [24, -33.53], [23.93, -33.53], [23.93, -33.6], [24, -33.6]]]
}
# make collection and search
coll = gd.MaskedCollection.from_name('COPERNICUS/S2_SR')
coll = coll.search('2019-01-10', '2019-01-21', region)
print(coll.schema_table)
print(coll.properties_table)
# create and download an image
im = gd.MaskedImage.from_id('COPERNICUS/S2_SR/20190115T080251_20190115T082230_T35HKC')
im.download('s2_image.tif', region=region)
# composite search results and download
comp_im = coll.composite()
comp_im.download('s2_comp_image.tif', region=region, crs='EPSG:32735', scale=30)
License
This project is licensed under the terms of the Apache-2.0 License.
Contributing
See the documentation for details.
Credits
- Tiled downloading was inspired by the work in GEES2Downloader under terms of the MIT license.
- Medoid compositing was adapted from gee_tools under the terms of the MIT license.
- Sentinel-2 cloud/shadow masking was adapted from ee_extra under terms of the Apache-2.0 license
Author
Dugal Harris - dugalh@gmail.com