compute_canopy_openness: Calculate canopy openness

In rcaiman: CAnopy IMage ANalysis

Calculate canopy openness

Description

Calculate canopy openness from a binarized hemispherical image with angular coordinates.

Usage

compute_canopy_openness(bin, z, a, m = NULL, angle_width = 10)

Arguments

bin	logical terra::SpatRaster with one layer. A binarized hemispherical image. See binarize_with_thr() for details.
z	terra::SpatRaster generated with zenith_image().
a	terra::SpatRaster generated with azimuth_image().
m	logical terra::SpatRaster with one layer. A binary mask with TRUE for selected pixels.
angle_width	numeric vector of length one. Angle in deg that must divide both 0–360 and 0–90 into an integer number of segments. Retrieve a set of valid values by running lapply(c(45, 30, 18, 10), function(a) vapply(0:6, function(x) a/2^x, 1)).

Details

Canopy openness is computed following the equation from \insertCiteGonsamo2011;textualrcaiman:

CO = \sum_{i = 1}^{N} GF(\phi_i, \theta_i) \cdot \frac{\cos(\theta_{1,i}) - \cos(\theta_{2,i})}{n_i}

where GF(\phi_i, \theta_i) is the gap fraction in cell i, \theta_{1,i} and \theta_{2,i} are the lower and upper zenith angles of the cell, n_i is the number of cells in the corresponding zenith ring, and N is the total number of cells.

When a mask is provided via the m argument, the equation is adjusted to compensate for the reduced area of the sky vault:

CO = \frac{\sum_{i=1}^{N} GF(\phi_i, \theta_i) \cdot w_i} {\sum_{i=1}^{N} w_i} \quad \text{with} \quad w_i = \frac{\cos(\theta_{1,i}) - \cos(\theta_{2,i})}{n_i}

The denominator ensures that the resulting openness value remains scale-independent. Without this normalization, masking would lead to underestimation, as the numerator alone assumes full hemispherical coverage.

Value

Numeric vector of length one, constrained to the range [0, 1].

References

\insertAllCited

Examples

caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- select_sky_region(z, 0, 70)
bin <- binarize_with_thr(caim$Blue, thr_isodata(caim$Blue[m]))
plot(bin)
compute_canopy_openness(bin, z, a, m, 10)

rcaiman documentation built on Sept. 9, 2025, 5:42 p.m.