README.md

---
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
   ```