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

Place your orthomosaic (.tif format) and digital elevation model (.tif format) in your Google Drive.
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.

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.

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):

{basename}_pred.png: The orthomosaic image with visual bounding boxes drawn around all detected trees.
{basename}.xml: Standard Pascal VOC XML annotation file.
{basename}.json: Standard COCO JSON annotation file.
{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.
{basename}_pred_with_heights.csv: Same as above, updated with Height (m) for each tree derived from the DEM file.
{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):

Install Python 3.8+ and install all dependencies:

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

Comment out Cell 1 (drive.mount) in the script.
Update the paths in Cell 2 to point to your local directories.
Execute:
```
python treelens_ortho_inference.py
```

Downloads last month: -