optim_dist_to_black: Optimize minimum distance to black pixels

In rcaiman: CAnopy IMage ANalysis

Optimize minimum distance to black pixels

Description

Estimate an optimal buffer (dist_to_black) to keep sampled sky points away from candidate canopy pixels (black pixels).

Usage

optim_dist_to_black(r, z, a, m, bin, g)

Arguments

r	numeric terra::SpatRaster of one layer. Typically the blue band of a canopy image.
z	terra::SpatRaster generated with zenith_image().
a	terra::SpatRaster generated with azimuth_image().
m	logical terra::SpatRaster with one layer. A binary mask with TRUE for selected pixels.
bin	logical terra::SpatRaster of one layer. Binary image where TRUE marks candidate sky pixels. Typically the output of binarize_with_thr().
g	numeric terra::SpatRaster of one layer. Segmentation grid, usually built with sky_grid_segmentation() or chessboard(). Ignored when method = "local_max".

Details

The heuristic seeks the largest buffer that still yields uniform angular coverage. It iteratively decreases dist_to_black while monitoring the percentage of 30 deg sky‑grid cells covered by sampled points. If coverage is low, the buffer is relaxed (and may be removed). This balances border avoidance with representativeness across the sky vault.

Value

numeric vector of length one to be passed as dist_to_black to extract_sky_points(), or NULL if no buffer is advised.

Examples

## Not run: 
caim <- read_caim()
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)
r <- caim$Blue

bin <- binarize_by_region(r, ring_segmentation(z, 15), "thr_isodata") &
  select_sky_region(z, 0, 88)
g <- sky_grid_segmentation(z, a, 10, first_ring_different = TRUE)

dist_to_black <- optim_dist_to_black(r, z, a, m, bin, g)
dist_to_black

bin <- grow_black(bin, 11)
plot(bin)
dist_to_black <- optim_dist_to_black(r, z, a, m, bin, g)
dist_to_black

## End(Not run)

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