diff options
Diffstat (limited to 'man/man1/proj4.1')
| -rw-r--r-- | man/man1/proj4.1 | 10758 |
1 files changed, 0 insertions, 10758 deletions
diff --git a/man/man1/proj4.1 b/man/man1/proj4.1 deleted file mode 100644 index 97b2473e..00000000 --- a/man/man1/proj4.1 +++ /dev/null @@ -1,10758 +0,0 @@ -.\" 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. -. |