path: root/man/man1/proj4.1

.\" Man page generated from reStructuredText.
.
.TH "PROJ4" "1" "Mar 18, 2018" "5.0.0" "PROJ.4"
.SH NAME
proj4 \- PROJ.4 Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
PROJ is a standard UNIX filter function which converts geographic longitude
and latitude coordinates into cartesian coordinates (and vice versa), and it is
a C API for software developers to include coordinate transformation in their
own software. PROJ is maintained on \fI\%GitHub\fP\&.
.TS
center;
|l|l|.
_
T{
Platform
T}	T{
Test Status and Coverage
T}
_
T{
Travis
T}	T{
\fI\%travis\fP
T}
_
T{
AppVeyor
T}	T{
\fI\%appveyor\fP
T}
_
T{
Coverage
T}	T{
\fI\%coverals\fP
T}
_
.TE
.sp
Full documentation is available as a single PDF at
\fI\%https://raw.githubusercontent.com/OSGeo/proj.4/gh\-pages/proj4.pdf\fP
.SH DOCUMENTATION
.SS Download
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Download\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Release Notes\fP
.IP \(bu 2
\fI\%Current Release\fP
.IP \(bu 2
\fI\%Past Releases\fP
.IP \(bu 2
\fI\%Binaries\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Linux\fP
.IP \(bu 2
\fI\%Docker\fP
.IP \(bu 2
\fI\%Windows\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Release Notes
.INDENT 0.0
.IP \(bu 2
\fI\%NEWS\fP
.UNINDENT
.SS Current Release
.INDENT 0.0
.IP \(bu 2
\fB2018\-03\-01\fP \fI\%proj\-5.0.0.tar.gz\fP (\fI\%md5\fP)
.IP \(bu 2
\fB2018\-03\-01\fP \fI\%proj\-datumgrid\-1.7.zip\fP
.IP \(bu 2
\fB2018\-03\-01\fP \fI\%proj\-datumgrid\-europe\-1.0.zip\fP
.IP \(bu 2
\fB2018\-03\-01\fP \fI\%proj\-datumgrid\-north\-america\-1.0.zip\fP
.IP \(bu 2
\fB2018\-03\-01\fP \fI\%proj\-datumgrid\-oceania\-1.0.zip\fP
.UNINDENT
.SS Past Releases
.INDENT 0.0
.IP \(bu 2
\fB2016\-09\-02\fP \fI\%proj\-4.9.3.tar.gz\fP
.IP \(bu 2
\fB2015\-09\-13\fP \fI\%proj\-4.9.2.tar.gz\fP
.IP \(bu 2
\fB2015\-03\-04\fP \fI\%proj\-4.9.1.tar.gz\fP
.IP \(bu 2
\fB2016\-09\-11\fP \fI\%proj\-datumgrid\-1.6.zip\fP
.UNINDENT
.SS Binaries
.SS Linux
.INDENT 0.0
.IP \(bu 2
\fI\%RedHat RPMs\fP
.IP \(bu 2
\fI\%SUSE\fP
.IP \(bu 2
\fI\%Debian\fP
.IP \(bu 2
\fI\%pkgsrc\fP
.IP \(bu 2
\fI\%Delphi\fP
.UNINDENT
.SS Docker
.sp
A \fI\%Docker\fP image with just PROJ binaries and a full compliment of grid shift
files is available on \fI\%DockerHub\fP:
.SS Windows
.INDENT 0.0
.IP \(bu 2
\fI\%OSGeo4W\fP contains 32\-bit and 64\-bit Windows binaries, including support for many grids\&.
.UNINDENT
.SS Installation
.sp
These pages describe how to install PROJ on your computer without compiling it
yourself. Below are guides for installing on Windows, Linux and Mac OS X. This
is a good place to get started if this is your first time using PROJ. More
advanced users may want to compile the software themselves.
.SS Windows
.sp
The simplest way to install PROJ on Windows is to use the \fI\%OSGeo4W\fP software
distribution. OSGeo4W provides easy access to many popular open source geospatial
software packages. After installation you can use PROJ from the OSGeo4W shell.
To install PROJ do the following:
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you have already installed software via OSGeo4W on your computer it is
likely that PROJ is already installed.
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 1. 4
Download either the \fI\%32 bit\fP or \fI\%64 bit\fP installer.
.IP 2. 4
Run the OSGeo4W setup program.
.IP 3. 4
Select “Advanced Install” and press Next.
.IP 4. 4
Select “Install from Internet” and press Next.
.IP 5. 4
Select a installation directory. The default suggestion is fine in most cases. Press Next.
.IP 6. 4
Select “Local packacke directory”. The suggestions is fine in most cases. Press Next.
.IP 7. 4
Select “Direct connection” and press Next.
.IP 8. 4
Choose the download.osgeo.org and press Next.
.IP 9. 4
Find “proj” under “Commandline_Utilities” and click the package in the “New” column until the version you want to install appears.
.IP 10. 4
Press next to install PROJ.
.UNINDENT
.sp
You should now have a “OSGeo” menu in your start menu. Within that menu you can
find the “OSGeo4W Shell” where you have access to all the OSGeo4W applications,
including proj.
.sp
For those who are more inclined to the command line, steps 2–10 above can be
accomplished by executing the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C:\etemp\eosgeo4w\-setup\-x86\-64.exe \-q \-k \-r \-A \-s http://download.osgeo.org/osgeo4w/ \-a x86_64 \-P proj
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Linux
.sp
How to install PROJ on Linux depends on which distribution you are using. Below
is a few examples for some of the more common Linux distributions:
.SS Debian
.sp
On Debian and similar systems (e.g. Ubuntu) the APT package manager is used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo apt\-get install proj\-bin
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Red Hat
.sp
On Red Hat based system packages are installed with yum:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
sudo yum install proj
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mac OS X
.sp
On OS X PROJ can be installed via the Homebrew package manager:
.INDENT 0.0
.INDENT 3.5
brew install proj
.UNINDENT
.UNINDENT
.SS Using PROJ
.sp
The main purpose of PROJ is to transform coordinates from one coordinate
reference system to another. This can be achieved either with the included
command line applications or the C API that is a part of the software package.
.SS Quick start
.sp
Coordinate transformations are defined by, what in PROJ terminology is
known as, “proj\-strings”. A proj\-string describes any transformation regardless of
how simple or complicated it might be. The simplest case is projection of geodetic
coordinates. This section focuses on the simpler cases and introduces the basic
anatomy of the proj\-string. The complex cases are discussed in
transformation\&.
.sp
A proj\-strings holds the parameters of a given coordinate transformation, e.g.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=merc +lat_ts=56.5 +ellps=GRS80
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
I.e. a proj\-string consists of a projection specifier, \fB+proj\fP, a number of
parameters that applies to the projection and, if needed, a description of a
datum shift. In the example above geodetic coordinates are transformed to
projected space with the Mercator projection with
the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every
projection in PROJ is identified by a shorthand such as \fBmerc\fP in the above
example.
.sp
By using the  above projection definition as parameters for the command line
utility \fBproj\fP we can convert the geodetic coordinates to projected space:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ proj +proj=merc +lat_ts=56.5 +ellps=GRS80
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If called as above \fBproj\fP will be in interactive mode, letting you type the
input data manually and getting a response presented on screen. \fBproj\fP
works as any UNIX filter though, which means that you can also pipe data to
the utility, for instance by using the \fBecho\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 55.2 12.2 |\ proj +proj=merc +lat_ts=56.5 +ellps=GRS80
3399483.80      752085.60
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
PROJ also comes bundled with the \fBcs2cs\fP utility which is used to transform
from one coordinate reference system to another. Say we want to convert
the above Mercator coordinates to UTM, we can do that with \fBcs2cs\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32
6103992.36      1924052.47 0.00
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Notice the \fB+to\fP parameter that separates the source and destination
projection definitions.
.sp
If you happen to know the EPSG identifiers for the two coordinates reference
systems you are transforming between you can use those with \fBcs2cs\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832
231950.54      1920310.71 0.00
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In the above example we transform geodetic coordinates in the WGS84 reference
frame to UTM zone 32N coordinates in the ETRS89 reference frame.
UTM coordinates
.SS Cartographic projection
.sp
The foundation of PROJ is the large number of
projections available in the library. This section
is devoted to the generic parameters that can be used on any projection in the
PROJ library.
.sp
Below is a list of PROJ parameters which can be applied to most coordinate
system definitions. This table does not attempt to describe the parameters
particular to particular projection types. These can be found on the pages
documenting the individual projections\&.
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Parameter
T}	T{
Description
T}
_
T{
+a
T}	T{
Semimajor radius of the ellipsoid axis
T}
_
T{
+axis
T}	T{
Axis orientation
T}
_
T{
+b
T}	T{
Semiminor radius of the ellipsoid axis
T}
_
T{
+ellps
T}	T{
Ellipsoid name (see \fBproj \-le\fP)
T}
_
T{
+k
T}	T{
Scaling factor (deprecated)
T}
_
T{
+k_0
T}	T{
Scaling factor
T}
_
T{
+lat_0
T}	T{
Latitude of origin
T}
_
T{
+lon_0
T}	T{
Central meridian
T}
_
T{
+lon_wrap
T}	T{
Center longitude to use for wrapping (see below)
T}
_
T{
+no_defs
T}	T{
Don’t use the /usr/share/proj/proj_def.dat defaults file
T}
_
T{
+over
T}	T{
Allow longitude output outside \-180 to 180 range, disables
wrapping (see below)
T}
_
T{
+pm
T}	T{
Alternate prime meridian (typically a city name, see below)
T}
_
T{
+proj
T}	T{
Projection name (see \fBproj \-l\fP)
T}
_
T{
+units
T}	T{
meters, US survey feet, etc.
T}
_
T{
+vunits
T}	T{
vertical units.
T}
_
T{
+x_0
T}	T{
False easting
T}
_
T{
+y_0
T}	T{
False northing
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
In the sections below most of the parameters are explained in details.
.SS Units
.sp
Horizontal units can be specified using the \fB+units\fP keyword with a symbolic
name for a unit (ie. \fBus\-ft\fP).  Alternatively the translation to meters can be
specified with the \fB+to_meter\fP keyword (ie. 0.304800609601219 for US feet).  The
\fB\-lu\fP argument to \fBcs2cs\fP or \fBproj\fP can be used to list symbolic unit names.
The default unit for projected coordinates is the meter.
A few special projections deviate from this behaviour, most notably the
latlong pseudo\-projection that returns degrees.
.sp
Vertical (Z) units can be specified using the \fB+vunits\fP keyword with a
symbolic name for a unit (ie. \fBus\-ft\fP).  Alternatively the translation to
meters can be specified with the \fB+vto_meter\fP keyword (ie. 0.304800609601219
for US feet).  The \fB\-lu\fP argument to \fBcs2cs\fP or \fBproj\fP can be used to list
symbolic unit names.  If no vertical units are specified, the vertical units will
default to be the same as the horizontal coordinates.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBproj\fP do not handle vertical units at all and hence the \fB+vto_meter\fP
argument will be ignored.
.UNINDENT
.UNINDENT
.sp
Scaling of output units can be done by applying the \fB+k_0\fP argument. The
returned coordinates are scaled by the value assigned with the \fB+k_0\fP
parameter.
.SS False Easting/Northing
.sp
Virtually all coordinate systems allow for the presence of a false easting
(\fB+x_0\fP) and northing (\fB+y_0\fP).  Note that these values are always expressed in
meters even if the coordinate system is some other units.  Some coordinate
systems (such as UTM) have implicit false easting and northing values.
.SS Longitude Wrapping
.sp
By default PROJ wraps output longitudes in the range \-180 to 180.  The \fB+over\fP
switch can be used to disable the default wrapping which is done at a low level
in \fBpj_inv()\fP\&.  This is particularly useful with projections like the
equidistant cylindrical
where it would be desirable for X values past \-20000000 (roughly) to continue
past \-180 instead of wrapping to +180.
.sp
The \fB+lon_wrap\fP option can be used to provide an alternative means of doing
longitude wrapping within \fBpj_transform()\fP\&.  The argument to this option is a
center longitude.  So \fB+lon_wrap=180\fP means wrap longitudes in the range 0 to
360.  Note that \fB+over\fP does \fBnot\fP disable \fB+lon_wrap\fP\&.
.SS Prime Meridian
.sp
A prime meridian may be declared indicating the offset between the prime
meridian of the declared coordinate system and that of greenwich.  A prime
meridian is declared using the “pm” parameter, and may be assigned a symbolic
name, or the longitude of the alternative prime meridian relative to greenwich.
.sp
Currently prime meridian declarations are only utilized by the
\fBpj_transform()\fP API call, not the \fBpj_inv()\fP and \fBpj_fwd()\fP calls.
Consequently the user utility \fBcs2cs\fP does honour prime meridians but the
\fBproj\fP user utility ignores them.
.sp
The following predeclared prime meridian names are supported.  These can be
listed using with \fBcs2cs \-lm\fP\&.
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Meridian
T}	T{
Longitude
T}
_
T{
greenwich
T}	T{
0dE
T}
_
T{
lisbon
T}	T{
9d07‘54.862”W
T}
_
T{
paris
T}	T{
2d20‘14.025”E
T}
_
T{
bogota
T}	T{
74d04‘51.3”E
T}
_
T{
madrid
T}	T{
3d41‘16.48”W
T}
_
T{
rome
T}	T{
12d27‘8.4”E
T}
_
T{
bern
T}	T{
7d26‘22.5”E
T}
_
T{
jakarta
T}	T{
106d48‘27.79”E
T}
_
T{
ferro
T}	T{
17d40’W
T}
_
T{
brussels
T}	T{
4d22‘4.71”E
T}
_
T{
stockholm
T}	T{
18d3‘29.8”E
T}
_
T{
athens
T}	T{
23d42‘58.815”E
T}
_
T{
oslo
T}	T{
10d43‘22.5”E
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
Example of use.  The location \fBlong=0\fP, \fBlat=0\fP in the greenwich based lat/long
coordinates is translated to lat/long coordinates with Madrid as the prime
meridian.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid
0 0                           <i>(input)</i>
3d41\(aq16.48"E    0dN 0.000     <i>(output)</i>
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Axis orientation
.sp
Starting in PROJ 4.8.0, the +axis argument can be used to control the axis
orientation of the coordinate system.  The default orientation is “easting,
northing, up” but directions can be flipped, or axes flipped using combinations
of the axes in the +axis switch.  The values are:
.INDENT 0.0
.IP \(bu 2
“e” \- Easting
.IP \(bu 2
“w” \- Westing
.IP \(bu 2
“n” \- Northing
.IP \(bu 2
“s” \- Southing
.IP \(bu 2
“u” \- Up
.IP \(bu 2
“d” \- Down
.UNINDENT
.sp
They can be combined in +axis in forms like:
.INDENT 0.0
.IP \(bu 2
\fB+axis=enu\fP \- the default easting, northing, elevation.
.IP \(bu 2
\fB+axis=neu\fP \- northing, easting, up \- useful for “lat/long” geographic
coordinates, or south orientated transverse mercator.
.IP \(bu 2
\fB+axis=wnu\fP \- westing, northing, up \- some planetary coordinate systems
have “west positive” coordinate systems
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fB+axis\fP argument does not work with the \fBproj\fP command line
utility.
.UNINDENT
.UNINDENT
.SS Geodetic transformation
.sp
PROJ can do everything from the most simple projection to very complex
transformations across many reference frames. While originally developed as a
tool for cartographic projections, PROJ has over time evolved into a powerful
generic coordinate transformation engine that makes it possible to do both
large scale cartographic projections as well as coordinate transformation at a
geodetic high precision level. This chapter delves into the details of how
geodetic transformations of varying complexity can be performed.
.sp
In PROJ, two frameworks for geodetic transformations exists, the \fIcs2cs\fP
framework and the \fItransformation pipelines\fP framework. The first is the original,
and limited, framework for doing geodetic transforms in PROJ The latter is a
newer addition that aims to be a more complete transformation framework. Both are
described in the sections below. Large portions of the text are based on
[EversKnudsen2017]\&.
.sp
Before describing the details of the two frameworks, let us first remark that
most cases of geodetic transformations can be expressed as a series of elementary
operations, the output of one operation being the input of the next. E.g. when
going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the
simplest case, go through 5 steps:
.INDENT 0.0
.IP 1. 3
Back\-project the UTM coordinates to geographic coordinates
.IP 2. 3
Convert the geographic coordinates to 3D cartesian geocentric coordinates
.IP 3. 3
Apply a Helmert transformation from ED50 to ETRS89
.IP 4. 3
Convert back from cartesian to geographic coordinates
.IP 5. 3
Finally project the geographic coordinates to UTM zone 32 planar coordinates.
.UNINDENT
.SS Transformation pipelines
.sp
The homology between the above steps and a Unix shell style pipeline is evident.
It is there the main architectural inspiration behind the transformation pipeline
framework. The pipeline framework is realized by utilizing a special “projection”,
that takes as its user supplied arguments, a series of elementary operations,
which it strings together in order to implement the full transformation needed.
Additionally, a number of elementary geodetic operations, including Helmert
transformations, general high order polynomial shifts and the Molodensky
transformation are available as part of the pipeline framework.
In anticipation of upcoming support for full time\-varying transformations, we
also introduce a 4D spatiotemporal data type, and a programming interface
(API) for handling this.
.sp
The Molodensky transformation converts directly from geodetic coordinates
in one datum, to geodetic coordinates in another datum, while the (typically more
accurate) Helmert transformation converts from 3D cartesian to 3D cartesian
coordinates. So when using the Helmert transformation one typically needs to do an
initial conversion from geodetic to cartesian coordinates, and a final conversion
the other way round, to arrive at the desired result. Fortunately, this three\-step
compound transformation has the attractive characteristic that each step depends
only on the output of the immediately preceding step. Hence, we can build a
geodetic\-to\-geodetic Helmert transformation by tying together the outputs and inputs
of 3 steps (geodetic\-to\-cartesian → Helmert → cartesian\-to\-geodetic), pipeline style.
The pipeline driver, makes this kind of chained transformations possible.
The implementation is compact, consisting of just one pseudo\-projection, called
\fBpipeline\fP, which takes as its arguments strings of elementary projections
(note: “projection” is the, slightly misleading, PROJ term used for any kind of
transformation).
The pipeline pseudo projection is supplemented by a number of elementary
transformations, all in all providing a framework for building high accuracy
solutions for a wide spectrum of geodetic tasks.
.sp
As a first example, let us take a look at the iconic
\fIgeodetic → Cartesian → Helmert → geodetic\fP case (steps 2 to 4 in the example in
the introduction). In PROJ it can be implemented as
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=pipeline
step proj=cart ellps=intl
step proj=helmert
     x=\-81.0703  y=\-89.3603  z=\-115.7526
    rx=\-0.48488 ry=\-0.02436 rz=\-0.41321  s=\-0.540645
step proj=cart inv ellps=GRS80
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The pipeline can be expanded at both ends to accommodate whatever coordinate type
is needed for input and output: In the example below, we transform from the
deprecated Danish System 45, a 2D system with some tension in the original defining
network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial
transformation (the init=./s45b… step, s45b.pol is a file containing the
polynomial coefficients), taking the S45 coordinates to a technical coordinate
system (TC32), defined to represent “UTM zone 32 coordinates, as they would look if
the Helmert transformation between ED50 and ETRS89 was perfect”. The TC32
coordinates are then converted back to geodetic(ED50) coordinates, using an
inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89),
using the relevant Helmert transformation, and back to geodetic(ETRS89), before
finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step
pipeline, implementing a transformation with centimeter level accuracy from a
deprecated system with decimeter level tensions.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=pipeline
step init=./s45b.pol:s45b_tc32
step proj=utm inv ellps=intl zone=32
step proj=cart ellps=intl
step proj=helmert
      x=\-81.0703  y=\-89.3603  z=\-115.7526
     rx=\-0.48488 ry=\-0.02436 rz=\-0.41321 s=\-0.540645
step proj=cart inv ellps=GRS80
step proj=utm ellps=GRS80 zone=33
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With the pipeline framework spatiotemporal transformation is possible. This is
possible by leveraging the time dimension in PROJ that enables 4D coordinates
(three spatial components and one temporal component) to be passed through a
transformation pipeline. In the example below a transformation from ITRF93 to
ITRF2000 is defined. The temporal component is given as GPS weeks in the input
data, but the 14\-parameter Helmert transform expects temporal units in decimalyears.
Hence the first step in the pipeline is the unitconvert pseudo\-projection that makes
sure the correct units are passed along to the Helmert transform.
Most parameters of the Helmert transform are taken from [AltamimiEtAl2002],
except the epoch which is the epoch of the transformation. The default setting is to
use “coordinate frame” convention of the Helmert transform, but “position vector”
convention can also be used. The last step in the pipeline is converting the
coordinate timestamps back to GPS weeks.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=pipeline
step proj=unitconvert t_in=gps_week t_out=decimalyear
step proj=helmert
     x=0.0127 y=0.0065 z=\-0.0209 s=0.00195
     rx=0.00039 ry=\-0.00080 rz=0.00114
     dx=\-0.0029 dy=\-0.0002 dz=\-0.0006 ds=0.00001
     drx=0.00011 dry=0.00019 drz=\-0.00007
     epoch=1988.0
step proj=unitconvert t_in=decimalyear t_out=gps_week
.ft P
.fi
.UNINDENT
.UNINDENT
.SS cs2cs paradigm
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Parameter
T}	T{
Description
T}
_
T{
+datum
T}	T{
Datum name (see \fBproj \-ld\fP)
T}
_
T{
+geoidgrids
T}	T{
Filename of GTX grid file to use for vertical datum transforms
T}
_
T{
+nadgrids
T}	T{
Filename of NTv2 grid file to use for datum transforms
T}
_
T{
+towgs84
T}	T{
3 or 7 term datum transform parameters
T}
_
T{
+to_meter
T}	T{
Multiplier to convert map units to 1.0m
T}
_
T{
+vto_meter
T}	T{
Vertical conversion to meters
T}
_
.TE
.UNINDENT
.UNINDENT
.sp
The \fIcs2cs\fP framework delivers a subset of the geodetic transformations available
with the \fIpipeline\fP framework. Coordinate transformations done in this framework
are transformed in a two\-step process with WGS84 as a pivot datum That is, the
input coordinates are transformed to WGS84 geodetic coordinates and then transformed
from WGS84 coordinates to the specified output coordinate reference system, by
utilizing either the Helmert transform, datum shift grids or a combination of both.
Datum shifts can be described in a proj\-string with the parameters \fB+towgs84\fP,
\fB+nadgrids\fP and \fB+geoidgrids\fP\&.
An inverse transform exists for all three and is applied if
specified in the input proj\-string. The most common is \fB+towgs84\fP, which is used to
define a 3\- or 7\-parameter Helmert shift from the input reference frame to WGS84.
Exactly which realization of WGS84 is not specified, hence a fair amount of
uncertainty is introduced in this step of the transformation. With the +nadgrids
parameter a non\-linear planar correction derived from interpolation in a
correction grid can be applied. Originally this was implemented as a means to
transform coordinates between the North American datums NAD27 and NAD83, but
corrections can be applied for any datum for which a correction grid exists. The
inverse transform for the horizontal grid shift is “dumb”, in the sense that the
correction grid is applied verbatim without taking into account that the inverse
operation is non\-linear. Similar to the horizontal grid correction, \fB+geoidgrids\fP
can be used to perform grid corrections in the vertical component.
Both grid correction methods allow inclusion of more than one grid in the same
transformation
.sp
In contrast to the \fItransformation pipeline\fP framework, transformations with the
\fIcs2cs\fP framework are expressed as two separate proj\-strings. One proj\-string \fIto\fP
WGS84 and one \fIfrom\fP WGS84. Together they form the mapping from the source
coordinate reference system to the destination coordinate reference system.
When used with the \fBcs2cs\fP the source and destination CRS’s are separated by the
special \fB+to\fP parameter.
.sp
The following example demonstrates converting from the Greek GGRS87 datum
to WGS84 with the \fB+towgs84\fP parameter.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +ellps=GRS80 +towgs84=\-199.87,74.79,246.62
    +to +proj=latlong +datum=WGS84
20 35
20d0\(aq5.467"E    35d0\(aq9.575"N 8.570
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The EPSG database provides this example for transforming from WGS72 to WGS84
using an approximated 7 parameter transformation.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \e
    +to +proj=latlong +datum=WGS84
4 55
4d0\(aq0.554"E     55d0\(aq0.09"N 3.223
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Grid Based Datum Adjustments
.sp
In many places (notably North America and Australia) national geodetic
organizations provide grid shift files for converting between different datums,
such as NAD27 to NAD83.  These grid shift files include a shift to be applied
at each grid location. Actually grid shifts are normally computed based on an
interpolation between the containing four grid points.
.sp
PROJ supports use of grid files for shifting between various reference frames.
The grid shift table formats are ctable (the binary format produced by the PROJ
\fBnad2bin\fP program), NTv1 (the old Canadian format), and NTv2 (\fB\&.gsb\fP \- the new
Canadian and Australian format).
.sp
The text in this section is based on the \fIcs2cs\fP framework. Gridshifting is off
course also possible with the \fIpipeline\fP framework. The major difference between the
two is that the \fIcs2cs\fP framework is limited to grid mappings to WGS84, whereas with
\fItransformation pipelines\fP it is possible to perform grid shifts between any two
reference frames, as long as a grid exists.
.sp
Use of grid shifts with \fBcs2cs\fP is specified using the \fB+nadgrids\fP
keyword in a coordinate system definition. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
% cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \e
    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
\-111 50
EOF
111d0\(aq2.952"W   50d0\(aq0.111"N 0.000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this case the \fB/usr/local/share/proj/ntv1_can.dat\fP grid shift file was
loaded, and used to get a grid shift value for the selected point.
.sp
It is possible to list multiple grid shift files, in which case each will be
tried in turn till one is found that contains the point being transformed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +ellps=clrk66 \e
          +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \e
    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
\-111 44
EOF
111d0\(aq2.788"W   43d59\(aq59.725"N 0.000
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Skipping Missing Grids
.sp
The special prefix \fB@\fP may be prefixed to a grid to make it optional.  If it
not found, the search will continue to the next grid.  Normally any grid not
found will cause an error.  For instance, the following would use the
\fBntv2_0.gsb\fP file if available (see nonfreegrids), otherwise it would
fallback to using the \fBntv1_can.dat\fP file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \e
    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
\-111 50
EOF
111d0\(aq3.006"W   50d0\(aq0.103"N 0.000
.ft P
.fi
.UNINDENT
.UNINDENT
.SS The null Grid
.sp
A special \fBnull\fP grid shift file is shift with releases after 4.4.6 (not
inclusive).  This file provides a zero shift for the whole world.  It may be
listed at the end of a nadgrids file list if you want a zero shift to be
applied to points outside the valid region of all the other grids.  Normally if
no grid is found that contains the point to be transformed an error will occur.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \e
    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
\-111 45
EOF
111d0\(aq3.006"W   50d0\(aq0.103"N 0.000

cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \e
    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
\-111 44
\-111 55
EOF
111d0\(aq2.788"W   43d59\(aq59.725"N 0.000
111dW   55dN 0.000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For more information see the chapter on transformation_grids\&.
.SS Caveats
.INDENT 0.0
.IP \(bu 2
Where grids overlap (such as conus and ntv1_can.dat for instance) the first
found for a point will be used regardless of whether it is appropriate or
not.  So, for instance, \fB+nadgrids=ntv1_can.dat\fP,conus would result in
the Canadian data being used for some areas in the northern United States
even though the conus data is the approved data to use for the area.
Careful selection of files and file order is necessary.  In some cases
border spanning datasets may need to be pre\-segmented into Canadian and
American points so they can be properly grid shifted
.IP \(bu 2
There are additional grids for shifting between NAD83 and various HPGN
versions of the NAD83 datum.  Use of these haven’t been tried recently so
you may encounter problems.  The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla
are examples of high precision grid shifts.  Take care!
.IP \(bu 2
Additional detail on the grid shift being applied can be found by setting
the PROJ_DEBUG environment variable to a value.  This will result in output
to stderr on what grid is used to shift points, the bounds of the various
grids loaded and so forth
.IP \(bu 2
The \fIcs2cs\fP framework always assumes that grids contain a shift \fBto\fP  NAD83 (essentially
WGS84). Other types of grids can be used with the \fIpipeline\fP framework.
.UNINDENT
.SS Environment variables
.sp
PROJ can be controlled by setting environment variables. Most users will
have a use for the \fI\%PROJ_LIB\fP\&.
.sp
On UNIX systems environment variables can be set for a shell\-session with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export VAR="some variable"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or it can be set for just one command line call:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ VAR="some variable" ./cmd
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Environment variables on UNIX are usually removed with the \fBunset\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ unset VAR
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On windows systems environment variables can be set in the command line with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
> set VAR="some variable"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB\(gaVAR\fP will be available for the entire session, unless it is unset. This is
done by setting the variable with no content:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
> set VAR=
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PROJ_LIB
The location of PROJ resource files\&.
It is only possible to specify a single library in \fI\%PROJ_LIB\fP; e.g. it
does not behave like PATH. PROJ is hardcoded to look for resource files
in other locations as well, amongst those are the users home directory,
\fB/usr/share/proj\fP and the current folder.
.UNINDENT
.INDENT 0.0
.TP
.B PROJ_DEBUG
Set the debug level of PROJ. The default debug level is zero, which results
in no debug output when using PROJ. A number from 1\-3, whit 3 being the most
verbose setting.
.UNINDENT
.SS Applications
.sp
Bundled with PROJ comes a set of small command line utilities. The \fBproj\fP
program is limited to converting between geographic and projection coordinates
within one datum. The \fBcs2cs\fP program operates similarly, but allows
translation between any pair of definable coordinate systems, including support
for basic datum translation. The \fBgeod\fP program provides the ability to do
geodesic (great circle) computations. \fBgie\fP is the program used for
regression tests in PROJ.
.SS proj
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
\fBproj\fP [ \fB\-bceEfiIlmorsStTvVwW\fP ] [ args ] ] [ \fI+args\fP ] file[s]
.sp
\fBinvproj\fP [ \fB\-bceEfiIlmorsStTwW\fP ] [ args ] ] [ \fI+args\fP ] file[s]
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBproj\fP and \fBinvproj\fP perform respective forward  and inverse
transformation  of cartographic data to or from cartesian data  with  a  wide
range  of selectable projection functions.
.sp
\fBinvproj\fP may not be available on all  platforms;  in  this  case
use \fI\%proj \-I\fP instead.
.sp
The  following  control parameters can appear in any order
.INDENT 0.0
.TP
.B \-b
Special option for binary coordinate data input and output through standard
input and standard output. Data is assumed to be in system type double
floating point words. This option is to be used when proj is a son process
and allows bypassing formatting operations.
.UNINDENT
.INDENT 0.0
.TP
.B \-i
Selects binary input only (see \fI\%\-b\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \-I
alternate method to specify inverse projection. Redundant when used with
invproj.
.UNINDENT
.INDENT 0.0
.TP
.B \-o
Selects binary output only (see \fI\%\-b\fP).
.UNINDENT
.INDENT 0.0
.TP
.B \-t<a>
\fIa\fP specifies a character employed as the first character to denote a
control line to be passed through without  processing. This  option
applicable to ascii input only. (# is the default value).
.UNINDENT
.INDENT 0.0
.TP
.B \-e <string>
String is an arbitrary string to be output if an error is detected during
data transformations. The default value is: \fIt\fP\&. Note that if the
\fI\%\-b\fP, \fI\%\-i\fP or \fI\%\-o\fP options are employed, an error
is returned as HUGE_VAL value for both return values.
.UNINDENT
.INDENT 0.0
.TP
.B \-E
causes the input coordinates to be copied to the output line prior to
printing the converted values.
.UNINDENT
.INDENT 0.0
.TP
.B \-l<[=id]>
List projection identifiers that can be selected with \fI+proj\fP\&. \fBproj \-l=id\fP
gives expanded description of projection id, e.g. \fBproj \-l=merc\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-lp
List of all projection id that can be used with the \fI+proj\fP parameter.
Equivalent to \fBproj \-l\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-lP
Expanded description of all projections that can be used with the \fI+proj\fP
parameter.
.UNINDENT
.INDENT 0.0
.TP
.B \-le
List of all ellipsoids that can be selected with the \fI+ellps\fP parameters.
.UNINDENT
.INDENT 0.0
.TP
.B \-lu
List of all distance units that can be selected with the \fI+units\fP parameter.
.UNINDENT
.INDENT 0.0
.TP
.B \-ld
List of datums that can be selected with the \fI+datum\fP parameter.
.UNINDENT
.INDENT 0.0
.TP
.B \-r
This options reverses the order of the expected input from
longitude\-latitude or x\-y to latitude\-longitude or y\-x.
.UNINDENT
.INDENT 0.0
.TP
.B \-s
This options reverses the order of the output from x\-y or longitude\-latitude
to y\-x or latitude\-longitude.
.UNINDENT
.INDENT 0.0
.TP
.B \-S
Causes estimation of meridional and parallel scale factors, area scale
factor and angular distortion, and maximum and minimum scale factors to be
listed between <> for each input point. For conformal projections meridional
and parallel scales factors will be equal and angular distortion zero. Equal
area projections will have an area factor of 1.
.UNINDENT
.INDENT 0.0
.TP
.B \-m <mult>
The cartesian data may be scaled by the mult parameter. When processing data
in a forward projection mode the cartesian output values are multiplied by
mult otherwise the input cartesian values are divided by mult before inverse
projection.  If the first two characters of mult are 1/ or 1: then the
reciprocal value of mult is employed.
.UNINDENT
.INDENT 0.0
.TP
.B \-f <format>
Format is a printf format string to control the form of the output values.
For inverse projections, the output will be in degrees when this option is
employed.  The  default format is “%.2f” for forward projection and DMS for
inverse.
.UNINDENT
.INDENT 0.0
.TP
.B \-[w|W]<n>
N is the number of significant fractional digits to employ for seconds
output (when the  option  is  not  specified, \fB\-w3\fP is assumed). When \fB\-W\fP
is employed the fields will be constant width and  with  leading zeroes.
.UNINDENT
.INDENT 0.0
.TP
.B \-v
causes a listing of cartographic control parameters tested for and used by
the program to be printed prior to input data. Should not be used with the
\fI\%\-T\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-V
This option causes an expanded annotated listing of the characteristics of
the projected point. \fI\%\-v\fP is implied with this option.
.UNINDENT
.INDENT 0.0
.TP
.B \-T <ulow,uhi,vlow,vhi,res[,umax,vmax]>
This option creates a set of bivariate Chebyshev polynomial coefficients
that approximate the selected  cartographic projection on stdout. The values
low and hi denote the range of the input where the u or v prefixes apply to
respective longitude\-x or latitude\-y depending upon whether a forward or
inverse projection is selected. Res is an integer number specifying the
power of 10 precision of the approximation. For example, a res of \-3
specifies an approximation with an accuracy better than .001. Umax, and vmax
specify maximum degree of the polynomials (default: 15).
.UNINDENT
.sp
The \fI+args\fP run\-line arguments are associated with cartographic parameters.
Additional projection control parameters may  be contained  in  two  auxiliary
control files: the first  is   optionally   referenced   with   the
\fI+init=file:id\fP and the second is always processed after the name of the
projection has been established from either the run\-line or the contents of
+init  file.   The   environment   parameter \fBPROJ_LIB\fP establishes the
default directory for a file reference without an absolute  path.   This is
also  used  for  supporting files like datum shift files.
.sp
One or more files (processed in  left  to  right order)  specify  the source of
data to be transformed.  A \fB\-\fP will specify the location  of  processing standard
input.  If no files are specified, the input is assumed  to  be  from  stdin.
For ASCII input data the two data values must be in the first two white  space
separated  fields and  when  both  input  and output are ASCII all trailing
portions of the input line are appended to the output line.
.sp
Input  geographic  data (longitude and latitude) must be in DMS format and input
cartesian  data must  be  in units consistent with the ellipsoid major axis or
sphere radius units.  Output geographic  coordinates  will  be in DMS (if the
\fB\-w\fP switch is not employed) and  precise  to  0.001” with  trailing, zero\-valued
minute\-second fields deleted.
.SS Example
.sp
The following script
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=utm  +lon_0=112w  +ellps=clrk66
\-r <<EOF
45d15\(aq33.1"   111.5W
45d15.551666667N   \-111d30
+45.25919444444    111d30\(aq000w
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will perform UTM forward projection with a standard UTM  central  meridian
nearest  longitude 112W.  The geographic values of this example are equivalent
and  meant  as  examples  of  various forms  of  DMS  input.  The x\-y output
data will appear as three lines of:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
460769.27     5011648.45
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Other programs
.sp
The \fBproj\fP program is limited to converting between geographic and
projected coordinates within one datum.
.sp
The \fBcs2cs\fP program operates similarly, but allows translation
between any paor of definable coordinate reference systems, including
support for datum translation.
.SS See also
.sp
\fBcs2cs(1)\fP, \fBcct(1)\fP, \fBgeod(1)\fP, \fBgie(1)\fP
.SS Bugs
.sp
A list of know bugs can be found at \fI\%http://github.com/OSGeo/proj.4/issues\fP
where new bug reports can be submitted to.
.SS Home page
.sp
\fI\%http://proj4.org/\fP
.SS cct
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
\fBcct\fP [ \fB\-cotvz\fP [ args ] ] \fI+opts[=arg]\fP  file[s]
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBcct\fP a 4D equivalent to the \fBproj\fP projection program,
performs transformation coordinate systems on a set of input points.  The
coordinate system transformation can include  translation  between projected
and geographic coordinates as well as the application of datum shifts.
.sp
The following control parameters can  appear  in any order:
.INDENT 0.0
.TP
.B \-c <x,y,z,t>
Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4.
.UNINDENT
.INDENT 0.0
.TP
.B \-o <output file name>, \-\-output=<output file name>
Specify the name of the output file.
.UNINDENT
.INDENT 0.0
.TP
.B \-t <time>, \-\-time=<time>
Specify a fixed observation time to be used for all input data.
.UNINDENT
.INDENT 0.0
.TP
.B \-z <height>, \-\-height=<height>
Specify a fixed observation height to be used for all input data.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Write non\-essential, but potentially useful, information to stderr.
Repeat for additional information (\fB\-vv\fP, \fB\-vvv\fP, etc.)
.UNINDENT
.sp
The \fI+args\fP arguments are associated with coordinate operation parameters.
Usage varies with operation.
.sp
\fBcct\fP is an acronym meaning \fICoordinate Conversion and Transformation\fP\&.
.sp
The acronym refers to definitions given in the OGC 08\-015r2/ISO\-19111
standard “Geographical Information – Spatial Referencing by Coordinates”,
which defines two different classes of \fIcoordinate operations\fP:
.sp
\fICoordinate Conversions\fP, which are coordinate operations where input
and output datum are identical (e.g. conversion from geographical to
cartesian coordinates) and
.sp
\fICoordinate Transformations\fP, which are coordinate operations where
input and output datums differ (e.g. change of reference frame).
.SS Examples
.INDENT 0.0
.IP 1. 3
The operator specs describe the action to be performed by \fBcct\fP\&. So
the following script
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo 12 55 0 0 | cct +proj=utm +zone=32 +ellps=GRS80
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will transform the input geographic coordinates into UTM zone 32 coordinates.
Hence, the command
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo 12 55 | cct \-z0 \-t0 +proj=utm +zone=32 +ellps=GRS80
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Should give results comparable to the classic proj command
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 2. 3
Convert geographical input to UTM zone 32 on the GRS80 ellipsoid:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cct +proj=utm +ellps=GRS80 +zone=32
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 3. 3
Roundtrip accuracy check for the case above:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cct +proj=pipeline +proj=utm +ellps=GRS80 +zone=32 +step +step +inv
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 4. 3
As (2) but specify input columns for longitude, latitude, height and time:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cct \-c 5,2,1,4  +proj=utm +ellps=GRS80 +zone=32
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 5. 3
As (2) but specify fixed height and time, hence needing only 2 cols in
input:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cct \-t 0 \-z 0  +proj=utm  +ellps=GRS80  +zone=32
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Background
.sp
\fBcct\fP also refers to Carl Christian Tscherning (1942–2014),
professor of Geodesy at the University of Copenhagen, mentor and advisor
for a generation of Danish geodesists, colleague and collaborator for
two generations of global geodesists, Secretary General for the
International Association of Geodesy, IAG (1995–2007), fellow of the
American Geophysical Union (1991), recipient of the IAG Levallois Medal
(2007), the European Geosciences Union Vening Meinesz Medal (2008), and
of numerous other honours.
.sp
\fIcct\fP, or Christian, as he was known to most of us, was recognized for his
good mood, his sharp wit, his tireless work, and his great commitment to
the development of geodesy – both through his scientific contributions,
comprising more than 250 publications, and by his mentoring and teaching
of the next generations of geodesists.
.sp
As Christian was an avid Fortran programmer, and a keen Unix connoisseur,
he would have enjoyed to know that his initials would be used to name a
modest Unix style transformation filter, hinting at the tireless aspect
of his personality, which was certainly one of the reasons he accomplished
so much, and meant so much to so many people.
.sp
Hence, in honour of \fIcct\fP (the geodesist) this is \fBcct\fP (the program).
.SS See also
.sp
\fBproj(1)\fP, \fBcs2cs(1)\fP, \fBgeod(1)\fP, \fBgie(1)\fP
.SS Bugs
.sp
A list of know bugs can be found at \fI\%http://github.com/OSGeo/proj.4/issues\fP
where new bug reports can be submitted to.
.SS Home page
.sp
\fI\%http://proj4.org/\fP
.SS cs2cs
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
\fBcs2cs\fP [ \fB\-eEfIlrstvwW\fP [ args ] ] [ \fI+opts[=arg]\fP ] [ +to [\fI+opts[=arg]\fP] ] file[s]
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBcs2cs\fP performs transformation between the source and destination
cartographic  coordinate  system on a set of input points.  The coordinate
system transformation can include  translation  between projected  and
geographic coordinates as well as the application of datum shifts.
.sp
The following control parameters can  appear  in any order:
.INDENT 0.0
.TP
.B \-I
method to specify inverse translation, convert from \fI+to\fP coordinate system to
the primary coordinate system defined.
.UNINDENT
.INDENT 0.0
.TP
.B \-t<a>
A specifies a character employed as the first character to denote a control
line to  be passed through without processing. This option  applicable  to
ascii  input only. (# is the default value).
.UNINDENT
.INDENT 0.0
.TP
.B \-e <string>
String is an arbitrary string to be output if an error is detected  during
data transformations. The  default value is: \fIt\fP\&. Note that if the \-b, \-i
or \-o options are employed, an error is returned as HUGE_VAL value for both
return values.
.UNINDENT
.INDENT 0.0
.TP
.B \-E
causes the input coordinates to be copied to the output line prior to
printing  the converted values.
.UNINDENT
.INDENT 0.0
.TP
.B \-l<[=id]>
List projection identifiers that can be selected with \fI+proj\fP\&. \fBcs2cs \-l=id\fP
gives expanded description of projection id, e.g. \fBcs2cs \-l=merc\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-lp
List of all projection id that can be used with the \fI+proj\fP parameter.
Equivalent to \fBcs2cs \-l\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-lP
Expanded description of all projections that can be used with the \fI+proj\fP
parameter.
.UNINDENT
.INDENT 0.0
.TP
.B \-le
List of all ellipsoids that can be selected with the \fI+ellps\fP parameters.
.UNINDENT
.INDENT 0.0
.TP
.B \-lu
List of all distance units that can be selected with the \fI+units\fP parameter.
.UNINDENT
.INDENT 0.0
.TP
.B \-ld
List of datums that can be selected with the \fI+datum\fP parameter.
.UNINDENT
.INDENT 0.0
.TP
.B \-r
This options reverses the order of the expected input from
longitude\-latitude or x\-y to latitude\-longitude or y\-x.
.UNINDENT
.INDENT 0.0
.TP
.B \-s
This options reverses the order of the output from x\-y or longitude\-latitude
to y\-x or latitude\-longitude.
.UNINDENT
.INDENT 0.0
.TP
.B \-f <format>
Format is a printf format string to control the form of the output values.
For inverse projections, the output will be in degrees when this option is
employed.  If a format is specified for inverse projection the output data
will be in deci\- mal  degrees. The default format is “%.2f” for forward
projection and DMS for inverse.
.UNINDENT
.INDENT 0.0
.TP
.B \-[w|W]<n>
N is the number of significant fractional digits to employ for seconds
output (when the option is not specified, \-w3 is assumed). When \-W is
employed the fields will be constant width and with leading zeroes.
.UNINDENT
.INDENT 0.0
.TP
.B \-v
causes a listing of cartographic control parameters tested for and used by
the program to be printed prior to input data.
.UNINDENT
.sp
The \fI+args\fP run\-line arguments are associated with cartographic
parameters.
.sp
The \fBcs2cs\fP program requires two coordinate system definitions.  The first (or
primary  is  defined based on all projection parameters not appearing after the
\fI+to\fP argument.  All projection  parameters appearing  after the \fI+to\fP argument
are considered the definition of the second  coordinate system.  If there is no
second coordinate system defined, a geographic coordinate system based on the
datum and ellipsoid of the source coordinate system is assumed.  Note  that  the
source  and destination  coordinate  system can both be projections, both be
geographic, or one of each and may have the same or different datums.
.sp
Additional  projection control parameters may be contained in two auxiliary
control  files:  the first   is   optionally   referenced   with  the
\fI+init=file:id\fP and the second is always processed after the name of the
projection has been established from either the run\-line or the  contents of
\fI+init\fP   file.   The  environment  parameter PROJ_LIB establishes the default
directory for a file  reference  without an absolute path.  This is also used
for  supporting  files  like  datum shift files.
.sp
One  or  more  files (processed in left to right order) specify the source of
data to  be  transformed.  A \fB\-\fP will specify the location of processing standard
input.  If no files are  specified,  the  input  is  assumed to be from stdin.
For input data the two data values  must  be  in the  first  two white space
separated fields and when both input and output are ASCII all  trailing portions
of the input line are appended to the output line.
.sp
Input geographic data (longitude  and  latitude) must  be  in  DMS  or decimal
degrees format and input cartesian data must be in units consistent with  the
ellipsoid major axis or sphere radius units.  Output geographic coordinates will
normally be in DMS format (use \fB\-f %.12f\fP for decimal degrees with 12 decimal
places), while projected (cartesian)   coordinates   will  be  in  linear
(meter, feet) units.
.SS Example
.sp
The following script
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10  +datum=NAD27 \-r
<<EOF 45d15\(aq33.1"   111.5W 45d15.551666667N   \-111d30 +45.25919444444
111d30\(aq000w EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will  transform the input NAD83 geographic coordinates into NAD27 coordinates in
the  UTM  projection  with  zone 10 selected.  The geographic values of this
example are equivalent and  meant as  examples of various forms of DMS input.
The x\-y output data will appear as three lines of:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1402285.99      5076292.42 0.000
.ft P
.fi
.UNINDENT
.UNINDENT
.SS See also
.sp
\fBproj(1)\fP, \fBcct(1)\fP, \fBgeod(1)\fP, \fBgie(1)\fP
.SS Bugs
.sp
A list of know bugs can be found at \fI\%http://github.com/OSGeo/proj.4/issues\fP
where new bug reports can be submitted to.
.SS Home page
.sp
\fI\%http://proj4.org/\fP
.SS geod
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
\fBgeod\fP \fI+ellps=<ellipse>\fP [ \fB\-afFIlptwW\fP [ args ] ] [ \fI+args\fP ] file[s]
.sp
\fBinvgeod\fP \fI+ellps=<ellipse>\fP [ \fB\-afFIlptwW\fP [ args  ]  ]  [ \fI+args\fP  ] file[s]
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBgeod\fP  (direct)  and  \fBinvgeod\fP (inverse) perform geodesic
(Great Circle) computations for determining latitude,  longitude  and back
azimuth  of  a terminus point given a initial point latitude, longitude,
azimuth and distance (direct) or  the  forward and  back azimuths and distance
between an initial and terminus point latitudes and  longitudes  (inverse).
The  results  are accurate  to  round  off for |f| < 1/50, where
f is flattening.
.sp
\fBinvgeod\fP may not be available on all  platforms;  in  this  case
use \fI\%geod \-I\fP instead.
.sp
The following command\-line options can appear in any order:
.INDENT 0.0
.TP
.B \-I
Specifies that the inverse geodesic computation is to be performed. May be
used with execution of geod as an alternative to invgeod execution.
.UNINDENT
.INDENT 0.0
.TP
.B \-a
Latitude and longitudes of the initial and terminal points, forward and
back azimuths and distance are  output.
.UNINDENT
.INDENT 0.0
.TP
.B \-ta
A specifies a character employed as the first character to denote a control
line to be passed through without processing.
.UNINDENT
.INDENT 0.0
.TP
.B \-le
Gives a listing of all the ellipsoids that may be selected with the
\fI+ellps=\fP option.
.UNINDENT
.INDENT 0.0
.TP
.B \-lu
Gives a listing of all the units that  may  be  selected with the \fI+units=\fP
option.
.UNINDENT
.INDENT 0.0
.TP
.B \-f <format>
Format is a printf format string to control the output form of the
geographic coordinate values. The default mode is DMS for geographic
coordinates and “%.3f” for distance.
.UNINDENT
.INDENT 0.0
.TP
.B \-F <format>
Format is a printf format string to control the output form of the distance
value (\fB\-F\fP). The default mode is DMS for geographic coordinates and
“%.3f” for distance.
.UNINDENT
.INDENT 0.0
.TP
.B \-w<n>
N is the number of significant fractional digits to employ for seconds
output (when the option is not specified, \fB\-w3\fP is assumed).
.UNINDENT
.INDENT 0.0
.TP
.B \-W<n>
N is the number of significant fractional digits to employ for seconds
output. When \fB\-W\fP is employed the fields will be constant width
with leading zeroes.
.UNINDENT
.INDENT 0.0
.TP
.B \-p
This option causes the azimuthal values to be output as unsigned DMS
numbers between 0 and 360 degrees. Also note \fI\%\-f\fP\&.
.UNINDENT
.sp
The  \fI+args\fP  command\-line  options  are associated with geodetic
parameters for specifying the ellipsoidal  or  sphere  to  use.
controls.  The options are processed in  left  to  right  order
from  the  command  line.  Reentry of an option is ignored with
the first occurrence assumed to be the desired value.
.sp
See the PROJ documentation for a full list of these parameters and
controls.
.sp
One or more files (processed in left to  right  order)  specify
the  source  of  data  to be transformed.  A \fB\-\fP will specify the
location of processing standard input.  If no files are  specified,
the input is assumed to be from stdin.
.sp
For  direct determinations input data must be in latitude, longitude,
azimuth and distance order and output will be latitude,
longitude  and  back  azimuth of the terminus point.  Latitude,
longitude of the initial and terminus point are input  for  the
inverse  mode  and respective forward and back azimuth from the
initial and terminus points are output along with the  distance
between the points.
.sp
Input  geographic  coordinates  (latitude  and  longitude)  and
azimuthal data must be in decimal degrees  or  DMS  format  and
input distance data must be in units consistent with the ellipsoid
major axis or sphere radius units.  The latitude must  lie
in the range [\-90d,90d].  Output geographic coordinates will be
in DMS (if the \fI\%\-f\fP switch is not employed) to 0.001” with trailing,
zero\-valued minute\-second fields deleted.  Output distance
data will be in the same  units  as  the  ellipsoid  or  sphere
radius.
.sp
The Earth’s ellipsoidal figure may be selected in the same manner
as program \fBproj\fP by using \fI+ellps=\fP, \fI+a=\fP, \fI+es=\fP, etc.
.sp
Geod may also be used to determine  intermediate  points  along
either  a  geodesic  line between two points or along an arc of
specified distance from a geographic point.  In both  cases  an
initial  point must be specified with \fI+lat_1=lat\fP and \fI+lon_1=lon\fP
parameters  and  either  a  terminus   point   \fI+lat_2=lat\fP   and
\fI+lon_2=lon\fP  or  a  distance  and azimuth from the initial point
with \fI+S=distance\fP and \fI+A=azimuth\fP must be specified.
.sp
If points along a geodesic are to  be  determined  then  either
\fI+n_S=integer\fP  specifying  the  number  of  intermediate  points
and/or  \fI+del_S=distance\fP  specifying  the  incremental  distance
between points must be specified.
.sp
To  determine  points along an arc equidistant from the initial
point both \fI+del_A=angle\fP  and  \fI+n_A=integer\fP  must  be  specified
which determine the respective angular increments and number of
points to be determined.
.SS Examples
.sp
The following script determines the geodesic azimuths and  distance in U.S.
statute miles from Boston, MA, to Portland, OR:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
geod +ellps=clrk66 <<EOF \-I +units=us\-mi
42d15\(aqN 71d07\(aqW 45d31\(aqN 123d41\(aqW
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which gives the results:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-66d31\(aq50.141" 75d39\(aq13.083" 2587.504
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where the first two values are the azimuth from Boston to Portland,
the back azimuth from Portland to Boston followed by the distance.
.sp
An  example  of forward geodesic use is to use the Boston location
and determine Portland’s location by azimuth and distance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
geod +ellps=clrk66 <<EOF +units=us\-mi
42d15\(aqN 71d07\(aqW \-66d31\(aq50.141" 2587.504
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which gives:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
45d31\(aq0.003"N 123d40\(aq59.985"W 75d39\(aq13.094"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Lack  of precision in the distance value compromises the
precision of the Portland location.
.UNINDENT
.UNINDENT
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%GeographicLib\fP\&.
.IP 2. 3
C. F. F. Karney, \fI\%Algorithms for Geodesics\fP, J. Geodesy \fB87\fP(1), 43–55 (2013);
\fI\%addenda\fP\&.
.IP 3. 3
\fI\%A geodesic bibliography\fP\&.
.UNINDENT
.SS See also
.sp
\fBproj(1)\fP, \fBcs2cs(1)\fP, \fBcct(1)\fP, \fBgeod(1)\fP, \fBgie(1)\fP
.SS Bugs
.sp
A list of know bugs can be found at \fI\%http://github.com/OSGeo/proj.4/issues\fP
where new bug reports can be submitted to.
.SS Home page
.sp
\fI\%http://proj4.org/\fP
.SS gie
.SS Synopsis
.INDENT 0.0
.INDENT 3.5
\fBgie\fP [ \fB\-hovql\fP [ args ] ] file[s]
.UNINDENT
.UNINDENT
.SS Description
.sp
\fBgie\fP, the Geospatial Integrity Investigation Environment, is a
regression testing environment for the PROJ transformation library. Its primary
design goal is to be able to perform regression testing of code that are a part
of PROJ, while not requiring any other kind of tooling than the same C compiler
already employed for compiling the library.
.INDENT 0.0
.TP
.B \-h, \-\-help
Print usage information
.UNINDENT
.INDENT 0.0
.TP
.B \-o <file>, \-\-output <file>
Specify output file name
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Verbose: Provide non\-essential informational output.  Repeat \fI\%\-v\fP for
more verbosity (e.g. \fB\-vv\fP)
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Quiet: Opposite of verbose. In  quiet  mode  not  even  errors  are
reported.  Only  interaction  is through the return code (0 on success,
non\-zero indicates number of FAILED tests)
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-list
List the PROJ internal system error codes
.UNINDENT
.sp
Tests for \fBgie\fP are defined in simple text files. Usually having the
extension \fB\&.gie\fP\&. Test for \fBgie\fP are written in the purpose\-build command language for gie.
The basic functionality of the gie command language is implemented through just
3 command verbs: \fBoperation\fP, which defines the PROJ operation to test,
\fBaccept\fP, which defines the input coordinate to read, and \fBexpect\fP, which
defines the result to expect.
.sp
A sample test file for \fBgie\fP that uses the three above basic commands looks
like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<gie>

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Test output of the UTM projection
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
operation  +proj=utm  +zone=32  +ellps=GRS80
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
accept     12  55
expect     691_875.632_14   6_098_907.825_05

</gie>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Parsing of a  \fBgie\fP file starts at \fB<gie>\fP and ends when \fB</gie>\fP
is reached. Anything before \fB<gie>\fP and after \fB</gie>\fP is not considered.
Test cases are created by defining an \fI\%operation\fP which
\fI\%accept\fP an input coordinate and \fI\%expect\fP an output
coordinate.
.sp
Because \fBgie\fP tests are wrapped in the \fB<gie>\fP/\fB</gie>\fP tags it is
also possible to add test cases to custom made init files\&.
The tests will be ignore by PROJ when reading the init file with \fI+init\fP and
\fBgie\fP ignores anything not wrapped in \fB<gie>\fP/\fB</gie>\fP\&.
.sp
\fBgie\fP tests are defined by a set of commands like \fI\%operation\fP,
\fI\%accept\fP and \fI\%expect\fP in the example above. Together the
commands make out the \fBgie\fP command language. Any line in a
\fBgie\fP file that does not start with a command is ignored. In the
example above it is seen how this can be used to add comments and styling to
\fBgie\fP test files in order to make them more readable as well as
documenting what the purpose of the various tests are.
.sp
Below the \fI\%gie command language\fP is explained in details.
.SS Examples
.INDENT 0.0
.IP 1. 3
Run all tests in a file with all debug information turned on
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gie \-vvvv corner\-cases.gie
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 2. 3
Run all tests in several files
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gie foo bar
.ft P
.fi
.UNINDENT
.UNINDENT
.SS gie command language
.INDENT 0.0
.TP
.B operation <+args>
Define a PROJ operation to test. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
operation proj=utm zone=32 ellps=GRS80
# test 4D function
accept    12 55 0 0
expect    691875.63214  6098907.82501  0  0

# test 2D function
accept    12 56
expect    687071.4391   6210141.3267
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B accept <x y [z [t]]>
Define the input coordinate to read. Takes test coordinate. The coordinate
can be defined by either 2, 3 or 4 values, where the first two values are
the x\- and y\-components, the 3rd is the z\-component and the 4th is the time
component. The number of components in the coordinate determines which
version of the operation is tested (2D, 3D or 4D). Many coordinates can be
accepted for one \fI\%operation\fP\&. For each \fI\%accept\fP an
accompanying \fI\%expect\fP is needed.
.sp
Note that \fBgie\fP accepts the underscore (“_”) as a thousands
separator.  It is not required (in fact, it is entirely ignored by the
input routine), but it significantly improves the readability of the very
long strings of numbers typically required in projected coordinates.
.sp
See \fI\%operation\fP for an example.
.UNINDENT
.INDENT 0.0
.TP
.B expect <x y [z [t]]> | <error code>
Define the expected coordinate that will be returned from accepted
coordinate passed though an operation. The expected coordinate can be
defined by either 2, 3 or 4 components, similarly to \fI\%accept\fP\&.
Many coordinates can be expected for one \fI\%operation\fP\&. For each
\fI\%expect\fP an accompanying \fI\%accept\fP is needed.
.sp
See \fI\%operation\fP for an example.
.sp
In addition to expecting a coordinate it is also possible to expect a
PROJ error code in case an operation can’t be created. This is useful when
testing that errors are caught and handled correctly. Below is an example of
that tests that the pipeline operator fails correctly when a non\-invertable
pipeline is constructed.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
operation   proj=pipeline step
            proj=urm5 n=0.5 inv
expect      failure pjd_err_malformed_pipeline
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See \fBgie \-l\fP for a list of error codes that can be expected.
.UNINDENT
.INDENT 0.0
.TP
.B tolerance <tolerance>
The \fI\%tolerance\fP command controls how much accepted coordinates
can deviate from the expected coordinate. This is handy to test that an
operation meets a certain numerical tolerance threshold. Some operations
are expexted to be accurate within milimeters  where others might only be
accurate within a few meters. \fI\%tolerance\fP should
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
operation       proj=merc
# test coordinate as returned by \(ga\(ga\(gaecho 12 55 | proj +proj=merc\(ga\(ga
tolerance       1 cm
accept          12 55
expect          1335833.89 7326837.72

# test that the same coordinate with a 50 m false easting as determined
# by \(ga\(gaecho 12 55 |proj +proj=merc +x_0=50\(ga\(ga is still within a 100 m
# tolerance of the unaltered coordinate from proj=merc
tolerance       100 m
accept          12 55
expect          1335883.89  7326837.72
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The default tolerance is 0.5 mm. See \fBproj \-lu\fP for a list of possible
units.
.UNINDENT
.INDENT 0.0
.TP
.B roundtrip <n> <tolerance>
Do a roundtrip test of an operation. \fI\%roundtrip\fP needs a
\fI\%operation\fP and a \fI\%accept\fP command
to function. The accepted coordinate is passed to the operation first in
it’s forward mode, then the output from the forward operation is passed
back to the inverse operation. This procedure is done \fBn\fP times. If the
resulting coordinate is within the set tolerance of the initial coordinate
the test is passed.
.sp
Example:
.sp
operation       proj=merc
accept          12 55
roundtrip       10000 5 mm
.UNINDENT
.INDENT 0.0
.TP
.B direction <direction>
The \fI\%direction\fP command specifies in which direction an operation
is performed. This can either be \fBforward\fP or \fBinverse\fP\&. An example of
this is seen below where it is tested that a symmetrical transformation
pipeline returns the same results in both directions.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
operation proj=pipeline zone=32 step
          proj=utm  ellps=GRS80 step
          proj=utm  ellps=GRS80 inv
tolerance 0.1 mm

accept 12 55 0 0
expect 12 55 0 0

# Now the inverse direction (still same result: the pipeline is symmetrical)

direction inverse
expect 12 55 0 0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The default direction is “forward”.
.UNINDENT
.INDENT 0.0
.TP
.B ignore <error code>
This is especially
useful in test cases that rely on a grid that is not guaranteed to be
available. Below is an example of that situation.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
operation  proj=hgridshift +grids=nzgd2kgrid0005.gsb  ellps=GRS80
tolerance 1 mm
ignore    pjd_err_failed_to_load_grid
accept    172.999892181021551 \-45.001620431954613
expect    173                 \-45
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See \fBgie \-l\fP for a list of error codes that can be ignored.
.UNINDENT
.SS Background
.sp
More importantly than being an acronym for “Geospatial Integrity Investigation
Environment”, gie were also the initials, user id, and USGS email address of
Gerald Ian Evenden (1935–2016), the geospatial visionary, who, already in the
1980s, started what was  to  become  the PROJ of today.
.sp
Gerald’s clear vision was that map projections are \fIjust special functions\fP\&.
Some of them rather complex, most of them of two variables, but all of them
\fIjust special functions\fP, and not particularly more special than the \fBsin()\fP,
\fBcos()\fP, \fBtan()\fP, and \fBhypot()\fP already available  in  the  C standard library.
.sp
And hence, according to Gerald, \fIthey should not be particularly much harder
to use\fP, for a programmer, than the \fBsin()\fP’s, \fBtan()\fP’s and
\fBhypot()\fP’s so readily available.
.sp
Gerald’s ingenuity also showed in the implementation of the vision, where
he devised a comprehensive, yet simple, system of key\-value pairs for
parameterising a map projection, and the highly flexible PJ struct, storing
run\-time compiled versions of those key\-value pairs, hence mak\- ing  a  map
projection  function call, pj_fwd(PJ, point), as easy as a traditional function
call like \fBhypot(x,y)\fP\&.
.sp
While today, we may have more formally well defined metadata systems (most
prominent the OGC WKT2 representation), nothing comes close being as easily
readable (“human compatible”) as Gerald’s key\-value system. This system in
particular, and the PROJ system in general, was Gerald’s great gift to anyone
using and/or communicating about geodata.
.sp
It is only reasonable to name a program, keeping an eye on the
integrity of the PROJ system, in honour of Gerald.
.sp
So in honour, and hopefully also in the spirit, of Gerald Ian Evenden
(1935–2016), this is the Geospatial Integrity Investigation Environment.
.SS See also
.sp
\fBproj(1)\fP, \fBcs2cs(1)\fP, \fBcct(1)\fP, \fBgeod(1)\fP
.SS Bugs
.sp
A list of know bugs can be found at \fI\%http://github.com/OSGeo/proj.4/issues\fP
where new bug reports can be submitted to.
.SS Home page
.sp
\fI\%http://proj4.org/\fP
.SS Coordinate operations
.sp
Coordinate operations in PROJ are divided into three groups:
Projections, conversions  and transformations.
Projections are purely cartographic mappings of the sphere onto the plane.
Technically projections are conversions (according to ISO standards), though in
PROJ projections are distinguished from conversions. Conversions are coordinate
operations that do not exert a change in reference frame. Operations that do
exert a change in reference frame are called transformations.
.SS Projections
.sp
Projections are coordinate operations that are technically conversions but since
projections are so fundamental to PROJ we differentiate them from conversions.
.sp
Projections map the spherical 3D space to a flat 2D space.
.SS Albers Equal Area
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Conic.
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection.
T}
_
T{
\fBDefined area\fP
T}	T{
Global.
T}
_
T{
T}	T{
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_1\fP
T}	T{
First standard parallel. Defaults to 0.0.
T}
_
T{
\fI+lat_2\fP
T}	T{
Second standard parallel. Can not be equal to \fIlat_1\fP\&.
Defaults to 0.0.
T}
_
.TE
[image: Albers Equal Area]
[image]
.SS Azimuthal Equidistant
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Azimuthal
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+guam\fP
T}	T{
Use Guam elliptical formulas. Defaults to false.
T}
_
.TE
[image: Azimuthal Equidistant]
[image]
.SS Airy
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward spherical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_b\fP
T}	T{
T}
_
T{
\fI+no_cut\fP
T}	T{
Do not cut at hemisphere limit
T}
_
.TE
[image: Airy]
[image]
.SS Aitoff
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Miscellaneous
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse spherical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
.TE
[image: Aitoff]
[image]
.SS Mod. Stererographics of Alaska
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Modified azimuthal
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Alaska
T}
_
.TE
[image: Mod. Stererographics of Alaska]
[image]
.SS Apian Globular I
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Miscellaneous
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward spherical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
.TE
[image: Apian Globular I]
[image]
.SS August Epicycloidal
[image: August Epicycloidal]
[image]
.SS Bacon Globular
[image: Bacon Globular]
[image]
.SS Bipolar conic of western hemisphere
[image: Bipolar conic of western hemisphere]
[image]
.SS Boggs Eumorphic
[image: Boggs Eumorphic]
[image]
.SS Bonne (Werner lat_1=90)
[image: Bonne (Werner lat_1=90)]
[image]
.SS Cal Coop Ocean Fish Invest Lines/Stations
.sp
The CalCOFI pseudo\-projection is the line and station coordinate system of the
California Cooperative Oceanic Fisheries Investigations program, known as CalCOFI, for sampling offshore of the west coast of the U.S. and Mexico.
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Conformal cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Only valid for the west coast of USA and Mexico
T}
_
T{
\fBImplemented by\fP
T}	T{
Frank Warmerdam
T}
_
T{
\fBOptions\fP
T}
_
T{
\fINo special options for this projection\fP
T}
_
.TE
[image: Cal Coop Ocean Fish Invest Lines/Stations]
[image]
.sp
The coordinate system is based on the Mercator projection with units rotated \-30
degrees from the meridian so that they are oriented with the coastline of the Southern California Bight and Baja California.
Lines increase from Northwest to Southeast.
A unit of line is 12 nautical miles. Stations increase from inshore to offshore.
A unit of station is equal to 4 nautical miles.
The rotation point is located at line 80, station 60, or 34.15 degrees N, \-121.15 degrees W, and is depicted by the red dot in the figure.
By convention, the ellipsoid of Clarke 1866 is used to calculate CalCOFI coordinates.
.sp
The CalCOFI program is a joint research effort by the U.S. National Oceanic and
Atmospheric Administration, University of California Scripps Oceanographic Institute, and California Department of Fish and Game.
Surveys have been conducted for the CalCOFI program since 1951, creating one of the oldest and most scientifically valuable joint oceanographic and fisheries data sets in the world.
The CalCOFI line and station coordinate system is now used by several other programs including the Investigaciones Mexicanas de la Corriente de California (IMECOCAL) program offshore of Baja California.
The figure depicts some commonly sampled locations from line 40 to line 156.7 and offshore to station 120. Blue numbers indicate line (bottom) or station (left) numbers along the grid. Note that lines spaced at approximate 3\-1/3 intervals are commonly sampled, e.g., lines 43.3 and 46.7.
.SS Usage
.sp
A typical forward CalCOFI projection would be from lon/lat coordinates on the
Clark 1866 ellipsoid.
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=calcofi +ellps=clrk66 \-E <<EOF
\-121.15 34.15
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Output of the above command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-121.15 34.15   80.00   60.00
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The reverse projection from line/station coordinates to lon/lat would be entered
as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=calcofi +ellps=clrk66 \-I \-E \-f "%.2f" <<EOF
80.0 60.0
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Output of the above command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
80.0 60.0   \-121.15 34.15
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mathematical definition
.sp
The algorithm used to make conversions is described in [EberHewitt1979] with
a few corrections reported in [WeberMoore2013]\&.
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%General information about the CalCOFI program\fP
.IP 2. 3
\fI\%The Investigaciones Mexicanas de la Corriente de California\fP
.UNINDENT
.SS Cassini (Cassini\-Soldner)
.sp
Although the Cassini projection has been largely replaced by the Transverse Mercator, it is still in limited use outside the United States and was one of the major topographic mapping projections until the early 20th century.
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Transverse and oblique cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, Spherical and Elliptical
T}
_
T{
\fBDefined area\fP
T}	T{
Global, but best used near the central meridian with long, narrow areas
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_0\fP
T}	T{
Latitude of origin (Default to 0)
T}
_
.TE
[image: Cassini]
[image]
.SS Usage
.sp
There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini\-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century [Steers1970]\&.
Many of these maps were prepared at a scale of 1:2,500.
The Cassini\-Soldner was also used for the detailed mapping of many German states during the same period.
.sp
Example using EPSG 30200 (Trinidad 1903, units in clarke’s links):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 0.17453293 \-1.08210414 | proj +proj=cass +lat_0=10.44166666666667 +lon_0=\-61.33333333333334 +x_0=86501.46392051999 +y_0=65379.0134283 +a=6378293.645208759 +b=6356617.987679838 +to_meter=0.201166195164 +no_defs
66644.94    82536.22
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example using EPSG 3068 (Soldner Berlin):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 13.5 52.4 | proj +proj=cass +lat_0=52.41864827777778 +lon_0=13.62720366666667 +x_0=40000 +y_0=10000 +ellps=bessel +datum=potsdam +units=m +no_defs
31343.05    7932.76
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mathematical definition
.sp
The formulas describing the Cassini projection are taken from Snyder’s [Snyder1987]\&.
.sp
\phi_0 is the latitude of origin that match the center of the map (default to 0). It can be set with \fB+lat_0\fP\&.
.SS Spherical form
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Elliptical form
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
and M() is the meridional distance function.
.SS Inverse projection
.sp
.ce

.ce 0
.sp
if \phi' = \frac{\pi}{2} then \phi=\phi' and \lambda=0
.sp
otherwise evaluate T and N above using \phi' and
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.IP 2. 3
[Snyder1987]
.IP 3. 3
\fI\%EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas\fP
.UNINDENT
.SS Central Cylindrical
[image: Central Cylindrical]
[image]
.SS Central Conic
.sp
This is central (centrographic) projection on cone tangent at \fBlat_0\fP latitude,
identical with \fBconic()\fP projection from \fBmapproj\fP R package.
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Conic
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global, but best used near the standard parallel
T}
_
T{
\fBImplemented by\fP
T}	T{
Lukasz Komsta
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_1\fP
T}	T{
Latitude of standard parallel.
T}
_
.TE
[image: Central Conic]
[image]
.SS Usage
.sp
This simple projection is rarely used, as it is not equidistant, equal\-area, nor
conformal.
.sp
An example of usage (and the main reason to implement this projection in proj4)
is the ATPOL geobotanical grid of Poland, developed in Institute of Botany,
Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]\&. The grid was
originally handwritten on paper maps and further copied by hand. The projection
(together with strange Earth radius) was chosen by its creators as the compromise
fit to existing maps during first software development in DOS era. Many years later
it is still de facto standard grid in Polish geobotanical research.
.sp
The ATPOL coordinates can be achieved with with the following parameters:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=\-350000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For more information see [Komsta2016] and [Verey2017]\&.
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Reference values
.sp
For ATPOL to WGS84 test, run the following script:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#!/bin/bash
cat << EOF | src/cs2cs \-v \-f "%E" +proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=\-350000 +to +proj=longlat +datum=WGS84 +no_defs
0 0
0 700000
700000 0
700000 700000
330000 350000
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It should result with
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
1.384023E+01 5.503040E+01 0.000000E+00
1.451445E+01 4.877385E+01 0.000000E+00
2.478271E+01 5.500352E+01 0.000000E+00
2.402761E+01 4.875048E+01 0.000000E+00
1.900000E+01 5.200000E+01 0.000000E+00
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Analogous script can be run for reverse test:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cat << EOF  | src/cs2cs \-v \-f "%E" +proj=longlat +datum=WGS84 +no_defs +to +proj=ccon +lat_1=52 +lat_0=52 +lon_0=19 +axis=esu +a=6390000 +x_0=330000 +y_0=\-350000
24 55
15 49
24 49
19 52
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and it should give the following results:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
6.500315E+05 4.106162E+03 0.000000E+00
3.707419E+04 6.768262E+05 0.000000E+00
6.960534E+05 6.722946E+05 0.000000E+00
3.300000E+05 3.500000E+05 0.000000E+00
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Equal Area Cylindrical
[image: Equal Area Cylindrical]
[image]
.SS Chamberlin Trimetric
[image: Chamberlin Trimetric]
[image]
.SS Collignon
[image: Collignon]
[image]
.SS Craster Parabolic (Putnins P4)
[image: Craster Parabolic (Putnins P4)]
[image]
.SS Denoyer Semi\-Elliptical
[image: Denoyer Semi-Elliptical]
[image]
.SS Eckert I
[image: Eckert I]
[image]
.sp
.ce

.ce 0
.SS Eckert II
[image: Eckert II]
[image]
.SS Eckert III
[image: Eckert III]
[image]
.SS Eckert IV
[image: Eckert IV]
[image]
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Eckert V
[image: Eckert V]
[image]
.SS Eckert VI
[image: Eckert VI]
[image]
.SS Equidistant Cylindrical (Plate Carrée)
.sp
The simplest of all projections. Standard parallels (0° when omitted) may be specified that determine latitude of true scale (k=h=1).
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Conformal cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse
T}
_
T{
\fBDefined area\fP
T}	T{
Global, but best used near the equator
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_ts\fP
T}	T{
Latitude of true scale. Defaults to 0.0
T}
_
T{
\fI+lat_0\fP
T}	T{
Center of the map : latitude of origin
T}
_
.TE
[image: Equidistant Cylindrical (Plate Carrée)]
[image]
.SS Usage
.sp
Because of the distortions introduced by this projection, it has little use in navigation or cadastral mapping and finds its main use in thematic mapping.
In particular, the plate carrée has become a standard for global raster datasets, such as Celestia and NASA World Wind, because of the particularly simple relationship between the position of an image pixel on the map and its corresponding geographic location on Earth.
.sp
The following table gives special cases of the cylindrical equidistant projection.
.TS
center;
|l|l|.
_
T{
Projection Name
T}	T{
(lat ts=) \phi_0
T}
_
T{
Plain/Plane Chart
T}	T{
0°
T}
_
T{
Simple Cylindrical
T}	T{
0°
T}
_
T{
Plate Carrée
T}	T{
0°
T}
_
T{
Ronald Miller—minimum overall scale distortion
T}	T{
37°30′
T}
_
T{
E.Grafarend and A.Niermann
T}	T{
42°
T}
_
T{
Ronald Miller—minimum continental scale distortion
T}	T{
43°30′
T}
_
T{
Gall Isographic
T}	T{
45°
T}
_
T{
Ronald Miller Equirectangular
T}	T{
50°30′
T}
_
T{
E.Grafarend and A.Niermann minimum linear distortion
T}	T{
61°7′
T}
_
.TE
.sp
Example using EPSG 32662 (WGS84 Plate Carrée):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 2 47 | proj +proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs
222638.98       5232016.07
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example using Plate Carrée projection with true scale at latitude 30° and central meridian 90°W:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo \-88 30 | proj +proj=eqc +lat_ts=30 +lat_0=90w
\-8483684.61     13358338.90
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mathematical definition
.sp
The formulas describing the Equidistant Cylindrical projection are all taken from Snyder’s [Snyder1987]\&.
.sp
\phi_{ts} is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set with \fB+lat_ts\fP\&.
.sp
\phi_0 is the latitude of origin that match the center of the map. It can be set with \fB+lat_0\fP\&.
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.IP 2. 3
\fI\%Wolfram Mathworld\fP
.UNINDENT
.SS Equidistant Conic
[image: Equidistant Conic]
[image]
.SS Euler
[image: Euler]
[image]
.SS Extended Transverse Mercator
[image: Extended Transverse Mercator]
[image]
.SS Fahey
[image: Fahey]
[image]
.SS Foucaut
[image: Foucaut]
[image]
.SS Foucaut Sinusoidal
[image: Foucaut Sinusoidal]
[image]
.sp
The \fIy\fP\-axis is based upon a weighted mean of the cylindrical equal\-area and
the sinusoidal projections. Parameter n=n is the weighting factor where
0 <= n <= 1\&.
.sp
.ce

.ce 0
.sp
For the inverse, the Newton\-Raphson method can be used to determine
\phi from the equation for y above. As n \rightarrow 0 and
\phi \rightarrow \pi/2, convergence is slow but for n = 0, \phi =
\sin^1y
.SS Gall (Gall Stereographic)
.sp
The Gall stereographic projection, presented by James Gall in 1855, is a cylindrical projection.
It is neither equal\-area nor conformal but instead tries to balance the distortion inherent in any projection.
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Transverse and oblique cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, Spherical
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}	T{
No special options for this projection
T}
_
.TE
[image: Gall (Gall Stereographic)]
[image]
.SS Usage
.sp
The need for a world map which avoids some of the scale exaggeration of the Mercator projection has led to some commonly used cylindrical modifications, as well as to other modifications which are not cylindrical.
The earliest common cylindrical example was developed by James Gall of Edinburgh about 1855 (Gall, 1885, p. 119\-123).
His meridians are equally spaced, but the parallels are spaced at increasing intervals away from the Equator.
The parallels of latitude are actually projected onto a cylinder wrapped about the sphere, but cutting it at lats. 45° N. and S., the point of perspective being a point on the Equator opposite the meridian being projected.
It is used in several British atlases, but seldom in the United States.
The Gall projection is neither conformal nor equal\-area, but has a blend of various features.
Unlike the Mercator, the Gall shows the poles as lines running across the top and bottom of the map.
.sp
Example using Gall Stereographical
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs
708432.90   5193386.36
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example using Gall Stereographical (Central meridian 90°W)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs
7792761.91  5193386.36
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mathematical definition
.sp
The formulas describing the Gall Stereographical are all taken from Snyder’s [Snyder1993]\&.
.SS Spherical form
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.IP 2. 3
\fI\%Cartographic Projection Procedures for the UNIX Environment\-A User’s Manual\fP
.UNINDENT
.SS Geostationary Satellite View
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Azimuthal
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden and Martin Raspaud
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+h\fP
T}	T{
Satellite height above earth. Required.
T}
_
T{
\fI+sweep\fP
T}	T{
Sweep angle axis of the viewing instrument.
Valid options are \fBx\fP and \fBy\fP\&. Defaults to \fBy\fP\&.
T}
_
T{
\fI+lon_0\fP
T}	T{
Subsatellite longitude point.
T}
_
.TE
[image: Geostationary Satellite View]
[image]
.sp
The geos projection pictures how a geostationary satellite scans the earth at regular
scanning angle intervals.
.SS Usage
.sp
In order to project using the geos projection you can do the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=geos +h=35785831.0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The required argument \fBh\fP is the viewing point (satellite position) height above
the earth.
.sp
The projection coordinate relate to the scanning angle by the following simple
relation:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
scanning_angle (radians) = projection_coordinate / h
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Note on sweep angle
.sp
The viewing instrument on\-board geostationary satellites described by this
projection have a two\-axis gimbal viewing geometry. This means that the different
scanning positions are obtained by rotating the gimbal along a N/S axis (or \fBy\fP)
and a E/W axis (or \fBx\fP).
[image: Gimbal geometry]
[image]
.sp
In the image above, the outer\-gimbal axis, or sweep\-angle axis, is the N/S axis (\fBy\fP)
while the inner\-gimbal axis, or fixed\-angle axis, is the E/W axis (\fBx\fP).
.sp
This example represents the scanning geometry of the Meteosat series satellite.
However, the GOES satellite series use the opposite scanning geometry, with the
E/W axis (\fBx\fP) as the sweep\-angle axis, and the N/S (\fBy\fP) as the fixed\-angle axis.
.sp
The sweep argument is used to tell PROJ which on which axis the outer\-gimbal
is rotating. The possible values are x or y, y being the default. Thus, the
scanning geometry of the Meteosat series satellite should take sweep as x, and
GOES should take sweep as y.
.SS Ginsburg VIII (TsNIIGAiK)
[image: Ginsburg VIII (TsNIIGAiK)]
[image]
.SS General Sinusoidal Series
[image: General Sinusoidal Series]
[image]
.SS Gnomonic
[image: Gnomonic]
[image]
.SS Goode Homolosine
[image: Goode Homolosine]
[image]
.SS Mod. Stererographics of 48 U.S.
[image: Mod. Stererographics of 48 U.S.]
[image]
.SS Mod. Stererographics of 50 U.S.
[image: Mod. Stererographics of 50 U.S.]
[image]
.SS Hammer & Eckert\-Greifendorff
[image: Hammer & Eckert-Greifendorff]
[image]
.SS Hatano Asymmetrical Equal Area
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Pseudocylindrical Projection
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global, but best between standard parallels
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_1\fP
T}	T{
Standard Parallel 1
T}
_
T{
\fI+lat_2\fP
T}	T{
Standard Parallel 2
T}
_
T{
\fI+sym\fP
T}	T{
Symmetric form used instead of asymmetric
T}
_
.TE
[image: Hatano Asymmetrical Equal Area]
[image]
.SS Mathematical Definition
.SS Forward
.sp
.ce

.ce 0
.TS
center;
|l|l|l|.
_
T{
Condition
T}	T{
C_p
T}	T{
C_p
T}
_
T{
if \fB+sym\fP or \phi > 0
T}	T{
1.75859
T}	T{
2.67595
T}
_
T{
if not \fB+sym\fP and \phi < 0
T}	T{
1.93052
T}	T{
2.43763
T}
_
.TE
.sp
For \phi = 0, y \leftarrow 0, and x \leftarrow 0.85\lambda\&.
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Compare Map Projections\fP
.IP 2. 3
\fI\%Mathworks\fP
.UNINDENT
.SS HEALPix
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Mixed
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Alex Raichev and Michael Speth
T}
_
T{
\fBOptions\fP
T}
_
T{
\fINo special options for this projection\fP
T}
_
.TE
[image: HEALPix]
[image]
.sp
The HEALPix projection is area preserving and can be used with a spherical and
ellipsoidal model. It was initially developed for mapping cosmic background
microwave radiation. The image below is the graphical representation of the
mapping and consists of eight isomorphic triangular interrupted map graticules.
The north and south contains four in which straight meridians converge polewards
to a point and unequally spaced horizontal parallels. HEALPix provides a mapping
in which points of equal latitude and equally spaced longitude are mapped to points
of equal latitude and equally spaced longitude with the module of the polar
interruptions.
.SS Usage
.sp
To run a forward HEALPix projection on a unit sphere model, use the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=healpix +lon_0=0 +a=1 \-E <<EOF
0 0
EOF
# output
0 0 0.00 0.00
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%NASA\fP
.IP 2. 3
\fI\%Wikipedia\fP
.UNINDENT
.SS rHEALPix
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Mixed
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Alex Raichev and Michael Speth
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+north_square\fP
T}	T{
Position of the north polar square.
Valid inputs are 0–3. Defaults to 0.
T}
_
T{
\fI+south_square\fP
T}	T{
Position of the south polar square.
Valid inputs are 0–3. Defaults to 0.
T}
_
.TE
[image: rHEALPix]
[image]
.sp
rHEALPix is a projection based on the HEALPix projection. The implementation of
rHEALPix uses the HEALPix projection. The rHEALPix combines the peaks of the
HEALPix into a square. The square’s position can be translated and rotated across
the x\-axis which is a novel approach for the rHEALPix projection. The initial
intention of using rHEALPix in the Spatial Computation Engine Science Collaboration
Environment (SCENZGrid).
.SS Usage
.sp
To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following
command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=rhealpix \-f \(aq%.2f\(aq +ellps=WGS84 +south_square=0 +north_square=2  \-E << EOF
> 55 12
> EOF
55 12   6115727.86  1553840.13
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%NASA\fP
.IP 2. 3
\fI\%Wikipedia\fP
.UNINDENT
.SS Interrupted Goode Homolosine
[image: Interrupted Goode Homolosine]
[image]
.SS International Map of the World Polyconic
[image: International Map of the World Polyconic]
[image]
.SS Icosahedral Snyder Equal Area
[image: Icosahedral Snyder Equal Area]
[image]
.SS Kavraisky V
[image: Kavraisky V]
[image]
.SS Kavraisky VII
[image: Kavraisky VII]
[image]
.SS Krovak
[image: Krovak]
[image]
.SS Laborde
[image: Laborde]
[image]
.SS Lambert Azimuthal Equal Area
[image: Lambert Azimuthal Equal Area]
[image]
.SS Lagrange
[image: Lagrange]
[image]
.SS Larrivee
[image: Larrivee]
[image]
.SS Laskowski
[image: Laskowski]
[image]
.SS Lambert Conformal Conic
[image: Lambert Conformal Conic]
[image]
.SS Lambert Conformal Conic Alternative
[image: Lambert Conformal Conic Alternative]
[image]
.SS Lambert Equal Area Conic
[image: Lambert Equal Area Conic]
[image]
.SS Lee Oblated Stereographic
[image: Lee Oblated Stereographic]
[image]
.SS Loximuthal
[image: Loximuthal]
[image]
.SS Space oblique for LANDSAT
[image: Space oblique for LANDSAT]
[image]
.SS McBryde\-Thomas Flat\-Polar Sine (No. 1)
[image: McBryde-Thomas Flat-Polar Sine (No. 1)]
[image]
.SS McBryde\-Thomas Flat\-Pole Sine (No. 2)
[image: McBryde-Thomas Flat-Pole Sine (No. 2)]
[image]
.SS McBride\-Thomas Flat\-Polar Parabolic
[image: McBride-Thomas Flat-Polar Parabolic]
[image]
.SS McBryde\-Thomas Flat\-Polar Quartic
[image: McBryde-Thomas Flat-Polar Quartic]
[image]
.SS McBryde\-Thomas Flat\-Polar Sinusoidal
[image: McBryde-Thomas Flat-Polar Sinusoidal]
[image]
.SS Mercator
.sp
The Mercator projection is a cylindrical map projection that origins from the 15th
century. It is widely recognized as the first regularly used map projection.
The projection is conformal which makes it suitable for navigational purposes.
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Conformal cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical and elliptical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global, but best used near the equator
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_ts\fP
T}	T{
Latitude of true scale. Defaults to 0.0
T}
_
T{
\fI+k_0\fP
T}	T{
Scaling factor. Defaults to 1.0
T}
_
.TE
[image: Mercator]
[image]
.SS Usage
.sp
Applications should be limited to equatorial regions, but is frequently
used for navigational charts with latitude of true scale (\fB+lat_ts\fP) specified within
or near chart’s boundaries.
Often inappropriately used for world maps since the regions near the poles
cannot be shown [Evenden1995]\&.
.sp
Example using latitude of true scale:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 56.35 12.32 | proj +proj=merc +lat_ts=56.5
3470306.37    759599.90
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example using scaling factor:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
echo 56.35 12.32 | proj +proj=merc +k_0=2
12545706.61     2746073.80
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that \fB+lat_ts\fP and \fB+k_0\fP are mutually exclusive.
If used together, \fB+lat_ts\fP takes precedence over \fB+k_0\fP\&.
.SS Mathematical definition
.sp
The formulas describing the Mercator projection are all taken from G. Evenden’s libproj manuals [Evenden2005]\&.
.SS Spherical form
.sp
For the spherical form of the projection we introduce the scaling factor:
.sp
.ce

.ce 0
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Elliptical form
.sp
For the elliptical form of the projection we introduce the scaling factor:
.sp
.ce

.ce 0
.sp
where m\left(\phi\right) is the parallel radius at latitude \phi\&.
.sp
We also use the Isometric Latitude kernel function t()\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
m() and t() should be described properly on a separate page about the theory of projections on the ellipsoid.
.UNINDENT
.UNINDENT
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.IP 2. 3
\fI\%Wolfram Mathworld\fP
.UNINDENT
.SS Miller Oblated Stereographic
[image: Miller Oblated Stereographic]
[image]
.SS Miller Cylindrical
.sp
The Miller cylindrical projection is a modified Mercator projection, proposed by Osborn Maitland Miller in 1942.
The latitude is scaled by a factor of \frac{4}{5}, projected according to Mercator, and then the result is multiplied by \frac{5}{4} to retain scale along the equator.
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Neither conformal nor equal area cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse spherical
T}
_
T{
\fBDefined area\fP
T}	T{
Global, but best used near the equator
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_0\fP
T}	T{
Latitude of origin (Default to 0)
T}
_
.TE
[image: Miller Cylindrical]
[image]
.SS Usage
.sp
The Miller Cylindrical projection is used for world maps and in several atlases,
including the National Atlas of the United States (USGS, 1970, p. 330\-331) [Snyder1987]\&.
.sp
Example using Central meridian 90°W:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo \-100 35 | proj +proj=mill +lon_0=90w
\-1113194.91      4061217.24
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mathematical definition
.sp
The formulas describing the Miller projection are all taken from Snyder’s manuals [Snyder1987]\&.
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.UNINDENT
.SS Mollweide
[image: Mollweide]
[image]
.SS Murdoch I
[image: Murdoch I]
[image]
.SS Murdoch II
[image: Murdoch II]
[image]
.SS Murdoch III
[image: Murdoch III]
[image]
.SS Natural Earth
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Pseudo cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Bernhard Jenny
T}
_
T{
\fBOptions\fP
T}
_
T{
\fINo special options for this projection\fP
T}
_
.TE
[image: Natural Earth]
[image]
.sp
The Natural Earth projection is intended for making world maps. A distinguishing trait
is its slightly rounded corners fashioned to emulate the spherical shape of Earth.
The meridians (except for the central meridian) bend acutely inward as they approach
the pole lines, giving the projection a hint of three\-dimensionality. This bending
also suggests that the meridians converge at the poles instead of truncating at the
top and bottom edges. The distortion characteristics of the Natural Earth projection
compare favorably to other world map projections.
.SS Usage
.sp
The Natural Earth projection has no special options so usage is simple. Here is
an example of an inverse projection on a sphere with a radius of 7500 m:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 3500 \-8000 | proj \-I +proj=natearth +a=7500
37d54\(aq6.091"E  61d23\(aq4.582"S
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.UNINDENT
.SS Nell
[image: Nell]
[image]
.SS Nell\-Hammer
[image: Nell-Hammer]
[image]
.SS Nicolosi Globular
[image: Nicolosi Globular]
[image]
.SS Near\-sided perspective
[image: Near-sided perspective]
[image]
.SS New Zealand Map Grid
[image: New Zealand Map Grid]
[image]
.SS General Oblique Transformation
[image: General Oblique Transformation]
[image]
.SS Oblique Cylindrical Equal Area
[image: Oblique Cylindrical Equal Area]
[image]
.SS Oblated Equal Area
[image: Oblated Equal Area]
[image]
.SS Oblique Mercator
[image: Oblique Mercator]
[image]
.SS Ortelius Oval
[image: Ortelius Oval]
[image]
.SS Orthographic
[image: Orthographic]
[image]
.SS Perspective Conic
[image: Perspective Conic]
[image]
.SS Polyconic (American)
[image: Polyconic (American)]
[image]
.SS Putnins P1
[image: Putnins P1]
[image]
.SS Putnins P2
[image: Putnins P2]
[image]
.SS Putnins P3
[image: Putnins P3]
[image]
.SS Putnins P3’
[image: Putnins P3']
[image]
.SS Putnins P4’
[image: Putnins P4']
[image]
.SS Putnins P5
[image: Putnins P5]
[image]
.SS Putnins P5’
[image: Putnins P5']
[image]
.SS Putnins P6
[image: Putnins P6]
[image]
.SS Putnins P6’
[image: Putnins P6']
[image]
.SS Quartic Authalic
[image: Quartic Authalic]
[image]
.SS Quadrilateralized Spherical Cube
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Azimuthal
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, elliptical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Martin Lambers
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_0\fP
T}	T{
Latitude (in degrees) of the view position.
T}
_
T{
\fI+lon_0\fP
T}	T{
Longitude (in degrees) of the view position.
T}
_
.TE
.sp
The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project
a sphere surface onto the six sides of a cube:
[image: Quadrilateralized Spherical Cube]
[image]
.sp
For this purpose, other alternatives can be used, notably gnom or
healpix\&. However, QSC projection has the following favorable properties:
.sp
It is an equal\-area projection, and at the same time introduces only limited angular
distortions. It treats all cube sides equally, i.e. it does not use different
projections for polar areas and equatorial areas. These properties make QSC
projection a good choice for planetary\-scale terrain rendering. Map data can be
organized in quadtree structures for each cube side. See [LambersKolb2012] for an example.
.sp
The QSC projection was introduced by [ONeilLaubscher1976],
building on previous work by [ChanONeil1975]\&. For clarity: The
earlier QSC variant described in [ChanONeil1975] became known as the COBE QSC since it
was used by the NASA Cosmic Background Explorer (COBE) project; it is an approximately
equal\-area projection and is not the same as the QSC projection.
.sp
See also [CalabrettaGreisen2002] Sec. 5.6.2 and 5.6.3 for a description of both and
some analysis.
.sp
In this implementation, the QSC projection projects onto one side of a circumscribed
cube. The cube side is selected by choosing one of the following six projection centers:
.TS
center;
|l|l|.
_
T{
\fB+lat_0=0 +lon_0=0\fP
T}	T{
front cube side
T}
_
T{
\fB+lat_0=0 +lon_0=90\fP
T}	T{
right cube side
T}
_
T{
\fB+lat_0=0 +lon_0=180\fP
T}	T{
back cube side
T}
_
T{
\fB+lat_0=0 +lon_0=\-90\fP
T}	T{
left cube side
T}
_
T{
\fB+lat_0=90\fP
T}	T{
top cube side
T}
_
T{
\fB+lat_0=\-90\fP
T}	T{
bottom cube side
T}
_
.TE
.sp
Furthermore, this implementation allows the projection to be applied to ellipsoids.
A preceding shift to a sphere is performed automatically; see [LambersKolb2012] for details.
.SS Usage
.sp
The following example uses QSC projection via GDAL to create the six cube side
maps from a world map for the WGS84 ellipsoid:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gdalwarp \-t_srs "+wktext +proj=qsc +units=m +ellps=WGS84  +lat_0=0 +lon_0=0"        \e
    \-wo SOURCE_EXTRA=100 \-wo SAMPLE_GRID=YES \-te \-6378137 \-6378137 6378137 6378137  \e
    worldmap.tiff frontside.tiff

gdalwarp \-t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=90"        \e
    \-wo SOURCE_EXTRA=100 \-wo SAMPLE_GRID=YES \-te \-6378137 \-6378137 6378137 6378137  \e
    worldmap.tiff rightside.tiff

gdalwarp \-t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=180"       \e
    \-wo SOURCE_EXTRA=100 \-wo SAMPLE_GRID=YES \-te \-6378137 \-6378137 6378137 6378137  \e
    worldmap.tiff backside.tiff

gdalwarp \-t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=\-90"       \e
    \-wo SOURCE_EXTRA=100 \-wo SAMPLE_GRID=YES \-te \-6378137 \-6378137 6378137 6378137  \e
    worldmap.tiff leftside.tiff

gdalwarp \-t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=90 +lon_0=0"        \e
    \-wo SOURCE_EXTRA=100 \-wo SAMPLE_GRID=YES \-te \-6378137 \-6378137 6378137 6378137  \e
    worldmap.tiff topside.tiff

gdalwarp \-t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=\-90 +lon_0=0"       \e
    \-wo SOURCE_EXTRA=100 \-wo SAMPLE_GRID=YES \-te \-6378137 \-6378137 6378137 6378137  \e
    worldmap.tiff bottomside.tiff
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Explanation:
.INDENT 0.0
.IP \(bu 2
QSC projection is selected with \fB+wktext +proj=qsc\fP\&.
.IP \(bu 2
The WGS84 ellipsoid is specified with \fB+ellps=WGS84\fP\&.
.IP \(bu 2
The cube side is selected with \fB+lat_0=... +lon_0=...\fP\&.
.IP \(bu 2
The \fB\-wo\fP options are necessary for GDAL to avoid holes in the output maps.
.IP \(bu 2
The \fB\-te\fP option limits the extends of the output map to the major axis diameter
(from \-radius to +radius in both x and y direction). These are the dimensions of one side
of the circumscribing cube.
.UNINDENT
.sp
The resulting images can be laid out in a grid like below.
.TS
center;
|l|l|l|l|.
_
T{
T}	T{
[image: Top side]
[image]
T}	T{
T}	T{
T}
_
T{
[image: Left side]
[image]
T}	T{
[image: Front side]
[image]
T}	T{
[image: Right side]
[image]
T}	T{
[image: Back side]
[image]
T}
_
T{
T}	T{
[image: Bottom side]
[image]
T}	T{
T}	T{
T}
_
.TE
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.IP 2. 3
\fI\%NASA\fP
.UNINDENT
.SS Robinson
[image: Robinson]
[image]
.SS Roussilhe Stereographic
[image: Roussilhe Stereographic]
[image]
.SS Rectangular Polyconic
[image: Rectangular Polyconic]
[image]
.SS Sinusoidal (Sanson\-Flamsteed)
[image: Sinusoidal (Sanson-Flamsteed)]
[image]
.sp
MacBryde and Thomas developed generalized formulas for sever of the
pseudocylindricals with sinusoidal meridians:
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Swiss. Obl. Mercator
[image: Swiss. Obl. Mercator]
[image]
.SS Stereographic
[image: Stereographic]
[image]
.SS Oblique Stereographic Alternative
[image: Oblique Stereographic Alternative]
[image]
.SS Gauss\-Schreiber Transverse Mercator (aka Gauss\-Laborde Reunion)
[image: Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion)]
[image]
.SS Transverse Central Cylindrical
[image: Transverse Central Cylindrical]
[image]
.SS Transverse Cylindrical Equal Area
[image: Transverse Cylindrical Equal Area]
[image]
.SS Tissot
[image: Tissot]
[image]
.SS Transverse Mercator
.sp
The transverse Mercator projection in its various forms is the most widely used projected coordinate system for world topographical and offshore mapping.
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Transverse and oblique cylindrical
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, Spherical and Elliptical
T}
_
T{
\fBDefined area\fP
T}	T{
Global, but reasonably accurate only within 15 degrees of the central meridian
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+lat_0\fP
T}	T{
Latitude of origin (Default to 0)
T}
_
T{
\fI+k0\fP
T}	T{
Scale factor at natural origin (Default to 1)
T}
_
.TE
[image: Transverse Mercator]
[image]
.SS Usage
.sp
Prior to the development of the Universal Transverse Mercator coordinate system, several European nations demonstrated the utility of grid\-based conformal maps by mapping their territory during the interwar period.
Calculating the distance between two points on these maps could be performed more easily in the field (using the Pythagorean theorem) than was possible using the trigonometric formulas required under the graticule\-based system of latitude and longitude.
In the post\-war years, these concepts were extended into the Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) coordinate system, which is a global (or universal) system of grid\-based maps.
.sp
The following table gives special cases of the Transverse Mercator projection.
.TS
center;
|l|l|l|l|l|.
_
T{
Projection Name
T}	T{
Areas
T}	T{
Central meridian
T}	T{
Zone width
T}	T{
Scale Factor
T}
_
T{
Transverse Mercator
T}	T{
World wide
T}	T{
Various
T}	T{
less than 6°
T}	T{
Various
T}
_
T{
Transverse Mercator south oriented
T}	T{
Southern Africa
T}	T{
2° intervals E of 11°E
T}	T{
2°
T}	T{
1.000
T}
_
T{
UTM North hemisphere
T}	T{
World wide equator to 84°N
T}	T{
6° intervals E & W of 3° E & W
T}	T{
Always 6°
T}	T{
0.9996
T}
_
T{
UTM South hemisphere
T}	T{
World wide north of 80°S to equator
T}	T{
6° intervals E & W of 3° E & W
T}	T{
Always 6°
T}	T{
0.9996
T}
_
T{
Gauss\-Kruger
T}	T{
Former USSR, Yugoslavia, Germany, S. America, China
T}	T{
Various, according to area
T}	T{
Usually less than 6°, often less than 4°
T}	T{
1.0000
T}
_
T{
Gauss Boaga
T}	T{
Italy
T}	T{
Various, according to area
T}	T{
6°
T}	T{
0.9996
T}
_
.TE
.sp
Example using Gauss\-Kruger on Germany area (aka EPSG:31467)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 9 51 | proj +proj=tmerc +lat_0=0 +lon_0=9 +k=1 +x_0=3500000 +y_0=0 +ellps=bessel +datum=potsdam +units=m +no_defs
3500000.00  5651505.56
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Example using Gauss Boaga on Italy area (EPSG:3004)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 15 42 | proj +proj=tmerc +lat_0=0 +lon_0=15 +k=0.9996 +x_0=2520000 +y_0=0 +ellps=intl +units=m +no_defs
2520000.00  4649858.60
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mathematical definition
.sp
The formulas describing the Transverse Mercator are all taken from Evenden’s [Evenden2005]\&.
.sp
\phi_0 is the latitude of origin that match the center of the map. It can be set with \fB+lat_0\fP\&.
.sp
k_0 is the scale factor at the natural origin (on the central meridian). It can be set with \fB+k_0\fP\&.
.sp
M(\phi) is the meridional distance.
.SS Spherical form
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Elliptical form
.SS Forward projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Inverse projection
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.SS Further reading
.INDENT 0.0
.IP 1. 3
\fI\%Wikipedia\fP
.IP 2. 3
\fI\%EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas\fP
.UNINDENT
.SS Two Point Equidistant
[image: Two Point Equidistant]
[image]
.SS Tilted perspective
.TS
center;
|l|l|.
_
T{
\fBClassification\fP
T}	T{
Azimuthal
T}
_
T{
\fBAvailable forms\fP
T}	T{
Forward and inverse, spherical projection
T}
_
T{
\fBDefined area\fP
T}	T{
Global
T}
_
T{
\fBImplemented by\fP
T}	T{
Gerald I. Evenden
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+h\fP
T}	T{
Height (in meters) above the surface. Required.
T}
_
T{
\fI+azi\fP
T}	T{
Bearing (in degrees) from due north.
T}
_
T{
\fI+tilt\fP
T}	T{
Angle (in degrees) away from nadir.
T}
_
T{
\fI+lat_0\fP
T}	T{
Latitude (in degrees) of the view position.
T}
_
T{
\fI+lon_0\fP
T}	T{
Longitude (in degrees) of the view position.
T}
_
.TE
[image: Tilted perspective]
[image]
.sp
Tilted Perspective is similar to nsper (\fBnsper\fP) in that it simulates a
perspective view from a height. Where \fBnsper\fP projects onto a plane tangent to
the surface, Tilted Perspective orients the plane towards the direction of the
view. Thus, extra parameters azi and tilt are required beyond \fInsper\(ga\fP’s \fBh\fP\&.
As with \fBnsper\fP, \fBlat_0\fP & \fBlon_0\fP are also required
for satellite position.
.SS Universal Polar Stereographic
[image: Universal Polar Stereographic]
[image]
.SS Urmaev V
[image: Urmaev V]
[image]
.SS Urmaev Flat\-Polar Sinusoidal
[image: Urmaev Flat-Polar Sinusoidal]
[image]
.SS Universal Transverse Mercator (UTM)
[image: Universal Transverse Mercator (UTM)]
[image]
.SS van der Grinten (I)
[image: van der Grinten (I)]
[image]
.SS van der Grinten II
[image: van der Grinten II]
[image]
.SS van der Grinten III
[image: van der Grinten III]
[image]
.SS van der Grinten IV
[image: van der Grinten IV]
[image]
.SS Vitkovsky I
[image: Vitkovsky I]
[image]
.SS Wagner I (Kavraisky VI)
[image: Wagner I (Kavraisky VI)]
[image]
.SS Wagner II
[image: Wagner II]
[image]
.sp
.ce

.ce 0
.SS Wagner III
[image: Wagner III]
[image]
.sp
.ce

.ce 0
.SS Wagner IV
[image: Wagner IV]
[image]
.SS Wagner V
[image: Wagner V]
[image]
.SS Wagner VI
[image: Wagner VI]
[image]
.SS Wagner VII
[image: Wagner VII]
[image]
.SS Werenskiold I
[image: Werenskiold I]
[image]
.SS Winkel I
[image: Winkel I]
[image]
.SS Winkel II
[image: Winkel II]
[image]
.SS Winkel Tripel
[image: Winkel Tripel]
[image]
.SS Conversions
.sp
Conversions are coordinate operations in which both coordinate reference systems
are based on the same datum. In PROJ projections are differentiated from
conversions.
.SS Axis swap
.sp
Change the order and sign of 2,3 or 4 axes.
.TS
center;
|l|l|.
_
T{
\fBOptions\fP
T}
_
T{
\fI+order\fP
T}	T{
Ordered comma\-separated list of axis, e.g. \fI+order=2,1,3,4\fP
T}
_
.TE
.sp
Each of the possible four axes are numbered with 1\-4, such that the first input axis
is 1, the second is 2 and so on. The output ordering is controlled by a list of the
input axes re\-ordered to the new mapping.
.SS Examples
.sp
Reversing the order of the axes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=axisswap +order=4,3,2,1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Swapping the first two axes (x and y):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=axisswap +order=2,1,3,4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The direction, or sign, of an axis can be changed by adding a minus in
front of the axis\-number:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=axisswap +order=1,\-2,3,4
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is only necessary to specify the axes that are affected by the swap
operation:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=axisswap +order=2,1
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Cartesian to geodetic conversion
.sp
Convert geodetic coordinates to cartesian coordinates.
.TS
center;
|l|l|.
_
T{
\fBOptions\fP
T}
_
T{
\fI+ellps\fP
T}	T{
Ellipsoid of the input coordinates. If used together with the
ellipsoid parameters below, \fB+ellps\fP is overwritten.
T}
_
T{
\fI+a\fP
T}	T{
Semi\-major radius of ellipsoid axis.
T}
_
T{
\fI+b\fP
T}	T{
Semi\-minor radius of ellipsoid axis.
T}
_
T{
\fI+es\fP
T}	T{
Eccentricity of ellipsoid.
T}
_
T{
\fI+f\fP
T}	T{
Flattening of ellipsoid.
T}
_
.TE
.SS Lat/long (Geodetic)
.SS Lat/long (Geodetic alias)
.SS Unit conversion
.sp
Convert between various distance and time units.
.TS
center;
|l|l|.
_
T{
\fBOptions\fP
T}
_
T{
\fI+xy_in\fP
T}	T{
Input unit of the horizontal components.
T}
_
T{
\fI+xy_out\fP
T}	T{
Output unit of the horizontal components.
T}
_
T{
\fI+z_in\fP
T}	T{
Input unit of the vertical component.
T}
_
T{
\fI+z_out\fP
T}	T{
Output unit of the vertical component.
T}
_
T{
\fI+t_in\fP
T}	T{
Input unit of the time component.
T}
_
T{
\fI+t_out\fP
T}	T{
Output unit of the time component.
T}
_
.TE
.sp
There are many examples of coordinate reference systems that are expressed in
other units than the meter. There are also many cases where temporal data
has to be translated to different units. The \fIunitconvert\fP operation takes care
of that.
.sp
Many North American systems are defined with coordinates in feet. For example
in Vermont:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline
+step +proj=tmerc +lat_0=42.5 +lon_0=\-72.5 +k=0.999964286 +x_0=500000.00001016 +y_0=0
+step +proj=unitconvert +xy_in=m +xy_out=us\-ft
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Often when working with GNSS data the timestamps are presented in GPS\-weeks,
but when the data transformed with the \fIhelmert\fP operation timestamps are
expected to be in units of decimalyears. This can be fixed with \fIunitconvert\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline
+step +proj=unitconvert +t_in=gpsweek +t_out=decimalyear
+step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Distance units
.sp
In the table below all distance units supported by PROJ is listed.
The same list can also be produced on the command line with \fIproj\fP or \fIcs2cs\fP,
by adding the \fI\-lu\fP flag when calling the utility.
.TS
center;
|l|l|.
_
T{
Label
T}	T{
Name
T}
_
T{
km
T}	T{
Kilometer
T}
_
T{
m
T}	T{
Meter
T}
_
T{
dm
T}	T{
Decimeter
T}
_
T{
cm
T}	T{
Centimeter
T}
_
T{
mm
T}	T{
Millimeter
T}
_
T{
kmi
T}	T{
International Nautical Mile
T}
_
T{
in
T}	T{
International Inch
T}
_
T{
ft
T}	T{
International Foot
T}
_
T{
yd
T}	T{
International Yard
T}
_
T{
mi
T}	T{
International Statute Mile
T}
_
T{
fath
T}	T{
International Fathom
T}
_
T{
ch
T}	T{
International Chain
T}
_
T{
link
T}	T{
International Link
T}
_
T{
us\-in
T}	T{
U.S. Surveyor’s Inch
T}
_
T{
us\-ft
T}	T{
U.S. Surveyor’s Foot
T}
_
T{
us\-yd
T}	T{
U.S. Surveyor’s Yard
T}
_
T{
us\-ch
T}	T{
U.S. Surveyor’s Chain
T}
_
T{
us\-mi
T}	T{
U.S. Surveyor’s Statute Mile
T}
_
T{
ind\-yd
T}	T{
Indian Yard
T}
_
T{
ind\-ft
T}	T{
Indian Foot
T}
_
T{
ind\-ch
T}	T{
Indian Chain
T}
_
.TE
.SS Time units
.sp
In the table below all time units supported by PROJ is listed.
.TS
center;
|l|l|.
_
T{
mjd
T}	T{
Modified Julian date
T}
_
T{
decimalyear
T}	T{
Decimal year
T}
_
T{
gps_week
T}	T{
GPS Week
T}
_
.TE
.SS Transformations
.sp
Transformations coordinate operation in which the two coordinate reference
systems are based on different datums.
.SS Kinematic datum shifting utilizing a deformation model
.sp
Perform datum shifts means of a deformation/velocity model.
.TS
center;
|l|l|.
_
T{
\fBInput type\fP
T}	T{
Cartesian coordinates.
T}
_
T{
\fBOutput type\fP
T}	T{
Cartesian coordinates.
T}
_
T{
\fBOptions\fP
T}
_
T{
\fIxy_grids\fP
T}	T{
Comma\-separated list of grids to load.
T}
_
T{
\fIz_grids\fP
T}	T{
Comma\-separated list of grids to load.
T}
_
T{
\fIt_epoch\fP
T}	T{
Central epoch of transformation. [decimalyear]. Only used in
spatiotemporal transformations.
T}
_
T{
\fIt_obs\fP
T}	T{
Observation time of coordinate(s). Mostly useful in 2D and 3D
transformations. [decimalyear]. \fIOptional\fP\&.
T}
_
.TE
.sp
The deformation operation is used to adjust coordinates for intraplate deformations.
Usually the transformation parameters for regional plate\-fixed reference frames such as
the ETRS89 does not take intraplate deformation into account. It is assumed that
tectonic plate of the region is rigid. Often times this is true, but near the plate
boundary and in areas with post\-glacial uplift the assumption breaks. Intraplate
deformations can be modelled and then applied to the coordinates so that
they represent the physical world better. In PROJ this is done with the deformation
operation.
.sp
The horizontal grid is stored in CTable2 format and the vertical grid is stored in the
GTX format. Both grids are expected to contain grid\-values in units of mm/year.
Details about the formats can be found in the GDAL documentation. GDAL both reads and
writes both file formats. Using GDAL for construction of new grids is recommended.
.SS Example
.sp
In [Häkli2016] coordinate transformation including a deformation model is described.
The paper describes how coordinates from the global ITRFxx frames are transformed to the
local Nordic realisations of ETRS89. Scandinavia is an area with significant post\-glacial
rebound. The deformations from the post\-glacial uplift is not accounted for in the
official ETRS89 transformations so in order to get accurate transformations in the Nordic
countries it is necessary to apply the deformation model. The transformation from ITRF2008
to the Danish realisation of ETRS89 is in PROJ described as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj =  pipeline ellps = GRS80
        # ITRF2008@t_obs \-> ITRF2000@t_obs
step    init = ITRF2008:ITRF2000
        # ITRF2000@t_obs \-> ETRF2000@t_obs
step    proj=helmert t_epoch = 2000.0 transpose
        x =  0.054  rx =  0.000891 drx =  8.1e\-05
        y =  0.051  ry =  0.00539  dry =  0.00049
        z = \-0.048  rz = \-0.008712 drz = \-0.000792
        # ETRF2000@t_obs \-> NKG_ETRF00@2000.0
step    proj = deformation t_epoch = 2000.0
        xy_grids = ./nkgrf03vel_realigned_xy.ct2
        z_grids  = ./nkgrf03vel_realigned_z.gtx
        # NKG_ETRF@2000.0 \-> ETRF92@2000.0
step    proj=helmert transpose s = \-0.009420e
        x = 0.03863 rx = 0.00617753
        y = 0.147   ry = 5.064e\-05
        z = 0.02776 rz = 4.729e\-05
        # ETRF92@2000.0 \-> ETRF92@1994.704
step    proj = deformation t_epoch = 1994.704 t_obs = 2000.0
        xy_grids = ./nkgrf03vel_realigned_xy.ct2
        z_grids  = ./nkgrf03vel_realigned_z.gtx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
From this we can see that the transformation from ITRF2008 to the Danish realisation of
ETRS89 is a combination of Helmert transformations and adjustments with a deformation
model. The first use of the deformation operation is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj = deformation t_epoch = 2000.0
xy_grids = ./nkgrf03vel_realigned_xy.ct2
z_grids  = ./nkgrf03vel_realigned_z.gtx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here we set the central epoch of the transformation, 2000.0. The observation epoch
is expected as part of the input coordinate tuple. The deformation model is
described by two grids, specified with \fIxy_grids\fP and \fIz_grids\fP\&. The first is
the horizontal part of the model and the second is the vertical component.
.SS Mathematical description
.sp
Mathematically speaking, application of a deformation model is simple. The deformation model is
represented as a grid of velocities in three dimensions. Coordinate corrections are
applied in cartesian space. For a given coordinate, (X, Y, Z), velocities
(V_X, V_Y, V_Z) can be interpolated from the gridded model. The time span
between t_c and t_{obs} determine the magnitude of the coordinate
correcton as seen in eq. \fI\%(1)\fP below.
.sp
.ce

.ce 0
.sp
Corrections are done in cartesian space.
.sp
Coordinates of the gridded model are in ENU (east, north, up) space because it would
otherwise require an enormous 3 dimensional grid to handle the corrections in cartesian
space. Keeping the correction in lat/long space reduces the complexity of the grid
significantly. Consequently though, the input coordinates needs to be converted to
lat/long space when searching for corrections in the grid. This is done with \fIcart\fP
operation. The converted grid corrections can then be applied to the input coordinates
in cartesian space. The conversion from ENU space to cartesian space is done in the
following way:
.sp
.ce

.ce 0
.sp
where \phi and \lambda are the latitude and longitude of the coordinate
that is searched for in the grid. (E, N, U) are the grid values in ENU\-space and
(X, Y, Z) are the corrections converted to cartesian space.
.SS Helmert transform
.sp
The Helmert transformation changes coordinates from one reference frame to
anoether by means of 3\-, 4\-and 7\-parameter shifts, or one of their 6\-, 8\- and
14\-parameter kinematic counterparts.
.TS
center;
|l|l|.
_
T{
\fBInput type\fP
T}	T{
Cartesian coordinates (spatial), decimalyears (temporal).
T}
_
T{
\fBOutput type\fP
T}	T{
Cartesian coordinates (spatial), decimalyears (temporal).
T}
_
T{
\fBOptions\fP
T}
_
T{
\fIx\fP
T}	T{
Translation of the x\-axis [m]. \fIOptional\fP\&.
T}
_
T{
\fIy\fP
T}	T{
Translation of the y\-axis [m]. \fIOptional\fP\&.
T}
_
T{
\fIz\fP
T}	T{
Translation of the z\-axis. [m]. \fIOptional\fP\&.
T}
_
T{
\fIs\fP
T}	T{
Scale factor [ppm]. \fIOptional\fP\&.
T}
_
T{
\fIrx\fP
T}	T{
X\-axis rotation in the 3D Helmert [arc seconds]. \fIOptional\fP\&.
T}
_
T{
\fIry\fP
T}	T{
Y\-axis rotation in the 3D Helmert [arc seconds]. \fIOptional\fP\&.
T}
_
T{
\fIrz\fP
T}	T{
Z\-axis rotation in the 3D Helmert [arc seconds]. \fIOptional\fP\&.
T}
_
T{
\fItheta\fP
T}	T{
Rotation angle in the 2D Helmert. [arc seconds]. \fIOptional\fP\&.
T}
_
T{
\fIdx\fP
T}	T{
Translation rate of the x\-axis. [m/year]. \fIOptional\fP\&.
T}
_
T{
\fIdy\fP
T}	T{
Translation rate of the y\-axis. [m/year]. \fIOptional\fP\&.
T}
_
T{
\fIdz\fP
T}	T{
Translation rate of the z\-axis. [m/year]. \fIOptional\fP\&.
T}
_
T{
\fIds\fP
T}	T{
Scale rate factor [ppm/year]. \fIOptional\fP\&.
T}
_
T{
\fIdrx\fP
T}	T{
Rotation rate of the x\-axis [arc seconds/year]. \fIOptional\fP\&.
T}
_
T{
\fIdry\fP
T}	T{
Rotation rate of the y\-axis [arc seconds/year]. \fIOptional\fP\&.
T}
_
T{
\fIdrz\fP
T}	T{
Rotation rate of the y\-axis [arc seconds/year]. \fIOptional\fP\&.
T}
_
T{
\fIt_epoch\fP
T}	T{
Central epoch of transformation. [decimalyear]. Only used in
spatiotemporal transformations. \fIOptional\fP\&.
T}
_
T{
\fIt_obs\fP
T}	T{
Observation time of coordinate(s). Mostly useful in 2D and 3D
transformations. [decimalyear]. \fIOptional\fP\&.
T}
_
T{
\fIexact\fP
T}	T{
Use exact transformation equations. \fIOptional\fP\&.
T}
_
T{
\fItranspose\fP
T}	T{
Transpose rotation matrix. \fIOptional\fP\&.
T}
_
.TE
.sp
The Helmert transform, in all it’s various incarnations, is used to perform reference
frame shifts. The transformation operates in cartesian space. It can be used to transform
planar coordinates from one datum to another, transform 3D cartesian
coordinates from one static reference frame to another or it can be used to do fully
kinematic transformations from global reference frames to local static frames.
.sp
All of the parameters described in the table above are marked as optional. This is true
as long as at least one parameter is defined in the setup of the transformation.
The behaviour of the transformation depends on which parameters are used in the setup.
For instance, if a rate of change parameter is specified a kinematic version of the
transformation is used.
.sp
The kinematic transformations require an observation time of the coordinate, as well
as a central epoch for the transformation. The latter is usually documented
alongside the rest of the transformation parameters for a given transformation.
The central epoch is controlled with the parameter \fIt_epoch\fP\&. The observation
time can either by stated as part of the coordinate when using PROJ’s
4D\-functionality or it can be controlled in the transformation setup by the
parameter \fIt_obs\fP\&. When \fIt_obs\fP is specified, all transformed coordinates are
treated as if they have the same observation time.
.SS Examples
.sp
Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=helmert ellps=GRS80 x=\-9597.3572 y=.6112
             s=0.304794780637 theta=\-1.244048
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=helmert ellps=GRS80 x=0.67678    y=0.65495   z=\-0.52827
            rx=\-0.022742 ry=0.012667 rz=0.022704  s=\-0.01070
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Transformation from \fIITRF2000@2017.0\fP  to \fIITRF93@2017.0\fP using 15 parameters:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=helmert ellps=GRS80
     x=0.0127     y=0.0065     z=\-0.0209  s=0.00195
     dx=\-0.0029   dy=\-0.0002   dz=\-0.0006 ds=0.00001
     rx=\-0.00039  ry=0.00080   rz=\-0.00114
     drx=\-0.00011 dry=\-0.00019 drz=0.00007
     epoch=1988.0 tobs=2017.0    transpose
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Mathematical description
.sp
In the notation used below, \hat{P} is the rate of change of a given transformation
parameter P\&. \dot{P} is the kinematically adjusted version of P,
described by
.sp
.ce

.ce 0
.sp
where t is the observation time of the coordinate and t_{central} is
the central epoch of the transformation. Equation \fI\%(1)\fP can be used to
propagate all transformation parameters in time.
.sp
Superscripts of vectors denote the reference frame the coordinates in the vector belong to.
.SS 2D Helmert
.sp
The simplest version of the Helmert transform is the 2D case. In the 2\-dimensional
case only the horizontal coordinates are changed. The coordinates can be
translated, rotated and scale. Translation is controlled with the \fIx\fP and \fIy\fP
parameters. The rotation is determined by \fItheta\fP and the scale is controlled with
the \fIs\fP parameters.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The scaling parameter \fIs\fP is unitless for the 2D Helmert, as opposed to the
3D version where the scaling parameter is given in units of ppm.
.UNINDENT
.UNINDENT
.sp
Mathematically the 2D Helmert is described as:
.sp
.ce

.ce 0
.sp
\fI\%(2)\fP can be extended to a time\-varying kinematic version by
adjusting the parameters with \fI\%(1)\fP to \fI\%(2)\fP, which yields
the kinematic 2D Helmert transform:
.sp
.ce

.ce 0
.sp
All parameters in \fI\%(3)\fP are determined by the use of \fI\%(1)\fP,
which applies the rate of change to each individual parameter for a given
timespan between t and t_{central}\&.
.SS 3D Helmert
.sp
The general form of the 3D Helmert is
.sp
.ce

.ce 0
.sp
Where T is a vector consisting of the three translation parameters, s
is the scaling factor and \mathbf{R} is a rotation matrix. V^A and
V^B are coordinate vectors, with V^A being the input coordinate and
V^B is the output coordinate.
.sp
The rotation matrix is composed of three rotation matrices, one for each axis:
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
.ce

.ce 0
.sp
The three rotation matrices can be combined in one:
.sp
.ce

.ce 0
.sp
For \mathbf{R}, this yields:
.sp
.ce

.ce 0
.sp
Using the small angle approxition the rotation matrix can be simplified to
.sp
.ce

.ce 0
.sp
Which allow us to express the most common version of the Helmert transform,
using the approximated rotation matrix:
.sp
.ce

.ce 0
.sp
If the rotation matrix is transposed the transformation is effectively reversed.
This is cause for some confusion since there is no correct way of defining the
rotation matrix. Two conventions exists and they seem to be equally popular.
In PROJ the rotation matrix can be transposed by adding the \fItranspose\fP flag in
the transformation setup.
.sp
Applying \fI\%(1)\fP we get the kinematic version of the approximated
3D Helmert:
.sp
.ce

.ce 0
.sp
The Helmert transformation can be applied without using the rotation parameters,
in which case it becomes a simple translation of the origin of the coordinate
system. When using the Helmert in this version equation \fI\%(4)\fP
simplifies to:
.sp
.ce

.ce 0
.sp
That after application of \fI\%(1)\fP has the following kinematic
counterpart:
.sp
.ce

.ce 0
.SS Molodensky transform
.sp
The Molodensky transformation resembles a Helmert with zero
rotations and a scale of unity, but converts directly from geodetic coordinates to
geodetic coordinates, without the intermediate shifts to and from cartesian
geocentric coordinates, associated with the Helmert transformation.
The Molodensky transformation is simple to implement and to parameterize, requiring
only the 3 shifts between the input and output frame, and the corresponding
differences between the semimajor axes and flattening parameters of the reference
ellipsoids. Due to its algorithmic simplicity, it was popular prior to the
ubiquity of digital computers. Today, it is mostly interesting for historical
reasons, but nevertheless indispensable due to the large amount of data that has
already been transformed that way [EversKnudsen2017]\&.
.TS
center;
|l|l|.
_
T{
\fBInput type\fP
T}	T{
Geodetic coordinates.
T}
_
T{
\fBOutput type\fP
T}	T{
Geodetic coordinates.
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+da\fP
T}	T{
Difference in semimajor axis of the defining ellipsoids.
T}
_
T{
\fI+df\fP
T}	T{
Difference in flattening of the defining ellipsoids.
T}
_
T{
\fI+dx\fP
T}	T{
Offset of the X\-axes of the defining ellipsoids.
T}
_
T{
\fI+dy\fP
T}	T{
Offset of the Y\-axes of the defining ellipsoids.
T}
_
T{
\fI+dz\fP
T}	T{
Offset of the Z\-axes of the defining ellipsoids.
T}
_
T{
\fI+ellps\fP
T}	T{
Ellipsoid definition of source coordinates.
Any specification can be used (e.g. \fI+a\fP, \fI+rf\fP, etc).
If not specified, default ellipsoid is used.
T}
_
T{
\fI+abridged\fP
T}	T{
Use the abridged version of the Molodensky transform.
Optional.
T}
_
.TE
.sp
The Molodensky transform can be used to perform a datum shift from coordinate
(\phi_1, \lambda_1, h_1) to (\phi_2, \lambda_2, h_2) where the two
coordinates are referenced to different ellipsoids. This is based on three
assumptions:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
The cartesian axes, X, Y, Z,  of the two ellipsoids are parallel.
.IP 2. 3
The offset, \delta X, \delta Y, \delta Z,  between the two ellipsoid
are known.
.IP 3. 3
The characteristics of the two ellipsoids, expressed as the difference in
semimajor axis (\delta a) and flattening (\delta f),  are known.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The Molodensky transform is mostly used for transforming between old systems
dating back to the time before computers. The advantage of the Molodensky transform
is that it is fairly simple to compute by hand. The ease of computation come at the
cost of limited accuracy.
.sp
A derivation of the mathematical formulas for the Molodensky transform can be found
in [Deakin2004]\&.
.SS Examples
.sp
The abridged Molodensky:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=molodensky a=6378160 rf=298.25 da=\-23 df=\-8.120449e\-8  dx=\-134 dy=\-48 dz=149 abridged
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The same transformation using the standard Molodensky:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj=molodensky a=6378160 rf=298.25 da=\-23 df=\-8.120449e\-8  dx=\-134 dy=\-48 dz=149
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Horizontal grid shift
.sp
Change of horizontal datum by grid shift.
.TS
center;
|l|l|.
_
T{
\fBInput type\fP
T}	T{
Geodetic coordinates.
T}
_
T{
\fBOutput type\fP
T}	T{
Geodetic coordinates.
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+grids\fP
T}	T{
Comma\-separated list of grids to load.
T}
_
.TE
.sp
The horizontal grid shift is done by offsetting the planar input coordinates by
a specific amount determined by the loaded grids. The simplest use case of the
horizontal grid shift is applying a single grid:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+hgridshift +grids=nzgr2kgrid0005.gsb
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
More than one grid can be loaded at the same time, for instance in case the
dataset needs to be transformed spans several countries. In this example grids
of the continental US, Alaska and Canada is loaded at the same time:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB@\fP in the above example states that the grid is optional, in case the grid
is not found in the PROJ search path. The list of grids is prioritized so that
grids in the start of the list takes precedence over the grids in the back of the
list.
.sp
PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details
about all three formats can be found in the GDAL documentation. GDAL reads and
writes all three formats. Using GDAL for construction of new grids is recommended.
.SS Vertical grid shift
.sp
Change Vertical datum change by grid shift
.TS
center;
|l|l|.
_
T{
\fBInput type\fP
T}	T{
Geodetic coordinates (horizontal), meters (vertical).
T}
_
T{
\fBOutput type\fP
T}	T{
Geodetic coordinates (horizontal), meters (vertical).
T}
_
T{
\fBOptions\fP
T}
_
T{
\fI+grids\fP
T}	T{
Comma\-separated list of grids to load.
T}
_
.TE
.sp
The vertical grid shift is done by offsetting the vertical input coordinates by
a specific amount determined by the loaded grids. The simplest use case of the
horizontal grid shift is applying a single grid. Here we change the vertical
reference from the ellipsoid to the global geoid model, EGM96:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+vgridshift +grids=egm96_16.gtx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
More than one grid can be loaded at the same time, for instance in the case where
a better geoid model than the global is available for a certain area. Here the
gridshift is set up so that the local DVR90 geoid model takes precedence over
the global model:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+vgridshift +grids=@dvr90.gtx,egm96_16.gtx
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fB@\fP in the above example states that the grid is optional, in case the grid
is not found in the PROJ search path. The list of grids is prioritized so that
grids in the start of the list takes precedence over the grids in the back of the
list.
.sp
PROJ supports the GTX file format for vertical grid corrections. Details
about all the format can be found in the GDAL documentation. GDAL both reads and
writes the format. Using GDAL for construction of new grids is recommended.
.SS The pipeline operator
.sp
Construct complex operations by daisy\-chaining operations in a sequential pipeline.
.TS
center;
|l|l|.
_
T{
\fBInput type\fP
T}	T{
Any.
T}
_
T{
\fBOutput type\fP
T}	T{
Any.
T}
_
T{
\fBOptions\fP
T}
_
T{
\fIstep\fP
T}	T{
Separate each step in a pipeline.
T}
_
T{
\fIinv\fP
T}	T{
Invert a step in a pipeline.
T}
_
.TE
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
See the section on transformation for a more thorough introduction
to the concept of transformation pipelines in PROJ.
.UNINDENT
.UNINDENT
.sp
With the pipeline operation it is possible to perform several operations after each
other on the same input data. This feature makes it possible to create transformations
that are made up of more than one operation, e.g. performing a datum shift and then
applying a suitable map projection. Theoretically any transformation between two
coordinate reference systems is possible to perform using the pipeline operation,
provided that the necessary coordinate operations in each step is available in PROJ.
.sp
A pipeline is made up of a number of steps, with each step being a coordinate operation
in itself. By connecting these individual steps sequentially we end up with a concatenated
coordinate operation. An example of this is a transformation from geodetic coordinates
on the GRS80 ellipsoid to a projected system where the east\-west and north\-east axes has
been swapped:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline +ellps=GRS80 +step +proj=merc +step +proj=axisswap +order=2,1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Here the first step is applying the merc projection and the second step is
applying the axisswap conversion. Note that the \fI+ellps=GRS80\fP is specified
before the first occurrence of \fI+step\fP\&. This means that the GRS80 ellipsoid is used
in both steps, since any parameter stated before the first occurrence of \fI+step\fP is
treated as a global parameter and is transferred to each individual steps.
.SS Rules for pipelines
.sp
\fB1. Pipelines must consist of at least one step.\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will result in an error.
.sp
\fB2. Pipelines can only be nested if the nested pipeline is defined in an init\-file.\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline
+step +proj=pipeline +step +proj=merc +step +proj=axisswap +order=2,1
+step +proj=unitconvert +xy_in=m +xy_out=us\-ft
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Results in an error, while
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline
+step +init=predefined_pipelines:projectandswap
+step +proj=unitconvert +xy_in=m +xy_out=us\-ft
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
does not.
.sp
\fB3. Pipelines without a forward path can’t be constructed.\fP
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline +step +inv +proj=urm5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will result in an error since urm5 does not have an inverse operation defined.
.sp
\fB4. Parameters added before the first \(ga+step\(ga are global and will be applied to all steps.\fP
.sp
In the following the GRS80 ellipsoid will be applied to all steps.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=pipeline +ellps=GRS80
+step +proj=cart
+step +proj=helmert +x=10 +y=3 +z=1
+step +proj=cart +inv
+step +proj=merc
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Resource files
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Resource files\fP
.INDENT 2.0
.IP \(bu 2
\fI\%External resources\fP
.IP \(bu 2
\fI\%Transformation grids\fP
.IP \(bu 2
\fI\%Init files\fP
.IP \(bu 2
\fI\%The defaults file\fP
.UNINDENT
.UNINDENT
.sp
A number of files containing preconfigured transformations and default parameters
for certain projections are bundled with the PROJ distribution. Init files
contains preconfigured proj\-strings for various coordinate reference systems
and the defaults file contains default values for parameters of select
projections.
.sp
In addition to the bundled init\-files the PROJ.4 project also distribute a number
of packages containing transformation grids and additional init\-files not included
in the main PROJ package.
.SS External resources
.sp
For a functioning PROJ installation of the
\fI\%proj\-datumgrid\fP is needed. If you
have installed PROJ from a package system chances are that this will already be
done for you. The \fIproj\-datumgrid\fP package provides transformation grids that
are essential for many of the predefined transformations in PROJ. Which grids
are included in the package can be seen on the
\fI\%proj\-datumgrid repository\fP as well
as descriptions of those grids.
.sp
In addition to the default \fIproj\-datumgrid\fP package regional packages are also
distributed. These include grids and init\-files that are valid within the given
region. The packages are divided into geographical regions in order to keep the
needed disk space by PROJ at a minimum. Some users may have a use for resource
files covering several regions in which case they can download more than one.
.sp
At the moment three regional resource file packages are distributed:
.INDENT 0.0
.IP \(bu 2
\fI\%Europe\fP
.IP \(bu 2
\fI\%Oceania\fP
.IP \(bu 2
\fI\%North America\fP
.UNINDENT
.sp
Click the links to jump to the relevant README files for each package. Details
on the content of the packages maintained there.
.sp
Links to the resource packages can be found in the download section\&.
.SS Transformation grids
.sp
Grid files are important for shifting and transforming between datums.
.sp
PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections and
the GTX file format for vertical corrections. Details about the formats can be
found in the \fI\%GDAL documentation\fP\&. GDAL reads and writes
all formats. Using GDAL for construction of new grids is recommended.
.sp
Below is a given a list of grid resources for various countries which are not
included in the grid distributions mentioned above.
.SS Free grids
.sp
Below is a list of grids distributed under a free and open license.
.SS Switzerland
.sp
Background in ticket \fI\%#145\fP
.sp
We basically have two shift grids available. An official here:
.sp
\fI\%Swiss CHENyx06 dataset in NTv2 format\fP
.sp
And a derived in a temporary location which is probably going to disappear soon.
.sp
Main problem seems to be there’s no mention of distributivity of the grid from
the official website.  It just tells: “you can use freely”.  The “contact” link
is also broken, but maybe someone could make a phone call to ask for rephrasing
that.
.SS Hungary
.sp
\fI\%Hungarian grid\fP ETRS89 \- HD72/EOV (epsg:23700), both horizontal and elevation grids
.SS Non\-Free Grids
.sp
Not all grid shift files have licensing that allows them to be freely
distributed, but can be obtained by users through free and legal methods.
.SS Canada NTv2.0
.sp
Although NTv1 grid shifts are provided freely with PROJ, the higher\-quality
NTv2.0 file needs to be downloaded from Natural Resources Canada. More info:
\fI\%http://www.geod.nrcan.gc.ca/tools\-outils/ntv2_e.php\fP\&.
.sp
Procedure:
.INDENT 0.0
.IP 1. 3
Visit the \fI\%NTv2\fP, and register/login
.IP 2. 3
Follow the Download NTv2 link near the bottom of the page.
.IP 3. 3
Unzip \fIntv2_100325.zip\fP (or similar), and move the grid shift file \fINTV2_0.GSB\fP to the proj directory (be sure to change the name to lowercase for consistency)
* e.g.: \fImv NTV2_0.GSB /usr/local/share/proj/ntv2_0.gsb\fP
.IP 4. 3
.INDENT 3.0
.TP
.B Test it using:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb +to +proj=latlong +ellps=GRS80 +datum=NAD83
\-111 50
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
111d0\(aq3.006"W   50d0\(aq0.103"N 0.000  # correct answer
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Australia
.sp
\fI\%Geocentric Datum of Australia AGD66/AGD84\fP
.SS Canada
.sp
\fI\%Canadian NTv2 grid shift binary\fP for NAD27 <=> NAD83.
.SS Germany
.sp
\fI\%German BeTA2007 DHDN GK3 => ETRS89/UTM\fP
.SS Great Britain
.sp
\fI\%Great Britain’s OSTN15_NTv2: OSGB 1936 => ETRS89\fP
.sp
\fI\%Great Britain’s OSTN02_NTv2: OSGB 1936 => ETRS89\fP
.SS Austria
.sp
\fI\%Austrian Grid\fP for MGI
.SS Spain
.sp
\fI\%Spanish grids\fP for ED50.
.SS Portugal
.sp
\fI\%Portuguese grids\fP for ED50, Lisbon 1890, Lisbon 1937 and Datum 73
.SS Brazil
.sp
\fI\%Brazilian grids\fP for datums Corrego Alegre 1961, Corrego Alegre 1970\-72, SAD69 and SAD69(96)
.SS South Africa
.sp
\fI\%South African grid\fP (Cape to Hartebeesthoek94 or WGS84)
.SS Netherlands
.sp
\fI\%Dutch grid\fP (Registration required before download)
.SS HARN
.sp
With the support of \fI\%i\-cubed\fP, Frank Warmerdam has
written tools to translate the HPGN grids from NOAA/NGS from \fB\&.los/.las\fP format
into NTv2 format for convenient use with PROJ.  This project included
implementing a \fI\%\&.los/.las reader\fP
for GDAL, and an \fI\%NTv2 reader/writer\fP\&.
Also, a script to do the bulk translation was implemented in
\fI\%https://github.com/OSGeo/gdal/tree/trunk/gdal/swig/python/samples/loslas2ntv2.py\fP\&.
The command to do the translation was:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
loslas2ntv2.py \-auto *hpgn.los
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As GDAL uses NAD83/WGS84 as a pivot datum, the sense of the HPGN datum shift offsets were negated to map from HPGN to NAD83 instead of the other way.  The files can be used with PROJ like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +datum=NAD83
      +to +proj=latlong +nadgrids=./azhpgn.gsb +ellps=GRS80
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# input:
\-112 34
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# output:
111d59\(aq59.996"W 34d0\(aq0.006"N \-0.000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This was confirmed against the \fI\%NGS HPGN calculator\fP\&.
.sp
The grids are available at \fI\%http://download.osgeo.org/proj/hpgn_ntv2.zip\fP
.SS HTDP
.sp
This page documents use of the \fIcrs2crs2grid.py\fP script and the HTDP
(Horizontal Time Dependent Positioning) grid shift modelling program from
NGS/NOAA to produce PROJ compatible grid shift files for fine grade
conversions between various NAD83 epochs and WGS84.  Traditionally PROJ has
treated NAD83 and WGS84 as equivalent and failed to distinguish between
different epochs or realizations of those datums.  At the scales of much
mapping this is adequate but as interest grows in high resolution imagery and
other high resolution mapping this is inadequate.  Also, as the North American
crust drifts over time the displacement between NAD83 and WGS84 grows (more
than one foot over the last two decades).
.SS Getting and building HTDP
.sp
The HTDP modelling program is in written FORTRAN.  The source and documentation
can be found on the HTDP page at \fI\%http://www.ngs.noaa.gov/TOOLS/Htdp/Htdp.shtml\fP
.sp
On linux systems it will be necessary to install \fIgfortran\fP or some FORTRAN
compiler.  For ubuntu something like the following should work.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
apt\-get install gfortran
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To compile the program do something like the following to produce the binary “htdp” from the source code.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gfortran htdp.for \-o htdp
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting crs2crs2grid.py
.sp
The \fIcrs2crs2grid.py\fP script can be found at
\fI\%https://github.com/OSGeo/gdal/tree/trunk/gdal/swig/python/samples/crs2crs2grid.py\fP
.sp
It depends on having the GDAL Python bindings operational.  If they are not
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Traceback (most recent call last):
  File "./crs2crs2grid.py", line 37, in <module>
    from osgeo import gdal, gdal_array, osr
ImportError: No module named osgeo
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Usage
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
   crs2crs2grid.py
           <src_crs_id> <src_crs_date> <dst_crs_id> <dst_crs_year>
           [\-griddef <ul_lon> <ul_lat> <ll_lon> <ll_lat> <lon_count> <lat_count>]
           [\-htdp <path_to_exe>] [\-wrkdir <dirpath>] [\-kwf]
           \-o <output_grid_name>

\-griddef: by default the following values for roughly the continental USA
          at a six minute step size are used:
          \-127 50 \-66 25 251 611
\-kwf: keep working files in the working directory for review.
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
crs2crs2grid.py 29 2002.0 8 2002.0 \-o nad83_2002.ct2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The goal of \fIcrs2crs2grid.py\fP is to produce a grid shift file for a designated
region.  The region is defined using the \fI\-griddef\fP switch.  When missing a
continental US region is used.  The script creates a set of sample points for
the grid definition, runs the “htdp” program against it and then parses the
resulting points and computes a point by point shift to encode into the final
grid shift file.  By default it is assumed the \fIhtdp\fP program will be in the
executable path.  If not, please provide the path to the executable using the
\fI\-htdp\fP switch.
.sp
The \fIhtdp\fP program supports transformations between many CRSes and for each (or
most?) of them you need to provide a date at which the CRS is fixed.  The full
set of CRS Ids available in the HTDP program are:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
 1...NAD_83(2011) (North America tectonic plate fixed)
 29...NAD_83(CORS96)  (NAD_83(2011) will be used)
 30...NAD_83(2007)    (NAD_83(2011) will be used)
 2...NAD_83(PA11) (Pacific tectonic plate fixed)
 31...NAD_83(PACP00)  (NAD 83(PA11) will be used)
 3...NAD_83(MA11) (Mariana tectonic plate fixed)
 32...NAD_83(MARP00)  (NAD_83(MA11) will be used)

 4...WGS_72                             16...ITRF92
 5...WGS_84(transit) = NAD_83(2011)     17...ITRF93
 6...WGS_84(G730) = ITRF92              18...ITRF94 = ITRF96
 7...WGS_84(G873) = ITRF96              19...ITRF96
 8...WGS_84(G1150) = ITRF2000           20...ITRF97
 9...PNEOS_90 = ITRF90                  21...IGS97 = ITRF97
10...NEOS_90 = ITRF90                   22...ITRF2000
11...SIO/MIT_92 = ITRF91                23...IGS00 = ITRF2000
12...ITRF88                             24...IGb00 = ITRF2000
13...ITRF89                             25...ITRF2005
14...ITRF90                             26...IGS05 = ITRF2005
15...ITRF91                             27...ITRF2008
                                        28...IGS08 = ITRF2008
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The typical use case is mapping from NAD83 on a particular date to WGS84 on
some date.  In this case the source CRS Id “29” (NAD_83(CORS96)) and the
destination CRS Id is “8 (WGS_84(G1150)).  It is also necessary to select the
source and destination date (epoch).  For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
crs2crs2grid.py 29 2002.0 8 2002.0 \-o nad83_2002.ct2
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The output is a CTable2 format grid shift file suitable for use with PROJ
(4.8.0 or newer).  It might be utilized something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +ellps=GRS80 +nadgrids=./nad83_2002.ct2 +to +proj=latlong +datum=WGS84
.ft P
.fi
.UNINDENT
.UNINDENT
.SS See Also
.INDENT 0.0
.IP \(bu 2
\fI\%http://www.ngs.noaa.gov/TOOLS/Htdp/Htdp.shtml\fP \- NGS/NOAA page about the HTDP
model and program.  Source for the HTDP program can be downloaded from here.
.UNINDENT
.SS Init files
.sp
Init files are used for preconfiguring proj\-strings for often used
transformations, such as those found in the EPSG database. Most init files contain
transformations from a given coordinate reference system to WGS84. This makes
it easy to transformations between any two coordinate reference systems with
\fBcs2cs\fP\&. Init files can however contain any proj\-string and don’t necessarily
have to follow the \fIcs2cs\fP paradigm where WGS84 is used as a pivot datum. The
ITRF init file is a good example of that.
.sp
A number of init files come pre\-bundled with PROJ but it is also possible to
add your own custom init files. PROJ looks for the init files in the directory
listed in the \fBPROJ_LIB\fP environment variable.
.sp
The format of init files made up of a identifier in angled brackets and a
proj\-string:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<3819> +proj=longlat +ellps=bessel
       +towgs84=595.48,121.69,515.35,4.115,\-2.9383,0.853,\-3.408 +no_defs <>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The above example is the first entry from the \fBepsg\fP init file. So, this is the
coordinate reference system with ID 3819 in the EPSG database. Comments can be
inserted by prefixing them with a “#”. With version 4.10.0 a new special metadata
entry is now accepted in init files. It can be parsed with a function from the public
API. The metadata entry in the epsg init file looks like this at the time of writing:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<metadata> +version=9.0.0 +origin=EPSG +lastupdate=2017\-01\-10
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Pre\-configured proj\-strings from init files are used in the following way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ cs2cs \-v +proj=latlong +to +init=epsg:3819
# \-\-\-\- From Coordinate System \-\-\-\-
#Lat/long (Geodetic alias)
#
# +proj=latlong +ellps=WGS84
# \-\-\-\- To Coordinate System \-\-\-\-
#Lat/long (Geodetic alias)
#
# +init=epsg:3819 +proj=longlat +ellps=bessel
# +towgs84=595.48,121.69,515.35,4.115,\-2.9383,0.853,\-3.408 +no_defs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is possible to override parameters when using \fB+init\fP\&. Just add the parameter
to the proj\-string alongside the \fB+init\fP parameter. For instance by overriding
the ellipsoid as in the following example
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+init=epsg:25832 +ellps=intl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
where the Hayford ellipsoid is used instead of the predefined GRS80 ellipsoid.
It is also possible to add additional parameters not specified in the init file,
for instance by adding an observation epoch when transforming from ITRF2000 to
ITRF2005:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+init=ITRF2000:ITRF2005 +tobs=2010.5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
which then expands to
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=helmert +x=\-0.0001 +y=0.0008 +z=0.0058 +s=\-0.0004
+dx=0.0002 +dy=\-0.0001 +dz=0.0018 +ds=\-0.000008
+epoch=2000.0 +transpose
+tobs=2010.5
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Below is a list of the init files that are packaged with PROJ.
.INDENT 0.0
.INDENT 3.5
.TS
center;
|l|l|.
_
T{
Name
T}	T{
Description
T}
_
T{
esri
T}	T{
Auto\-generated mapping from Esri projection index. Not
maintained any more
T}
_
T{
epsg
T}	T{
EPSG database
T}
_
T{
GL27
T}	T{
Great Lakes Grids
T}
_
T{
IGNF
T}	T{
French coordinate systems supplied by the IGNF
T}
_
T{
ITRF2000
T}	T{
Full set of transformation parameters between ITRF2000 and other
ITRF’s
T}
_
T{
ITRF2008
T}	T{
Full set of transformation parameters between ITRF2008 and other
ITRF’s
T}
_
T{
ITRF2014
T}	T{
Full set of transformation parameters between ITRF2014 and other
ITRF’s
T}
_
T{
nad27
T}	T{
State plane coordinate systems, North American Datum 1927
T}
_
T{
nad83
T}	T{
State plane coordinate systems, North American Datum 1983
T}
_
.TE
.UNINDENT
.UNINDENT
.SS The defaults file
.sp
The \fBproj_def.dat\fP file supplies default parameters for PROJ. It uses the same
syntax as the init files described above. The identifiers in the defaults file
describe to what the parameters should apply. If the \fB<general>\fP identifier is
used, then all parameters in that section applies for all proj\-strings. Otherwise
the identifier is connected to a specific projection. With the defaults file
supplied with PROJ the default ellipsoid is set to WGS84 (for all proj\-strings).
Apart from that only the Albers Equal Area,
Lambert Conic Conformal and the
Lagrange projections have default parameters.
Defaults can be ignored by adding the \fB+no_def\fP parameter to a proj\-string.
.SS Geodesic calculations
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Geodesic calculations\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Introduction\fP
.IP \(bu 2
\fI\%Solution of geodesic problems\fP
.IP \(bu 2
\fI\%Additional properties\fP
.IP \(bu 2
\fI\%Multiple shortest geodesics\fP
.IP \(bu 2
\fI\%Background\fP
.UNINDENT
.UNINDENT
.SS Introduction
.sp
Consider a ellipsoid of revolution with equatorial radius a, polar
semi\-axis b, and flattening f=(a−b)/a\&.  Points on
the surface of the ellipsoid are characterized by their latitude \phi
and longitude \lambda\&.  (Note that latitude here means the
\fIgeographical latitude\fP, the angle between the normal to the ellipsoid
and the equatorial plane).
.sp
The shortest path between two points on the ellipsoid at
(\phi_1,\lambda_1) and (\phi_2,\lambda_2)
is called the geodesic.  Its length is
s_{12} and the geodesic from point 1 to point 2 has forward
azimuths \alpha_1 and \alpha_2 at the two end
points.  In this figure, we have \lambda_{12}=\lambda_2-\lambda_1\&.
.INDENT 0.0
.INDENT 3.5
.UNINDENT
.UNINDENT
.sp
A geodesic can be extended indefinitely by requiring that any
sufficiently small segment is a shortest path; geodesics are also the
straightest curves on the surface.
.SS Solution of geodesic problems
.sp
Traditionally two geodesic problems are considered:
.INDENT 0.0
.IP \(bu 2
the direct problem — given \phi_1,
\lambda_1, \alpha_1, s_{12},
determine \phi_2, \lambda_2, \alpha_2\&.
.IP \(bu 2
the inverse problem — given  \phi_1,
\lambda_1,  \phi_2, \lambda_2,
determine s_{12}, \alpha_1,
\alpha_2\&.
.UNINDENT
.sp
PROJ incorporates \fI\%C library for Geodesics\fP from \fI\%GeographicLib\fP\&.  This library provides
routines to solve the direct and inverse geodesic problems.  Full double
precision accuracy is maintained provided that
\lvert f\rvert<\frac1{50}\&.  Refer
to the
.INDENT 0.0
.INDENT 3.5
\fI\%application programming interface\fP
.UNINDENT
.UNINDENT
.sp
for full documentation.  A brief summary of the routines is given in
geodesic(3).
.sp
The interface to the geodesic routines differ in two respects from the
rest of PROJ:
.INDENT 0.0
.IP \(bu 2
angles (latitudes, longitudes, and azimuths) are in degrees (instead
of in radians);
.IP \(bu 2
the shape of ellipsoid is specified by the flattening f; this can
be negative to denote a prolate ellipsoid; setting f=0 corresponds
to a sphere, in which case the geodesic becomes a great circle.
.UNINDENT
.sp
PROJ also includes a command line tool, geod(1), for performing
simple geodesic calculations.
.SS Additional properties
.sp
The routines also calculate several other quantities of interest
.INDENT 0.0
.IP \(bu 2
S_{12} is the area between the geodesic from point 1 to
point 2 and the equator; i.e., it is the area, measured
counter\-clockwise, of the quadrilateral with corners
(\phi_1,\lambda_1), (0,\lambda_1),
(0,\lambda_2), and
(\phi_2,\lambda_2)\&.  It is given in
meters\s-2\u2\d\s0\&.
.IP \(bu 2
m_{12}, the reduced length of the geodesic is defined such
that if the initial azimuth is perturbed by d\alpha_1
(radians) then the second point is displaced by m_{12}\,d\alpha_1
in the direction perpendicular to the
geodesic.  m_{12} is given in meters.  On a curved surface
the reduced length obeys a symmetry relation, m_{12}+m_{21}=0\&.
On a flat surface, we have m_{12}=s_{12}\&.
.IP \(bu 2
M_{12} and M_{21} are geodesic scales.  If two
geodesics are parallel at point 1 and separated by a small distance
:math\(gadt\(ga, then they are separated by a distance M_{12}\,dt at
point 2.  M_{21} is defined similarly (with the geodesics
being parallel to one another at point 2).  M_{12} and
M_{21} are dimensionless quantities.  On a flat surface,
we have M_{12}=M_{21}=1\&.
.IP \(bu 2
\sigma_{12} is the arc length on the auxiliary sphere.
This is a construct for converting the problem to one in spherical
trigonometry.  The spherical arc length from one equator crossing to
the next is always 180^\circ\&.
.UNINDENT
.sp
If points 1, 2, and 3 lie on a single geodesic, then the following
addition rules hold:
.INDENT 0.0
.IP \(bu 2
s_{13}=s_{12}+s_{23},
.IP \(bu 2
\sigma_{13}=\sigma_{12}+\sigma_{23},
.IP \(bu 2
S_{13}=S_{12}+S_{23},
.IP \(bu 2
m_{13}=m_{12}M_{23}+m_{23}M_{21},
.IP \(bu 2
M_{13}=M_{12}M_{23}-(1-M_{12}M_{21})m_{23}/m_{12},
.IP \(bu 2
M_{31}=M_{32}M_{21}-(1-M_{23}M_{32})m_{12}/m_{23}\&.
.UNINDENT
.SS Multiple shortest geodesics
.sp
The shortest distance found by solving the inverse problem is
(obviously) uniquely defined.  However, in a few special cases there are
multiple azimuths which yield the same shortest distance.  Here is a
catalog of those cases:
.INDENT 0.0
.IP \(bu 2
\phi_1=-\phi_2 (with neither point at
a pole).  If \alpha_1=\alpha_2, the geodesic
is unique.  Otherwise there are two geodesics and the second one is
obtained by setting
[\alpha_1,\alpha_2]\leftarrow[\alpha_2,\alpha_1],
[M_{12},M_{21}]\leftarrow[M_{21},M_{12}],
S_{12}\leftarrow-S_{12}\&.
(This occurs when the longitude difference is near \pm180^\circ
for oblate ellipsoids.)
.IP \(bu 2
\lambda_2=\lambda_1\pm180^\circ (with
neither point at a pole).  If \alpha_1=0^\circ or
\pm180^\circ, the geodesic is unique.  Otherwise there are two
geodesics and the second one is obtained by setting
[\alpha_1,\alpha_2]\leftarrow[-\alpha_1,-\alpha_2],
S_{12}\leftarrow-S_{12}\&.  (This occurs when
\phi_2 is near -\phi_1 for prolate
ellipsoids.)
.IP \(bu 2
Points 1 and 2 at opposite poles.  There are infinitely many
geodesics which can be generated by setting
[\alpha_1,\alpha_2]\leftarrow[\alpha_1,\alpha_2]+[\delta,-\delta],
for arbitrary \delta\&.
(For spheres, this prescription applies when points 1 and 2 are
antipodal.)
.IP \(bu 2
s_{12}=0 (coincident points).  There are infinitely many
geodesics which can be generated by setting
[\alpha_1,\alpha_2]\leftarrow[\alpha_1,\alpha_2]+[\delta,\delta],
for arbitrary \delta\&.
.UNINDENT
.SS Background
.sp
The algorithms implemented by this package are given in [Karney2013]
and are based on [Bessel1825] and [Helmert1880]; the algorithm for
areas is based on [Danielsen1989]\&.  These improve on the work of
[Vincenty1975] in the following respects:
.INDENT 0.0
.IP \(bu 2
The results are accurate to round\-off for terrestrial ellipsoids (the
error in the distance is less then 15 nanometers, compared to 0.1 mm
for Vincenty).
.IP \(bu 2
The solution of the inverse problem is always found.  (Vincenty’s
method fails to converge for nearly antipodal points.)
.IP \(bu 2
The routines calculate differential and integral properties of a
geodesic.  This allows, for example, the area of a geodesic polygon to
be computed.
.UNINDENT
.sp
Additional background material is provided in [GeodesicBib],
[GeodesicWiki], and [Karney2011]\&.
.SS Development
.sp
These pages are primarily focused towards developers either contributing to the
PROJ project or using the library in their own software.
.SS Quick start
.sp
This is a short introduction to the PROJ API. In the following section we
create a simple program that transforms a geodetic coordinate to UTM and back
again. The program is explained a few lines at a time. The complete program can
be seen at the end of the section.
.sp
See the following sections for more in\-depth descriptions of different parts of
the PROJ API or consult the API reference for specifics.
.sp
Before the PROJ API can be used it is necessary to include the \fBproj.h\fP header
file. Here \fBstdio.h\fP is also included so we can print some text to the screen:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <stdio.h>
#include <proj.h>

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Let’s declare a few variables that’ll be used later in the program. Each variable
will be discussed below.
See the reference for more info on data types\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
PJ_CONTEXT *C;
PJ *P;
PJ_COORD a, b;

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For use in multi\-threaded programs the \fBPJ_CONTEXT\fP threading\-context is used.
In this particular example it is not needed, but for the sake of completeness
it created here. The section on threads discusses
this in detail.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
C = proj_context_create();

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Next we create the \fBPJ\fP transformation object \fBP\fP with the function
\fBproj_create\fP\&. \fBproj_create\fP takes the threading context \fBC\fP created above,
and a proj\-string that defines the desired transformation. Here we transform
from geodetic coordinate to UTM zone 32N.
It is recommended to create one threading\-context per thread used by the program.
This ensures that all \fBPJ\fP objects created in the same context will be sharing
resources such as error\-numbers and loaded grids.
In case the creation of the \fBPJ\fP object fails an error message is displayed and
the program returns. See errorhandling for further
details.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
P = proj_create (C, "+proj=utm +zone=32 +ellps=GRS80");
if (0==P)
    return puts ("Oops"), 0;

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
PROJ uses it’s own data structures for handling coordinates. Here we use a
\fBPJ_COORD\fP which is easily assigned with the function \fBproj_coord\fP\&. Note
that the input values are converted to radians with \fBproj_torad\fP\&. This is
necessary since PROJ is using radians internally. See transformations
for further details.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
a = proj_coord (proj_torad(12), proj_torad(55), 0, 0);

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The coordinate defined above is transformed with \fBproj_trans_coord\fP\&. For this
a \fBPJ\fP object, a transformation direction (either forward or inverse) and the
coordinate is needed. The transformed coordinate is returned in \fBb\fP\&.
Here the forward (\fBPJ_FWD\fP) transformation from geodetic to UTM is made.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
b = proj_trans_coord (P, PJ_FWD, a);
printf ("easting: %g, northing: %g\en", b.en.e, b.en.n);

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The inverse transformation (UTM to geodetic) is done similar to above,
this time using \fBPJ_INV\fP as the direction.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
b = proj_trans_coord (P, PJ_INV, b);
printf ("longitude: %g, latitude: %g\en", b.lp.lam, b.lp.phi);

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Before ending the program the allocated memory needs to be released again:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj_destroy (P);
proj_context_destroy (C); /* may be omitted in the single threaded case */

.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A complete compilable version of the above can be seen here:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <stdio.h>
#include <proj.h>

int main (void) {
    PJ_CONTEXT *C;
    PJ *P;
    PJ_COORD a, b;
    
    /* or you may set C=0 if you are sure you will use PJ objects from only one thread */
    C = proj_context_create();

    P = proj_create (C, "+proj=utm +zone=32 +ellps=GRS80");
    if (0==P)
        return puts ("Oops"), 0;

    /* a coordinate union representing Copenhagen: 55d N, 12d E    */
    /* note: PROJ.4 works in radians, hence the proj_torad() calls */
    a = proj_coord (proj_torad(12), proj_torad(55), 0, 0);

    /* transform to UTM zone 32, then back to geographical */
    b = proj_trans_coord (P, PJ_FWD, a);
    printf ("easting: %g, northing: %g\en", b.en.e, b.en.n);
    b = proj_trans_coord (P, PJ_INV, b);
    printf ("longitude: %g, latitude: %g\en", b.lp.lam, b.lp.phi);

    /* Clean up */
    proj_destroy (P);
    proj_context_destroy (C); /* may be omitted in the single threaded case */
    return 0;
}

.ft P
.fi
.UNINDENT
.UNINDENT
.SS Transformations
.SS Error handling
.SS Threads
.sp
This page is about efforts to make PROJ thread safe.
.SS Key Thread Safety Issues
.INDENT 0.0
.IP \(bu 2
the global pj_errno variable is shared between threads and makes it
essentially impossible to handle errors safely.  Being addressed with the
introduction of the projCtx execution context.
.IP \(bu 2
the datum shift using grid files uses globally shared lists of loaded grid
information. Access to this has been made safe in 4.7.0 with the introduction
of a PROJ mutex used to protect access to these memory structures (see
pj_mutex.c).
.UNINDENT
.SS projCtx
.sp
Primarily in order to avoid having pj_errno as a global variable, a “thread
context” structure has been introduced into a variation of the PROJ API for
the 4.8.0 release.  The pj_init() and pj_init_plus() functions now have context
variations called pj_init_ctx() and pj_init_plus_ctx() which take a projections
context.
.sp
The projections context can be created with pj_ctx_alloc(), and there is a
global default context used when one is not provided by the application.  There
is a pj_ctx_ set of functions to create, manipulate, query, and destroy
contexts.  The contexts are also used now to handle setting debugging mode, and
to hold an error reporting function for textual error and debug messages.   The
API looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
projPJ pj_init_ctx( projCtx, int, char ** );
projPJ pj_init_plus_ctx( projCtx, const char * );

projCtx pj_get_default_ctx(void);
projCtx pj_get_ctx( projPJ );
void pj_set_ctx( projPJ, projCtx );
projCtx pj_ctx_alloc(void);
void    pj_ctx_free( projCtx );
int pj_ctx_get_errno( projCtx );
void pj_ctx_set_errno( projCtx, int );
void pj_ctx_set_debug( projCtx, int );
void pj_ctx_set_logger( projCtx, void (*)(void *, int, const char *) );
void pj_ctx_set_app_data( projCtx, void * );
void *pj_ctx_get_app_data( projCtx );
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multithreaded applications are now expected to create a projCtx per thread
using pj_ctx_alloc().  The context’s error handlers, and app data may be
modified if desired, but at the very least each context has an internal error
value accessed with pj_ctx_get_errno() as opposed to looking at pj_errno.
.sp
Note that pj_errno continues to exist, and it is set by pj_ctx_set_errno() (as
well as setting the context specific error number), but pj_errno still suffers
from the global shared problem between threads and should not be used by
multithreaded applications.
.sp
Note that pj_init_ctx(), and pj_init_plus_ctx() will assign the projCtx to the
created projPJ object.  Functions like pj_transform(), pj_fwd() and pj_inv()
will use the context of the projPJ for error reporting.
.SS src/multistresstest.c
.sp
A small multi\-threaded test program has been written (src/multistresstest.c)
for testing multithreaded use of PROJ.  It performs a series of reprojections
to setup a table expected results, and then it does them many times in several
threads to confirm that the results are consistent.  At this time this program
is not part of the builds but it can be built on linux like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gcc \-g multistresstest.c .libs/libproj.so \-lpthread \-o multistresstest
\&./multistresstest
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reference
.SS Data types
.sp
This section describes the numerous data types in use in PROJ.4. As a rule
of thumb PROJ.4 data types are prefixed with \fBPJ_\fP, or in one particular case,
is simply called \fI\%PJ\fP\&. A few notable exceptions can be traced
back to the very early days of PROJ.4 when the \fBPJ_\fP prefix was not
consistently used.
.SS Transformation objects
.INDENT 0.0
.TP
.B PJ
Object containing everything related to a given projection or transformation.
As a user of the PROJ.4 library you are only exposed to pointers to this
object and the contents is hidden behind the public API. \fI\%PJ\fP objects
are created with \fBproj_create()\fP and destroyed with
\fBproj_destroy()\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B PJ_DIRECTION
Enumeration that is used to convey in which direction a given transformation
should be performed. Used in transformation function call as described in
the section on transformation functions\&.
.sp
Forward transformations are defined with the :c:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef enum proj_direction {
    PJ_FWD   =  1,   /* Forward    */
    PJ_IDENT =  0,   /* Do nothing */
    PJ_INV   = \-1    /* Inverse    */
} PJ_DIRECTION;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B PJ_FWD
Perform transformation in the forward direction.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_IDENT
Identity. Do nothing.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_INV
Perform transformation in the inverse direction.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_CONTEXT
Context objects enable safe multi\-threaded usage of PROJ.4. Each \fI\%PJ\fP
object is connected to a context (if not specified, the default context is
used). All operations within a context should be performed in the same thread.
\fI\%PJ_CONTEXT\fP objects are created with \fBproj_context_create()\fP
and destroyed with \fBproj_context_destroy()\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B PJ_AREA
Opaque object describing an area in which a transformation is performed.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This object is not fully implemented yet. It is to be used with
\fBproj_create_crs_to_crs()\fP to select the best transformation
between the two input coordinate reference systems.
.UNINDENT
.UNINDENT
.UNINDENT
.SS 2 dimensional coordinates
.sp
Various 2\-dimensional coordinate data types.
.INDENT 0.0
.TP
.B PJ_LP
Geodetic coordinate, latitude and longitude. Usually in radians.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct { double lam, phi; } PJ_LP;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LP.lam
Longitude. Lambda.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LP.phi
Latitude. Phi.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_XY
2\-dimensional cartesian coordinate.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct { double x, y; } PJ_XY;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XY.x
Easting.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XY.y
Northing.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_UV
2\-dimensional generic coordinate. Usually used when contents can be either
a \fI\%PJ_XY\fP or \fI\%PJ_LP\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {double u, v; } PJ_UV;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UV.u
Longitude or easting, depending on use.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UV.v
Latitude or northing, depending on use.
.UNINDENT
.UNINDENT
.SS 3 dimensional coordinates
.sp
The following data types are the 3\-dimensional equivalents to the data
types above.
.INDENT 0.0
.TP
.B PJ_LPZ
3\-dimensional version of \fI\%PJ_LP\fP\&. Holds longitude, latitude and
a vertical component.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct { double lam, phi, z; } PJ_LPZ;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LPZ.lam
Longitude. Lambda.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LPZ.phi
Latitude. Phi.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LPZ.z
Vertical component.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_XYZ
Cartesian coordinate in 3 dimensions. Extension  of \fI\%PJ_XY\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct { double x, y, z; } PJ_XYZ;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XYZ.x
Easting or the X component of a 3D cartesian system.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XYZ.y
Northing or the Y component of a 3D cartesian system.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XYZ.z
Vertical component or the Z component of a 3D cartesian system.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_UVW
3\-dimensional extension of \fI\%PJ_UV\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {double u, v, w; } PJ_UVW;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UVW.u
Longitude or easting, depending on use.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UVW.v
Latitude or northing, depending on use.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UVW.w
Vertical component.
.UNINDENT
.UNINDENT
.SS Spatiotemporal coordinate types
.sp
The following data types are extensions of the triplets above into the time
domain.
.INDENT 0.0
.TP
.B PJ_LPZT
Spatiotemporal version of \fI\%PJ_LPZ\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    double lam;
    double phi;
    double z;
    double t;
} PJ_LPZT;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LPZT.lam
Longitude.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LPZT.phi
Latitude
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LPZT.z
Vertical component.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_LPZT.t
Time component.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_XYZT
Generic spatiotemporal coordinate. Useful for e.g. cartesian coordinates with
an attached time\-stamp.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    double x;
    double y;
    double z;
    double t;
} PJ_XYZT;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XYZT.x
Easting or the X component of a 3D cartesian system.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XYZT.y
Northing or the Y component of a 3D cartesian system.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XYZT.z
Vertical or the Z component of a 3D cartesian system.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_XYZT.t
Time component.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_UVWT
Spatiotemporal version of \fI\%PJ_UVW\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct { double u, v, w, t; } PJ_UVWT;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UVWT.e
First horizontal component.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UVWT.n
Second horizontal component.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UVWT.w
Vertical component.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_UVWT.t
Temporal component.
.UNINDENT
.UNINDENT
.SS Ancillary types for geodetic computations
.INDENT 0.0
.TP
.B PJ_OPK
Rotations, for instance three euler angles.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct { double o, p, k; } PJ_OPK;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_OPK.o
First rotation angle, omega.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_OPK.p
Second rotation angle, phi.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_OPK.k
Third rotation angle, kappa.
.UNINDENT
.UNINDENT
.SS Complex coordinate types
.INDENT 0.0
.TP
.B PJ_COORD
General purpose coordinate union type, applicable in two, three and four dimensions.
This is the default coordinate datatype used in PROJ.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef union {
    double v[4];
    PJ_XYZT xyzt;
    PJ_UVWT uvwt;
    PJ_LPZT lpzt;
    PJ_XYZ  xyz;
    PJ_UVW  uvw;
    PJ_LPZ  lpz;
    PJ_XY   xy;
    PJ_UV   uv;
    PJ_LP   lp;
} PJ_COORD ;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double v[4]
Generic four\-dimensional vector.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_XYZT PJ_COORD.xyzt
Spatiotemporal cartesian coordinate.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_UVWT PJ_COORD.uvwt
Spatiotemporal generic coordinate.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_LPZT PJ_COORD.lpzt
Longitude, latitude, vertical and time components.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_XYZ PJ_COORD.xyz
3\-dimensional cartesian coordinate.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_UVW PJ_COORD.uvw
3\-dimensional generic coordinate.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_LPZ PJ_COORD.lpz
Longitude, latitude and vertical component.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_XY PJ_COORD.xy
2\-dimensional cartesian coordinate.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_UV PJ_COORD.uv
2\-dimensional generic coordinate.
.UNINDENT
.INDENT 7.0
.TP
.B PJ_LP PJ_COORD.lp
Longitude and latitude.
.UNINDENT
.UNINDENT
.SS Projection derivatives
.INDENT 0.0
.TP
.B PJ_FACTORS
Various cartographic properties, such as scale factors, angular distortion
and meridian convergence. Calculated with \fBproj_factors()\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    double meridional_scale;
    double parallel_scale;
    double areal_scale;

    double angular_distortion;
    double meridian_parallel_angle;
    double meridian_convergence;

    double tissot_semimajor;
    double tissot_semiminor;

    double dx_dlam;
    double dx_dphi;
    double dy_dlam;
    double dy_dphi;
} PJ_FACTORS;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.meridional_scale
Meridional scale at coordinate \left(\lambda,\phi\right)\&.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.parallel_scale
Parallel scale at coordinate \left(\lambda,\phi\right)\&.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.areal_scale
Areal scale factor at coordinate \left(\lambda,\phi\right)\&.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.angular_distortion
Angular distortion at coordinate \left(\lambda,\phi\right)\&.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.meridian_parallel_angle
.INDENT 7.0
.INDENT 3.5
Meridian/parallel angle, \theta^\prime, at coordinate \left(\lambda,\phi\right)\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.meridian_convergence
Meridian convergence at coordinate \left(\lambda,\phi\right)\&.
Sometimes also described as \fIgrid declination\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.tissot_semimajor
Maximum scale factor.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.tissot_semiminor
Minimum scale factor.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.dx_dlam
Partial derivative \frac{\partial x}{\partial \lambda} of coordinate
\left(\lambda,\phi\right)\&.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.dy_dlam
Partial derivative \frac{\partial y}{\partial \lambda} of coordinate
\left(\lambda,\phi\right)\&.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.dx_dphi
Partial derivative \frac{\partial x}{\partial \phi} of coordinate
\left(\lambda,\phi\right)\&.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_FACTORS.dy_dphi
Partial derivative \frac{\partial y}{\partial \phi} of coordinate
\left(\lambda,\phi\right)\&.
.UNINDENT
.UNINDENT
.SS List structures
.INDENT 0.0
.TP
.B PJ_OPERATIONS
Description a PROJ.4 operation
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
struct PJ_OPERATIONS {
    char    *id;                 /* operation keyword */
    PJ *(*proj)(PJ *);           /* operation  entry point */
    char    * const *descr;      /* description text */
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B char *id
Operation keyword.
.UNINDENT
.INDENT 7.0
.TP
.B PJ *(*op)(PJ\fI\ *\fP)
Operation entry point.
.UNINDENT
.INDENT 7.0
.TP
.B char * const *
Description of operation.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_ELLPS
Description of ellipsoids defined in PROJ.4
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
struct PJ_ELLPS {
    char    *id;
    char    *major;
    char    *ell;
    char    *name;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B char *id
Keyword name of the ellipsoid.
.UNINDENT
.INDENT 7.0
.TP
.B char *major
Semi\-major axis of the ellipsoid, or radius in case of a sphere.
.UNINDENT
.INDENT 7.0
.TP
.B char *ell
Elliptical parameter, e.g. \fIrf=298.257\fP or \fIb=6356772.2\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B char *name
Name of the ellipsoid
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_UNITS
Distance units defined in PROJ.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
struct PJ_UNITS {
    char    *id;           /* units keyword */
    char    *to_meter;     /* multiply by value to get meters */
    char    *name;         /* comments */
    double   factor;       /* to_meter factor in actual numbers */
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B char *id
Keyword for the unit.
.UNINDENT
.INDENT 7.0
.TP
.B char *to_meter
Text representation of the factor that converts a given unit to meters
.UNINDENT
.INDENT 7.0
.TP
.B char *name
Name of the unit.
.UNINDENT
.INDENT 7.0
.TP
.B double factor
Conversion factor that converts the unit to meters.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_PRIME_MERIDIANS
Prime meridians defined in PROJ.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
struct PJ_PRIME_MERIDIANS {
    char    *id;
    char    *defn;
};
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B char *id
Keyword for the prime meridian
.UNINDENT
.INDENT 7.0
.TP
.B char *def
Offset from Greenwich in DMS format.
.UNINDENT
.UNINDENT
.SS Info structures
.INDENT 0.0
.TP
.B PJ_INFO
Struct holding information about the current instance of PROJ. Struct is
populated by \fBproj_info()\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    int           major;
    int           minor;
    int           patch;
    const char   *release;
    const char   *version;
    const char   *searchpath;
} PJ_INFO;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B const char *PJ_INFO.release
Release info. Version number and release date,
e.g. “Rel. 4.9.3, 15 August 2016”.
.UNINDENT
.INDENT 7.0
.TP
.B const char *PJ_INFO.version
Text representation of the full version number,
e.g. “4.9.3”.
.UNINDENT
.INDENT 7.0
.TP
.B int PJ_INFO.major
Major version number.
.UNINDENT
.INDENT 7.0
.TP
.B int PJ_INFO.minor
Minor version number.
.UNINDENT
.INDENT 7.0
.TP
.B int PJ_INFO.patch
Patch level of release.
.UNINDENT
.INDENT 7.0
.TP
.B const char PJ_INFO.searchpath
Search path for PROJ. List of directories separated by
semicolons (Windows) or colons (non\-Windows), e.g.
“C:\eUsers\edoctorwho;C:\eOSGeo4W64\eshare\eproj”.
Grids and init files are looked for in directories in the search path.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_PROJ_INFO
Struct holding information about a \fI\%PJ\fP object. Populated by
\fBproj_pj_info()\fP\&. The \fI\%PJ_PROJ_INFO\fP object provides a
view into the internals of a \fI\%PJ\fP, so once the \fI\%PJ\fP
is destroyed or otherwise becomes invalid, so does the
\fI\%PJ_PROJ_INFO\fP
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    const char  *id;
    const char  *description;
    const char  *definition;
    int          has_inverse;
    double       accuracy;
} PJ_PROJ_INFO;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B const char *PJ_PROJ_INFO.id
Short ID of the operation the \fI\%PJ\fP object is based on, that is,
what comes afther the \fB+proj=\fP in a proj\-string, e.g. “\fImerc\fP”.
.UNINDENT
.INDENT 7.0
.TP
.B const char *PJ_PROJ_INFO.description
Long describes of the operation the \fI\%PJ\fP object is based on,
e.g. “\fIMercator    Cyl, Sph&Ell   lat_ts=\fP”.
.UNINDENT
.INDENT 7.0
.TP
.B const char *PJ_PROJ_INFO.definition
The proj\-string that was used to create the \fI\%PJ\fP object with,
e.g. “\fI+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84\fP”.
.UNINDENT
.INDENT 7.0
.TP
.B int PJ_PROJ_INFO.has_inverse
1 if an inverse mapping of the defined operation exists, otherwise 0.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_PROJ_INFO.accuracy
Expected accuracy of the transformation. \-1 if unknown.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_GRID_INFO
Struct holding information about a specific grid in the search path of
PROJ. Populated with the function \fBproj_grid_info()\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    char        gridname[32];
    char        filename[260];
    char        format[8];
    LP          lowerleft;
    LP          upperright;
    int         n_lon, n_lat;
    double      cs_lon, cs_lat;
} PJ_GRID_INFO;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_GRID_INFO.gridname[32]
Name of grid, e.g. “\fIBETA2007.gsb\fP”.
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_GRID_INFO
Full path of grid file, e.g. \fI“C:\eOSGeo4W64\eshare\eproj\eBETA2007.gsb”\fP
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_GRID_INFO.format[8]
File format of grid file, e.g. “\fIntv2\fP”
.UNINDENT
.INDENT 7.0
.TP
.B LP PJ_GRID_INFO.lowerleft
Geodetic coordinate of lower left corner of grid.
.UNINDENT
.INDENT 7.0
.TP
.B LP PJ_GRID_INFO.upperright
Geodetic coordinate of upper right corner of grid.
.UNINDENT
.INDENT 7.0
.TP
.B int PJ_GRID_INFO.n_lon
Number of grid cells in the longitudinal direction.
.UNINDENT
.INDENT 7.0
.TP
.B int PJ_GRID_INFO.n_lat
Number of grid cells in the latitudianl direction.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_GRID_INFO.cs_lon
Cell size in the longitudinal direction. In radians.
.UNINDENT
.INDENT 7.0
.TP
.B double PJ_GRID_INFO.cs_lat
Cell size in the latitudinal direction. In radians.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_INIT_INFO
Struct holding information about a specific init file in the search path of
PROJ. Populated with the function \fBproj_init_info()\fP\&.
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    char        name[32];
    char        filename[260];
    char        version[32];
    char        origin[32];
    char        lastupdate[16];
} PJ_INIT_INFO;
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_INIT_INFO.name[32]
Name of init file, e.g. “\fIepsg\fP”.
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_INIT_INFO.filename[260]
Full path of init file, e.g. “\fIC:\eOSGeo4W64\eshare\eproj\eepsg\fP”
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_INIT_INFO.version[32]
Version number of init\-file, e.g. “\fI9.0.0\fP”
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_INIT_INFO.origin[32]
Originating entity of the init file, e.g. “\fIEPSG\fP”
.UNINDENT
.INDENT 7.0
.TP
.B char PJ_INIT_INFO.lastupdate
Date of last update of the init\-file.
.UNINDENT
.UNINDENT
.SS Functions
.SS Threading contexts
.INDENT 0.0
.TP
.B PJ_CONTEXT* proj_context_create(void)
Create a new threading\-context.
.INDENT 7.0
.TP
.B Returns
\fBPJ_CONTEXT*\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B void proj_context_destroy(PJ_CONTEXT\fI\ *ctx\fP)
Deallocate a threading\-context.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBctx\fP (\fIPJ_CONTEXT*\fP) – Threading context.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Transformation setup
.INDENT 0.0
.TP
.B PJ* proj_create(PJ_CONTEXT\fI\ *ctx\fP, const char\fI\ *definition\fP)
Create a transformation object from a proj\-string.
.sp
Example call:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel");
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The returned \fBPJ\fP\-pointer should be deallocated with \fI\%proj_destroy()\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBctx\fP (\fIPJ_CONTEXT*\fP) – Threading context.
.IP \(bu 2
\fBdefinition\fP (\fIconst char*\fP) – Proj\-string of the desired transformation.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ* proj_create_argv(PJ_CONTEXT\fI\ *ctx\fP, int\fI\ argc\fP, char\fI\ **argv\fP)
Create transformation object with argc/argv\-style initialization. For this
application each parameter in the defining proj\-string is an entry in \fBargv\fP\&.
.sp
Example call:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"};
PJ* P = proj_create_argv(0, 3, args);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The returned \fBPJ\fP\-pointer should be deallocated with \fI\%proj_destroy()\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBctx\fP (\fIPJ_CONTEXT*\fP) – Threading context
.IP \(bu 2
\fBargc\fP (\fIint\fP) – Count of arguments in \fBargv\fP
.IP \(bu 2
\fBargv\fP (\fIchar**\fP) – Vector of strings with proj\-string parameters, e.g. \fB+proj=merc\fP
.UNINDENT
.TP
.B Returns
\fBPJ*\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ* proj_create_crs_to_crs(PJ_CONTEXT\fI\ *ctx\fP, const char\fI\ *srid_from\fP, const char\fI\ *srid_to\fP, PJ_AREA\fI\ *area\fP)
Create a transformation object that is a pipeline between two known
coordinate reference systems.
.sp
\fBsrid_from\fP and \fBsrid_to\fP should be the value part of a \fB+init=...\fP parameter
set, i.e. “epsg:25833” or “IGNF:AMST63”. Any projection definition that
can be found in a init\-file in \fBPROJ_LIB\fP is a valid input to this function.
.sp
For now the function mimics the cs2cs app: An input and an output CRS is
given and coordinates are transformed via a hub datum (WGS84). This
transformation strategy is referred to as “early\-binding” by the EPSG. The
function can be extended to support “late\-binding” transformations in the
future without affecting users of the function. When the function is extended
to the late\-binding approach the \fBarea\fP argument will be used. For
now it is just a place\-holder for a future improved implementation.
.sp
Example call:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The returned \fBPJ\fP\-pointer should be deallocated with \fI\%proj_destroy()\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBctx\fP (\fIPJ_CONTEXT*\fP) – Threading context.
.IP \(bu 2
\fBsrid_from\fP (\fIconst char*\fP) – Source SRID.
.IP \(bu 2
\fBsrid_to\fP (\fIconst char*\fP) – Destination SRID.
.IP \(bu 2
\fBarea\fP (\fIPJ_AREA\fP) – Descriptor of the desired area for the transformation.
.UNINDENT
.TP
.B Returns
\fBPJ*\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ* proj_destroy(PJ\fI\ *P\fP)
Deallocate a \fBPJ\fP transformation object.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIPJ*\fP) – 
.UNINDENT
.TP
.B Returns
\fBPJ*\fP
.UNINDENT
.UNINDENT
.SS Coordinate transformation
.INDENT 0.0
.TP
.B PJ_COORD proj_trans(PJ\fI\ *P\fP, PJ_DIRECTION\fI\ direction\fP, PJ_COORD\fI\ coord\fP)
Transform a single \fBPJ_COORD\fP coordinate.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIPJ*\fP) – 
.IP \(bu 2
\fBdirection\fP (\fIPJ_DIRECTION\fP) – Transformation direction.
.IP \(bu 2
\fBcoord\fP (\fIPJ_COORD\fP) – Coordinate that will be transformed.
.UNINDENT
.TP
.B Returns
\fBPJ_COORD\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B size_t proj_trans_generic(PJ\fI\ *P\fP, PJ_DIRECTION\fI\ direction\fP, double\fI\ *x\fP, size_t\fI\ sx\fP, size_t\fI\ nx\fP, double\fI\ *y\fP, size_t\fI\ sy\fP, size_t\fI\ ny\fP, double\fI\ *z\fP, size_t\fI\ sz\fP, size_t\fI\ nz\fP, double\fI\ *t\fP, size_t\fI\ st\fP, size_t\fI\ nt\fP)
Transform a series of coordinates, where the individual coordinate dimension
may be represented by an array that is either
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
fully populated
.IP 2. 3
a null pointer and/or a length of zero, which will be treated as a
fully populated array of zeroes
.IP 3. 3
of length one, i.e. a constant, which will be treated as a fully
populated array of that constant value
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The strides, \fBsx\fP, \fBsy\fP, \fBsz\fP, \fBst\fP,
represent the step length, in bytes, between
consecutive elements of the corresponding array. This makes it possible for
\fBproj_transform()\fP to handle transformation of a large class of application
specific data structures, without necessarily understanding the data structure
format, as in:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
typedef struct {
    double x, y;
    int quality_level;
    char surveyor_name[134];
} XYQS;

XYQS survey[345];
double height = 23.45;
size_t stride = sizeof (XYQS);

\&...

proj_trans_generic (
    P, PJ_INV, sizeof(XYQS),
    &(survey[0].x), stride, 345,  /*  We have 345 eastings  */
    &(survey[0].y), stride, 345,  /*  ...and 345 northings. */
    &height, 1,                   /*  The height is the constant  23.45 m */
    0, 0                          /*  and the time is the constant 0.00 s */
);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is similar to the inner workings of the deprecated pj_transform function, but the
stride functionality has been generalized to work for any size of basic unit,
not just a fixed number of doubles.
.sp
In most cases, the stride will be identical for x, y, z, and t, since they will
typically be either individual arrays (stride = sizeof(double)), or strided
views into an array of application specific data structures (stride = sizeof (…)).
.sp
But in order to support cases where \fBx\fP, \fBy\fP, \fBz\fP,
and \fBt\fP come from heterogeneous sources, individual strides,
\fBsx\fP, \fBsy\fP, \fBsz\fP, \fBst\fP, are used.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Since \fBproj_transform()\fP does its work \fIin place\fP, this means that even the
supposedly constants (i.e. length 1 arrays) will return from the call in altered
state. Hence, remember to reinitialize between repeated calls.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIPJ*\fP) – Transformation object
.IP \(bu 2
\fBdirection\fP – Transformation direction
.IP \(bu 2
\fBx\fP (\fIdouble*\fP) – Array of x\-coordinates
.IP \(bu 2
\fBy\fP (\fIdouble*\fP) – Array of y\-coordinates
.IP \(bu 2
\fBz\fP (\fIdouble*\fP) – Array of z\-coordinates
.IP \(bu 2
\fBt\fP (\fIdouble*\fP) – Array of t\-coordinates
.IP \(bu 2
\fBsx\fP (\fIsize_t\fP) – Step length, in bytes, between consecutive elements of the corresponding array
.IP \(bu 2
\fBnx\fP (\fIsize_t\fP) – Number of elements in the corresponding array
.IP \(bu 2
\fBsy\fP (\fIsize_t\fP) – Step length, in bytes, between consecutive elements of the corresponding array
.IP \(bu 2
\fBnv\fP (\fIsize_t\fP) – Number of elements in the corresponding array
.IP \(bu 2
\fBsz\fP (\fIsize_t\fP) – Step length, in bytes, between consecutive elements of the corresponding array
.IP \(bu 2
\fBnz\fP (\fIsize_t\fP) – Number of elements in the corresponding array
.IP \(bu 2
\fBst\fP (\fIsize_t\fP) – Step length, in bytes, between consecutive elements of the corresponding array
.IP \(bu 2
\fBnt\fP (\fIsize_t\fP) – Number of elements in the corresponding array
.UNINDENT
.TP
.B Returns
Number of transformations successfully completed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B size_t proj_trans_array(PJ\fI\ *P\fP, PJ_DIRECTION\fI\ direction\fP, size_t\fI\ n\fP, PJ_COORD\fI\ *coord\fP)
Batch transform an array of \fBPJ_COORD\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIPJ*\fP) – 
.IP \(bu 2
\fBdirection\fP (\fIPJ_DIRECTION\fP) – Transformation direction
.IP \(bu 2
\fBn\fP (\fIsize_t\fP) – Number of coordinates in \fBcoord\fP
.UNINDENT
.TP
.B Returns
\fBsize_t\fP 0 if all observations are transformed without error, otherwise returns error number
.UNINDENT
.UNINDENT
.SS Error reporting
.INDENT 0.0
.TP
.B int proj_errno(PJ\fI\ *P\fP)
Get a reading of the current error\-state of \fBP\fP\&. An non\-zero error
codes indicates an error either with the transformation setup or during a
transformation.
.INDENT 7.0
.TP
.B Param
PJ* P: Transformation object.
.TP
.B Returns
\fBint\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B void proj_errno_set(PJ\fI\ *P\fP, int\fI\ err\fP)
.UNINDENT
.sp
Change the error\-state of \fBP\fP to \fIerr\fP\&.
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B param PJ* P
Transformation object.
.TP
.B param int err
Error number.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B int proj_errno_reset(PJ\fI\ *P\fP)
Clears the error number in \fBP\fP, and bubbles it up to the context.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
void foo (PJ *P) {
    int last_errno = proj_errno_reset (P);

    do_something_with_P (P);

    /* failure \- keep latest error status */
    if (proj_errno(P))
        return;
    /* success \- restore previous error status */
    proj_errno_restore (P, last_errno);
    return;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Param
PJ* P: Transformation object.
.TP
.B Returns
\fBint\fP Returns the previous value of the errno, for convenient reset/restore operations.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B void proj_errno_restore(PJ\fI\ *P\fP, int\fI\ err\fP)
Reduce some mental impedance in the canonical reset/restore use case:
Basically, \fI\%proj_errno_restore()\fP is a synonym for
\fI\%proj_errno_set()\fP, but the use cases are very different:
\fIset\fP indicate an error to higher level user code, \fIrestore\fP passes previously
set error indicators in case of no errors at this level.
.sp
Hence, although the inner working is identical, we provide both options,
to avoid some rather confusing real world code.
.sp
See usage example under \fI\%proj_errno_reset()\fP
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIPJ*\fP) – Transformation object.
.IP \(bu 2
\fBerr\fP (\fIint\fP) – Error code.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const char* proj_errno_string(int\fI\ err\fP)
Get a text representation of an error number.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBerr\fP (\fIint\fP) – Error number.
.UNINDENT
.TP
.B Returns
\fBconst char*\fP String with description of error.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
Available from version 5.1.0.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Info functions
.INDENT 0.0
.TP
.B PJ_INFO proj_info(void)
Get information about the current instance of the PROJ library.
.INDENT 7.0
.TP
.B Returns
\fBPJ_INFO\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_PROJ_INFO proj_pj_info(const PJ\fI\ *P\fP)
Get information about a specific transformation object, \fBP\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIconst PJ*\fP) – Transformation object
.UNINDENT
.TP
.B Returns
\fBPJ_PROJ_INFO\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_GRID_INFO proj_grid_info(const char\fI\ *gridname\fP)
Get information about a specific grid.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBgridname\fP (\fIconst char*\fP) – Gridname in the PROJ searchpath
.UNINDENT
.TP
.B Returns
\fBPJ_GRID_INFO\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_INIT_INFO proj_init_info(const char\fI\ *initname\fP)
Get information about a specific init file.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBinitname\fP (\fIconst char*\fP) – Init file in the PROJ searchpath
.UNINDENT
.TP
.B Returns
\fBPJ_INIT_INFO\fP
.UNINDENT
.UNINDENT
.SS Lists
.INDENT 0.0
.TP
.B const PJ_OPERATIONS* proj_list_operations(void)
Get a pointer to an array of all operations in PROJ. The last entry
of the returned array is a NULL\-entry. The array is statically allocated
and does not need to be freed after use.
.sp
Print a list of all operations in PROJ:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
PJ_OPERATIONS *ops;
for (ops = proj_list_operations(); ops\->id; ++ops)
    printf("%s\en", ops\->id);
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Returns
\fBPJ_OPERATIONS*\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const PJ_ELLPS* proj_list_ellps(void)
Get a pointer to an array of ellipsoids defined in PROJ. The last entry
of the returned array is a NULL\-entry. The array is statically allocated
and does not need to be freed after use.
.INDENT 7.0
.TP
.B Returns
\fBPJ_ELLPS*\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const PJ_UNITS* proj_list_units(void)
Get a pointer to an array of distance units defined in PROJ. The last
entry of the returned array is a NULL\-entry. The array is statically
allocated and does not need to be freed after use.
.INDENT 7.0
.TP
.B Returns
\fBPJ_UNITS*\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void)
Get a pointer to an array of prime meridians defined in PROJ. The last
entry of the returned array is a NULL\-entry. The array is statically
allocated and does not need to be freed after use.
.INDENT 7.0
.TP
.B Returns
\fBPJ_PRIME_MERIDIANS*\fP
.UNINDENT
.UNINDENT
.SS Distances
.INDENT 0.0
.TP
.B double proj_lp_dist(const PJ\fI\ *P\fP, PJ_COORD\fI\ a\fP, PJ_COORD\fI\ b\fP)
Calculate geodesic distance between two points in geodetic coordinates.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIPJ*\fP) – Transformation object
.IP \(bu 2
\fBa\fP (\fIPJ_COORD\fP) – Coordinate of first point
.IP \(bu 2
\fBb\fP (\fIPJ_COORD\fP) – Coordinate of second point
.UNINDENT
.TP
.B Returns
\fBdouble\fP Distance between \fBa\fP and \fBb\fP in meters.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B double proj_lp_dist(const PJ\fI\ *P\fP, PJ_COORD\fI\ a\fP, PJ_COORD\fI\ b\fP)
Calculate geodesic distance between two points in geodetic coordinates.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIPJ*\fP) – Transformation object
.IP \(bu 2
\fBa\fP (\fIPJ_COORD\fP) – Coordinate of first point
.IP \(bu 2
\fBb\fP (\fIPJ_COORD\fP) – Coordinate of second point
.UNINDENT
.TP
.B Returns
\fBdouble\fP Distance between \fBa\fP and \fBb\fP in meters.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B double proj_xy_dist(PJ_COORD\fI\ a\fP, PJ_COORD\fI\ b\fP)
Calculate 2\-dimensional euclidean between two projected coordinates.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBa\fP (\fIPJ_COORD\fP) – First coordinate
.IP \(bu 2
\fBb\fP (\fIPJ_COORD\fP) – Second coordinate
.UNINDENT
.TP
.B Returns
\fBdouble\fP Distance between \fBa\fP and \fBb\fP in meters.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B double proj_xyz_dist(PJ_COORD\fI\ a\fP, PJ_COORD\fI\ b\fP)
Calculate 3\-dimensional euclidean between two projected coordinates.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBa\fP (\fIPJ_COORD\fP) – First coordinate
.IP \(bu 2
\fBb\fP (\fIPJ_COORD\fP) – Second coordinate
.UNINDENT
.TP
.B Returns
\fBdouble\fP Distance between \fBa\fP and \fBb\fP in meters.
.UNINDENT
.UNINDENT
.SS Various
.INDENT 0.0
.TP
.B PJ_COORD proj_coord(double\fI\ x\fP, double\fI\ y\fP, double\fI\ z\fP, double\fI\ t\fP)
Initializer for the \fBPJ_COORD\fP union. The function is
shorthand for the otherwise convoluted assignment.
Equivalent to
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}};
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
PJ_COORD c;
// Assign using the PJ_XYZT struct in the union
c.xyzt.x = 10.0;
c.xyzt.y = 20.0;
c.xyzt.z = 30.0;
c.xyzt.t = 40.0;
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Since \fBPJ_COORD\fP is a union of structs, the above assignment can
also be expressed in terms of the other types in the union, e.g.
\fBPJ_UVWT\fP or \fBPJ_LPZT\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBx\fP (\fIdouble\fP) – 1st component in a \fBPJ_COORD\fP
.IP \(bu 2
\fBy\fP (\fIdouble\fP) – 2nd component in a \fBPJ_COORD\fP
.IP \(bu 2
\fBz\fP (\fIdouble\fP) – 3rd component in a \fBPJ_COORD\fP
.IP \(bu 2
\fBt\fP (\fIdouble\fP) – 4th component in a \fBPJ_COORD\fP
.UNINDENT
.TP
.B Returns
\fBPJ_COORD\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B double proj_roundtrip(PJ\fI\ *P\fP, PJ_DIRECTION\fI\ direction\fP, int\fI\ n\fP, PJ_COORD\fI\ *coord\fP)
Measure internal consistency of a given transformation. The function
performs \fBn\fP round trip transformations starting in either
the forward or reverse \fBdirection\fP\&. Returns the euclidean
distance of the starting point \fBcoo\fP and the resulting
coordinate after \fBn\fP iterations back and forth.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIconst PJ*\fP) – 
.IP \(bu 2
\fBdirection\fP (\fIPJ_DIRECTION\fP) – Starting direction of transformation
.IP \(bu 2
\fBn\fP (\fIint\fP) – Number of roundtrip transformations
.IP \(bu 2
\fBcoord\fP (\fIPJ_COORD\fP) – Input coordinate
.UNINDENT
.TP
.B Returns
\fBdouble\fP Distance between original coordinate and the resulting coordinate after \fBn\fP transformation iterations.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_FACTORS proj_factors(PJ\fI\ *P\fP, PJ_COORD\fI\ lp\fP)
Calculate various cartographic properties, such as scale factors, angular
distortion and meridian convergence. Depending on the underlying projection
values will be calculated either numerically (default) or analytically.
.sp
The function also calculates the partial derivatives of the given
coordinate.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIconst PJ*\fP) – Transformation object
.IP \(bu 2
\fBlp\fP (\fIconst PJ_COORD\fP) – Geodetic coordinate
.UNINDENT
.TP
.B Returns
\fBPJ_FACTORS\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B double proj_torad(double\fI\ angle_in_degrees\fP)
Convert degrees to radians.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBangle_in_degrees\fP (\fIdouble\fP) – Degrees
.UNINDENT
.TP
.B Returns
\fBdouble\fP Radians
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B double proj_todeg(double\fI\ angle_in_radians\fP)
Convert radians to degrees
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBangle_in_radians\fP (\fIdouble\fP) – Radians
.UNINDENT
.TP
.B Returns
\fBdouble\fP Degrees
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B double proj_dmstor(const char\fI\ *is\fP, char\fI\ **rs\fP)
Convert string of degrees, minutes and seconds to radians.
Works similarly to the C standard library function \fBstrtod()\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBis\fP (\fIconst  char*\fP) – Value to be converted to radians
.IP \(bu 2
\fBrs\fP – Reference to an already allocated char*, whose value is set by the function to the next character in \fBis\fP after the numerical value.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B char *proj_rtodms(char\fI\ *s\fP, double\fI\ r\fP, int\fI\ pos\fP, int\fI\ neg\fP)
Convert radians to string representation of degrees, minutes and seconds.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBs\fP (\fIchar*\fP) – Buffer that holds the output string
.IP \(bu 2
\fBr\fP (\fIdouble\fP) – Value to convert to dms\-representation
.IP \(bu 2
\fBpos\fP (\fIint\fP) – Character denoting positive direction, typically \fI‘N’\fP or \fI‘E’\fP\&.
.IP \(bu 2
\fBneg\fP (\fIint\fP) – Character denoting negative direction, typically \fI‘S’\fP or \fI‘W’\fP\&.
.UNINDENT
.TP
.B Returns
\fBchar*\fP Pointer to output buffer (same as \fBs\fP)
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B PJ_COORD proj_geocentric_latitude(const PJ\fI\ *P\fP, PJ_DIRECTION\fI\ direction\fP, PJ_COORD\fI\ coord\fP)
Convert from geographical latitude to geocentric latitude.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIconst PJ*\fP) – Transformation object
.IP \(bu 2
\fBdirection\fP (\fIPJ_DIRECTION\fP) – Starting direction of transformation
.IP \(bu 2
\fBcoord\fP (\fIPJ_COORD\fP) – Coordinate
.UNINDENT
.TP
.B Returns
\fBPJ_COORD\fP Converted coordinate
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B int proj_angular_input(PJ\fI\ *P\fP, enum PJ_DIRECTION\fI\ dir\fP)
Check if a operation expects angular input.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBP\fP (\fIconst PJ*\fP) – Transformation object
.IP \(bu 2
\fBdirection\fP (\fIPJ_DIRECTION\fP) – Starting direction of transformation
.UNINDENT
.TP
.B Returns
\fBint\fP 1 if angular input is expected, otherwise 0
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B int proj_angular_output(PJ\fI\ *P\fP, enum PJ_DIRECTION\fI\ dir\fP)
Check if an operation returns angular output.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B param \fIP\fP
Transformation object
.TP
.B type \fIP\fP
const PJ*
.TP
.B param \fIdirection\fP
Starting direction of transformation
.TP
.B type \fIdirection\fP
PJ_DIRECTION
.TP
.B returns
\fBint\fP 1 if angular output is returned, otherwise 0
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Deprecated API
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%Deprecated API\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Introduction\fP
.IP \(bu 2
\fI\%Example\fP
.IP \(bu 2
\fI\%API Functions\fP
.INDENT 2.0
.IP \(bu 2
\fI\%pj_transform\fP
.IP \(bu 2
\fI\%pj_init_plus\fP
.IP \(bu 2
\fI\%pj_free\fP
.IP \(bu 2
\fI\%pj_is_latlong\fP
.IP \(bu 2
\fI\%pj_is_geocent\fP
.IP \(bu 2
\fI\%pj_get_def\fP
.IP \(bu 2
\fI\%pj_latlong_from_proj\fP
.IP \(bu 2
\fI\%pj_set_finder\fP
.IP \(bu 2
\fI\%pj_set_searchpath\fP
.IP \(bu 2
\fI\%pj_deallocate_grids\fP
.IP \(bu 2
\fI\%pj_strerrno\fP
.IP \(bu 2
\fI\%pj_get_errno_ref\fP
.IP \(bu 2
\fI\%pj_get_release\fP
.UNINDENT
.UNINDENT
.UNINDENT
.SS Introduction
.sp
Procedure \fBpj_init()\fP selects and initializes a cartographic
projection with its argument control parameters. \fBargc\fP is the number
of elements in the array of control strings argv that each contain
individual cartographic control keyword assignments (+ proj arguments).
The list must contain at least the proj=projection and Earth’s radius or
elliptical parameters. If the initialization of the projection is
successful a valid address is returned otherwise a NULL value.
.sp
The \fBpj_init_plus()\fP function operates similarly to \fBpj_init()\fP but
takes a single string containing the definition, with each parameter
prefixed with a plus sign. For example
\fB+proj=utm +zone=11 +ellps=WGS84\fP\&.
.sp
Once initialization is performed either forward or inverse projections
can be performed with the returned value of \fBpj_init()\fP used as the
argument proj. The argument structure projUV values u and v contain
respective longitude and latitude or x and y. Latitude and longitude are
in radians. If a projection operation fails, both elements of projUV are
set to \fBHUGE_VAL\fP (defined in \fBmath.h\fP).
.sp
Note: all projections have a forward mode, but some do not have an
inverse projection. If the projection does not have an inverse the
projPJ structure element inv will be \fBNULL\fP\&.
.sp
The \fBpj_transform\fP function may be used to transform points between
the two provided coordinate systems. In addition to converting between
cartographic projection coordinates and geographic coordinates, this
function also takes care of datum shifts if possible between the source
and destination coordinate system. Unlike \fBpj_fwd()\fP and \fBpj_inv()\fP
it is also allowable for the coordinate system definitions
\fB(projPJ *)\fP to be geographic coordinate systems (defined as
\fB+proj=latlong\fP).
The x, y and z arrays contain the input values of the points, and are replaced with the output values.
The function returns zero on success, or the error number (also in \fBpj_errno\fP)
on failure.
.sp
Memory associated with the projection may be freed with \fBpj_free()\fP\&.
.SS Example
.sp
The following program reads latitude and longitude values in decimal
degrees, performs Mercator projection with a Clarke 1866 ellipsoid and a
33° latitude of true scale and prints the projected cartesian values in
meters:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <proj_api.h>

main(int argc, char **argv) {
     projPJ pj_merc, pj_latlong;
     double x, y;

     if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) )
        exit(1);
     if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) )
        exit(1);
     while (scanf("%lf %lf", &x, &y) == 2) {
        x *= DEG_TO_RAD;
        y *= DEG_TO_RAD;
        p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL );
        printf("%.2f\et%.2f\en", x, y);
     }
     exit(0);
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For this program, an input of \fB\-16 20.25\fP would give a result of
\fB\-1495284.21 1920596.79\fP\&.
.SS API Functions
.SS pj_transform
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int pj_transform( projPJ srcdefn,
                  projPJ dstdefn,
                  long point_count,
                  int point_offset,
                  double *x,
                  double *y,
                  double *z );
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Transform the x/y/z points from the source coordinate system to the
destination coordinate system.
.sp
\fBsrcdefn\fP: source (input) coordinate system.
.sp
\fBdstdefn\fP: destination (output) coordinate system.
.sp
\fBpoint_count\fP: the number of points to be processed (the size of the
x/y/z arrays).
.sp
\fBpoint_offset\fP: the step size from value to value (measured in
doubles) within the x/y/z arrays \- normally 1 for a packed array. May be
used to operate on xyz interleaved point arrays.
.sp
\fBx\fP/\fBy\fP/\fBz\fP: The array of X, Y and Z coordinate values passed as
input, and modified in place for output. The Z may optionally be NULL.
.sp
\fBreturn\fP: The return is zero on success, or a PROJ.4 error code.
.sp
The \fBpj_transform()\fP function transforms the passed in list of points
from the source coordinate system to the destination coordinate system.
Note that geographic locations need to be passed in radians, not decimal
degrees, and will be returned similarly. The \fBz\fP array may be passed
as NULL if Z values are not available.
.sp
If there is an overall failure, an error code will be returned from the
function. If individual points fail to transform \- for instance due to
being over the horizon \- then those x/y/z values will be set to
\fBHUGE_VAL\fP on return. Input values that are \fBHUGE_VAL\fP will not be
transformed.
.SS pj_init_plus
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
projPJ pj_init_plus(const char *definition);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This function converts a string representation of a coordinate system
definition into a projPJ object suitable for use with other API
functions. On failure the function will return NULL and set pj_errno.
The definition should be of the general form
\fB+proj=tmerc +lon_0 +datum=WGS84\fP\&. Refer to PROJ.4 documentation and
the transformation notes for additional detail.
.sp
Coordinate system objects allocated with \fBpj_init_plus()\fP should be
deallocated with \fBpj_free()\fP\&.
.SS pj_free
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void pj_free( projPJ pj );
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Frees all resources associated with pj.
.SS pj_is_latlong
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int pj_is_latlong( projPJ pj );
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns TRUE if the passed coordinate system is geographic
(\fBproj=latlong\fP).
.SS pj_is_geocent
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int pj_is_geocent( projPJ pj );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns TRUE if the coordinate system is geocentric (\fBproj=geocent\fP).
.SS pj_get_def
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
char *pj_get_def( projPJ pj, int options);\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns the PROJ.4 initialization string suitable for use with
\fBpj_init_plus()\fP that would produce this coordinate system, but with
the definition expanded as much as possible (for instance \fB+init=\fP and
\fB+datum=\fP definitions).
.SS pj_latlong_from_proj
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
projPJ pj_latlong_from_proj( projPJ pj_in );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a new coordinate system definition which is the geographic
coordinate (lat/long) system underlying \fBpj_in\fP\&.
.SS pj_set_finder
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void pj_set_finder( const char *(*new_finder)(const char *) );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Install a custom function for finding init and grid shift files.
.SS pj_set_searchpath
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void pj_set_searchpath ( int count, const char **path );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Set a list of directories to search for init and grid shift files.
.SS pj_deallocate_grids
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
void pj_deallocate_grids( void );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Frees all resources associated with loaded and cached datum shift grids.
.SS pj_strerrno
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
char *pj_strerrno( int );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns the error text associated with the passed in error code.
.SS pj_get_errno_ref
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int *pj_get_errno_ref( void );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns a pointer to the global pj_errno error variable.
.SS pj_get_release
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
const char *pj_get_release( void );\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Returns an internal string describing the release version.
.SS Obsolete Functions
.sp
\fBXY pj_fwd( LP lp, PJ *P );\fP
.sp
\fBLP pj_inv( XY xy, PJ *P );\fP
.sp
\fBprojPJ pj_init(int argc, char **argv);\fP
.SS Using PROJ in CMake projects
.sp
The recommended way to use the PROJ library in a CMake project is to
link to the imported library target \fB${PROJ4_LIBRARIES}\fP provided by
the CMake configuration which comes with the library. Typical usage is:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_package(PROJ4)

target_link_libraries(MyApp ${PROJ4_LIBRARIES})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
By adding the imported library target \fB${PROJ4_LIBRARIES}\fP to the
target link libraries, CMake will also pass the include directories to
the compiler.  This requires that you use CMake version 2.8.11 or later.
If you are using an older version of CMake, then add
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include_directories(${PROJ4_INCLUDE_DIRS})
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The CMake command \fBfind_package\fP will look for the configuration in a
number of places. The lookup can be adjusted for all packages by setting
the cache variable or environment variable \fBCMAKE_PREFIX_PATH\fP\&. In
particular, CMake will consult (and set) the cache variable
\fBPROJ4_DIR\fP\&.
.SS Language bindings
.sp
PROJ bindings are available for a number of different development platforms.
.SS Python
.sp
\fI\%pyproj\fP:
Python interface (wrapper for PROJ)
.SS Ruby
.sp
\fI\%proj4rb\fP:
Bindings for PROJ in ruby
.SS TCL
.sp
\fI\%proj4tcl\fP:
Bindings for PROJ in tcl (critcl source)
.SS MySQL
.sp
\fI\%fProj4\fP:
Bindings for PROJ in MySQL
.SS Excel
.sp
\fI\%proj.xll\fP:
Excel add\-in for PROJ map projections
.SS Visual Basic
.sp
\fI\%PROJ VB Wrappers\fP:
By Eric G. Miller.
.SS Version 4 to 5 API Migration
.sp
This is a transition guide for developers wanting to migrate their code to use
PROJ version 5.
.SS Background
.sp
Before we go on, a bit of background is needed. The new API takes a different
view of the world than the old because it is needed in order to obtain high
accuracy transformations. The old API is constructed in such a way that any transformation
between two coordinate reference systems \fImust\fP pass through the ill\-defined
WGS84 reference frame, using it as a hub. The new API does away with this limitation to
transformations in PROJ. It is still possible to do that type of transformations
but in many cases there will be a better alternative.
.sp
The world view represented by the old API is always sufficient if all you care about is
meter level accuracy \- and in many cases it will provide much higher accuracy
than that. But the view that “WGS84 is the \fItrue\fP foundation of the world, and
everything else can be transformed natively to and from WGS84” is inherently flawed.
.sp
First and foremost because any time WGS84 is mentioned, you should ask yourself
“Which of the six WGS84 realizations are we talking about here?”.
.sp
Second, because for many (especially legacy) systems, it may not be straightforward
to transform to WGS84 (or actually ITRF\-something, ETRS\-something or NAD\-something
which appear to be the practical meaning of the term WGS84 in everyday PROJ related
work), while centimeter\-level accurate transformations may exist between pairs of
older systems.
.sp
The concept of a hub reference frame (“datum”) is not inherently bad, but in many
cases you need to handle and select that datum with more care than the old API allows.
The primary aim of the new API is to allow just that. And to do that, you must realize
that the world is inherently 4 dimensional. You may in many cases assume one or more of
the coordinates to be constant, but basically, to obtain geodetic accuracy transformations,
you need to work in 4 dimensions.
.sp
Now, having described the background for introducing the new API, let’s try to show
how to use it. First note that in order to go from system A to system B, the old API
starts by doing an \fBinverse\fP transformation from system A to WGS84, then does a
\fBforward\fP transformation from WGS84 to system B.
.sp
With \fBcs2cs\fP being the command line interface to the old API, and \fBcct\fP being the same
for the new, this example of doing the same thing in both world views will should give
an idea of the differences:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ echo 300000 6100000 | cs2cs +proj=utm +zone=33 +ellps=GRS80 +to +proj=utm +zone=32 +ellps=GRS80
683687.87       6099299.66 0.00


$ echo 300000 6100000 0 0 | cct +proj=pipeline +step +inv +proj=utm +zone=33 +ellps=GRS80 +step +proj=utm +zone=32 +ellps=GRS80
683687.8667   6099299.6624    0.0000    0.0000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lookout for the \fB+inv\fP in the first \fB+step\fP, indicating an inverse transform.
.SS Code example
.sp
The difference between the old and new API is shown here with a few examples. Below
we implement the same program with the two different API’s. The program reads
input latitude and longitude from the command line and convert them to
projected coordinates with the Mercator projection.
.sp
We start by writing the program for PROJ v. 4:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <proj_api.h>

main(int argc, char **argv) {
    projPJ pj_merc, pj_latlong;
    double x, y;

    if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) )
        return 1;
    if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) )
        return 1;

    while (scanf("%lf %lf", &x, &y) == 2) {
        x *= DEG_TO_RAD;
        y *= DEG_TO_RAD;
        p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL );
        printf("%.2f\et%.2f\en", x, y);
    }

    return 0;
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The same program implemented using PROJ v. 5:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <proj.h>

main(int argc, char **argv) {
    PJ *P;
    PJ_COORD c;

    P = proj_create(PJ_DEFAULT_CTX, "+proj=merc +ellps=clrk66 +lat_ts=33");
    if (P==0)
        return 1;

    while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) {
        c.lp.lam = proj_todeg(c.lp.lam);
        c.lp.phi = proj_todeg(c.lp.phi);
        c = proj_trans(P, PJ_FWD, c);
        printf("%.2f\et%.2f\en", c.xy.x, c.xy.y);
    }

}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Looking at the two different programs, there’s a few immediate
differences that catches the eye. First off, the included header file describing
the API has changed from \fBproj_api.h\fP to simply \fBproj.h\fP\&. All functions in \fBproj.h\fP
belongs to the \fBproj_\fP namespace.
.sp
With the new API also comes new datatypes. E.g. the transformation object \fBprojPJ\fP
which has been changed to a pointer of type \fBPJ\fP\&. This is done to highlight the
actual nature of the object, instead of hiding it away behind a typedef. New data
types for handling coordinates have also been introduced. In the above example we
use the \fBPJ_COORD\fP, which is a union of various types. The benefit of this is that
it is possible to use the various structs in the union to communicate what state
the data is in at different points in the program. For instance as in the above
example where the coordinate is read from STDIN as a geodetic coordinate,
communicated to the reader of the code by using the \fBc.lp\fP struct.
After it has been projected we print it to STDOUT by accessing the individual
elements in \fBc.xy\fP to illustrate that the coordinate is now in projected space.
Data types are prefixed with \fIPJ_\fP\&.
.sp
The final, and perhaps biggest, change is that the fundamental concept of
transformations in PROJ are now handled in a single transformation object (\fBPJ\fP)
and not by stating the source and destination systems as previously. It is of
course still possible to do just that, but the transformation object now
captures the whole transformation from source to destination in one. In the
example with the old API the source system is described as
\fB+proj=latlon +ellps=clrk66\fP and the destination system is described as
\fB+proj=merc +ellps=clrk66 +lat_ts=33\fP\&. Since the Mercator projection accepts
geodetic coordinates as its input, the description of the source in this case
is superfluous. We use that to our advantage in the new API and simply state
the destination. This is simple at a glance, but is actually a big conceptual
change. We are now focused on the path between two systems instead of what the
source and destination systems are.
.SS Function mapping from old to new API
.TS
center;
|l|l|.
_
T{
\fBOld API functions\fP
T}	T{
\fBNew API functions\fP
T}
_
T{
pj_fwd
T}	T{
proj_trans
T}
_
T{
pj_inv
T}	T{
proj_trans
T}
_
T{
pj_fwd3
T}	T{
proj_trans
T}
_
T{
pj_inv3
T}	T{
proj_trans
T}
_
T{
pj_transform
T}	T{
proj_trans_array or proj_trans_generic
T}
_
T{
pj_init
T}	T{
proj_create
T}
_
T{
pj_init_plus
T}	T{
proj_create
T}
_
T{
pj_free
T}	T{
proj_destroy
T}
_
T{
pj_is_latlong
T}	T{
proj_angular_output
T}
_
T{
pj_is_geocent
T}	T{
proj_angular_outout
T}
_
T{
pj_get_def
T}	T{
proj_pj_info
T}
_
T{
pj_latlong_from_proj
T}	T{
\fINo equivalent\fP
T}
_
T{
pj_set_finder
T}	T{
\fINo equivalent\fP
T}
_
T{
pj_set_searchpath
T}	T{
\fINo equivalent\fP
T}
_
T{
pj_deallocate_grids
T}	T{
\fINo equivalent\fP
T}
_
T{
pj_strerrno
T}	T{
\fINo equivalent\fP
T}
_
T{
pj_get_errno_ref
T}	T{
proj_errno
T}
_
T{
pj_get_release
T}	T{
proj_info
T}
_
.TE
.SS Development rules and tools for PROJ code contributors
.sp
This is a guide for PROJ, casual or regular, code contributors.
.SS Code contributions.
.sp
Code contributions can be either bug fixes or new features. The process
is the same for both, so they will be discussed together in this
section.
.SS Making Changes
.INDENT 0.0
.IP \(bu 2
Create a topic branch from where you want to base your work.
.IP \(bu 2
You usually should base your topic branch off of the master branch.
.IP \(bu 2
To quickly create a topic branch: \fBgit checkout \-b my\-topic\-branch\fP
.IP \(bu 2
Make commits of logical units.
.IP \(bu 2
Check for unnecessary whitespace with \fBgit diff \-\-check\fP before
committing.
.IP \(bu 2
Make sure your commit messages are in the \fI\%proper
format\fP\&.
.IP \(bu 2
Make sure you have added the necessary tests for your changes.
.IP \(bu 2
Make sure that all tests pass
.UNINDENT
.SS Submitting Changes
.INDENT 0.0
.IP \(bu 2
Push your changes to a topic branch in your fork of the repository.
.IP \(bu 2
Submit a pull request to the PROJ repository in the OSGeo
organization.
.IP \(bu 2
If your pull request fixes/references an issue, include that issue
number in the pull request. For example:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Wiz the bang

Fixes #123.
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP \(bu 2
PROJ developers will look at your patch and take an appropriate
action.
.UNINDENT
.SS Coding conventions
.SS Programming language
.sp
PROJ is developed strictly in ANSI C 89.
.SS Coding style
.sp
We don’t enforce any particular coding style, but please try to keep it
as simple as possible. If improving existing code, please try to conform
with the style of the locally surrounding code.
.SS Whitespace
.sp
Throughout the PROJ code base you will see differing whitespace use.
The general rule is to keep whitespace in whatever form it is in the
file you are currently editing. If the file has a mix of tabs and space
please convert the tabs to space in a separate commit before making any
other changes. This makes it a lot easier to see the changes in diffs
when evaluating the changed code. New files should use spaces as
whitespace.
.SS File names
.sp
Files in which projections are implemented are prefixed with an
upper\-case \fBPJ_\fP and most other files are prefixed with lower\-case
\fBpj_\fP\&. Some file deviate from this pattern, most of them dates back to
the very early releases of PROJ. New contributions should follow the
pj\-prefix pattern. Unless there are obvious reasons not to.
.SS Tools
.SS cppcheck static analyzer
.sp
You can run locally \fBscripts/cppcheck.sh\fP that is a wrapper script around the
cppcheck utility. It is known to work with cppcheck 1.61 of Ubuntu Trusty 14.0,
since this is what is currently used on Travis\-CI
(\fBtravis/linux_gcc/before_install.sh\fP).
At the time of writing, this also works with cppcheck 1.72 of Ubuntu Xenial
16.04, and latest cppcheck
master.
.sp
cppcheck can have false positives. In general, it is preferable to rework the
code a bit to make it more ‘obvious’ and avoid those false positives. When not
possible, you can add a comment in the code like
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* cppcheck\-suppress duplicateBreak */
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
in the preceding line. Replace
duplicateBreak with the actual name of the violated rule emitted by cppcheck.
.SS CLang Static Analyzer (CSA)
.sp
CSA is run by the \fBtravis/csa\fP build configuration. You may also run it locally.
.sp
Preliminary step: install clang. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
wget http://releases.llvm.org/6.0.0/clang+llvm\-6.0.0\-x86_64\-linux\-gnu\-ubuntu\-14.04.tar.xz
tar xJf clang+llvm\-6.0.0\-x86_64\-linux\-gnu\-ubuntu\-14.04.tar.xz
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Run configure under the scan\-build utility of clang:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./clang+llvm\-6.0.0\-x86_64\-linux\-gnu\-ubuntu\-14.04/bin/scan\-build ./configure
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Build under scan\-build:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./clang+llvm\-6.0.0\-x86_64\-linux\-gnu\-ubuntu\-14.04/bin/scan\-build make [\-j8]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If CSA finds errors, they will be emitted during the build. And in which case,
at the end of the build process, scan\-build will emit a warning message
indicating errors have been found and how to display the error report. This
is with someling like
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\&./clang+llvm\-6.0.0\-x86_64\-linux\-gnu\-ubuntu\-14.04/bin/scan\-view /tmp/scan\-build\-2018\-03\-15\-121416\-17476\-1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will open a web browser with the interactive report.
.sp
CSA may also have false positives. In general, this happens when the code is
non\-trivial / makes assumptions that hard to check at first sight. You will
need to add extra checks or rework it a bit to make it more “obvious” for CSA.
This will also help humans reading your code !
.SS Typo detection and fixes
.sp
Run \fBscripts/fix_typos.sh\fP
.SS FAQ
.SS Contents
.INDENT 0.0
.IP \(bu 2
\fI\%FAQ\fP
.INDENT 2.0
.IP \(bu 2
\fI\%Where can I find the list of projections and their arguments?\fP
.IP \(bu 2
\fI\%How do I build/configure PROJ to support datum shifting?\fP
.IP \(bu 2
\fI\%How do I debug problems with NAD27/NAD83 datum shifting?\fP
.IP \(bu 2
\fI\%How do I use EPSG coordinate system codes with PROJ?\fP
.IP \(bu 2
\fI\%How do I use 3 parameter and 7 parameter datum shifting\fP
.IP \(bu 2
\fI\%Does PROJ work in different international numeric locales?\fP
.IP \(bu 2
\fI\%Changing Ellipsoid / Why can’t I convert from WGS84 to Google Earth / Virtual Globe Mercator?\fP
.IP \(bu 2
\fI\%Why do I get different results with 4.5.0 and 4.6.0?\fP
.IP \(bu 2
\fI\%How do I calculate distances/directions on the surface of the earth?\fP
.IP \(bu 2
\fI\%What is the HEALPix projection and how can I use it?\fP
.IP \(bu 2
\fI\%What is the rHEALPix projection and how can I use it?\fP
.IP \(bu 2
\fI\%What options does PROJ allow for the shape of the Earth (geodesy)?\fP
.IP \(bu 2
\fI\%What if I want a spherical Earth?\fP
.IP \(bu 2
\fI\%How do I change the radius of the Earth?  How do I use PROJ for work on Mars?\fP
.IP \(bu 2
\fI\%How do I do False Eastings and False Northings?\fP
.UNINDENT
.UNINDENT
.SS Where can I find the list of projections and their arguments?
.sp
There is no simple single location to find all the required information. The
!PostScript/PDF documents listed on the [\fI\%http://trac.osgeo.org/proj/wiki\fP main]
PROJ page under documentation are the authoritative source but projections
and options are spread over several documents in a form more related to their
order of implementation than anything else.
.sp
The ‘’‘proj’‘’ command itself can report the list of projections using the
‘’‘\-lp’‘’ option, the list of ellipsoids with the ‘’‘\-le’‘’ option, the list of
units with the ‘’‘\-lu’‘’ option, and the list of built\-in datums with the
‘’‘\-ld’‘’ option.
.sp
The [\fI\%http://www.remotesensing.org/geotiff/proj_list/\fP GeoTIFF Projections Pages]
include most of the common PROJ projections, and a definition of the
projection specific options for each.
.INDENT 0.0
.IP \(bu 2
How do I do datum shifts between NAD27 and NAD83?
.UNINDENT
.sp
While the ‘’‘nad2nad’‘’ program can be used in some cases, the ‘’‘cs2cs’‘’ is
now the preferred mechanism.   The following example demonstrates using the
default shift parameters for NAD27 to NAD83:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
% cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 \-117 30
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
producing:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
117d0\(aq2.901"W   30d0\(aq0.407"N 0.000
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In order for datum shifting to work properly the various grid shift files must
be available.  See below.  More details are available in the
[wiki:GenParms#nadgrids\-GridBasedDatumAdjustments General Parameters] document.
.SS How do I build/configure PROJ to support datum shifting?
.sp
After downloading and unpacking the PROJ source, also download and unpack the
set of datum shift files.  See download for instructions how to fetch
and install these files
.sp
On Windows the extra nadshift target must be used.  For instance
\fBnmake /f makefile.vc nadshift\fP in the \fBproj/src\fP directory.
.sp
A default build and install on Unix will normally build knowledge of the
directory where the grid shift files are installed into the PROJ library
(usually /usr/local/share/proj).  On Windows the library is normally built
thinking that C:PROJNAD is the installed directory for the grid shift files.
If the built in concept of the PROJ data directory is incorrect, the \fBPROJ_LIB\fP
environment can be defined with the correct directory.
.SS How do I debug problems with NAD27/NAD83 datum shifting?
.INDENT 0.0
.IP 1. 3
Verify that you have the binary files (eg. /usr/local/share/proj/conus)
installed on your system.  If not, see the previous question.
.IP 2. 3
Try a datum shifting operation in relative isolation, such as with the cs2cs
command listed above.  Do you get reasonable results?  If not it is likely
the grid shift files aren’t being found.  Perhaps you need to define
PROJ_LIB?
.IP 3. 3
The cs2cs command and the underlying pj_transform() API know how to do a
grid shift as part of a more complex coordinate transformation; however, it
is imperative that both the source and destination coordinate system be
defined with appropriate datum information.  That means that implicitly or
explicitly there must be a +datum= clause, a +nadgrids= clause or a
+towgs84= clause.  For instance
\fBcs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +ellps=WGS84\fP won’t work because defining the output
coordinate system as using the ellipse WGS84 isn’t the same as defining it
to use the datum WGS84 (use +datum=WGS84).  If either the input or output
are not identified as having a datum, the datum shifting (and ellipsoid
change) step is just quietly skipped!
.IP 4. 3
The \fBPROJ_DEBUG\fP environment can be defined (any value) to force extra output
from the PROJ library to stderr (the text console normally) with
information on what data files are being opened and in some cases why a
transformation fails.
.INDENT 3.0
.INDENT 3.5
.sp
.nf
.ft C
export PROJ_DEBUG=ON
cs2cs ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 3.0
.INDENT 3.5
\fBPROJ_DEBUG\fP support is not yet very mature in the PROJ library.
.UNINDENT
.UNINDENT
.IP 5. 3
The \fB\-v\fP flag to cs2cs can be useful in establishing more detail on what
parameters being used internally for a coordinate system.  This will include
expanding the definition of +datum clause.
.UNINDENT
.SS How do I use EPSG coordinate system codes with PROJ?
.sp
There is somewhat imperfect translation between 2d geographic and projected
coordinate system codes and PROJ descriptions of the coordinate system
available in the epsg definition file that normally lives in the proj/nad
directory.  If installed (it is installed by default on Unix), it is possible
to use EPSG numbers like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
% cs2cs \-v +init=epsg:26711
# \-\-\-\- From Coordinate System \-\-\-\-
#Universal Transverse Mercator (UTM)
#       Cyl, Sph
#       zone= south
# +init=epsg:26711 +proj=utm +zone=11 +ellps=clrk66 +datum=NAD27 +units=m
# +no_defs +nadgrids=conus,ntv1_can.dat
#\-\-\- following specified but NOT used
# +ellps=clrk66
# \-\-\-\- To Coordinate System \-\-\-\-
#Lat/long (Geodetic)
#
# +proj=latlong +datum=NAD27 +ellps=clrk66 +nadgrids=conus,ntv1_can.dat
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The proj/nad/epsg file can be browsed and searched in a text editor for
coordinate systems.  There are known to be problems with some coordinate
systems, and any coordinate systems with odd axes, a non\-greenwich prime
meridian or other quirkiness are unlikely to work properly.  Caveat Emptor!
.SS How do I use 3 parameter and 7 parameter datum shifting
.sp
Datum shifts can be approximated with 3 and 7 parameter transformations.  Their
use is more fully described in the
[wiki:GenParms#towgs84\-DatumtransformationtoWGS84 towgs84] parameter
discussion.
.SS Does PROJ work in different international numeric locales?
.sp
No.  PROJ makes extensive use of sprintf() and atof() internally to translate
numeric values.  If a locale is in effect that modifies formatting of numbers,
altering the role of commas and periods in numbers, then PROJ will not work.
This problem is common in some European locales.
.sp
On unix\-like platforms, this problem can be avoided by forcing the use of the
default numeric locale by setting the LC_NUMERIC environment variable to C.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ export LC_NUMERIC=C
$ proj ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
NOTE: Per ticket #49, in PROJ 4.7.0 and later pj_init() operates with locale
overridden to “C” to avoid most locale specific processing for applications
using the API.  Command line tools may still have issues.
.UNINDENT
.UNINDENT
.SS Changing Ellipsoid / Why can’t I convert from WGS84 to Google Earth / Virtual Globe Mercator?
.sp
The coordinate system definition for Google Earth, and Virtual Globe Mercator
is as follows, which uses a sphere as the earth model for the Mercator
projection.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0
     +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
But, if you do something like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +datum=WGS84
    +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0
                   +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
to convert between WGS84 and mercator on the sphere there will be substantial
shifts in the Y mercator coordinates.  This is because internally cs2cs is
having to adjust the lat/long coordinates from being on the sphere to being on
the WGS84 datum which has a quite differently shaped ellipsoid.
.sp
In this case, and many other cases using spherical projections, the desired
approach is to actually treat the lat/long locations on the sphere as if they
were on WGS84 without any adjustments when using them for converting to other
coordinate systems.  The solution is to “trick” PROJ into applying no change
to the lat/long values when going to (and through) WGS84.  This can be
accomplished by asking PROJ to use a null grid shift file for switching from
your spherical lat/long coordinates to WGS84.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cs2cs +proj=latlong +datum=WGS84 \e
    +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 \e
    +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note the strategic addition of \fI\%+nadgrids=@null\fP to the spherical projection
definition.
.sp
Similar issues apply with many other datasets distributed with projections
based on a spherical earth model \- such as many NASA datasets.  This coordinate
system is now known by the EPSG code 3857 and has in the past been known as
EPSG:3785 and EPSG:900913.  When using this coordinate system with GDAL/OGR it
is helpful to include the +wktext so the exact PROJ string will be preserved
in the WKT representation (otherwise key parameters like \fI+nadgrids=@null\fP will
be dropped):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0
           +units=m +nadgrids=@null +wktext  +no_defs
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Why do I get different results with 4.5.0 and 4.6.0?
.sp
The default datum application behavior changed with the 4.6.0 release.  PROJ
will now only apply a datum shift if both the source and destination coordinate
system have valid datum shift information.
.INDENT 0.0
.TP
.B From the PROJ 4.6.0 Release Notes (in NEWS):
.INDENT 7.0
.IP \(bu 2
MAJOR: Rework pj_transform() to avoid applying ellipsoid to ellipsoid
transformations as a datum shift when no datum info is available.
.UNINDENT
.UNINDENT
.SS How do I calculate distances/directions on the surface of the earth?
.sp
These are called geodesic calculations. There is a page about it here:
geodesic\&.
.SS What is the HEALPix projection and how can I use it?
.INDENT 0.0
.INDENT 2.5
[image]
.UNINDENT
.UNINDENT
.sp
The HEALPix projection is area preserving and can be used with a
spherical and ellipsoidal model.  It was initially developed for mapping cosmic
background microwave radiation.  The image below is the graphical
representation of the mapping and consists of eight isomorphic triangular
interrupted map graticules.  The north and south contains four in which
straight meridians converge polewards to a point and unequally spaced
horizontal parallels.  HEALPix provides a mapping in which points of equal
latitude and equally spaced longitude are mapped to points of equal latitude
and equally spaced longitude with the module of the polar interruptions. ||
.sp
To run a forward HEALPix projection on a unit sphere model, use the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=healpix +lon_0=0 +a=1 \-E <<EOF
0 0
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Output of the above command.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 0 0.00 0.00
.ft P
.fi
.UNINDENT
.UNINDENT
.SS What is the rHEALPix projection and how can I use it?
.INDENT 0.0
.INDENT 2.5
[image]
.UNINDENT
.UNINDENT
.sp
rHEALPix is a projection based on the HEALPix projection.  The implementation
of rHEALPix uses the HEALPix projection.  The rHEALPix combines the peaks of
the HEALPix into a square.  The square’s position can be translated and rotated
across the x\-axis which is a novel approach for the rHEALPix projection.  The
initial intention of using rHEALPix in the Spatial Computation Engine Science
Collaboration Environment (SCENZGrid).
.sp
To run a inverse rHEALPix projection on a WGS84 ellipsoidal model, use the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
proj +proj=rhealpix \-f \(aq%.2f\(aq \-I +lon_0=0 +a=1 +ellps=WGS84 +npole=0 +spole=0 \-E <<EOF
0 0.7853981633974483
EOF
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Where spole and npole are integers from the range of 0 to 3 inclusive and represent the positions of the north polar and south polar squares.
.sp
Output of above command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
0 0.7853981633974483 0.00 41.94
.ft P
.fi
.UNINDENT
.UNINDENT
.SS What options does PROJ allow for the shape of the Earth (geodesy)?
.sp
See \fI\%https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c\fP
for possible ellipse options. For example, putting \fB+ellps=WGS84\fP uses
the \fBWGS84\fP Earth shape.
.SS What if I want a spherical Earth?
.sp
Use \fB+ellps=sphere\fP\&.  See \fI\%https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c\fP
for the radius used in this case.
.SS How do I change the radius of the Earth?  How do I use PROJ for work on Mars?
.sp
You can supply explicit values for the semi minor and semi major axes instead
of using the symbolic “sphere” value.  Eg, if the radius were 2000000m:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+proj=laea +lon_0=\-40.000000 +lat_0=74.000000 +x_0=1000000 +y_0=1700000 +a=2000000 +b=2000000"
.ft P
.fi
.UNINDENT
.UNINDENT
.SS How do I do False Eastings and False Northings?
.sp
Use \fB+x_0\fP and \fB+y_0\fP in the projection string.
.SS Contributing
.sp
PROJ has a wide and varied user base. Some are highly skilled
geodesists with a deep knowledge of map projections and reference
systems, some are GIS software developers and others are GIS users. All
users, regardless of the profession or skill level, has the ability to
contribute to PROJ. Here’s a few suggestion on how:
.INDENT 0.0
.IP \(bu 2
Help PROJ\-users that is less experienced than yourself.
.IP \(bu 2
Write a bug report
.IP \(bu 2
Request a new feature
.IP \(bu 2
Write documentation for your favorite map projection
.IP \(bu 2
Fix a bug
.IP \(bu 2
Implement a new feature
.UNINDENT
.sp
In the following sections you can find some guidelines on how to
contribute. As PROJ is managed on GitHub most contributions require
that you have a GitHub account. Familiarity with
\fI\%issues\fP and the \fI\%GitHub
Flow\fP is an advantage.
.SS Help a fellow PROJ user
.sp
The main forum for support for PROJ is the mailing list. You can
subscribe to the mailing list
\fI\%here\fP and read the
archive \fI\%here\fP\&.
.sp
If you have questions about the usage of PROJ the mailing list is also
the place to go. Please \fIdo not\fP use the GitHub issue tracker as a
support forum. Your question is much more likely to be answered on the
mailing list, as many more people follow that than the issue tracker.
.SS Adding bug reports
.sp
Bug reports are handled in the \fI\%issue
tracker\fP on PROJ’s home on
GitHub. Writing a good bug report is not easy. But fixing a poorly
documented bug is not easy either, so please put in the effort it takes
to create a thorough bug report.
.sp
A good bug report includes at least:
.INDENT 0.0
.IP \(bu 2
A title that quickly explains the problem
.IP \(bu 2
A description of the problem and how it can be reproduced
.IP \(bu 2
Version of PROJ being used
.IP \(bu 2
Version numbers of any other relevant software being used, e.g.
operating system
.IP \(bu 2
A description of what already has been done to solve the problem
.UNINDENT
.sp
The more information that is given up front, the more likely it is that
a developer will find interest in solving the problem. You will probably
get follow\-up questions after submitting a bug report. Please answer
them in a timely manner if you have an interest in getting the issue
solved.
.sp
Finally, please only submit bug reports that are actually related to
PROJ. If the issue materializes in software that uses PROJ it is
likely a problem with that particular software. Make sure that it
actually is a PROJ problem before you submit an issue. If you can
reproduce the problem only by using tools from PROJ it is definitely a
problem with PROJ.
.SS Feature requests
.sp
Got an idea for a new feature in PROJ? Submit a thorough description
of the new feature in the \fI\%issue
tracker\fP\&. Please include any
technical documents that can help the developer make the new feature a
reality. An example of this could be a publicly available academic paper
that describes a new projection. Also, including a numerical test case
will make it much easier to verify that an implementation of your
requested feature actually works as you expect.
.sp
Note that not all feature requests are accepted.
.SS Write documentation
.sp
PROJ is in dire need of better documentation. Any contributions of
documentation are greatly appreciated. The PROJ documentation is
available on \fI\%proj4.org\fP\&. The website is generated
with \fI\%Sphinx\fP\&. Contributions to
the documentation should be made as \fI\%Pull
Requests\fP on GitHub.
.sp
If you intend to document one of PROJ’s supported projections please
use the \fI\%Mercator projection\fP
as a template.
.SS Code contributions
.sp
See Code contributions
.SS Legalese
.sp
Committers are the front line gatekeepers to keep the code base clear of
improperly contributed code. It is important to the PROJ users,
developers and the OSGeo foundation to avoid contributing any code to
the project without it being clearly licensed under the project license.
.sp
Generally speaking the key issues are that those providing code to be
included in the repository understand that the code will be released
under the MIT/X license, and that the person providing the code has the
right to contribute the code. For the committer themselves understanding
about the license is hopefully clear. For other contributors, the
committer should verify the understanding unless the committer is very
comfortable that the contributor understands the license (for instance
frequent contributors).
.sp
If the contribution was developed on behalf of an employer (on work
time, as part of a work project, etc) then it is important that an
appropriate representative of the employer understand that the code will
be contributed under the MIT/X license. The arrangement should be
cleared with an authorized supervisor/manager, etc.
.sp
The code should be developed by the contributor, or the code should be
from a source which can be rightfully contributed such as from the
public domain, or from an open source project under a compatible
license.
.sp
All unusual situations need to be discussed and/or documented.
.sp
Committers should adhere to the following guidelines, and may be
personally legally liable for improperly contributing code to the source
repository:
.INDENT 0.0
.IP \(bu 2
Make sure the contributor (and possibly employer) is aware of the
contribution terms.
.IP \(bu 2
Code coming from a source other than the contributor (such as adapted
from another project) should be clearly marked as to the original
source, copyright holders, license terms and so forth. This
information can be in the file headers, but should also be added to
the project licensing file if not exactly matching normal project
licensing (COPYING).
.IP \(bu 2
Existing copyright headers and license text should never be stripped
from a file. If a copyright holder wishes to give up copyright they
must do so in writing to the foundation before copyright messages are
removed. If license terms are changed it has to be by agreement
(written in email is ok) of the copyright holders.
.IP \(bu 2
Code with licenses requiring credit, or disclosure to users should be
added to COPYING.
.IP \(bu 2
When substantial contributions are added to a file (such as
substantial patches) the author/contributor should be added to the
list of copyright holders for the file.
.IP \(bu 2
If there is uncertainty about whether a change is proper to
contribute to the code base, please seek more information from the
project steering committee, or the foundation legal counsel.
.UNINDENT
.SS Additional Resources
.INDENT 0.0
.IP \(bu 2
\fI\%General GitHub documentation\fP
.IP \(bu 2
\fI\%GitHub pull request
documentation\fP
.UNINDENT
.SS Acknowledgements
.sp
The \fIcode contribution\fP section of this CONTRIBUTING file is inspired by
\fI\%PDAL’s\fP
and the \fIlegalese\fP section is modified from \fI\%GDAL committer
guidelines\fP
.SS Glossary
.INDENT 0.0
.TP
.B Pseudocylindrical Projection
Pseudocylindrical projections have the mathematical characteristics of
.sp
.ce

.ce 0
.sp
where the parallels of latitude are straight lines, like cylindrical
projections, but the meridians are curved toward the center as they
depart from the equator. This is an effort to minimize the distortion
of the polar regions inherent in the cylindrical projections.
.sp
Pseudocylindrical projections are almost exclusively used for small
scale global displays and, except for the Sinusoidal projection, only
derived for a spherical Earth. Because of the basic definition none of
the pseudocylindrical projections are conformal but many are equal
area.
.sp
To further reduce distortion, pseudocylindrical are often presented in
interrupted form that are made by joining several regions with
appropriate central meridians and false easting and clipping
boundaries. Interrupted Homolosine constructions are suited for showing
respective global land and oceanic regions, for example. To reduce the
lateral size of the map, some uses remove an irregular, North\-South
strip of the mid\-Atlantic region so that the western tip of Africa is
plotted north of the eastern tip of South America.
.UNINDENT
.SS License
.INDENT 0.0
.TP
.B Author
Frank Warmerdam
.TP
.B Contact
\fI\%warmerdam@pobox.com\fP
.TP
.B Date
2001
.UNINDENT
.sp
PROJ.4 has been placed under an MIT license. I believe this to be as close as
possible to public domain while satisfying those who say that a copyright
notice is required in some countries. The COPYING file read as follows:
.sp
All source, data files and other contents of the PROJ.4 package are available
under the following terms. Note that the PROJ 4.3 and earlier was “public
domain” as is common with US government work, but apparently this is not a well
defined legal term in many countries. I am placing everything under the
following MIT style license because I believe it is effectively the same as
public domain, allowing anyone to use the code as they wish, including making
proprietary derivatives.
.sp
Though I have put my own name as copyright holder, I don’t mean to imply I did
the work. Essentially all work was done by Gerald Evenden.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Copyright (c) 2000, Frank Warmerdam

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS References
.IP [AltamimiEtAl2002] 5
Altamimi, Z., P. Sillard, and C. Boucher (2002),
ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications,
J. Geophys. Res., 107(B10), 2214,
\fI\%doi:10.1029/2001JB000561\fP\&.
.IP [Bessel1825] 5
F. W. Bessel, 1825,
\fI\%The calculation of longitude and latitude from geodesic measurements\fP,
Astron. Nachr. \fB331\fP(8), 852–861 (2010),
translated by C. F. F. Karney and R. E. Deakin.
.IP [CalabrettaGreisen2002] 5
M. Calabretta and E. Greisen, 2002,
“Representations of celestial coordinates in FITS”.
Astronomy & Astrophysics 395, 3, 1077–1122.
.IP [ChanONeil1975] 5
F. Chan and E. M. O’Neill, 1975,
“Feasibility Study of a Quadrilateralized Spherical Cube Earth Data Base”,
Tech. Rep. EPRF 2\-75 (CSC), Environmental Prediction Research Facility.
.IP [Danielsen1989] 5
J. Danielsen, 1989,
\fI\%The area under the geodesic\fP,
Survey Review \fB30\fP(232), 61–66.
.IP [Deakin2004] 5
R.E. Deakin, 2004,
\fI\%The Standard and Abridged Molodensky Coordinate Transformation Formulae\fP\&.
.IP [EberHewitt1979] 5
L. E. Eber and R.P. Hewitt, 1979,
\fI\%Conversion algorithms for the CalCOFI station grid\fP,
California Cooperative Oceanic Fisheries Investigations Reports 20:135\-137.
.IP [Evenden1995] 5
G. I. Evenden, 1995,
\fI\%Cartograpic Projection Procedures for the UNIX Environment \-
A User’s Manual\fP\&.
.IP [Evenden2005] 5
G. I. Evenden, 2005,
\fI\%libproj4: A Comprehensive Library of Cartographic Projection Functions
(Preliminary Draft)\fP\&.
.IP [EversKnudsen2017] 5
K. Evers and T. Knudsen, 2017,
\fI\%Transformation pipelines for PROJ.4\fP,
FIG Working Week 2017 Proceedings.
.IP [GeodesicBib] 5
\fI\%A geodesic bibliography\fP\&.
.IP [GeodesicWiki] 5
The wikipedia page,
\fI\%Geodesics on an ellipsoid\fP\&.
.IP [Häkli2016] 5
P. Häkli, M. Lidberg, L. Jivall, et al, 2016,
\fI\%The NKG2008 GPS Campaign \- final transformation results and a new common Nordic reference frame\fP,
Journal of Geodetic Science, 6(1).
.IP [Helmert1880] 5
F. R. Helmert, 1880,
\fI\%Mathematical and Physical Theories of Higher Geodesy, Vol 1\fP,
(Teubner, Leipzig), Chaps. 5–7.
.IP [Karney2011] 5
C. F. F. Karney, 2011,
\fI\%Geodesics on an ellipsoid of revolution\fP;
\fI\%errata\fP\&.
.IP [Karney2013] 5
C. F. F. Karney, 2013,
\fI\%Algorithms for geodesics\fP,
J. Geodesy \fB87\fP(1) 43–55;
\fI\%addenda\fP\&.
.IP [Komsta2016] 5
L. Komsta, 2016,
\fI\%ATPOL geobotanical grid revisited \- a proposal of coordinate conversion
algorithms\fP,
Annales UMCS Sectio E Agricultura 71(1), 31–37.
.IP [LambersKolb2012] 5
M. Lambers and A. Kolb, 2012,
“Ellipsoidal Cube Maps for Accurate Rendering of Planetary\-Scale
Terrain Data”, Proc. Pacific Graphics (Short Papers).
.IP [ONeilLaubscher1976] 5
E. M. O’Neill and R. E. Laubscher, 1976,
“Extended Studies of a Quadrilateralized Spherical Cube Earth Data Base”,
Tech. Rep. NEPRF 3\-76 (CSC),
Naval Environmental Prediction Research Facility.
.IP [Snyder1987] 5
J. P. Snyder, 1987,
\fI\%Map Projections \- A Working Manual\fP\&.
U.S. Geological Survey professional paper 1395.
.IP [Snyder1993] 5
J. P. Snyder, 1993,
Flattening the Earth, Chicago and London, The University of Chicago press.
.IP [Steers1970] 5
J. A. Steers, 1970,
An introduction to the study of map projections (15th ed.),
London Univ. Press, p. 229.
.IP [Verey2017] 5
M. Verey, 2017,
\fI\%Theoretical analysis and practical consequences of adopting an ATPOL
grid model as a conical projection, defining the conversion of plane
coordinates to the WGS\-84 ellipsoid\fP,
Fragmenta Floristica et Geobotanica Polonica (preprint submitted).
.IP [Vincenty1975] 5
T. Vincenty, 1975,
\fI\%Direct and inverse solutions of geodesics on the ellipsoid with
application of nested equations\fP,
Survey Review \fB23\fP(176), 88–93.
.IP [WeberMoore2013] 5
E. D. Weber and T.J. Moore, 2013,
\fI\%Corrected Conversion Algorithms For The CalCOFI Station Grid And Their
Implementation In Several Computer Languages\fP,
California Cooperative Oceanic Fisheries Investigations Reports 54.
.IP [Zajac1978] 5
A. Zajac, 1978,
“Atlas of distribution of vascular plants in Poland (ATPOL)”,
Taxon 27(5/6), 481–484.
.SH MAILING LIST
.sp
The PROJ mailing list can be found at \fI\%http://lists.maptools.org/mailman/listinfo/proj\fP
.SH INDICES AND TABLES
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
Gerald Evenden, Frank Warmerdam, and others
.SH COPYRIGHT
1983-2018
.\" Generated by docutils manpage writer.
.