Update README.md

README.md

@@ -8,27 +8,46 @@ tags:
 
 ## Model description
 
-This model is trained for detecting both standing and fallen deadwood from UAV RGB images. More thorough description is available on [https://mayrajeo.github.io/maskrcnn-deadwood](https://mayrajeo.github.io/maskrcnn-deadwood).
+These models were trained for detecting both standing and fallen deadwood from UAV RGB images. All model configurations and weights here are fine-tuned from models available in [Detectron2 Model Zoo](https://github.com/facebookresearch/detectron2/blob/main/MODEL_ZOO.md).
+
+The models are trained on 512x512px RGB image patches with spatial resolution between 3.9cm and 4.3 cm and with hand-annotated deadwood data based on visual inspection. The location of training dataset is in the vicinity of Hiidenportti national, Sotkamo, Finland, and the images were acquired during leaf-on season, on 16. and 17.7.2019. Most likely the models are most suitable to use with imagery from leaf-on season and with similar ground sampling distance.
 
 ## Training data
 
-The model was trained on expert-annotated deadwood data, acquired on during leaf-on season 16.-17.7.2019 from Hiidenportti, Sotkamo, Eastern-Finland. The ground resolution for the data varied between 3.9 and 4.4cm. In addition, the model was tested with data collected from Evo, Hämeenlinna, Southern-Finland, acquired on 11.7.2018. The data from Evo was used only for testing the models. 
+These models were trained on expert-annotated deadwood data, acquired on during leaf-on season 16.-17.7.2019 from Hiidenportti, Sotkamo, Eastern-Finland. The ground resolution for the data varied between 3.9 and 4.4cm. In addition, the model was tested with data collected from Evo, Hämeenlinna, Southern-Finland, acquired on 11.7.2018. The data from Evo was used only for testing the models. 
+
+## Results
+
+Patch-level data are non-overlapping 512x512 pixel tiles extracted from larger virtual plots. The results presented here are the run with test-time augmentation.
+
+Scene-level data are the full virtual plots extracted from the full images. For Hiidenportti, the virtual plot sizes vary between 2560x2560px and 8192x4864px. These patches contain also non-annotated buffer areas in order to extract the complete annotated area. For Sudenpesänkangas, all 71 scenes are 100x100 meters (2063x2062) pixels, and during inference they are extracted from the full mosaic with enough buffer to cover the full area. The results presented here are run for 512x512 pixel tiles with 256 px overlap, with both edge filtering and mask merging described in the workflow.
+
+### Hiidenportti test set
 
-## Metrics
+Hiidenportti test set contains 241 non-overlapping 512x512 pixel image patches, extracted from 5 scenes that cover 11 circular field plots.
 
-|Metric|Hiidenportti|Evo|
-|------|------------|---|
-|Patch AP50|0.704|0.519|
-|Patch AP|0.366|0.252|
-|Patch AP groundwood|0.326|0.183|
-|Patch AP uprightwood|0.406|0.321|
-|Scene AP50|0.683|0.511|
-|Scene AP|0.341|0.236|
-|Scene AP groundwood|0.246|0.160|
-|Scene AP uprightwood|0.436|0.311|
+|Model|Patch AP50|Patch AP|Patch AP-groundwood|Patch AP-uprightwood|Scene AP50|Scene AP|Scene AP-groundwood|Scene AP-uprightwood|
+|----|-----------|--------|-------------------|--------------------|-----------|--------|-------------------|--------------------|
+|mask_rcnn_R_50_FPN_3x|0.654|0.339|0.316|0.363|0.640|0.315|0.235|0.396|
+|mask_rcnn_R_101_FPN_3x|**0.704**|**0.366**|0.326|**0.406**|**0.683**|**0.341**|0.246|**0.436**|
+|mask_rcnn_X_101_32x8d_FPN_3x|0.679|0.355|**0.333**|0.377|0.661|0.333|**0.255**|0.412|
+|cascade_mask_rcnn_R_50_FPN_3x|0.652|0.345|0.306|0.384|0.623|0.317|0.223|0.411|
+
+### Evo dataset
+
+Sudenpesänkangas dataset contains 798 on-overlapping 512x512 pixel image patches, extracted from 71 scenes.
+
+|Model|Patch AP50|Patch AP|Patch AP-groundwood|Patch AP-uprightwood|Scene AP50|Scene AP|Scene AP-groundwood|Scene AP-uprightwood|
+|----|-----------|--------|-------------------|--------------------|-----------|--------|-------------------|--------------------|
+|mask_rcnn_R_50_FPN_3x|0.486|0.237|0.175|0.299|0.474|0.221|0.152|0.290|
+|mask_rcnn_R_101_FPN_3x|**0.519**|**0.252**|**0.183**|0.321|**0.511**|**0.236**|**0.160**|**0.311**|
+|mask_rcnn_X_101_32x8d_FPN_3x|0.502|0.245|0.182|0.307|0.494|0.232|0.159|0.305|
+|cascade_mask_rcnn_R_50_FPN_3x|0.497|0.248|0.172|**0.323**|0.473|0.225|0.148|0.302|
 
 ## How to use
 
+### Running for small patches
+
 ```python
 from detectron2.engine import DefaultPredictor
 from detectron2.config import get_cfg
@@ -44,4 +63,35 @@ predictor = DefaultPredictor(cfg)
 
 img = cv2.imread('<path_to_image_patch>')
 outputs = predictor(image)
-```
+```
+
+### Running for larger scenes
+
+Running on larger scenes requires the following steps:
+
+1. Tiling the scenes into smaller image patches, optionally with overlap
+2. Running the model on these smaller patches
+3. Gathering the predictions into a single GIS data file
+4. Optionally post-processing the results
+
+[drone_detector](https://jaeeolma.github.io/drone_detector) package has helpers for this:
+
+```python
+from drone_detector.engines.detectron2.predict import predict_instance_masks
+
+predict_instance_masks(
+    path_to_model_config='<path_to_model_config>', # model config file
+    path_to_image='<path_to_image>', # which image to process
+    outfile='<name_for_predictions>.geojson', # where to save the results
+    processing_dir='temp', # directory for temporary files, deleted afterwards. Default: temp
+    tile_size=512, # image patch size in pixels, square patches. Default: 400
+    tile_overlap=256, # overlap between tiles. Default: 100
+    smooth_preds=False, # not yet implemented, at some points runs dilation+erosion to smooth polygons. Default: False
+    coco_set='<path_to_coco>', # the coco set the model was trained on to infer the class names. None defaults to dummy categories. Default: None
+    postproc_results=True # whether to discard masks in the edge regions of patches Default: False
+   )
+```
+
+Also, after installing the package, `predict_instance_masks_detectron2` can be used as CLI command with identical syntax.
+
+When provided models default to dummy classes, **1** is *standing deadwood* and **2** is *fallen deadwood*.