i.segment(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

✨ NAME ✨

i.segment — the icon that identifies segments (objects) from imagery data. literally pulling objects out of your pixels bestie 💅

🌸 KEYWORDS 🌸

imagery, segmentation, classification, object recognition

okay so this is i.segment(1grass), straight out of the GRASS User's Manual, and she is that girl 🎀

🦋 SYNOPSIS 🦋

i.segment
i.segment --help
i.segment [-dwap] group=name[,name,...] output=name  [band_suffix=name]
threshold=float  [radius=float]   [hr=float]   [method=string]
[similarity=string]   [minsize=integer]   [memory=memory in MB]
[iterations=integer]   [seeds=name]   [bounds=name]   [goodness=name]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

  • -d — use 8 neighbors (3x3 neighborhood) instead of the default 4 neighbors for each pixel. more friends per pixel, more opinions, no cap 🫶
  • -w — weighted input, do not perform the default scaling of input raster maps. she's already doing the math herself, leave her alone 💅
  • -a — use adaptive bandwidth for mean shift. the range (spectral) bandwidth gets adapted for each moving window ✨
  • -p — use progressive bandwidth for mean shift. spatial bandwidth goes ⬆️ up, range (spectral) bandwidth goes ⬇️ down, in each iteration. the way she changes mid-run is giving main character energy
  • --overwrite — allow output files to overwrite existing files. bestie this one is permanent, be so fr before you use it 💀
  • --help — print usage summary
  • --verbose — verbose module output. she will yap (affectionately) 🗣️
  • --quiet — quiet module output. she will NOT yap 🙈
  • --ui — force launching GUI dialog

🧚 Parameters 🧚

  • group=name[,name,...] — [required] name of input imagery group or raster maps. this is the group chat you're putting to work 💜
  • output=name — [required] name for output raster map
  • band_suffix=name — suffix for output bands with modified band values. also: name for output raster map
  • threshold=float — [required] difference threshold between 0 and 1. threshold = 0 merges only identical segments; threshold = 1 merges all. extremes literally only, pick a lane 🌈
  • radius=float — spatial radius in number of cells. must be >= 1, only cells within spatial bandwidth are considered for mean shift. default: 1.5 ⭐
  • hr=float — range (spectral) bandwidth [0, 1]. only cells within range (spectral) bandwidth are considered for mean shift. range bandwidth is used as conductance parameter for adaptive bandwidth 🔥
  • method=string — segmentation method. options: region_growing, mean_shift. default: region_growing
  • similarity=string — similarity calculation method. options: euclidean, manhattan. default: euclidean
  • minsize=integer — minimum number of cells in a segment. the final step will merge small segments with their best neighbor. options: 1-100000. default: 1
  • memory=memory in MB — maximum memory to be used (in MB). cache size for raster rows. default: 300
  • iterations=integer — maximum number of iterations
  • seeds=name — name for input raster map with starting seeds 🌱
  • bounds=name — name of input bounding/constraining raster map. must be integer values, each area will be segmented independent of the others 🚧
  • goodness=name — name for output goodness of fit estimate map

💖 DESCRIPTION 💖

so i.segment identifies segments (objects) from imagery data. periodt.

image segmentation, aka object recognition, is the whole process of grouping similar pixels into unique segments — also called objects. the literature describes boundary and region based algorithms, and rn a region growing and merging algorithm is what's implemented here.

every object found during segmentation gets its own unique ID, and it's a collection of contiguous pixels that meet some criteria. now lowkey the contrast with image classification matters: in classification, all pixels similar to each other get the same class and they do NOT need to be contiguous. seg different vibe entirely ✨

the segmentation results can serve on their own, or they can be a preprocessing step for image classification. and ngl that preprocessing step is doing real work: she can reduce noise and speed up the classification 🔥

🌈 NOTES 🌈

🌱 Region Growing and Merging

this algorithm goes through all the current segments in the raster map, sequentially, one at a time. for the current segment and each of its neighbors, the similarity is calculated with the given distance formula. segments will be merged if they meet a number of criteria, including:

  1. the pair is mutually most similar to each other (the similarity distance will be smaller than to any other neighbor), and
  2. the similarity must be lower than the input threshold.

the whole process repeats until no merges are made during a complete pass. not me refreshing the whole raster until nothing changes 😭

💅 Similarity and Threshold

the similarity between segments and unmerged objects decides which objects get merged. smaller distance values indicate a closer match — with a similarity score of zero for identical pixels. soulmates, essentially 🫶

during normal processing, merges are only allowed when the similarity between two segments is lower than the given threshold value. during the final pass, though, if a minimum segment size of 2 or larger is given with the minsize parameter, segments with a smaller pixel count will be merged with their most similar neighbor even if the similarity is greater than the threshold. she's bending the rules at the end, iconic behavior honestly

the threshold must be larger than 0.0 and smaller than 1.0. a threshold of 0 would allow only identical valued pixels to be merged, while a threshold of 1 would allow everything to be merged. and here's the important bit bestie: the threshold is scaled to the data range of the entire input data, not the current computational region. that's what lets you apply the same threshold to different computational regions when you're working on the same dataset, making sure the threshold means the same thing in all subregions. consistency queen 👑

initial empirical tests indicate threshold values of 0.01 to 0.05 are reasonable values to start. it's recommended to start with a low value, e.g. 0.01, and then perform hierarchical segmentation by using the output of the last run as seeds for the next run. glow up in stages, always 🌸

🧮 Calculation Formulas

both Euclidean and Manhattan distances use the normal definition, considering each raster in the image group as a dimension. in future, the distance calculation will also take into account the shape characteristics of the segments. rn though:

the normal distances get multiplied by the input radiometric weight. then an additional contribution is added:

(1-radioweight) * {smoothness * smoothness weight + compactness * (1-smoothness weight)}

where

compactness = Perimeter Length / sqrt( Area )
smoothness = Perimeter Length / Bounding Box

the perimeter length is estimated as the number of pixel sides the segment has. math girlies stay winning 📐✨

🌰 Seeds

the seeds map can be used to provide either seed pixels (random or selected points from which to start the segmentation process) or seed segments. if the seeds are the results of a previous segmentation with lower threshold, hierarchical segmentation can be performed. the program auto-detects the different approaches by itself — no need to explain yourself, she gets it 🙈 any pixels that have identical seed values and are contiguous will be assigned a unique segment ID.

🔢 Maximum number of segments

the current limit with CELL storage used for segment IDs is 2 billion starting segment IDs. segment IDs are assigned whenever a yet unprocessed pixel is merged with another segment. integer overflow can happen for computational regions with more than 2 billion cells and very low threshold values, resulting in many segments. and if integer overflow occurs during region growing, starting segments can be used (created by initial classification or other methods). so basically: know your limits or get humbled 💀

🎯 Goodness of Fit

the goodness of fit for each pixel is calculated as 1 - distance of the pixel to the object it belongs to. the distance is calculated with the selected similarity method. a value of 1 means identical values, perfect fit, and a value of 0 means maximum possible distance, worst possible fit. she's either thriving or she's not, no in between 😭

🦋 Mean shift

mean shift image segmentation consists of 2 steps: anisotrophic filtering and 2. clustering. (yes bestie, the original really wrote it like that, and we respect the author's vision 💅)

for anisotrophic filtering, new cell values are calculated from all pixels not farther than radius pixels away from the current pixel and with a spectral difference not larger than hr. that means pixels that are too different from the current pixel are not considered in the calculation of new pixel values. radius and hr are the spatial and spectral (range) bandwidths for anisotrophic filtering. cell values are iteratively recalculated (shifted to the segment's mean) until the maximum number of iterations is reached or until the largest shift is smaller than threshold.

okay heads up bestie — if input bands have been reprojected, they should not be reprojected with bilinear resampling, because that method causes smooth transitions between objects. more appropriate methods are bicubic or lanczos resampling. choose wisely 💀

🚧 Boundary Constraints

boundary constraints limit the adjacency of pixels and segments. each unique value present in the bounds raster is considered as a mask. so no segments in the final segmented map will cross a boundary — even if their spectral data is very similar. the wall stays up, periodt 🧱

🍓 Minimum Segment Size

to reduce the salt and pepper effect, a minsize greater than 1 will add one additional pass to the processing. during the final pass, the threshold is ignored for any segments smaller then the set size, thus forcing very small segments to merge with their most similar neighbor. a minimum segment size larger than 1 is recommended when using adaptive bandwidth selected with the -a flag. tiny segments get adopted by their bestie, it's giving chosen family 🫶

🌈 EXAMPLES 🌈

okay bestie this is the part where we actually use the thing 🫶 two full walkthroughs, both with real sample data, no cap.

Segmentation of RGB orthophoto

This one is working with the ortho photograph that ships in the NC Sample Dataset. First things first — set up an imagery group:

i.group group=ortho_group input=ortho_2001_t792_1m@PERMANENT

Then shrink the region down to a smaller test region (the resolution comes straight from the input ortho photograph):

g.region -p raster=ortho_2001_t792_1m n=220446 s=220075 e=639151 w=638592

Now let's try out a low threshold and go look at the results:

i.segment group=ortho_group output=ortho_segs_l1 threshold=0.02

And... from a visual inspection, this gives too many segments. 🙈 So we do what any icon does: bump the threshold, use the previous results as seeds, and set a minimum size of 2:

i.segment group=ortho_group output=ortho_segs_l2 threshold=0.05 seeds=ortho_segs_l1 min=2
i.segment group=ortho_group output=ortho_segs_l3 threshold=0.1 seeds=ortho_segs_l2
i.segment group=ortho_group output=ortho_segs_l4 threshold=0.2 seeds=ortho_segs_l3
i.segment group=ortho_group output=ortho_segs_l5 threshold=0.3 seeds=ortho_segs_l4

so here's the tea ☕ the output ortho_segs_l4 with threshold=0.2 still has too many segments, but the output with threshold=0.3 has too few. A threshold value of 0.25 seems to be a good choice — goldilocks core, honestly. 💅

There is also some noise in the image, so next we're gonna force all segments smaller than 10 pixels to be merged into their most similar neighbor — even if they're less similar than our threshold requires. Bold, but necessary.

Set the region to match the entire map(s) in the group:

g.region -p raster=ortho_2001_t792_1m@PERMANENT

Run i.segment on the full map:

i.segment group=ortho_group output=ortho_segs_final threshold=0.25 min=10

Fun lil reality check: processing the entire ortho image with nearly 10 million pixels took about 450 times more than the final run. 😭 the full image does NOT play around.

Segmentation of panchromatic channel

This one uses the panchromatic channel of the Landsat7 scene from the North Carolina sample dataset:

# create group with single channel
i.group group=singleband input=lsat7_2002_80
# set computational region to Landsat7 PAN band
g.region raster=lsat7_2002_80 -p
# perform segmentation with minsize=5
i.segment group=singleband threshold=0.05 minsize=5 \
  output=lsat7_2002_80_segmented_min5 goodness=lsat7_2002_80_goodness_min5
# perform segmentation with minsize=100
i.segment group=singleband threshold=0.05 minsize=100
  output=lsat7_2002_80_segmented_min100 goodness=lsat7_2002_80_goodness_min100
ngl bestie, that second i.segment call is copied exactly as-is and it's got no backslash at the end of the first line — the line break in the source is literally just hanging there. If you're pasting this, add the \ yourself. 🫠

And the verdict from the pictures:

  • Original panchromatic channel of the Landsat7 scene
  • Segmented panchromatic channel, minsize=5
  • Segmented panchromatic channel, minsize=100

✨ TODO ✨

the vibes are immaculate but the work is not done, queen. here's the list:

Functionality

  • Further testing of the shape characteristics (smoothness, compactness) — if it looks good it should be added. (in progress)
  • Malahanobis distance for the similarity calculation.

Use of Segmentation Results

  • Providing updates to i.maxlik so the segmentation output can be used as input for the existing classification functionality.
  • Integration/workflow for r.fuzzy (Addon).

Speed

  • See create_isegs.c

🔖 REFERENCES 🔖

This project was first developed during GSoC 2012 👑 Project documentation, Image Segmentation references, and other information is at the project wiki.

Information about classification in GRASS is at available on the wiki.

👀 SEE ALSO 👀

  • i.segment.stats (addon), i.segment.uspo (addon), i.segment.hierarchical (addon)
  • g.gui.iclass, i.group, i.maxlik, i.smap, r.kappa

💖 AUTHORS 💖

  • Eric Momsen — North Dakota State University
  • Markus Metz (GSoC Mentor)

📦 SOURCE CODE 📦

Available at: i.segment source code (history)

Latest change: Friday Apr 17 01:04:26 2026 in commit: 32a143358df26b2e518b03c7e0d79541e8d1e5b1

Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

and that's the whole page bestie 🎀 this was i.segment(1grass) from the GRASS 8.5.0 manual, freshly touched on Friday Apr 17 01:04:26 2026 ✨ go segment something pretty, you've got this 💜🦋

📦 where this page comes from