From a3f43744feec86272fe532124679d3a013ef9a8c Mon Sep 17 00:00:00 2001 From: PROJ deploybot Date: Tue, 22 Mar 2022 20:00:06 +0000 Subject: update with results of commit https://github.com/OSGeo/PROJ/commit/53c07a8bd211b7aee4bc07a9c6726005504b7181 --- usage/differences.html | 281 ++++++++++++++++++++++++++ usage/ellipsoids.html | 343 ++++++++++++++++++++++++++++++++ usage/environmentvars.html | 239 +++++++++++++++++++++++ usage/index.html | 152 +++++++++++++++ usage/network.html | 237 ++++++++++++++++++++++ usage/projections.html | 366 ++++++++++++++++++++++++++++++++++ usage/quickstart.html | 188 ++++++++++++++++++ usage/transformation.html | 477 +++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 2283 insertions(+) create mode 100644 usage/differences.html create mode 100644 usage/ellipsoids.html create mode 100644 usage/environmentvars.html create mode 100644 usage/index.html create mode 100644 usage/network.html create mode 100644 usage/projections.html create mode 100644 usage/quickstart.html create mode 100644 usage/transformation.html (limited to 'usage') diff --git a/usage/differences.html b/usage/differences.html new file mode 100644 index 00000000..590fa7ac --- /dev/null +++ b/usage/differences.html @@ -0,0 +1,281 @@ + + + + + + + Known differences between versions — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Known differences between versions

+

Once in a while, a new version of PROJ causes changes in the existing behavior. +In this section we track deliberate changes to PROJ that break from previous +behavior. Most times that will be caused by a bug fix. Unfortunately, some bugs +have existed for so long that their faulty behavior is relied upon by software +that uses PROJ.

+

Behavioural changes caused by new bugs are not tracked here, as they should be +fixed in later versions of PROJ.

+
+

Version 4.6.0

+

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.

+

The PROJ 4.6.0 Release Notes states

+
+

MAJOR: Rework pj_transform() to avoid applying ellipsoid to ellipsoid +transformations as a datum shift when no datum info is available.

+
+
+
+

Version 5.0.0

+
+

Longitude wrapping when using custom central meridian

+

By default PROJ wraps output longitudes in the range -180 to 180. Previous to +PROJ 5, this was handled incorrectly when a custom central meridian was set with ++lon_0. This caused a change in sign on the resulting easting as seen +below:

+
$ proj +proj=merc +lon_0=110
+-70 0
+-20037508.34    0.00
+290 0
+20037508.34     0.00
+
+
+

From PROJ 5 on onwards, the same input now results in same coordinates, as seen +from the example below where PROJ 5 is used:

+
$ proj +proj=merc +lon_0=110
+-70 0
+-20037508.34    0.00
+290 0
+-20037508.34    0.00
+
+
+

The change is made on the basis that \(\lambda=290^{\circ}\) is a full +rotation of the circle larger than \(\lambda=-70^{\circ}\) and hence +should return the same output for both.

+

Adding the +over flag to the projection definition provides +the old behavior.

+
+
+
+

Version 6.0.0

+
+

Removal of proj_def.dat

+

Before PROJ 6, the proj_def.dat was used to provide general and per-projection +parameters, when +no_defs was not specified. It has now been removed. In case, +no ellipsoid or datum specification is provided in the PROJ string, the +default ellipsoid is GRS80 (was WGS84 in previous PROJ versions).

+
+
+

Changes to deformation

+
+

Reversed order of operation

+

In the initial version of the of deformation operation +the time span between \(t_{obs}\) and \(t_c\) was determined by the +expression

+
+\[dt = t_c - t_{obs}\]
+

With version 6.0.0 this has been reversed in order to behave similarly to +the Helmert operation, which determines time differences as

+
+\[dt = t_{obs} - t_c\]
+

Effectively this means that the direction of the operation has been reversed, +so that what in PROJ 5 was a forward operation is now an inverse operation and +vice versa.

+

Pipelines written for PROJ 5 can be migrated to PROJ 6 by adding +inv +to forward steps involving the deformation operation. Similarly ++inv should be removed from inverse steps to be compatible with +PROJ 6.

+
+
+

Removed +t_obs parameter

+

The +t_obs parameter was confusing for users since it effectively +overwrote the observation time in input coordinates. To make it more clear +what is the operation is doing, users are now required to directly specify +the time span for which they wish to apply a given deformation. The parameter ++dt has been added for that purpose. The new parameter is mutually +exclusive with +t_epoch. +dt is used when deformation +for a set amount of time is needed and +t_epoch is used (in +conjunction with the observation time of the input coordinate) when +deformation from a specific epoch to the observation time is needed.

+
+
+
+
+

Version 6.3.0

+
+

projinfo

+

Before PROJ 6.3.0, WKT1:GDAL was implicitly calling --boundcrs-to-wgs84, to +add a TOWGS84[] node in some cases. This is no longer the case.

+
+
+
+

Version 7.0.0

+
+

proj

+

Removed -ld option from application, since it promoted use of deprecated +parameters like +towgs and +datum.

+
+
+

cs2cs

+

Removed -ld option from application, since it promoted use of deprecated +parameters like +towgs and +datum.

+
+
+

UTF-8 adoption

+

The value of all path, filenames passed to PROJ through function calls, PROJ +strings or environment variables should be encoded in UTF-8.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/usage/ellipsoids.html b/usage/ellipsoids.html new file mode 100644 index 00000000..afa8a63f --- /dev/null +++ b/usage/ellipsoids.html @@ -0,0 +1,343 @@ + + + + + + + Ellipsoids — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Ellipsoids

+

An ellipsoid is a mathematically defined surface which approximates the geoid: +the surface of the Earth’s gravity field, which is approximately the same as +mean sea level.

+
+Global and local fitting of the ellipsoid +
+

Global and local fitting of the ellipsoid

+
+
+

A complete ellipsoid definition comprises a size (primary) and a shape (secondary) +parameter.

+
+

Ellipsoid size parameters

+
+
++R=<value>
+

Radius of the sphere, \(R\).

+
+ +
+
++a=<value>
+

Semi-major axis of the ellipsoid, \(a\).

+
+ +
+
+

Ellipsoid shape parameters

+
+
++rf=<value>
+

Reverse flattening of the ellipsoid, \(1/f\).

+
+ +
+
++f=<value>
+

Flattening of the ellipsoid, \(f\).

+
+ +
+
++es=<value>
+

Eccentricity squared, \(e^2\).

+
+ +
+
++e=<value>
+

Eccentricity, \(e\).

+
+ +
+
++b=<value>
+

Semi-minor axis, \(b\).

+
+ +

The ellipsoid definition may be augmented with a spherification flag, turning +the ellipsoid into a sphere with features defined by the ellipsoid.

+
+
+

Ellipsoid spherification parameters

+
+
++R_A=<value>
+

A sphere with the same surface area as the ellipsoid.

+
+ +
+
++R_V=<value>
+

A sphere with the same volume as the ellipsoid.

+
+ +
+
++R_a=<value>
+

A sphere with \(R = (a + b)/2\) (arithmetic mean).

+
+ +
+
++R_g=<value>
+

A sphere with \(R = \sqrt{ab}\) (geometric mean).

+
+ +
+
++R_h=<value>
+

A sphere with \(R = 2ab/(a+b)\) (harmonic mean).

+
+ +
+
++R_lat_a=<phi>
+

A sphere with \(R\) being the arithmetic mean of the corresponding +ellipsoid at latitude \(\phi\).

+
+ +
+
++R_lat_g=<phi>
+

A sphere with \(R\) being the geometric mean of the corresponding +ellipsoid at latitude \(\phi\).

+
+ +

If +R is given as size parameter, any shape and spherification +parameters given are ignored.

+
+
+

Built-in ellipsoid definitions

+

The ellps=xxx parameter provides both size and shape for a number of +built-in ellipsoid definitions.

+
+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

ellps

Parameters

Datum name

GRS80

a=6378137.0 rf=298.257222101

GRS 1980(IUGG, 1980)

airy

a=6377563.396 b=6356256.910

Airy 1830

bessel

a=6377397.155 rf=299.1528128

Bessel 1841

clrk66

a=6378206.4 b=6356583.8

Clarke 1866

intl

a=6378388.0 rf=297.

International 1909 (Hayford)

WGS60

a=6378165.0 rf=298.3

WGS 60

WGS66

a=6378145.0 rf=298.25

WGS 66

WGS72

a=6378135.0 rf=298.26

WGS 72

WGS84

a=6378137.0 rf=298.257223563

WGS 84

sphere

a=6370997.0 b=6370997.0

Normal Sphere (r=6370997)

+
+

If size and shape are given as ellps=xxx, later shape and size parameters +are are taken into account as modifiers for the built-in ellipsoid definition.

+

While this may seem strange, it is in accordance with historical PROJ +behavior. It can e.g. be used to define coordinates on the ellipsoid +scaled to unit semimajor axis by specifying +ellps=xxx +a=1

+
+
+

Transformation examples

+

Spherical earth with radius 7000km:

+
proj=laton R=7000000
+
+
+

Using the GRS80 ellipsoid:

+
proj=laton ellps=GRS80
+
+
+

Expressing ellipsoid by semi-major axis and reverse flattening (\(1/f\)):

+
proj=laton a=6378137.0 rf=298.25
+
+
+

Spherical earth based on volume of ellipsoid

+
proj=laton a=6378137.0 rf=298.25 +R_V
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/usage/environmentvars.html b/usage/environmentvars.html new file mode 100644 index 00000000..57327597 --- /dev/null +++ b/usage/environmentvars.html @@ -0,0 +1,239 @@ + + + + + + + Environment variables — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Environment variables

+

PROJ can be controlled by setting environment variables. Most users will +have a use for the PROJ_LIB.

+

On UNIX systems environment variables can be set for a shell-session with:

+
$ export VAR="some variable"
+
+
+

or it can be set for just one command line call:

+
$ VAR="some variable" ./cmd
+
+
+

Environment variables on UNIX are usually removed with the unset command:

+
$ unset VAR
+
+
+

On windows systems environment variables can be set in the command line with:

+
> set VAR="some variable"
+
+
+

VAR will be available for the entire session, unless it is unset. This is +done by setting the variable with no content:

+
> set VAR=
+
+
+
+
+PROJ_LIB
+

The location of PROJ resource files.

+

Starting with PROJ 6, multiple directories can be specified. On Unix, they +should be separated by the colon (:) character. on Windows, by the semi-colon (;) +character.

+

PROJ is hardcoded to look for resource files +in other locations as well, amongst those are the +installation directory (usually share/proj under the PROJ +installation root) and the current folder.

+

You can also set the location of the resource files using +proj_context_set_search_paths() in the proj.h API header.

+
+ +
+

Changed in version 6.1.0: Starting with PROJ version 6.1.0, the paths set by +proj_context_set_search_paths() will have priority over the +PROJ_LIB to allow for multiple versions of PROJ +resource files on your system without conflicting.

+
+
+
+PROJ_AUX_DB
+
+

New in version 8.1.0.

+
+

To set the path to one or several auxiliary SQLite3 databases of structure +identical to the main proj.db database and that can contain additional +object (CRS, transformation, …) definitions. If several paths are +provided, they must be separated by the colon (:) character on Unix, and +on Windows, by the semi-colon (;) character.

+
+ +
+
+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, with 3 being the most +verbose setting.

+
+ +
+
+PROJ_NETWORK
+
+

New in version 7.0.0.

+
+

If set to ON, enable the capability to use remote grids stored on CDN +(Content Delivery Network) storage, when grids are not available locally. +Alternatively, the proj_context_set_enable_network() function can +be used.

+
+ +
+
+PROJ_NETWORK_ENDPOINT
+
+

New in version 7.0.0.

+
+

Define the endpoint of the CDN storage. Normally defined through the +proj.ini configuration file locale in PROJ_LIB. +Alternatively, the proj_context_set_url_endpoint() function can +be used.

+
+ +
+
+PROJ_CURL_CA_BUNDLE
+
+

New in version 7.2.0.

+
+

Define a custom path to the CA Bundle file. This can be useful if curl +and PROJ_NETWORK are enabled. Alternatively, the +proj_curl_set_ca_bundle_path() function can be used.

+
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/usage/index.html b/usage/index.html new file mode 100644 index 00000000..56120262 --- /dev/null +++ b/usage/index.html @@ -0,0 +1,152 @@ + + + + + + + Using PROJ — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Using PROJ

+

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.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/usage/network.html b/usage/network.html new file mode 100644 index 00000000..c3a3dce6 --- /dev/null +++ b/usage/network.html @@ -0,0 +1,237 @@ + + + + + + + Network capabilities — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Network capabilities

+
+

New in version 7.0.

+
+

PROJ 7.0 has introduced, per PROJ RFC 4: Remote access to grids and GeoTIFF grids, the capability to work with grid files +that are not installed on the local machine where PROJ is executed.

+

This enables to transparently download the parts of grids that are needed to +perform a coordinate transformation.

+
+

CDN of GeoTIFF grids

+

Files are accessed by default through a CDN (Content Delivery Network), +accessible through https://cdn.proj.org, that contains Geodetic TIFF grids (GTG) +datasets which are mirrored and managed by the +https://github.com/OSGeo/PROJ-data/ GitHub project. +Files in the CDN are designed to be used by PROJ 7 or later, but any software +project wishing to use the CDN for shifting support are encouraged to +participate in the project and leverage the CDN.

+
+
+

How to enable network capabilities ?

+

This capability assumes that PROJ has been build against libcurl, and that +the user authorizes network access.

+

Authorizing network access can be done in multiple ways:

+
+
    +

  • enabling / uncommenting the network = on line of proj.ini

    • +

  • defining the PROJ_NETWORK environment variable to ON

    • +

  • or using the proj_context_set_enable_network() with a +enabled = TRUE value.

    • +
+
+
+

Note

+

Instead of using the libcurl implementation, an application using the PROJ +API can supply its own network implementation through C function callbacks +with proj_context_set_network_callbacks(). Enabling network use +must still be done with one of the above mentioned method.

+
+
+
+

Setting endpoint

+

When this is enabled, and a grid is not found in the various locations where +resource files are looked for, PROJ will then +attempt at loading the file from a remote server, which defaults to +https://cdn.proj.org in proj.ini. This location can be changed with +the PROJ_NETWORK_ENDPOINT environment variable or with +proj_context_set_url_endpoint().

+
+
+

Caching

+

To avoid repeated access to network, a local cache of downloaded chunks of grids +is implemented as SQLite3 database, cache.db, stored in the +PROJ user writable directory.

+

This local caching is enabled by default (can be changed in proj.ini or +with proj_grid_cache_set_enable()). The default maximum size of the +cache is 300 MB, which is more than half of the total size of grids available, +at time of writing. This size can also be customized in proj.ini or +with proj_grid_cache_set_max_size()

+
+
+

Download API

+

When on-demand loading of grid is not desirable, the PROJ API also offers the +capability to download whole grids in the +PROJ user writable directory by using the +proj_is_download_needed() and proj_download_file() functions.

+
+
+

Download utility

+

projsync is a tool for downloading resource files.

+
+
+

Mirroring

+

If you are able, you are encouraged to mirror the grids via AWS S3 command line:

+
aws s3 sync s3://cdn.proj.org .
+
+
+

If direct S3 access is not possible, you can also use wget to locally mirror the +data:

+
wget --mirror https://cdn.proj.org/
+
+
+
+
+

Acknowledgments

+

The s3://cdn.proj.org bucket is hosted by the +Amazon Public Datasets program. +CDN services are provided by the AWS Public Dataset team via +CloudFront

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/usage/projections.html b/usage/projections.html new file mode 100644 index 00000000..12ab1246 --- /dev/null +++ b/usage/projections.html @@ -0,0 +1,366 @@ + + + + + + + Cartographic projection — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Cartographic projection

+

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.

+

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.

+
+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Description

+a

Semimajor radius of the ellipsoid axis

+axis

Axis orientation

+b

Semiminor radius of the ellipsoid axis

+ellps

Ellipsoid name (see proj -le)

+k

Scaling factor (deprecated)

+k_0

Scaling factor

+lat_0

Latitude of origin

+lon_0

Central meridian

+lon_wrap

Center longitude to use for wrapping (see below)

+over

Allow longitude output outside -180 to 180 range, disables +wrapping (see below)

+pm

Alternate prime meridian (typically a city name, see below)

+proj

Projection name (see proj -l)

+units

meters, US survey feet, etc.

+vunits

vertical units.

+x_0

False easting

+y_0

False northing

+
+

In the sections below most of the parameters are explained in details.

+
+

Units

+

Horizontal units can be specified using the +units keyword with a symbolic +name for a unit (i.e. us-ft). Alternatively the translation to meters can be +specified with the +to_meter keyword (i.e. 0.304800609601219 for US feet). The +-lu argument to cs2cs or proj can be used to list +symbolic unit names. The default unit for projected coordinates is the meter. +A few special projections deviate from this behavior, most notably the +latlong pseudo-projection that returns degrees.

+

Vertical (Z) units can be specified using the +vunits keyword with a +symbolic name for a unit (i.e. us-ft). Alternatively the translation to +meters can be specified with the +vto_meter keyword (i.e. 0.304800609601219 +for US feet). The -lu argument to cs2cs or proj 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.

+
+

Note

+

proj does not handle vertical units at all and hence the ++vto_meter argument will be ignored.

+
+

Scaling of output units can be done by applying the +k_0 argument. The +returned coordinates are scaled by the value assigned with the +k_0 +parameter.

+
+
+

False Easting/Northing

+

Virtually all coordinate systems allow for the presence of a false easting +(+x_0) and northing (+y_0). 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.

+
+
+

Longitude Wrapping

+

By default PROJ wraps output longitudes in the range -180 to 180. The +over +switch can be used to disable the default wrapping which is done at a low level +in pj_inv(). 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.

+

The +lon_wrap option can be used to provide an alternative means of doing +longitude wrapping within pj_transform(). The argument to this option is a +center longitude. So +lon_wrap=180 means wrap longitudes in the range 0 to +360. Note that +over does not disable +lon_wrap.

+
+
+

Prime Meridian

+

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.

+

Currently prime meridian declarations are only utilized by the +pj_transform() API call, not the pj_inv() and pj_fwd() calls. +Consequently the user utility cs2cs does honour prime meridians but +the proj user utility ignores them.

+

The following predeclared prime meridian names are supported. These can be +listed using with cs2cs -lm.

+
+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Meridian

Longitude

greenwich

0dE

lisbon

9d07’54.862”W

paris

2d20’14.025”E

bogota

74d04’51.3”E

madrid

3d41’16.48”W

rome

12d27’8.4”E

bern

7d26’22.5”E

jakarta

106d48’27.79”E

ferro

17d40’W

brussels

4d22’4.71”E

stockholm

18d3’29.8”E

athens

23d42’58.815”E

oslo

10d43’22.5”E

+
+

Example of use. The location long=0, lat=0 in the greenwich based lat/long +coordinates is translated to lat/long coordinates with Madrid as the prime +meridian.

+
cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid
+0 0
+3d41'16.48"E    0dN 0.000
+
+
+
+
+

Axis orientation

+

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:

+
    +

  • “e” - Easting

    • +

  • “w” - Westing

    • +

  • “n” - Northing

    • +

  • “s” - Southing

    • +

  • “u” - Up

    • +

  • “d” - Down

    • +
+

They can be combined in +axis in forms like:

+
    +

  • +axis=enu - the default easting, northing, elevation.

    • +

  • +axis=neu - northing, easting, up - useful for “lat/long” geographic +coordinates, or south orientated transverse mercator.

    • +

  • +axis=wnu - westing, northing, up - some planetary coordinate systems +have “west positive” coordinate systems

    • +
+
+

Note

+

The +axis argument does not work with the proj command line +utility.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/usage/quickstart.html b/usage/quickstart.html new file mode 100644 index 00000000..6c8b338e --- /dev/null +++ b/usage/quickstart.html @@ -0,0 +1,188 @@ + + + + + + + Quick start — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Quick start

+

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 +Geodetic transformation.

+

A proj-strings holds the parameters of a given coordinate transformation, e.g.

+
+proj=merc +lat_ts=56.5 +ellps=GRS80
+
+
+

I.e. a proj-string consists of a projection specifier, +proj, 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 merc in the above +example.

+

By using the above projection definition as parameters for the command line +utility proj we can convert the geodetic coordinates to projected space:

+
$ proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+
+
+

If called as above proj will be in interactive mode, letting you +type the input data manually and getting a response presented on screen. +proj works as any UNIX filter though, which means that you can also +pipe data to the utility, for instance by using the echo command:

+
$ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80
+3399483.80      752085.60
+
+
+

PROJ also comes bundled with the cs2cs 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 +cs2cs:

+
$ 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
+
+
+

Notice the +to parameter that separates the source and destination +projection definitions.

+

If you happen to know the EPSG identifiers for the two coordinates reference +systems you are transforming between you can use those with cs2cs:

+
$ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832
+231950.54      1920310.71 0.00
+
+
+

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

+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/usage/transformation.html b/usage/transformation.html new file mode 100644 index 00000000..8d9e757a --- /dev/null +++ b/usage/transformation.html @@ -0,0 +1,477 @@ + + + + + + + Geodetic transformation — PROJ 9.0.0 documentation + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Geodetic transformation

+

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.

+

In PROJ, two frameworks for geodetic transformations exists, the +PROJ 4.x/5.x / cs2cs / pj_transform() +framework and the transformation pipelines 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].

+

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:

+
    +

  1. Back-project the UTM coordinates to geographic coordinates

    2. +

  2. Convert the geographic coordinates to 3D cartesian geocentric coordinates

    3. +

  3. Apply a Helmert transformation from ED50 to ETRS89

    4. +

  4. Convert back from cartesian to geographic coordinates

    5. +

  5. Finally project the geographic coordinates to UTM zone 32 planar coordinates.

    6. +
+
+

Transformation pipelines

+

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.

+

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 +pipeline, 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.

+

As a first example, let us take a look at the iconic +geodetic → Cartesian → Helmert → geodetic case (steps 2 to 4 in the example in +the introduction). In PROJ it can be implemented as

+
proj=pipeline
+step proj=cart ellps=intl
+step proj=helmert convention=coordinate_frame
+     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
+
+
+

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.

+
proj=pipeline
+step init=./s45b.pol:s45b_tc32
+step proj=utm inv ellps=intl zone=32
+step proj=cart ellps=intl
+step proj=helmert convention=coordinate_frame
+      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
+
+
+

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 [Altamimi2002], +except the epoch which is the epoch of the transformation. +The last step in the pipeline is converting the +coordinate timestamps back to GPS weeks.

+
proj=pipeline
+step proj=unitconvert t_in=gps_week t_out=decimalyear
+step proj=helmert convention=coordinate_frame
+     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
+     t_epoch=1988.0
+step proj=unitconvert t_in=decimalyear t_out=gps_week
+
+
+
+
+

PROJ 4.x/5.x paradigm

+
+
++++ + + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

Description

+datum

Datum name (see proj -ld)

+geoidgrids

Filename of GTX grid file to use for vertical datum transforms

+nadgrids

Filename of NTv2 grid file to use for datum transforms

+towgs84

3 or 7 term datum transform parameters

+to_meter

Multiplier to convert map units to 1.0m

+vto_meter

Vertical conversion to meters

+
+
+

Warning

+

This section documents the behavior of PROJ 4.x and 5.x. In PROJ 6.x, +cs2cs has been reworked to use proj_create_crs_to_crs() internally, +with late binding capabilities, and thus is no longer constrained to using +WGS84 as a pivot (also called as early binding method). +When cs2cs of PROJ 6 is used with PROJ.4 expanded strings to describe the CRS, +including +towgs84, +nadgrids and +geoidgrids, it will generally give +the same results as earlier PROJ versions. When used with AUTHORITY:CODE +CRS descriptions, it may return different results.

+
+

The cs2cs framework in PROJ 4 and 5 delivers a subset of the geodetic transformations available +with the pipeline framework. Coordinate transformations done in this framework +were 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 +towgs84, ++nadgrids and +geoidgrids. +An inverse transform exists for all three and is applied if +specified in the input proj-string. The most common is +towgs84, 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, +geoidgrids +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

+

In contrast to the transformation pipeline framework, transformations with the +cs2cs framework in PROJ 4 and 5 were expressed as two separate proj-strings. One proj-string to +WGS84 and one from WGS84. Together they form the mapping from the source +coordinate reference system to the destination coordinate reference system. +When used with the cs2cs the source and destination CRS’s are separated by the +special +to parameter.

+

The following example demonstrates converting from the Greek GGRS87 datum +to WGS84 with the +towgs84 parameter.

+
cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62
+    +to +proj=latlong +datum=WGS84
+20 35
+20d0'5.467"E    35d0'9.575"N 0.000
+
+
+

With PROJ 6, you can simply use the following:

+
+

Note

+

With PROJ 6, the order of coordinates for EPSG geographic coordinate +reference systems is latitude first, longitude second.

+
+
cs2cs "GGRS87" "WGS 84"
+35 20
+35d0'9.575"N    20d0'5.467"E 0.000
+
+cs2cs EPSG:4121 EPSG:4326
+35 20
+35d0'9.575"N    20d0'5.467"E 0.000
+
+
+

The EPSG database provides this example for transforming from WGS72 to WGS84 +using an approximated 7 parameter transformation.

+
cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \
+    +to +proj=latlong +datum=WGS84
+4 55
+4d0'0.554"E     55d0'0.09"N 0.000
+
+
+

With PROJ 6, you can simply use the following (note the reversed order for +latitude and longitude)

+
cs2cs "WGS 72" "WGS 84"
+55 4
+55d0'0.09"N 4d0'0.554"E 0.000
+
+cs2cs EPSG:4322 EPSG:4326
+55 4
+55d0'0.09"N 4d0'0.554"E 0.000
+
+
+
+
+

Grid Based Datum Adjustments

+

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.

+

PROJ supports use of grid files for shifting between various reference frames. +The grid shift table formats are CTable, NTv1 (the old Canadian format), and NTv2 +(.gsb - the new Canadian and Australian format).

+

The text in this section is based on the cs2cs framework. Gridshifting is off +course also possible with the pipeline framework. The major difference between the +two is that the cs2cs framework is limited to grid mappings to WGS84, whereas with +transformation pipelines it is possible to perform grid shifts between any two +reference frames, as long as a grid exists.

+

Use of grid shifts with cs2cs is specified using the +nadgrids +keyword in a coordinate system definition. For example:

+
% cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \
+    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+-111 50
+EOF
+111d0'2.952"W   50d0'0.111"N 0.000
+
+
+

In this case the /usr/local/share/proj/ntv1_can.dat grid shift file was +loaded, and used to get a grid shift value for the selected point.

+

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.

+
cs2cs +proj=latlong +ellps=clrk66 \
+          +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \
+    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+-111 44
+EOF
+111d0'2.788"W   43d59'59.725"N 0.000
+
+
+
+

Skipping Missing Grids

+

The special prefix @ 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 +ntv2_0.gsb file if available, otherwise it would +fallback to using the ntv1_can.dat file.

+
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \
+    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+-111 50
+EOF
+111d0'3.006"W   50d0'0.103"N 0.000
+
+
+
+
+

The null Grid

+

A special null grid shift file is distributed with PROJ. +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.

+
cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
+    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+-111 45
+EOF
+111d0'3.006"W   50d0'0.103"N 0.000
+
+cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \
+    +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF
+-111 44
+-111 55
+EOF
+111d0'2.788"W   43d59'59.725"N 0.000
+111dW   55dN 0.000
+
+
+

For more information see the chapter on Other transformation grids.

+
+
+

Caveats

+
    +

  • 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, +nadgrids=ntv1_can.dat,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

    • +

  • 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

    • +
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file -- cgit v1.2.3