Provided by: grass-doc_8.3.0-1_all bug

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: Tuesday Jun 27 11:12:53 2023

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

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