geefcc


Namegeefcc JSON
Version 0.1.3 PyPI version JSON
download
home_pagehttps://ecology.ghislainv.fr/geefcc
SummaryForest cover change from Google Earth Engine
upload_time2024-06-19 23:13:21
maintainerNone
docs_urlNone
authorGhislain Vieilledent
requires_python>=3.6
licenseGPLv3
keywords deforestation tropical forests forest cover change map google earth engine
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ..
   # ==============================================================================
   # 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"
}
        
Elapsed time: 0.25302s