run_treeqsm: Run TreeQSM on a LAS/LAZ file using PyTLidar

In tReeTraits: Calculate Tree Traits from Terrestrial Lidar

Run TreeQSM on a LAS/LAZ file using PyTLidar

Description

Processes a point cloud, filters and normalizes it, then runs the PyTLidar TreeQSM model to reconstruct cylinders representing the tree structure.

Usage

run_treeqsm(
  file,
  output_dir = NULL,
  intensity_threshold = 40000,
  resolution = 0.02,
  patch_diam1 = c(0.05, 0.1),
  patch_diam2min = c(0.04, 0.05),
  patch_diam2max = c(0.12, 0.14),
  optimizing_metrics = c("TrunkMean", "Branch1Mean"),
  verbose = TRUE
)

Arguments

file	Path to the input LAS or LAZ file.
output_dir	Directory to save output files; temporary if NULL.
intensity_threshold	Minimum point intensity to retain.
resolution	Thinning voxel size (m).
patch_diam1	Numeric vector of patch diameter 1 parameters.
patch_diam2min	Numeric vector of minimum patch diameter 2.
patch_diam2max	Numeric vector of maximum patch diameter 2.
optimizing_metrics	Character vector of metric names to average and minimize when selecting the best QSM fit. See Details
verbose	Logical; whether to print details during processing.

Details

The optimizing_metrics argument controls which point-to-cylinder distance summaries are used to evaluate TreeQSM fits. These metrics quantify how closely reconstructed cylinders match the underlying point cloud and are computed for different structural components of the tree.

Available metrics include:

• median, mean, max, std: Overall point–to–cylinder distances.

• TrunkMedian, TrunkMean, TrunkMax, TrunkStd: Trunk-only distances.

• BranchMedian, BranchMean, BranchMax, BranchStd: All branch distances.

• Branch1Median, Branch1Mean, Branch1Max, Branch1Std: First-order branch distances.

• Branch2Median, Branch2Mean, Branch2Max, Branch2Std: Second-order branch distances.

When multiple metrics are supplied, their row-wise mean is computed and minimized to select the best-fitting QSM, allowing users to balance fit quality across different tree components.

Value

A list with elements:

• qsm_pars: Data frame of selected patch parameters and fit metrics.

• qsm: Data frame of cylinder-level QSM output.

A list with elements:

qsm_pars

Data frame of patch parameters and fit metrics.

qsm

Data frame of cylinder-level QSM output.

Examples

## Not run: 
file <- system.file("extdata", "tree_0744.laz", package="tReeTraits")
run_treeqsm(file)

## End(Not run)

tReeTraits documentation built on Feb. 26, 2026, 1:07 a.m.