R: Out-of-the-box sky reconstruction

ootb_sky_reconstruction {rcaiman}

R Documentation

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 Li et al. (2016) 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 Lang et al. (2010) 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 Piñeiro et al. (2008), 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

Lang M, Kuusk A, M~ottus M, Rautiainen M, Nilson T (2010). “Canopy gap fraction estimation from digital hemispherical images using sky radiance models and a linear conversion method.” Agricultural and Forest Meteorology, 150(1), 20–29. doi:10.1016/j.agrformet.2009.08.001.

Li DH, Lou S, Lam JC, Wu RH (2016). “Determining solar irradiance on inclined planes from classified CIE (International Commission on Illumination) standard skies.” Energy, 101, 462–470. doi:10.1016/j.energy.2016.02.054.

Piñeiro G, Perelman S, Guerschman JP, Paruelo JM (2008). “How to evaluate models: Observed vs. predicted or predicted vs. observed?” Ecological Modelling, 216(3-4), 316–322. doi:10.1016/j.ecolmodel.2008.05.006.

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)

[Package rcaiman version 1.2.2 Index]