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