Better README

Author: nickponline

README.md

@@ -7,38 +7,38 @@ This repository contains a description of the DroneDeploy Segmentation Dataset a
 
 ### Quickstart
 
+Follow these steps to train a model and run inference end-to-end:
+
 ```
-# clone this repository
 git clone https://github.com/dronedeploy/dd-ml-segmentation-benchmark.git
-cd dd-ml-segmentation-benchmark/
-# install requirements
+cd dd-ml-segmentation-benchmark
 pip3 install -r requirements.txt
-# optional: log in to W&B to see your training metrics,
-# track your experiments, and submit your models to the benchmark
-wandb login
-# train Fastai model
-python3 main.py
-# train Keras model
-python3 main_keras.py
 
-```
-
-### Training
+# optional: log in to W&B to track your experiements
+wandb login
 
-To start training a model on a small sample dataset run the following, once working you should use the *full dataset*  by changing `main.py`
+# train a Keras model
+python3 main_keras.py
 
-```
-pip3 install -r requirements.txt
+# train a Fastai model
 python3 main.py
 ```
 
-This will download the sample dataset and begin training a model. You can monitor training performance on [Weights and Biases](https://www.wandb.com/). Once training is complete inference will be performed on all test scenes and a number of prediction images with names like `123123_ABCABC-prediction.png` will be created. After the the images are created they will be scored. Here's what the prediction looks like, not bad for 50 lines of code but there is a lot of room for improvement:  
+This will download the sample dataset and begin training a model. You can monitor training performance on [Weights and Biases](https://www.wandb.com/). Once training is complete inference will be performed on all test scenes and a number of prediction images with names like `123123_ABCABC-prediction.png` will be created in the `wandb` directory. After the the images are created they will be scored. Here's what a prediction looks like, not bad for 50 lines of code but there is a lot of room for improvement:  
 
 ![Example](https://github.com/dronedeploy/dd-ml-segmentation-benchmark/raw/master/img/out.gif)
 
 ### Dataset Details
 
-The *full dataset* can be downloaded by changing a line in `main.py` this is the dataset that should be used for benchmarking. The dataset comprises a number of aerial scenes captured from drones. Each scene has a ground resolution of 10 cm per pixel. For each scene there is a corresponding "image", "elevation" and "label". The image is an RGB tif, the elevation is a single channel floating point .tif and the label is a PNG with 7 colors representing the 7 classes. Please see `index.csv` - inside the downloaded dataset - for a description of the quality of each labelled image and the distribution of the labels. To use the dataset you can split it into smaller chips (see `images2chips.py`). Here is an example of one of the labelled scenes:
+The dataset comprises a number of aerial scenes captured from drones. Each scene has a ground resolution of 10 cm per pixel. For each scene there is a corresponding "image", "elevation" and "label". These are located in the `images`, `elevation` and `labels` directory.
+
+The images an RGB tifs, the elevations are single channel floating point tifs (where each pixel value represents elevation in meters) and finally the labels are PNGs with 7 colors representing the 7 classes (documented below)
+
+In addition please see `index.csv` - inside the downloaded dataset folder - for a description of the quality of each labelled image and the distribution of the labels.
+
+To use a dataset for training it need to first be converted to chips (see `images2chips.py`). This will created an `images-chips` and `label-chips` directory which contains a number of `300x300` (by default) RGB images. The `label-chips` are also RGB but will be very low pixel intensities `[0 .. 7]` so will appear black as first glance. You can use the `color2class` and `category2mask` function to switch between the two label representations. 
+
+Here is an example of one of the labelled scenes:
 
 ![Example](https://github.com/dronedeploy/dd-ml-segmentation-benchmark/raw/master/img/15efe45820_D95DF0B1F4INSPIRE-label.png)
 
@@ -62,8 +62,8 @@ Color (Blue, Green, Red) to Class Name:
 ----
 The sample implementation is very basic and there is immediate opportunity to experiment with:
 - Data augmentation (`dataloader.py`)
-- Hyper- parameters (`train.py`)
-- Post-processing (`inference.py`)
+- Hyper- parameters (`train_*.py`)
+- Post-processing (`inference_*.py`)
 - Chip size (`images2chips.py`)
-- Model architecture (`train.py`)
+- Model architecture (`train_*.py`)
 - Elevation tiles are not currently used at all (`images2chips.py`)