pointtree 1.0.1

A Python Package for Tree Instance Segmentation in 3D Point Clouds.

The package contains implementation of the following tree instance segmentation algorithms:

• TreeXAlgorithm
• CoarseToFineAlgorithm

It contains the official source code of the following papers:

• TreeXAlgorithm - Burmeister, Josafat-Mattias, Tockner, Andreas, Reder, Stefan, Engel, Markus, Richter, Rico, Mund, Jan-Peter, & Döllner, Jürgen (2025). "treeX: Unsupervised Tree Instance Segmentation in Dense Forest Point Clouds." arXiv preprint arXiv:2509.03633.
• CoarseToFineAlgorithm - Burmeister, Josafat-Mattias, Richter, Rico, Reder, Stefan, Mund, Jan-Peter, & Döllner, Jürgen (2024). "Tree Instance Segmentation in Urban 3D Point Clouds Using a Coarse-to-Fine Algorithm Based on Semantic Segmentation." ISPRS Annals of the Photogrammetry, Remote Sensing and Spatial Information Sciences, 10, 79-86.

Package Documentation

The documentation of our package is available here.

Installation

The installation steps are detailed in the documentation. A minimal example is shown below:

python -m pip install torch==2.10.0

python -m  pip install torch-scatter torch-cluster -f https://data.pyg.org/whl/torch-2.10.0+cpu.html

python -m pip install pointtree

How To Use the Package

The TreeXAlgorithm segments individual tree instances from point clouds of forest areas. It assumes that the input point cloud contains only terrain and vegetation points. If your data includes other objects (e.g., man-made structures), the algorithm can still be applied, but its accuracy may be reduced.

1. Creating an Algorithm Instance

To get started, create an instance of the TreeXAlgorithm class. All parameters have default values, but you can override them by passing keyword arguments to the constructor. For a complete list of parameters and their descriptions, see the documentation.

from pointtree.instance_segmentation import TreeXAlgorithm

# Optional: specify a folder for saving visualizations of intermediate results
# Note: generating visualizations slows down processing and is recommended only for small datasets
visualization_folder = "./visualizations"  # or set to None to disable

algorithm = TreeXAlgorithm(visualization_folder=visualization_folder)

2. Using Presets

We provide presets tailored to typical point cloud characteristics from different laser scanning modalities: terrestrial (TLS), and UAV-borne (ULS). These presets simplify setup for common use cases.

from pointtree.instance_segmentation import TreeXPresetTLS, TreeXPresetULS

preset = TreeXPresetTLS()  # or use TreeXPresetULS()
algorithm = TreeXAlgorithm(**preset)

3. Running the Algorithm

The algorithm requires a numpy array of shape (n_points, 3) as input, containing the xyz-coordinates of the point cloud. If available, you can also pass reflection intensity values which may improve segmentation accuracy.

The algorithm returns a tuple of three numpy arrays:

• instance IDs: an array of instance labels (points that belong to the same tree have the same ID, points not belonging to any tree have the ID -1),
• trunk positions: 2D coordinates of the detected tree trunks at breast height
• trunk diameters: diameters of the detected trunks at breast height.

from pointtorch import read

# Load your point cloud (supports .txt, .csv, .las, .laz, .ply)
file_path = "./demo.laz"
point_cloud = read(file_path)

# Run the algorithm
instance_ids, trunk_positions, trunk_diameters = algorithm(
    point_cloud[["x", "y", "z"]].to_numpy(),
    intensities=point_cloud["intensity"].to_numpy(),
    point_cloud_id="test-point-cloud",  # Optional: Used for naming visualization / intermediate outputs
    crs="EPSG:4326"  # Optional: Used for georeferencing intermediate outputs
)

# Add results to the point cloud and save to a new file
point_cloud["instance_id"] = instance_ids
point_cloud.to("./demo_segmented.laz", columns=["x", "y", "z", "instance_id"])

How to Cite

If you use our code, please consider citing our papers:

@article{Burmeister_Tree_X_2025,
author = {Burmeister, Josafat-Mattias and Tockner, Andreas and Reder, Stefan and Engel, Markus and Richter, Rico and Mund, Jan-Peter and D{\"o}llner, J{\"u}rgen},
doi = {https://doi.org/10.48550/arXiv.2509.03633},
journal = {{arXiv} preprint},
title = {{treeX}: Unsupervised Tree Instance Segmentation in Dense Forest Point Clouds},
year = {2025}
}

@article{Burmeister_Tree_Instance_Segmentation_2024,
author = {Burmeister, Josafat-Mattias and Richter, Rico and Reder, Stefan and Mund, Jan-Peter and D{\"o}llner, J{\"u}rgen},
doi = {10.5194/isprs-annals-X-4-W5-2024-79-2024},
journal = {{ISPRS} Annals of the Photogrammetry, Remote Sensing and Spatial Information Sciences},
pages = {79--86},
title = {{Tree Instance Segmentation in Urban 3D Point Clouds Using a Coarse-to-Fine Algorithm Based on Semantic Segmentation}},
volume = {X-4/W5-2024},
year = {2024}
}