i.cluster(1)		      Grass User's Manual		  i.cluster(1)



NNAAMMEE
       ii..cclluusstteerr  - An imagery function that generates spectral signatures for
       land cover types in an image using a clustering algorithm.  The result-
       ing  signature file is used as input for _i_._m_a_x_l_i_k, to generate an unsu-
       pervised image classification.
       _(_G_R_A_S_S _I_m_a_g_e _P_r_o_c_e_s_s_i_n_g _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ii..cclluusstteerr
       ii..cclluusstteerr hheellpp
       ii..cclluusstteerr  [--qq]	ggrroouupp==_n_a_m_e  ssuubbggrroouupp==_n_a_m_e  ssiiggffiillee==_n_a_m_e  ccllaasssseess==_v_a_l_u_e
       [sseeeedd==_n_a_m_e] [ssaammppllee==_r_o_w___i_n_t_e_r_v_a_l_,_c_o_l___i_n_t_e_r_v_a_l] [iitteerraattiioonnss==_v_a_l_u_e] [ccoonn--
       vveerrggeennccee==_v_a_l_u_e] [sseeppaarraattiioonn==_v_a_l_u_e] [mmiinn__ssiizzee==_v_a_l_u_e] [rreeppoorrttffiillee==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       _i_._c_l_u_s_t_e_r performs the first pass in the  GRASS	two-pass  unsupervised
       classification  of  imagery,  while the GRASS program _i_._m_a_x_l_i_k executes
       the second pass. Both programs must be run to complete the unsupervised
       classification.


       _i_._c_l_u_s_t_e_r  is  a  clustering  algorithm that reads through the (raster)
       imagery	data  and  builds  pixel  clusters  based  on	the   spectral
       reflectances  of the pixels.  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.  _i_._c_l_u_s_t_e_r 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  clus-
       ters  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  conver-
       gence,  the  maximum  number of iterations, and the row and column sam-
       pling 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_._m_a_x_l_i_k) to classify the	image.
       The  clusters  or  spectral classes result can be related to land cover
       types on the ground.

OOPPTTIIOONNSS
       The program can be run either non-interactively	or  interactively.  It
       will  be  run non-interactively if the user specifies 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) on the command line  using  the
       form:	ii..cclluusstteerr    [--qq]    ggrroouupp==_n_a_m_e   ssuubbggrroouupp==_n_a_m_e   ssiiggffiillee==_n_a_m_e
       ccllaasssseess==_v_a_l_u_e  [sseeeedd==_n_a_m_e]  [ssaammppllee==_r_o_w___i_n_t_e_r_v_a_l_,_c_o_l___i_n_t_e_r_v_a_l]  [iitteerraa--
       ttiioonnss==_v_a_l_u_e]  [ccoonnvveerrggeennccee==_v_a_l_u_e]  [sseeppaarraattiioonn==_v_a_l_u_e]  [mmiinn__ssiizzee==_v_a_l_u_e]
       [rreeppoorrttffiillee==_n_a_m_e]

       where the _g_r_o_u_p should contain the imagery files that the  user	wishes
       to  classify.   The  _s_u_b_g_r_o_u_p is a subset of this group.  The user must
       create a group and subgroup by running the GRASS program _i_._g_r_o_u_p before
       running	_i_._c_l_u_s_t_e_r.   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. The _s_i_g_f_i_l_e is
       the  file  to  contain result signatures which can be used as input for
       _i_._m_a_x_l_i_k.  The classes value is the initial number of  clusters	to  be
       discriminated;  any  parameter values left unspecified are set to their
       default values. Alternatively, the program will be run interactively if
       the user types only _i_._c_l_u_s_t_e_r; in this case the program will prompt the
       user for parameter values using the standard GRASS _p_a_r_s_e_r.

   FFllaaggss::
       --qq     Run quietly.  Suppresses output of program percent-complete mes-
	      sages and the time elapsed from the beginning of the program. If
	      this flag is not used, these messages are printed out.


   PPaarraammeetteerrss::
       ggrroouupp==_n_a_m_e
	      The name of the group file which contains the imagery files that
	      the user wishes to classify.

       ssuubbggrroouupp==_n_a_m_e
	      The  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 run-
	      ning the GRASS program _i_._g_r_o_u_p before running _i_._c_l_u_s_t_e_r.

       ssiiggffiillee==_n_a_m_e
	      The name assigned to output signature file which contains signa-
	      tures of classes and can be used as the input file for the GRASS
	      program _i_._m_a_x_l_i_k for an unsupervised classification.

       ccllaasssseess==_v_a_l_u_e
	      The number of clusters that will initially be identified in  the
	      clustering process before the iterations begin.

       sseeeedd==_n_a_m_e
	      The  name  of a seed signature file is optional. The seed signa-
	      tures are signatures that contain cluster means  and  covariance
	      matrices	which  were  calculated  prior	to  the current run of
	      _i_._c_l_u_s_t_e_r. They may be acquired from a previously run of _i_._c_l_u_s_-
	      _t_e_r  or from a supervised classification signature training site
	      section (e.g., using the signature file output by _i_._c_l_a_s_s).  The
	      purpose  of  seed signatures is to optimize the cluster decision
	      boundaries (means) for the number of clusters specified.

       ssaammppllee==_r_o_w___i_n_t_e_r_v_a_l_,_c_o_l___i_n_t_e_r_v_a_l
	      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).

       iitteerraattiioonnss==_v_a_l_u_e
	      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;
	      the user may want to rerun _i_._c_l_u_s_t_e_r with  a  higher  number  of
	      iterations (see _r_e_p_o_r_t_f_i_l_e).
	      Default: 30

       ccoonnvveerrggeennccee==_v_a_l_u_e
	      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_._c_l_u_s_t_e_r begins iterations that change clus-
	      ter  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 con-
	      vergence 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
	      _r_e_p_o_r_t_f_i_l_e).
	      Default: 98.0

       sseeppaarraattiioonn==_v_a_l_u_e
	      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 _c_o_n_v_e_r_g_e_n_c_e).
	      Default: 0.0

       mmiinn__ssiizzee==_v_a_l_u_e
	      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

       rreeppoorrttffiillee==_n_a_m_e
	      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.


NNOOTTEESS
       Running in command line mode, _i_._c_l_u_s_t_e_r will overwrite the output  sig-
       nature  file and reportfile (if required by the user) without prompting
       if the files existed.

SSEEEE AALLSSOO
       _G_R_A_S_S _T_u_t_o_r_i_a_l_: _I_m_a_g_e _P_r_o_c_e_s_s_i_n_g


       _i_._c_l_a_s_s

       _i_._g_r_o_u_p

       _i_._g_e_n_s_i_g

       _i_._m_a_x_l_i_k

AAUUTTHHOORRSS
       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
       Tao Wen, University of Illinois at Urbana-Champaign, Illinois

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_3 _$



GRASS 5.0							  i.cluster(1)
