JernejPuc / eo-workshop

Example of machine learning in Earth observation

eo-learn workshop: machine learning in land cover classification with multispectral satellite imagery

This workshop focuses on a particular problem in the field of Earth observation (EO), with the aim of showcasing the eo-learn Python library.

It is based on one of the examples from the developer's public repository and simulates a full processing pipeline.

General instructions before starting the workshop are written below. The material has been prepared for an online event by the Faculty of mathematics and physics, University of Ljubljana, but you can run through it by yourself by following the notebooks in this repository.

Minimum requirements

Working with satellite imagery can be inherently challenging due to large amounts of data that needs to be processed. As this is only an example, the data is more manageable, although memory-related issues can still arise. While the contents have been successfully tested on a Linux machine with only 4 GB of RAM, it is recommended that you use a machine with more RAM at your disposal.

Set-up

eo-learn can be installed through conda or pip.

Using Anaconda is recommended, as it is generally convenient for scientific computing and data science. In any case, a 64-bit Python environment of version >=3.6 is required.

On Linux, it is recommended that you first install the following system packages (per the build instructions):

$ sudo apt-get install -y libgdal-dev
$ sudo apt-get install graphviz
$ sudo apt-get install proj-bin
$ sudo apt-get install gcc
$ sudo apt-get install libproj-dev

Installing with conda

Install Anaconda by following the instructions for your operating system. If already installed, you may want to update it with:

$ conda update
$ conda update conda
$ conda update conda-build

Create and activate an isolated environment with:

$ conda create --name myenv
$ conda activate myenv

eo-learn can then be installed from conda-forge as follows:

$ conda config --add channels conda-forge
$ conda install -c conda-forge eo-learn

Note: On Windows, at least, you may experience some issues relating to the libssl-1_1-x64.dll and libcrypto-1_1.dll files:

• If prevented from updating or downloading new packages, the solution may be to overwrite the instance of libssl-1_1-x64.dll in Anaconda3\Library\bin with the instance from Anaconda3\DLLs.
• If encountering "ImportError: DLL load failed while importing _ssl: The specified module could not be found.", for example, when running $ jupyter notebook or $ python -c "import ssl; print('ok')" from your environment, the solution may be to copy the libcrypto-1_1.dll and libssl-1_1.dll files from Anaconda3\Library\bin to Anaconda3\envs\myenv\DLLs.

Installing with pip

You can install and create an isolated environment by running:

$ pip install virtualenv
$ python -m venv myenv

The environemnt can be activated by running $ myenv\Scripts\activate.bat on Windows and $ source myenv/bin/activate otherwise.

Once activated, install eo-learn with:

$ pip install eo-learn

Note: On Windows, if issues are encountered that may be traced to the gdal, rasterio, shapely, fiona, or cartopy packages, you may need to install them from the Unofficial Windows wheels repository, as per the official installation instructions.

Other packages

If Jupyter Notebook was not installed during the process, you can follow the official installation instructions. Once installed, additional ipywidgets need to be installed and activated, so that specific elements can be properly displayed.

Using conda:

$ conda install -c conda-forge ipywidgets

Using pip:

$ pip install ipywidgets
$ jupyter nbextension enable --py widgetsnbextension --sys-prefix

When going through the notebooks, ipywidgets may cause some warnings to be raised. These can be ignored:

[IPKernelApp] ERROR | No such comm target registered: hv-extension-comm
[IPKernelApp] WARNING | No such comm: hv-extension-comm

Finally, eo-learn should already include lightgbm, an implementation of Gradient Boosting Decision Trees, which we will be using for this example. If you are experiencing problems during installation, consult the LightGBM installation guide.

Downloading the materials

Download this repository by clicking the Clone or download button at the top of the page.

To confirm that everything has installed correctly, you can navigate to the directory, where you have extracted the repository to, run $ jupyter notebook within your environment, and skim through notebook 2. Afterwards, lightgbm installation can be verified with $ python -c "import lightgbm; print('ok')".

The data required for the rest of the workshop can be downloaded from http://eo-learn.sentinel-hub.com.s3.eu-central-1.amazonaws.com/eow_material.zip (~1.2 GB).

Contact

For any questions or issues related to the workshop, you can raise an issue within this repository or send me an e-mail.

If you have questions regarding eo-learn itself or its use cases, you are welcome to send your feedback to its authors, the EO Research team at Sinergise, by:

• raising an issue on GitHub,
• sending an e-mail,
• opening a topic on the Sentinel Hub forum, or
• using any other of the established Sentinel Hub communication channels.