ootb_sky_cie: Out-of-the-box CIE sky model and raster

In rcaiman: CAnopy IMage ANalysis

Out-of-the-box CIE sky model and raster

Description

Fit and validate a CIE general sky model from a canopy photograph without manual parameter tuning, and return the predicted raster.

Usage

ootb_sky_cie(
  r,
  z,
  a,
  m,
  bin,
  gs,
  min_spherical_dist = seq(0, 12, 3),
  method = c("Nelder-Mead", "BFGS", "CG", "SANN"),
  custom_sky_coef = NULL,
  parallel = TRUE
)

Arguments

r	numeric terra::SpatRaster of one layer. Typically, the blue band of a a canopy photograph. Digital numbers should be linearly related to radiance. See read_caim_raw() 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.
bin	logical terra::SpatRaster with one layer. A binarized hemispherical image. See binarize_with_thr() for details.
gs	list where each element is the output of sky_grid_segmentation(). See Examples for guidance.
min_spherical_dist	numeric vector. Values passed to rem_nearby_points().
method	character vector. Optimization methods for fit_cie_model().
custom_sky_coef	optional numeric vector of length five. If NULL (default), the 15 standard CIE skies are tested as starting conditions. Use this to avoid recomputing the initial step (depending only on method) when testing other inputs.
parallel	logical vector of length one. If TRUE, operations are executed in parallel.

Details

Runs a full pipeline to fit a CIE sky model to radiance from a canopy image:

1. a preliminary estimate of sky digital numbers is attempted using the two-corner method aiming to start with a comprehensive sampling of the sky vault (see method = "detect_bg_dn" of apply_by_direction()).

2. sky point extraction is performed with extract_sky_points(), using information from a binary mask (bin) and post-filtering with rem_nearby_points() and rem_outliers().

3. relative radiance is computed with extract_rr() and fitted to CIE sky models using fit_cie_model(), selecting the best among different initial conditions and optimization methods.

4. model validation is performed via validate_cie_model().

5. raster prediction with cie_image().

Value

List with:

rr_raster

numeric terra::SpatRaster. Predicted relative radiance.

model

list returned by fit_cie_model(). The optimal fit.

model_validation

list returned by validate_cie_model().

dist_to_black

Value of dist_to_black used in extract_sky_points() for the optimal fit.

use_window

logical. Whether a window was used in extract_rr() for the optimal fit.

min_spherical_dist

Value of min_dist used in rem_nearby_points(space = "spherical") for the optimal fit.

sky_points

data.frame with columns row and col. Locations of sky points.

sun_row_col

data.frame with the estimated sun‑disk position in image coordinates.

g

Sky grid used for the optimal fit (as returned by sky_grid_segmentation()).

tested_grids

character vector describing the tested grid configurations.

tested_distances

character vector of tested min_dist values in rem_nearby_points(space = "spherical").

tested_methods

character vector of optimization methods tested in fit_cie_model().

optimal_start

starting parameters selected after testing the 15 CIE skies.

model_up

model fitted to relative radiance detected with the two‑corner method, if that step succeeded; otherwise NULL.

Note

This function is part of a paper under preparation.

Examples

## Not run: 
caim <- read_caim()
r <- caim$Blue
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)

bin <- ootb_bin(caim, z, a, m, TRUE)

set.seed(7)
gs <- list(
  #high res
  sky_grid_segmentation(z, a, 2.25, first_ring_different = TRUE),
  sky_grid_segmentation(z, a, 2.8125, first_ring_different = TRUE),
  #medium res
  sky_grid_segmentation(z, a, 9, first_ring_different = TRUE),
  sky_grid_segmentation(z, a, 10, first_ring_different = TRUE),
  #low res
  sky_grid_segmentation(z, a, 15, first_ring_different = FALSE),
  sky_grid_segmentation(z, a, 18, first_ring_different = FALSE)
)

sky_cie <- ootb_sky_cie(r, z, a, m, bin, gs,
                        method = c("Nelder-Mead", "BFGS", "CG", "SANN"),
                        min_spherical_dist = seq(0, 12, 3),
                        parallel = TRUE)

sky_cie$rr_raster
plot(sky_cie$rr_raster)
sky_cie$model_validation$rmse
plot(sky_cie$model_validation$pred, sky_cie$model_validation$obs)
abline(0,1)

ratio <- r/sky_cie$rr_raster/sky_cie$model$rr$zenith_dn
plot(ratio)
plot(select_sky_region(ratio, 0.95, 1.05))
plot(select_sky_region(ratio, 1.15, max(ratio[], na.rm = TRUE)))

plot(bin)
points(sky_cie$sky_points$col,
       nrow(caim) - sky_cie$sky_points$row, col = 2, pch = 10)


## End(Not run)

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