search

leftfield-geospatial / geedim

Search, composite, and download Google Earth Engine imagery.
https://geedim.readthedocs.io
Apache License 2.0
77 stars 11 forks source link
cli cloud-free cloud-shadow-mask compositing download earth-observation google-earth-engine landsat python remote-sensing satellite-imagery search sentinel-2 surface-reflectance

readme

|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
------------

``geedim`` is a python 3 package, and requires users to be registered with `Google Earth
Engine <https://signup.earthengine.google.com>`__.

It can be installed with `pip <https://pip.pypa.io/>`_ or `conda <https://docs.anaconda.com/free/miniconda/>`_.

pip

.. code:: shell

pip install geedim

conda


.. code:: shell

   conda install -c conda-forge 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 <command> --help

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 <https://github.com/leftfield-geospatial/geedim/blob/main/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