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

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

EXAMPLES

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

SEE ALSO

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

REFERENCES

370       GDAL Pages: http://www.gdal.org
371

AUTHORS

373       Vytautas Vebra (oliver4grass at gmail.com)
374       Markus Metz (improved nodata logic)
375

SOURCE CODE

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-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
383
384
385
386GRASS 7.8.2                                                      r.out.gdal(1)
Impressum