readme: ---
  license: apache-2.0
  tags:
  - UAV
  - Deadwood
  - detectron2
  ---
  
  ## Model description
  
  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.
  
  Example app is running on [https://huggingface.co/spaces/mayrajeo/maskrcnn-deadwood](https://huggingface.co/spaces/mayrajeo/maskrcnn-deadwood), which uses R101 backbone without TTA.
  
  ## Training data
  
  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
  
  Hiidenportti test set contains 241 non-overlapping 512x512 pixel image patches, extracted from 5 scenes that cover 11 circular field plots.
  
  |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
  from detectron2.data import build_detection_test_loader
  import cv2
  
  cfg = get_cfg()
  cfg.merge_from_file(<path_to_model_config>)
  cfg.OUTPUT_DIR = '<path_to_output>'
  cfg.MODEL.WEIGHTS = '<path_to_weights>'
  cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST = 0.5 # score threshold for detections
  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 afterward