ESA WorldCereal classification module

Overview

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 to run classification tasks in the cloud, by default the Copernicus Data Space Ecosystem (CDSE).

Users can leverage the system in a notebook environment through Terrascope 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 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, 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.
• 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

One of our demo notebooks can introduce to you quickly how to map crops with the Worldcereal system. There's two options to run these notebooks:

Option 1: Run on Terrascope

You can use a preconfigured environment on Terrascope 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.

• For a cropland map generation demo without any model training:

• For a crop type map generation demo with model training:

• For a demo on how to interact with the WorldCereal Reference Data Module (RDM):

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:

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 .[train,notebooks]

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:

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 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 file for details.

Acknowledgments

The WorldCereal project is funded by the European Space Agency (ESA) under grant no. 4000130569/20/I-NB.

WorldCereal's classification backbone makes use of the Presto model, originally implemented here. Without the groundbreaking work being done by Gabriel Tseng and the rest of the NASA Harvest team, both in the original Presto implementation as well as its adaptation for WorldCereal, this package would simply not exist in its present form 🙏.

The pre-configured Jupyter notebook environment in which users can train custom models and launch WorldCereal jobs is provided by Terrascope, the Belgian Earth observation data space, managed by VITO Remote Sensing on behalf of the Belgian Science Policy Office

How to cite

If you use WorldCereal resources in your work, please cite it as follows:

@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},
}