|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
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
FAQs
Search, composite and download Google Earth Engine imagery.
We found that geedim demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.