Compare Multiple Image Pairs

Compare multiple pairs of images in batch. Useful for visual regression testing across many screenshots.

Usage

compare_images_batch(pairs, diff_dir = NULL, parallel = FALSE, ...)

Arguments

pairs

A data.frame with columns img1 and img2 containing file paths, or a list of named lists with img1 and img2 elements.

diff_dir

Directory to save diff images. If NULL, no diff images are created. If provided, diff images are named based on the input file names.

parallel

Logical; if TRUE, compare images in parallel using multiple CPU cores. Uses parallel::mclapply on Unix systems (macOS, Linux) and falls back to sequential processing on Windows. Default is FALSE. The number of cores is taken from getOption("mc.cores") (or detected), capped at the number of pairs, and limited to 2 when the _R_CHECK_LIMIT_CORES_ environment variable is "TRUE"/"true" or "warn" (as during R CMD check --as-cran).

...

Additional arguments passed to compare_images().

Value

A tibble (if available) or data.frame with class odiffr_batch, containing one row per comparison with all columns from compare_images() (including error) plus a leading pair_id column. Use summary() to get aggregate statistics. If pairs is empty (a zero-row data.frame or an empty list), an empty odiffr_batch with the same columns is returned.

Details

A failure while comparing one pair (for example, a file that does not exist, cannot be read, or has an unsupported format) does not abort the batch. Instead, that pair is reported as a row with match = FALSE, reason = "error", and the error message in the error column. The same applies to failed worker processes when parallel = TRUE.

See also

summary.odiffr_batch() for summarizing batch results, compare_image_dirs() for directory-based comparison.

Examples

if (FALSE) { # \dontrun{
# Create a data frame of image pairs
pairs <- data.frame(
  img1 = c("baseline/page1.png", "baseline/page2.png"),
  img2 = c("current/page1.png", "current/page2.png")
)

# Compare all pairs
results <- compare_images_batch(pairs, diff_dir = "diffs/")

# Compare in parallel (Unix only)
results <- compare_images_batch(pairs, parallel = TRUE)

# Check which comparisons failed
results[!results$match, ]

# Inspect errors (e.g. unreadable or missing files)
results[results$reason == "error", c("img1", "img2", "error")]
} # }