GRAINet: Mapping grain size distributions in river beds from UAV images with convolutional neural networks

This is a demonstration to show how to run the training and testing code used to analyze the grain size distributions in river beds over entire gravel bars (Lang et al., 2020).

Along with the code, we release a small subset of the dataset used in the study, which is a single gravel bar (orthophoto) with 212 manually annotated image tiles. The full dataset cannot be published for commercial reasons, as it is owned by a private company (who also created it at their own cost).

Important note: The trained model resulting from this demo will not generalize as described in the paper.

Getting Started

Clone this repository to your local machine. In your terminal type:
```
git clone URL
```
Download the data from here.

Move the data folder into the GRAINet directory. The directory tree should look like this: GRAINet/data_GRAINet_demo/

Prerequisites

This code uses keras with a tensorflow backend. GDAL is used to predict for georeferenced orthophotos. The following instructions will guide you to install:

python3
jupyter
tensorflow
keras
gdal

Installing

We recommend to install python via anaconda and to create a new conda environment.

Install Anaconda and read the Anaconda tutorial
Create a new environment: conda create --name GRAINenv python=3.7.1
Activate the new conda environment (for conda 4.6 and later versions)
- Windows: conda activate GRAINenv
- Linux and macOS: conda activate GRAINenv
For versions prior to conda 4.6, use:
- Windows: activate GRAINenv
- Linux, macOS: source activate GRAINenv
--> now your terminal prompt should start with (GRAINenv)

Install the following packages in your activated GRAINenv:

conda install jupyter
conda install matplotlib
conda install keras=2.2.4
conda install h5py=2.9.0
conda install scikit-image

Install tensorflow with anaconda or follow the official tensorflow installation instructions (e.g. with pip) or check the anaconda installation instructions.
```
conda install tensorflow-gpu=1.13.1
```
Install GDAL with anaconda or follow the official GDAL installation instructions
```
conda install -c conda-forge gdal
```

Verify your installation

Run python in your conda GRAINenv. Then:

import keras
import tensorflow
import h5py
from osgeo import gdal

The code has been tested with the following versions:

keras.__version__
'2.2.4'
tensorflow.__version__
'1.13.1'
h5py.__version__
'2.9.0'

Run the notebook

Open the jupyter notebook:

jupyter notebook GRAINet_demo_dm_regression.ipynb

Citation

If you use this code please cite our paper:

Lang, Nico, Andrea Irniger, Agnieszka Rozniak, Roni Hunziker, Jan Dirk Wegner, and Konrad Schindler. "GRAINet: mapping grain size distributions in river beds from UAV images with convolutional neural networks." Hydrology and Earth System Sciences 25, no. 5 (2021): 2567-2597.

BibTex:

@article{lang2021grainet,
  title={GRAINet: mapping grain size distributions in river beds from UAV images with convolutional neural networks},
  author={Lang, Nico and Irniger, Andrea and Rozniak, Agnieszka and Hunziker, Roni and Wegner, Jan Dirk and Schindler, Konrad},
  journal={Hydrology and Earth System Sciences},
  volume={25},
  number={5},
  pages={2567--2597},
  year={2021},
  publisher={Copernicus GmbH}
}

langnico/GRAINet