Geografic-Information-System/general/g.proj/g.proj.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.
If compiled without <a href="http://www.gdal.org/ogr/">OGR</a> present, the 
functionality is limited to:
<ul>
<li>Reporting the projection information for the current location, 
either in conventional GRASS (-p flag) or PROJ.4 (-j flag) format</li>
<li>Changing the datum, or reporting and modifying the datum transformation 
parameters, for the current location</li>
</ul>

<p>When compiled with OGR, functionality is increased and allows output of 
the projection information 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://proj.osgeo.org/">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 
<tt>$GISBASE/etc/proj/ogr_csv</tt>. These can be updated if necessary
to support future revisions of the EPSG database.</dd>
</dl>

<p>If datum information is incorrect or missing in the input
co-ordinate system definition (e.g. PROJ.4 descriptions have very limited
support for specifying datum names), a GRASS datum abbreviation can instead be
supplied using the <em>datum</em> parameter. This will override any
datum contained in the input co-ordinate system, and discard
any datum transformation parameters. Enter datum=<em>list</em> to return a
list of all the datums supported by GRASS. Since any
existing datum transformation parameters will have been discarded, the
<em>datumtrans</em> parameter should in general always be used in
conjunction with <em>datum</em>.

<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>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 <strong>not</strong> warn before doing this.

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

<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
<tt>$GISBASE/etc/proj</tt>), <em>g.proj</em> 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 <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. This can be useful to change the datum information
for an existing location.

<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>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>The maximum size of input WKT or PROJ.4 projection descriptions is
limited to 8000 bytes.

<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, but forcing a change to datum transformation parameter set no. 1:<br>

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

<p>List the possible datum transformation parameters for the current location:<br>

<div class="code"><pre>
g.proj -t datumtrans=-1
</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>Create a new location from a PROJ.4 description, explicitly
specifying a datum and using the default datum transformation
parameters:<br>

<div class="code"><pre>
g.proj -c location=spain proj4="+proj=utm +zone=30 +ellps=intl" datum=eur50 datumtrans=0
</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/persjournals/PE-RS-Journals/Grids-Datums.html">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>