create_sl_stand: Create a virtual stand from a tree inventory

In SamsaRaLight: Simulate Tree Light Transmission Using Ray-Tracing

Create a virtual stand from a tree inventory

Description

This function builds a virtual forest stand from a user-provided tree inventory. The inventory zone (core polygon) can optionally be modified (e.g., replaced by an enclosing rectangle or an axis-aligned rectangle) before constructing the stand. Trees are spatially shifted so that the resulting inventory zone is centered within a regular grid of square cells. Optionally, additional trees can be added around the core inventory area to match its basal area per hectare.

Usage

create_sl_stand(
  trees_inv,
  cell_size,
  latitude,
  slope,
  aspect,
  north2x,
  sensors = NULL,
  core_polygon_df = NULL,
  modify_polygon = c("none", "rect", "aarect"),
  fill_around = FALSE,
  verbose = TRUE
)

Arguments

trees_inv	A data.frame with one row per tree. See check_inventory for the required structure and validated columns.
cell_size	Numeric. Side length of square cells composing the stand (meters).
latitude	Numeric. Latitude of the stand (degrees).
slope	Numeric. Slope of the plot (degrees).
aspect	Numeric. Aspect of the slope, defined as the azimuth of the downslope direction, clockwise from North (degrees). (0 degrees: North-facing slope, 90 degrees: East-facing slope, 180 degrees: South-facing slope, 270 degrees: West-facing slope)
north2x	Numeric. Clockwise angle from North to the X-axis (degrees). The default 90 degrees corresponds to a Y-axis oriented toward true North (0 degrees: x-axis points North, 90 degrees: x-axis points East, 180 degrees: x-axis points South, 270 degrees: x-axis points West).
sensors	Optional data.frame defining position and height of the sensor within the stand. See check_sensors for the required structure and validated columns.
core_polygon_df	Optional data.frame defining the core inventory polygon. Must contain columns x and y. If NULL, a concave hull is automatically computed from tree positions.
modify_polygon	Character. Defines how the inventory polygon is modified. One of: "none": the core polygon is used as provided or computed. "rect": the polygon is replaced by its minimum enclosing rectangle. "aarect": the polygon is replaced by an axis-aligned enclosing rectangle.
fill_around	Logical. If TRUE, trees are added outside the core polygon until the basal area per hectare of the full stand matches that of the core inventory.
verbose	Logical. If TRUE (default), messages and warnings are printed during processing. If FALSE, output is silent.

Details

The function supports sloping terrain and coordinate system rotation, and returns a fully prepared stand ready for use in the ray-tracing pipeline (see run_sl).

The returned trees data.frame conforms to the inventory format checked by check_inventory, with the following controlled modifications:

• Tree vertical position z is computed from terrain slope and aspect.

• Crown maximum radius height hmax_m is computed when fixed by crown geometry conventions:

  • "P" and "4P": hmax_m = hbase_m

  • "E" and "4E": hmax_m = hbase_m + 0.5 * (h_m - hbase_m)

  For crown types "2E" and "8E", hmax_m must be provided by the user.

• If missing, column dbh_cm is added and filled with NA.

• If missing, crown interception properties (e.g. crown_openness, crown_lad) are added using default values.

All input data.frames (trees_inv, sensors, and core_polygon_df) are automatically checked for coordinate type:

• If x and y columns exist, they are assumed to be planar.

• If lon and lat columns exist, they are converted into planar UTM coordinates automatically using create_xy_from_lonlat().

• The UTM projection (EPSG) is determined from the mean coordinates of trees_inv. All inputs must share the same EPSG; otherwise, the function stops with an error. If conversion occurred, the EPSG is stored in the output.

The function ensures that all trees fall within the core inventory polygon, applying small buffers if necessary to handle numerical precision issues. Invalid polygons are automatically repaired when possible.

When fill_around = TRUE, trees are randomly sampled from the original inventory and positioned outside the core polygon until the target basal area per hectare is reached for the full stand.

Value

A named list with the following elements:

trees

Data.frame of the final tree inventory, including added trees if fill_around = TRUE. The structure matches the inventory format validated by check_inventory, with additional derived variables required for ray tracing. A logical column added_to_fill indicates whether each tree originates from the initial inventory or was added to fill around the inventory zone.

core_polygon

List describing the inventory zone:

• df: data.frame of polygon vertices

• sf: corresponding sf POLYGON

• modify_polygon: applied polygon modification

transform

List of transformation and filling information, including core area, target and final basal area, number of added trees, and applied spatial transformations.

geometry

List describing stand geometry and terrain parameters (cell size, number of cells, slope, aspect, and orientation).

Examples

data_prenovel <- SamsaRaLight::data_prenovel
trees_inv <- data_prenovel$trees

stand <- create_sl_stand(
  trees_inv = trees_inv,
  cell_size = 10,
  latitude = 46.52666,
  slope = 6,
  aspect = 144,
  north2x = 54
)

SamsaRaLight documentation built on April 16, 2026, 5:08 p.m.