~ubuntu-branches/ubuntu/wily/grass/wily

<h2>DESCRIPTION</h2>

<em>r.in.gdal</em> allows a user to create a (binary) GRASS 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 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 of the more than 80 supported formats:

<div class="code"><pre>

Long Format Name                                        Code                    Creation        Georeferencing          Maximum File Size

Arc/Info ASCII Grid                                     AAIGrid                 Yes             Yes                     No limits

Arc/Info Binary Grid                                    AIG                     No              Yes                     --

AIRSAR Polarimetric                                     AIRSAR                  No              No                      --

Microsoft Windows Device Independent Bitmap (.bmp)      BMP                     Yes             Yes                     4GiB

BSB Nautical Chart Format (.kap)                        BSB                     No              Yes                     --

VTP Binary Terrain Format (.bt)                         BT                      Yes             Yes                     --

CEOS (Spot for instance)                                CEOS                    No              No                      --

First Generation USGS DOQ (.doq)                        DOQ1                    No              Yes                     --

New Labelled USGS DOQ (.doq)                            DOQ2                    No              Yes                     --

Data (.dt0, .dt1)                                       DTED                    No              Yes                     --

ERMapper Compressed Wavelets (.ecw)                     ECW                     Yes             Yes			

ESRI .hdr Labelled                                      EHdr                    No              Yes                     --

ENVI .hdr Labelled Raster                               ENVI                    Yes             Yes                     No limits

Envisat Image Product (.n1)                             Envisat                 No              No                      --

EOSAT FAST Format                                       FAST                    No              Yes                     --

FITS (.fits)                                            FITS                    Yes             No			

Graphics Interchange Format (.gif)                      GIF                     Yes             No                      2GB

Arc/Info Binary Grid (.adf)                             GIO                     Yes             Yes		     

GRASS Rasters                                           GRASS                   No              Yes                     --

TIFF / GeoTIFF (.tif)                                   GTiff                   Yes             Yes                     4GiB

Hierarchical Data Format Release 4 (HDF4)               HDF4                    Yes             Yes                     2GiB

Erdas Imagine (.img)                                    HFA                     Yes             Yes                     No limits

Atlantis MFF2e                                          HKV                     Yes             Yes                     No limits

Image Display and Analysis (WinDisp)                    IDA                     Yes             Yes                     2GB

ILWIS Raster Map (.mpr,.mpl)                            ILWIS                   Yes             Yes                     --

Japanese DEM (.mem)                                     JDEM                    No              Yes                     --

JPEG JFIF (.jpg)                                        JPEG                    Yes             Yes                     4GiB (max dimentions 65500x65500)

JPEG2000 (.jp2, .j2k)                                   JPEG2000                Yes             Yes                     2GiB

JPEG2000 (.jp2, .j2k)                                   JP2KAK                  Yes             Yes                     No limits

NOAA Polar Orbiter Level 1b Data Set (AVHRR)            L1B                     No              Yes                     --

Erdas 7.x .LAN and .GIS                                 LAN                     No              Yes                     2GB

In Memory Raster                                        MEM                     Yes             Yes                     2GiB

Atlantis MFF                                            MFF                     Yes             Yes                     No limits

Multi-resolution Seamless Image Database                MrSID                   No              Yes                     --

NDF                                                     NLAPS Data Format       No              Yes                     No limits

NITF                                                    NITF                    Yes             Yes		

NetCDF                                                  netCDF                  Yes             Yes                     2GB

OGDI Bridge                                             OGDI                    No              Yes                     --

PCI .aux Labelled                                       PAux                    Yes             No                      No limits

PCI Geomatics Database File                             PCIDSK                  Yes             Yes                     No limits

Portable Network Graphics (.png)                        PNG                     Yes             No		

PCRaster (.map)                                         PCRaster                Yes             No			

Netpbm (.ppm,.pgm)                                      PNM                     Yes             No                      No limits

RadarSat2 XML (product.xml)                             RS2                     No              Yes                     4GB

USGS SDTS DEM (*CATD.DDF)                               SDTS                    No              Yes                     --

SAR CEOS                                                SAR_CEOS                No              Yes                     --

USGS ASCII DEM (.dem)                                   USGSDEM                 No              Yes                     --

X11 Pixmap (.xpm)                                       XPM                     Yes             No			

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

<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° 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 - 2010. To import the different 

chunks of data provided by the project as netCDF files, the offset parameter can be used to get 

daily numbered raster maps from 1. Jan. 1950 on. Make sure you are in a LatLong location.

<div class="code"><pre>

# Import precipitation data

r.in.gdal -o input=rr_0.25deg_reg_1950-1964_v4.0.nc output=precipitation offset=0

r.in.gdal -o input=rr_0.25deg_reg_1965-1979_v4.0.nc output=precipitation offset=5479

r.in.gdal -o input=rr_0.25deg_reg_1980-1994_v4.0.nc output=precipitation offset=10957

r.in.gdal -o input=rr_0.25deg_reg_1995-2010_v4.0.nc output=precipitation offset=16436

# Import air pressure data

r.in.gdal -o input=pp_0.25deg_reg_1950-1964_v4.0.nc output=air_pressure offset=0

r.in.gdal -o input=pp_0.25deg_reg_1965-1979_v4.0.nc output=air_pressure offset=5479

r.in.gdal -o input=pp_0.25deg_reg_1980-1994_v4.0.nc output=air_pressure offset=10957

r.in.gdal -o input=pp_0.25deg_reg_1995-2010_v4.0.nc output=air_pressure offset=16436

# Import min temperature data

r.in.gdal -o input=tn_0.25deg_reg_1950-1964_v4.0.nc output=temperatur_min offset=0

r.in.gdal -o input=tn_0.25deg_reg_1965-1979_v4.0.nc output=temperatur_min offset=5479

r.in.gdal -o input=tn_0.25deg_reg_1980-1994_v4.0.nc output=temperatur_min offset=10957

r.in.gdal -o input=tn_0.25deg_reg_1995-2010_v4.0.nc output=temperatur_min offset=16436

# Import max temperature data

r.in.gdal -o input=tx_0.25deg_reg_1950-1964_v4.0.nc output=temperatur_max offset=0

r.in.gdal -o input=tx_0.25deg_reg_1965-1979_v4.0.nc output=temperatur_max offset=5479

r.in.gdal -o input=tx_0.25deg_reg_1980-1994_v4.0.nc output=temperatur_max offset=10957

r.in.gdal -o input=tx_0.25deg_reg_1995-2010_v4.0.nc output=temperatur_max offset=16436

# Import mean temperature data

r.in.gdal -o input=tg_0.25deg_reg_1950-1964_v4.0.nc output=temperatur_mean offset=0

r.in.gdal -o input=tg_0.25deg_reg_1965-1979_v4.0.nc output=temperatur_mean offset=5479

r.in.gdal -o input=tg_0.25deg_reg_1980-1994_v4.0.nc output=temperatur_mean offset=10957

r.in.gdal -o input=tg_0.25deg_reg_1995-2010_v4.0.nc output=temperatur_mean 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/seg/topo/gltiles.shtml">GLOBE DEM tiles</a>

(approx 1km resolution, better than GTOPO30 DEM data), the user has to download

additionally the related <a href="ftp://ftp.ngdc.noaa.gov/GLOBE_DEM/data/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>.

<h3>Worldclim.org</h3>

To import <a href="http://www.worldclim.org">Worldclim</a> data, the following

line has to be added to each .hdr file:

<div class="code"><pre>

PIXELTYPE SIGNEDINT

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

</em>

<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: 2014-11-01 20:59:34 +0100 (Sat, 01 Nov 2014) $</i>