snic_animation: Animated visualization of SNIC seeding and segmentation

Description

Generate an animated GIF illustrating how SNIC segmentation evolves as seeds are progressively added. This function runs a sequence of SNIC segmentations using incremental subsets of the provided seeds and compiles the results into an animation.

Usage

snic_animation(
  x,
  seeds,
  file_path,
  max_frames = 100L,
  delay = 10,
  progress = getOption("snic.progress", FALSE),
  ...,
  snic_args = list(compactness = 0.5),
  device_args = list(res = 96, bg = "white")
)

Value

Invisibly, the file path of the generated GIF.

Arguments

x: A SpatRaster representing the image to segment. Dimensions and coordinate reference are inferred automatically.
seeds: A two-column object specifying seed coordinates. If x has a CRS, use columns lat and lon (in EPSG:4326); otherwise use pixel indices (r, c). Typically created with snic_grid or interactively with snic_grid_manual.
file_path: Path where the resulting GIF is saved. The file must not already exist and the parent directory must be writable.
max_frames: Maximum number of frames to render. If there are more seeds than max_frames, only the first max_frames seeds are used.
delay: Per-frame delay in centiseconds (1/100 s). Passed to magick::image_animate(). Default is 10 (0.1 s per frame).
progress: Logical scalar; if TRUE, show the textual progress bar while generating frames.
...: Additional arguments forwarded to snic_plot when drawing each frame (e.g., RGB band indices or palette options).
snic_args: Named list of extra arguments passed to snic on every iteration (e.g., compactness). Arguments x and seeds are reserved and cannot be overridden.
device_args: Named list of arguments passed to grDevices::png() when rendering frames. Defaults to list(res = 96, bg = "white"). Values such as width, height, and filename are managed automatically.

Details

For each iteration, the function adds one seed to the current set and re-runs snic. The segmentation and seed locations are drawn using snic_plot, saved as PNGs, and then combined into an animated GIF using the magick package. This is intended for exploratory and didactic use to illustrate the influence of seed placement and parameters such as compactness.

Examples

Run this code

if (requireNamespace("terra", quietly = TRUE) &&
    terra_is_working() &&
    requireNamespace("magick", quietly = TRUE)) {
    tif_dir <- system.file("demo-geotiff", package = "snic", mustWork = TRUE)
    files <- file.path(
        tif_dir,
        c(
            "S2_20LMR_B02_20220630.tif",
            "S2_20LMR_B04_20220630.tif",
            "S2_20LMR_B08_20220630.tif",
            "S2_20LMR_B12_20220630.tif"
        )
    )
    s2 <- terra::aggregate(terra::rast(files), fact = 8)

    set.seed(42)
    seeds <- snic_grid(s2, type = "random", spacing = 10L, padding = 0L)

    gif_file <- snic_animation(
        s2,
        seeds = seeds,
        file_path = tempfile("snic-demo", fileext = ".gif"),
        max_frames = 20L,
        snic_args = list(compactness = 0.1),
        r = 4, g = 3, b = 1,
        device_args = list(height = 192, width = 256)
    )
    gif_file
}