bounding_box {lacunr}

Create voxel array

Description

bounding_box() takes a table of voxel data and converts it into a 3-dimensional array, with the original voxels arranged in their correct spatial positions inside of a 3-D "box" of empty voxels. This array can be input directly into lacunarity() to generate lacunarity curves.

Usage

bounding_box(x, threshold = 0, edge_length = NULL)

Arguments

x

A 'lac_voxels' object created by voxelize() (preferred), or a 'lasmetrics3d' object created by lidR::voxel_metrics(). Users can alternatively supply a data.table containing X, Y, Z, and N columns, in which case the argument edge_length is required.

threshold

An integer specifying the minimum number of points to use when determining if a voxel is occupied. The default is 0. bounding_box() retains only those voxels where x$N is greater than threshold.

edge_length

a numeric vector of length 3, specifying the X, Y, and Z dimensions of each voxel. This argument should only be necessary when supplying voxel data generated by a function other than voxelize() or lidR::voxel_metrics().

Details

bounding_box() relies on the spatial coordinates of the input data to determine the dimensions of the resulting array. Noisy point cloud data will often produce "outlier" voxels surrounding points that are far removed from the bulk of the point cloud. These can drastically alter the output, creating an array in which the occupied voxels are surrounded by a large region of empty space. It is highly recommended that users supply a cutoff value for threshold to ideally remove these outliers. More elaborate filtering tools for trimming the point data before voxelization are available in the lidR package.

Value

A 3-dimensional integer array containing values of 0 or 1, representing the occupancy of a given voxel. Occupied voxels (1) are arranged according to their relative positions in 3-dimensional space, and fully encapsulated within a rectangular volume of unoccupied voxels (0). The XYZ positions of the voxels are retained in the array dimnames.

Examples

# Basic usage ---------------------------------------------------------------
# simulate a diagonal line of points with XYZ coordinates
pc <- data.frame(X = as.numeric(0:24), 
                 Y = as.numeric(0:24), 
                 Z = as.numeric(0:24))
# convert point data to cubic voxels of length 5
vox <- voxelize(pc, edge_length = c(5,5,5))
# convert to voxel array
box <- bounding_box(vox)

# Using lidR::voxel_metrics -------------------------------------------------
if (require("lidR")){
# reformat point data into rudimentary LAS object
las <- suppressMessages(lidR::LAS(pc))
# convert to voxels of length 5
vox <- lidR::voxel_metrics(las, ~list(N = length(Z)), res = 5)
# convert to voxel array
box <- bounding_box(vox)
}