Metadata-Version: 2.2
Name: pointtree
Version: 1.0.0
Summary: A Python Package for Tree Instance Segmentation in 3D Point Clouds.
Keywords: tree,point cloud,segmentation
Author-Email: Josafat-Mattias Burmeister <burmeister@uni-potsdam.de>
Maintainer-Email: Josafat-Mattias Burmeister <burmeister@uni-potsdam.de>
License: MIT License
         
         Copyright (c) 2024 Josafat-Mattias Burmeister
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Project-URL: Homepage, https://github.com/ai4trees/pointtree
Project-URL: Documentation, https://ai4trees.github.io/pointtree/
Project-URL: Repository, https://github.com/ai4trees/pointtree.git
Project-URL: Issues, https://github.com/ai4trees/pointtree/issues
Project-URL: Changelog, https://ai4trees.github.io/pointtree/changelog
Requires-Python: >=3.11
Requires-Dist: circle_detection<2.0.0,>=1.0.0
Requires-Dist: cloth-simulation-filter<2.0.0,>=1.1.5
Requires-Dist: laspy<3.0.0,>=2.0.0
Requires-Dist: numba<1.0.0,>=0.64.0
Requires-Dist: numpy<3.0.0,>=2.3.0
Requires-Dist: pandas<3.0.0,>=2.0.0
Requires-Dist: pointtorch<2.0.0,>=1.0.1
Requires-Dist: psutil<7.0.0,>=5.9.0
Requires-Dist: pyclesperanto-prototype<1.0.0,>=0.22.0
Requires-Dist: pygam<1.0.0,>=0.9.0
Requires-Dist: rasterio<2.0.0,>=1.3.9
Requires-Dist: scipy<2.0.0,>=1.8.0
Requires-Dist: scikit-image<1.0.0,>=0.25.0
Requires-Dist: scikit-learn<2.0.0,>=1.2.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pandas-stubs; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: scipy-stubs; extra == "dev"
Requires-Dist: types-Pillow; extra == "dev"
Requires-Dist: types-psutil; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<9.0.0,>=7.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints<4.0.0,>=2.0.0; extra == "docs"
Requires-Dist: sphinx-copybutton<1.0.0; extra == "docs"
Requires-Dist: sphinx-design<1.0.0; extra == "docs"
Requires-Dist: sphinx-docsearch<1.0.0; extra == "docs"
Requires-Dist: sphinx-mdinclude<1.0.0; extra == "docs"
Requires-Dist: sphinx-sitemap<3.0.0,>=2.0.0; extra == "docs"
Requires-Dist: sphinxawesome-theme<6.0.0,>=5.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-jsmath<2.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-katex<1.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-napoleon<1.0.0; extra == "docs"
Description-Content-Type: text/markdown

<img src="https://github.com/ai4trees/pointtree/blob/main/docs/assets/pointtree-logo-color.png?raw=true" alt="pointtree" width="300" height="100">

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

![pypi-image](https://badge.fury.io/py/pointtree.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/ai4trees/pointtree/actions/workflows/code-quality-main.yml/badge.svg)](https://github.com/ai4trees/pointtree/actions/workflows/code-quality-main.yml)
[![coverage](https://codecov.io/gh/ai4trees/pointtree/branch/main/graph/badge.svg)](https://codecov.io/github/ai4trees/pointtree?branch=main)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pointtree)

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.](https://doi.org/10.48550/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.](https://isprs-annals.copernicus.org/articles/X-4-W5-2024/79/2024/isprs-annals-X-4-W5-2024-79-2024.pdf)

### Package Documentation

The documentation of our package is available [here](https://ai4trees.github.io/pointtree/stable).

### Project Setup

The setup of our package is described in the [documentation](https://ai4trees.github.io/pointtree/stable#get-started).

### 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](https://ai4trees.github.io/pointtree/v0.1.0/pointtree.instance_segmentation.html#pointtree.instance_segmentation.TreeXAlgorithm).

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

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

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