Geografic-Information-System/lib/proj/projlib.dox

/*! \page projlib GRASS and the PROJ projection library
<!-- doxygenized from "GRASS 5 Programmer's Manual" 
     by M. Neteler 11/2005
  -->

by GRASS Development Team

https://grass.osgeo.org

\section projintro GRASS GIS and the PROJ projection library

GRASS GIS utilizes the PROJ library (<a
href="https://proj.org">https://proj.org</a>) originally
developed by Gerald Evenden/USGS (Cartographic Projection Procedures
for the UNIX Environment -- A User's Manual, Evenden, 1990, Open-file
report 90-284). The PROJ functions are used through wrapper functions
in a GRASS environment.

Internally to the PROJ library, projection may involve transformation to
and from geodetic co-ordinates (latitude and longitude), and numerical
corrections to account for different datums.

This is transparent for the user as input and output parameters are
either read from PROJ_INFO and PROJ_UNITS files (<tt>g.proj</tt>,
<tt>v.proj</tt>, <tt>r.proj</tt>). In addition, a PROJ_EPSG file is
stored. GRASS converts a co-ordinate system representation to WKT
style, the EPSG code is here preferred if available. The TOWGS84 parameter
is scanned from PROJ_INFO file and appended to co-ordinate system definition
imported from EPSG code by GDAL library.

In GRASS the wrapper functions in lib/proj/get_proj.c makes the
preparations to set up the parameter strings and init the info-structures,
while lib/proj/do_proj.c contains the actual projection calls.

Files lib/proj/ellipse.c and lib/proj/datum.c contain functions for
querying GRASS locations and users for ellipsoid and datum information
(some of these functions were included in the GIS library in earlier
versions of GRASS).

File lib/proj/convert.c contains functions for converting GRASS
co-ordinate system descriptions to and from the formats used by other
GIS. Heavy use is made of the OGR library, part of GDAL
(https://gdal.org).

\subsection datum_transformation Datum transformation

GRASS generally supports datum transformation (3 parameters, 7 parameters
and grid).
<p>

Note that datum transformation is handled exclusively by PROJ 6 and later.
In the case that GRASS is compiled with PROJ 5 or older, the datum
management is still done within GRASS GIS. Only in that case,
if a warning appears that a certain datum is not recognised by GRASS and
no parameters found, the datum transformation parameters have to be
added to $GISBASE/etc/proj/datum.table (and also $GISBASE/etc/proj/datumtransform.table
if you have 7-parameter transformation parameters). No need to re-compile
though. When adding to git, currently these files are still in lib/gis/. 
<p>

A list of datum equivalents is included in convert.c for geospatial files that
use a non-standard name for a datum that is already supported in GRASS.
<p>
Hint: use GDAL's "testepsg" to identify the canonical name, e.g.
      testepsg epsg:4674

\subsection Makefile_Example Makefile Example

<p>
The following code demonstrates the Makefile.

\verbatim
MODULE_TOPDIR = ../..

PGM = r.myproj

EXTRA_INC = $(PROJINC)
LIBES     = $(GPROJLIB) $(GISLIB)
DEPENDENCIES= $(GPROJDEP) $(GISDEP)

include $(MODULE_TOPDIR)/include/Make/Module.make

default: cmd
\endverbatim

\section Functions

 - GPJ_ask_datum_params()
 
 - GPJ_get_datum_by_name()

 - GPJ__get_datum_params()

 - GPJ_get_datum_params()
 
 - GPJ_get_datum_transform_by_name()

 - GPJ_get_default_datum_params_by_name()

 - GPJ_get_ellipsoid_by_name()
 
 - GPJ__get_ellipsoid_params()

 - GPJ_get_ellipsoid_params()
 
 - GPJ_get_equivalent_latlong()
 
 - GPJ_grass_to_osr()
 
 - GPJ_grass_to_osr2()

 - GPJ_grass_to_wkt()

 - GPJ_grass_to_wkt2()

 - GPJ_free_datum()

 - GPJ_free_datum_transform()

 - GPJ_free_ellps()
 
 - GPJ_set_csv_loc()
 
 - GPJ_osr_to_grass()

 - GPJ_wkt_to_grass()

 - GPJ_init_transform()

 - GPJ_transform()

 - GPJ_transform_array()
*/