Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/leftfield-geospatial/geedim
Search, composite, and download Google Earth Engine imagery.
https://github.com/leftfield-geospatial/geedim
cli cloud-free cloud-shadow-mask compositing download earth-observation google-earth-engine landsat python remote-sensing satellite-imagery search sentinel-2 surface-reflectance
Last synced: 3 months ago
JSON representation
Search, composite, and download Google Earth Engine imagery.
- Host: GitHub
- URL: https://github.com/leftfield-geospatial/geedim
- Owner: leftfield-geospatial
- License: apache-2.0
- Created: 2021-07-26T10:55:36.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-20T19:16:18.000Z (8 months ago)
- Last Synced: 2024-05-02T03:02:13.625Z (6 months ago)
- Topics: cli, cloud-free, cloud-shadow-mask, compositing, download, earth-observation, google-earth-engine, landsat, python, remote-sensing, satellite-imagery, search, sentinel-2, surface-reflectance
- Language: Python
- Homepage: https://geedim.readthedocs.io
- Size: 1.14 MB
- Stars: 72
- Watchers: 5
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Contributing: docs/contributing.rst
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- Awesome-GEE - geedim - Search, composite, and download Earth Engine imagery, without size limits. (Python API / Packages)
README
|Tests| |codecov| |PyPI version| |conda-forge version| |docs| |License|
``geedim``
==========
.. short_descr_start
Search, composite, and download `Google Earth Engine `__ 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 `_ 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 |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LT05/C02/T1_L2 | Landsat 5, collection 2, tier 1, level 2 surface |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LE07/C02/T1_L2 | Landsat 7, collection 2, tier 1, level 2 surface |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LC08/C02/T1_L2 | Landsat 8, collection 2, tier 1, level 2 surface |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `LANDSAT/LC09/C02/T1_L2 | Landsat 9, collection 2, tier 1, level 2 surface |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2 | Sentinel-2, level 1C, top of atmosphere reflectance. |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2_SR | Sentinel-2, level 2A, surface reflectance. |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2_HARMONIZED | Harmonised Sentinel-2, level 1C, top of atmosphere |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
| `COPERNICUS/S2_SR_HARMONIZED | Harmonised Sentinel-2, level 2A, surface reflectance. |
| `_ | |
+------------------------------------------+-------------------------------------------------------+
.. install_start
Installation
------------
``geedim`` is a python 3 package, and requires users to be registered with `Google Earth
Engine `__.
It can be installed with `pip `_ or `conda `_.
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 --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 `__.
Contributing
------------
See the `documentation `__ for details.
Credits
-------
- Tiled downloading was inspired by the work in `GEES2Downloader `__ under
terms of the `MIT license `__.
- Medoid compositing was adapted from `gee_tools `__ under the terms of the
`MIT license `__.
- Sentinel-2 cloud/shadow masking was adapted from `ee_extra `__ under
terms of the `Apache-2.0 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