diff options
Diffstat (limited to '_sources/usage')
| -rw-r--r-- | _sources/usage/differences.rst.txt | 147 | ||||
| -rw-r--r-- | _sources/usage/ellipsoids.rst.txt | 159 | ||||
| -rw-r--r-- | _sources/usage/environmentvars.rst.txt | 96 | ||||
| -rw-r--r-- | _sources/usage/index.rst.txt | 21 | ||||
| -rw-r--r-- | _sources/usage/network.rst.txt | 107 | ||||
| -rw-r--r-- | _sources/usage/projections.rst.txt | 163 | ||||
| -rw-r--r-- | _sources/usage/quickstart.rst.txt | 69 | ||||
| -rw-r--r-- | _sources/usage/transformation.rst.txt | 346 |
8 files changed, 1108 insertions, 0 deletions
diff --git a/_sources/usage/differences.rst.txt b/_sources/usage/differences.rst.txt new file mode 100644 index 00000000..3bc2f54d --- /dev/null +++ b/_sources/usage/differences.rst.txt @@ -0,0 +1,147 @@ +.. _differences: + +================================================================================ +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 :c:func:`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 +:option:`+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 :math:`\lambda=290^{\circ}` is a full +rotation of the circle larger than :math:`\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 :file:`proj_def.dat` +------------------------------- + +Before PROJ 6, the :file:`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 :ref:`deformation<deformation>` +------------------------------------------------------------------ +.. _differences_deformation: + + +Reversed order of operation +........................... + +In the initial version of the of :ref:`deformation<deformation>` operation +the time span between :math:`t_{obs}` and :math:`t_c` was determined by the +expression + +.. math:: + + dt = t_c - t_{obs} + +With version 6.0.0 this has been reversed in order to behave similarly to +the :ref:`Helmert operation<helmert>`, which determines time differences as + +.. math:: + + 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 :option:`+inv` +to forward steps involving the deformation operation. Similarly +:option:`+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 +:option:`+dt` has been added for that purpose. The new parameter is mutually +exclusive with :option:`+t_epoch`. :option:`+dt` is used when deformation +for a set amount of time is needed and :option:`+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. diff --git a/_sources/usage/ellipsoids.rst.txt b/_sources/usage/ellipsoids.rst.txt new file mode 100644 index 00000000..cd4b0c43 --- /dev/null +++ b/_sources/usage/ellipsoids.rst.txt @@ -0,0 +1,159 @@ +.. _ellipsoids: + +================================================================================ +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. + + +.. figure:: ../../images/general_ellipsoid.png + :width: 500 px + :align: center + :alt: 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: + +Ellipsoid size parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +R=<value> + + Radius of the sphere, :math:`R`. + +.. option:: +a=<value> + + Semi-major axis of the ellipsoid, :math:`a`. + +.. _ellipsoid_shape_parameters: + +Ellipsoid shape parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +rf=<value> + + Reverse flattening of the ellipsoid, :math:`1/f`. + +.. option:: +f=<value> + + Flattening of the ellipsoid, :math:`f`. + +.. option:: +es=<value> + + Eccentricity squared, :math:`e^2`. + +.. option:: +e=<value> + + Eccentricity, :math:`e`. + +.. option:: +b=<value> + + Semi-minor axis, :math:`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: + +Ellipsoid spherification parameters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. option:: +R_A=<value> + + A sphere with the same surface area as the ellipsoid. + +.. option:: +R_V=<value> + + A sphere with the same volume as the ellipsoid. + +.. option:: +R_a=<value> + + A sphere with :math:`R = (a + b)/2` (arithmetic mean). + +.. option:: +R_g=<value> + + A sphere with :math:`R = \sqrt{ab}` (geometric mean). + +.. option:: +R_h=<value> + + A sphere with :math:`R = 2ab/(a+b)` (harmonic mean). + +.. option:: +R_lat_a=<phi> + + A sphere with :math:`R` being the arithmetic mean of the corresponding + ellipsoid at latitude :math:`\phi`. + +.. option:: +R_lat_g=<phi> + + A sphere with :math:`R` being the geometric mean of the corresponding + ellipsoid at latitude :math:`\phi`. + +If :option:`+R` is given as size parameter, any shape and spherification +parameters given are ignored. + +.. _ellipsoid_definitions: + +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`` + +.. _ellipsoid_transformation_examples: + +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 (:math:`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 + diff --git a/_sources/usage/environmentvars.rst.txt b/_sources/usage/environmentvars.rst.txt new file mode 100644 index 00000000..0439d918 --- /dev/null +++ b/_sources/usage/environmentvars.rst.txt @@ -0,0 +1,96 @@ +.. _environmentvars: + +================================================================================ +Environment variables +================================================================================ + +PROJ can be controlled by setting environment variables. Most users will +have a use for the :envvar:`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= + +.. envvar:: PROJ_LIB + + The location of PROJ :doc:`resource files<../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 + :func:`proj_context_set_search_paths` in the :file:`proj.h` API header. + +.. versionchanged:: 6.1.0 + + Starting with PROJ version 6.1.0, the paths set by + :func:`proj_context_set_search_paths` will have priority over the + :envvar:`PROJ_LIB` to allow for multiple versions of PROJ + resource files on your system without conflicting. + + +.. envvar:: PROJ_AUX_DB + + .. versionadded:: 8.1.0 + + To set the path to one or several auxiliary SQLite3 databases of structure + identical to the main :file:`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. + + +.. envvar:: 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. + +.. envvar:: PROJ_NETWORK + + .. versionadded:: 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 :c:func:`proj_context_set_enable_network` function can + be used. + +.. envvar:: PROJ_NETWORK_ENDPOINT + + .. versionadded:: 7.0.0 + + Define the endpoint of the CDN storage. Normally defined through the + :file:`proj.ini` configuration file locale in :envvar:`PROJ_LIB`. + Alternatively, the :c:func:`proj_context_set_url_endpoint` function can + be used. + +.. envvar:: PROJ_CURL_CA_BUNDLE + + .. versionadded:: 7.2.0 + + Define a custom path to the CA Bundle file. This can be useful if `curl` + and :envvar:`PROJ_NETWORK` are enabled. Alternatively, the + :c:func:`proj_curl_set_ca_bundle_path` function can be used. diff --git a/_sources/usage/index.rst.txt b/_sources/usage/index.rst.txt new file mode 100644 index 00000000..4bb75121 --- /dev/null +++ b/_sources/usage/index.rst.txt @@ -0,0 +1,21 @@ +.. _usage: + +================================================================================ +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. + + +.. toctree:: + :maxdepth: 1 + + quickstart + projections + transformation + ellipsoids + environmentvars + differences + network diff --git a/_sources/usage/network.rst.txt b/_sources/usage/network.rst.txt new file mode 100644 index 00000000..37a32d34 --- /dev/null +++ b/_sources/usage/network.rst.txt @@ -0,0 +1,107 @@ +.. _network: + +================================================================================ +Network capabilities +================================================================================ + +.. versionadded:: 7.0 + +PROJ 7.0 has introduced, per :ref:`rfc4`, 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_grids: + +CDN of GeoTIFF grids +-------------------- + +Files are accessed by default through a CDN (Content Delivery Network), +accessible through https://cdn.proj.org, that contains :ref:`geodetictiffgrids` +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 :ref:`proj-ini` + - defining the :envvar:`PROJ_NETWORK` environment variable to ON + - or using the :cpp:func:`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 :cpp:func:`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 +:ref:`resource files are looked for <resource_file_paths>`, PROJ will then +attempt at loading the file from a remote server, which defaults to +https://cdn.proj.org in :ref:`proj-ini`. This location can be changed with +the :envvar:`PROJ_NETWORK_ENDPOINT` environment variable or with +:cpp:func:`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, :file:`cache.db`, stored in the +:ref:`PROJ user writable directory <user_writable_directory>`. + +This local caching is enabled by default (can be changed in :ref:`proj-ini` or +with :cpp:func:`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 :ref:`proj-ini` or +with :cpp:func:`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 +:ref:`PROJ user writable directory <user_writable_directory>` by using the +:cpp:func:`proj_is_download_needed` and :cpp:func:`proj_download_file` functions. + +Download utility +---------------- + +:ref:`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 <https://aws.amazon.com/opendata/public-datasets/>`_. +CDN services are provided by the AWS Public Dataset team via +`CloudFront <https://aws.amazon.com/cloudfront/>`_ diff --git a/_sources/usage/projections.rst.txt b/_sources/usage/projections.rst.txt new file mode 100644 index 00000000..1f2e504f --- /dev/null +++ b/_sources/usage/projections.rst.txt @@ -0,0 +1,163 @@ +.. _projections_intro: + +================================================================================ +Cartographic projection +================================================================================ + +The foundation of PROJ is the large number of +:doc:`projections<../operations/projections/index>` 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 :doc:`projections<../operations/projections/index>`. + + ========== ================================================================ + 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 :program:`cs2cs` or :program:`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 :program:`cs2cs` or :program:`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:: + :program:`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 +:doc:`equidistant cylindrical<../operations/projections/eqc>` +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 :program:`cs2cs` does honour prime meridians but +the :program:`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 :program:`proj` command line + utility. + + diff --git a/_sources/usage/quickstart.rst.txt b/_sources/usage/quickstart.rst.txt new file mode 100644 index 00000000..85e7aa95 --- /dev/null +++ b/_sources/usage/quickstart.rst.txt @@ -0,0 +1,69 @@ +.. _quickstart: + +================================================================================ +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 +:doc:`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 :doc:`Mercator projection<../operations/projections/merc>` 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 :program:`proj` we can convert the geodetic coordinates to projected space: + +:: + + $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + +If called as above :program:`proj` will be in interactive mode, letting you +type the input data manually and getting a response presented on screen. +:program:`proj` works as any UNIX filter though, which means that you can also +pipe data to the utility, for instance by using the :program:`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 :program:`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 +:program:`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 :program:`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 diff --git a/_sources/usage/transformation.rst.txt b/_sources/usage/transformation.rst.txt new file mode 100644 index 00000000..785ca65e --- /dev/null +++ b/_sources/usage/transformation.rst.txt @@ -0,0 +1,346 @@ +.. _transformation: + +================================================================================ +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* / :program:`cs2cs` / :c:func:`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 +:cite:`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. Convert the geographic coordinates to 3D cartesian geocentric coordinates +3. Apply a Helmert transformation from ED50 to ETRS89 +4. Convert back from cartesian to geographic coordinates +5. Finally project the geographic coordinates to UTM zone 32 planar coordinates. + + +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 :cite:`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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. _cs2cs_specific_options: + + ============ ============================================================== + 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, + :program:`cs2cs` has been reworked to use :c:func:`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 :program:`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 :program:`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 +(:file:`.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 :program:`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 :file:`/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 +:file:`ntv2_0.gsb` file if available, otherwise it would +fallback to using the :file:`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 :file:`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 :ref:`transformation_grids`. + +Caveats +................................................................................ + +* Where grids overlap (such as conus and :file:`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 |