Command line interface

Getting started

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).
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, reporting cloudless portions.

geedim search -c l8-c2-l2 -s 2021-06-01 -e 2021-07-01 --bbox 24 -33 24.1 -33.1 --cloudless-portion

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

Composite the results of a Landsat-8 search, export to Earth Engine asset, and download the asset image.

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 export --type asset --folder <your cloud project> --scale 30 --crs EPSG:3857 download

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

Usage

geedim

Search, composite and download Google Earth Engine imagery.

geedim [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options

-v, --verbose: Increase verbosity.

-q, --quiet: Decrease verbosity.

--version: Show the version and exit.

Commands

composite: Create a composite image.

config: Configure cloud/shadow masking.

download: Download image(s).

export: Export image(s).

search: Search for images.

geedim search

Search for images.

Search a Google Earth Engine image collection for images, based on date, region, portion of filled pixels in region, and custom filters. Filtering on cloud/shadow-free (cloudless) portion of filled pixels is supported on the following collections:

geedim name

EE name

l4-c2-l2

LANDSAT/LT04/C02/T1_L2

l5-c2-l2

LANDSAT/LT05/C02/T1_L2

l7-c2-l2

LANDSAT/LE07/C02/T1_L2

l8-c2-l2

LANDSAT/LC08/C02/T1_L2

l9-c2-l2

LANDSAT/LC09/C02/T1_L2

s2-toa

COPERNICUS/S2

s2-sr

COPERNICUS/S2_SR

s2-toa-hm

COPERNICUS/S2_HARMONIZED

s2-sr-hm

COPERNICUS/S2_SR_HARMONIZED

The search must be filtered with at least one of the --start-date, --bbox or --region options.

Note that filled/cloudless portions are not taken from the granule metadata, but are calculated as portions inside the specified search region for improved accuracy. These portions are only found and reported when one or both of --fill-portion / --cloudless-portion are specified.

Search speed can be improved by specifying --custom-filter, and or by omitting --fill-portion / --cloudless-portion.

Examples

Search the GEDI canopy height collection for images with a filled portion of at least 0.5%:

geedim search -c LARSE/GEDI/GEDI02_A_002_MONTHLY -s 2021-12-01 -e 2022-02-01 --bbox 23 -34 23.2 -33.8 --fill-portion 0.5

Search the Landsat-9 collection for images, reporting the cloud/shadow free portion:

geedim search -c l9-c2-l2 -s 2022-01-01 -e 2022-03-01 --bbox 23 -34 23.2 -33.8 --cloudless-portion

Search the Landsat-8 collection for images whose CLOUD_COVER_LAND property is less than 50%, and include the CLOUD_COVER_LAND, and CLOUD_COVER image properties in the search results:

geedim search -c l8-c2-l2 -s 2022-01-01 -e 2022-05-01 --bbox 23 -34 23.2 -33.8 -cf "CLOUD_COVER_LAND<50" -ap CLOUD_COVER_LAND -ap CLOUD_COVER

geedim search [OPTIONS]

Options

-c, --collection <collection>: Required Earth Engine image collection to search. geedim or EE collection names can be used.

-s, --start-date <start_date>: Start date (UTC).

-e, --end-date <end_date>

End date (UTC).

Default:: one day after ``--start-date``

-b, --bbox <LEFT BOTTOM RIGHT TOP>: Region defined by WGS84 bounding box co-ordinates.

-r, --region <region>: Region defined by geojson polygon or raster file. Use “-” to read geojson from stdin.

-fp, --fill-portion, --fill <VALUE>

Lower limit on the portion of the region that contains filled/valid image pixels (%). Uses zero if VALUE is not specified.

Default:: don't calculate, or filter on, fill portion

-cp, --cloudless-portion, --cloudless <VALUE>

Lower limit on the portion of filled pixels that are cloud/shadow free (%). Uses zero if VALUE is not specified. If cloud/shadow masking is not supported for the specified collection, --cloudless-portion has no effect.

Default:: don't calculate, or filter on, cloudless portion

-cf, --custom-filter <custom_filter>: Custom image property filter e.g. “property > value”. Quote delimiters are required.

-ap, --add-property <add_props>: Additional image property name(s) to include in search results.

-op, --output <output>: JSON file to write search results to.

geedim download

Download image(s).

Download Earth Engine image(s) to GeoTIFF file(s), allowing optional region of interest, and other image formatting options to be specified. Images larger than the Earth Engine size limit are split and downloaded as separate tiles, then re-assembled into a single GeoTIFF. Downloaded image files are populated with metadata from the Earth Engine image and STAC.

This command can be chained after the composite command, to download the composite image, or it can be chained after an asset export to download the asset image. It can also be chained after the search command, in which case the search result images will be downloaded, without the need to specify image IDs with --id, or region with --bbox / --region.

The following auxiliary bands are added to images from collections with support for cloud/shadow masking:

Band name

Description

FILL_MASK

Mask of filled (valid) pixels.

SHADOW_MASK

Mask of cloud shadows.

CLOUD_MASK

Mask of clouds.

CLOUDLESS_MASK

Mask of filled & cloud/shadow-free pixels.

CLOUD_DIST

Distance to nearest cloud (10m).

Images from other collections, will contain the FILL_MASK band only.

Bounds and resolution of the downloaded image can be specified with --region / --bbox and --scale / --shape, or --crs-transform and --shape. The --like option will automatically derive --crs, --crs-transform and --shape from a provided template raster. If no bounds are specified (with either --region, or --crs-transform & --shape), the entire image granule is downloaded.

When --crs, --scale, --crs-transform and --shape are not specified, the pixel grids of the downloaded and Earth Engine images will coincide.

Image filenames are derived from their Earth Engine ID.

Examples

Download a region of a Landsat-9 image, applying the cloud/shadow mask and converting to uint16:

geedim download -i LANDSAT/LC09/C02/T1_L2/LC09_173083_20220308 --mask --bbox 21.6 -33.5 21.7 -33.4 --dtype uint16

Download the results of a MODIS NBAR search, specifying a CRS and scale to reproject to:

geedim search -c MODIS/006/MCD43A4 -s 2022-01-01 -e 2022-01-03 --bbox 23 -34 24 -33 download --crs EPSG:3857 --scale 500

geedim download [OPTIONS]

Options

-i, --id <image_id>: Earth Engine image ID(s) to download.

-c, --crs <crs>

CRS to reproject image(s) to (EPSG string or path to WKT text file).

Default:: source image CRS.

-b, --bbox <LEFT BOTTOM RIGHT TOP>: Region defined by WGS84 bounding box co-ordinates.

-r, --region <region>: Region defined by geojson polygon file, or raster file. Use “-” to read geojson from stdin.

-s, --scale <scale>

Pixel scale (size) to resample image(s) to (m).

Default:: minimum scale of the source image bands.

-ct, --crs-transform <XSCALE XSHEAR XTRANSLATION YSHEAR YSCALE YTRANSLATION>: Six element affine transform in the download CRS. Use with --shape to specify image bounds and resolution.

-sh, --shape <HEIGHT WIDTH>: Image height & width dimensions (pixels).

-l, --like <like>: Template raster from which to derive --crs, --crs-transform & --shape.

-dt, --dtype <dtype>

Data type to convert image(s) to.

Default:: smallest data type able to represent the range of pixel values.
Options:: uint8 | uint16 | uint32 | int8 | int16 | int32 | float32 | float64

-bn, --band-name <bands>

Band name(s) to download.

Default:: all bands

-m, --mask, -nm, --no-mask

Whether to apply cloud/shadow mask(s); or fill mask(s), in the case of images without support for cloud/shadow masking.

Default:: False

-rs, --resampling <resampling>

Resampling method.

Default:: near
Options:: near | bilinear | bicubic | average

-so, --scale-offset, -nso, --no-scale-offset

Whether to apply any EE band scales and offsets to the image.

Default:: False

-dd, --download-dir <download_dir>

Directory to download image file(s) into.

Default:: current working directory.

-mts, --max-tile-size <max_tile_size>

Maximum download tile size (MB).

Default:: 32

-mtd, --max-tile-dim <max_tile_dim>

Maximum download tile dimension (pixels).

Default:: 10000

-o, --overwrite: Overwrite the destination file if it exists.

geedim export

Export image(s).

Export Earth Engine image(s) to Google Drive, Earth Engine asset, or Google Cloud Storage, allowing optional region of interest, and other image formatting options to be specified.

This command can be chained after the composite command, to export the composite image. It can also be chained after the search command, in which case the search result images will be exported, without the need to specify image IDs with --id, or region with --bbox / --region.

The following auxiliary bands are added to images from collections with support for cloud/shadow masking:

Band name

Description

FILL_MASK

Mask of filled (valid) pixels.

SHADOW_MASK

Mask of cloud shadows.

CLOUD_MASK

Mask of clouds.

CLOUDLESS_MASK

Mask of filled & cloud/shadow-free pixels.

CLOUD_DIST

Distance to nearest cloud (10m).

Images from other collections, will contain the FILL_MASK band only.

Bounds and resolution of the exported image can be specified with --region / --bbox and --scale / --shape, or --crs-transform and --shape. The --like option will automatically derive --crs, --crs-transform and --shape from a provided template raster. If no bounds are specified (with either --region, or --crs-transform & --shape), the entire image granule is exported.

When --crs, --scale, --crs-transform and --shape are not specified, the pixel grids of the exported and Earth Engine images will coincide.

Image file or asset names are derived from their Earth Engine ID.

Examples

Export a region of a Landsat-9 image to an Earth Engine asset, applying the cloud/shadow mask and converting to uint16:

geedim export -i LANDSAT/LC09/C02/T1_L2/LC09_173083_20220308 --type asset --folder <your cloud project> --mask --bbox 21.6 -33.5 21.7 -33.4 --dtype uint16

Export the results of a MODIS NBAR search to Google Drive in the ‘geedim’ folder, specifying a CRS and scale to reproject to:

geedim search -c MODIS/006/MCD43A4 -s 2022-01-01 -e 2022-01-03 --bbox 23 -34 24 -33 export --crs EPSG:3857 --scale 500 -df geedim

geedim export [OPTIONS]

Options

-i, --id <image_id>: Earth Engine image ID(s) to export.

-t, --type <type>

Export type.

Default:: drive
Options:: drive | asset | cloud

-f, -df, --folder, --drive-folder <folder>: Google Drive folder, Earth Engine asset project, or Google Cloud Storage bucket to export image(s) to. Interpretation based on --type.

-c, --crs <crs>

CRS to reproject image(s) to (EPSG string or path to WKT text file).

Default:: source image CRS.

-b, --bbox <LEFT BOTTOM RIGHT TOP>: Region defined by WGS84 bounding box co-ordinates.

-r, --region <region>: Region defined by geojson polygon file, or raster file. Use “-” to read geojson from stdin.

-s, --scale <scale>

Pixel scale (size) to resample image(s) to (m).

Default:: minimum scale of the source image bands.

-ct, --crs-transform <XSCALE XSHEAR XTRANSLATION YSHEAR YSCALE YTRANSLATION>: Six element affine transform in the download CRS. Use with --shape to specify image bounds and resolution.

-sh, --shape <HEIGHT WIDTH>: Image height & width dimensions (pixels).

-l, --like <like>: Template raster from which to derive --crs, --crs-transform & --shape.

-dt, --dtype <dtype>

Data type to convert image(s) to.

Default:: smallest data type able to represent the range of pixel values.
Options:: uint8 | uint16 | uint32 | int8 | int16 | int32 | float32 | float64

-bn, --band-name <bands>

Band name(s) to download.

Default:: all bands

-m, --mask, -nm, --no-mask

Whether to apply cloud/shadow mask(s); or fill mask(s), in the case of images without support for cloud/shadow masking.

Default:: False

-rs, --resampling <resampling>

Resampling method.

Default:: near
Options:: near | bilinear | bicubic | average

-so, --scale-offset, -nso, --no-scale-offset

Whether to apply any EE band scales and offsets to the image.

Default:: False

-w, --wait, -nw, --no-wait

Whether to wait for the export to complete.

Default:: True

geedim composite

Create a composite image.

Create cloud/shadow-free and other composite image(s) from specified input images.

download or export commands can be chained after the composite command to download/export the composite image. composite can also be chained after search, download or composite, in which case it will composite the output image(s) from the previous command. Images specified with the --id option will be added to any existing chained images i.e. images output from previous chained commands.

In general, input images should belong to the same collection. In the specific case of Landsat, images from spectrally compatible collections can be combined i.e. Landsat-4 with Landsat-5, and Landsat-8 with Landsat-9.

--method specifies the method for finding a composite pixel from the stack of corresponding input image pixels. The following options are available:

Method

Description

q-mosaic

Use the unmasked pixel with the highest cloud distance

(i.e. distance to nearest cloud). Where more than one

pixel has the same cloud distance, the first one in the

stack is selected.

mosaic

Use the first unmasked pixel in the stack.

medoid

Use the medoid of the unmasked pixels i.e. the pixel

of the image with the minimum sum of spectral distances

to the rest of the input images.

Maintains relationship between bands.

median

Use the median of the unmasked pixels.

mode

Use the mode of the unmasked pixels.

mean

Use the mean of the unmasked pixels.

For the mosaic, q-mosaic and medoid methods there are three ways of ordering (i.e. prioritising) images in the stack:

If --date is specified, images are sorted by the absolute

difference of their capture time from this date.

If either --region or --bbox are specified, images are sorted

by their cloudless/filled portion inside this region.

If none of the above options are specified, images are sorted by their

capture time.

By default, input images are masked before compositing. This means that only cloud/shadow-free (or filled) pixels are used to make the composite. You can turn off this behaviour with the --no-mask option.

Examples

Composite two Landsat-7 images using the default options 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

Create and download a composite of a year of GEDI canopy height data, by chaining with search:

geedim search -c LARSE/GEDI/GEDI02_A_002_MONTHLY -s 2021-01-01 -e 2022-01-01 --bbox 23 -34 23.1 -33.9 --fill-portion 0.1 composite -cm mosaic download --crs EPSG:3857 --scale 25

Create and download a cloud/shadow-free composite of Sentinel-2 SR images, by chaining with search:

geedim search -c s2-sr -s 2021-01-12 -e 2021-01-23 --bbox 23 -33.5 23.1 -33.4 composite -cm q-mosaic download --crs EPSG:3857 --scale 10

geedim composite [OPTIONS]

Options

-i, --id <image_id>: Earth Engine image ID(s) to include in composite.

-cm, --method <method>

Compositing method to use.

Default:: `q-mosaic` for cloud/shadow mask supported collections, `mosaic` otherwise.
Options:: q-mosaic | mosaic | medoid | median | mode | mean

-m, --mask, -nm, --no-mask

Whether to apply cloud/shadow (or fill) masks to input images before compositing. Fill masks are used for images without support for cloud/shadow masking.

Default:: True

-rs, --resampling <resampling>

Resample images with this method before compositing.

Default:: near
Options:: near | bilinear | bicubic | average

-b, --bbox <bbox>: Give preference to images with the highest cloudless (or filled) portion inside this bounding box (left, bottom, right, top). Valid for mosaic and q-mosaic compositing --method.

-r, --region <region>: Give preference to images with the highest cloudless (or filled) portion inside this geojson polygon, or raster file, region. Valid for mosaic and q-mosaic compositing --method.

-d, --date <date>: Give preference to images closest to this date (UTC). Valid for mosaic and q-mosaic compositing --method.

geedim config

Configure cloud/shadow masking.

Chain this command with one or more other command(s) to configure cloud/shadow masking for those operation(s). A sensible default configuration is used if this command is not specified.

Cloud/shadow masking is supported for the collections:

geedim name

EE name

l4-c2-l2

LANDSAT/LT04/C02/T1_L2

l5-c2-l2

LANDSAT/LT05/C02/T1_L2

l7-c2-l2

LANDSAT/LE07/C02/T1_L2

l8-c2-l2

LANDSAT/LC08/C02/T1_L2

l9-c2-l2

LANDSAT/LC09/C02/T1_L2

s2-toa

COPERNICUS/S2

s2-sr

COPERNICUS/S2_SR

s2-toa-hm

COPERNICUS/S2_HARMONIZED

s2-sr-hm

COPERNICUS/S2_SR_HARMONIZED

For Sentinel-2 collections, --mask-method can be one of:

cloud-prob: Use a threshold on the corresponding Sentinel-2 cloud

probability image.

qa: Use the Sentinel-2 QA60 quality band.

Examples

Search the Sentinel-2 SR collection for images with a cloudless portion of at least 60%, where cloud/shadow is identified with the qa mask-method:

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

Download and cloud/shadow mask a Landsat-8 image, where shadows are excluded from the mask:

geedim config --no-mask-shadows download -i LANDSAT/LC08/C02/T1_L2/LC08_172083_20220104 --mask --bbox 24.25 -34 24.5 -33.75

geedim config [OPTIONS]

Options

-mc, --mask-cirrus, -nmc, --no-mask-cirrus

Whether to mask cirrus clouds. Valid for Landsat 8-9 images, and, for Sentinel-2 images with the qa --mask-method.

Default:: True

-ms, --mask-shadows, -nms, --no-mask-shadows

Whether to mask cloud shadows.

Default:: True

-mm, --mask-method <mask_method>

Method used to mask clouds. Valid for Sentinel-2 images.

Default:: cloud-prob
Options:: cloud-prob | qa

-p, --prob <prob>

Cloud probability threshold (%). Valid for Sentinel-2 images with the cloud-prob --mask-method

Default:: 60

-d, --dark <dark>

NIR reflectance threshold for shadow masking. NIR values below this threshold are potential cloud shadows. Valid for Sentinel-2 images

Default:: 0.15

-sd, --shadow-dist <shadow_dist>

Maximum distance (m) to look for cloud shadows from cloud edges. Valid for Sentinel-2 images.

Default:: 1000

-b, --buffer <buffer>

Distance (m) to dilate cloud/shadow. Valid for Sentinel-2 images.

Default:: 50

-cdi, --cdi-thresh <cdi_thresh>: Cloud Displacement Index (CDI) threshold. Values below this threshold are considered potential clouds. Valid for Sentinel-2 images. By default, the CDI is not used.

-mcd, --max-cloud-dist <max_cloud_dist>

Maximum distance (m) to look for clouds. Used to form the cloud distance band for the q-mosaic compositing --method.

Default:: 5000