ootb_mblt {rcaiman}

Out-of-the-box model-based local thresholding

Description

Out-of-the-box version of the model-based local thresholding (MBLT) algorithm

Usage

ootb_mblt(r, z, a, bin = NULL, fix_cs_sky = FALSE, w = 0.5)

Arguments

r

SpatRaster. A normalized greyscale image. Typically, the blue channel extracted from a canopy photograph. Please see read_caim() and normalize().

z

SpatRaster built with zenith_image().

a

SpatRaster built with azimuth_image().

bin

SpatRaster. This should be a preliminary binarization of r useful for masking pixels that are very likely pure sky pixels.

fix_cs_sky

Logical vector of length one. If it is TRUE, fix_reconstructed_sky() is used to fix the cone-shaped sky.

w

Numeric vector of length one. Weighting parameter from Díaz and Lencinas (2018)'s Equation 1. See thr_mblt()

Details

This function is a hard-coded version of a MBLT pipeline. The MBLT approach proposes a linear relationship between background value and optimal threshold value. This function uses statistical models for sky reconstruction that are able to explain smooth changes in sky brightness, so this function works best under clear skies or overcast conditions. After the reconstruction, local thresholds are linearly predicted from sky brightness values (see thr_mblt()).

As a high-level summary, the function starts producing a working binarized image and ends with a refined binarized image.

The pipeline combines these main functions extract_sky_points_simple() or extract_sky_points(), fit_coneshaped_model(), and fit_trend_surface(). The code can be easily inspected by calling ootb_mblt without parenthesis. Advanced users can use that code as a template.

The MBLT algorithm was first presented in Díaz and Lencinas (2018). The version presented here differs from the original in the following main aspects:

• The original version used a global thresholding method to provide sky points to the cone-shaped model. This one uses extract_sky_points_simple(). Nevertheless, a binarized image can be provided through the bin argument, triggering the use of extract_sky_points() instead of extract_sky_points_simple().

• intercept and slope are automatically obtained using data from sky points and a linear model for accuracy evaluation after Piñeiro et al. (2008). This approach handles inaccuracies in background reconstruction (see thr_mblt() for additional details).

• This version does not use asynchronous acquisition under the open sky, as the original method did. The cone-shaped model (fit_coneshaped_model()) run without a filling source and the cone-shaped sky is used as filling source for trend surface fitting (fit_trend_surface()).

This function searches for black objects against a light background. When regular canopy hemispherical images are provided as input, the algorithm will find dark canopy elements against a bright sky almost everywhere in the picture and, therefore, the result will fit user expectations. However, if a hemispherical photograph taken under the open sky is provided, this algorithm would be still searching black objects against a light background, so the darker portions of the sky will be taken as objects, i.e., canopy. As a consequence, this will not fit users expectations since they are looking for the classes Gap and No-gap, no matter if one of those are not in the picture itself. This kind of error could happen with photographs of open forests for the same working principle.

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

Value

Object from class list containing the binarized image (named bin) and the reconstructed skies (named sky_cs and sky_s).

Note

If NULL is provided as the w argument, the weight is calculated as the coefficient of determination (R^2) of linear model for accuracy evaluation (Piñeiro et al. 2008).

References

Díaz GM, Lencinas JD (2018). “Model-based local thresholding for canopy hemispherical photography.” Canadian Journal of Forest Research, 48(10), 1204–1216. doi:10.1139/cjfr-2018-0006.

Piñeiro G, Perelman S, Guerschman JP, Paruelo JM (2008). “How to evaluate models: Observed vs. predicted or predicted vs. observed?” Ecological Modelling, 216(3-4), 316–322. doi:10.1016/j.ecolmodel.2008.05.006.

See Also

Other Binarization Functions: apply_thr(), obia(), ootb_obia(), regional_thresholding(), thr_isodata(), thr_mblt()

Examples

## Not run: 
path <- system.file("external/DSCN4500.JPG", package = "rcaiman")
caim <- read_caim(path, c(1250, 1020) - 745, 745 * 2, 745 * 2)
z <- zenith_image(ncol(caim), lens("Nikon_FCE9"))
a <- azimuth_image(z)
r <- gbc(caim$Blue)
r <- correct_vignetting(r, z, c(0.0638, -0.101)) %>% normalize()
bin <- find_sky_pixels(r, z, a)
bin <- ootb_mblt(r, z, a, bin)
plot(bin$bin)


## End(Not run)