Geografic-Information-System/general/g.proj/description.html

<h2>DESCRIPTION</h2>

<P><em>g.proj</em> provides a means of converting a co-ordinate system
description (i.e. projection information) between various formats.
It requires <A HREF="http://www.gdal.org/ogr/">OGR</A> to compile. The basic
functionality of the module is to report the projection information for the
current location, either in conventional GRASS (-p flag) or PROJ.4 (-j flag) 
format.</P>

<P>Projection information may also be output in the Well-Known Text (WKT) 
format popularised
by proprietary GIS. In addition, if one of the parameters <em>georef</em>, 
<em>wkt</em>, <em>proj4</em> or <em>epsg</em> is specified, rather than the 
projection information being read from the current location it is imported 
from an external source as follows:
<dl>
<dt>georef=<em>filename</em></dt>
<dd><em>g.proj</em> attempts to invoke GDAL and OGR in turn to read a
georeferenced file <em>filename</em>. The projection information will be
read from this file. If the file is not georeferenced or cannot be read,
XY (unprojected) will be used.</dd>

<dt>wkt=<em>filename</em> or <em>-</em></dt>
<dd>The file <em>filename</em> should contain a projection description in WKT
format with or without line-breaks (e.g. a '.prj' file). If <em>-</em> is given
for the filename, the WKT description will be read from stdin rather than a
file.</dd>

<dt>proj4=<em>description</em> or <em>-</em></dt>
<dd><em>description</em> should be a projection description in 
<A HREF="http://remotesensing.org/proj/">PROJ.4</a> format, enclosed in
quotation marks if there are any spaces. If <em>-</em> is given for
<em>description</em>, the PROJ.4 description will be read from stdin rather 
than as a directly-supplied command-line parameter.</dd>

<dt>epsg=<em>number</em></dt>
<dd><em>number</em> should correspond to the index number of a valid
co-ordinate system in the <a href="http://www.epsg.org/CurrentDB.html">EPSG 
database</a>. EPSG code support is based upon a local copy of the GDAL CSV 
co-ordinate system and datum information files, stored in the directory 
${GISBASE}/etc/ogr_csv. These can be updated if necessary to support future
revisions of the EPSG database.</dd>
</dl>
</P>

<P>The -p, -j, -w, etc. flags are all functional when importing projection
information from an external source, meaning that <em>g.proj</em> can be
used to convert between representations of the information. It is
<strong>not</strong> required that either the input or output be in GRASS
format.</P>

<P>In addition however, if the -c flag is specified, <em>g.proj</em> will 
create new GRASS projection files (PROJ_INFO, PROJ_UNITS, WIND and 
DEFAULT_WIND) based on the imported information. If the <em>location</em> 
parameter is specified in addition to -c, then a new location will be created. 
Otherwise the projection information files in the current location will be
overwritten. The program will warn before doing this only if command-line
interactive mode (<em>-i</em> flag) is selected.</P>

<P>The final mode of operation of g.proj is to report on the datum
information and datum transformation parameters associated with the
co-ordinate system. The -d flag will report a human-readable summary of
this.</P>

<H2>NOTES</H2>

<P>If the input co-ordinate system contains a datum name but no
transformation parameters, and there is more than one suitable parameter set
available (according to the files datum.table and datumtransform.table in
${GISBASE}/etc), g.proj will check the value of the <em>datumtrans</em>
option and act according to the following:<br>
<strong>-1:</strong> List available parameter sets in a GUI-parsable (but also
human-readable) format and exit.<br>
<strong>0 (default):</strong> Continue without specifying parameters - if 
used when creating a location, other GRASS modules will use the "default" 
(likely non-optimum) parameters for this datum if necessary in the future.<br>
<strong>Any other number less than or equal to the number of parameter sets
available for this datum:</strong> Choose this parameter set and add it to the
co-ordinate system description.<br>
If the module is being used from the command-line through an interactive
terminal, the <em>-i</em> flag can be specified to enable interactive
selection of the parameter set, and the value of <em>datumtrans</em> (if 
specified) is ignored.<br>
If the <em>-t</em> flag is specified, the module will attempt to change the
datum transformation parameters using one of the above two methods 
<strong>even if</strong> a valid parameter set is already specified in the 
input co-ordinate system.</P>

<P>Output is simply based on the input projection information. g.proj does 
<strong>not</strong> attempt to verify that the co-ordinate system thus 
described matches an existing system in use in the world. In particular,
this means there are no EPSG Authority codes in the WKT output.</P>

<P>WKT format shows the false eastings and northings in the projected unit
(e.g. meters, feet) but in PROJ format it should always be given in meters.</P>

<P>The maximum size of input WKT or PROJ.4 projection descriptions is
limited to 8000 bytes.</P>

<H2>EXAMPLES</H2>

Print the projection information for the current location:<br>

<div class="code"><pre>
g.proj -p
</pre></div>

<p>
Create a '.prj' file in ESRI format corresponding to the current location:<br>

<div class="code"><pre>
g.proj -wef > irish_grid.prj
</pre></div>

<p>
Read the projection information from a geotiff file and print it in PROJ.4
format:<br>

<div class="code"><pre>
g.proj -jf georef=ASTER_DEM20020508161837.tif
</pre></div>

<p>
Convert the PROJ.4 projection description contained in a text file to WKT
format:<br>

<div class="code"><pre>
cat proj4.description | g.proj -w proj4=-
</pre></div>

<p>
Create a new location with the co-ordinate system referred to by EPSG code
4326 (Latitude-Longitude/WGS84), without explicitly specifiying datum
transformation parameters:<br>

<div class="code"><pre>
g.proj -c epsg=4326 location=latlong
</pre></div>

<p>
Create a new location with the co-ordinate system referred to by ESRI-EPSG code
900913 (<a href="http://spatialreference.org/ref/user/6/">Google Mercator Projection</a>)<br>

<div class="code"><pre>
g.proj -c epsg=900913 loc=google
</pre></div>

<p>
Create a new location with the co-ordinate system referred to by EPSG code
29900 (Irish Grid), selecting datum transformation parameter set no. 2:<br>

<div class="code"><pre>
g.proj -c epsg=29900 datumtrans=2 location=irish_grid
</pre></div>

<p>
Create a new location with the same co-ordinate system as the current
location:<br>

<div class="code"><pre>
g.proj -c location=newloc
</pre></div>

<p>
Interactively change/update the datum transformation parameters for the
current location:<br>

<div class="code"><pre>
g.proj -itc
</pre></div>

<p>
Create a new location with the co-ordinate system from a WKT definition
stored in a text file:<br>

<div class="code"><pre>
g.proj -c wkt=irish_grid.prj location=irish_grid
</pre></div>

<p>
Reproject external raster map to current GRASS projection (does not always make sense!)
using the GDAL 'gdalwarp' tool. We recommend to use the ERDAS/Img format and not
to use the ESRI style of WKT:<br>
<div class="code"><pre>
# example for 30x30 pixel resolution (enforce with -tr to avoid odd values)
gdalwarp -of HFA -tr 30 30 -t_srs "`g.proj -wf`" aster.img aster_tmerc.img
</pre></div>

<p>
Reproject external vector map to current GRASS projection
using the OGR 'ogr2ogr' tool:<br>
<div class="code"><pre>
ogr2ogr -t_srs "`g.proj -wf`" polbnda_italy_GB_ovest.shp polbnda_italy_LL.shp
</pre></div>


<H2>REFERENCES</H2>

<a href="http://proj.maptools.org">PROJ 4</a>: Projection/datum support library<br>
<a href="http://www.gdal.org">GDAL raster library and toolset</a><br>
<a href="http://www.gdal.org/ogr/">OGR vector library and toolset</a>

<P>
<B>Further reading</B>
<ul>
<li> <a href="http://www.asprs.org/resources/grids/">ASPRS Grids and Datum</a>
<li> <a href="http://www.mapref.org">MapRef - The Collection of Map Projections and Reference Systems for Europe</a>
<li> <a href="http://www.remotesensing.org/geotiff/proj_list/">Projections Transform List</a> (PROJ4)
</ul>

<H2>SEE ALSO</H2>
 
<EM><a href="g.setproj.html">g.setproj</a></EM><BR>
<EM><a href="r.in.gdal.html">r.in.gdal</a></EM><BR>
<EM><a href="v.in.ogr.html">v.in.ogr</a></EM>

<h2>AUTHOR</h2>

Paul Kelly

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