1r.out.gdal(1) GRASS GIS User's Manual r.out.gdal(1)
2
3
4
6 r.out.gdal - Exports GRASS raster maps into GDAL supported formats.
7
9 raster, export, output
10
12 r.out.gdal
13 r.out.gdal --help
14 r.out.gdal [-lcmtf] input=name output=name format=string [type=string]
15 [createopt=string[,string,...]] [metaopt=string[,string,...]]
16 [nodata=float] [overviews=integer] [--overwrite] [--help] [--ver‐
17 bose] [--quiet] [--ui]
18
19 Flags:
20 -l
21 List supported output formats
22
23 -c
24 Do not write GDAL standard colortable
25 Only applicable to Byte or UInt16 data types
26
27 -m
28 Do not write non-standard metadata
29 Enhances compatibility with other GIS software
30
31 -t
32 Write raster attribute table
33 Some export formats may not be supported
34
35 -f
36 Force raster export despite any warnings of data loss
37 Overrides nodata safety check
38
39 --overwrite
40 Allow output files to overwrite existing files
41
42 --help
43 Print usage summary
44
45 --verbose
46 Verbose module output
47
48 --quiet
49 Quiet module output
50
51 --ui
52 Force launching GUI dialog
53
54 Parameters:
55 input=name [required]
56 Name of raster map (or group) to export
57
58 output=name [required]
59 Name for output raster file
60
61 format=string [required]
62 Raster data format to write (case sensitive, see also -l flag)
63 Options: VRT, GTiff, COG, NITF, HFA, ELAS, AAIGrid, DTED, PNG, GTA,
64 JPEG, MEM, GIF, FITS, XPM, BMP, PCIDSK, PCRaster, ILWIS, SGI,
65 SRTMHGT, Leveller, Terragen, GMT, netCDF, HDF4Image, ISIS3, ISIS2,
66 PDS4, VICAR, ERS, JP2OpenJPEG, FIT, GRIB, JPEG2000, RMF, WMS, RST,
67 INGR, GSAG, GSBG, GS7BG, R, KMLSUPEROVERLAY, WEBP, PDF, Rasterlite,
68 MBTiles, CALS, WMTS, MRF, PNM, PAux, MFF, MFF2, BT, LAN, IDA, LCP,
69 GTX, NTv2, CTable2, KRO, ROI_PAC, RRASTER, BYN, ARG, USGSDEM, BAG,
70 NWT_GRD, ADRG, BLX, PostGISRaster, SAGA, XYZ, HF2, ZMap, SIGDEM,
71 GPKG, NGW, ENVI, EHdr, ISCE
72 Default: GTiff
73
74 type=string
75 Data type
76 Options: Byte, Int16, UInt16, Int32, UInt32, Float32, Float64,
77 CInt16, CInt32, CFloat32, CFloat64
78
79 createopt=string[,string,...]
80 Creation option(s) to pass to the output format driver
81 In the form of "NAME=VALUE", separate multiple entries with a comma
82
83 metaopt=string[,string,...]
84 Metadata key(s) and value(s) to include
85 In the form of "META-TAG=VALUE", separate multiple entries with a
86 comma. Not supported by all output format drivers.
87
88 nodata=float
89 Assign a specified nodata value to output bands
90 If given, the nodata value is always written to metadata even if
91 there are no NULL cells in the input band (enhances output compati‐
92 bility).
93
94 overviews=integer
95 Number of overviews to create for the output dataset
96 Options: 0-5
97 Default: 0
98
100 r.out.gdal allows a user to export a GRASS raster map layer into any
101 GDAL supported raster map format. If a GRASS raster map is exported for
102 a particular application, the application’s native format would be
103 preferable. GeoTIFF is supported by a wide range of applications (see
104 also NOTES on GeoTIFF below).
105
106 To specify multiple creation options use a comma separated list (cre‐
107 ateopt="TFW=YES,COMPRESS=DEFLATE").
108
109 For possible createopt and metaopt parameters please consult the indi‐
110 vidual supported formats pages on the GDAL website. The createopt
111 parameter may be used to create TFW or World files ("TFW=YES","WORLD‐
112 FILE=ON").
113
114 r.out.gdal also supports the export of multiband rasters as a group,
115 when the imagery group’s name is entered as input. (created imagery
116 groups with the i.group module)
117
118 As with most GRASS raster modules, the current region extents and
119 region resolution are used, and a MASK is respected if present. Use
120 g.region’s "align=", or "raster=" options if you need to realign the
121 region settings to match the original map’s before export.
122
124 The set of supported raster formats written by r.out.gdal depends on
125 the local GDAL installation, printed with the -l flag. Available may be
126 (incomplete list):
127
128 AAIGrid: Arc/Info ASCII Grid
129 BMP: MS Windows Device Independent Bitmap
130 BSB: Maptech BSB Nautical Charts
131 DTED: DTED Elevation Raster
132 ELAS: ELAS
133 ENVI: ENVI .hdr Labelled
134 FIT: FIT Image
135 GIF: Graphics Interchange Format (.gif)
136 GTiff: GeoTIFF
137 HDF4Image: HDF4 Dataset
138 HFA: Erdas Imagine Images (.img)
139 JPEG2000: JPEG-2000 part 1 (ISO/IEC 15444-1)
140 JPEG: JPEG JFIF
141 MEM: In Memory Raster
142 MFF2: Atlantis MFF2 (HKV) Raster
143 MFF: Atlantis MFF Raster
144 NITF: National Imagery Transmission Format
145 PAux: PCI .aux Labelled
146 PCIDSK: PCIDSK Database File
147 PNG: Portable Network Graphics
148 PNM: Portable Pixmap Format (netpbm)
149 VRT: Virtual Raster
150 XPM: X11 PixMap Format
151
153 Out of the GDAL data types, the closest match for GRASS CELL, FCELL and
154 DCELL rasters are respectively Int32, Float32 and Float64. These are
155 not exact equivalents, but they will preserve the maximum possible data
156 range and number of decimal places for each respective GRASS raster
157 data type. Please keep in mind that not all CELL rasters will require
158 Int32 - e.g., 0-255 CELL raster are covered by the Byte type as well.
159 Moreover, some GDAL-supported formats do not support all the data types
160 possible in GDAL and GRASS. Use r.info to check the data type and range
161 for your GRASS raster, refer to specific format documentation (on the
162 GDAL website), format vendor’s documentation, and e.g. the Wikipedia
163 article Typical boundaries of primitive integral types for details.
164
165 Ranges of GDAL data types
166 GDAL data type minimum maximum
167 Byte 0 255
168 UInt16 0 65,535
169 Int16, CInt16 -32,768 32,767
170 UInt32 0 4,294,967,295
171 Int32, CInt32 -2,147,483,648 2,147,483,647
172 Float32, CFloat32 -3.4E38 3.4E38
173 Float64, CFloat64 -1.79E308 1.79E308
174
175 If there is a need to keep file sizes small, use the simplest data type
176 covering the data range of the raster(s) to be exported, e.g., if suit‐
177 able use Byte rather than UInt16; use Int16 rather than Int32; or use
178 Float32 rather than Float64. In addition, the COMPRESS createopt used
179 can have a very large impact on the size of the output file.
180
181 Some software may not recognize all of the compression methods avail‐
182 able for a given file format, and certain compression methods may only
183 be supported for certain data types (depends on vendor and version).
184
185 If the export settings are set such that data loss would occur in the
186 output file (i.e, due to the particular choice of data type and/or file
187 type), the normal behaviour of r.out.gdal in this case would be to
188 issue an error message describing the problem and exit without export‐
189 ing. The -f flag allows raster export even if some of the data loss
190 tests are not passed, and warnings are issued instead of errors.
191
192 r.out.gdal exports may appear all black or gray on initial display in
193 other GIS software. This is not a bug of r.out.gdal, but often caused
194 by the default color table assigned by that software. The default
195 color table may be grayscale covering the whole range of possible val‐
196 ues which is very large for e.g. Int32 or Float32. E.g. stretching the
197 color table to actual min/max would help (sometimes under symbology).
198
199 Adding overviews to speed up map display in other software
200 Adding overviews with gdaladdo after exporting can speed up display.
201 The overviews are created internally within the exported file. The
202 amount of levels (power-of-two factors) are controlled with the over‐
203 views parameter. The higher the overview level defined by the user the
204 more lower resolution internal overviews are added Note that other
205 software might create their own overviews, ignoring existing overviews.
206
207 GeoTIFF caveats
208 GeoTIFF exports can only be displayed by standard image viewers if the
209 GDAL data type was set to Byte and the GeoTIFF contains either one or
210 three bands. All other data types and numbers of bands can be properly
211 read with GIS software only. Although GeoTIFF files usually have a .tif
212 extension, these files are not necessarily images but first of all spa‐
213 tial raster datasets, e.g. land cover or elevation.
214
215 When writing out multi-band GeoTIFF images for users of ESRI software
216 or ImageMagick, the interleaving mode should be set to "pixel" using
217 createopt="INTERLEAVE=PIXEL". BAND interleaving is slightly more effi‐
218 cient, but not supported by some applications. This issue only arises
219 when writing out multi-band imagery groups.
220
221 Classic TIFF format supports only files with up to 4GB. Files that
222 exceed this limit (in compressed or uncompressed form) need to be
223 exported with createopt="BIGTIFF=YES". BIGTIFF is available if GDAL is
224 built with libtiff >= 4.0.
225
226 Improving GeoTIFF compatibility
227 To create a GeoTIFF that is highly compatible with various other GIS
228 software packages, it is recommended to keep the GeoTIFF file as simple
229 as possible. You will have to experiment with which options your soft‐
230 ware is compatible with, as this varies widely between vendors and ver‐
231 sions. Long term, the less metadata you have to remove the more
232 self-documenting (and useful) the dataset will be.
233
234 Here are some things to try:
235
236 · Create a World file with createopt="TFW=YES".
237
238 · Do not use GeoTIFF internal compression. Other GIS software
239 often supports only a subset of the available compression meth‐
240 ods with the supported methods differing between GIS software
241 packages. Unfortunately this means the output image can be
242 rather huge, but the file can be compressed with software like
243 zip, gnuzip, or bzip2.
244
245 · Skip exporting the color table. Color tables are not always
246 properly rendered, particularly for type UInt16, and the Geo‐
247 TIFF file can appear completely black. If you are lucky the
248 problematic software package has a method to reset the color
249 table and assign a new color table (sometimes called symbol‐
250 ogy).
251
252 · Keep metadata simple with createopt="PROFILE=GeoTIFF" or cre‐
253 ateopt="PROFILE=BASELINE". With BASELINE no GDAL or GeoTIFF
254 tags will be written and a World file is required (cre‐
255 ateopt="TFW=YES").
256
257 Cloud Optimized GeoTIFFs (COG) can be created with the creation options
258 createopt=TILED=YES,COMPRESS=DEFLATE, followed by gdaladdo to build
259 overviews.
260
262 Export the integer raster basin_50K map to GeoTIFF format
263 g.region raster=basin_50K -p
264 r.out.gdal input=basin_50K output=basin_50K.tif
265
266 Export a DCELL raster map in GeoTIFF format suitable for ESRI software
267 g.region raster=elevation -p
268 r.out.gdal in=elevation output=elevation.tif createopt="PROFILE=GeoTIFF,TFW=YES"
269
270 Export a raster map in "Deflate" compressed GeoTIFF format
271 g.region raster=elevation -p
272 r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=DEFLATE"
273
274 Export a large raster map in LZW compressed (Big) GeoTIFF format
275 g.region raster=elevation -p
276 # Using PREDICTOR 2 or 3 (the latter mainly for floating point data) can further reduce file size
277 r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=LZW,PREDICTOR=3,BIGTIFF=YES"
278
279 Export a raster map with internal overview in "Deflate" compressed GeoTIFF
280 format
281 g.region raster=elevation -p
282 # overviews=5 corresponds to ’gdaladdo ... 2 4 8 16 32’
283 r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=DEFLATE" overviews=5
284
285 Export R,G,B imagery bands in GeoTIFF format suitable for ESRI software
286 i.group group=nc_landsat_rgb input=lsat7_2002_30,lsat7_2002_20,lsat7_2002_10
287 g.region raster=lsat7_2002_30 -p
288 r.out.gdal in=nc_landsat_rgb output=nc_landsat_rgb.tif type=Byte \
289 createopt="PROFILE=GeoTIFF,INTERLEAVE=PIXEL,TFW=YES"
290
291 Export the floating point raster elevation map to ERDAS/IMG format
292 g.region raster=elevation -p
293 r.out.gdal input=elevation output=elelevation.img format=HFA type=Float32
294
295 Export group of image maps as multi-band file
296 g.list group
297 i.group group=tm7 subgroup=tm7 input=tm7_10,tm7_20,tm7_30,tm7_40,tm7_50,tm7_60,tm7_70
298 i.group -l tm7
299 g.region raster=tm7_10 -p
300 r.out.gdal tm7 output=lsat_multiband.tif
301 gdalinfo lsat_multiband.tif
302
303 Export RGB with alpha channel that encodes NULL cells
304 When exporting exporting RGB data rather than GIS data for Web applica‐
305 tions or generally the scope of visualization, the alpha channel is of
306 use. Here the export type is commonly the Byte data type.
307
308 When exporting data with r.out.gdal, assigning a nodata value (specific
309 parameter of the module) means that any band values equal to this
310 nodata value will be interpreted as nodata. Using an additional alpha
311 channel means that all pixels with an alpha value of 0 are transparent.
312 The alpha channel thus represents per-pixel encoding of nodata, just
313 like the GRASS MASK (null file). That means when using an alpha chan‐
314 nel, you do not need to "free up" any particular value, but you can use
315 any value you like to replace NULL cells, as long as the value can be
316 represented by the Byte data type. It does not matter if that value is
317 already present in any of the input bands.
318
319 Hence for "visual-only" RGB data export it is needed to create an addi‐
320 tional alpha channel that encodes all NULL cells and in the RGB bands
321 to be exported replace NULL cells with some value in the range 0-255.
322 For example:
323
324 # for simplicity variables are used
325 RMAP="lsat7_2000_30"
326 GMAP="lsat7_2000_20"
327 BMAP="lsat7_2000_10"
328 OUTNAME="lsat7_2000_RGBA.tif"
329 # extract alpha
330 r.mapcalc "out_a = if(isnull($RMAP) || isnull($GMAP) || isnull($BMAP), 0, 255)"
331 # replace NULL cells with a valid value, extract colors
332 # exporting 8 bit RGB data, not GIS data, therefore the `#` operator:
333 r.mapcalc "out_r = if(isnull($RMAP), 0, #$RMAP)"
334 r.mapcalc "out_g = if(isnull($GMAP), 0, #$GMAP)"
335 r.mapcalc "out_b = if(isnull($BMAP), 0, #$BMAP)"
336 # create group for export
337 i.group group=out_rgba input=out_r,out_g,out_b,out_a
338 # remove any MASK because this works only if there are
339 # no NULL cells in the bands to be exported
340 r.mask -r
341 # export the group:
342 # add PROFILE=BASELINE to createopt to produce a standard TIFF file
343 # without any GTiff extensions
344 r.out.gdal input=out_rgba output=$OUTNAME -cm createopt="PHOTOMETRIC=RGB,ALPHA=YES"
345 gdalinfo $OUTNAME
346 The resulting GeoTIFF file can be used e.g. for Web server applica‐
347 tions.
348
350 · "ERROR 6: SetColorInterpretation() not supported for this
351 dataset.": This may indicate that the color table was not writ‐
352 ten properly. But usually it will be correct and the message
353 can be ignored.
354
355 · "ERROR 6: SetNoDataValue() not supported for this dataset.":
356 The selected output format does not support "no data". It is
357 recommended to use a different output format if your data con‐
358 tains NULLs.
359
360 · "Warning 1: Lost metadata writing to GeoTIFF ... too large to
361 fit in tag.": The color table metadata may be too large. It is
362 recommended to simplify or not write the color table, or use a
363 different output format or the flags -c and -m.
364
366 The GDAL supported formats page.
367 r.out.ascii, r.out.bin, r.out.mat, r.out.png, r.out.ppm, r.pack
368
370 GDAL Pages: http://www.gdal.org
371
373 Vytautas Vebra (oliver4grass at gmail.com)
374 Markus Metz (improved nodata logic)
375
377 Available at: r.out.gdal source code (history)
378
379 Main index | Raster index | Topics index | Keywords index | Graphical
380 index | Full index
381
382 © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
383
384
385
386GRASS 7.8.5 r.out.gdal(1)