ootb_sky_reconstruction: Out-of-the-box sky reconstruction

In rcaiman: CAnopy IMage ANalysis

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
)

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 \insertCiteLi2016;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 \insertCiteLang2010;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.

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 \insertCitePineiro2008;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.

References

\insertAllCited

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

## Not run: 
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)

## End(Not run)

rcaiman documentation built on Nov. 15, 2023, 1:08 a.m.