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  clus-
       tering algorithm.  The resulting signature file is used as
       input for _i_._m_a_x_l_i_k,  to	generate  an  unsupervised  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]   [ccoonnvveerrggeennccee==_v_a_l_u_e]	 [sseeppaarraa--
       ttiioonn==_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 clus-
       ters 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 signa-
       tures)  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 gen-
       erating spectral signatures for this  number  of  clusters
       and "attempts" to end up with this number of clusters dur-
       ing 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 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_._m_a_x_l_i_k) to classify the image.  The clusters	or  spec-
       tral  classes result can be related to land cover types on
       the ground.

OOPPTTIIOONNSS
       The program can be run either non-interactively or  inter-
       actively.  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  ssuubb--
       ggrroouupp==_n_a_m_e  ssiiggffiillee==_n_a_m_e  ccllaasssseess==_v_a_l_u_e	[sseeeedd==_n_a_m_e] [ssaamm--
       ppllee==_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] [ccoonnvveerr--
       ggeennccee==_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  run-
       ning  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 classifi-
       cation 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 messages 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 running 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 signatures 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 iden-
	      tified  in the clustering process before the itera-
	      tions begin.

       sseeeedd==_n_a_m_e
	      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_._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 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 itera-
	      tions 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 clus-
	      ters  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 min-
	      imum  number  of pixels for which means and covari-
	      ance matrices will be calculated.
	      Default: 17

       rreeppoorrttffiillee==_n_a_m_e
	      The reportfile is an optional parameter which  con-
	      tains  the  result,  i.e.,  the statistics for each
	      cluster. Also included are  the  resulting  percent
	      convergence  for the clusters, the number of itera-
	      tions 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 signature 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, Illi-
       nois

       _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)
