enhance_caim {rcaiman}

Enhance canopy image

Description

This function was first proposed in Díaz and Lencinas (2015). It uses the color perceptual attributes (hue, lightness, and chroma) to enhance the contrast between the sky and plants through fuzzy classification. It applies the next classification rules (here expressed in natural language): clear sky is blue and clouds decrease its chroma; if clouds are highly dense, then the sky is achromatic, and, in such cases, it can be light or dark; everything that does not match this description is not sky. These linguistic rules were translated to math language by means of fuzzy logic. This translation was thoughtfully explained in the aforementioned article.

Usage

enhance_caim(
  caim,
  m = NULL,
  sky_blue = NULL,
  sigma = NULL,
  w_red = 0,
  thr = NULL,
  fuzziness = NULL,
  gamma = NULL
)

Arguments

caim

SpatRaster. The return of a call to read_caim() or read_caim_raw().

m

SpatRaster. A mask. For hemispherical photographs, check mask_hs().

sky_blue

color. Is the target_color argument to be passed to membership_to_color(). Default (NULL) is the equivalent to enter sRGB(0.1, 0.4, 0.8)–the HEX color code is #1A66CC, it can be entered into a search engine (such as Mozilla Firefox) to see a color swatch.

sigma

Numeric vector of length one. Use NULL (default) to estimate it automatically as the euclidean distance between target_color and grey in the CIE LAB color space.

w_red

Numeric vector of length one. Weight of the red channel. A single layer image is calculated as a weighted average of the blue and red channels. This layer is used as lightness information. The weight of the blue is the complement of w_red.

thr

Numeric vector of length one. Location parameter of the logistic membership function. Use NULL to estimate it automatically with thr_isodata().

fuzziness

Numeric vector of length one. This number is a constant value that scales mem. Use NULL to estimate it automatically as the midpoint between the maximum and minimum values of lightness.

gamma

Numeric vector of length one. This is for applying a gamma back correction to the lightness information (see Details and argument w_red).

Details

This is a pixel-wise methodology that evaluates the possibility for a pixel to be member of the class Gap. High score could mean either high membership to sky_blue or, in the case of achromatic pixels, a high membership to values above thr. The algorithm internally uses membership_to_color() and local_fuzzy_thresholding(). The argument sky_blue is the target_color of the former function and its output is the argument mem of the latter function.

The argument sky_blue can be obtained from a photograph that clearly shows the sky. Then, it can be used to process all the others photograph taken with the same equipment, configuration, and protocol.

Via the gamma argument, gbc() can be internally used to back-correct the values passed to local_fuzzy_thresholding().

Value

An object of class SpatRaster (with same pixel dimensions than caim) that should show more contrast between the sky and plant pixels than any of the individual bands from caim; if not, different parameters should be tested.

Note

If you use this function in your research, please cite Díaz and Lencinas (2015) in addition to this package (⁠citation("rcaiman"⁠).

The default value of argument m is the equivalent to enter !is.na(caim$Red). See the Details section in local_fuzzy_thresholding() to understand how this argument can modify the output.

References

Díaz GM, Lencinas JD (2015). “Enhanced gap fraction extraction from hemispherical photography.” IEEE Geoscience and Remote Sensing Letters, 12(8), 1785–1789. doi:10.1109/lgrs.2015.2425931.

See Also

Other Pre-processing Functions: gbc(), local_fuzzy_thresholding(), membership_to_color(), normalize()

Examples

## Not run: 
caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(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)
mblt <- ootb_mblt(r, z, a, bin)

mx <- optim_normalize(caim, mblt$bin)
mn <- min(caim[m])

sky_blue_sample <- crop_caim(caim, c(327, 239), 41, 89)
plotRGB(normalize(sky_blue_sample, mn, mx, TRUE)*255)
sky_blue <- apply(sky_blue_sample[], 2, median) %>%
  normalize(., mn, mx) %>%
  as.numeric() %>%
  matrix(., ncol = 3) %>%
  sRGB()
hex(sky_blue)
# Use hex() to obtain the HEX color code. To see a color swatch, enter the
# HEX code into a search engine (such as Mozilla Firefox).
# NOTE: see extract_dn() for an alternative method to obtain sky_blue

as(sky_blue, "HSV") #saturatio (S) is low
# To obtain same hue (H) but greater saturation
sky_blue <- HSV(239, 0.85, 0.5) %>% as(., "sRGB") %>% as(., "LAB")
hex(sky_blue)

caim <- normalize(caim, mx = mx, force_range = TRUE)
ecaim <- enhance_caim(caim, m, sky_blue = sky_blue)
plot(ecaim)
plot(caim$Blue)

## to compare
plot(apply_thr(ecaim, thr_isodata(ecaim[m])))
plot(apply_thr(caim$Blue, thr_isodata(caim$Blue[m])))

## End(Not run)