TreeQSM-Py

Python implementation of TreeQSM (Tree Quantitative Structure Model) - a method for reconstructing quantitative structure models for trees from point cloud data.

Overview

TreeQSM-Py is a Python port of the original MATLAB implementation. It reconstructs 3D tree models as hierarchical collections of cylinders (Quantitative Structure Models - QSMs) from point cloud data, typically obtained from terrestrial laser scanning.

Original MATLAB version: https://github.com/InverseTampere/TreeQSM

NOTE: Conversion has been mostly done with LLM and most likely error prone. Certain fixes and guardrails have been implemented to assist on another on-going project where this conversion is helpful

Installation

pip install -e .

For development with visualization support:

pip install -e ".[dev,viz]"

Quick Start

import numpy as np
from treeqsm import treeqsm, create_input

# Load point cloud (Nx3 array in meters)
P = np.loadtxt('tree_pointcloud.txt')

# Create input parameters
inputs = create_input(
    PatchDiam1=[0.08, 0.10],
    PatchDiam2Min=[0.02, 0.03],
    PatchDiam2Max=[0.07, 0.09],
    name='my_tree',
    tree=1,
    model=1
)

# Reconstruct QSM
qsm = treeqsm(P, inputs)

# Access results
print(f"Total volume: {qsm.treedata.TotalVolume:.3f} L")
print(f"DBH: {qsm.treedata.DBHqsm:.3f} m")
print(f"Tree height: {qsm.treedata.TreeHeight:.3f} m")
print(f"Number of branches: {qsm.treedata.NumberBranches}")

Features

• Complete reconstruction pipeline from point clouds to QSMs
• Multi-parameter optimization workflow
• 91 different optimization metrics
• Point cloud filtering and preprocessing
• Optional stem triangulation
• Quality metrics (point-to-model distances, surface coverage)
• Batch processing for multiple trees

Requirements

• Python ≥ 3.8
• NumPy ≥ 1.20
• SciPy ≥ 1.7
• scikit-learn ≥ 1.0

Optional:

• matplotlib ≥ 3.5 (visualization)
• open3d ≥ 0.16 (3D visualization)

License

GNU General Public License v3.0 or later (GPLv3+)

Original MATLAB implementation: Copyright (C) 2013-2022 Pasi Raumonen

Python port: Copyright (C) 2025 Asikaim

References

• Raumonen et al. 2013, Remote Sensing: https://www.mdpi.com/2072-4292/5/2/491
• Calders et al. 2015, Methods in Ecology and Evolution: https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.12301
• Raumonen et al. 2015, ISPRS Annals: https://www.isprs-ann-photogramm-remote-sens-spatial-inf-sci.net/II-3-W4/189/2015/

Status

🚧 Under Development - This is a work-in-progress port from MATLAB to Python.