|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 –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 ``cloud-score`` mask-method to identify clouds:

.. code:: shell

   geedim config --mask-method cloud-score search -c s2-sr-hm --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_HARMONIZED')
   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_HARMONIZED/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=10)

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