diff --git a/README.md b/README.md index d552e8e2..4db54284 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,111 @@ -# WorldCereal classification module -[![DOI](https://zenodo.org/badge/621251443.svg)](https://zenodo.org/badge/latestdoi/621251443) +# ESA WorldCereal classification module +[![Tests](https://github.com/WorldCereal/worldcereal-classification/actions/workflows/ci.yaml/badge.svg)](https://github.com/WorldCereal/worldcereal-classification/actions/workflows/ci.yaml) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![DOI](https://img.shields.io/badge/DOI-10.5194/essd--15--5491--2023-blue)](https://doi.org/10.5194/essd-15-5491-2023) + [![Terrascope Environment](https://img.shields.io/badge/try%20on-Terrascope-blue)](https://terrascope-url) [![Documentation](https://img.shields.io/badge/docs-WorldCereal%20Documentation-blue)](https://worldcereal.github.io/worldcereal-documentation/) [![Discuss Forum](https://img.shields.io/badge/discuss-forum-ED1965?logo=discourse&logoColor=white)](https://forum.esa-worldcereal.org/) -This repository contains the code for running the WorldCereal classification module. -|:exclamation: Note that this package is actively undergoing significant updates. For the version accompanying the paper below, [please check this release](https://github.com/WorldCereal/worldcereal-classification/tree/v1.1.1). | -|:-----------------------------------------| +

+ + logo + +

+## Overview -Launch the _beta_ version of a V1 version of the new system: +**WorldCereal** is a Python package designed for generating cropland and crop type maps at a wide range of spatial scales, leveraging satellite and auxiliary data, and state-of-the-art classification workflows. It uses [openEO](https://openeo.org/) to run classification tasks in the cloud, by default the [Copernicus Data Space Ecosystem (CDSE)](https://dataspace.copernicus.eu/). -[![Binder](https://replay.notebooks.egi.eu/badge_logo.svg)](https://replay.notebooks.egi.eu/v2/gh/WorldCereal/worldcereal-binder/main?urlpath=git-pull%3Frepo%3Dhttps%253A%252F%252Fgithub.com%252FWorldCereal%252Fworldcereal-classification%26urlpath%3Dlab%252Ftree%252Fworldcereal-classification%252Fnotebooks%252Fsystem_v1_demo.ipynb%26branch%3Dsystem-v1-demo) +Users can leverage the system in a notebook environment through [Terrascope](https://terrascope.be/en) or set up the environment locally using the provided installation options. +In order to run classification jobs on CDSE, users can get started with [**monthly free openEO processing credits**](https://documentation.dataspace.copernicus.eu/Quotas.html) by registering on the CDSE platform. Additional credits can be purchased, or users may soon be able to request them through the **ESA Network of Resources**. + +## Features + +- **Scalable**: Generate maps at a wide range of spatial scales. +- **Cloud-based Processing**: Leverages openEO to run classifications in the cloud. +- **Powerful classification pipeline**: WorldCereal builds upon [**Presto**](https://arxiv.org/abs/2304.14065), a pretrained transformer-based model, leveraging global self-supervised learning of multimodal input timeseries, leading to better accuracies and higher generalizability in space and time of downstream crop classification models. The Presto backbone of WorldCereal classification pipelines is developed [here](https://github.com/WorldCereal/presto-worldcereal). +- **Customizable**: Users can pick any region or temporal range and apply either default models or train their own and produce custom maps, interacting with publicly available training data. +- **Easy to Use**: Integrates into Jupyter notebooks and other Python environments. + +## Quick Start + +#### Option 1: Run on Terrascope + +You can use a preconfigured environment on [**Terrascope**](https://terrascope.be/en) to run the workflows in a Jupyter notebook environment. Just register as a new user on Terrascope or use one of the supported EGI eduGAIN login methods to get started. + +[![Terrascope Environment](https://img.shields.io/badge/run%20on-Terrascope-blue)](https://terrascope-url) + +#### Option 2: Install Locally + +If you prefer to install the package locally, you can create the environment using **Conda** or **pip**. + +First clone the repository: +```bash +git clone https://github.com/WorldCereal/worldcereal-classification.git +cd worldcereal-classification +``` +Next, install the package locally: +- for Conda: `conda env create -f environment.yml` +- for Pip: `pip install .` + +## Usage Example +In it's most simple form, a cropland mask can be generated with just few lines of code, triggering an openEO job on CDSE and downloading the result locally: + +```python +from openeo_gfmap import BoundingBoxExtent, TemporalContext +from worldcereal.job import generate_map + +# Specify the spatial extent +spatial_extent = BoundingBoxExtent( + west=44.432274, + south=51.317362, + east=44.698802, + north=51.428224, + epsg=4326 +) + +# Specify the temporal extent (this has to be one year) +temporal_extent = TemporalContext('2022-11-01', '2023-10-31') + +# Launch processing job (result will automatically be downloaded) +results = generate_map(spatial_extent, temporal_extent, output_dir='.') +``` + +## Documentation + +Comprehensive documentation is available at the following link: https://worldcereal.github.io/worldcereal-documentation/ + +## Support +Questions, suggestions, feedback? Use [our forum](https://forum.esa-worldcereal.org/) to get in touch with us and the rest of the community! + +## License + +This project is licensed under the terms of the MIT License. See the [LICENSE](LICENSE) file for details. + +## Acknowledgments + +The WorldCereal project is funded by the [European Space Agency (ESA)](https://www.esa.int/) under grant no. 4000130569/20/I-NB. + +The pre-configured Jupyter notebook environment in which users can train custom models and launch WorldCereal jobs is provided by [Terrascope](https://terrascope.be/en), the Belgian Earth observation data space, managed by [VITO Remote Sensing](https://remotesensing.vito.be/) on behalf of the [Belgian Science Policy Office](https://www.belspo.be/belspo/index_en.stm) + +## How to cite + +If you use WorldCereal resources in your work, please cite it as follows: + +```bibtex + +@article{van_tricht_worldcereal_2023, + title = {{WorldCereal}: a dynamic open-source system for global-scale, seasonal, and reproducible crop and irrigation mapping}, + volume = {15}, + issn = {1866-3516}, + shorttitle = {{WorldCereal}}, + url = {https://essd.copernicus.org/articles/15/5491/2023/}, + doi = {10.5194/essd-15-5491-2023}, + number = {12}, + urldate = {2024-03-01}, + journal = {Earth System Science Data}, + author = {Van Tricht, Kristof and Degerickx, Jeroen and Gilliams, Sven and Zanaga, Daniele and Battude, Marjorie and Grosu, Alex and Brombacher, Joost and Lesiv, Myroslava and Bayas, Juan Carlos Laso and Karanam, Santosh and Fritz, Steffen and Becker-Reshef, Inbal and Franch, Belén and Mollà-Bononad, Bertran and Boogaard, Hendrik and Pratihast, Arun Kumar and Koetz, Benjamin and Szantoi, Zoltan}, + month = dec, + year = {2023}, + pages = {5491--5515}, +} +``` -*Van Tricht, K., Degerickx, J., Gilliams, S., Zanaga, D., Battude, M., Grosu, A., Brombacher, J., Lesiv, M., Bayas, J. C. L., Karanam, S., Fritz, S., Becker-Reshef, I., Franch, B., Mollà-Bononad, B., Boogaard, H., Pratihast, A. K., & Szantoi, Z. (2023). WorldCereal: A dynamic open-source system for global-scale, seasonal, and reproducible crop and irrigation mapping. Earth System Science Data Discussions, 1–36. https://doi.org/10.5194/essd-2023-184* diff --git a/SEASONS.md b/SEASONS.md deleted file mode 100644 index 8589612f..00000000 --- a/SEASONS.md +++ /dev/null @@ -1,64 +0,0 @@ -This document describes how the WorldCereal system is triggered in the different cereal and maize seasons. Definition of the seasons is as follows: - - `tc-wintercereals` is the global "winter wheat" season which considers winter-planted wheat. This does not consider optional dormancy requirements nor wheat variety. Therefore, it is considered the main wheat season anywhere in the world. - - `tc-maize-main` is the main "maize" season, although in some regions of the world (parts of the Northern Hemisphere) this season also covers spring-planted wheat ("spring wheat"). This season therefore targets maize globally, and additionally spring wheat in dedicated regions. - - `tc-maize-second` is an optional second "maize" season occurring in some parts of the world. There will be no wheat mapping in this season. - -The temporary crops layer, which is used as a mask for all crop type, active marker and irrigation products, is typically generated after the end of the LATEST season within a given reference year and AEZ. So production of the temporary crops layer can coincide with the tc-wintercereals, tc-maize-main and tc-maize-second season depending on the timing of eah of these seasons within the AEZ. - -Based on these definitions, the triggers, periods considered, and detector models are described below. - -## Season / Detector Mapping: - -### Winter wheat triggers - -| `tc-wintercereals` trigger | -| -------------------------- | - -| Product | Period | Detector | Model | Remarks | -| ---------------------- | :----------------------------------------: | ---------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------: | -| Temporary crops | [season_end - 1 year, season_end] | Temporary crops detector | [WorldCerealPixelCatBoost_temporarycrops](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v750/cropland_detector_WorldCerealPixelCatBoost_v750-realms) | :exclamation: Only when this season is the LAST season to end in the reference year | -| Winter cereals | [season_start - buffer, season_end] | Wintercereals detector | [WorldCerealPixelCatBoost_wintercereals](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v751/wintercereals_detector_WorldCerealPixelCatBoost_v751/config.json) | - | -| Active cropland marker | [season_start - buffer, season_end] | Season detector | None | - | -| Irrigation | [season_start - buffer, season_end] | Irrigation detector | [WorldCerealPixelCatBoost_irrigation](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v420/irrigation_detector_WorldCerealPixelCatBoost_v420/config.json) | - | - - -### Maize triggers - -| `tc-maize-main` trigger | -| ----------------- | - -| Product | Period | Detector | Model | Remarks | -| ---------------------- | :-----------------------------------------: | ----------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------: | -| Temporary crops | [season_end - 1 year, season_end] | Temporary crops detector | [WorldCerealPixelCatBoost_temporarycrops](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v750/cropland_detector_WorldCerealPixelCatBoost_v750-realms) | :exclamation: Only when this season is the LAST season to end in the reference year | -| Maize | [season_start - buffer, season_end] | Maize detector | [WorldCerealPixelCatBoost_maize](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v751/maize_detector_WorldCerealPixelCatBoost_v751/config.json) | - | -| Spring cereals | [season_start - buffer, season_end] | Spring cereals detector | [WorldCerealPixelCatBoost_springcereals](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v751/springcereals_detector_WorldCerealPixelCatBoost_v751/config.json) | :exclamation: Only when AEZ `trigger_sw = 1` | -| Active cropland marker | [season_start - buffer, season_end] | Season detector | None | - | -| Irrigation | [season_start - buffer, season_end] | Irrigation detector | [WorldCerealPixelCatBoost_irrigation](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v420/irrigation_detector_WorldCerealPixelCatBoost_v420/config.json) | - | - - -| `tc-maize-second` trigger | -| ----------------- | - -| Product | Period | Detector | Model | Remarks | -| ---------------------- | :-----------------------------------------: | ------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------: | -| Temporary crops | [season_end - 1 year, season_end] | Temporary crops detector | [WorldCerealPixelCatBoost_temporarycrops](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v750/cropland_detector_WorldCerealPixelCatBoost_v750-realms) | :exclamation: Only when this season is the LAST season to end in the reference year | -| Maize | [season_start - buffer, season_end] | Maize detector | [WorldCerealPixelCatBoost_maize](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v751/maize_detector_WorldCerealPixelCatBoost_v751/config.json) | - | -| Active cropland marker | [season_start - buffer, season_end] | Season detector | None | - | -| Irrigation | [season_start - buffer, season_end] | Irrigation detector | [WorldCerealPixelCatBoost_irrigation](https://artifactory.vgt.vito.be:443/auxdata-public/worldcereal/models/WorldCerealPixelCatBoost/v420/irrigation_detector_WorldCerealPixelCatBoost_v420/config.json) | - | - - - -## Required processing buffers -While the system takes into account the globally prescribed seasonality of wheat and maize, actual processing needs to include a buffer before the exact start of each season. -The purpose of the buffer is to capture a potential slight shift in the growing season of a particular year. Especially a backward shift would impact GDD normalization and detection of phenological features. - -The default buffer (in days) prior to the prescribed season start is the amount of days that will be subtracted from the original season start and become the new season start as used by the system: -``` -SEASON_BUFFER = { - 'tc-wintercereals': 15, - 'tc-maize-main': 15, - 'tc-maize-second': 15, - 'tc-annual': 0, - 'custom': 0 -} -``` diff --git a/assets/worldcereal_logo.jpg b/assets/worldcereal_logo.jpg new file mode 100644 index 00000000..fa430e98 Binary files /dev/null and b/assets/worldcereal_logo.jpg differ diff --git a/environment.yml b/environment.yml index 0f98125c..ce60860b 100644 --- a/environment.yml +++ b/environment.yml @@ -1,4 +1,4 @@ -name: worldcereal-official +name: worldcereal channels: - pytorch - conda-forge