Title:	Tree Crown Segmentation in Airborne LiDAR Point Clouds
Version:	1.0.1
Maintainer:	Timon Miesner <timon.miesner@thuenen.de>
Description:	Provides a function that performs the adaptive mean shift algorithm for individual tree crown delineation in 3D point clouds as proposed by Ferraz et al. (2016) <doi:10.1016/j.rse.2016.05.028>, as well as supporting functions.
License:	GPL-3
URL:	https://github.com/Lenostatos/crownsegmentr
Depends:	R (≥ 4.0.0)
Imports:	assertthat, data.table, dbscan, lidR (≥ 4.0.0), methods, Rcpp (≥ 1.0.0), sf, terra
Suggests:	EBImage, future, testthat (≥ 3.0.0), raster
LinkingTo:	BH (≥ 1.75.0-0), progress, Rcpp (≥ 1.0.0)
Config/testthat/edition:	3
Contact:	timon.miesner@thuenen.de, Leon.Steinmeier@posteo.net, nikolai.knapp@thuenen.de
Encoding:	UTF-8
RoxygenNote:	7.3.3
SystemRequirements:	C++17, GNU make
NeedsCompilation:	yes
Packaged:	2025-12-02 11:58:22 UTC; miesner
Author:	Leon Steinmeier [aut] (Created the package as part of his master thesis.), Timon Miesner [cre, aut] (Expanded the functionality of the package as part of the project ForestPulse.), Nikolai Knapp [aut] (Initialized, motivated and managed the development of the package.)
Repository:	CRAN
Date/Publication:	2025-12-09 07:50:13 UTC

Assert that the extent of a raster covers that of a data.frame point cloud

Description

Assert that the extent of a raster covers that of a data.frame point cloud

Usage

assert_that_raster_covers_data_frame_point_cloud(
  raster,
  data_frame_point_cloud,
  message
)

Arguments

Assert that the extent of a raster covers that of a LAS point cloud

Description

Assert that the extent of a raster covers that of a LAS point cloud

Usage

assert_that_raster_covers_las_point_cloud(raster, las_point_cloud, message)

Arguments

Searches modes with the AMS3D algorithm for a lidar point cloud of a forest

Description

Employs the 3D adaptive mean shift algorithm (Ferraz et al., 2016) to estimate the mode of each point in a point cloud which is assumed to contain trees. In this context the mode is a theoretical "center of mass" of a tree crown point cloud, that is usually located shortly below the crown apex.

Usage

calculate_centroids_flexible(
  coordinate_table,
  min_point_height_above_ground,
  ground_height_data,
  crown_diameter_to_tree_height_data,
  crown_length_to_tree_height_data,
  crown_diameter_constant,
  crown_length_constant,
  centroid_convergence_distance,
  max_iterations_per_point,
  also_return_all_centroids,
  show_progress_bar
)

calculate_centroids_normalized(
  coordinate_table,
  min_point_height_above_ground,
  crown_diameter_to_tree_height,
  crown_length_to_tree_height,
  crown_diameter_constant,
  crown_length_constant,
  centroid_convergence_distance,
  max_iterations_per_point,
  also_return_all_centroids,
  show_progress_bar
)

calculate_centroids_terraneous(
  coordinate_table,
  min_point_height_above_ground,
  ground_height_grid_data,
  crown_diameter_to_tree_height,
  crown_length_to_tree_height,
  crown_diameter_constant,
  crown_length_constant,
  centroid_convergence_distance,
  max_iterations_per_point,
  also_return_all_centroids,
  show_progress_bar
)

Arguments

Value

A list with either one or two elements:

• The first element (named "terminal_coordinates") contains the terminal centroids for all points in the coordinate_table. These are stored in a data.frame with three columns that hold the x-, y-, and z-coordinates and they are stored in the same order as their respective points in the coordinate_table.

• The second element (named "centroid_coordinates") is only present if also_return_all_centroids was set to TRUE and contains the centroids calculated during the mode finding process. The prior centroids are stored in a data.frame with xyz-coordinate columns like the terminal centroids. To enable grouping of these centroids by the point they belong to, there is one additional column (named "point_index") which holds row indices of the corresponding points in the coordinate_table.

Functions

• calculate_centroids_flexible(): Can take either a single value or raster data for both the ground height and the crown_diameter_to_tree_height and crown_length_to_tree_height parameters.

• calculate_centroids_terraneous(): Use a ground height raster to find modes in a non-normalized point cloud.

Raster argument structure

Raster data has to be passed as a list comprising the following named elements:

• values: Numeric vector holding the values.

• num_rows: Integer number indicating the number of rows.

• num_cols: Integer number indicating the number of columns.

• x_min: Number indicating the lowest x coordinate covered.

• x_max: Number indicating the largest x coordinate covered.

• y_min: Number indicating the lowest y coordinate covered.

• y_max: Number indicating the largest y coordinate covered.

References

Ferraz, A., S. Saatchi, C. Mallet, and V. Meyer (2016) Lidar detection of individual tree size in tropical forests. Remote Sensing of Environment 183:318–333. doi:10.1016/j.rse.2016.05.028.

Get the scale and offset values of all files referenced by a LAScatalog

Description

Get the scale and offset values of all files referenced by a LAScatalog

Usage

collect_scale_n_offset_of_LAScatalog_files(LAScatalog)

Value

A data.table with 7 columns. The first three columns hold the x, y, and z scale factors, the next three columns hold the x, y, and z offsets and the last column holds the file paths. There is one row for each referenced file.

Extract coordinate data from a data.frame-like object

Description

This function extracts three numeric columns from the input table. If possible, columns which are named x/X, y/Y, or z/Z.

Usage

extract_coordinate_values(coordinate_table)

Arguments

Value

A base::data.frame() with just three columns that are expected to hold the x-, y-, and z-coordinates in that order.

Calculate a raster of crown diameter for tree height for AMS3D

Description

The function calculates a raster with values for crown_diameter_to_tree_height as input for the AMS3D algorithm. It segments the tree crowns with the Li2012 algorithm, calculates a ratio of crown diameter to tree height for each tree, and converts this into a raster.

Usage

li_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

Arguments

Value

terra SpatRaster

Details

The output raster can serve as input for the parameter "crown_diameter_to_tree_height" for the function segment_tree_crowns. It averages the ratio of crown diameter to tree height for a given radius, for trees that were detected with the Li2012 tree segmentation algorithm.

Calculate a raster of crown diameter to tree height using watershed segmentation

Description

The function calculates a raster with values for crown_diameter_to_tree_height as input for the AMS3D algorithm. It segments the tree crowns with the watershed algorithm from lidR, calculates a ratio of crown diameter to tree height for each tree, and converts this into a raster.

Usage

## S4 method for signature 'LAS'
li_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

## S4 method for signature 'data.frame'
li_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

## S4 method for signature 'LAScatalog'
li_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

watershed_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

## S4 method for signature 'LAS'
watershed_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

## S4 method for signature 'data.frame'
watershed_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

## S4 method for signature 'LAScatalog'
watershed_diameter_raster(
  point_cloud,
  crown_diameter_constant = 0,
  limits = c(0, 1),
  ground_height = NULL,
  smoothing_radius = 5,
  ...
)

Arguments

Value

a terra SpatRaster

Functions

• li_diameter_raster(LAS): Calculate a raster of crown diameter for tree height using li2012 segmentation

• li_diameter_raster(data.frame): Calculate a raster of crown diameter for tree height using li2012 segmentation

• li_diameter_raster(LAScatalog): Calculate a raster of crown diameter for tree height using li2012 segmentation

• watershed_diameter_raster(LAS): Calculate a raster of crown diameter for tree height using watershed segmentation

• watershed_diameter_raster(data.frame): Calculate a raster of crown diameter for tree height using watershed segmentation

• watershed_diameter_raster(LAScatalog): Calculate a raster of crown diameter for tree height using watershed segmentation

Details

The output raster can serve as input for the parameter "crown_diameter_to_tree_height" for the function segment_tree_crowns. It averages the ratio of crown diameter to tree height for a given radius, for trees that were detected with watershed segmentation. The Bioconductor package "EBImage" is required to use this function.

Find all exact matches with at least one of the provided patterns

Description

Find all exact matches with at least one of the provided patterns

Usage

match_any(patterns, targets)

Arguments

Value

A boolean vector of the same length as targets.

Remove small clusters from segmented point cloud

Description

The function takes a point cloud in which trees were segmented, and removes tree clusters that are smaller than a certain radius or a certain height

Usage

remove_small_trees(
  point_cloud,
  min_radius = 1,
  min_height = -Inf,
  crown_id_column_name = "crown_id"
)

## S4 method for signature 'data.frame'
remove_small_trees(
  point_cloud,
  min_radius = 1,
  min_height = -Inf,
  crown_id_column_name = "crown_id"
)

## S4 method for signature 'LAS'
remove_small_trees(
  point_cloud,
  min_radius = 1,
  min_height = -Inf,
  crown_id_column_name = "crown_id"
)

## S4 method for signature 'LAScatalog'
remove_small_trees(
  point_cloud,
  min_radius = 1,
  min_height = -Inf,
  crown_id_column_name = "crown_id"
)

Arguments

Value

lidR LAS

Functions

• remove_small_trees(data.frame): removes small tree clusters in a segmented LAS object.

• remove_small_trees(LAS): removes small tree clusters in a segmented LAS object.

• remove_small_trees(LAScatalog): removes small tree clusters in a segmented LAScatalog.

Details

returns the same las object that was given as input, but with altered crown id's. Trees that are considered too small have their crown id set to NA, and all other crown id's are re-assigned so that they are without gaps

Segment Tree Crowns in a 3D Point Cloud

Description

Employs a variant of the mean shift algorithm (Ferraz et. al, 2016) and after that the DBSCAN algorithm in order to identify tree crowns in airborne lidar data.

Usage

segment_tree_crowns(
  point_cloud,
  crown_diameter_to_tree_height,
  crown_length_to_tree_height,
  crown_diameter_constant = 0,
  crown_length_constant = 0,
  segment_crowns_only_above = 0,
  ground_height = NULL,
  crown_id_column_name = "crown_id",
  centroid_convergence_distance = 0.01,
  max_iterations_per_point = 500,
  dbscan_neighborhood_radius = 0.3,
  min_num_points_per_crown = 5,
  ...
)

## S4 method for signature 'data.frame'
segment_tree_crowns(
  point_cloud,
  crown_diameter_to_tree_height,
  crown_length_to_tree_height,
  crown_diameter_constant,
  crown_length_constant,
  segment_crowns_only_above,
  ground_height,
  crown_id_column_name,
  centroid_convergence_distance,
  max_iterations_per_point,
  dbscan_neighborhood_radius,
  min_num_points_per_crown,
  verbose = TRUE,
  also_return_terminal_centroids = FALSE,
  also_return_all_centroids = FALSE
)

## S4 method for signature 'LAS'
segment_tree_crowns(
  point_cloud,
  crown_diameter_to_tree_height,
  crown_length_to_tree_height,
  crown_diameter_constant,
  crown_length_constant,
  segment_crowns_only_above,
  ground_height,
  crown_id_column_name,
  centroid_convergence_distance,
  max_iterations_per_point,
  dbscan_neighborhood_radius,
  min_num_points_per_crown,
  verbose = TRUE,
  also_return_terminal_centroids = FALSE,
  also_return_all_centroids = FALSE,
  write_crown_id_also_to_file = FALSE,
  crown_id_file_description = crown_id_column_name
)

## S4 method for signature 'LAScatalog'
segment_tree_crowns(
  point_cloud,
  crown_diameter_to_tree_height,
  crown_length_to_tree_height,
  crown_diameter_constant,
  crown_length_constant,
  segment_crowns_only_above,
  ground_height,
  crown_id_column_name,
  centroid_convergence_distance,
  max_iterations_per_point,
  dbscan_neighborhood_radius,
  min_num_points_per_crown,
  write_crown_id_also_to_file = TRUE,
  crown_id_file_description = crown_id_column_name
)

Arguments

Value

The point cloud which was passed to the function but extended with a column/attribute holding for each point the ID of a segmented body. IDs with the value NA indicate that a point was not assigned to any body.

If also_return_terminal_centroids and/or also_return_all_centroids were set to TRUE, a list with at most three named elements in the following order:

segmented_point_cloud

The segmented point cloud which would have been returned directly if also_return_terminal_centroids and also_return_all_centroids had been set to FALSE.

terminal_centroids

If also_return_terminal_centroids was set to TRUE, a point cloud of the same type as the input point cloud holding the terminal centroids calculated with the AMS3D algorithm and two additional columns/attributes. One of these columns/attributes holds IDs of the segmented bodies that the modes belong to and the other (named "point_index") holds indices to the points in the input point cloud.

centroids

If also_return_all_centroids was set to TRUE, a point cloud of the same type as the input point cloud holding the centroids calculated with the AMS3D algorithm and two additional columns/attributes. One of these columns/attributes holds IDs of the segmented bodies that the centroids belong to and the other (named "point_index") holds indices to the points in the input point cloud.

The method for LASCatalogs works just like any other lidR function that accepts them, i.e. it returns either an in-memory LAS object or writes the processed chunks to individual files and returns those file's names. Please refer to the LASCatalog documentation for more details.

Functions

• segment_tree_crowns(data.frame): Segments coordinates stored as three columns in a data.frame or data.table.

• segment_tree_crowns(LAS): Segments the point cloud data of a LAS object.

• segment_tree_crowns(LAScatalog): Segments the point cloud data of a LAScatalog. This method does not support additionally returning centroids. Instead of the verbose parameter use the LAScatalog's progress option (see the LAScatalog documentation -> "Processing options" -> "progress").

How the algorithm works

The basic assumption is that tree crowns form local maxima of point density and height within lidar point clouds. These local maxima are called modes. The algorithm tries to find the nearest mode for each point. This is done by looking at the surrounding points and moving into the direction of the highest point density until the nearest mode is (almost) reached.

The surrounding points are found with a search kernel (a three-dimensional search window) which has the shape of a vertical cylinder. According to literature, the algorithm works best if the search kernel has roughly the size of the surrounding crowns. Therefore, the parameters controlling the kernels dimension are simplistically called crown_diameter_to_tree_height, crown_diameter_constant, and crown_lenght... respectively. The diameter of the kernel is calculated from the height above ground of the kernels center times the value for crown_diameter_to_tree_height, plus the crown_diameter constant. The height of the kernel is calculated respectively.

The direction of the highest point density is found by calculating the average position of all points within the cylinder, the cylinder's so called centroid. In order to move further into the direction of the highest point density, a new cylinder is placed on the centroid and a new centroid is calculated for that cylinder. This continues on until the cylinders "stop moving", i.e. until two subsequently calculated centroids are closer to each other than centroid_convergence_distance. At this point, the most recently calculated centroid, hence called 'terminal centroid', is assumed to be close enough to the mode, so that the original point can be linked to the respective tree top.

It sometimes happens that centroids converge only after a lot of iterations. In order to prevent situations where an excessive number of centroids is calculated for just one point, the parameter max_iterations_per_point is used to stop the centroid calculations after a certain number of them has been performed. Nonetheless, the last centroid found before stopping is still taken as a good enough guess of the nearest mode's position.

After the terminal centroids of the individual points have been calculated, it can be seen that terminal centroids of points belonging to the same tree crown are positioned very close to each other, shortly below the crown's apex. These dense clusters of terminal centroids are identified with the DBSCAN algorithm which assigns a cluster ID to every one of them. The cluster IDs are then finally connected back to the points of the point cloud and used as crown IDs.

The DBSCAN clustering is explained nicely in Wikipedia but here is a quick sketch of what it does: The DBSCAN algorithm classifies points as either core points, border points, or noise and assigns core and border points to the same cluster if they are close enough to at least one other core point of the cluster.

In order to be core points, points need to have enough neighbors. The parameter dbscan_neighborhood_radius determines the radius of the neighborhood and the parameter min_num_points_per_crown determines the minimum number of points in the neighborhood (including the to-be-classified one), which are needed for a core point.

Border points are within the neighborhood of core points but don't have enough neighbors to be core points themselves. Noise points are not within the neighborhood of any core point and also don't have enough neighbors to be core points.

Clusters are identified by iterating over the points and classifying them one by one. For each point the neighborhood is scanned and the point is classified accordingly. If the point is a core or border point, the neighboring points are classified next. As long as it is possible to directly connect to new core or border points in this way, the same cluster ID is assigned to each encountered point.

References

Ferraz, A., S. Saatchi, C. Mallet, and V. Meyer (2016) Lidar detection of individual tree size in tropical forests. Remote Sensing of Environment 183:318–333. doi:10.1016/j.rse.2016.05.028

Ferraz, A., F. Bretar, S. Jaquemond, G. Gonçalves, L. Pereira, M. Tomé, and P. Soares (2012) 3-D mapping of a multi-layered Mediteranean forest using ALS data. Remote Sensing of Environment, 121:210-223. doi:10.1016/j.rse.2012.01.020

Calls the C++ back-end and the DBSCAN algorithm to perform the segmentation

Description

This functions is meant to be used internally by methods of the segment_tree_crowns generic.

Usage

segment_tree_crowns_core(
  coordinate_table,
  segment_crowns_only_above,
  ground_height,
  crown_diameter_to_tree_height,
  crown_length_to_tree_height,
  crown_diameter_constant,
  crown_length_constant,
  verbose,
  centroid_convergence_distance,
  max_iterations_per_point,
  dbscan_neighborhood_radius,
  min_num_points_per_crown,
  also_return_terminal_centroids,
  also_return_all_centroids
)

Arguments

Value

A list with at most three elements:

crown_ids

A vector of IDs of segmented bodies.

terminal_coordinates

If also_return_terminal_centroids was set to TRUE, a data.table with mode coordinates as the second list element. The table has two additional columns:

crown_id

Holds the IDs also returned with the first list element.

point_index

Holds row indices of the original points in the input coordinate_table.

centroid_coordinates

If also_return_all_centroids was set to TRUE, a data.table with centroid coordinates as the last list element. The table has two additional columns:

crown_id

Holds the IDs also returned with the first list element.

point_index

Holds row indices of the original points in the input coordinate_table.

How the algorithm works

The basic assumption is that tree crowns form local maxima of point density and height within lidar point clouds. These local maxima are called modes. The algorithm tries to find the nearest mode for each point. This is done by looking at the surrounding points and moving into the direction of the highest point density until the nearest mode is (almost) reached.

The surrounding points are found with a search kernel (a three-dimensional search window) which has the shape of a vertical cylinder. According to literature, the algorithm works best if the search kernel has roughly the size of the surrounding crowns. Therefore, the parameters controlling the kernels dimension are simplistically called crown_diameter_to_tree_height, crown_diameter_constant, and crown_lenght... respectively. The diameter of the kernel is calculated from the height above ground of the kernels center times the value for crown_diameter_to_tree_height, plus the crown_diameter constant. The height of the kernel is calculated respectively.

The direction of the highest point density is found by calculating the average position of all points within the cylinder, the cylinder's so called centroid. In order to move further into the direction of the highest point density, a new cylinder is placed on the centroid and a new centroid is calculated for that cylinder. This continues on until the cylinders "stop moving", i.e. until two subsequently calculated centroids are closer to each other than centroid_convergence_distance. At this point, the most recently calculated centroid, hence called 'terminal centroid', is assumed to be close enough to the mode, so that the original point can be linked to the respective tree top.

It sometimes happens that centroids converge only after a lot of iterations. In order to prevent situations where an excessive number of centroids is calculated for just one point, the parameter max_iterations_per_point is used to stop the centroid calculations after a certain number of them has been performed. Nonetheless, the last centroid found before stopping is still taken as a good enough guess of the nearest mode's position.

After the terminal centroids of the individual points have been calculated, it can be seen that terminal centroids of points belonging to the same tree crown are positioned very close to each other, shortly below the crown's apex. These dense clusters of terminal centroids are identified with the DBSCAN algorithm which assigns a cluster ID to every one of them. The cluster IDs are then finally connected back to the points of the point cloud and used as crown IDs.

The DBSCAN clustering is explained nicely in Wikipedia but here is a quick sketch of what it does: The DBSCAN algorithm classifies points as either core points, border points, or noise and assigns core and border points to the same cluster if they are close enough to at least one other core point of the cluster.

In order to be core points, points need to have enough neighbors. The parameter dbscan_neighborhood_radius determines the radius of the neighborhood and the parameter min_num_points_per_crown determines the minimum number of points in the neighborhood (including the to-be-classified one), which are needed for a core point.

Border points are within the neighborhood of core points but don't have enough neighbors to be core points themselves. Noise points are not within the neighborhood of any core point and also don't have enough neighbors to be core points.

Clusters are identified by iterating over the points and classifying them one by one. For each point the neighborhood is scanned and the point is classified accordingly. If the point is a core or border point, the neighboring points are classified next. As long as it is possible to directly connect to new core or border points in this way, the same cluster ID is assigned to each encountered point.

Asserts that all files referenced by a LAScatalog have the same scale and offset values.

Description

Asserts that all files referenced by a LAScatalog have the same scale and offset values.

Usage

validate_scale_n_offset_are_consistent(LAScatalog)

Arguments

Ensures that crown IDs are written to output files of the LAScatalog

Description

Issues a warning if the user wanted to write the output to files but not store IDs of segmented bodies.

Usage

validate_write_crown_id_also_to_file_for_LAScatalogs(
  write_crown_id_also_to_file,
  LAScatalog
)

Arguments

Value

A possibly corrected value for write_crown_id_also_to_file.