artificial_stand: Artificial Forest Stand
In rTLS: Processing of Point Clouds Derived from Terrestrial Laser Scanning

artificial_stand

R Documentation

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`.

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.

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.

Author(s)

J. Antonio Guzmán Q.

Examples

#' #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)

rTLS documentation built on Dec. 28, 2022, 1:28 a.m.