i.cluster(1grass)

okay bestie, come closer 💖 this is i.cluster(1grass) from the GRASS User's Manual, and honestly? it's a whole vibe. it's the first half of the two-part unsupervised classification saga, and we're gonna go through every single flag together, no skips, no shortcuts, periodt. ✨

---

🌸 NAME 🌸

i.cluster — generates spectral signatures for land cover types in an image using a clustering algorithm. 🦋

And the signature file it makes? it becomes the input for i.maxlik, which is what actually generates an unsupervised image classification. so like — these two are a package deal, iykyk. 💅

---

🎀 KEYWORDS 🎀

imagery, classification, signatures

---

✨ SYNOPSIS ✨

the way this command is shaped, bestie:

i.cluster
i.cluster --help
i.cluster group=name subgroup=name signaturefile=name classes=integer
[seed=name]   [sample=rows,cols]   [iterations=integer]
[convergence=float]   [separation=float]   [min_size=integer]
[reportfile=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]
[--ui]

💅 Flags: 💅

• --overwrite — lets your output files just bulldoze existing files and take their place. ruthless. love that for them.
• --help — prints the usage summary so you're not out here guessing. 💖
• --verbose — verbose module output, aka the module will not shut up (affectionately).
• --quiet — quiet module output. the opposite. silence era. 🤫
• --ui — forces the GUI dialog to launch, if you're a click-not-type kind of bestie.

🫶 Parameters: 🫶

• group=name [required] — name of input imagery group.
• subgroup=name [required] — name of input imagery subgroup.
• signaturefile=name [required] — name for the output file that's gonna hold your result signatures.
• classes=integer [required] — the initial number of classes. options: 1-255.
• seed=name — name of file containing initial signatures.
• sample=rows,cols — number of rows and columns over which a sample pixel is taken.
• iterations=integer — maximum number of iterations. default: 30.
• convergence=float — percent convergence. options: 0-100. default: 98.0.
• separation=float — cluster separation. default: 0.0.
• min_size=integer — minimum number of pixels in a class. default: 17.
• reportfile=name — name for the output file containing the final report.

---

🌈 DESCRIPTION 🌈

okay so here's the tea ☕ — i.cluster runs the first pass in the two-pass unsupervised classification of imagery, and the GRASS module i.maxlik runs the second pass. both commands must be run to actually complete the unsupervised classification. you can't just do one and dip. 🙈

i.cluster is a clustering algorithm — a modification of the k-means clustering algorithm, to be precise — that reads through the (raster) imagery data and builds pixel clusters based on the spectral reflectances of the pixels (see Figure). these pixel clusters are imagery categories that can be related to land cover types on the ground. the spectral distributions of the clusters (e.g., land cover spectral signatures) are influenced by six parameters set by the user. and one relevant parameter you set is the initial number of clusters to be discriminated. 👑

Fig.: Land use/land cover clustering of LANDSAT scene (simplified)

i.cluster starts by generating spectral signatures for this number of clusters and "attempts" to end up with this number of clusters during the clustering process. the resulting number of clusters and their spectral distributions, however, are also influenced by the range of the spectral values (category values) in the image files and the other parameters set by the user. those parameters are:

• the minimum cluster size
• minimum cluster separation
• the percent convergence
• the maximum number of iterations
• the row and column sampling intervals

the cluster spectral signatures that result are composed of cluster means and covariance matrices. these cluster means and covariance matrices get used in the second pass (i.maxlik) to classify the image. the clusters — aka spectral classes — that result can be related to land cover types on the ground. 🌱

so the user has to specify: the name of the group file, the name of the subgroup file, the name of a file to contain result signatures, the initial number of clusters to be discriminated, and optionally other parameters (see below). the group should contain the imagery files you wish to classify. the subgroup is a subset of this group. ⭐

heads up bestie: you must create a group and subgroup by running the GRASS program i.group before running i.cluster. no skipping steps. the subgroup should contain only the imagery band files that you wish to classify.

also — note that this subgroup must contain more than one band file. one band is not enough, that's the rule. 😤

the purpose of the group and subgroup is to collect map layers for classification or analysis. the signaturefile is the file that contains the result signatures, which can then be used as input for i.maxlik. the classes value is the initial number of clusters to be discriminated. any parameter values you leave unspecified get set to their default values. easy! 💅

for all raster maps used to generate the signature file, it is recommended to have a semantic label set. use r.support to set semantic labels of each member of the imagery group. signatures generated for one scene are suitable for classification of other scenes as long as they consist of the same raster bands (semantic labels match). if semantic labels are not set, it will only be possible to use the obtained signature file to classify the same imagery group that was used for generating the signatures. so like... set your labels. do it for your future self. 🫶

🦋 Parameters: 🦋

• group=name — the name of the group file which contains the imagery files that the user wishes to classify.
• subgroup=name — the name of the subset of the group specified in the group option, which must contain only imagery band files and more than one band file. the user must create a group and a subgroup by running the GRASS program i.group before running i.cluster. ✨
• signaturefile=name — the name assigned to the output signature file, which contains signatures of classes and can be used as the input file for the GRASS program i.maxlik for an unsupervised classification.
• classes=value — the number of clusters that will initially be identified in the clustering process, before the iterations begin.
• seed=name — the name of a seed signature file is optional. 🌱 the seed signatures are signatures that contain cluster means and covariance matrices which were calculated prior to the current run of i.cluster. they may be acquired from a previous run of i.cluster, or from a supervised classification signature training site section (e.g., using the signature file output by g.gui.iclass). the purpose of seed signatures is to optimize the cluster decision boundaries (means) for the number of clusters specified. so fancy.
• sample=rows,cols — these numbers are optional, with default values based on the size of the data set such that the total pixels to be processed is approximately 10,000 (consider round up). 📈 the smaller these numbers, the larger the sample size used to generate the signatures for the classes defined. yes, smaller numbers = bigger sample. the math is mathing, trust.
• iterations=value — this parameter determines the maximum number of iterations, which is greater than the number of iterations predicted to achieve the optimum percent convergence. the default value is 30. if the number of iterations reaches the maximum designated by the user, you may want to rerun i.cluster with a higher number of iterations (see reportfile). default: 30
• convergence=value — a high percent convergence is the point at which cluster means become stable during the iteration process. the default value is 98.0 percent. when clusters are being created, their means constantly change as pixels are assigned to them and the means are recalculated to include the new pixel. after all clusters have been created, i.cluster begins iterations that change cluster means by maximizing the distances between them. as these means shift, a higher and higher convergence is approached. because means will never become totally static, a percent convergence and a maximum number of iterations are supplied to stop the iterative process. 👑

the percent convergence should be reached before the maximum number of iterations. if the maximum number of iterations is reached, it is probable that the desired percent convergence was not reached. 🫠 the number of iterations is reported in the cluster statistics in the report file (see reportfile). default: 98.0

• separation=value — this is the minimum separation below which clusters will be merged in the iteration process. the default value is 0.0. this is an image-specific number (a "magic" number ✨) that depends on the image data being classified and the number of final clusters that are acceptable. its determination requires experimentation. note that as the minimum class (or cluster) separation is increased, the maximum number of iterations should also be increased to achieve this separation with a high percentage of convergence (see convergence). default: 0.0
• min_size=value — this is the minimum number of pixels that will be used to define a cluster, and is therefore the minimum number of pixels for which means and covariance matrices will be calculated. default: 17
• reportfile=name — the reportfile is an optional parameter which contains the result, i.e., the statistics for each cluster. 🎀 also included are the resulting percent convergence for the clusters, the number of iterations that was required to achieve the convergence, and the separability matrix.

---

💭 NOTES 💭

🌸 Sampling method 🌸

okay so here's the tea, bestie: i.cluster does not cluster all the pixels. it only clusters a sample — that's the sample parameter, iykyk. and the result of that clustering is not that all pixels get assigned to a given cluster either. essentially, only signatures that are representative of a given cluster get generated. so if you run i.cluster on the same data, asking for the same number of classes, but with different sample sizes, you'll likely get slightly different signatures for each cluster on each run. no cap. 😭

🧚 Algorithm used for i.cluster 🧚

the algorithm uses input parameters set by you on the initial number of clusters, the minimum distance between clusters, and the correspondence between iterations that's desired, plus the minimum size for each cluster. it also asks if all pixels are to be clustered, or every "x"th row and "y"th column (that's the sampling thing 💅), the correspondence between iterations desired, and the maximum number of iterations to be carried out.

In the 1st pass, initial cluster means for each band are defined by giving the first cluster a value equal to the band mean minus its standard deviation, and the last cluster a value equal to the band mean plus its standard deviation, with all other cluster means distributed equally spaced in between these. then each pixel gets assigned to the class it's closest to — distance being measured as Euclidean distance. all clusters less than the user-specified minimum distance are then merged. and if a cluster has less than the user-specified minimum number of pixels, all those pixels get reassigned again to the next nearest cluster. new cluster means are calculated for each band as the average of raster pixel values in that band for all pixels present in that cluster. slay ✨

In the 2nd pass, pixels are then again reassigned to clusters based on the new cluster means. the cluster means are then again recalculated. 🔁 this process is repeated until the correspondence between iterations reaches a user-specified level, or till the maximum number of iterations specified is over — whichever comes first. periodt.

---

✨ EXAMPLE ✨

Preparing the statistics for unsupervised classification of a LANDSAT scene within North Carolina project:

# Set computational region to match the scene
g.region raster=lsat7_2002_10 -p
# store VIZ, NIR, MIR into group/subgroup (leaving out TIR)
i.group group=lsat7_2002 subgroup=res_30m \
  input=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70
# generate signature file and report
i.cluster group=lsat7_2002 subgroup=res_30m \
  signaturefile=cluster_lsat2002 \
  classes=10 reportfile=rep_clust_lsat2002.txt

to complete the unsupervised classification, i.maxlik is subsequently used. see example in its manual page. 👑

The signature file obtained in the example above will allow to classify the current imagery group only (lsat7_2002). if you wanna re-use the signature file for the classification of different imagery group(s), set semantic labels for each group member beforehand — i.e., before generating the signature files. Semantic labels are set by means of r.support, as shown below:

# Define semantic labels for all LANDSAT bands
r.support map=lsat7_2002_10 semantic_label=TM7_1
r.support map=lsat7_2002_20 semantic_label=TM7_2
r.support map=lsat7_2002_30 semantic_label=TM7_3
r.support map=lsat7_2002_40 semantic_label=TM7_4
r.support map=lsat7_2002_50 semantic_label=TM7_5
r.support map=lsat7_2002_61 semantic_label=TM7_61
r.support map=lsat7_2002_62 semantic_label=TM7_62
r.support map=lsat7_2002_70 semantic_label=TM7_7
r.support map=lsat7_2002_80 semantic_label=TM7_8

---

👀 SEE ALSO 👀

• Image classification wiki page
• Historical reference also the GRASS GIS 4 Image Processing manual (PDF)
• Wikipedia article on k-means clustering (note that i.cluster uses a modification of the k-means clustering algorithm)

r.support, g.gui.iclass, i.group, i.gensig, i.maxlik, i.segment, i.smap, r.kappa

---

🫶 AUTHORS 🫶

• Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
• Tao Wen, University of Illinois at Urbana-Champaign, Illinois
• Semantic label support: Maris Nartiss, University of Latvia

---

💻 SOURCE CODE 💻

Available at: i.cluster source code (history)

Latest change: Thursday Nov 06 22:27:54 2025 in commit: 298b38614712934179355ea767403d6bfea8f5f9

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 a wrap, bestie 🎀 this was GRASS 8.5.0, i.cluster(1grass) — last touched in that commit on Thursday Nov 06 22:27:54 2025, and the © runs 2003-2026 for the whole GRASS Development Team. go cluster some pixels, you got this 💜🦋✨