File size: 4,811 Bytes
9712fbd e624743 e053ce9 e624743 9712fbd e624743 e053ce9 e624743 e053ce9 e624743 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | ---
license: mit
tags:
- forestry
- object-detection
- aerial-imagery
- detectron2
- sahi
- treelens
- tree-crown-detection
---
# TreeLens Detectron2 Tree Detection Model
This repository hosts the **TreeLens** tree detection model, built on **Detectron2** and integrated with the **SAHI (Slicing Aided Hyper Inference)** library. It is designed to detect and map tree crowns in high-resolution aerial orthomosaics and estimate tree biophysical parameters like crown width, height, and biomass (using digital elevation models).
Developed by **Farmers for Forests**, this model is optimized to work with SAHI sliced inference.
---
## How to Run the Inference Script
This guide explains how to run the `treelens_ortho_inference.py` script step-by-step. The script is structured with `# %%` cell markers, meaning you can easily open it in Google Colab (by renaming it to `.ipynb` or uploading it directly) or run it in VS Code as interactive cells.
### Step 1: Upload and Organize Your Files
1. Place your orthomosaic (`.tif` format) and digital elevation model (`.tif` format) in your Google Drive.
2. By default, the script looks for your files at:
- **Orthomosaic:** `/content/drive/MyDrive/test.tif`
- **DEM (Elevation):** `/content/drive/MyDrive/test.tif`
- **Output Directory:** `/content/drive/MyDrive`
*(If you want to use different paths, edit lines 6 to 11 in **Cell 2** of the script).*
---
### Step 2: Open and Run the Script in Google Colab
You can run this code by uploading the script to a Google Colab notebook:
#### **Cell 1: Mount Google Drive**
This cell links your Google Drive to the runtime environment to access your orthomosaic and DEM images.
```python
from google.colab import drive
drive.mount('/content/drive')
```
#### **Cell 2: Setup Paths and Parameters**
Define your file inputs, output folder, confidence threshold, and average tree crown width.
* `aveg_width = 13` The script will automatically calculate the best slicing patch size based on this width and the ground resolution (GSD) of your `.tif` file. `aveg_width/GSD = sahi slice size (pixel)`
#### **Cell 3: Download Model Files from Hugging Face**
Downloads the Detectron2 weights (`Treelens_model.pth`) and the training configuration (`config.yaml`) from the Hugging Face hub automatically.
```python
repo_id = "farmersforforests/TreeLens-detectron2"
```
#### **Cell 4 & 5: Install Dependencies & Import Libraries**
Installs and imports the core packages:
* `sahi` (Sliced Inference framework)
* `detectron2` (Object Detection engine)
* `rasterio` (Geospatial metadata & projection parser)
* `scipy` & `pycocotools`
#### **Cell 6: Load Helper Functions**
Executes function definitions for:
* Geocoding coordinates (pixels to Latitude & Longitude)
* Outputting Pascal VOC XML and COCO JSON formats
* Extracting GSD resolution and calculating tree heights from the DEM
#### **Cell 7: Initialize Model**
Loads the Detectron2 model onto your GPU (`cuda:0`).
* *Note: Make sure your Colab notebook is set to a GPU hardware accelerator (Runtime > Change runtime type > GPU).*
#### **Cell 8 & 9: Run Inference & Save Results**
Processes the orthomosaics, runs sliced inference, plots predictions, and saves the output logs.
---
## Outputs Generated
Once the script runs successfully, the following files will be saved in your `save_dir` (Google Drive root by default):
1. **`{basename}_pred.png`**: The orthomosaic image with visual bounding boxes drawn around all detected trees.
2. **`{basename}.xml`**: Standard Pascal VOC XML annotation file.
3. **`{basename}.json`**: Standard COCO JSON annotation file.
4. **`{basename}_pred.csv`**: A spreadsheet with:
- Target bounding box pixel coordinates (`xmin`, `ymin`, `xmax`, `ymax`).
- Spatial coordinates of each tree center (`lon`, `lat`).
- Calculated `Crown (m)` width of each tree.
5. **`{basename}_pred_with_heights.csv`**: Same as above, updated with `Height (m)` for each tree derived from the DEM file.
6. **`{basename}_pred_with_biomass.csv`**: (Optional) Estimates DBH (cm) and AGB (Above Ground Biomass in kg) for each tree. To enable this, set `calculate_biomass = True` in Cell 9.
---
## Local Terminal/CLI Execution (Optional)
If you wish to run this script outside of Colab (e.g. locally in a terminal):
1. Install Python 3.8+ and install all dependencies:
```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
python -m pip install 'git+https://github.com/facebookresearch/detectron2.git'
pip install -U sahi huggingface_hub rasterio scipy pycocotools pandas matplotlib pillow
```
2. Comment out Cell 1 (`drive.mount`) in the script.
3. Update the paths in Cell 2 to point to your local directories.
4. Execute:
```bash
python treelens_ortho_inference.py
```
|