r.in.gdal(1)	       Grass User's Manual	     r.in.gdal(1)



NNAAMMEE
       rr..iinn..ggddaall   -  Import  GDAL  supported  raster file into a
       binary raster map layer.
       _(_G_R_A_S_S _R_a_s_t_e_r _D_a_t_a _I_m_p_o_r_t _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..iinn..ggddaall
       rr..iinn..ggddaall hheellpp
       rr..iinn..ggddaall [[--oo]] [[--ee]] iinnppuutt==_n_a_m_e  [bbaanndd==_n_u_m_b_e_r]  oouuttppuutt==_n_a_m_e
       [ttaarrggeett==_n_a_m_e] [TTIITTLLEE=="_p_h_r_a_s_e"] [llooccaattiioonn==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       _r_._i_n_._g_d_a_l  allows a user to create a (binary) GRASS raster
       map layer, or  imagery  group,  from  any  GDAL	supported
       raster  file format, with an optional title.  The imported
       file may also be optionally used to create a new location.

OOPPTTIIOONNSS
   FFllaaggss::
       --oo     Override projection (use locations projection)

       --ee     Extend  the  DEFAULT_WIND  in  PERMANENT	mapset to
	      include the region of the new map layer.	Old reso-
	      lution  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.


   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      Name  of	an existing GDAL supported raster file to
	      be imported.


       bbaanndd==_n_u_m_b_e_r
	      Number of input band to  extract	(default  is  all
	      bands). Number between 1 and number of bands.


       oouuttppuutt==_n_a_m_e
	      Name  to be assigned to resultant binary raster map
	      layer or imagery group.  An imagery group is gener-
	      ated if more than one band is imported.


       ttaarrggeett==_n_a_m_e
	      Name  of	location to read projection info from for
	      GCPs transformation


       TTIITTLLEE== Title  to  be  assigned  to  resultant  raster  map
	      layer(s).


       llooccaattiioonn==_n_a_m_e
	      Name  of	new location to create based on the file,
	      if so desired.



GGDDAALL SSuuppppoorrtteedd FFoorrmmaattss
       Full details on GDAL supported formats are available at:


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



       Selected formats:

       Format Name			  Georeferencing

       Arc/Info Binary Grid				    Yes

       CEOS (Spot for instance) 			    No
       First Generation USGS DOQ			    Yes
       New Labelled USGS DOQ				    Yes
       Military Elevation Data (DTED)			    Yes
       Eosat Fast Format				    No
       ESRI .hdr Labelled				    Yes
       TIFF / GeoTIFF					    Yes
       Erdas Imagine .hfa				    No
       JPEG JFIF					    No
       PCI .aux Labelled				    Yes
       Portable Network Graphics (PNG)			    No
       USGS SDTS DEM					    Yes
       SAR CEOS 					    No

       If GDAL doesn't support the indicated file it will  report
       it  with  a message like ERROR 4: `abc.e00' not recognised
       as a supported file format by GDAL,  or	that  the  format
       wasn't  built  into  the  version  of libgdal.1.1.so being
       used.


       rr..iinn..ggddaall will only operate correctly if the  GDAL  shared
       library	is  installed  on the system and accessable (nor-
       mally via LD_LIBRARY_PATH).  If not, r.in.gdal will report
       Unable to initialize GDAL bridge.  If this occurs it means
       that you either don't  have  GDAL  installed  (ie.   libg-
       dal.1.1.so), it isn't in the LD_LIBRARY_PATH, or it is the
       wrong version.

	r.in.gdal uses a number of strategies to  find	the  GDAL
       shared library.	It first looks in $GISBASE/lib/.  Then it
       looks for $GDAL_HOME and finally  it  searches  without	a
       path  letting  all the standard Unix dlopen() search rules
       apply (which normally includes LD_LIBRARY_PATH).

LLooccaattiioonn CCrreeaattiioonn
       rr..iinn..ggddaall attempts to preserve projection information when
       importing  datasets  if the source format includes projec-
       tion information, and if the GDAL driver supports it.   If
       the  projection	of  the source dataset does not match the
       projection of the current location rr..iinn..ggddaall  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 cur-
       rent  location,	they may pass the --oo flag to override the
       projection check.


       If the user wishes to import the data with the  full  pro-
       jection	definition,  it  is  possible  to  have r.in.gdal
       automatically create a new location based on  the  projec-
       tion  and  extents of the file being read.  This is accom-
       plished by passing the name to be used for the  new  loca-
       tion  via  the llooccaattiioonn 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 oouuttppuutt name into the PERMANENT
       mapset.


       Support for GCPs: In case the image contains GCPs they are
       written to a POINTS file within an imagery group. They can
       directly  be  used for i.rectify. The _t_a_r_g_e_t option allows
       to automatically re-project the GCPs from their	own  pro-
       jection	into  another  projection read from the PROJ_INFO
       file of the location name _t_a_r_g_e_t.

NNOOTTEESS
       I plan to make a variety of improvements to  rr..iinn..ggddaall  in
       the  future  including  support	for  reporting everything
       known about a dataset if the oouuttppuutt parameter is not  set.


       The  rr..iinn..ggddaall comand 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 auto-
	      matically 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 sig-
	      nal data formats) data bands are translated to  two
	      floating	point  cell  layers  (*.real and *.imagi-
	      nary).


	Georeferencing
	      If the dataset has affine  georeferencing  informa-
	      tion,  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 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.


	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 for-
	      mats  (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.



SSEEEE AALLSSOO
       _r_._i_n_._a_s_c_i_i_, _r_._i_n_._a_r_c_, _r_._i_n_._b_i_n_, _r_._n_u_l_l


RREEFFEERREENNCCEESS
       GDAL pages,

       GDAL precompiled library (libgdal-linux-grass.tar.gz, this
       library is required  to	run  r.in.gdal,  store	in  $GIS-
       BASE/lib/)

AAUUTTHHOORR
       Frank Warmerdam (warmerdam@pobox.com).

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_3_/_0_1 _0_0_:_0_8_:_3_1 _$



GRASS 5.0					     r.in.gdal(1)
