## NAME

r.in.gdal - Imports raster data into a GRASS raster map using GDAL library.

## KEYWORDS

raster, import, create location

## SYNOPSIS

r.in.gdal
r.in.gdal --help
r.in.gdal [-ojeflakcrp] input=name output=name [band=integer[,integer,...]] [memory=memory in MB] [target=name] [title=phrase] [offset=integer] [num_digits=integer] [map_names_file=name] [location=name] [table=file] [gdal_config=string] [gdal_doo=string] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

### Flags:

-o
  Override projection check (use current location's projection)
  Assume that the dataset has same projection as the current location
-j
  Perform projection check only and exit
-e
  Extend region extents based on new dataset
  Also updates the default region if in the PERMANENT mapset
-f
  List supported formats and exit
-l
  Force Lat/Lon maps to fit into geographic coordinates (90N,S; 180E,W)
-a
  Auto-adjustment for lat/lon
  Attempt to fix small precision errors in resolution and extents
-k
  Keep band numbers instead of using band color names
-c
  Create the location specified by the "location" parameter and exit. Do not import the raster file.
-r
  Limit import to the current region
-p
  Print number of bands and exit
--overwrite
  Allow output files to overwrite existing files
--help
  Print usage summary
--verbose
  Verbose module output
--quiet
  Quiet module output
--ui
  Force launching GUI dialog

### Parameters:

input=name [required]
  Name of raster file to be imported
output=name [required]
  Name for output raster map
band=integer[,integer,...]
  Band(s) to select (default is all bands)
memory=memory in MB
  Maximum memory to be used (in MB)
  Cache size for raster rows
  Default: 300
target=name
  Name of GCPs target location
  Name of location to create or to read projection from for GCPs transformation
title=phrase
  Title for resultant raster map
offset=integer
  Offset to be added to band numbers
  If 0, no offset is added and the first band is 1
  Default: 0
num_digits=integer
  Zero-padding of band number by filling with leading zeros up to given number
  If 0, length will be adjusted to 'offset' number without leading zeros
  Default: 0
map_names_file=name
  Name of the output file that contains the imported map names
location=name
  Name for new location to create
table=file
  File prefix for raster attribute tables
  The band number and ".csv" will be appended to the file prefix
gdal_config=string
  GDAL configuration options
  Comma-separated list of key=value pairs
gdal_doo=string
  GDAL dataset open options
  Comma-separated list of key=value pairs

## DESCRIPTION

r.in.gdal allows a user to create a GRASS GIS raster map layer, or imagery group, from any GDAL supported raster map format, with an optional title. The imported file may also be optionally used to create a new location.

### GDAL supported raster formats

Full details on all GDAL supported formats are available at:

http://www.gdal.org/formats_list.html

Selected formats out of the more than 140 supported formats:

    Long Format Name                              Code           Creation  Georeferencing Maximum file size
    ---------------------------------------------+-------------+----------+--------------+-----------------
    ADRG/ARC Digitilized Raster Graphics          ADRG              Yes      Yes          --
    Arc/Info ASCII Grid                           AAIGrid           Yes      Yes          2GB
    Arc/Info Binary Grid (.adf)                   AIG               No       Yes          --
    Arc/Info Export E00 GRID                      E00GRID           No       Yes          --
    ArcSDE Raster                                 SDE               No       Yes          --
    ASCII Gridded XYZ                             XYZ               Yes      Yes          --
    BSB Nautical Chart Format (.kap)              BSB               No       Yes          --
    CEOS (Spot for instance)                      CEOS              No       No           --
    DB2                                           DB2               Yes      Yes          No limits
    DODS / OPeNDAP                                DODS              No       Yes          --
    EarthWatch/DigitalGlobe .TIL                  TIL               No       No           --
    ENVI .hdr Labelled Raster                     ENVI              Yes      Yes          No limits
    Envisat Image Product (.n1)                   ESAT              No       No           --
    EOSAT FAST Format                             FAST              No       Yes          --
    Epsilon - Wavelet compressed images           EPSILON           Yes      No           --
    Erdas 7.x .LAN and .GIS                       LAN               No       Yes          2GB
    ERDAS Compressed Wavelets (.ecw)              ECW               Yes      Yes
    Erdas Imagine (.img)                          HFA               Yes      Yes          No limits
    Erdas Imagine Raw                             EIR               No       Yes          --
    ERMapper (.ers)                               ERS               Yes      Yes
    ESRI .hdr Labelled                            EHdr              Yes      Yes          No limits
    EUMETSAT Archive native (.nat)                MSGN              No       Yes
    FIT                                           FIT               Yes      No           --
    FITS (.fits)                                  FITS              Yes      No           --
    Fuji BAS Scanner Image                        FujiBAS           No       No           --
    GDAL Virtual (.vrt)                           VRT               Yes      Yes          --
    Generic Binary (.hdr Labelled)                GENBIN            No       No           --
    GeoPackage                                    GPKG              Yes      Yes          No limits
    Geospatial PDF                                PDF               Yes      Yes          --
    GMT Compatible netCDF                         GMT               Yes      Yes          2GB
    Golden Software Surfer 7 Binary Grid          GS7BG             Yes      Yes          4GiB
    Graphics Interchange Format (.gif)            GIF               Yes      No           2GB
    GRASS Raster Format                           GRASS             No       Yes          --
    GSat File Format                              GFF               No       No           --
    Hierarchical Data Format Release 4 (HDF4)     HDF4              Yes      Yes          2GiB
    Hierarchical Data Format Release 5 (HDF5)     HDF5              No       Yes          2GiB
    Idrisi Raster                                 RST               Yes      Yes          No limits
    ILWIS Raster Map (.mpr,.mpl)                  ILWIS             Yes      Yes          --
    Image Display and Analysis (WinDisp)          IDA               Yes      Yes          2GB
    In Memory Raster                              MEM               Yes      Yes
    Intergraph Raster                             INGR              Yes      Yes          2GiB
    IRIS                                          IRIS              No       Yes          --
    Japanese DEM (.mem)                           JDEM              No       Yes          --
    JAXA PALSAR Product Reader (Level 1.1/1.5)    JAXAPALSAR        No       No           --
    JPEG2000 (.jp2, .j2k)                         JP2OpenJPEG       Yes      Yes
    JPEG JFIF (.jpg)                              JPEG              Yes      Yes          4GiB
    KMLSUPEROVERLAY                               KMLSUPEROVERLAY   Yes      Yes
    MBTiles                                       MBTiles           Yes      Yes          --
    Meta Raster Format                            MRF               Yes      Yes          --
    Meteosat Second Generation                    MSG               No       Yes
    MG4 Encoded Lidar                             MG4Lidar          No       Yes          --
    Microsoft Windows Device Independent Bitmap   BMP               Yes      Yes          4GiB
    Military Elevation Data (.dt0, .dt1, .dt2)    DTED              Yes      Yes          --
    Multi-resolution Seamless Image Database      MrSID             No       Yes          --
    NASA Planetary Data System                    PDS               No       Yes          --
    NetCDF                                        netCDF            Yes      Yes          2GB
    Netpbm (.ppm,.pgm)                            PNM               Yes      No           No limits
    NITF                                          NITF              Yes      Yes          10GB
    NLAPS Data Format                             NDF               No       Yes          No limits
    NOAA NGS Geoid Height Grids                   NGSGEOID          No       Yes
    NOAA Polar Orbiter Level 1b Data Set (AVHRR)  L1B               No       Yes          --
    OGC Web Coverage Service                      WCS               No       Yes          --
    OGC Web Map Service, and TMS, WorldWind, On EaWMS               No       Yes          --
    OGC Web Map Tile Service                      WMTS              No       Yes          --
    OGDI Bridge                                   OGDI              No       Yes          --
    Oracle Spatial GeoRaster                      GEORASTER         Yes      Yes          No limits
    OziExplorer .MAP                              MAP               No       Yes          --
    OZI OZF2/OZFX3                                OZI               No       Yes          --
    PCI Geomatics Database File                   PCIDSK            Yes      Yes          No limits
    PCRaster                                      PCRaster          Yes      Yes
    Planet Labs Mosaics API                       PLMosaic          No       Yes          --
    Portable Network Graphics (.png)              PNG               Yes      No
    PostGIS Raster (previously WKTRaster)         PostGISRaster     No       Yes          --
    RadarSat2 XML (product.xml)                   RS2               No       Yes          4GB
    Rasdaman                                      RASDAMAN          No       No           No limits
    Rasterlite - Rasters in SQLite DB             Rasterlite        Yes      Yes          --
    Raster Product Format/RPF (CADRG, CIB)        RPFTOC            No       Yes          --
    R Object Data Store                           R                 Yes      No           --
    ROI_PAC Raster                                ROI_PAC           Yes      Yes          --
    R Raster (.grd)                               RRASTER           No       Yes          --
    SAGA GIS Binary format                        SAGA              Yes      Yes          --
    SAR CEOS                                      SAR_CEOS          No       Yes          --
    Sentinel 1 SAR SAFE (manifest.safe)           SAFE              No       Yes          No limits
    Sentinel 2                                    SENTINEL2         No       Yes          No limits
    SGI Image Format                              SGI               Yes      Yes          --
    SRTM HGT Format                               SRTMHGT           Yes      Yes          --
    TerraSAR-X Complex SAR Data Product           COSAR             No       No           --
    TerraSAR-X Product                            TSX               Yes      No           --
    TIFF / BigTIFF / GeoTIFF (.tif)               GTiff             Yes      Yes          4GiB/None for BigTIFF
    USGS ASCII DEM / CDED (.dem)                  USGSDEM           Yes      Yes          --
    USGS Astrogeology ISIS cube (Version 3)       ISIS3             No       Yes          --
    USGS SDTS DEM (*CATD.DDF)                     SDTS              No       Yes          --
    Vexcel MFF                                    MFF               Yes      Yes          No limits
    VICAR                                         VICAR             No       Yes          --
    VTP Binary Terrain Format (.bt)               BT                Yes      Yes          --
    WEBP                                          WEBP              Yes      No           --
    WMO GRIB1/GRIB2 (.grb)                        GRIB              No       Yes          2GB

### Location Creation

r.in.gdal attempts to preserve projection information when importing datasets if the source format includes projection information, and if the GDAL driver supports it. If the projection of the source dataset does not match the projection of the current location r.in.gdal will report an error message (`Projection of dataset does not appear to match current location`) and then report the PROJ_INFO parameters of the source dataset.

If the user wishes to ignore the difference between the apparent coordinate system of the source data and the current location, they may pass the -o flag to override the projection check.

If the user wishes to import the data with the full projection definition, it is possible to have r.in.gdal automatically create a new location based on the projection and extents of the file being read. This is accomplished by passing the name to be used for the new location via the location parameter. Upon completion of the command, a new location will have been created (with only a PERMANENT mapset), and the raster will have been imported with the indicated output name into the PERMANENT mapset.

### Support for Ground Control Points

In case the image contains Ground Control Points (GCP) they are written to a POINTS file within an imagery group. They can directly be used for i.rectify.

The target option allows you to automatically re-project the GCPs from their own projection into another projection read from the PROJ_INFO file of the location name target.

If the target location does not exist, a new location will be created matching the projection definition of the GCPs. The target of the output group will be set to the new location, and i.rectify can now be used without any further preparation.

Some satellite images (e.g. NOAA/AVHRR, ENVISAT) can contain hundreds or thousands of GCPs. In these cases thin plate spline coordinate transformation is recommended, either before import with gdalwarp -tps or after import with i.rectify -t.

### Map names: Management of offset and leading zeros

The offset parameter allows adding an offset to band number(s) which is convenient in case of the import of e.g. a continuous time series split across different input files.

The num_digits parameter allows defining the number of leading zeros (zero padding) in case of band numbers (e.g., to turn `band.1` into `band.001`).

## NOTES

Import of large files can be significantly faster when setting memory to the size of the input file.

The r.in.gdal command does support the following features, as long as the underlying format driver supports it:

Color Table
  Bands with associated colortables will have the color tables transferred. Note that if the source has no colormap, r.in.gdal in GRASS 5.0 will emit no colormap. Use r.colors map=... color=grey to assign a greyscale colormap. In a future version of GRASS r.in.gdal will likely be upgraded to automatically emit greyscale colormaps.
Data Types
  Most GDAL data types are supported. Float32 and Float64 type bands are translated as GRASS floating point cells (but not double precision ... this could be added if needed), and most other types are translated as GRASS integer cells. This includes 16bit integer data sources. Complex (some SAR signal data formats) data bands are translated to two floating point cell layers (*.real and *.imaginary).
Georeferencing
  If the dataset has affine georeferencing information, this will be used to set the north, south, east and west edges. Rotational coefficients will be ignored, resulting in incorrect positioning for rotated datasets.
Projection
  The dataset's projection will be used to compare to the current location or to define a new location. Internally GDAL represents projections in OpenGIS Well Known Text format. A large subset of the total set of GRASS projections are supported.
Null Values
  Raster bands for which a null value is recognised by GDAL will have the null pixels transformed into GRASS style nulls during import. Many generic formats (and formats poorly supported by GDAL) do not have a way of recognising null pixels in which case r.null should be used after the import.
GCPs
  Datasets that have Ground Control Points will have them imported as a POINTS file associated with the imagery group. Datasets with only one band that would otherwise have been translated as a simple raster map will also have an associated imagery group if there are ground control points. The coordinate system of the ground control points is reported by r.in.gdal but not preserved. It is up to the user to ensure that the location established with i.target has a compatible coordinate system before using the points with i.rectify.
Raster Attribute Tables
  r.in.gdal can write out raster attribute tables as CSV files. Moreover, information in raster attribute tables is automatically imported as long as the field definitions contain information about how to use a field, e.g. for color information or for labels.

Planned improvements to r.in.gdal in the future include support for reporting everything known about a dataset if the output parameter is not set.

### Error Messages

"ERROR: Input map is rotated - cannot import."
In this case the image must be first externally rotated, applying the rotation info stored in the metadata field of the raster image file. For example, the gdalwarp software can be used to transform the map to North-up (note, there are several gdalwarp parameters to select the resampling algorithm):

    gdalwarp rotated.tif northup.tif

"ERROR: Projection of dataset does not appear to match the current location."
You need to create a location whose projection matches the data you wish to import. Try using location parameter to create a new location based upon the projection information in the file. If desired, you can then re-project it to another location with r.proj. Alternatively you can override this error by using the -o flag.

"WARNING: G_set_window(): Illegal latitude for North"
Latitude/Longitude locations in GRASS can not have regions which exceed 90° North or South. Non-georeferenced imagery will have coordinates based on the images's number of pixels: 0,0 in the bottom left; cols,rows in the top right. Typically imagery will be much more than 90 pixels tall and so the GIS refuses to import it. If you are sure that the data is appropriate for your Lat/Lon location and intentd to reset the map's bounds with the r.region module directly after import you may use the -l flag to constrain the map coordinates to legal values. While the resulting bounds and resolution will likely be wrong for your map the map's data will be unaltered and safe. After resetting to known bounds with r.region you should double check them with r.info, paying special attention to the map resolution. In most cases you will want to import into the datafile's native projection, or into a simple XY location and use the Georectifaction tools (i.rectify et al.) to properly project into the target location. The -l flag should only be used if you know the projection is correct but the internal georeferencing has gotten lost, and you know the what the map's bounds and resolution should be beforehand.

## EXAMPLES

### ECAD Data

The European Climate Assessment and Dataset (ECAD) project provides climate data for Europe ranging from 1950 - 2015 or later (Terms of use). To import the different chunks of data provided by the project as netCDF files, the offset parameter can be used to properly assign numbers to the series of daily raster maps from 1st Jan 1950 (in case of importing the ECAD data split into multi-annual chunks). The ECAD data must be imported into a LatLong location.

By using the num_digits parameter leading zeros are added to the map name numbers, allowing for chronological numbering of the imported raster map layers, so that g.list lists them in the correct order. Here, use num_digits=5 to have a 5 digit suffix with leading zeros (00001 - 99999).

    # Import of ECAD data split into chunks
    # Import precipitation data
    r.in.gdal -o input=rr_0.25deg_reg_1950-1964_v12.0.nc output=precipitation num_digits=5 offset=0
    r.in.gdal -o input=rr_0.25deg_reg_1965-1979_v12.0.nc output=precipitation num_digits=5 offset=5479
    r.in.gdal -o input=rr_0.25deg_reg_1980-1994_v12.0.nc output=precipitation num_digits=5 offset=10957
    r.in.gdal -o input=rr_0.25deg_reg_1995-2015_v12.0.nc output=precipitation num_digits=5 offset=16436

    # Import air pressure data
    r.in.gdal -o input=pp_0.25deg_reg_1950-1964_v12.0.nc output=air_pressure num_digits=5 offset=0
    r.in.gdal -o input=pp_0.25deg_reg_1965-1979_v12.0.nc output=air_pressure num_digits=5 offset=5479
    r.in.gdal -o input=pp_0.25deg_reg_1980-1994_v12.0.nc output=air_pressure num_digits=5 offset=10957
    r.in.gdal -o input=pp_0.25deg_reg_1995-2015_v12.0.nc output=air_pressure num_digits=5 offset=16436

    # Import min temperature data
    r.in.gdal -o input=tn_0.25deg_reg_1950-1964_v12.0.nc output=temperatur_min num_digits=5 offset=0
    r.in.gdal -o input=tn_0.25deg_reg_1965-1979_v12.0.nc output=temperatur_min num_digits=5 offset=5479
    r.in.gdal -o input=tn_0.25deg_reg_1980-1994_v12.0.nc output=temperatur_min num_digits=5 offset=10957
    r.in.gdal -o input=tn_0.25deg_reg_1995-2015_v12.0.nc output=temperatur_min num_digits=5 offset=16436

    # Import max temperature data
    r.in.gdal -o input=tx_0.25deg_reg_1950-1964_v12.0.nc output=temperatur_max num_digits=5 offset=0
    r.in.gdal -o input=tx_0.25deg_reg_1965-1979_v12.0.nc output=temperatur_max num_digits=5 offset=5479
    r.in.gdal -o input=tx_0.25deg_reg_1980-1994_v12.0.nc output=temperatur_max num_digits=5 offset=10957
    r.in.gdal -o input=tx_0.25deg_reg_1995-2015_v12.0.nc output=temperatur_max num_digits=5 offset=16436

    # Import mean temperature data
    r.in.gdal -o input=tg_0.25deg_reg_1950-1964_v12.0.nc output=temperatur_mean num_digits=5 offset=0
    r.in.gdal -o input=tg_0.25deg_reg_1965-1979_v12.0.nc output=temperatur_mean num_digits=5 offset=5479
    r.in.gdal -o input=tg_0.25deg_reg_1980-1994_v12.0.nc output=temperatur_mean num_digits=5 offset=10957
    r.in.gdal -o input=tg_0.25deg_reg_1995-2015_v12.0.nc output=temperatur_mean num_digits=5 offset=16436

### GTOPO30 DEM

To avoid the GTOPO30 data being read incorrectly, you can add a new line "PIXELTYPE SIGNEDINT" in the .HDR to force interpretation of the file as signed rather than unsigned integers. Then the .DEM file can be imported. Finally, e.g. the 'terrain' color table can be assigned to the imported map with r.colors.

### GLOBE DEM

To import GLOBE DEM tiles (approx 1km resolution, better than GTOPO30 DEM data), the user has to download additionally the related HDR file(s). Finally, e.g. the 'terrain' color table can be assigned to the imported map with r.colors. See also their DEM portal.

### Raster file import over network

Since GDAL 2.x it is possible to import raster data over the network (see GDAL Virtual File Systems) including Cloud Optimized GeoTIFF, i.e. access uncompressed and compressed raster data via a http(s) or ftp connection. As an example the import of the global SRTMGL1 V003 tiles at 1 arc second (about 30 meters) resolution, void-filled:

    r.in.gdal /vsicurl/https://www.datenatlas.de/geodata/public/srtmgl1/srtmgl1.003.tif output=srtmgl1_v003_30m memory=2000
    g.region raster=srtmgl1_v003_30m -p
    r.colors srtmgl1_v003_30m color=srtm_plus

### Worldclim.org data

To import the BIL data from Worldclim, the following line has to be added to each .hdr file:

    PIXELTYPE SIGNEDINT

To import the ESRI Grd data from Worldclim, the broken spatial extent (exceeding the boundaries) needs to be fixed prior to import:

    # example: tmean dataset
    gdal_translate -a_ullr -180 90 180 -60 tmean_1 tmean_1_fixed.tif
    r.in.gdal input=tmean_1_fixed.tif output=tmean_1

### HDF

The import of HDF bands requires the specification of the individual bands as seen by GDAL:

    # Example MODIS FPAR
    gdalinfo MOD15A2.A2003153.h18v04.004.2003171141042.hdf
    ...
    Subdatasets:
      SUBDATASET_1_NAME=HDF4_EOS:EOS_GRID:"MOD15A2.A2003153.h18v04.004.2003171141042.hdf":MOD_Grid_MOD15A2:Fpar_1km
      SUBDATASET_1_DESC=[1200x1200] Fpar_1km MOD_Grid_MOD15A2 (8-bit unsigned integer)
      SUBDATASET_2_NAME=HDF4_EOS:EOS_GRID:"MOD15A2.A2003153.h18v04.004.2003171141042.hdf":MOD_Grid_MOD15A2:Lai_1km
      SUBDATASET_2_DESC=[1200x1200] Lai_1km MOD_Grid_MOD15A2 (8-bit unsigned integer)
    ...

    # import of first band, here FPAR 1km:
    r.in.gdal HDF4_EOS:EOS_GRID:"MOD15A2.A2003153.h18v04.004.2003171141042.hdf":MOD_Grid_MOD15A2:Fpar_1km \
              out=fpar_1km_2003_06_02
    # ... likewise for other HDF bands in the file.

## REFERENCES

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

## SEE ALSO

r.colors, r.import, r.in.ascii, r.in.bin, r.null, t.register

GRASS GIS Wiki page: Import of Global datasets

## AUTHOR

Frank Warmerdam (email).

## SOURCE CODE

Available at: r.in.gdal source code (history)

Accessed: Saturday Dec 02 22:12:17 2023

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual