Generate a background condition for masking

Internal function for parsing potential background conditions. Prioritizes transparency masking if conflicting options are provided. See details.

Usage

backgroundCondition(
  lower = NULL,
  upper = NULL,
  center = NULL,
  radius = NULL,
  transparent = NULL,
  alpha_channel = FALSE,
  quietly = TRUE
)

Arguments

lower, upper

RGB triplet ranges for setting a bounding box of pixels to mask.

center, radius

RGB triplet and radius (as a proportion) for masking pixels within a spherical range.

transparent

Logical or NULL. Use transparency to mask? Requires an alpha channel.

alpha_channel

Logical. Is there an alpha channel?

quietly

Logical. Print a message about background masking parameters?

Value

A list with background masking parameters. Can be one of 4 classes:

1. bg_rect: If lower and upper are specified.

2. bg_sphere: If center and radius are specified.

3. bg_t: If transparent is TRUE and there is an alpha channel with transparent pixels.

4. bg_none: If no background masking is specified (or transparency was specified but there are no transparent pixels).

Details

Prioritizes transparency. If transparency = TRUE but other options (such as lower and upper) are specified, then only transparent pixels will be masked. If transparency = TRUE but there is no alpha channel (as in a JPEG image), this flag is ignored and other options (lower and upper or center and radius) are used instead.

This is an internal convenience function sourced by backgroundIndex().

Examples

# masking a white background:
backgroundCondition(lower = rep(0.9, 3), upper = rep(1, 3), quietly = FALSE)
#> Masking pixels in range:
#>  R: 0.9-1; G: 0.9-1; B: 0.9-1
#> $lower
#> [1] 0.9 0.9 0.9
#> 
#> $upper
#> [1] 1 1 1
#> 
#> attr(,"class")
#> [1] "bg_rect"

# masking transparent pixels:
backgroundCondition(transparent = TRUE, alpha_channel = TRUE, quietly = FALSE)
#> Using transparency to mask pixels
#> [1] "transparent"
#> attr(,"class")
#> [1] "bg_t"

# oops, no alpha channel:
backgroundCondition(transparent = TRUE, alpha_channel = FALSE, quietly = FALSE)
#> Using all pixels
#> [1] NA
#> attr(,"class")
#> [1] "bg_none"

# oops, no alpha channel, but with white background as a fallback:
backgroundCondition(lower = rep(0.9, 3), upper = rep(1, 3),
                    transparent = TRUE, alpha_channel = FALSE,
                    quietly = FALSE)
#> Masking pixels in range:
#>  R: 0.9-1; G: 0.9-1; B: 0.9-1
#> $lower
#> [1] 0.9 0.9 0.9
#> 
#> $upper
#> [1] 1 1 1
#> 
#> attr(,"class")
#> [1] "bg_rect"