Debian Codegraph @

imagery/i.cluster/i.cluster.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <em>i.cluster</em> performs the first pass in the two-pass
4 unsupervised classification of imagery, while the GRASS module <em>
5 <a href="i.maxlik.html">i.maxlik</a></em> executes the second pass.
6 Both commands must be run to complete the unsupervised classification.
7
8 <p>
9 <em>i.cluster</em> is a clustering algorithm (a modification of the
10 <i>k</i>-means clustering algorithm) that reads through the (raster) imagery
11 data and builds pixel clusters based on the spectral reflectances of the
12 pixels (see Figure).
13 The pixel clusters are imagery categories that can be related
14 to land cover types on the ground. The spectral distributions of the
15 clusters (e.g., land cover spectral signatures) are influenced by six
16 parameters set by the user. A relevant parameter set by the user is the
17 initial number of clusters to be discriminated.
18
19 <p>
20 <center>
21 <img src="i_cluster_landsat_clustering.png" norder="1"><br>
22 <table border="0" width=590>
23 <tr><td><center>
24 <i>Fig.: Land use/land cover clustering of LANDSAT scene (simplified)</i>
25 </center></td></tr>
26 </table>
27 </center>
28
29 <p>
30 <em>i.cluster</em> starts by generating spectral signatures
31 for this number of clusters and "attempts" to end up with
32 this number of clusters during the clustering process. The
33 resulting number of clusters and their spectral
34 distributions, however, are also influenced by the range of
35 the spectral values (category values) in the image files
36 and the other parameters set by the user. These parameters
37 are: the minimum cluster size, minimum cluster separation,
38 the percent convergence, the maximum number of iterations,
39 and the row and column sampling intervals.
40
41 <p>
42 The cluster spectral signatures that result are composed of
43 cluster means and covariance matrices. These cluster means
44 and covariance matrices are used in the second pass
45 (<em><a href="i.maxlik.html">i.maxlik</a></em>) to
46 classify the image. The clusters or spectral classes
47 result can be related to land cover types on the ground.
48
49 The user has to specify the name of group file, the name of subgroup
50 file, the name of a file to contain result signatures, the
51 initial number of clusters to be discriminated, and
52 optionally other parameters (see below)
53 where the <em>group</em> should contain the imagery files
54 that the user wishes to classify. The <em>subgroup</em> is
55 a subset of this group. The user must create a group and
56 subgroup by running the GRASS program
57
58 <em><a href="i.group.html">i.group</a></em>
59
60 before running <em>i.cluster</em>. The subgroup should
61 contain only the imagery band files that the user wishes to
62 classify. Note that this subgroup must contain more than
63 one band file. The purpose of the group and subgroup is to
64 collect map layers for classification or analysis. The
65 <em>signaturefile</em> is the file to contain result signatures
66 which can be used as input for
67
68 <em><a href="i.maxlik.html">i.maxlik</a></em>.
69
70 The classes value is the initial number of clusters to be
71 discriminated; any parameter values left unspecified are
72 set to their default values.
73
74 <p>
75 For all raster maps used to generate signature file it is recommended
76 to have semantic label set.
77 Use <em><a href="r.support.html">r.support</a></em> to set
78 semantc labels of each member of the imagery group.
79 Signatures generated for one scene are suitable for classification
80 of other scenes as long as they consist of same raster bands
81 (semantic labels match). If semantic labels are not set, it will be
82 possible to use obtained signature file to classify only the same
83 imagery group used for generating signatures.
84
85 <h3>Parameters:</h3>
86
87 <dl>
88 <dt><b>group=</b><em>name</em>
89
90 <dd>The name of the group file which contains the imagery
91 files that the user wishes to classify.
92
93 <dt><b>subgroup=</b><em>name</em>
94
95 <dd>The name of the subset of the group specified in group
96 option, which must contain only imagery band files and more
97 than one band file. The user must create a group and a
98 subgroup by running the GRASS program
99
100 <em><a href="i.group.html">i.group</a></em>
101
102 before
103 running <em>i.cluster</em>.
104
105 <dt><b>signaturefile=</b><em>name</em>
106
107 <dd>The name assigned to output signature file which
108 contains signatures of classes and can be used as the input
109 file for the GRASS program
110 <em><a href="i.maxlik.html">i.maxlik</a></em>
111 for an unsupervised classification.
112
113 <dt><b>classes=</b><em>value</em>
114
115 <dd>The number of clusters that will initially be
116 identified in the clustering process before the iterations
117 begin.
118
119 <dt><b>seed=</b><em>name</em>
120
121 <dd>The name of a seed signature file is optional. The seed
122 signatures are signatures that contain cluster means and
123 covariance matrices which were calculated prior to the
124 current run of <em>i.cluster</em>. They may be acquired
125 from a previously run of <em>i.cluster</em> or from a
126 supervised classification signature training site section
127 (e.g., using the signature file output by
128
129 <em><a href="g.gui.iclass.html">g.gui.iclass</a></em>).
130
131 The purpose of seed signatures is to optimize the cluster
132 decision boundaries (means) for the number of clusters
133 specified.
134
135 <dt><b>sample=</b><em>rows,cols</em>
136
137 <dd>These numbers are optional with default values based on
138 the size of the data set such that the total pixels to be
139 processed is approximately 10,000 (consider round up). The
140 smaller these numbers, the larger the sample size used to
141 generate the signatures for the classes defined.
142
143 <dt><b>iterations=</b><em>value</em>
144
145 <dd>This parameter determines the maximum number of
146 iterations which is greater than the number of iterations
147 predicted to achieve the optimum percent convergence. The
148 default value is 30. If the number of iterations reaches
149 the maximum designated by the user; the user may want to
150 rerun <em>i.cluster</em> with a higher number of iterations
151 (see <a href="#reportfile"><em>reportfile</em></a>).
152
153 <br>
154
155 Default: 30
156
157 <a name="convergence"></a>
158 <dt><b>convergence=</b><em>value</em>
159
160 <dd>A high percent convergence is the point at which
161 cluster means become stable during the iteration process.
162 The default value is 98.0 percent. When clusters are being
163 created, their means constantly change as pixels are
164 assigned to them and the means are recalculated to include
165 the new pixel. After all clusters have been created,
166 <em>i.cluster</em> begins iterations that change cluster
167 means by maximizing the distances between them. As these
168 means shift, a higher and higher convergence is
169 approached. Because means will never become totally
170 static, a percent convergence and a maximum number of
171 iterations are supplied to stop the iterative process. The
172 percent convergence should be reached before the maximum
173 number of iterations. If the maximum number of iterations
174 is reached, it is probable that the desired percent
175 convergence was not reached. The number of iterations is
176 reported in the cluster statistics in the report file
177 (see <a href="#reportfile"><em>reportfile</em></a>).
178
179 <br>
180
181 Default: 98.0
182
183 <dt><b>separation=</b><em>value</em>
184
185 <dd>This is the minimum separation below which clusters
186 will be merged in the iteration process. The default value
187 is 0.0. This is an image-specific number (a "magic" number)
188 that depends on the image data being classified and the
189 number of final clusters that are acceptable. Its
190 determination requires experimentation. Note that as the
191 minimum class (or cluster) separation is increased, the
192 maximum number of iterations should also be increased to
193 achieve this separation with a high percentage of
194 convergence
195 (see <a href="#convergence"><em>convergence</em></a>).
196
197 <br>
198 Default: 0.0
199
200 <dt><b>min_size=</b><em>value</em>
201
202 <dd>This is the minimum number of pixels that will be used
203 to define a cluster, and is therefore the minimum number of
204 pixels for which means and covariance matrices will be
205 calculated.
206
207 <br>
208 Default: 17
209
210 <a name="reportfile"></a>
211 <dt><b>reportfile=</b><em>name</em>
212
213 <dd>The reportfile is an optional parameter which contains
214 the result, i.e., the statistics for each cluster. Also
215 included are the resulting percent convergence for the
216 clusters, the number of iterations that was required to
217 achieve the convergence, and the separability matrix.
218 </dl>
219
220 <h2>NOTES</h2>
221
222 <h3>Sampling method</h3>
223
224 <em>i.cluster</em> does not cluster all pixels, but only a sample (see
225 parameter <b>sample</b>). The result of that clustering is not that all
226 pixels are assigned to a given cluster; essentially, only signatures which are
227 representative of a given cluster are generated. When running <em>i.cluster</em>
228 on the same data asking for the same number of classes, but with different
229 sample sizes, likely slightly different signatures for each cluster are
230 obtained at each run.
231
232 <h3>Algorithm used for i.cluster</h3>
233
234 <!-- cited after Harini Nagendra, "algorithm used for i.cluster"
235 https://lists.osgeo.org/pipermail/grass-user/1997-December/000912.html
236 -->
237
238 The algorithm uses input parameters set by the user on the
239 initial number of clusters, the minimum distance between clusters, and the
240 correspondence between iterations which is desired, and minimum size for
241 each cluster. It also asks if all pixels to be clustered, or every "x"th row
242 and "y"th column (sampling), the correspondence between iterations
243 desired, and the maximum number of iterations to be carried out.
244 <p>
245 In the 1st pass, initial cluster means for each band are defined by giving
246 the first cluster a value equal to the band mean minus its standard
247 deviation, and the last cluster a value equal to the band mean plus its
248 standard deviation, with all other cluster means distributed equally
249 spaced in between these. Each pixel is then assigned to the class which it
250 is closest to, distance being measured as Euclidean distance. All clusters
251 less than the user-specified minimum distance are then merged. If a
252 cluster has less than the user-specified minimum number of pixels, all those
253 pixels are again reassigned to the next nearest cluster. New cluster means
254 are calculated for each band as the average of raster pixel values in that
255 band for all pixels present in that cluster.
256 <p>
257 In the 2nd pass, pixels are then again reassigned to clusters based on new
258 cluster means. The cluster means are then again recalculated. This
259 process is repeated until the correspondence between iterations reaches a
260 user-specified level, or till the maximum number of iterations specified is
261 over, whichever comes first.
262
263 <h2>EXAMPLE</h2>
264
265 Preparing the statistics for unsupervised classification of
266 a LANDSAT scene within North Carolina project:
267
268 <div class="code"><pre>
269 # Set computational region to match the scene
270 g.region raster=lsat7_2002_10 -p
271
272 # store VIZ, NIR, MIR into group/subgroup (leaving out TIR)
273 i.group group=lsat7_2002 subgroup=res_30m \
274 input=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70
275
276 # generate signature file and report
277 i.cluster group=lsat7_2002 subgroup=res_30m \
278 signaturefile=cluster_lsat2002 \
279 classes=10 reportfile=rep_clust_lsat2002.txt
280 </pre></div>
281
282 To complete the unsupervised classification, <em>i.maxlik</em> is subsequently used.
283 See example in its manual page.
284
285 <p>
286 The signature file obtained in the example above will allow
287 to classify the current imagery group only (lsat7_2002).
288 If the user would like to re-use the signature file for the
289 classification of different imagery group(s), they can set
290 semantic labels for each group member beforehand, i.e.,
291 before generating the signature files.
292 Semantic labels are set by means of <em>r.support</em>
293 as shown below:
294
295 <div class="code"><pre>
296 # Define semantic labels for all LANDSAT bands
297 r.support map=lsat7_2002_10 semantic_label=TM7_1
298 r.support map=lsat7_2002_20 semantic_label=TM7_2
299 r.support map=lsat7_2002_30 semantic_label=TM7_3
300 r.support map=lsat7_2002_40 semantic_label=TM7_4
301 r.support map=lsat7_2002_50 semantic_label=TM7_5
302 r.support map=lsat7_2002_61 semantic_label=TM7_61
303 r.support map=lsat7_2002_62 semantic_label=TM7_62
304 r.support map=lsat7_2002_70 semantic_label=TM7_7
305 r.support map=lsat7_2002_80 semantic_label=TM7_8
306 </pre></div>
307
308 <h2>SEE ALSO</h2>
309
310 <ul>
311 <li> <a href="https://grasswiki.osgeo.org/wiki/Image_classification">Image classification</a> wiki page</li>
312 <li> Historical reference also the GRASS GIS 4
313 <a href="https://grass.osgeo.org/gdp/imagery/grass4_image_processing.pdf">Image Processing manual</a> (PDF)</li>
314 <li> <a href="https://en.wikipedia.org/wiki/K-means_clustering">Wikipedia article on <i>k</i>-means clustering</a>
315 (note that <em>i.cluster</em> uses a modification of the <i>k</i>-means clustering algorithm)</li>
316 </ul>
317
318 <p>
319 <em>
320 <a href="r.support.html">r.support</a>,
321 <a href="g.gui.iclass.html">g.gui.iclass</a>,
322 <a href="i.group.html">i.group</a>,
323 <a href="i.gensig.html">i.gensig</a>,
324 <a href="i.maxlik.html">i.maxlik</a>,
325 <a href="i.segment.html">i.segment</a>,
326 <a href="i.smap.html">i.smap</a>,
327 <a href="r.kappa.html">r.kappa</a>
328 </em>
329
330 <h2>AUTHORS</h2>
331
332 Michael Shapiro,
333 U.S. Army Construction Engineering Research Laboratory
334 <br>
335 Tao Wen,
336 University of Illinois at Urbana-Champaign, Illinois
337 <br>
338 Semantic label support: Maris Nartiss,
339 University of Latvia