rcaiman (version 1.2.2)

ootb_sky_reconstruction: Out-of-the-box sky reconstruction

Description

Build an above canopy image from a single below canopy image

Usage

ootb_sky_reconstruction(
  r,
  z,
  a,
  bin,
  filling_source = NULL,
  dist_to_plant = 3,
  sun_coord = NULL,
  general_sky_type = NULL,
  twilight = TRUE,
  rmse = TRUE,
  method = "BFGS",
  try_grids = TRUE,
  thin_points = TRUE,
  refine_sun_coord = TRUE,
  try_optims = TRUE,
  force_sampling = TRUE,
  interpolate = TRUE
)

Value

If a filling source is not provided, the result is an object from the class list that includes the following: (1) the reconstructed sky (SpatRaster), (2) the output produced by fit_cie_sky_model(), (3) the out-of-range index (see fit_cie_sky_model()), (4) sky points that were not involved in obtaining (2), (5) an object from the class lm (see stats::lm()) that is the result of validating (1) with (4) and the method recommended by Pineiro2008;textualrcaiman, and (6) a binarized image produced with (1), the coefficients from (4) and thr_mblt() with apply_thr(), using 'w=0.95'. If a filling source is provided, only a reconstructed sky (SpatRaster) is returned.

Arguments

r

SpatRaster. A normalized greyscale image. Typically, the blue channel extracted from a canopy photograph. Please see read_caim() and normalize().

z

SpatRaster built with zenith_image().

a

SpatRaster built with azimuth_image().

bin

SpatRaster. This should be a preliminary binarization of r useful for masking pixels that are very likely pure sky pixels.

filling_source

SpatRaster. An actual or reconstructed above-canopy image to complement the sky pixels detected through the gaps of r. A photograph taken immediately after or before taking r under the open sky with the same equipment and configuration is a very good option but not recommended under fleeting clouds. The orientation relative to the North must be the same as for r. If it is set to NULL (default), only sky pixels from r will be used as input.

dist_to_plant

Numeric vector of length one or NULL. See extract_sky_points().

sun_coord

An object of class list. The result of a call to extract_sun_coord() or an object with same structure and names. See also row_col_from_zenith_azimuth() in case you want to provide values based on date and time of acquisition and the suncalc package.

general_sky_type

Character vector of length one. It could be any of these: "Overcast", "Clear", or "Partly cloudy". See Table 1 from Li2016;textualrcaiman for additional details.

twilight

Logical vector of length one. If it is TRUE and the initial standard parameters belong to the "Clear" general sky type, sun zenith angles from 90 to 96 degrees will be tested (civic twilight). This is necessary since extract_sun_coord() would mistakenly recognize the center of what can be seen of the solar corona as the solar disk.

rmse

Logical vector of length one. If it is TRUE, the criteria for selecting the best sky model is to choose the one with the lowest root mean square error (RMSE) calculated by using the sky_points argument as the source of reference values. Otherwise, the criteria is to evaluate the whole image by calculating the out-of-range index as \(\sum_{i = 1}^{N}(r_i/sky_i)^2\), where \(r\) is the r argument, \(sky\) is the raster obtained from the fitted model with cie_sky_model_raster() and zenith_dn, \(i\) is the index that represents the position of a given pixel on the raster grid, and \(N\) is the total number of pixels that satisfy either of these inequalities: \(r_i/sky_i<0\) and \(r_i/sky_i>1\).

method

Optimization method to use. See optim.

try_grids

Logical vector of length one.

thin_points

Logical vector of length one.

refine_sun_coord

Logical vector of length one.

try_optims

Logical vector of length one.

force_sampling

Logical vector of length one.

interpolate

Logical vector of length one. If TRUE, interpolate_sky_points() will be used.

Details

This function is a hard-coded version of a pipeline that uses these main functions fit_cie_sky_model() and interpolate_sky_points().

The pipeline is an automatic version of the Lang2010;textualrcaiman method.

Providing a filling source triggers an alternative pipeline in which the sky is fully reconstructed with interpolate_sky_points() after a dense sampling (\(1 \times 1\) degree cells), which is supported by the fact that sky digital numbers will be available for every pixel, either from r gaps or from the filling source.

References

See Also

Other Sky Reconstruction Functions: cie_sky_model_raster(), fit_cie_sky_model(), fit_coneshaped_model(), fit_trend_surface(), fix_reconstructed_sky(), interpolate_sky_points()

Examples

if (FALSE) {
caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)

m <- !is.na(z)
mn <- quantile(caim$Blue[m], 0.01)
mx <- quantile(caim$Blue[m], 0.99)
r <- normalize(caim$Blue, mn, mx, TRUE)

bin <- find_sky_pixels(r, z, a)
bin <- ootb_mblt(r, z, a, bin)
plot(bin$bin)

mx <- optim_normalize(caim, m)

r <- normalize(caim$Blue)
caim <- normalize(caim, mx = mx, force_range = TRUE)

bin <- ootb_obia(caim, z, a, m, HSV(239, 0.85, 0.5), gamma = NULL)
plot(bin)
bin <- ootb_mblt(r, z, a, bin)$bin
plot(bin)

set.seed(7)
sky <- ootb_sky_reconstruction(r, z, a, bin)

sky$sky
sky$validation %>% summary()
plot(sky$sky)
plot(r/sky$sky)
hist(r/sky$sky, xlim = c(0, 2), breaks = 255)
hist((r/sky$sky)[bin], xlim = c(0, 2), breaks = 255)
plot((r/sky$sky)>1.1)

plot(sky$bin)

sky2 <- ootb_sky_reconstruction(r, z, a, sky$bin, sky$sky)
plot(sky2)
plot(r/sky2)
hist(r/sky2, xlim = c(0, 2), breaks = 255)
hist((r/sky2)[sky$bin], xlim = c(0, 2), breaks = 255)
plot((r/sky2)>1.1)
}