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: 6 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 (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-04-21T19:26:04.000Z (about 1 year ago)
- Last Synced: 2025-05-01T13:01:59.156Z (about 1 year 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.47 MB
- Stars: 94
- Watchers: 4
- Forks: 13
- Open Issues: 1
-
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
======
.. description_start
Geedim provides a Python API and command line toolkit for exporting and cloud masking Google Earth Engine (GEE) imagery. Images and Image collections can be exported to:
- GeoTIFF file
- NumPy array
- Xarray Dataset / DataArray
- Google Cloud platforms
And cloud masking is supported on:
- Landsat 4-9 `collection 2 `__ images
- Sentinel-2 `TOA `__ and `surface reflectance `__ images
.. description_end
.. install_start
Installation
------------
To install from PyPI:
.. code:: shell
pip install geedim
To install from conda-forge:
.. code:: shell
conda install -c conda-forge geedim
To support exporting to Xarray, use ``pip install geedim[xarray]`` or ``conda install -c conda-forge geedim xarray`` instead.
A registered Google Cloud project is required for `access to Earth Engine `__. Once installation and registration is done, Earth Engine should be authenticated:
.. code:: shell
earthengine authenticate
.. install_end
Examples
--------
API
~~~
Geedim provides access to its functionality through the ``gd`` accessor on the ``ee.Image`` and ``ee.ImageCollection`` `GEE `__ classes. This example exports a 6 month cloud-free composite of Sentinel-2 surface reflectance imagery to a GeoTIFF file:
.. code:: python
import ee
# import geedim to enable accessors
import geedim # noqa: F401
ee.Initialize()
# filter collection based on cloud-free portion etc.
region = ee.Geometry.Rectangle(24.35, -33.75, 24.45, -33.65)
coll = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED')
filt_coll = coll.gd.filter(
'2021-10-01', '2022-04-01', region=region, cloudless_portion=60
)
# print image properties
print(filt_coll.gd.schemaTable)
print(filt_coll.gd.propertiesTable)
# create a cloud-free composite & download
comp_im = filt_coll.gd.composite('median')
prep_im = comp_im.gd.prepareForExport(
crs='EPSG:3857', region=region, scale=10, dtype='uint16'
)
prep_im.gd.toGeoTIFF('s2_comp.tif')
Command line interface
~~~~~~~~~~~~~~~~~~~~~~
Much of the API functionality can also be accessed on the command line with ``geedim`` and its sub-commands. This repeats the API example, exporting a 6-month cloud-free composite of Sentinel-2 surface reflectance imagery to a GeoTIFF file:
.. code:: shell
geedim search -c COPERNICUS/S2_SR_HARMONIZED -s 2024-10-01 -e 2025-04-01 -b 24.35 -33.75 24.45 -33.65 -cp 60 composite -cm median download -c EPSG:3857 -r - -s 10 -dt uint16
Documentation
-------------
Documentation is hosted at `geedim.readthedocs.io `__.
License
-------
This project is licensed under the terms of the `Apache-2.0 License `__.
Credits
-------
- Tiled downloading was inspired by the `MIT licensed `__ `GEES2Downloader `__ project.
- Medoid compositing, and the accessor approach to extending the `GEE API `__, were adapted from `geetools `__ under terms of the
`MIT license `__.
- Sentinel-2 cloud 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