centre: Align frames to a common set of reference points

In stopmotion: Build Stop Motion Animations from Image Sequences

Align frames to a common set of reference points

Description

Transforms selected frames so that two user-supplied reference points (e.g. left and right eye positions) map onto the same pixel locations across all frames. The transformation is a full affine warp — rotation, scaling, and translation are applied simultaneously — computed from the two point correspondences via magick::image_distort.

Usage

centre(images, points, reference = 1L, frames = NULL)

center(images, points, reference = 1L, frames = NULL)

Arguments

images	an object of class magick-image to modify
points	a data.frame with columns frame (integer frame index), x (numeric, pixels from the left edge), and y (numeric, pixels from the bottom edge, as returned by locator() after plot(as.raster(images[[i]]))). Exactly two rows per frame are required. Within each frame, the first row is reference point 1 and the second is reference point 2; the pairing must be consistent across frames (e.g. always left-eye first, right-eye second).
reference	integer. The frame whose reference points define the target alignment. All other selected frames are warped to match it. The reference frame itself is left unchanged. Defaults to 1L.
frames	integer vector of frame indices to duplicate. Defaults to NULL, which duplicates all frames.

Value

a magick-image object of the same length as images.

Verbosity

After each operation a message listing the updated frame sequence is printed in interactive sessions. Use stopmotion_verbosity(FALSE) to suppress these messages, or set options(stopmotion.verbose = FALSE) in your script or ‘.Rprofile’.

Examples

  dino_dir <- system.file("extdata", package = "stopmotion")
  images <- read(dir = dino_dir)

  # Manually record eye positions for each frame (e.g. using locator())
  points <- data.frame(
    frame = c(1L, 1L, 2L, 2L, 3L, 3L),
    x     = c(210, 390, 215, 388, 208, 392),
    y     = c(180, 182, 176, 179, 183, 181)
  )

  centre(images = images, points = points, reference = 1L, frames = 1:3)

stopmotion documentation built on March 24, 2026, 5:06 p.m.