1r.out.gdal(1) GRASS GIS User's Manual r.out.gdal(1)
2
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,...]] [no‐
16 data=float] [overviews=integer] [offset=float] [scale=float]
17 [--overwrite] [--help] [--verbose] [--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, COG, NITF, HFA, ELAS, AAIGrid, DTED, PNG, GTA,
64 JPEG, MEM, GIF, FITS, XPM, BMP, PCIDSK, PCRaster, ILWIS, SGI,
65 SRTMHGT, Leveller, Terragen, netCDF, HDF4Image, ISIS3, ISIS2, PDS4,
66 VICAR, ERS, JP2OpenJPEG, FIT, GRIB, RMF, WMS, RST, GSAG, GSBG,
67 GS7BG, R, KMLSUPEROVERLAY, WEBP, PDF, Rasterlite, MBTiles, CALS,
68 WMTS, MRF, PNM, PAux, MFF, MFF2, BT, LAN, LCP, GTX, NTv2, CTable2,
69 KRO, ROI_PAC, RRASTER, BYN, ARG, USGSDEM, BAG, NWT_GRD, ADRG, BLX,
70 PostGISRaster, SAGA, XYZ, HF2, ZMap, SIGDEM, EXR, GPKG, NGW, ENVI,
71 EHdr, ISCE, Zarr
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 offset=float
100 Assign a specified offset value to output bands
101 scale=float
103 Assign a specified scale value to output bands
104
106 r.out.gdal allows a user to export a GRASS raster map layer into any
107 GDAL supported raster map format. If a GRASS raster map is exported for
108 a particular application, the application’s native format would be
109 preferable. GeoTIFF is supported by a wide range of applications (see
110 also NOTES on GeoTIFF below).
111 To specify multiple creation options use a comma separated list (cre‐
113 ateopt="TFW=YES,COMPRESS=DEFLATE").
114 For possible createopt and metaopt parameters please consult the indi‐
116 vidual supported formats pages on the GDAL website. The createopt pa‐
117 rameter may be used to create TFW or World files ("TFW=YES","WORLD‐
118 FILE=ON").
119 r.out.gdal also supports the export of multiband rasters as a group,
121 when the imagery group’s name is entered as input. (created imagery
122 groups with the i.group module)
123 As with most GRASS raster modules, the current region extents and re‐
125 gion resolution are used, and a MASK is respected if present. Use
126 g.region’s "align=", or "raster=" options if you need to realign the
127 region settings to match the original map’s before export.
128
130 The set of supported raster formats written by r.out.gdal depends on
131 the local GDAL installation, printed with the -l flag. Available may be
132 (incomplete list):
133 AAIGrid: Arc/Info ASCII Grid
135 BMP: MS Windows Device Independent Bitmap
136 BSB: Maptech BSB Nautical Charts
137 DTED: DTED Elevation Raster
138 ELAS: ELAS
139 ENVI: ENVI .hdr Labelled
140 FIT: FIT Image
141 GIF: Graphics Interchange Format (.gif)
142 GTiff: GeoTIFF
143 HDF4Image: HDF4 Dataset
144 HFA: Erdas Imagine Images (.img)
145 JPEG2000: JPEG-2000 part 1 (ISO/IEC 15444-1)
146 JPEG: JPEG JFIF
147 MEM: In Memory Raster
148 MFF2: Atlantis MFF2 (HKV) Raster
149 MFF: Atlantis MFF Raster
150 NITF: National Imagery Transmission Format
151 PAux: PCI .aux Labelled
152 PCIDSK: PCIDSK Database File
153 PNG: Portable Network Graphics
154 PNM: Portable Pixmap Format (netpbm)
155 VRT: Virtual Raster
156 XPM: X11 PixMap Format
157
159 Out of the GDAL data types, the closest match for GRASS CELL, FCELL and
160 DCELL rasters are respectively Int32, Float32 and Float64. These are
161 not exact equivalents, but they will preserve the maximum possible data
162 range and number of decimal places for each respective GRASS raster
163 data type. Please keep in mind that not all CELL rasters will require
164 Int32 - e.g., 0-255 CELL raster are covered by the Byte type as well.
165 Moreover, some GDAL-supported formats do not support all the data types
166 possible in GDAL and GRASS. Use r.info to check the data type and range
167 for your GRASS raster, refer to specific format documentation (on the
168 GDAL website), format vendor’s documentation, and e.g. the Wikipedia
169 article Typical boundaries of primitive integral types for details.
170 Ranges of GDAL data types
172 GDAL data type minimum maximum
173 Byte 0 255
174 UInt16 0 65,535
175 Int16, CInt16 -32,768 32,767
176 UInt32 0 4,294,967,295
177 Int32, CInt32 -2,147,483,648 2,147,483,647
178 Float32, CFloat32 -3.4E38 3.4E38
179 Float64, CFloat64 -1.79E308 1.79E308
180 If there is a need to keep file sizes small, use the simplest data type
182 covering the data range of the raster(s) to be exported, e.g., if suit‐
183 able use Byte rather than UInt16; use Int16 rather than Int32; or use
184 Float32 rather than Float64. In addition, the COMPRESS createopt used
185 can have a very large impact on the size of the output file.
186 Some software may not recognize all of the compression methods avail‐
188 able for a given file format, and certain compression methods may only
189 be supported for certain data types (depends on vendor and version).
190 If the export settings are set such that data loss would occur in the
192 output file (i.e, due to the particular choice of data type and/or file
193 type), the normal behaviour of r.out.gdal in this case would be to is‐
194 sue an error message describing the problem and exit without exporting.
195 The -f flag allows raster export even if some of the data loss tests
196 are not passed, and warnings are issued instead of errors.
197 r.out.gdal exports may appear all black or gray on initial display in
199 other GIS software. This is not a bug of r.out.gdal, but often caused
200 by the default color table assigned by that software. The default
201 color table may be grayscale covering the whole range of possible val‐
202 ues which is very large for e.g. Int32 or Float32. E.g. stretching the
203 color table to actual min/max would help (sometimes under symbology).
204 Adding overviews to speed up map display in other software
206 Adding overviews with gdaladdo after exporting can speed up display.
207 The overviews are created internally within the exported file. The
208 amount of levels (power-of-two factors) are controlled with the over‐
209 views parameter. The higher the overview level defined by the user the
210 more lower resolution internal overviews are added Note that other
211 software might create their own overviews, ignoring existing overviews.
212 GeoTIFF caveats
214 GeoTIFF exports can only be displayed by standard image viewers if the
215 GDAL data type was set to Byte and the GeoTIFF contains either one or
216 three bands. All other data types and numbers of bands can be properly
217 read with GIS software only. Although GeoTIFF files usually have a .tif
218 extension, these files are not necessarily images but first of all spa‐
219 tial raster datasets, e.g. land cover or elevation.
220 When writing out multi-band GeoTIFF images for users of ESRI software
222 or ImageMagick, the interleaving mode should be set to "pixel" using
223 createopt="INTERLEAVE=PIXEL". BAND interleaving is slightly more effi‐
224 cient, but not supported by some applications. This issue only arises
225 when writing out multi-band imagery groups.
226 Classic TIFF format supports only files with up to 4GB. Files that ex‐
228 ceed this limit (in compressed or uncompressed form) need to be ex‐
229 ported with createopt="BIGTIFF=YES". BIGTIFF is available if GDAL is
230 built with libtiff &= 4.0.
231 Improving GeoTIFF compatibility
233 To create a GeoTIFF that is highly compatible with various other GIS
234 software packages, it is recommended to keep the GeoTIFF file as simple
235 as possible. You will have to experiment with which options your soft‐
236 ware is compatible with, as this varies widely between vendors and ver‐
237 sions. Long term, the less metadata you have to remove the more
238 self-documenting (and useful) the dataset will be.
239 Here are some things to try:
241 • Create a World file with createopt="TFW=YES".
243 • Do not use GeoTIFF internal compression. Other GIS software of‐
245 ten supports only a subset of the available compression methods
246 with the supported methods differing between GIS software pack‐
247 ages. Unfortunately this means the output image can be rather
248 huge, but the file can be compressed with software like zip,
249 gnuzip, or bzip2.
250 • Skip exporting the color table. Color tables are not always
252 properly rendered, particularly for type UInt16, and the Geo‐
253 TIFF file can appear completely black. If you are lucky the
254 problematic software package has a method to reset the color
255 table and assign a new color table (sometimes called symbol‐
256 ogy).
257 • Keep metadata simple with createopt="PROFILE=GeoTIFF" or cre‐
259 ateopt="PROFILE=BASELINE". With BASELINE no GDAL or GeoTIFF
260 tags will be written and a World file is required (cre‐
261 ateopt="TFW=YES").
262 Offset/scale parameters
264 Offset is only relevant if not zero. Scale is only relevant if not 1.
265
267 Export the integer raster basin_50K map to GeoTIFF format
268 See also GeoTIFF format description (GDAL):
269 g.region raster=basin_50K -p
270 r.out.gdal input=basin_50K output=basin_50K.tif
271 Export the integer raster landclass96 map to Cloud Optimized GeoTIFF format
273 See also Cloud Optimized GeoTIFF (COG) format description (GDAL):
274 g.region -p raster=landclass96
275 r.out.gdal -fmt input=landclass96 output=landclass96.tif format=COG overviews=4
276 Export a DCELL raster map in GeoTIFF format suitable for ESRI software
278 g.region raster=elevation -p
279 r.out.gdal in=elevation output=elevation.tif createopt="PROFILE=GeoTIFF,TFW=YES"
280 Export a raster map in "Deflate" compressed GeoTIFF format
282 g.region raster=elevation -p
283 r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=DEFLATE"
284 Export a large raster map in LZW compressed (Big) GeoTIFF format
286 # integer map export
287 g.region raster=zipcodes -p
288 # Using PREDICTOR 2 for integer maps can further reduce file size
289 r.out.gdal in=zipcodes output=zipcodes.tif createopt="COMPRESS=LZW,PREDICTOR=2,BIGTIFF=YES"
290 # floating point map export
291 g.region raster=elevation -p
292 # Using PREDICTOR 3 for floating point data can further reduce file size
293 r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=LZW,PREDICTOR=3,BIGTIFF=YES"
294 Export a raster map with internal overview in "Deflate" compressed GeoTIFF
296 format
297 g.region raster=elevation -p
298 # overviews=5 corresponds to ’gdaladdo ... 2 4 8 16 32’
299 r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=DEFLATE" overviews=5
300 Export R,G,B imagery bands in GeoTIFF format suitable for ESRI software
302 i.group group=nc_landsat_rgb input=lsat7_2002_30,lsat7_2002_20,lsat7_2002_10
303 g.region raster=lsat7_2002_30 -p
304 r.out.gdal in=nc_landsat_rgb output=nc_landsat_rgb.tif type=Byte \
305 createopt="PROFILE=GeoTIFF,INTERLEAVE=PIXEL,TFW=YES"
306 Export group of image maps as multi-band file
308 g.list group
309 i.group group=tm7 subgroup=tm7 input=tm7_10,tm7_20,tm7_30,tm7_40,tm7_50,tm7_60,tm7_70
310 i.group -l tm7
311 g.region raster=tm7_10 -p
312 r.out.gdal tm7 output=lsat_multiband.tif
313 gdalinfo lsat_multiband.tif
314 Export RGB with alpha channel that encodes NULL cells
316 When exporting exporting RGB data rather than GIS data for Web applica‐
317 tions or generally the scope of visualization, the alpha channel is of
318 use. Here the export type is commonly the Byte data type.
319 When exporting data with r.out.gdal, assigning a nodata value (specific
321 parameter of the module) means that any band values equal to this no‐
322 data value will be interpreted as nodata. Using an additional alpha
323 channel means that all pixels with an alpha value of 0 are transparent.
324 The alpha channel thus represents per-pixel encoding of nodata, just
325 like the GRASS MASK (null file). That means when using an alpha chan‐
326 nel, you do not need to "free up" any particular value, but you can use
327 any value you like to replace NULL cells, as long as the value can be
328 represented by the Byte data type. It does not matter if that value is
329 already present in any of the input bands.
330 Hence for "visual-only" RGB data export it is needed to create an addi‐
332 tional alpha channel that encodes all NULL cells and in the RGB bands
333 to be exported replace NULL cells with some value in the range 0-255.
334 For example:
335 # for simplicity variables are used
337 RMAP="lsat7_2000_30"
338 GMAP="lsat7_2000_20"
339 BMAP="lsat7_2000_10"
340 OUTNAME="lsat7_2000_RGBA.tif"
341 # extract alpha
342 r.mapcalc "out_a = if(isnull($RMAP) || isnull($GMAP) || isnull($BMAP), 0, 255)"
343 # replace NULL cells with a valid value, extract colors
344 # exporting 8 bit RGB data, not GIS data, therefore the `#` operator:
345 r.mapcalc "out_r = if(isnull($RMAP), 0, #$RMAP)"
346 r.mapcalc "out_g = if(isnull($GMAP), 0, #$GMAP)"
347 r.mapcalc "out_b = if(isnull($BMAP), 0, #$BMAP)"
348 # create group for export
349 i.group group=out_rgba input=out_r,out_g,out_b,out_a
350 # remove any MASK because this works only if there are
351 # no NULL cells in the bands to be exported
352 r.mask -r
353 # export the group:
354 # add PROFILE=BASELINE to createopt to produce a standard TIFF file
355 # without any GTiff extensions
356 r.out.gdal input=out_rgba output=$OUTNAME -cm createopt="PHOTOMETRIC=RGB,ALPHA=YES"
357 gdalinfo $OUTNAME
358 The resulting GeoTIFF file can be used e.g. for Web server applica‐
359 tions.
360 Export the floating point raster elevation map to ERDAS/IMG format
362 See also Erdas Imagine .img format description (GDAL):
363 g.region raster=elevation -p
364 r.out.gdal input=elevation output=elelevation.img format=HFA type=Float32
365 Export raster map with offset/scale assigned
367 An offset value can be assigned to output raster data by offset parame‐
368 ter. Similarly a scale value can be assigned by scale parameter.
369 # produce raster map
370 g.region n=100 s=0 e=100 w=0 res=1
371 r.random.cells output=random distance=1.0
372 r.info -r random
373 # export raster data with offset/scale assigned
374 r.out.gdal input=random output=random.tif offset=100 scale=0.01
375 Check result by gdalinfo command line tool:
376 gdalinfo random.tif
377 ...
378 Band 1 Block=100x40 Type=UInt16, ColorInterp=Palette
379 Description = random
380 Computed Min/Max=1.000,3661.000
381 NoData Value=65535
382 Offset: 100, Scale:0.01
383 ...
384
386 • "ERROR 6: SetColorInterpretation() not supported for this
387 dataset.": This may indicate that the color table was not writ‐
388 ten properly. But usually it will be correct and the message
389 can be ignored.
390 • "ERROR 6: SetNoDataValue() not supported for this dataset.":
392 The selected output format does not support "no data". It is
393 recommended to use a different output format if your data con‐
394 tains NULLs.
395 • "Warning 1: Lost metadata writing to GeoTIFF ... too large to
397 fit in tag.": The color table metadata may be too large. It is
398 recommended to simplify or not write the color table, or use a
399 different output format or the flags -c and -m.
400
402 GDAL Pages: https://gdal.org
403
405 GDAL supported raster formats and GDAL supported vector formats
406 r.out.ascii, r.out.bin, r.out.mat, r.out.png, r.out.ppm, r.pack
408
410 Vytautas Vebra (oliver4grass at gmail.com)
411 Markus Metz (improved nodata logic)
412
414 Available at: r.out.gdal source code (history)
415 Accessed: Saturday Jan 21 21:14:51 2023
417 Main index | Raster index | Topics index | Keywords index | Graphical
419 index | Full index
420 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
422GRASS 8.2.1 r.out.gdal(1)