ootb_obia {rcaiman}

Out-of-the-box object-based image analysis of canopy photographs

Description

Out-of-the-box version of methods first presented in Díaz and Lencinas (2015).

Usage

ootb_obia(
  caim,
  z = NULL,
  a = NULL,
  m = NULL,
  sky_blue = NULL,
  w_red = 0,
  gamma = 2.2
)

Arguments

caim

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

z

SpatRaster built with zenith_image().

a

SpatRaster built with azimuth_image().

m

SpatRaster. Default (NULL) is the equivalent to enter !is.na(z) for hemispherical photography, or enter !is.na(caim$Red) for restricted view photography.

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.

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.

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 function is a hard-coded version of a pipeline that combines these main functions mask_sunlit_canopy(), enhance_caim(), polar_qtree()/qtree(), and obia(). The code can be easily inspected by calling ootb_obia –no parenthesis. Advanced users can use that code as a template.

Pixels from the synthetic layer returned by obia() that lay between 0 and 1 are assigned to the class plant only if they comply with the following conditions:

• Their values are equal to 0 after defuzzify() with a sky grid segmentation of 10 degrees.

• Their values are equal to 0 after apply_thr() with a threshold computed with thr_isodata().

• They are not exclusively surrounded by sky pixels.

Use the default values of z and a to process restricted view photographs.

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

Value

An object of class SpatRaster with values 0 and 1.

References

Díaz GM (2023). “Optimizing forest canopy structure retrieval from smartphone-based hemispherical photography.” Methods in Ecology and Evolution, 14(3), 875–884. doi:10.1111/2041-210x.14059.

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 Binarization Functions: apply_thr(), obia(), ootb_mblt(), regional_thresholding(), thr_isodata(), thr_mblt()

Examples

## Not run: 
# ==============================================
# Circular Hemispherical Photo (from a raw file)
# ==============================================

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)
plot(mblt$bin)

mx <- optim_normalize(caim, mblt$bin)
ncaim <- normalize(caim, mx = mx, force_range = TRUE)
plotRGB(ncaim*255)
plotRGB(normalize(caim)*255)
percentage_of_clipped_highlights(ncaim$Blue, m)

bin2 <- ootb_obia(ncaim, z, a, gamma = NULL)
plot(bin2)

# =====================================
# Hemispherical Photo from a Smartphone
# =====================================

path <- system.file("external/APC_0581.jpg", package = "rcaiman")
caim <- read_caim(path) %>% normalize()
z <- zenith_image(2132/2, c(0.7836, 0.1512, -0.1558))
a <- azimuth_image(z)
zenith_colrow <- c(1063, 771)/2
caim <- expand_noncircular(caim, z, zenith_colrow) %>% normalize()
m <- !is.na(caim$Red) & !is.na(z)
caim[!m] <- 0

bin <- ootb_obia(caim, z, a)
plot(bin)

# ============================
# Restricted View Canopy Photo
# ============================

path <- system.file("external/APC_0020.jpg", package = "rcaiman")
caim <- read_caim(path) %>% normalize()

bin <- ootb_obia(caim)
plot(bin)

## End(Not run)