(Français)

<img src="https://github.com/NRCan/TreeAIBox/blob/b0918d50b1343d62e1b518c29cd50d38f801b359/treeaibox-header.bmp" alt="treeaibox_logo" width="60"/> TreeAIBox CloudCompare Plugin

A CloudCompare Python plugin providing a unified web-style GUI for a suite of LiDAR processing modules targeting forest and tree analysis.

It enables forestry practitioners and researchers to interactively process 3D LiDAR data within the open-source CloudCompare software.

This aligns with the idea that agentic AI should first break down tasks into sub-questions and then fine-tune smaller, specialized vision models—an approach that can be both more effective and more cost-efficient than relying solely on large language models.

📖 Overview

TreeAIBox brings together four core LiDAR-processing workflows in a single GUI:

• TreeFiltering
  Supervised deep-learning filtering to separate understory and overstory points.

• TreeisoNet
  End-to-end crown segmentation pipeline (StemCls → TreeLoc → TreeOff → CrownOff3D), allowing manual editing.

• WoodCls
  3D stem & branch classification on TLS data.

• QSM
  Plot-level skeletonization and export of tree structure to XML/OBJ.

• UrbanFiltering
  Supervised deep learning–based filtering to classify urban scenes into seven categories: 1 = ground, 2 = vegetation, 3 = vehicles (cars+trucks), 4 = powerlines, 5 = fences, 6 = poles, 7 = buildings.

🚀 Features

• 20+ pretrained AI models
  Downloadable from a remote server; mostly lightweight or distilled versions, fine-tuned with carefully annotated datasets.

• 3D targeted
  Operates directly on raw 3D point clouds—no CHM or raster inputs—using voxel-based AI architectures for both training and inference.

• Sensor, scene, and resolution options
  Supports TLS, ALS, and UAV LiDAR across boreal, mixedwood, reclamation, and urban forest types.

• GPU acceleration toggle
  Runs on either GPU (CUDA) or CPU for flexibility.

• Web-style UI framework
  Features resizable windows and modular UI components.

• Interactive parameter controls
  Allow certain result customization using adjustable parameters.

• Open source
  Fully Python-based (except for pretrained model files); outputs include scalar fields, point clouds, and exportable files.

• Windows installer
  Automatically installs required packages and registers the main script as a Python plugin.

🛠️ Installation

1. Via Windows installer (Suggested)

A ready-to-run online installer is provided. Ensure internet access is enabled:

1. Install CloudCompare

   Download and install CloudCompare v2.14.alpha (latest release) from https://cloudcompare-org.danielgm.net/release/

2. Download the TreeAIBox Installer

   Get TreeAIBox_Plugin_Installer_v1.0.exe from our releases page: https://github.com/NRCan/TreeAIBox/releases

3. Run the Installer

   • Right-click TreeAIBox_Plugin_Installer_v1.0.exe and choose Run as administrator.
   • Follow the on-screen prompts. By default, the installer will detect your CloudCompare folder (e.g., %PROGRAMFILES%\CloudCompare) from the registry.

   What Installer does:

   • Copies all Python scripts, UI files, images, and modules into:

     …\CloudCompare\plugins\Python\Plugins\TreeAIBox\
     

   • Generates a helper batch script to detect your NVIDIA GPU and install the matching PyTorch wheel.

   • Launches pip to install required Python packages (e.g., PyQt6, torch, requests).

4. Finish Up

   Once installation completes, restart CloudCompare and launch TreeAIBox from the Python console.

Note: The NSIS script (CloudCompare_Python_Plugin.nsi) can be edited if you need to customize install paths or package versions.

2. Alternatively, manual (Git + pip)

cd %PROGRAMFILES%\CloudCompare\plugins\Python\Plugins
git clone https://github.com/NRCan/TreeAIBox.git TreeAIBox
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu121
pip install PyQt6 PyQt6-WebEngine requests numpy_indexed timm numpy_groupies cut_pursuit_py circle_fit scikit-learn scikit-image

Under CloudCompare’s Script Register menu, click Add Script, then browse to and select TreeAIBox.py to register it.

▶️ Usage

In CloudCompare, under Script Register, click the TreeAIBox.

Then select a point cloud, pick your module tab, choose/download a model, adjust settings, and click Apply.

When isolating ALS individual trees, set an appropriate voxel resolution (e.g., 0.8 m horizontal by 2.0 m vertical) to optimize tree detection on TreeisoNet.

⚙️ Configuration

• model_zoo.json lists available model names.
• Logs & outputs in C:\Users\USERNAME\AppData\Local\CloudCompare\TreeAIBox\.

The table below summarizes the voxel resolution and GPU memory used by the current AI models, categorized by sensor type, task, component, and scene:

<table> <thead> <tr> <th align="center">Sensor</th> <th align="center">Task</th> <th align="center">Component</th> <th align="center">Scene</th> <th align="center">Resolution</th> <th align="center">VRAM</th> </tr> </thead> <tbody> <!-- ALS Classification --> <tr> <td align="center" rowspan="4"><strong>ALS (or UAV without stems)</strong></td> <td align="center" rowspan="4">Classification</td> <td align="center" rowspan="3">Vegetation layer</td> <td align="center">Mountainous</td> <td align="center">80 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">Regular</td> <td align="center">50 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">Wellsite</td> <td align="center">15 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">Urban layers</td> <td align="center">Urban</td> <td align="center">30 cm</td> <td align="center">3 GB</td> </tr> <!-- UAV Classification --> <tr> <td align="center" rowspan="2"><strong>UAV (with stems)</strong></td> <td align="center" rowspan="2">Classification</td> <td align="center">Vegetation layer</td> <td align="center">Regular</td> <td align="center">12 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">Stems</td> <td align="center">Mixedwood</td> <td align="center">8 cm</td> <td align="center">3 GB</td> </tr> <!-- TLS Classification --> <tr> <td align="center" rowspan="7"><strong>TLS</strong></td> <td align="center" rowspan="7">Classification</td> <td align="center">Vegetation layer</td> <td align="center">Regular</td> <td align="center">8 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center" rowspan="3">Stems</td> <td align="center" rowspan="3">Boreal</td> <td align="center">10 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">4 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">20 cm</td> <td align="center">8 GB</td> </tr> <tr> <td align="center">Stems</td> <td align="center">Regular</td> <td align="center">4 cm</td> <td align="center">12 GB</td> </tr> <tr> <td align="center" rowspan="2">Stems + branches</td> <td align="center" rowspan="2">Regular</td> <td align="center">4 cm</td> <td align="center">2 GB</td> </tr> <tr> <td align="center">2.5 cm</td> <td align="center">3 GB</td> </tr> <!-- ALS Clustering --> <tr> <td align="center" rowspan="2"><strong>ALS (or UAV without stems)</strong></td> <td align="center" rowspan="2">Clustering</td> <td align="center">Tree tops</td> <td align="center">Wellsite</td> <td align="center">10 cm</td> <td align="center">4 GB</td> </tr> <tr> <td align="center">Tree segments</td> <td align="center">Wellsite</td> <td align="center">10 cm</td> <td align="center">4 GB</td> </tr> <!-- UAV Clustering --> <tr> <td align="center" rowspan="2"><strong>UAV (with stems)</strong></td> <td align="center" rowspan="2">Clustering</td> <td align="center">Tree bases</td> <td align="center">Mixedwood</td> <td align="center">10 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">Tree segments</td> <td align="center">Mixedwood</td> <td align="center">15 cm</td> <td align="center">4 GB</td> </tr> <!-- TLS Clustering --> <tr> <td align="center" rowspan="2"><strong>TLS</strong></td> <td align="center" rowspan="2">Clustering</td> <td align="center">Tree bases</td> <td align="center">Boreal</td> <td align="center">10 cm</td> <td align="center">3 GB</td> </tr> <tr> <td align="center">Tree segments</td> <td align="center">Boreal</td> <td align="center">15 cm</td> <td align="center">4 GB</td> </tr> </tbody> </table>

🗂️ Folder structure

TreeAIBo