apply_by_direction: Apply a method by direction using a constant field of view

In rcaiman: CAnopy IMage ANalysis

Apply a method by direction using a constant field of view

Description

Applies a method to each set of pixels defined by a direction and a constant field of view (FOV). By default, several built-in methods are available (see method), but a custom function can also be provided via the fun argument.

Usage

apply_by_direction(
  r,
  z,
  a,
  m,
  spacing = 10,
  laxity = 2.5,
  fov = c(30, 40, 50),
  method = c("thr_isodata", "detect_bg_dn", "fit_coneshaped_model",
    "fit_trend_surface_np1", "fit_trend_surface_np6"),
  fun = NULL,
  parallel = FALSE
)

Arguments

r	terra::SpatRaster of one or more layers (e.g., RGB channels or binary masks) in fisheye projection.
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.
spacing	numeric vector of length one. Angular spacing (in degrees) between directions to process.
laxity	numeric vector of length one.
fov	numeric vector. Field of view in degrees. If more than one value is provided, they are tried in order when a method fails.
method	character vector of length one. Built-in method to apply. Available options are "thr_isodata", "detect_bg_dn", "fit_coneshaped_model", "fit_trend_surface_np1", and "fit_trend_surface_np6". Ignored if fun is provided.
fun	NULL (default) or a function accepting r, z, a, and m as input and returning a single-layer terra::SpatRaster object with the same number of rows and columns as its first input, r.
parallel	logical vector of length one. If TRUE, operations are executed in parallel.

Value

terra::SpatRaster object with two layers: "dn" for digital number values and "n" for the number of valid pixels used in each directional estimate.

Note

This function is part of a manuscript currently under preparation.

References

\insertAllCited

Examples

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

# Automatic sky brightness estimation
sky <- apply_by_direction(r, z, a, m, spacing = 10, fov = c(30, 60),
                          method = "detect_bg_dn", parallel = TRUE)
plot(sky$dn)
plot(r / sky$dn)

# Using cone-shaped model
sky_cs <- apply_by_direction(caim, z, a, m, spacing = 15, fov = 60,
                             method = "fit_coneshaped_model", parallel = TRUE)
plot(sky_cs$dn)

# Using trend surface model
sky_s <- apply_by_direction(caim, z, a, m, spacing = 15, fov = 60,
                            method = "fit_trend_surface_np1", parallel = TRUE)
plot(sky_s$dn)

# Using a custom thresholding function
thr <- apply_by_direction(r, z, a, m, 15, fov = c(30, 40, 50),
  fun = function(r, z, a, m) {
    thr <- tryCatch(thr_twocorner(r[m])$tm, error = function(e) NA)
    r[] <- thr
    r
  },
  parallel = TRUE
)
plot(thr$dn)
plot(binarize_with_thr(r, thr$dn))

## End(Not run)

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