..
# ==============================================================================
# author :Ghislain Vieilledent
# email :ghislain.vieilledent@cirad.fr
# web :https://ecology.ghislainv.fr
# license :GPLv3
# ==============================================================================
.. image:: https://ecology.ghislainv.fr/geefcc/_static/logo-geefcc.svg
:align: right
:target: https://ecology.ghislainv.fr/geefcc
:alt: Logo geefcc
:width: 140px
``geefcc`` Python package
*************************
|Python version| |PyPI version| |GitHub Actions| |License| |Zenodo|
Overview
========
The ``geefcc`` Python package can be used to make forest cover change (fcc) maps from Google Earth Engine (GEE) and download them locally. Forest cover change maps are obtained from two global tree/forest cover change products: `Global Forest Change <https://glad.earthengine.app/view/global-forest-change>`_ or `Tropical Moist Forests <https://forobs.jrc.ec.europa.eu/TMF>`_. These two products are derived from the Landsat satellite image archive and provide tree/forest cover data at 30 m resolution.
.. image:: https://ecology.ghislainv.fr/geefcc/_static/banner_geefcc.png
:align: center
:target: https://ecology.ghislainv.fr/geefcc
:alt: banner_geefcc
The ``geefcc`` package depends on the `xee <https://github.com/google/Xee>`_ Python package, which allows opening GEE datasets locally without exporting data to GEE assets or Google Drive. The user only has to specify an area of interest (aoi), either with an extent, a polygon vector file, or a country iso code (e.g. PER for Peru), and the years defining the time periods considered for the forest cover change (e.g. 2000, 2010, 2020). For the Global Forest Change product, the users also has to specify a tree cover threshold to define the forest (e.g. 75%).
.. note::
The current version of the package uses GFC data up to year 2023 (`GFC v1.11 2023 <https://developers.google.com/earth-engine/datasets/catalog/UMD_hansen_global_forest_change_2023_v1_11>`_) and TMF data up to year 2022 (`TMF v1 2022 <https://forobs.jrc.ec.europa.eu/TMF/data>`_) so that years for computing forest cover change can be in the interval 2001--2024 for GFC (GFC does not provide loss for the year 2000) and 2000--2023 for TMF. Forest cover is given on the 1\ :sup:`st` of January for each year. The current version of the package only considers **deforestation as change** and **not forest gain or regrowth**.
Prerequisites
=============
Access to Google Earth Engine
-----------------------------
To use the ``geefcc`` Python package, you need a Google account and an `access to Earth Engine <https://developers.google.com/earth-engine/guides/access#a-role-in-a-cloud-project>`_ either via a Google Cloud project that's registered to use Earth Engine or via an individually signed-up account. Please follow this link `to register for Earth Engine <https://code.earthengine.google.com/register>`_.
You must always initialize GEE before using ``geefcc`` functions specifying a Google Cloud project name and `Earth Engine high-volume endpoint <https://developers.google.com/earth-engine/cloud/highvolume>`_:
.. code-block:: python
ee.Initialize(
credentials=credentials,
project=project,
opt_url="https://earthengine-highvolume.googleapis.com"
)
GDAL
----
GDAL must be installed on your system.
To install GDAL on Windows, use the `OSGeo4W <https://trac.osgeo.org/osgeo4w/>`_ network installer. OSGeo4W is a binary distribution of a broad set of open source geospatial software for Windows environments (Windows 11 down to 7). Select *Express Install* and install GDAL. Several Gb of space will be needed on disk to install this programs. This will also install *OSGeo4W Shell* to execute command lines.
To install GDAL on other systems, use your package manager, for example ``apt`` for Debian/Ubuntu Linux distributions.
.. code:: shell
sudo apt update
sudo apt install gdal-bin libgdal-dev
After installing GDAL, you can test the installation by running ``gdalinfo --version`` in the command prompt or terminal, which should display the installed GDAL version.
GADM website
------------
The ``geefcc`` package downloads country administrative borders from the `GADM <https://gadm.org/data.html>`_ website. From time to time, their server is not responding. In case of problem with downloading country borders, check directly on the GADM website that data can be downloaded manually to be sure that the problem is coming from ``geefcc``.
Installation
============
The easiest way to install the ``geefcc`` Python package is via `pip <https://pip.pypa.io/en/stable/>`_ in the *OSGeo4W Shell* for Windows or in a virtual environment for Linux.
For Linux, create and activate a virtual environment before installing ``geefcc`` with ``pip``:
.. code-block:: shell
cd ~
# Create a directory for virtual environments
mkdir venvs
# Create the virtual environment with venv
python3 -m venv ~/venvs/venv-geefcc
# Activate (start) the virtual environment
source ~/venvs/venv-geefcc/bin/activate
Install Python dependencies and ``geefcc`` in the *OSGeo4W Shell* or in the newly created virtual environment:
.. code-block:: shell
# Upgrade pip, setuptools, and wheel
python3 -m pip install --upgrade pip setuptools wheel
# Install numpy
python3 -m numpy
# Install gdal Python bindings (the correct version)
python3 -m pip install gdal==$(gdal-config --version)
# Install geefcc. This will install all other dependencies
python3 -m pip install geefcc
If you want to install the development version of ``geefcc``, replace the last line with:
.. code-block:: shell
python3 -m pip install https://github.com/ghislainv/geefcc/archive/master.zip
To deactivate and delete the virtual environment:
.. code-block:: shell
deactivate
rm -R ~/venvs/venv-geefcc # Just remove the repository
In case of problem while installing GDAL Python bindings, try the following command:
.. code-block:: shell
python3 -m pip install --no-cache-dir --force-reinstall gdal==$(gdal-config --version)
Contributing
============
The ``geefcc`` Python package is Open Source and released under
the `GNU GPL version 3 license
<https://ecology.ghislainv.fr/geefcc/license.html>`__. Anybody
who is interested can contribute to the package development following
our `Community guidelines
<https://ecology.ghislainv.fr/geefcc/contributing.html>`__. Every
contributor must agree to follow the project's `Code of conduct
<https://ecology.ghislainv.fr/geefcc/code_of_conduct.html>`__.
.. |Python version| image:: https://img.shields.io/pypi/pyversions/geefcc?logo=python&logoColor=ffd43b&color=306998
:target: https://pypi.org/project/geefcc
:alt: Python version
.. |PyPI version| image:: https://img.shields.io/pypi/v/geefcc
:target: https://pypi.org/project/geefcc
:alt: PyPI version
.. |GitHub Actions| image:: https://github.com/ghislainv/geefcc/workflows/PyPkg/badge.svg
:target: https://github.com/ghislainv/geefcc/actions
:alt: GitHub Actions
.. |License| image:: https://img.shields.io/badge/licence-GPLv3-8f10cb.svg
:target: https://www.gnu.org/licenses/gpl-3.0.html
:alt: License GPLv3
.. |Zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.11258039.svg
:target: https://doi.org/10.5281/zenodo.11258039
:alt: Zenodo
Raw data
{
"_id": null,
"home_page": "https://ecology.ghislainv.fr/geefcc",
"name": "geefcc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "deforestation tropical forests forest cover change map google earth engine",
"author": "Ghislain Vieilledent",
"author_email": "ghislain.vieilledent@cirad.fr",
"download_url": "https://files.pythonhosted.org/packages/fc/27/9ff407f2ea1836af139e82be9d97b7fc2fffce3e73ae338452f740f05894/geefcc-0.1.3.tar.gz",
"platform": null,
"description": "..\n # ==============================================================================\n # author :Ghislain Vieilledent\n # email :ghislain.vieilledent@cirad.fr\n # web :https://ecology.ghislainv.fr\n # license :GPLv3\n # ==============================================================================\n\n.. image:: https://ecology.ghislainv.fr/geefcc/_static/logo-geefcc.svg\n :align: right\n :target: https://ecology.ghislainv.fr/geefcc\n :alt: Logo geefcc\n :width: 140px\n\t \n``geefcc`` Python package\n*************************\n\n\n|Python version| |PyPI version| |GitHub Actions| |License| |Zenodo|\n\n\nOverview\n========\n\nThe ``geefcc`` Python package can be used to make forest cover change (fcc) maps from Google Earth Engine (GEE) and download them locally. Forest cover change maps are obtained from two global tree/forest cover change products: `Global Forest Change <https://glad.earthengine.app/view/global-forest-change>`_ or `Tropical Moist Forests <https://forobs.jrc.ec.europa.eu/TMF>`_. These two products are derived from the Landsat satellite image archive and provide tree/forest cover data at 30\u00a0m resolution.\n\n.. image:: https://ecology.ghislainv.fr/geefcc/_static/banner_geefcc.png\n :align: center\n :target: https://ecology.ghislainv.fr/geefcc\n :alt: banner_geefcc\n\nThe ``geefcc`` package depends on the `xee <https://github.com/google/Xee>`_ Python package, which allows opening GEE datasets locally without exporting data to GEE assets or Google Drive. The user only has to specify an area of interest (aoi), either with an extent, a polygon vector file, or a country iso code (e.g. PER for Peru), and the years defining the time periods considered for the forest cover change (e.g. 2000, 2010, 2020). For the Global Forest Change product, the users also has to specify a tree cover threshold to define the forest (e.g. 75%).\n\n.. note::\n The current version of the package uses GFC data up to year 2023 (`GFC v1.11 2023 <https://developers.google.com/earth-engine/datasets/catalog/UMD_hansen_global_forest_change_2023_v1_11>`_) and TMF data up to year 2022 (`TMF v1 2022 <https://forobs.jrc.ec.europa.eu/TMF/data>`_) so that years for computing forest cover change can be in the interval 2001--2024 for GFC (GFC does not provide loss for the year 2000) and 2000--2023 for TMF. Forest cover is given on the 1\\ :sup:`st` of January for each year. The current version of the package only considers **deforestation as change** and **not forest gain or regrowth**.\n\nPrerequisites\n=============\n\nAccess to Google Earth Engine\n-----------------------------\n\nTo use the ``geefcc`` Python package, you need a Google account and an `access to Earth Engine <https://developers.google.com/earth-engine/guides/access#a-role-in-a-cloud-project>`_ either via a Google Cloud project that's registered to use Earth Engine or via an individually signed-up account. Please follow this link `to register for Earth Engine <https://code.earthengine.google.com/register>`_.\n\nYou must always initialize GEE before using ``geefcc`` functions specifying a Google Cloud project name and `Earth Engine high-volume endpoint <https://developers.google.com/earth-engine/cloud/highvolume>`_:\n\n.. code-block:: python\n\n ee.Initialize(\n credentials=credentials,\n project=project,\n opt_url=\"https://earthengine-highvolume.googleapis.com\"\n )\n\nGDAL\n----\n\nGDAL must be installed on your system.\n\nTo install GDAL on Windows, use the `OSGeo4W <https://trac.osgeo.org/osgeo4w/>`_ network installer. OSGeo4W is a binary distribution of a broad set of open source geospatial software for Windows environments (Windows 11 down to 7). Select *Express Install* and install GDAL. Several Gb of space will be needed on disk to install this programs. This will also install *OSGeo4W Shell* to execute command lines.\n\nTo install GDAL on other systems, use your package manager, for example ``apt`` for Debian/Ubuntu Linux distributions.\n\n.. code:: shell\n\n sudo apt update\n sudo apt install gdal-bin libgdal-dev\n\nAfter installing GDAL, you can test the installation by running ``gdalinfo --version`` in the command prompt or terminal, which should display the installed GDAL version.\n\nGADM website\n------------\n \nThe ``geefcc`` package downloads country administrative borders from the `GADM <https://gadm.org/data.html>`_ website. From time to time, their server is not responding. In case of problem with downloading country borders, check directly on the GADM website that data can be downloaded manually to be sure that the problem is coming from ``geefcc``.\n\nInstallation\n============\n\nThe easiest way to install the ``geefcc`` Python package is via `pip <https://pip.pypa.io/en/stable/>`_ in the *OSGeo4W Shell* for Windows or in a virtual environment for Linux.\n\nFor Linux, create and activate a virtual environment before installing ``geefcc`` with ``pip``:\n\n.. code-block:: shell\n\n cd ~\n # Create a directory for virtual environments\n mkdir venvs\n # Create the virtual environment with venv\n python3 -m venv ~/venvs/venv-geefcc\n # Activate (start) the virtual environment\n source ~/venvs/venv-geefcc/bin/activate\n\nInstall Python dependencies and ``geefcc`` in the *OSGeo4W Shell* or in the newly created virtual environment:\n \n.. code-block:: shell\n \n # Upgrade pip, setuptools, and wheel\n python3 -m pip install --upgrade pip setuptools wheel\n # Install numpy\n python3 -m numpy\n # Install gdal Python bindings (the correct version)\n python3 -m pip install gdal==$(gdal-config --version)\n # Install geefcc. This will install all other dependencies\n python3 -m pip install geefcc\n\nIf you want to install the development version of ``geefcc``, replace the last line with:\n\n.. code-block:: shell\n\n python3 -m pip install https://github.com/ghislainv/geefcc/archive/master.zip\n\nTo deactivate and delete the virtual environment:\n\n.. code-block:: shell\n\t\t\n deactivate\n rm -R ~/venvs/venv-geefcc # Just remove the repository\n\nIn case of problem while installing GDAL Python bindings, try the following command:\n\n.. code-block:: shell\n\t\t\n python3 -m pip install --no-cache-dir --force-reinstall gdal==$(gdal-config --version)\n \nContributing\n============\n\nThe ``geefcc`` Python package is Open Source and released under\nthe `GNU GPL version 3 license\n<https://ecology.ghislainv.fr/geefcc/license.html>`__. Anybody\nwho is interested can contribute to the package development following\nour `Community guidelines\n<https://ecology.ghislainv.fr/geefcc/contributing.html>`__. Every\ncontributor must agree to follow the project's `Code of conduct\n<https://ecology.ghislainv.fr/geefcc/code_of_conduct.html>`__.\n \n.. |Python version| image:: https://img.shields.io/pypi/pyversions/geefcc?logo=python&logoColor=ffd43b&color=306998\n :target: https://pypi.org/project/geefcc\n :alt: Python version\n\n.. |PyPI version| image:: https://img.shields.io/pypi/v/geefcc\n :target: https://pypi.org/project/geefcc\n :alt: PyPI version\n\n.. |GitHub Actions| image:: https://github.com/ghislainv/geefcc/workflows/PyPkg/badge.svg\n :target: https://github.com/ghislainv/geefcc/actions\n :alt: GitHub Actions\n\t \n.. |License| image:: https://img.shields.io/badge/licence-GPLv3-8f10cb.svg\n :target: https://www.gnu.org/licenses/gpl-3.0.html\n :alt: License GPLv3\n\n.. |Zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.11258039.svg\n :target: https://doi.org/10.5281/zenodo.11258039\n :alt: Zenodo\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Forest cover change from Google Earth Engine",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://ecology.ghislainv.fr/geefcc",
"Homepage": "https://ecology.ghislainv.fr/geefcc",
"Source": "https://github.com/ghislainv/geefcc/",
"Traker": "https://github.com/ghislainv/geefcc/issues"
},
"split_keywords": [
"deforestation",
"tropical",
"forests",
"forest",
"cover",
"change",
"map",
"google",
"earth",
"engine"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a830cdfb4c09b6a12923cbe530a34172fb267e30a8a28a4a04ecaf4fcbf58002",
"md5": "7d3ee4157164d51a62dd99a6aafde926",
"sha256": "a271dd32736920be8f76eee8211018fa569f01700c109e0be758daec38c2c0a6"
},
"downloads": -1,
"filename": "geefcc-0.1.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d3ee4157164d51a62dd99a6aafde926",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 32857,
"upload_time": "2024-06-19T23:13:19",
"upload_time_iso_8601": "2024-06-19T23:13:19.728013Z",
"url": "https://files.pythonhosted.org/packages/a8/30/cdfb4c09b6a12923cbe530a34172fb267e30a8a28a4a04ecaf4fcbf58002/geefcc-0.1.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc279ff407f2ea1836af139e82be9d97b7fc2fffce3e73ae338452f740f05894",
"md5": "88a27cb992c03aa330c9b15542f7679c",
"sha256": "d27ad67bf78b96d945451f50b85862a1fddab423177ac7f1944172f65d1363f5"
},
"downloads": -1,
"filename": "geefcc-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "88a27cb992c03aa330c9b15542f7679c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 32396,
"upload_time": "2024-06-19T23:13:21",
"upload_time_iso_8601": "2024-06-19T23:13:21.533087Z",
"url": "https://files.pythonhosted.org/packages/fc/27/9ff407f2ea1836af139e82be9d97b7fc2fffce3e73ae338452f740f05894/geefcc-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-19 23:13:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ghislainv",
"github_project": "geefcc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "geefcc"
}
JSON
