deadtrees/README.md

DeadTrees

Description

Map dead trees from ortho photos. A Unet (semantic segmentation model) is trained on a ortho photo collection of Luxembourg (year: 2019). This repository contains the preprocessing pipeline, training scripts, models, and a docker-based demo app (backend: FastAPI, frontend: Streamlit).

Fig 1: Streamlit UI for interactive prediction of dead trees in ortho photos.

How to run

# clone project
git clone https://github.com/cwerner/deadtrees
cd deadtrees

# [OPTIONAL] create virtual environment (using venve, pyenv, etc.) and activate it. An easy way to get a base system configured is to use micromamba (a faster alternative to anaconda) and the fastchan channel to install the notoriously finicky pytorch base dependencies and cuda setup

wget -qO- https://micromamba.snakepit.net/api/micromamba/linux-64/latest | tar -xvj bin/micromamba

# init shell (~/micromamba in the following line is the location where envs are stored, could be somewhere else)
./bin/micromamba shell init -s bash -p ~/micromamba
source ~/.bashrc

micromamba create -p deadtrees python=3.9 -c conda-forge
micromamba activate deadtrees
# install cuda-compiled foundational packages (force it for pytorch since the auto-detection often fails)
micromamba install "pytorch=*=*cuda*" torchvision albumentations -c fastchan -c conda-forge

# install requirements (basic requirements):
pip install -e . 

# [OPTIONAL] install extra requirements for training:
pip install -e ".[train]"

# [OPTIONAL] install extra requirements to preprocess the raw data
# (instead of reading preprocessed data from S3):
pip install -e ".[preprocess]"

# [ALTERNATIVE] install all subpackages:
pip install -e ".[all]"

Download the dataset from S3 (output of the createdataset dvc stage)

dvc pull createdataset

Specify the location of the training dataset on your system by creating the file .env with the following syntax:

export TRAIN_DATASET_PATH="/path_to_my_repos/deadtrees/data/dataset/train"

Train model with default configuration (you can adjust the training config on the commandline or by editing the hydra yaml files in configs):

python run.py