Provided by: grass-doc_6.4.3-3_all

**NAME**

i.cluster- Generates spectral signatures for land cover types in an image using a clustering algorithm. The resulting signature file is used as input for i.maxlik, to generate an unsupervised image classification.

**KEYWORDS**

imagery, classification, signatures

**SYNOPSIS**

i.clusteri.clusterhelpi.cluster[-q]group=namesubgroup=namesigfile=nameclasses=integer[seed=name] [sample=row_interval,col_interval] [iterations=integer] [convergence=float] [separation=float] [min_size=integer] [reportfile=name] [--verbose] [--quiet]Flags:-qQuiet--verboseVerbose module output--quietQuiet module outputParameters:group=nameName of input imagery groupsubgroup=nameName of input imagery subgroupsigfile=nameName for output file containing result signaturesclasses=integerInitial number of classes Options:1-255seed=nameName of file containing initial signaturessample=row_interval,col_intervalSampling intervals (by row and col); default: ~10,000 pixelsiterations=integerMaximum number of iterations Default:30convergence=floatPercent convergence Options:0-100Default:98.0separation=floatCluster separation Default:0.0min_size=integerMinimum number of pixels in a class Default:17reportfile=nameName for output file containing final report

**DESCRIPTION**

i.clusterperforms the first pass in the GRASS two-pass unsupervised classification of imagery, while the GRASS programi.maxlikexecutes the second pass. Both programs must be run to complete the unsupervised classification.i.clusteris a clustering algorithm that reads through the (raster) imagery data and builds pixel clusters based on the spectral reflectances of the pixels (see Figure). The pixel clusters are imagery categories that can be related to land cover types on the ground. The spectral distributions of the clusters (which will be the land cover spectral signatures) are influenced by six parameters set by the user. The first parameter set by the user is the initial number of clusters to be discriminated. |Fig.:Landuse/landcoverclusteringofLANDSATscene(simplified)i.clusterstarts 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. These parameters are: the minimum cluster size, minimum cluster separation, the percent convergence, the maximum number of iterations, and 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 are used in the second pass (i.maxlik) to classify the image. The clusters or spectral classes result can be related to land cover types on the ground. The user has to specify the name of group file, the name of 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) where thegroupshould contain the imagery files that the user wishes to classify. Thesubgroupis a subset of this group. The user must create a group and subgroup by running the GRASS programi.groupbefore runningi.cluster. The subgroup should contain only the imagery band files that the user wishes to classify. Note that this subgroup must contain more than one band file. The purpose of the group and subgroup is to collect map layers for classification or analysis. Thesigfileis the file to contain result signatures which can be used as input fori.maxlik. The classes value is the initial number of clusters to be discriminated; any parameter values left unspecified are set to their default values.Flags:-qRun quietly. Suppresses output of program percent-complete messages and the time elapsed from the beginning of the program. If this flag is not used, these messages are printed out.Parameters:group=nameThe name of the group file which contains the imagery files that the user wishes to classify.subgroup=nameThe name of the subset of the group specified in 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 programi.groupbefore runningi.cluster.sigfile=nameThe name assigned to output signature file which contains signatures of classes and can be used as the input file for the GRASS programi.maxlikfor an unsupervised classification.classes=valueThe number of clusters that will initially be identified in the clustering process before the iterations begin.seed=nameThe 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 ofi.cluster. They may be acquired from a previously run ofi.clusteror from a supervised classification signature training site section (e.g., using the signature file output byi.class). The purpose of seed signatures is to optimize the cluster decision boundaries (means) for the number of clusters specified.sample=row_interval,col_intervalThese 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).iterations=valueThis 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; the user may want to reruni.clusterwith a higher number of iterations (seereportfile). Default: 30convergence=valueA 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.clusterbegins 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 (seereportfile). Default: 98.0separation=valueThis 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 (seeconvergence). Default: 0.0min_size=valueThis 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: 17reportfile=nameThe 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**

Running in command line mode,i.clusterwill overwrite the output signature file and reportfile (if required by the user) without prompting if the files existed.

**EXAMPLE**

Preparing the statistics for unsupervised classification of a LANDSAT subscene in North Carolina: g.region rast=lsat7_2002_10 -p # store VIZ, NIR, MIR into group/subgroup i.group group=my_lsat7_2002 subgroup=my_lsat7_2002 \ input=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 i.cluster group=my_lsat7_2002 subgroup=my_lsat7_2002 sigfile=sig_clust_lsat2002 \ classes=10 report=rep_clust_lsat2002.txt To complete the unsupervised classification,i.maxlikis subsequently used.

**SEE** **ALSO**

The GRASS 4ImageProcessingmanuali.class,i.group,i.gensig,i.maxlik

**AUTHORS**

Michael Shapiro, U.S.Army Construction Engineering Research Laboratory Tao Wen, University of Illinois at Urbana-Champaign, IllinoisLastchanged:$Date:2012-12-1604:47:36-0800(Sun,16Dec2012)$Full index © 2003-2013 GRASS Development Team