Geografic-Information-System/raster/r.in.gdal/r.in.gdal.html

<h2>DESCRIPTION</h2>

<em>r.in.gdal</em> 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.

<!--
Extended explanations:

<dt><b>-e</b>
<dd>Extend the DEFAULT_WIND in PERMANENT mapset to include the region of
the new map layer.  Old resolution is preserved, but the region, and rows/cols
are updated.  This will fail if the user doesn't have write access to the
PERMANENT mapset.
</dl>
-->

<h3>GDAL supported raster formats</h3>

Full details on all GDAL supported formats are available at:
<p>
<a href="http://www.gdal.org/formats_list.html">http://www.gdal.org/formats_list.html</a>
<p>
Selected formats out of the more than 140 supported formats:

<div class="code"><pre>
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
</pre></div>

<h3>Location Creation</h3>

<em>r.in.gdal</em> 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 <em>r.in.gdal</em> will 
report an error message (<tt>Projection of dataset does not appear to 
match current location</tt>) and then report the PROJ_INFO parameters of
the source dataset.

<p>
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 
<b>-o</b> flag to override the projection check. 

<p>
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 <b>location</b>
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 <b>output</b> name into the PERMANENT mapset.

<h3>Support for GCPs</h3>
In case the image contains GCPs they are written to a
POINTS file within an imagery group. They can directly be used for 
<a href="i.rectify.html">i.rectify</a>.
<p>
The <b>target</b> 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 <b>target</b>.
<p>
If the <b>target</b> 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 
<a href=i.rectify.html>i.rectify</a> can now be used without any further 
preparation. 
<p>
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 
<b>gdalwarp -tps</b> or after import with <b>i.rectify -t</b>.


<h3>Map names: Management of offset and leading zeros</h3>

The <b>offset</b> 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.
<p>
The <b>num_digits</b> parameter allows defining the number of  leading zeros
(zero padding) in case of band numbers (e.g., to turn <tt>band.1</tt> into
<tt>band.001</tt>).


<h2>NOTES</h2>

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

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

<p>
<dl>

<dt> Color Table
<dd> 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.<br>

<dt> Data Types
<dd> 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).<br>

<dt> Georeferencing
<dd> 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.<br>

<dt> Projection
<dd> The datasets 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.<br>

<dt> Null Values
<dd> 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.<br>

<dt> GCPs
<dd> 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.<br>

</dl>

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

<h3>Error Messages</h3>

<i>"ERROR: Input map is rotated - cannot import."</i><br>
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 
<a href="http://www.gdal.org/gdal_utilities.html">gdalwarp</a>  software can be used 
to transform the map to North-up (note, there are several gdalwarp parameters to select the
resampling algorithm):

<div class="code"><pre>
gdalwarp rotated.tif northup.tif
</pre></div>

<p>
<i>"ERROR: Projection of dataset does not appear to match the current location."</i><br>

You need to create a location whose projection matches the data you
wish to import. Try using <b>location</b> 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 <em>r.proj</em>.
Alternatively you can override this error by using the <b>-o</b> flag.

<p>
<i>"WARNING: G_set_window(): Illegal latitude for North"</i><br>

Latitude/Longitude locations in GRASS can not have regions which exceed
90&deg; 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 <em>r.region</em> module directly after import you may
use the <b>-l</b> 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 <em>r.region</em> you should double check them with
<em>r.info</em>, 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
(<em>i.rectify</em> et al.) to properly project into the target location.
The <b>-l</b> flag should <i>only</i> 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.


<h2>EXAMPLES</h2>

<h3>ECAD Data</h3>

The <a href="http://eca.knmi.nl/">European Climate Assessment and Dataset (ECAD) project</a> 
provides climate data for Europe ranging from 1950 - 2015 or later
(<a href="http://eca.knmi.nl/download/ensembles/ensembles.php">Terms of use</a>).
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.
<p>
By using the <em>num_digits</em> parameter leading zeros are added to the
map name numbers, allowing for chronological numbering of the imported raster
map layers, so that <em>g.list</em> lists them in the correct order.
Here, use <em>num_digits=5</em> to have a 5 digit suffix with leading zeros (00001 - 99999).
</p>

<div class="code"><pre>
# 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
</pre></div>


<h3>GTOPO30 DEM</h3>

To avoid that the GTOPO30 data are 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 <em>r.colors</em>.


<h3>GLOBE DEM</h3>

To import <a href="http://www.ngdc.noaa.gov/mgg/topo/elev/">GLOBE DEM tiles</a>
(approx 1km resolution, better than GTOPO30 DEM data), the user has to download
additionally the related <a href="http://www.ngdc.noaa.gov/mgg/topo/elev/esri/hdr/">HDR file(s)</a>.
Finally, e.g. the 'terrain' color table can be assigned to the imported map with <em>r.colors</em>.
See also their <a href="http://www.ngdc.noaa.gov/mgg/dem/demportal.html">DEM portal</a>.

<h3>Worldclim.org data</h3>

To import the BIL data from <a href="http://www.worldclim.org">Worldclim</a>, the following
line has to be added to each .hdr file:
<div class="code"><pre>
PIXELTYPE SIGNEDINT
</pre></div>
<p>

To import the ESRI Grd data from <a href="http://www.worldclim.org">Worldclim</a>, the
broken spatial extent (exceeding the boundaries) needs to be fixed prior to import: 

<div class="code"><pre>
# 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
</pre></div>

<h3>HDF</h3>

The import of HDF bands requires the specification of the individual bands
as seen by GDAL:
<div class="code"><pre>
# 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.
</pre></div>


<h2>SEE ALSO</h2>
<em>
<a href="r.colors.html">r.colors</a>,
<a href="r.import.html">r.import</a>,
<a href="r.in.ascii.html">r.in.ascii</a>,
<a href="r.in.bin.html">r.in.bin</a>,
<a href="r.null.html">r.null</a>,
<a href="t.register.html">t.register</a>
</em>

<p>
GRASS GIS Wiki page: Import of <a href="http://grasswiki.osgeo.org/wiki/Global_datasets">Global datasets</a>

<h2>REFERENCES</h2>

GDAL Pages: <a href="http://www.gdal.org">http://www.gdal.org/</a><br>

<h2>AUTHOR</h2>

<a href="http://home.gdal.org/warmerda/">Frank Warmerdam</a>
 (<a href="mailto:warmerdam AT pobox dot com">email</a>).

<p>
<i>Last changed: $Date$</i>