Read an image-based face-region mask from a PNG or JPEG

Reads a binary mask image from disk and returns a logical vector of length prod(img_dims) in column-major order, the format the rest of the package expects. White / light pixels (above threshold) become TRUE, dark pixels become FALSE. Use this for image-based masks created with webmorphR::mask_oval(), painted in GIMP, drawn with PowerPoint shapes, or any other tool that produces a binary PNG/JPEG.

Companion to make_face_mask() (parametric oval). Either function returns the same logical-vector shape.

Usage

read_face_mask(path, threshold = 0.5, invert = FALSE, expected_dims = NULL)

Arguments

path

Path to a PNG or JPEG mask image.

threshold

Numeric in [0, 1]. Pixels with luminance above this become TRUE. Default 0.5 (mid-gray).

invert

If TRUE, the mask is inverted (useful for black-on-white masks). Default FALSE.

expected_dims

Optional integer c(nrow, ncol). When set, aborts if the loaded image's dimensions do not match. Useful for catching a wrong-resolution mask before it silently corrupts a downstream computation.

Value

Logical vector of length prod(img_dims), column-major.

See also

make_face_mask() for the parametric oval / sub-region constructor. Mask consumers: infoval(), pixel_t_test(), agreement_map_test(), rel_cluster_test(), rel_icc(), rel_split_half(), rel_loo(), rel_dissimilarity(), run_reliability(), run_discriminability(), run_discriminability_pairwise(), plot_agreement_map(), plot_ci_overlay(). Plot helpers: plot_face_mask(), plot_mask_overlay().

Examples

if (FALSE) { # \dontrun{
fm <- read_face_mask("masks/oval_256.png",
                     expected_dims = c(256L, 256L))
iv <- infoval(signal_matrix, noise_matrix, trial_counts,
              mask = fm, iter = 1000L, seed = 1L)
} # }