<img src="https://github.com/project-lightlin/misc/blob/main/img/smartqsm-logo.png?raw=true" width="192" height="24" alt="logo"> 2 Ginkgo <span style="font-weight:normal;">assists in Comprehensive Survey of Ancient and Famous Trees</span>

Latest version 2.1.0 released on 2026/04/02. Click here to view changelog.

---

SmartQSM is a quantitative structure model for individual tree 3D reconstruction and parameter extraction based on point cloud data. It is a part of Project LiGHTLIN.

Note:

This project is under long-term maintenance.

We would greatly appreciate it if you could contribute code fixes or new features, and mark your contribution among the contributors:) You can open an issue or mail to the author (see below) and we will review it as soon as possible!

For technical reasons, early versions (<=2.1.0) underwent many changes. We apologize for any inconvenience any inconvenience this may have caused.

:smiley: First Impression

| Real-time processing and displaying | Interactive architectural analysis | |-------------------------------------|-----------------------------------| | | |

This method integrates multiple (reimplemented and improved) tree skeleton extraction algorithms including

• :thumbsup: spconv-contraction (Sparse-convolution-based point cloud contraction) proposed by Yang et al. (2026) ^{This repo} and inspired by Dobbs et al.(2023) :octocat:
• :thumbsup: layerwise-clustering proposed by Xu et al. (2007) and inspired by Yang et al. (2024) :octocat:

From Ver 2.0:

• :thumbsup: flexible-layerwise-clustering inspired by Wang et al. (2025)
• space-colonization proposed by Runions et al. (2007)

More to come...

and supports the extraction of 82 multiscale parameters (Click here to view details) including

| Type | Parameters | | --- | --- | |Individual-scale: tree parameters| Location, Number of branches, Max branch order, Tree height, DBH, Girth, Ground diameter, Bole height, Diameter at bole height, Bole length, Bole area, Bole volume, Trunk length, Trunk area, Trunk volume, Stem length, Stem area, Stem volume, Within-crown stem length, Within-crown stem area, Within-crown stem volume, Min crown radius, Azimuth of min crown radius, Height at min crown radius, Mean crown radius, Max crown radius, Azimuth of max crown radius, Height at max crown radius, Min crown width, Azimuth of min crown width, Mean crown width, Max crown width, Azimuth of max crown width, East-west crown width, North-south crown width, Crown convex area, Crown convex volume, Active crown convex area, Active crown convex volume, Crown projection convex area, Crown perimeter, Canopy area, Crown center offset, Crown center azimuth, Min crown spread, Azimuth of min crown spread, Max crown spread, Azimuth of max crown spread, etc.| |Organ-scale: branch attributes| Order, Base height, Base diameter, Mid-length diameter, Tip diameter, Length, Area, Volume, Max spread, Azimuth, Zenith, Chord length, Arc height, Height difference, Branching radius, Branching angle, Tip deflection angle, Vertical deflection angle, Tip-based DINC, Apex-based DINC, Growth length, Growth area, Growth volume, Base offset, Base azimuth, Insertion distance, etc.| |Plot-scale: stand's spatial structure indices| Uniform angle index, Hegyi's competition index, Mingling, Tree species diversity mingling, Diameter dominance, Crowdedness, Openness, Within-unit species richness, etc.|

:smile: We are truly honored that SmartQSM was featured on CCTV News Channel's "Morning News" (Click here to watch the report)!

:star2: Star History

:medal_sports: Contributors

Author & Maintainer

• @teduzhu Dr. Jie Yang (杨杰), Beijing Forestry University (nj_yang_jie@bjfu.edu.cn)

Contributors

• @jk160804211 Dr. Kang Jiang (蒋康), Nanjing Forestry University: Reimplementation of space colonization
• @Luneighbour Mr. Nanbo Lu (鲁南博), Central South University of Forestry & Technology: Test
• @Cathy Dr. Tianrun Cai (蔡天润), Research Institute of Forestry, Chinese Academy of Forestry: Test

Acknowledgements

:balance_scale: License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

To report any (possible) abuse or infringement behavior, please contact yangtd@ifrit.ac.cn with a detailed description and any supporting evidence. Thank you for helping us make our community a better place!

:inbox_tray: Installation and Startup

0. Prerequisites

This repo has been verified and tested on Windows 10/11. Linux has not been tested.

1. Please refer to how-to-install-python-and-deep-learning-libraries to prepare the virtual environment. If your computer does not meet the requirements for installing deep learning libraries, you can still proceed with this tutorial after simply setting up a Python virtual environment. Only some features will be limited (e.g., spconv-based-contraction will be unavailable), and the program will prompt relevant information; all other features will function normally.

2. Install Git and clone the repo into the specified working directory using:

git clone https://github.com/project-lightlin/SmartQSM.git

in the CONDA environment.

Or you can:

A. click the Code button on the top right corner of the repo page,

B. click Download ZIP,

C. extract the downloaded zip file to the desired location.

Note:

We strongly recommend that you install Git for future upgrades.

3. Change the working directory of the virtual environment to the project directory (including requirements.txt).

4. Finish post-installation by running

python post_installation.py

1. Run SmartQSM

python entrypoints/smartqsm.py

Or use command-line arguments:

python entrypoints/smartqsm.py [-h] [-v] [-y] [-c CONFIG] [-t] [CLOUD_PATHS ...]

You can refer to the specific parameter descriptions by using the -h option. The default configuration file represented by CONFIG is located in the configs/ directory of the project; you can select any one based on your requirements. Advanced Usage: You can create a .yaml file with the same name as your input point cloud file in the same directory to achieve personalized reconstruction at the file level.

Input

Warning: The ground and understory vegetation of the input individual tree point cloud should be cleaned up and there should be no large nontarget tree points, otherwise the reconstructed model will be distorted.

You can import multiple point clouds from different folders in batch at once, and the program will process them sequentially.

The names of the configuration files usually provide a brief summary of the skeletonization algorithm used, along with some additional information. Specifically,

• Use the configuration file marked "cpu" if the PyTorch version in the virtual environment is for CPU; use the configuration file marked "GPU" if the version is "cuXXX".
• Use “LEAFOFF” for cases with sparse or absent foliage; use “LEAFON” for cases with abundant foliage.

Output

Each processed individual tree point cloud will generate five output files in the same directory, including:

• *_active_crown.ply: Triangle mesh of active crown convex hull
• *_branches.ply: Triangle mesh of branching structure colored by order
• *_crown.ply: Triangle mesh of crown convex hull
• *_qsm.mat: This file can be the input of some tools developed for TreeQSM such as LeafGen. However, when using it, you need to transform the coordinates in QSM.cylinder.start. The recommended solution is to subtract [QSM.treedata.X_m, QSM.treedata.Y_m, QSM.treedata.altitude_m] from each coordinate. Otherwise, especially when a projected coordinate system is involved, the model cannot be displayed correctly.
• *_skeleton.dxf: Line set of tree skeleton

PLY and DXF files can be opened by CloudCompare.

2. Run QSM Viewer: Interactive architectural analysis tool

python entrypoints/qsm_viewer.py

Or

python entrypoints/qsm_viewer.py PATH_OF_YOUR_qsm.mat

Import the *_qsm.mat file, which must have a corresponding and unmodified *_branches.ply.