Skip to contents

SEEDS superpixel segmentation

Source: R/seeds_segmenter.R
seeds_segmenter.Rd

Generates **superpixels** using a SEEDS-like hierarchical approach based on fast **histogram block moves**. The method starts from a regular grid of initial labels and iteratively refines boundaries by proposing block-wise label changes that improve a histogram-based objective.

Usage

seeds_segmenter(
  x,
  step = 10L,
  nbins = 20L,
  block_sizes = c(8L, 4L, 2L, 1L),
  iters_per_level = 5L,
  boundary_samples = 8L,
  alpha = 1,
  smooth = 0L,
  output_file = NULL,
  verbose = FALSE
)

Arguments

x

A SpatRaster with \(\ge 1\) layer (band).

step

Integer \(\ge 1\). Approximate initial superpixel spacing in pixels. Larger values produce fewer (larger) superpixels. Internally this sets the size of the initial grid cells used to initialize labels.

nbins

Integer \(\ge 2\). Number of histogram bins per band. Pixel values are quantized per band based on that band's min/max (computed ignoring NA/NaN).

block_sizes

Integer vector of hierarchical block sizes (coarse-to-fine), e.g. c(8,4,2,1). At each level, candidate moves are proposed over aligned bs x bs blocks, refining boundaries progressively.

iters_per_level

Integer \(\ge 1\). Number of refinement iterations per hierarchy level in block_sizes.

boundary_samples

Integer \(\ge 1\). Sampling effort knob controlling how many boundary-proposal samples are evaluated per iteration. Internally the C++ routine scales the number of samples roughly with the number of labels (K) and caps it for safety.

alpha

Non-negative numeric. Additive smoothing constant for histogram probabilities (Laplace-like smoothing). Higher values reduce sensitivity to small counts and can stabilize results.

smooth

Integer \(\ge 0\). Optional mean filter window size (pixels) applied to the raster prior to mean-shift. If 0 (default), no pre-smoothing is applied. If > 0, a smooth x smooth mean filter is applied via terra::focal().

output_file

Optional character string. If provided, the resulting segmentation raster is written to this file via terra::writeRaster().

verbose

Logical. If TRUE, prints progress messages from the R wrapper and allows the C++ routine to check for user interrupts during the refinement loop. If FALSE, runs quietly.

Value

A single-layer SpatRaster with integer superpixel IDs in a layer named "seeds".

Details

This wrapper is intended to be **tile-friendly** (fast, local updates) and can be used inside tiling strategies for large rasters.

**Implementation notes (C++):**

  • Quantization: each band is quantized into nbins using per-band min/max computed over finite values. NaN values are quantized to -1 and ignored in histogram updates.

  • Initialization: labels are initialized as a regular grid with cell size step (in pixels). Labels start as 0..K-1 in C++, and are returned to R as 1..K.

  • Moves: at each hierarchy level, the algorithm samples boundary pixels, finds a 4-neighbour label competitor, and evaluates whether moving the aligned bs x bs block from region A to region B increases a histogram score. If beneficial, all pixels of label A inside that block are reassigned.

  • Determinism: the sampler uses a deterministic RNG in C++, yielding reproducible results given the same inputs and parameters.

Missing values: unlike other segmenters in rsegm, this SEEDS implementation does not explicitly mask NA pixels. Pixels with NA/NaN do not contribute to histograms, but still receive a label. Consider pre-filling or masking if NA regions should be excluded.

See also

baatz_segmenter, fh_segmenter, meanshift_segmenter

Examples

if (FALSE) { # \dontrun{
library(terra)
r <- terra::rast(sample_raster_path())

spx <- seeds_segmenter(
  r,
  step = 12,
  nbins = 20,
  block_sizes = c(8, 4, 2, 1),
  iters_per_level = 5,
  boundary_samples = 8,
  alpha = 1.0,
  verbose = TRUE
)
plot(spx)
} # }