Extract canopy from voxel space.

Extract canopy from VoxelSpace object. The canopy layer is the set of highest voxels with number of hits greater than a user-defined threshold.

Minimum number of hits/echos

Minimum number of hits is set by default to one, meaning that a single echo in a voxel is enough to consider that there is some vegetation. Increasing this threshold will tend to lower the canopy level or introduce some gaps ( i-j-cells with no vegetation). This hit.min filter is stronger than butterfly() since is does not discriminate isolated voxels. A reasonable value for hit.min cannot be suggested ad-hoc since it strongly depends on sampling intensity. Removing butterflies prior to extracting canopy is advisable.

Gaps

For a VoxelSpace with fully defined ground level (see ground()), missing canopy cells can be interpreted as gaps. Conversely if both ground and canopy are missing for a i-j-cell, then it is inconclusive.

Above/below canopy

Function aboveCanopy returns voxel index above canopy level (excluded). Function belowCanopy returns voxel index below canopy level (included).

Canopy Height Model

Function canopyHeight returns ground distance at canopy level, including gaps.

canopy(vxsp, hit.min = 1)

belowCanopy(vxsp, ...)

aboveCanopy(vxsp, ...)

canopyHeight(vxsp, ...)

Arguments

vxsp: a VoxelSpace object.
hit.min: a positive integer, minimum number of hit/echo in a voxel to consider it contains vegetation.
...: additional parameters which will be passed to canopy function. So far only hit.min parameter.

Value

data.table::data.table object with voxel index either below canopy, canopy level or above canopy

Examples

vxsp <- readVoxelSpace(system.file("extdata", "tls_sample.vox", package = "AMAPVox"))
cnp <- canopy(vxsp)
acnp <- aboveCanopy(vxsp)
bcnp <- belowCanopy(vxsp)
# canopy layer included in below canopy subset
all(bcnp[cnp, on=list(i, j, k)] == cnp) # TRUE expected
#> [1] TRUE
vxsp@data[cnp, list(i, j, ground_distance), on=list(i, j, k)]
#>         i     j ground_distance
#>     <int> <int>           <num>
#>  1:     0     1            4.25
#>  2:     0     2            4.25
#>  3:     0     3            4.25
#>  4:     0     4            3.75
#>  5:     1     0            3.75
#>  6:     1     1            4.25
#>  7:     1     2            4.25
#>  8:     1     3            4.25
#>  9:     1     4            3.75
#> 10:     1     5            3.25
#> 11:     2     0            4.25
#> 12:     2     1            4.75
#> 13:     2     2            4.75
#> 14:     2     3            4.25
#> 15:     2     4            4.25
#> 16:     2     5            4.25
#> 17:     3     0            4.75
#> 18:     3     1            4.75
#> 19:     3     2            4.75
#> 20:     3     3            4.75
#> 21:     3     4            4.75
#> 22:     3     5            4.25
#> 23:     4     0            4.75
#> 24:     4     1            4.75
#> 25:     4     2            4.75
#> 26:     4     3            4.75
#> 27:     4     4            4.75
#> 28:     4     5            3.75
#> 29:     5     0            4.25
#> 30:     5     1            4.75
#> 31:     5     2            4.75
#> 32:     5     3            4.75
#> 33:     5     4            4.75
#> 34:     6     1            3.75
#> 35:     6     2            3.75
#>         i     j ground_distance