Skip to contents

FH mean-shift hybrid geospatial image segmenter

Source: R/fh_meanshift_segmenter.R
fh_meanshift_segmenter.Rd

Performs high-quality, scalable image segmentation by combining a fast graph-based region merging step (Felzenszwalb-Huttenlocher, FH) with a region-level Mean-Shift refinement. This hybrid approach achieves good segmentation quality while remaining computationally efficient for large, multi-band raster images.

Usage

fh_meanshift_segmenter(
  x,
  scale_bands = TRUE,
  smooth = 3,
  fh_k = 0.5,
  fh_min_size = 20,
  eight = TRUE,
  ms_dim = 0,
  ms_ranger = 0.15,
  ms_hs = 12,
  ms_max_iter = 10,
  ms_eps = 0.001,
  mode_merge = 0.6,
  final_min_size = 80,
  output_file = NULL,
  verbose = TRUE
)

Arguments

x

SpatRaster. Input image to segment. May be multi-band (e.g., RGB, VNIR, VNIR+SWIR).

scale_bands

logical, default TRUE. If TRUE, each band is centered and scaled to unit variance prior to segmentation. Strongly recommended for multi-sensor or multi-band data.

smooth

integer, default 3. Size of a square mean-filter kernel applied before segmentation. Set to 0 to disable smoothing. Values between 3 and 5 often reduce speckle and improve boundary stability.

fh_k

numeric, default 0.5. Scale parameter for the FH region-merging step. Larger values produce fewer, larger initial regions; smaller values preserve fine detail.

fh_min_size

integer, default 20. Minimum allowed size (in pixels) for FH regions. Smaller regions are merged during the FH cleanup stage.

eight

logical, default TRUE. If TRUE, uses 8-neighborhood connectivity; otherwise 4-neighborhood.

ms_dim

integer, default 0. Number of dimensions/bands to use in mean shift step.

ms_ranger

numeric, default 0.15. Spectral (range) bandwidth for Mean-Shift clustering of regions. Smaller values preserve spectral distinctions; larger values encourage region merging.

ms_hs

numeric, default 12. Spatial bandwidth (in pixels) used during Mean-Shift refinement. Controls spatial coherence of merged regions.

ms_max_iter

integer, default 10. Maximum number of Mean-Shift iterations per region.

ms_eps

numeric, default 1e-3. Convergence tolerance for Mean-Shift mode estimation.

mode_merge

numeric, default 0.6. Threshold controlling the merging of nearby Mean-Shift modes. Higher values result in more aggressive merging of similar regions.

final_min_size

integer, default 80. Minimum segment size (in pixels) enforced after Mean-Shift refinement. Remaining smaller segments are merged into spectrally closest neighbors.

output_file

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

verbose

Do progress messages? (default: TRUE)

Value

SpatRaster. A single-layer raster where each cell contains an integer segment ID.

Details

The algorithm proceeds in four main stages:

  1. Optional spatial smoothing and per-band normalization.

  2. Initial over-segmentation using the FH graph-based method (fast, noise-robust, edge-preserving).

  3. Region-level Mean-Shift clustering in reduced spectral space to merge spectrally similar regions.

  4. Final region merging and minimum-size enforcement.

Compared to pixel-level Mean-Shift, this hybrid strategy is substantially faster and more memory-efficient, while producing spatially coherent, object-like segments suitable for OBIA workflows.

This function is optimized for large images and is well suited for object-based image analysis (OBIA) of satellite or UAV imagery. For very large rasters (tens to hundreds of millions of pixels), consider tiling.

See also

fh_segmenter

Examples

if (FALSE) { # \dontrun{
library(terra)

img <- rast("multispectral_image.tif")

seg <- fh_meanshift_segmenter(
  img,
  fh_k = 0.4,
  fh_min_size = 30,
  ms_ranger = 0.12,
  ms_hs = 10,
  final_min_size = 100
)

plot(seg)
} # }