artificial_stand: Artificial Forest Stand

Description

Create an artificial forest stand of a given area using tree point clouds.

Usage

artificial_stand(
  files,
  n.trees,
  dimension,
  coordinates = NULL,
  sample = TRUE,
  replace = TRUE,
  overlap = NULL,
  rotation = TRUE,
  degrees = NULL,
  n_attempts = 100,
  progress = TRUE,
  plot = TRUE,
  ...
)

Arguments

files

A character vector describing the file name or path of the tree point cloud to use. Those files most contain three columns representing the *XYZ* coordinates of a given point cloud.

n.trees

A positive numeric vector describing the number of point clouds to use.

dimension

A positive numeric vector of length two describing the width and length of the future forest stand.

coordinates

A data.table of two columns and with nrows equal to n.trees describing the basal *XYZ* coordinates of the point clouds in the future stand. If NULL, it uses random basal coordinates based on stand dimension. NULL as default.

sample

Logical. If TRUE, it performs a sample of the files to determine the order to build the artificial stand. If FALSE, it use the file order described in files. TRUE as default.

replace

Logical. If TRUE, it performs a sample selection with a replacement if sample = TRUE to determine the order to build the artificial stand. Useful if the n.trees is lower than length(files). TRUE as default.

overlap

A positive numeric vector between 0 and 100 describing the overlap percentage of a given the tree crowns in the future forest stand. If NULL, the degree of overlap is not controlled.

rotation

Logical. If TRUE, it performs a rotation in yaw axis of the point cloud. TRUE as default.

degrees

A positive numeric vector describing the degrees of rotation of the point clouds in the future stand. The length(degree) should be the same as n.trees. If NULL, it creates random degrees of rotation for each n.trees.

n_attempts

A positive numeric vector of length one describing the number of attempts to provide random coordinates until a tree met the overlap criteria. This needs to be used if coordinate = NULL and overlap != NULL. n_attempts = 100 as default.

progress

Logical, if TRUE displays a graphical progress bar. TRUE as default.

plot

Logical. If TRUE, it provides visual tracking of the distribution of each tree in the artificial stand. This can not be exported as a return object.

...

Parameters passed to fread for the reading of files.

Value

A list which contain a data.table (Trees) with the information of the point clouds used and their current coordinates in the stand, and another data.table with that compile all the point clouds used.

Details

When coordinates = NULL, artifical_stand adds, in sequence, random coordinates to each files in the future stand based on the crown area overlap. That is, first a tree from files is randomly located within the stand dimention, then a second tree from files will be located in the future stand based on the crown area overlap from the previous tree, and so on. If during the random location a given tree does not meet the requirements of overlap, new random coordinates will be provided until the requirements are met.

Since artificial_stand will try to add tree to the stand until the requirements are met, this could lead to an infinite loop if the stand dimention is small or if the trees on files are large or many n.trees. Therefore, the use of n_attempts is recommended to avoid this scenario.

Examples

Run this code

# NOT RUN {
#' #Import an example point cloud
path <- system.file("extdata", "pc_tree.txt", package = "rTLS")

#Creates a stand of 4 trees with 10% of overlap
files <- rep(path, 4)
artificial_stand(files, n.trees = 4, dimension = c(15, 15), overlap = 10)

#Creates a stand of 4 trees with their locations
location <- data.table(X = c(5, 10, 10, 5), Y = c(5, 5, 10, 10))
artificial_stand(files, n.trees = 4, dimension = c(15, 15), coordinates = location)


# }