← Back to branch summary

~ubuntu-branches/ubuntu/vivid/grass/vivid-proposed

« back to all changes in this revision

Viewing changes to raster/r.colors/r.colors.html

  • Committer: Package Import Robot
  • Author(s): Bas Couwenberg
  • Date: 2015-02-20 23:12:08 UTC
  • mfrom: (8.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20150220231208-1u6qvqm84v430b10
Tags: 7.0.0-1~exp1
* New upstream release.
* Update python-ctypes-ternary.patch to use if/else instead of and/or.
* Drop check4dev patch, rely on upstream check.
* Add build dependency on libpq-dev to grass-dev for libpq-fe.h.
* Drop patches applied upstream, refresh remaining patches.
* Update symlinks for images switched from jpg to png.

Show diffs side-by-side

added added

removed removed

Lines of Context:
raster/r.colors/r.colors.html
 
1
<h2>DESCRIPTION</h2>
 
2
 
 
3
<em>r.colors</em> allows the user to create and/or modify the color
 
4
table for a raster map or several raster maps at once. 
 
5
The raster maps (specified on the command line
 
6
by <b>map</b> or as <b>file</b> using an input file with one map name per line) 
 
7
must exist in the user's current mapset search path.
 
8
 
 
9
<p>The <b>raster</b> option allows user to specify a raster map <i>name</i>
 
10
from which to copy the color map.
 
11
 
 
12
<p>The <b>raster_3d</b> option allows user to specify a 3D raster
 
13
map <i>name</i> from which to copy the color map.
 
14
 
 
15
<p>The <b>-e</b> flag equalizes the original raster's color table. It can
 
16
preclude the need for <em>grey.eq</em> rule, when used as
 
17
<b>-e color=</b><em>grey</em>. Note however, that this will not yield
 
18
a color table identical to <em>color=grey.eq</em>,
 
19
because <em>grey.eq</em> scales the fraction by 256 to get a grey
 
20
level, while <b>-e</b> uses it to interpolate the original color
 
21
table. If the original color table is a 0-255 grey scale, <b>-e</b>
 
22
is effectively scaling the fraction by 255. Different algorithms are
 
23
used. <b>-e</b> is designed to work with any color table, both the
 
24
floating point and the integer raster maps.
 
25
 
 
26
<p>The <b>-g</b> flag divides the raster's grey value range into 100
 
27
logarithmically equal steps (where &quot;step&quot; is a rule with the
 
28
same grey level for the start and end points). It can preclude the
 
29
need for <em>grey.log</em> rule, when used as <b>-g
 
30
color=</b><em>grey</em>. Note however, that this will not yield a
 
31
color table identical to <em>color=grey.log</em>. Different algorithms
 
32
are used. Unlike <b>color=</b><em>grey.log</em>, <b>-g</b> is designed
 
33
to work with both floating point and integer rasters, without
 
34
performance issues with large datasets, of any original color
 
35
table. Logarithmic scaling doesn't work on negative values. In the
 
36
case when the value range includes zero, there's no realistic
 
37
solution.
 
38
 
 
39
<p>The <b>-e</b> and <b>-g</b> flags are not mutually exclusive.
 
40
 
 
41
<p>If the user specifies the <b>-w</b> flag, the current color table file for
 
42
the input map will not be overwritten. This means that the color table is
 
43
created only if the <i>map</i> does not already have a color table. If this
 
44
option is not specified, the color table will be created if one does not
 
45
exist, or modified if it does.
 
46
 
 
47
<p><p>Color table types <i>aspect, grey, grey.eq</i> (histogram-equalized
 
48
grey scale), <i>byg</i> (blue-yellow-green), <i>byr</i>
 
49
(blue-yellow-red), <i>gyr</i> (green-yellow-red), <i>rainbow, ramp,
 
50
ryg</i> (red-yellow-green), <i>random</i>, and <i>wave</i> are
 
51
pre-defined color tables that <em>r.colors</em> knows how to create
 
52
without any further input.
 
53
 
 
54
<p>
 
55
In case several input raster maps are provided the range (min, max) of all maps 
 
56
will be used for color table creation. Hence the created color table will span from
 
57
the smallest minimum to the largest maximum value of all input raster maps and
 
58
will be applied to all input raster maps.
 
59
 
 
60
<p>In general, tables which associate colors with percentages (aspect, bcyr, byg,
 
61
byr, elevation, grey, gyr, rainbow, ramp, ryb, ryg and wave) can be applied to
 
62
any data, while those which use absolute values (aspectcolr, curvature, etopo2,
 
63
evi, ndvi, population, slope, srtm, and terrain) only make sense for data with
 
64
certain ranges.
 
65
 
 
66
One can get a rough idea of the applicability of a colour table by reading the
 
67
corresponding rules file (<tt>$GISBASE/etc/colors/&lt;name&gt;</tt>).
 
68
For example the <em>slope</em> rule is defined as:
 
69
 
 
70
<div class="code"><pre>
 
71
0  255:255:255
 
72
2  255:255:0
 
73
5  0:255:0
 
74
10 0:255 255
 
75
15 0:0:255
 
76
30 255:0:255
 
77
50 255:0:0
 
78
90 0:0:0
 
79
</pre></div>
 
80
 
 
81
<p>This is designed for the slope map generated
 
82
by <em><a href="r.slope.aspect.html">r.slope.aspect</a></em>, where the
 
83
value is a slope angle between 0 and 90 degrees.
 
84
 
 
85
<p>Similarly, the <em>aspectcolr</em> rule:
 
86
 
 
87
<div class="code"><pre>
 
88
0 white
 
89
1 yellow
 
90
90 green
 
91
180 cyan
 
92
270 red
 
93
360 yellow
 
94
</pre></div>
 
95
 
 
96
<p>is designed for the aspect maps produced
 
97
by <em><a href="r.slope.aspect.html">r.slope.aspect</a></em>, where the
 
98
value is a heading between 0 and 360 degrees.
 
99
 
 
100
<p>The <b>rules</b> color table type will cause <i>r.colors</i> to read
 
101
color table specifications from standard input (stdin) and will build
 
102
the color table accordingly.
 
103
 
 
104
<p>Using color table type <b>rules</b>, there are <!--three-->two ways to
 
105
build a color table: <!--by color list,--> by category values and by
 
106
&quot;percent&quot; values.
 
107
 
 
108
<!-- HB: this causes an error in current code, maybe easy to enable functionality from old code??
 
109
<p>Building a customized color table by color list is the simplest of the three
 
110
rules methods: just list the colors you wish to appear in the color table in the
 
111
order that you wish them to appear. Use the standard GRASS color names: white,
 
112
black, red, green, blue, yellow, magenta, cyan, aqua, grey, gray, orange, brown,
 
113
purple, violet, and indigo.
 
114
 
 
115
<p>For example, to create a color table for the raster map layer <i>elevation</i>
 
116
that assigns greens to low map category values, browns to the next larger
 
117
map category values, and yellows to the still larger map category values,
 
118
one would type:
 
119
 
 
120
<div class="code"><pre>
 
121
<b>r.colors map=</b><i>elevation</i> <b>color=</b><i>rules</i>
 
122
green
 
123
brown
 
124
yellow
 
125
end
 
126
</pre></div>
 
127
-->
 
128
<p>To build a color table by category values' indices, the user should
 
129
determine the range of category values in the raster map with which
 
130
the color table will be used. Specific category values will then be
 
131
associated with specific colors. Note that a color does not have to be
 
132
assigned for every valid category value because <em>r.colors</em> will
 
133
interpolate a color ramp to fill in where color specification rules
 
134
have been left out. The format of such a specification is as follows:
 
135
 
 
136
<div class="code"><pre>
 
137
category_value color_name
 
138
category_value color_name
 
139
.. ..
 
140
.. ..
 
141
category_value color_name
 
142
end
 
143
</pre></div>
 
144
 
 
145
<p>Each category value must be valid for the raster map, category values
 
146
must be in ascending order and only use standard GRASS color names
 
147
(aqua, black, blue, brown, cyan, gray, green, grey, indigo, magenta,
 
148
orange, purple, red, violet, white, yellow).
 
149
 
 
150
<p>Colors can also be specified by color numbers each in the range
 
151
0-255. The format of a category value color table specification using
 
152
color numbers instead of color names is as follows:
 
153
 
 
154
<div class="code"><pre>
 
155
category_value red_number:green_number:blue_number
 
156
category_value red_number:green_number:blue_number
 
157
.. .. .. ..
 
158
.. .. .. ..
 
159
category_value red_number:green_number:blue_number
 
160
end
 
161
</pre></div>
 
162
 
 
163
<p>Specifying a color table by &quot;percent&quot; values allows one to
 
164
treat a color table as if it were numbered from 0 to 100. The format
 
165
of a &quot;percent&quot; value color table specification is the same
 
166
as for a category value color specification, except that the category
 
167
values are replaced by &quot;percent&quot; values, each from 0-100, in
 
168
ascending order. The format is as follows:
 
169
 
 
170
<div class="code"><pre>
 
171
percent_value% color_name
 
172
percent_value% color_name
 
173
.. ..
 
174
.. ..
 
175
percent_value% color_name
 
176
end
 
177
</pre></div>
 
178
 
 
179
<p>Using &quot;percent&quot; value color table specification rules,
 
180
colors can also be specified by color numbers each in the range
 
181
0-255. The format of a percent value color table specification using
 
182
color numbers instead of color names is as follows:
 
183
 
 
184
<div class="code"><pre>
 
185
percent_value% red_number:green_number:blue_number
 
186
percent_value% red_number:green_number:blue_number
 
187
.. .. .. ..
 
188
.. .. .. ..
 
189
percent_value% red_number:green_number:blue_number
 
190
end
 
191
</pre></div>
 
192
 
 
193
<p>Note that you can also mix these <!--three-->two methods of color
 
194
table specification; for example:
 
195
 
 
196
<div class="code"><pre>
 
197
0 black
 
198
10% yellow
 
199
78 blue<!--\n magenta
 
200
purple
 
201
brown-->
 
202
100% 0:255:230
 
203
end
 
204
</pre></div>
 
205
 
 
206
<p>To set the NULL (no data) color, use the "nv" parameter:
 
207
 
 
208
<div class="code"><pre>
 
209
0 black
 
210
10% yellow
 
211
nv white
 
212
end
 
213
</pre></div>
 
214
 
 
215
<p>To set the color to used for undefined values (beyond the range of the
 
216
color rules) use the "default" parameter:
 
217
 
 
218
<div class="code"><pre>
 
219
0 red
 
220
1 blue
 
221
default grey
 
222
end
 
223
</pre></div>
 
224
 
 
225
<h2>NOTES</h2>
 
226
 
 
227
All color tables are stored in <tt>$GISBASE/etc/colors/</tt>. Further
 
228
user-defined color tables can also be stored in this directory for
 
229
access from the <em>color</em> parameter or in a user defined directory.
 
230
See also <em>r.colors.out</em> for printing color tables easily to the
 
231
terminal.
 
232
<p>
 
233
The color table assigned to a raster map is stored in
 
234
<tt>$GISDBASE/location/mapset/colr/</tt>.
 
235
 
 
236
<h2>EXAMPLES</h2>
 
237
 
 
238
The below example shows how you can specify colors for a three
 
239
category map, assigning red to category 1, green to category 2, and
 
240
blue to category 3. Start by using a text editor to create the
 
241
following rules specification file (save it with the
 
242
name <i>rules.file</i>):
 
243
 
 
244
<div class="code"><pre>
 
245
1 red
 
246
2 green
 
247
3 blue
 
248
end
 
249
</pre></div>
 
250
 
 
251
<p>The color table can then by assigned to map <i>threecats</i> by the
 
252
following GRASS commands (two ways are available):
 
253
 
 
254
<div class="code"><pre>
 
255
# read input from stdin
 
256
cat rules.file | r.colors map=threecats rules=-
 
257
 
 
258
# read directly from file
 
259
r.colors map=threecats rules=rules.file
 
260
</pre></div>
 
261
 
 
262
<p>To create a natural looking lookup table (LUT) for true map layer
 
263
<i>elevation</i>, use the following rules specification file. It will
 
264
assign light green shades to the lower elevations (first 20% of the
 
265
LUT), and then darker greens (next 15%, and next 20%) and light browns
 
266
(next 20%) for middle elevations, and darker browns (next 15%) for
 
267
higher elevations, and finally yellow for the highest peaks (last 10%
 
268
of LUT).
 
269
 
 
270
<div class="code"><pre>
 
271
0% 0:230:0
 
272
20% 0:160:0
 
273
35% 50:130:0
 
274
55% 120:100:30
 
275
75% 120:130:40
 
276
90% 170:160:50
 
277
100% 255:255:100
 
278
</pre></div>
 
279
 
 
280
<p>To invert the current rules: 
 
281
<div class="code"><pre>
 
282
r.colors map=current_raster -n rast=current_raster
 
283
</pre></div>
 
284
 
 
285
<h2>SEE ALSO</h2>
 
286
 
 
287
<em>
 
288
  <a href="d.colortable.html">d.colortable</a>,
 
289
  <a href="d.histogram.html">d.histogram</a>,
 
290
  <a href="d.legend.html">d.legend</a>,
 
291
  <a href="r.colors.out.html">r.colors.out</a>
 
292
  <a href="r.colors.stddev.html">r.colors.stddev</a>,
 
293
  <a href="r.support.html">r.support</a>,
 
294
  <a href="r.univar.html">r.univar</a>,
 
295
  <a href="v.colors.html">v.colors</a>,
 
296
  <a href="v.colors.out.html">v.colors.out</a>,
 
297
  <a href="r3.colors.html">r3.colors</a>,
 
298
  <a href="r3.colors.out.html">r3.colors.out</a>
 
299
</em>
 
300
 
 
301
<p>See also wiki
 
302
page <a href="http://grasswiki.osgeo.org/wiki/Color_tables">Color
 
303
tables</a> (from GRASS User Wiki)
 
304
 
 
305
<p><a href="http://colorbrewer.org">ColorBrewer</a> is an online tool designed to
 
306
help people select good color schemes for maps and other graphics.
 
307
 
 
308
 
 
309
<h2>AUTHORS</h2>
 
310
Michael Shapiro and David Johnson<br>
 
311
Support for 3D rasters by Soeren Gebbert
 
312
 
 
313
<p><i>Last changed: $Date: 2014-12-24 11:56:44 +0100 (Wed, 24 Dec 2014) $</i>