1r.out.gdal(1) Grass User's Manual r.out.gdal(1)
2
6 r.out.gdal - Exports GRASS raster maps into GDAL supported formats.
7
9 raster, export
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 Flags:
20 -l
21 List supported output formats
22 -c
24 Do not write GDAL standard colortable
25 Only applicable to Byte or UInt16 data types
26 -m
28 Do not write non-standard metadata
29 Enhances compatibility with other GIS software
30 -t
32 Write raster attribute table
33 Some export formats may not be supported
34 -f
36 Force raster export despite any warnings of data loss
37 Overrides nodata safety check
38 --overwrite
40 Allow output files to overwrite existing files
41 --help
43 Print usage summary
44 --verbose
46 Verbose module output
47 --quiet
49 Quiet module output
50 --ui
52 Force launching GUI dialog
53 Parameters:
55 input=name [required]
56 Name of raster map (or group) to export
57 output=name [required]
59 Name for output raster file
60 format=string [required]
62 Raster data format to write (case sensitive, see also -l flag)
63 Options: VRT, GTiff, 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, ERS, JP2OpenJPEG, FIT, GRIB, JPEG2000, RMF, WMS, RST, INGR,
67 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, ARG, USGSDEM, NWT_GRD,
70 ADRG, BLX, PostGISRaster, SAGA, XYZ, HF2, ZMap, GPKG, ENVI, EHdr,
71 ISCE
72 Default: GTiff
73 type=string
75 Data type
76 Options: Byte, Int16, UInt16, Int32, UInt32, Float32, Float64,
77 CInt16, CInt32, CFloat32, CFloat64
78 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 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 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 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 To specify multiple creation options use a comma separated list (cre‐
107 ateopt="TFW=YES,COMPRESS=DEFLATE").
108 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 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 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 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 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 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 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 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 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 GeoTIFF caveats
200 GeoTIFF exports can only be displayed by standard image viewers if the
201 GDAL data type was set to Byte and the GeoTIFF contains either one or
202 three bands. All other data types and numbers of bands can be properly
203 read with GIS software only. Although GeoTIFF files usually have a .tif
204 extension, these files are not necessarily images but first of all spa‐
205 tial raster datasets, e.g. land cover or elevation.
206 When writing out multi-band GeoTIFF images for users of ESRI software
208 or ImageMagick, the interleaving mode should be set to "pixel" using
209 createopt="INTERLEAVE=PIXEL". BAND interleaving is slightly more effi‐
210 cient, but not supported by some applications. This issue only arises
211 when writing out multi-band imagery groups.
212 Improving GeoTIFF compatibility
214 To create a GeoTIFF that is highly compatible with various other GIS
215 software packages, it is recommended to keep the GeoTIFF file as simple
216 as possible. You will have to experiment with which options your soft‐
217 ware is compatible with, as this varies widely between vendors and ver‐
218 sions. Long term, the less metadata you have to remove the more
219 self-documenting (and useful) the dataset will be.
220 Here are some things to try:
222 · Create a World file with createopt="TFW=YES".
224 · Do not use GeoTIFF internal compression. Other GIS software
226 often supports only a subset of the available compression meth‐
227 ods with the supported methods differing between GIS software
228 packages. Unfortunately this means the output image can be
229 rather huge, but the file can be compressed with software like
230 zip, gnuzip, or bzip2.
231 · Skip exporting the color table. Color tables are not always
233 properly rendered, particularly for type UInt16, and the Geo‐
234 TIFF file can appear completely black. If you are lucky the
235 problematic software package has a method to reset the color
236 table and assign a new color table (sometimes called symbol‐
237 ogy).
238 · Keep metadata simple with createopt="PROFILE=GeoTIFF" or cre‐
240 ateopt="PROFILE=BASELINE". With BASELINE no GDAL or GeoTIFF
241 tags will be written and a World file is required (cre‐
242 ateopt="TFW=YES").
243 · Adding overviews with gdaladdo after exporting can speed up
245 display. Note that other software might create their own over‐
246 views, ignoring existing overviews.
247 Cloud Optimized GeoTIFFs (COG) can be created with the creation options
249 createopt=TILED=YES,COMPRESS=DEFLATE, followed by gdaladdo to build
250 overviews.
251
253 Export the integer raster basin_50K map to GeoTIFF format
254 g.region raster=basin_50K -p
255 r.out.gdal input=basin_50K output=basin_50K.tif
256 Export a DCELL raster map in GeoTIFF format suitable for ESRI software
258 g.region raster=elevation -p
259 r.out.gdal in=elevation output=elevation.tif createopt="PROFILE=GeoTIFF,TFW=YES"
260 Export a raster map in "Deflate" compressed GeoTIFF format
262 g.region raster=elevation -p
263 r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=DEFLATE"
264 Export R,G,B imagery bands in GeoTIFF format suitable for ESRI software
266 i.group group=nc_landsat_rgb input=lsat7_2002_30,lsat7_2002_20,lsat7_2002_10
267 g.region raster=lsat7_2002_30 -p
268 r.out.gdal in=nc_landsat_rgb output=nc_landsat_rgb.tif type=Byte \
269 createopt="PROFILE=GeoTIFF,INTERLEAVE=PIXEL,TFW=YES"
270 Export the floating point raster elevation map to ERDAS/IMG format
272 g.region raster=elevation -p
273 r.out.gdal input=elevation output=elelevation.img format=HFA type=Float32
274 Export group of image maps as multi-band file
276 g.list group
277 i.group group=tm7 subgroup=tm7 input=tm7_10,tm7_20,tm7_30,tm7_40,tm7_50,tm7_60,tm7_70
278 i.group -l tm7
279 g.region raster=tm7_10 -p
280 r.out.gdal tm7 output=lsat_multiband.tif
281 gdalinfo lsat_multiband.tif
282 Export RGB with alpha channel that encodes NULL cells
284 When exporting exporting RGB data rather than GIS data for Web applica‐
285 tions or generally the scope of visualization, the alpha channel is of
286 use. Here the export type is commonly the Byte data type.
287 When exporting data with r.out.gdal, assigning a nodata value (specific
289 parameter of the module) means that any band values equal to this
290 nodata value will be interpreted as nodata. Using an additional alpha
291 channel means that all pixels with an alpha value of 0 are transparent.
292 The alpha channel thus represents per-pixel encoding of nodata, just
293 like the GRASS MASK (null file). That means when using an alpha chan‐
294 nel, you do not need to "free up" any particular value, but you can use
295 any value you like to replace NULL cells, as long as the value can be
296 represented by the Byte data type. It does not matter if that value is
297 already present in any of the input bands.
298 Hence for "visual-only" RGB data export it is needed to create an addi‐
300 tional alpha channel that encodes all NULL cells and in the RGB bands
301 to be exported replace NULL cells with some value in the range 0-255.
302 For example:
303 # for simplicity variables are used
305 RMAP="lsat7_2000_30"
306 GMAP="lsat7_2000_20"
307 BMAP="lsat7_2000_10"
308 OUTNAME="lsat7_2000_RGBA.tif"
309 # extract alpha
310 r.mapcalc "out_a = if(isnull($RMAP) || isnull($GMAP) || isnull($BMAP), 0, 255)"
311 # replace NULL cells with a valid value, extract colors
312 # exporting 8 bit RGB data, not GIS data, therefore the `#` operator:
313 r.mapcalc "out_r = if(isnull($RMAP), 0, #$RMAP)"
314 r.mapcalc "out_g = if(isnull($GMAP), 0, #$GMAP)"
315 r.mapcalc "out_b = if(isnull($BMAP), 0, #$BMAP)"
316 # create group for export
317 i.group group=out_rgba input=out_r,out_g,out_b,out_a
318 # remove any MASK because this works only if there are
319 # no NULL cells in the bands to be exported
320 r.mask -r
321 # export the group:
322 # add PROFILE=BASELINE to createopt to produce a standard TIFF file
323 # without any GTiff extensions
324 r.out.gdal input=out_rgba output=$OUTNAME -cm createopt="PHOTOMETRIC=RGB,ALPHA=YES"
325 gdalinfo $OUTNAME
326 The resulting GeoTIFF file can be used e.g. for Web server applica‐
327 tions.
328
330 · "ERROR 6: SetColorInterpretation() not supported for this
331 dataset.": This may indicate that the color table was not writ‐
332 ten properly. But usually it will be correct and the message
333 can be ignored.
334 · "ERROR 6: SetNoDataValue() not supported for this dataset.":
336 The selected output format does not support "no data". It is
337 recommended to use a different output format if your data con‐
338 tains NULLs.
339 · "Warning 1: Lost metadata writing to GeoTIFF ... too large to
341 fit in tag.": The color table metadata may be too large. It is
342 recommended to simplify or not write the color table, or use a
343 different output format or the flags -c and -m.
344
346 The GDAL supported formats page.
347 r.out.ascii, r.out.bin, r.out.mat, r.out.png, r.out.ppm, r.pack
348
350 GDAL Pages: http://www.gdal.org
351
353 Vytautas Vebra (oliver4grass at gmail.com)
354 Markus Metz (improved nodata logic)
355 Last changed: $Date: 2017-10-12 20:47:34 +0200 (Thu, 12 Oct 2017) $
357
359 Available at: r.out.gdal source code (history)
360 Main index | Raster index | Topics index | Keywords index | Graphical
362 index | Full index
363 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
365GRASS 7.4.4 r.out.gdal(1)