geedim
geedim copied to clipboard
Published
20 hours ago •
leftfield-geospatial
leftfield-geospatial
Search, composite, and download Google Earth Engine imagery.
|Tests| |codecov| |PyPI version| |conda-forge version| |docs| |License|
geedim
.. short_descr_start
Search, composite, and download Google Earth Engine <https://earthengine.google.com/>__ imagery, without size limits.
.. short_descr_end
.. description_start
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, Earth Engine asset or
Google Cloud Storage. Images larger than the
EE size limit <https://developers.google.com/earth-engine/apidocs/ee-image-getdownloadurl>_ are split and downloaded
as separate tiles, then re-assembled into a single GeoTIFF.
.. description_end
See the documentation site for more detail: https://geedim.readthedocs.io/.
.. supp_im_start
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:
.. supp_im_end
+------------------------------------------+-------------------------------------------------------+
| EE name | Description |
+==========================================+=======================================================+
| `LANDSAT/LT04/C02/T1_L2 | Landsat 4, collection 2, tier 1, level 2 surface |
| <https://developers.google.com/earth-eng | reflectance. |
| ine/datasets/catalog/LANDSAT_LT04_C02_T1 | |
| _L2>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LT05/C02/T1_L2 | Landsat 5, collection 2, tier 1, level 2 surface |
| <https://developers.google.com/earth-eng | reflectance. |
| ine/datasets/catalog/LANDSAT_LT05_C02_T1 | |
| _L2>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LE07/C02/T1_L2 | Landsat 7, collection 2, tier 1, level 2 surface |
| <https://developers.google.com/earth-eng | reflectance. |
| ine/datasets/catalog/LANDSAT_LE07_C02_T1 | |
| _L2>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LC08/C02/T1_L2 | Landsat 8, collection 2, tier 1, level 2 surface |
| <https://developers.google.com/earth-eng | reflectance. |
| ine/datasets/catalog/LANDSAT_LC08_C02_T1 | |
| _L2>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LC09/C02/T1_L2 | Landsat 9, collection 2, tier 1, level 2 surface |
| <https://developers.google.com/earth-eng | reflectance. |
| ine/datasets/catalog/LANDSAT_LC09_C02_T1 | |
| _L2>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2 | Sentinel-2, level 1C, top of atmosphere reflectance. |
| <https://developers.google.com/earth- | |
| engine/datasets/catalog/COPERNICUS_S2>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2_SR | Sentinel-2, level 2A, surface reflectance. |
| <https://developers.google.com/earth-eng | |
| ine/datasets/catalog/COPERNICUS_S2_SR>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2_HARMONIZED | Harmonised Sentinel-2, level 1C, top of atmosphere |
| <https://developers.google.com/earth-eng | reflectance. |
| ine/datasets/catalog/COPERNICUS_S2_HARMO | |
| NIZED>`_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2_SR_HARMONIZED | Harmonised Sentinel-2, level 2A, surface reflectance. |
| <https://developers.google.com/earth-eng | |
| ine/datasets/catalog/COPERNICUS_S2_SR_HA | |
| RMONIZED>`_ | |
+------------------------------------------+-------------------------------------------------------+
.. install_start
Installation
------------
Requirements
~~~~~~~~~~~~
``geedim`` is a python 3 package, and requires users to be registered with `Google Earth
Engine <https://signup.earthengine.google.com>`__.
conda
~~~~~
Under Windows, using ``conda`` is the easiest way to resolve binary dependencies. The
`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ installation provides a minimal ``conda``.
.. code:: shell
conda install -c conda-forge geedim
pip
~~~
.. code:: shell
pip install geedim
Authentication
~~~~~~~~~~~~~~
Following installation, Earth Engine should be authenticated:
.. code:: shell
earthengine authenticate
.. install_end
Getting started
---------------
Command line interface
.. cli_start
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:
.. code:: shell
geedim --help
and help on a geedim command with:
.. code:: shell
geedim
Examples ^^^^^^^^
Search for Landsat-8 images, reporting cloudless portions.
.. code:: shell
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.
.. code:: shell
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-1:
Examples
^^^^^^^^
Composite two Landsat-7 images and download the result:
.. code:: shell
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.
.. code:: shell
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.
.. code:: shell
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:
.. code:: shell
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
.. cli_end
API
~~~
Example
^^^^^^^
.. code:: python
import geedim as gd
gd.Initialize() # initialise earth engine
# geojson polygon 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, reporting cloudless portions
coll = gd.MaskedCollection.from_name('COPERNICUS/S2_SR')
coll = coll.search('2019-01-10', '2019-01-21', region, cloudless_portion=0)
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 <LICENSE>`__.
Contributing
------------
See the `documentation <https://geedim.readthedocs.io/en/latest/contributing.html>`__ for details.
Credits
-------
- Tiled downloading was inspired by the work in `GEES2Downloader <https://github.com/cordmaur/GEES2Downloader>`__ under
terms of the `MIT license <https://github.com/cordmaur/GEES2Downloader/blob/main/LICENSE>`__.
- Medoid compositing was adapted from `gee_tools <https://github.com/gee-community/gee_tools>`__ under the terms of the
`MIT license <https://github.com/gee-community/gee_tools/blob/master/LICENSE>`__.
- Sentinel-2 cloud/shadow masking was adapted from `ee_extra <https://github.com/r-earthengine/ee_extra>`__ under
terms of the `Apache-2.0 license <https://github.com/r-earthengine/ee_extra/blob/master/LICENSE>`__
.. |Tests| image:: https://github.com/leftfield-geospatial/geedim/actions/workflows/run-unit-tests.yml/badge.svg
:target: https://github.com/leftfield-geospatial/geedim/actions/workflows/run-unit-tests.yml
.. |codecov| image:: https://codecov.io/gh/leftfield-geospatial/geedim/branch/main/graph/badge.svg?token=69GZNQ3TI3
:target: https://codecov.io/gh/leftfield-geospatial/geedim
.. |PyPI version| image:: https://img.shields.io/pypi/v/geedim.svg
:target: https://pypi.org/project/geedim/
.. |conda-forge version| image:: https://img.shields.io/conda/vn/conda-forge/geedim.svg
:alt: conda-forge
:target: https://anaconda.org/conda-forge/geedim
.. |docs| image:: https://readthedocs.org/projects/geedim/badge/?version=latest
:target: https://geedim.readthedocs.io/en/latest/?badge=latest
.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
:target: https://opensource.org/licenses/Apache-2.0
Metadata
74
Stars
10
Forks
Watchers
Owner
leftfield-geospatial
Metadata
Search, composite, and download Google Earth Engine imagery.