rcaiman (version 2.0.1)

thr_twocorner: Compute two-corner thresholds

Description

Apply Rosin’s geometric corner detector for unimodal histograms Rosin2001;textualrcaiman to both sides of a bimodal canopy histogram as in Macfarlane’s two-corner approach Macfarlane2011;textualrcaiman. Optional slope-reduction as in Macfarlane is supported. Peak detection can use a prominence-based method or Macfarlane’s original windowed maxima.

Usage

thr_twocorner(
  x,
  sigma = 2,
  slope_reduction = TRUE,
  method = "prominence",
  diagnose = FALSE,
  adjust_par = TRUE
)

Value

A list with:

lp

Lower peak DN.

lc

Lower corner DN (Rosin on the left mode).

tl

Low threshold derived from lc and uc.

tm

Mid threshold derived from lc and uc.

th

High threshold derived from lc and uc.

uc

Upper corner DN (Rosin on the right mode).

up

Upper peak DN.

Arguments

x

numeric vector or a single-column matrix or data.frame able to be coerced to numeric.

sigma

numeric vector of length one. Standard deviation (DN) of the Gaussian kernel used to smooth the histogram prior to peak detection and Rosin’s construction.

slope_reduction

logical vector of length one. If TRUE, apply Macfarlane’s slope-reduction before Rosin’s construction on each side.

method

character vector of length one. Peak detection strategy. One of "prominence" (default) or "macfarlane".

diagnose

logical vector of length one. If TRUE, plot the geometric construction.

adjust_par

logical vector of length one. If TRUE and diagnose = TRUE, temporarily adjust and then restore graphical parameters.

Details

Runs the following pipeline:

1. Build an 8-bit histogram of x after min–max normalization to [0,255].

2. Smooth the histogram with a discrete Gaussian kernel of standard deviation sigma (in DN), using reflective padding to mitigate edge bias.

3. Detect the two mode peaks according to method:

   • method = "prominence": find local maxima via discrete derivatives with plateau handling; find nearest left/right minima; compute peak prominence as \(\min(y[p]-y[L],\,y[p]-y[R])\); filter by minimum prominence and minimum peak separation; select the pair that maximizes \(\min(\mathrm{prom}_\mathrm{left},\,\mathrm{prom}_\mathrm{right})\).

   • method = "macfarlane": search peaks within fixed DN windows as in Macfarlane2011;textualrcaiman. Peak search is performed on the unsmoothed histogram, as originally proposed.

4. Apply Rosin’s corner construction on each mode. The line end at the “first empty bin after the last filled bin” is determined on the unsmoothed histogram Rosin2001;textualrcaiman. If slope_reduction = TRUE and the peak height exceeds the mean of the smoothed histogram, the peak height is reduced to that mean before the geometric construction (Macfarlane’s variant).

5. Derive thresholds: $$T_l = DN_{lc} + (DN_{uc} - DN_{lc}) \times 0.25$$ $$T_m = DN_{lc} + (DN_{uc} - DN_{lc}) \times 0.50$$ $$T_h = DN_{lc} + (DN_{uc} - DN_{lc}) \times 0.75$$ where \(DN_{lc}\) and \(DN_{uc}\) are the lower and upper corners.

When diagnose = TRUE, a geometric construction like the one shown below is sent to the active graphics device.

When diagnose = TRUE and adjust_par = TRUE, the function temporarily adjusts margins to draw the geometric construction in a large square format and restores the previous settings on exit. If adjust_par = FALSE, no parameters are changed and the plot respects the current device/layout.

References

Examples

caim <- conventional_lens_image()
# Prominence-based peak detection, Gaussian smoothing with sigma = 2 DN
thr <- thr_twocorner(caim$Blue[], sigma = 2, slope_reduction = FALSE,
                     method = "prominence")
# Original Macfarlane peak search (for comparison)
thr2 <- thr_twocorner(caim$Blue[], sigma = 2, slope_reduction = TRUE,
                      method = "macfarlane")
data.frame(unlist(thr), unlist(thr2))