← Back to branch summary

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

« back to all changes in this revision

Viewing changes to raster/r.out.gdal/description.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.out.gdal/description.html
1
 
<h2>DESCRIPTION</h2>
2
 
 
3
 
<em>r.out.gdal</em> allows a user to export a GRASS raster map layer
4
 
into any GDAL supported raster map format. If a GRASS raster map is
5
 
exported for a particular application, the application's native format
6
 
would be preferrable. GeoTIFF is supported by a wide range of
7
 
applications (see also <b>NOTES</b> on GeoTIFF below).
8
 
<p>
9
 
To specify multiple creation options use a comma separated list
10
 
(<em>createopt="TFW=YES,COMPRESS=DEFLATE"</em>).
11
 
<p>
12
 
For possible <em>createopt</em> and <em>metaopt</em> parameters please
13
 
consult the individual
14
 
<a href="http://www.gdal.org/formats_list.html">supported formats</a>
15
 
pages on the GDAL website.
16
 
The <em>createopt</em> parameter may be used to create TFW or World files
17
 
("TFW=YES","WORLDFILE=ON").
18
 
<p>
19
 
<em>r.out.gdal</em> also supports the export of multiband rasters as
20
 
a group, when the imagery group's name is entered as input.
21
 
(created imagery groups with the <em><a href="i.group.html">i.group</a></em>
22
 
module)
23
 
<p>
24
 
As with most GRASS raster modules, the current region extents and region
25
 
resolution are used, and a MASK is respected if present.
26
 
Use <em><a href="g.region.html">g.region</a></em>'s "align=", or "rast="
27
 
options if you need to realign the region settings to match the original
28
 
map's before export.
29
 
 
30
 
 
31
 
<h2>SUPPORTED RASTER FORMATS</h2>
32
 
 
33
 
The set of <a href="http://www.gdal.org/formats_list.html">supported
34
 
raster formats</a> written by <em>r.out.gdal</em> depends on the
35
 
local GDAL installation. Available may be (incomplete list):<p>
36
 
 
37
 
<pre>
38
 
  AAIGrid: Arc/Info ASCII Grid
39
 
  BMP: MS Windows Device Independent Bitmap
40
 
  BSB: Maptech BSB Nautical Charts
41
 
  DTED: DTED Elevation Raster
42
 
  ELAS: ELAS
43
 
  ENVI: ENVI .hdr Labelled
44
 
  FIT: FIT Image
45
 
  GIF: Graphics Interchange Format (.gif)
46
 
  GTiff: GeoTIFF
47
 
  HDF4Image: HDF4 Dataset
48
 
  HFA: Erdas Imagine Images (.img)
49
 
  JPEG2000: JPEG-2000 part 1 (ISO/IEC 15444-1)
50
 
  JPEG: JPEG JFIF
51
 
  MEM: In Memory Raster
52
 
  MFF2: Atlantis MFF2 (HKV) Raster
53
 
  MFF: Atlantis MFF Raster
54
 
  NITF: National Imagery Transmission Format
55
 
  PAux: PCI .aux Labelled
56
 
  PCIDSK: PCIDSK Database File
57
 
  PNG: Portable Network Graphics
58
 
  PNM: Portable Pixmap Format (netpbm)
59
 
  VRT: Virtual Raster
60
 
  XPM: X11 PixMap Format
61
 
</pre>
62
 
 
63
 
 
64
 
<h2>NOTES</h2>
65
 
 
66
 
<p>
67
 
Out of the GDAL data types, the closest match for GRASS CELL, FCELL and
68
 
DCELL rasters are respectively Int32, Float32 and Float64. These are not
69
 
exact equivalents, but they will preserve the maximum possible data range
70
 
and number of decimal places for each respective GRASS raster data type.
71
 
Please keep in mind that not all CELL rasters will require Int32 - e.g.,
72
 
0-255 CELL raster are covered by the Byte <em>type</em> as well.
73
 
Moreover, some GDAL-supported formats do not support all the data types
74
 
possible in GDAL and GRASS. Use <em><a href="r.info.html">r.info</a></em> to
75
 
check the data type and range for your GRASS raster, refer to specific
76
 
format documentation (on the <a href="http://www.gdal.org/">GDAL website</a>),
77
 
format vendor's documentation, and e.g. the Wikipedia article
78
 
<em><a href="http://en.wikipedia.org/wiki/C_syntax#Typical_boundaries_of_primitive_integral_types">
79
 
Typical boundaries of primitive integral types</a></em>
80
 
for details.
81
 
 
82
 
 
83
 
<h3>Ranges of GDAL data types</h3>
84
 
<pre>
85
 
  GDAL data type               minimum          maximum
86
 
 
87
 
  Byte                               0              255
88
 
  UInt16                             0           65,535
89
 
  Int16, CInt16                -32,768           32,767
90
 
  UInt32                             0    4,294,967,295
91
 
  Int32, CInt32         -2,147,483,648    2,147,483,647
92
 
  Float32, CFloat32            -3.4E38           3.4E38
93
 
  Float64, CFloat64          -1.79E308         1.79E308
94
 
</pre>
95
 
 
96
 
<p>
97
 
If there is a need to keep file sizes small, use the simplest data type
98
 
covering the data range of the raster(s) to be exported, e.g., if suitable
99
 
use Byte rather than UInt16; use Int16 rather than Int32; or use Float32
100
 
rather than Float64. In addition, the COMPRESS <b>createopt</b> used can
101
 
have a very large impact on the size of the output file.
102
 
<p>
103
 
Some software may not recognize all of the compression methods
104
 
available for a given file format, and certain compression methods may
105
 
only be supported for certain data types (depends on vendor and version).
106
 
<!-- e.g. data destined for ESRI software should use COMPRESS=LZW/PACKBITS/DEFLATE ??? -->
107
 
<p>
108
 
If the export settings are set such that data loss would occur in the output
109
 
file (i.e, due to the particular choice of data type and/or file type), the
110
 
normal behaviour of <em>r.out.gdal</em> in this case would be to issue an error
111
 
message describing the problem and exit without exporting. The <b>-f</b> flag
112
 
allows raster export even if some of the data loss tests are not passed, and
113
 
warnings are issued instead of errors.
114
 
<p>
115
 
<em>r.out.gdal</em> exports may appear all black or gray on initial
116
 
display in other GIS software. This is not a bug of <em>r.out.gdal</em>,
117
 
but often caused by the default color table assigned by that software.
118
 
The default color table may be grayscale covering the whole range of
119
 
possible values which is very large for e.g. Int32 or Float32. E.g.
120
 
stretching the color table to actual min/max would help (sometimes under
121
 
symbology).
122
 
 
123
 
<h3>GeoTIFF caveats</h3>
124
 
 
125
 
GeoTIFF exports can only be displayed by standard image viewers
126
 
if the GDAL data type was set to Byte and the GeoTIFF contains either
127
 
one or three bands. All other data types and numbers of bands can be
128
 
properly read with GIS software only. Although GeoTIFF files usually
129
 
have a .tif extension, these files are not necessarily images but
130
 
first of all spatial raster datasets, e.g. SRTM DEM version 4.
131
 
<p>
132
 
When writing out multi-band GeoTIFF images for users of ESRI software or
133
 
ImageMagick, the interleaving mode should be set to "pixel" using
134
 
<em>createopt="INTERLEAVE=PIXEL"</em>. BAND interleaving is slightly more
135
 
efficient, but not supported by some applications.
136
 
<!-- GDAL switched default from BAND to PIXEL interleave on 08/01/07 (r11823) -->
137
 
This issue only arises when writing out multi-band imagery groups.
138
 
<p>
139
 
 
140
 
<h3>Improving GeoTIFF compatibility</h3>
141
 
 
142
 
To create a GeoTIFF that is highly compatible with various other GIS
143
 
software packages, it is recommended to keep the GeoTIFF file as simple
144
 
as possible. You will have to experiment with which options your
145
 
software is compatible with, as this varies widely between vendors and
146
 
versions. Long term, the less metadata you have to remove the more
147
 
self-documenting (and useful) the dataset will be.
148
 
<p>
149
 
Here are some things to try:
150
 
 
151
 
<ul>
152
 
<li>Create a World file with <tt>createopt="TFW=YES"</tt>.
153
 
 
154
 
<li>Do not use GeoTIFF internal compression. Other GIS software often 
155
 
supports only a subset of the available compression methods with the 
156
 
supported methods differing between GIS software packages. Unfortunately
157
 
this means the output image can be rather huge, but the file can be
158
 
compressed with software like <tt>zip</tt>, <tt>gnuzip</tt>, or <tt>bzip2</tt>.
159
 
 
160
 
<li>Skip exporting the color table. Color tables are not always properly
161
 
rendered, particularly for type UInt16, and the GeoTIFF file can appear
162
 
completely black. If you are lucky the problematic software package has
163
 
a method to reset the color table and assign a new color table
164
 
(sometimes called symbology).
165
 
 
166
 
<li>Keep metadata simple with <tt>createopt="PROFILE=GeoTIFF"</tt> or 
167
 
<tt>createopt="PROFILE=BASELINE"</tt>. With BASELINE no GDAL or GeoTIFF
168
 
tags will be written and a World file is required (<em>createopt="TFW=YES"</em>).
169
 
 
170
 
<li>Adding overviews with <tt>gdaladdo</tt> after exporting can speed up display.
171
 
Note that other software might create their own overviews, ignoring existing
172
 
overviews.
173
 
</ul>
174
 
 
175
 
 
176
 
<h2>EXAMPLES</h2>
177
 
 
178
 
<h3>Export the integer raster roads map to GeoTIFF format:</h3>
179
 
<div class="code"><pre>
180
 
r.out.gdal input=roads output=roads.tif type=UInt16
181
 
</pre></div>
182
 
<p>
183
 
 
184
 
<h3>Export a DCELL raster map in GeoTIFF format suitable for ESRI software:</h3>
185
 
<div class="code"><pre>
186
 
r.out.gdal in=elevation.10m out=ned_elev10m.tif type=Float64 createopt="PROFILE=GeoTIFF,TFW=YES"
187
 
</pre></div>
188
 
<p>
189
 
 
190
 
<h3>Export R,G,B imagery bands in GeoTIFF format suitable for ESRI software:</h3>
191
 
<div class="code"><pre>
192
 
i.group group=nc_landsat_rgb input=lsat7_2002_30,lsat7_2002_20,lsat7_2002_10
193
 
r.out.gdal in=nc_landsat_rgb out=nc_landsat_rgb.tif type=Byte createopt="PROFILE=GeoTIFF,INTERLEAVE=PIXEL,TFW=YES"
194
 
</pre></div>
195
 
<p>
196
 
 
197
 
<h3>Export the floating point raster elevation map to ERDAS/IMG format:</h3>
198
 
<div class="code"><pre>
199
 
r.out.gdal input=elevation.10m output=elev_dem10.img format=HFA type=Float32
200
 
</pre></div>
201
 
 
202
 
<h3>Export group of image maps as multi-band file</h3>
203
 
<div class="code"><pre>
204
 
g.list group
205
 
i.group group=tm7 subgroup=tm7 input=tm7_10,tm7_20,tm7_30,tm7_40,tm7_50,tm7_60,tm7_70
206
 
i.group -l tm7
207
 
r.out.gdal tm7 type=UInt16 out=lsat_multiband.tif
208
 
gdalinfo lsat_multiband.tif
209
 
</pre></div>
210
 
 
211
 
 
212
 
<h2>GDAL RELATED ERROR MESSAGES</h2>
213
 
 
214
 
<ul>
215
 
<li> "ERROR 6: SetColorInterpretation() not supported for this dataset.":
216
 
 This <i>may</i> indicate that the color table was not written properly.
217
 
 But usually it will be correct and the message can be ignored.</li>
218
 
 
219
 
<li> "ERROR 6: SetNoDataValue() not supported for this dataset.":
220
 
 The selected output format does not support "no data". It is recommended
221
 
 to use a different output format if your data contains NULLs.</li>
222
 
 
223
 
<li> "Warning 1: Lost metadata writing to GeoTIFF ... too large to fit in
224
 
 tag.": The color table metadata may be too large. It is recommended to
225
 
 simplify or not write the color table, or use a different output format.</li>
226
 
</ul>
227
 
 
228
 
 
229
 
<h2>SEE ALSO</h2>
230
 
 
231
 
The <a href="http://www.gdal.org/formats_list.html">GDAL supported formats</a>
232
 
page.
233
 
<br>
234
 
<em>
235
 
<a href="r.out.ascii.html">r.out.ascii</a>,
236
 
<a href="r.out.arc.html">r.out.arc</a>,
237
 
<a href="r.out.bin.html">r.out.bin</a>,
238
 
<a href="r.out.mat.html">r.out.mat</a>,
239
 
<a href="r.out.png.html">r.out.png</a>,
240
 
<a href="r.out.ppm.html">r.out.ppm</a>,
241
 
<a href="r.out.tiff.html">r.out.tiff</a>
242
 
<br>
243
 
<a href="r.out.gdal.sh.html">r.out.gdal.sh</a></em>
244
 
 (old shell script version using <tt>gdal_translate</tt>)
245
 
 
246
 
 
247
 
<h2>REFERENCES</h2>
248
 
 
249
 
GDAL Pages: <a href="http://www.gdal.org">http://www.gdal.org</a>
250
 
 
251
 
 
252
 
<h2>AUTHORS</h2>
253
 
 
254
 
Vytautas Vebra (oliver4grass at gmail.com)<br>
255
 
Markus Metz (improved nodata logic)
256
 
 
257
 
<p>
258
 
<i>Last changed: $Date: 2010-09-16 09:25:59 +0200 (Thu, 16 Sep 2010) $</i>