4
<em>r.category</em> prints the category values and labels for the raster map
5
layer specified by <b>map=</b><em>name</em> to standard output.
9
The user can specify all needed parameters on the command line, and run the
10
program non-interactively. If the user does not specify any categories
11
(e.g., using the optional <b>cats=</b><em>range</em>[,<em>range</em>,...]
12
argument), then all the category values and labels for the named raster map
13
layer that occur in the map are printed. The entire <em>map</em> is read
14
using <em><a href="r.describe.html">r.describe</a></em>, to determine which
15
categories occur in the <em>map</em>. If a listing of categories is
16
specified, then the labels for those categories only are printed. The
17
<em>cats</em> may be specified as single category values, or as ranges of
18
values. The user may also (optionally) specify that a field separator other
19
than a space or tab be used to separate the category value from its
20
corresponding category label in the output, by using the
21
<b>fs=</b><em>character</em>|<em>space</em>|<em>tab</em> option (see example
22
below). If no field separator is specified by the user, a tab is used to
23
separate these fields in the output, by default.
27
The output is sent to standard output in the form of one category per line,
28
with the category value first on the line, then an ASCII TAB character (or
29
whatever single character or space is specified using the <b>fs</b>
30
parameter), then the label for the category.
35
Any ASCII TAB characters which may be in the label are replaced by spaces.
37
The output from <em>r.category</em> can be redirected into a file, or piped into
40
<h3>Input from a file</h3>
42
The <b>rules</b> option allows the user to assign category labels from values
43
found in a file. The label can refer to a single category, range of
44
categories, floating point value, or a range of floating point values.
45
The format is given as follows.
46
<div class="code"><pre>
51
If the filename is given as "-", the category labels are read from <tt>stdin</tt>
54
<h3>Default and dynamic category labels</h3>
56
Default and dynamic category labels can be created for categories that
57
are not explicitly labeled.
59
The coefficient line can be followed by explicit category labels
60
which override the format label generation.
64
5: . ## explicit category labels
67
explicit labels can be also of the form:
69
5.5:5:9 label description
71
15:30 label description
76
<li>$1 refers to the value num*5.0+1000 (ie, using the first 2 coefficients)
77
<li>$2 refers to the value num*5.0+1005 (ie, using the last 2 coefficients)
79
$1.2 will print $1 with 2 decimal places.
81
Also, the form $?xxx$yyy$ translates into yyy if the category is 1, xxx
82
otherwise. The $yyy$ is optional. Thus
86
will become: 1 meter (for category 1)<br>
87
2 meters (for category 2), etc.
90
format='Elevation: $1.2 to $2.2 feet' ## Format Statement
91
coefficients="5.0,1000,5.0,1005" ## Coefficients
93
The format and coefficients above would be used to generate the
94
following statement in creation of the format appropriate category
95
string for category "num":
97
sprintf(buff,"Elevation: %.2f to %.2f feet", num*5.0+1000, num*5.0*1005)
100
Note: while both the format and coefficent lines must be present
101
a blank line for the format string will effectively suppress
102
automatic label generation.
104
Note: quant rules of Categories structures are heavily dependant
105
on the fact that rules are stored in the same order they are entered.
106
since i-th rule and i-th label are entered at the same time, we
107
know that i-th rule maps fp range to i, thus we know for sure
108
that cats.labels[i] corresponds to i-th quant rule
111
To use a "<tt>$</tt>" in the label without triggering the plural test,
112
put "<tt>$$</tt>" in the format string.
114
Use 'single quotes' when using a "<tt>$</tt>" on the command line to
115
avoid unwanted shell substitution.
122
<dt><div class="code"><pre>
126
prints the values and labels associated with all of the categories in the
127
<em>soils</em> raster map layer;
129
<dt><div class="code"><pre>
130
r.category map=soils cats=10,12,15-20
133
prints only the category values and labels for <em>soils</em> map layer
134
categories <tt>10, 12</tt>, and <tt>15</tt> through <tt>20</tt>; and
136
<dt><div class="code"><pre>
137
r.category map=soils cats=10,20 fs=':'
140
prints the values and labels for <em>soils</em> map layer categories
141
<tt>10</tt> and <tt>20</tt>, but uses "<tt>:</tt>" (instead of a tab)
142
as the character separating the category values from the category
143
values in the output.
150
<div class="code"><pre>
159
Respect the <b>fs=</b> field separator setting for input rules.
164
UNIX Manual entries for <i>awk</i> and <i>sort</i>
167
<em><a href="r.coin.html">r.coin</a></em>,
168
<em><a href="r.describe.html">r.describe</a></em>,
169
<em><a href="d.what.rast.html">d.what.rast</a></em>,
170
<em><a href="r.support.html">r.support</a></em>
174
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory<br>
175
Hamish Bowman, University of Otago, New Zealand (label creation options)
178
<i>Last changed: $Date$</i>
added
removed
raster/r.cats/r.category.html
