From 50d03c140217ab2fa9da1e492a3c2750dc6fba4d Mon Sep 17 00:00:00 2001 From: James Ball <37094972+PatBall1@users.noreply.github.com> Date: Wed, 17 Jan 2024 13:46:19 +0000 Subject: [PATCH] Jb/multi (#135) * Remove large files and edits to readmes * readme * Bump version 1.0.8 --- README.md | 4 ++-- docs/source/index.rst | 9 +++++---- docs/source/tutorial.rst | 19 ++++++++++++++----- docs/source/tutorial_multi.rst | 18 ++++++++++++++++++ model_garden/220723_withParacouUAV.pth | 3 --- model_garden/230103_randresize_full.pth | 3 --- model_garden/README.md | 10 ++++++---- .../urban_trees_Cambridge_20230630.pth | 3 --- 8 files changed, 45 insertions(+), 24 deletions(-) create mode 100644 docs/source/tutorial_multi.rst delete mode 100644 model_garden/220723_withParacouUAV.pth delete mode 100644 model_garden/230103_randresize_full.pth delete mode 100644 model_garden/urban_trees_Cambridge_20230630.pth diff --git a/README.md b/README.md index a1f5d759..f180b961 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,8 @@ Detectree2是一个基于Mask R-CNN的自动树冠检测与分割的Python包。 | :---: | :--- |

-> [!WARNING] -> Due to an influx of new users we have been hitting bandwidth limits. This is primarily from the file size of the pre-trained models. If you are using these models please aim to save them locally and point to them when you need them rather than downloading them each time they are required. We will move to a more bandwidth friendly set up soon. In the meantime, if installing the package is failing please raise it as an issue or notify me directly on ball.jgc@gmail.com. +> [!NOTE] +> To save bandwidth trained models have been moved to [Zenodo](https://zenodo.org/records/10522461). Download models directly with `wget` or equivalent. ## Citation diff --git a/docs/source/index.rst b/docs/source/index.rst index c3cc369f..255eefc3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,10 +6,11 @@ Detectree2 ========== -`Detectree2 `_, based on the `Detectron2 `_ -Mask R-CNN architecture, locates trees in aerial images. -It has been designed to delineate trees in challenging dense tropical forests for a range of -ecological applications. Here is an example image of the predictions made by Detectree2. +`Detectree2 `_, based on the +`Detectron2 `_ Mask R-CNN +architecture, locates trees in aerial images. It has been designed to delineate +trees in challenging dense tropical forests for a range of ecological +applications. Below is an example image of the predictions made by Detectree2. .. .. image:: ../../report/figures/plot_13_285520_583300.jpg .. :width: 400 diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index c74dc6b2..9c9e9bed 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -1,7 +1,12 @@ Tutorial ======== -A tutorial for: +This tutorial goes through the steps of single class (tree) detection and +delineation. A guide to multiclass prediction (e.g. species mapping, +disease mapping) is coming soon. Example data that can be used in +this tutorial is available `here `_. + +The key steps are: 1. Preparing data 2. Training models @@ -19,8 +24,11 @@ To train a model you will need an orthomosaic (as ``.tif``) and corresponding tree crown polgons that are readable by Geopandas (e.g. ``.gpkg``, ``.shp``). For the best results, manual crowns should be supplied as dense clusters rather than -sparsely scattered across in the landscape. See below for an example of the -required input crowns and image. +sparsely scattered across in the landscape. The method is designed to make +predictions across the entirety of the supplied tiles and assumes training +tiles are comprehensively labelled. If the network is shown scenes that are +incompletely labelled, it may replicate that in its predictions. See +below for an example of the required input crowns and image. .. image:: ../../report/figures/Danum_example_data.png :width: 400 @@ -29,7 +37,8 @@ required input crowns and image. | If you would just like to make predictions on an orthomosaic with a pre-trained -model from the ``model_garden``, skip to part 4 (Generating landscape predictions). +model from the ``model_garden``, skip to part 4 (Generating landscape +predictions). Preparing data @@ -233,7 +242,7 @@ especially useful if you only have limited training data available. To retrieve .. code-block:: python - !wget https://github.com/PatBall1/detectree2/raw/master/model_garden/230103_randresize_full.pth + !wget https://zenodo.org/records/10522461/files/230103_randresize_full.pth Then set up the configurations as before but with the trained model also supplied: diff --git a/docs/source/tutorial_multi.rst b/docs/source/tutorial_multi.rst new file mode 100644 index 00000000..21b1fc72 --- /dev/null +++ b/docs/source/tutorial_multi.rst @@ -0,0 +1,18 @@ +Tutorial (multiclass) +===================== + +This tutorial goes through the steps of multiclass detection and +delineation (e.g. species mapping, disease mapping). A guide to single +class prediction is available +`here `_. The multiclass +process is more complicated than single class prediction as the classes need to +be correctly encoded in the data. + +The key steps are: + +1. Preparing data +2. Training models +3. Evaluating model performance +4. Making landscape level predictions + +THE REST OF THIS TUTORIAL IS UNDER CONSTRUCTION diff --git a/model_garden/220723_withParacouUAV.pth b/model_garden/220723_withParacouUAV.pth deleted file mode 100644 index 3e05505b..00000000 --- a/model_garden/220723_withParacouUAV.pth +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:b2fc7ff3006b429ddbae947ead4149efb74370df7a5686de0af8573b13f62537 -size 503062735 diff --git a/model_garden/230103_randresize_full.pth b/model_garden/230103_randresize_full.pth deleted file mode 100644 index 325a9dcf..00000000 --- a/model_garden/230103_randresize_full.pth +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:54cbbae77e17f0928ece4cdcbe05d8909450a4840330155e8430479506df37c7 -size 498209001 diff --git a/model_garden/README.md b/model_garden/README.md index 1f39e01f..ecd41c03 100644 --- a/model_garden/README.md +++ b/model_garden/README.md @@ -1,12 +1,13 @@ # Model garden -Welcome to the model garden. Here lives the pretrained models. Please feel free -to pick what is ripe for your tree crown delineation problem. +Welcome to the model garden. Here live the pretrained models (now hosted on +[Zenodo](https://zenodo.org/records/10522461)). Please feel free to pick what +is ripe for your tree crown delineation problem. Download with e.g. ``` -!wget https://github.com/PatBall1/detectree2/raw/master/model_garden/230103_randresize_full.pth +!wget https://zenodo.org/records/10522461/files/230103_randresize_full.pth ``` and load with: @@ -19,7 +20,7 @@ cfg = setup_cfg(update_model=trained_model) ## 220723_withParacouUAV.pth A model trained with a range of tropical data including aeroplane and UAV -mounted cameras. +mounted cameras. Sites: Paracou, Danum, Sepilok. * Appropriate tile size ~ 100 m @@ -27,6 +28,7 @@ mounted cameras. An updated model trained across a range of tropical sites with better scale transferability owing to random resize augmentation during training. +Sites: Paracou, Danum, Sepilok. * Appropriate tile size ~ 100 m (with some tolerance) diff --git a/model_garden/urban_trees_Cambridge_20230630.pth b/model_garden/urban_trees_Cambridge_20230630.pth deleted file mode 100644 index 5345c61b..00000000 --- a/model_garden/urban_trees_Cambridge_20230630.pth +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:3bcfc86ee2daff04cb894d2d9bf5d5bf95a74f6fe1df776353ce0d538b5d0075 -size 503062799