1r.out.gdal(1)                 Grass User's Manual                r.out.gdal(1)
2
3
4

NAME

6       r.out.gdal  - Exports GRASS raster maps into GDAL supported formats.
7

KEYWORDS

9       raster, export
10

SYNOPSIS

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, 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
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

DESCRIPTION

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

SUPPORTED RASTER FORMATS

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

NOTES

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   Improving GeoTIFF compatibility
222       To  create  a  GeoTIFF that is highly compatible with various other GIS
223       software packages, it is recommended to keep the GeoTIFF file as simple
224       as  possible. You will have to experiment with which options your soft‐
225       ware is compatible with, as this varies widely between vendors and ver‐
226       sions.  Long  term,  the  less  metadata  you  have  to remove the more
227       self-documenting (and useful) the dataset will be.
228
229       Here are some things to try:
230
231           ·   Create a World file with createopt="TFW=YES".
232
233           ·   Do not use GeoTIFF internal  compression.  Other  GIS  software
234               often supports only a subset of the available compression meth‐
235               ods with the supported methods differing between  GIS  software
236               packages.  Unfortunately  this  means  the  output image can be
237               rather huge, but the file can be compressed with software  like
238               zip, gnuzip, or bzip2.
239
240           ·   Skip  exporting  the  color  table. Color tables are not always
241               properly rendered, particularly for type UInt16, and  the  Geo‐
242               TIFF  file  can  appear  completely black. If you are lucky the
243               problematic software package has a method to  reset  the  color
244               table  and  assign  a new color table (sometimes called symbol‐
245               ogy).
246
247           ·   Keep metadata simple with createopt="PROFILE=GeoTIFF"  or  cre‐
248               ateopt="PROFILE=BASELINE".  With  BASELINE  no  GDAL or GeoTIFF
249               tags will be  written  and  a  World  file  is  required  (cre‐
250               ateopt="TFW=YES").
251
252       Cloud Optimized GeoTIFFs (COG) can be created with the creation options
253       createopt=TILED=YES,COMPRESS=DEFLATE, followed  by  gdaladdo  to  build
254       overviews.
255

EXAMPLES

257   Export the integer raster basin_50K map to GeoTIFF format
258       g.region raster=basin_50K -p
259       r.out.gdal input=basin_50K output=basin_50K.tif
260
261   Export a DCELL raster map in GeoTIFF format suitable for ESRI software
262       g.region raster=elevation -p
263       r.out.gdal in=elevation output=elevation.tif createopt="PROFILE=GeoTIFF,TFW=YES"
264
265   Export a raster map in "Deflate" compressed GeoTIFF format
266       g.region raster=elevation -p
267       r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=DEFLATE"
268
269   Export  a raster map with internal overview in "Deflate" compressed GeoTIFF
270       format
271       g.region raster=elevation -p
272       # overviews=5 corresponds to ’gdaladdo ... 2 4 8 16 32’
273       r.out.gdal in=elevation output=elevation.tif createopt="COMPRESS=DEFLATE" overviews=5
274
275   Export R,G,B imagery bands in GeoTIFF format suitable for ESRI software
276       i.group group=nc_landsat_rgb input=lsat7_2002_30,lsat7_2002_20,lsat7_2002_10
277       g.region raster=lsat7_2002_30 -p
278       r.out.gdal in=nc_landsat_rgb output=nc_landsat_rgb.tif type=Byte \
279         createopt="PROFILE=GeoTIFF,INTERLEAVE=PIXEL,TFW=YES"
280
281   Export the floating point raster elevation map to ERDAS/IMG format
282       g.region raster=elevation -p
283       r.out.gdal input=elevation output=elelevation.img format=HFA type=Float32
284
285   Export group of image maps as multi-band file
286       g.list group
287       i.group group=tm7 subgroup=tm7 input=tm7_10,tm7_20,tm7_30,tm7_40,tm7_50,tm7_60,tm7_70
288       i.group -l tm7
289       g.region raster=tm7_10 -p
290       r.out.gdal tm7 output=lsat_multiband.tif
291       gdalinfo lsat_multiband.tif
292
293   Export RGB with alpha channel that encodes NULL cells
294       When exporting exporting RGB data rather than GIS data for Web applica‐
295       tions  or generally the scope of visualization, the alpha channel is of
296       use. Here the export type is commonly the Byte data type.
297
298       When exporting data with r.out.gdal, assigning a nodata value (specific
299       parameter  of  the  module)  means  that  any band values equal to this
300       nodata value will be interpreted as nodata. Using an  additional  alpha
301       channel means that all pixels with an alpha value of 0 are transparent.
302       The alpha channel thus represents per-pixel encoding  of  nodata,  just
303       like  the  GRASS MASK (null file). That means when using an alpha chan‐
304       nel, you do not need to "free up" any particular value, but you can use
305       any  value  you like to replace NULL cells, as long as the value can be
306       represented by the Byte data type. It does not matter if that value  is
307       already present in any of the input bands.
308
309       Hence for "visual-only" RGB data export it is needed to create an addi‐
310       tional alpha channel that encodes all NULL cells and in the  RGB  bands
311       to  be  exported replace NULL cells with some value in the range 0-255.
312       For example:
313
314       # for simplicity variables are used
315       RMAP="lsat7_2000_30"
316       GMAP="lsat7_2000_20"
317       BMAP="lsat7_2000_10"
318       OUTNAME="lsat7_2000_RGBA.tif"
319       # extract alpha
320       r.mapcalc "out_a = if(isnull($RMAP) || isnull($GMAP) || isnull($BMAP), 0, 255)"
321       # replace NULL cells with a valid value, extract colors
322       # exporting 8 bit RGB data, not GIS data, therefore the `#` operator:
323       r.mapcalc "out_r = if(isnull($RMAP), 0, #$RMAP)"
324       r.mapcalc "out_g = if(isnull($GMAP), 0, #$GMAP)"
325       r.mapcalc "out_b = if(isnull($BMAP), 0, #$BMAP)"
326       # create group for export
327       i.group group=out_rgba input=out_r,out_g,out_b,out_a
328       # remove any MASK because this works only if there are
329       # no NULL cells in the bands to be exported
330       r.mask -r
331       # export the group:
332       # add PROFILE=BASELINE to createopt to produce a standard TIFF file
333       # without any GTiff extensions
334       r.out.gdal input=out_rgba output=$OUTNAME -cm createopt="PHOTOMETRIC=RGB,ALPHA=YES"
335       gdalinfo $OUTNAME
336       The resulting GeoTIFF file can be used e.g.  for  Web  server  applica‐
337       tions.
338
340           ·   "ERROR  6:  SetColorInterpretation()  not  supported  for  this
341               dataset.": This may indicate that the color table was not writ‐
342               ten  properly.   But usually it will be correct and the message
343               can be ignored.
344
345           ·   "ERROR 6: SetNoDataValue() not supported  for  this  dataset.":
346               The  selected  output  format does not support "no data". It is
347               recommended to use a different output format if your data  con‐
348               tains NULLs.
349
350           ·   "Warning  1:  Lost metadata writing to GeoTIFF ... too large to
351               fit in tag.": The color table metadata may be too large. It  is
352               recommended  to simplify or not write the color table, or use a
353               different output format or the flags -c and -m.
354

SEE ALSO

356       The GDAL supported formats page.
357        r.out.ascii, r.out.bin, r.out.mat, r.out.png, r.out.ppm, r.pack
358

REFERENCES

360       GDAL Pages: http://www.gdal.org
361

AUTHORS

363       Vytautas Vebra (oliver4grass at gmail.com)
364       Markus Metz (improved nodata logic)
365
366       Last changed: $Date: 2019-01-15 10:57:42 +0100 (Tue, 15 Jan 2019) $
367

SOURCE CODE

369       Available at: r.out.gdal source code (history)
370
371       Main index | Raster index | Topics index | Keywords index  |  Graphical
372       index | Full index
373
374       © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual
375
376
377
378GRASS 7.6.0                                                      r.out.gdal(1)
Impressum