Skip to contents

Fast Baatz-Schape multiresolution segmentation

Source: R/baatz_fast_segmenter.R
baatz_fast_segmenter.Rd

Performs a **fast** multiresolution image segmentation inspired by the Baatz-Schape OBIA algorithm.

Usage

baatz_fast_segmenter(
  x,
  scale_param = 50,
  color_weight = 0.9,
  compactness = 0.5,
  band_weights = NULL,
  smooth = 0L,
  output_file = NULL,
  verbose = FALSE
)

Arguments

x

A SpatRaster or a character string giving the path to a raster readable by terra.

scale_param

Numeric scalar controlling the segmentation scale. Larger values tend to produce larger segments. Internally, the C++ routine uses a threshold proportional to scale_param^2 for merge acceptance.

color_weight

Numeric in \([0,1]\) controlling the relative importance of spectral (color) heterogeneity versus shape. Higher values emphasize spectral similarity.

compactness

Numeric in \([0,1]\) controlling the trade-off between compactness and smoothness in the shape criterion.

band_weights

Optional numeric vector with length equal to the number of bands in x. Provides per-band weights for the spectral component. If NULL, all bands are weighted equally.

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 enables verbose output from the underlying C++ routine. If FALSE (default), runs quietly.

Value

A single-layer SpatRaster with integer segment labels in a layer named "segments".

Details

Compared to baatz_segmenter, this function calls a streamlined C++ implementation designed to be substantially faster on small to medium rasters by using efficient region bookkeeping, a priority-queue of merge candidates, and a disjoint-set union (DSU) structure to finalize labels.

The input raster is converted to a dense matrix of \(n_{pixels} \times n_{bands}\). Any missing values are replaced by the corresponding band mean before segmentation.

The C++ routine initializes one region per pixel and builds 4-neighbour adjacencies, tracking the shared boundary length between neighbouring regions. Candidate merges are scored with a *fusion factor* combining:

  • a spectral term based on the increase in within-region variance (computed from per-region band sums and sums of squares), and

  • a shape term that combines compactness and smoothness based on region perimeter and bounding-box perimeter, while accounting for the shared boundary length between the two regions.

Merges are greedily applied in increasing fusion-factor order until no candidate remains below the scale threshold. Final labels are remapped to consecutive integers starting at 1.

Label values are arbitrary and should be treated as categorical.

References

Baatz, M. & Schape, A. (2000). Multiresolution Segmentation: An Optimization Approach for High Quality Multi-Scale Image Segmentation. In: Strobl et al. (eds), Angewandte Geographische Informationsverarbeitung XII.

See also

baatz_segmenter, fh_segmenter, fh_meanshift_segmenter

Examples

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

seg <- baatz_fast_segmenter(
  r,
  scale_param = 50,
  color_weight = 0.9,
  compactness = 0.5,
  verbose = TRUE
)
plot(seg)
} # }