A new upgrade in February 2025 boosts the processing speed by 5-15x. The plugin is now integrated into CloudCompare 2.14.alpha (Windows only).

A new Python version accelerated by C++ has been developed.

Zhouxin Xi ([email protected]) and Chris Hopkinson ([email protected])

The University of Lethbridge - Department of Geography & Environment - Artemis Lab

Please cite:

Xi, Z.; Hopkinson, C. 3D Graph-Based Individual-Tree Isolation (Treeiso) from Terrestrial Laser Scanning Point Clouds. Remote Sens. 2022, 14, 6116. https://doi.org/10.3390/rs14236116

This tool relies on the cut-pursuit algorithm, please also consider citing:

Landrieu, L.; Obozinski, G. Cut Pursuit: Fast Algorithms to Learn Piecewise Constant Functions on General Weighted Graphs. SIAM J. Imaging Sci. 2017, 10, 1724–1766. hal link

Raguet, H.; Landrieu, L. Cut-pursuit algorithm for regularizing nonsmooth functionals with graph total variation. In Proceedings of the International Conference on Machine Learning, Stockholm, Sweden, 10–15 July 2018; Volume 80, pp. 4247–4256.

├── data                                    # Raw data
│   └── LPine1_demo.laz                     # Example TLS data (subset due to file size limits)
├── Matlab                                  # treeiso Matlab source code
│   ├── treeiso.m                           # Main Matlab program
│   ├── cutPursuit.m                        # Wrapper for L0 cut-pursuit mex code
│   ├── jitknnsearch.m                      # JIT-accelerated knnsearch for small point sets
│   ├── overlapping.m                       # Calculates overlap ratio between crown convex hulls
│   ├── L0_cut_pursuit.mexw64               # Compiled L0 cut-pursuit executable
│   ├── L0_cut_pursuit_segmentation.mexw64  # Compiled L0 cut-pursuit segmentation executable
│   ├── las2mat.mexw64                      # Compiled LAS/LAZ file reader
│   └── mat2las.mexw64                      # Compiled LAS/LAZ file writer
├── Python                                  # treeiso Python source code
│   ├── treeiso.py                          # Main Python program
│   ├── cut_pursuit_L0.py                   # Simplified Python version of cut-pursuit (L0 norm only)
│   └── cut_pursuit_L0_replica_cpp.py       # Python version closer to the original C++ (slower; for reference)
├── PythonCPP                               # Python source code accelerated by C++ (Recommended)
│   ├── treeiso.py                          # Main Python program
│   └── cut_pursuit_L0.py                   # Backup simplified cut-pursuit (L0 norm only)
├── R                                       # R script
│   ├── treeiso_example.R                   # An R example
├── CloudCompare                            # CloudCompare plugin (external link)
├── cut_pursuit_py                          # C++ cut-pursuit Python binder (external link)
├── .gitmodules                             # External repository declarations
├── LICENSE
└── README.md

• Noise Removal: Clean your TLS data to remove noise (e.g., using CloudCompare with a Sober filter, NN=10, std=1).
• Decimation: Decimate the point cloud to a reasonable resolution (approximately 2 cm).
• Ground Points: Remove ground points before running tree isolation.

1. Execution:
   Run the Matlab script located at Matlab/treeiso.m.
   When prompted, enter the folder path containing your LAS/LAZ files.
   The script will search for all LAS/LAZ files in the specified directory and process each one.

2. Testing:
   For a quick test, point the script to the data folder containing LPine1_demo.laz.

3. Output:
   Processed LAS/LAZ files (with additional fields) will be saved in Matlab/output/. Each output file includes three additional fields:

   • init_segs: Initial segmentation from 3D cut-pursuit
   • interim_segs: Second-stage segmentation from 2D cut-pursuit
   • segs: Final tree segmentation

4. Performance:
   Processing a ~25 MB LAS/LAZ file takes about 10 minutes on an Intel Core i7-9700K with 16 GB RAM.

Note:
The mex files were compiled on Windows 10 (64-bit) using Visual Studio 2019. If you need to compile them yourself, please refer to the following resources:
cutpursuit and mastools.

• Python 3.6–3.12 (newer versions are untested)

1. Open your terminal or command-line interface.
2. Clone or download the repository:

   git clone https://github.com/artemislab/treeiso.git
   cd treeiso/PythonCPP

3. Install the dependencies:

   pip install -r requirements.txt

Run the treeiso.py script in the PythonCPP folder:

python treeiso.py

When prompted, enter the path to the directory containing your LAS/LAZ or CSV files. The resulting LAZ or CSV file will be saved in the same directory with the suffix *_treeiso.laz or *_treeiso.csv.

Note:
The program first checks for the presence of the C++-based cut_pursuit_py module. If it is not installed, it falls back to the pure Python version (cut_pursuit_L0.py). The C++ interface is provided via pre-built wheels for Ubuntu, macOS, and Windows, so you typically do not need a C++ compiler. The C++ version offers a speed-up of over 5× compared to the pure Python implementation, though the results may differ slightly.

1. Clone or download the repository:

   git clone https://github.com/artemislab/treeiso.git
   cd treeiso/Python

2. Install the dependencies:

   pip install -r requirements.txt

Run the treeiso.py script in the Python folder:

python treeiso.py

When prompted, enter the path to your directory containing LAS/LAZ files. The output file will be saved in the same input directory.

An R script suggested by Gergo Dioszegi uses the CloudCompare command-line interface to automate processing. This script remains untested.

The speed comparison between the 2023 and 2025 versions and the time profiling for the 2025 version are shown in the figure below:

Speed Comparison	Time Profiling

The time complexity of the cut-pursuit algorithm is approximately O(log n) iterations multiplied by O(m+n) per iteration.

Raw TLS Example1	After treeiso isolation	Top view

Raw TLS Example2	After treeiso isolation	Top view

Raw TLS Example3	After treeiso isolation	Top view

treeiso is not intended to be a perfect, all-in-one solution. Instead, it is designed as an interactive tool that allows users to re-run the algorithm on problematic areas or manually adjust the segmentation results within CloudCompare.