estimate_sun_angles: Estimate sun angular coordinates

In rcaiman: CAnopy IMage ANalysis

Estimate sun angular coordinates

Description

Estimates the sun’s zenith and azimuth angles (deg) from a canopy hemispherical photograph, using either direct detection of the solar disk or indirect cues from the circumsolar region.

Usage

estimate_sun_angles(
  r,
  z,
  a,
  bin,
  g,
  angular_radius_sun = 30,
  method = "assume_obscured"
)

Arguments

r	numeric terra::SpatRaster of one layer. Typically the blue band of a canopy image.
z	terra::SpatRaster generated with zenith_image().
a	terra::SpatRaster generated with azimuth_image().
bin	logical terra::SpatRaster of one layer. Binary image where TRUE marks candidate sky pixels. Typically the output of binarize_with_thr().
g	single-layer terra::SpatRaster with integer values. Sky segmentation map produced by sky_grid_segmentation().
angular_radius_sun	numeric vector of length one. Maximum angular radius (in degrees) used to define the circumsolar region.
method	character vector of length one. Estimation mode: "assume_obscured" (default) or "assume_veiled".

Details

This function can operate under two alternative assumptions for estimating the sun position:

Veiled sun

The solar disk is visible or partially obscured; the position is inferred from localized brightness peaks.

Obscured sun

The solar disk is not visible; the position is inferred from radiometric and spatial cues aggregated over the circumsolar region.

When method = "assume_veiled", g and angular_radius_sun are ignored. Estimates refer to positions above the horizon; therefore, estimated angles may require further manipulation if the photograph was acquired under crepuscular light.

Value

Named numeric vector of length two, with names z and a, representing the sun’s zenith and azimuth angles (in degrees).

Note

A scientific article presenting and validating this method is currently under preparation.

Examples

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

bin <- binarize_by_region(r, ring_segmentation(z, 15), "thr_isodata") &
  select_sky_region(z, 0, 88)

g <- sky_grid_segmentation(z, a, 10)
sun_angles <- estimate_sun_angles(r, z, a, bin, g,
                                  angular_radius_sun = 30)
row_col <- row_col_from_zenith_azimuth(z, a,
                                       sun_angles["z"],
                                       sun_angles["a"])
plot(caim$Blue)
points(row_col[1,2], nrow(caim) - row_col[1,1], col = "yellow",
       pch = 8, cex = 3)

## End(Not run)

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