complementary_gradients: Calculate complementary gradients

View source: R/complementary_gradients.R

complementary_gradientsR Documentation

Calculate complementary gradients

Description

Compute three color-opponent gradients to enhance the visual separation between sky and canopy in hemispherical photographs, particularly under diffuse light or complex cloud patterns.

Usage

complementary_gradients(caim)

Arguments

caim

numeric terra::SpatRaster with three layers named "Red", "Green", and "Blue". Digital numbers should be linearly related to radiance. See read_caim_raw() for details.

Details

The method exploits chromatic differences between the red, green, and blue bands, following a simplified opponent-color logic. Each gradient is normalized by total brightness and modulated by a logistic contrast function to reduce the influence of underexposed regions:

  • "green_magenta" = (R - G + B) / (R + G + B) · logistic(brightness)

  • "yellow_blue" = (-R - G + B) / (R + G + B) · logistic(brightness)

  • "red_cyan" = (-R + G + B) / (R + G + B) · logistic(brightness)

The logistic(brightness) term is computed as:

\text{logistic}(x) = \frac{1}{1 + \exp\left(-\frac{x - q_{0.1}}{\mathrm{IQR}}\right)}

where q_{0.1} is the 10th percentile of brightness values (x = R + G + B), and IQR is their interquartile range.

This weighting suppresses gradients in poorly exposed regions to reduce spurious values caused by low signal-to-noise ratios.

Value

Numeric terra::SpatRaster with three layers and the same geometry as caim. The layers ("green_magenta", "yellow_blue", "red_cyan") are chromatic gradients modulated by brightness.

Note

This function is part of a paper under preparation.

References

\insertAllCited

Examples

## Not run: 
caim <- read_caim()
com <- complementary_gradients(caim)
plot(com)

## End(Not run)

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