update with results of commit https://github.com/OSGeo/PROJ/commit/53c07a8bd211b7aee4bc07a9c6726005504b7181gh-pages

11 files changed, 828 insertions, 0 deletions

diff --git a/_sources/operations/conversions/axisswap.rst.txt b/_sources/operations/conversions/axisswap.rst.txt
new file mode 100644
index 00000000..b8d606ff
--- /dev/null
+++ b/_sources/operations/conversions/axisswap.rst.txt
@@ -0,0 +1,56 @@
+.. _axisswap:
+
+================================================================================
+Axis swap
+================================================================================
+
+.. versionadded:: 5.0.0
+
+Change the order and sign of 2,3 or 4 axes.
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | axisswap                                               |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 2D, 3D or 4D                                           |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Any                                                    |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Any                                                    |
++---------------------+--------------------------------------------------------+
+
+
+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.
+
+Usage
+################################################################################
+
+Reversing the order of the axes::
+
+    +proj=axisswap +order=4,3,2,1
+
+Swapping the first two axes (x and y)::
+
+    +proj=axisswap +order=2,1,3,4
+
+The direction, or sign, of an axis can be changed by adding a minus in
+front of the axis-number::
+
+    +proj=axisswap +order=1,-2,3,4
+
+It is only necessary to specify the axes that are affected by the swap
+operation::
+
+    +proj=axisswap +order=2,1
+
+Parameters
+################################################################################
+
+.. option:: +order=<list>
+
+    Ordered comma-separated list of axis, e.g. *+order=2,1,3,4*.
+    Adding a minus in front of an axis number results in a change of direction
+    for that axis, e.g. southward instead of northward.
+
+    *Required.*
diff --git a/_sources/operations/conversions/cart.rst.txt b/_sources/operations/conversions/cart.rst.txt
new file mode 100644
index 00000000..239b1772
--- /dev/null
+++ b/_sources/operations/conversions/cart.rst.txt
@@ -0,0 +1,38 @@
+.. _cart:
+
+================================================================================
+Geodetic to cartesian conversion
+================================================================================
+
+.. versionadded:: 5.0.0
+
+Convert geodetic coordinates to cartesian coordinates (in the forward path).
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | cart                                                   |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 3D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                   |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Geocentric cartesian coordinates                       |
++---------------------+--------------------------------------------------------+
+
+This conversion converts geodetic coordinate values (longitude, latitude,
+elevation above ellipsoid) to their geocentric (X, Y, Z) representation, where
+the first axis (X) points from the Earth centre to the point of longitude=0,
+latitude=0, the second axis (Y) points from the Earth centre to the point of
+longitude=90, latitude=0 and the third axis (Z) points to the North pole.
+
+Usage
+################################################################################
+
+Convert geodetic coordinates to GRS80 cartesian coordinates::
+
+    echo 17.7562015132 45.3935192042 133.12 2017.8 | cct +proj=cart +ellps=GRS80
+    4272922.1553   1368283.0597  4518261.3501     2017.8000
+
+Parameters
+################################################################################
+
+.. include:: ../options/ellps.rst
diff --git a/_sources/operations/conversions/geoc.rst.txt b/_sources/operations/conversions/geoc.rst.txt
new file mode 100644
index 00000000..6ee32ea6
--- /dev/null
+++ b/_sources/operations/conversions/geoc.rst.txt
@@ -0,0 +1,75 @@
+.. _geoc:
+
+================================================================================
+Geocentric Latitude
+================================================================================
+
+.. versionadded:: 5.0.0
+
+Convert from Geodetic Latitude to Geocentric Latitude (in the forward path).
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | geoc                                                   |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 2D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                   |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Geocentric angular coordinates                         |
++---------------------+--------------------------------------------------------+
+
+The geodetic (or geographic) latitude (also called planetographic latitude
+in the context of non-Earth bodies) is the angle between the equatorial plane
+and the normal (vertical) to the ellipsoid surface at the considered point.
+The geodetic latitude is what is normally used everywhere in PROJ when angular
+coordinates are expected or produced.
+
+The geocentric latitude (also called planetocentric latitude in the context of
+non-Earth bodies) is the angle between the equatorial plane and a line joining
+the body centre to the considered point.
+
+.. image:: ./images/geocentric_latitude.png
+   :align: center
+   :scale: 100%
+   :alt:   Geocentric latitude
+
+
+.. note::
+
+    This conversion must be distinguished from the :ref:`cart`
+    which converts geodetic coordinates to geocentric coordinates in the cartesian
+    domain.
+
+Mathematical definition
+#######################
+
+The formulas describing the conversion are taken from :cite:`Snyder1987`
+(equation 3-28)
+
+Let :math:`\phi'` to be the geocentric latitude and :math:`\phi`  the
+geodetic latitude, then
+
+.. math::
+
+  \phi' = \arctan \left[ (1 - e^2) \tan \left( \phi \right) \right]
+
+The geocentric latitude is consequently lesser (in absolute value) than the geodetic
+latitude, except at the equator and the poles where they are equal.
+
+On a sphere, they are always equal.
+
+Usage
+################################################################################
+
+Converting from geodetic latitude to geocentric latitude::
+
+    +proj=geoc +ellps=GRS80
+
+Converting from geocentric latitude to geodetic latitude::
+
+    +proj=pipeline +step +proj=geoc +inv +ellps=GRS80
+
+Parameters
+################################################################################
+
+.. include:: ../options/ellps.rst
diff --git a/_sources/operations/conversions/index.rst.txt b/_sources/operations/conversions/index.rst.txt
new file mode 100644
index 00000000..b335c2ac
--- /dev/null
+++ b/_sources/operations/conversions/index.rst.txt
@@ -0,0 +1,23 @@
+.. _conversions_list:
+
+================================================================================
+Conversions
+================================================================================
+
+Conversions are coordinate operations in which both coordinate reference systems
+are based on the same datum. In PROJ projections are differentiated from
+conversions.
+
+.. toctree::
+   :maxdepth: 1
+
+   axisswap
+   cart
+   geoc
+   latlon
+   noop
+   pop
+   push
+   set
+   topocentric
+   unitconvert
diff --git a/_sources/operations/conversions/latlon.rst.txt b/_sources/operations/conversions/latlon.rst.txt
new file mode 100644
index 00000000..25e2a143
--- /dev/null
+++ b/_sources/operations/conversions/latlon.rst.txt
@@ -0,0 +1,46 @@
+.. _latlon:
+
+********************************************************************************
+Lat/long (Geodetic alias)
+********************************************************************************
+
+Passes geodetic coordinates through unchanged.
+
++---------------------+--------------------------------------------------------+
+| **Aliases**         | latlon, latlong, lonlat, longlat                       |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 2D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                   |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Geodetic coordinates                                   |
++---------------------+--------------------------------------------------------+
+
+.. note:: Can not be used with the :program:`proj` application.
+
+
+Parameters
+################################################################################
+
+No parameters will affect the output of the operation if used on it's own.
+However, the parameters below can be used in a declarative manner when used with
+:program:`cs2cs` or in a :ref:`transformation pipeline <pipeline>` .
+
+.. include:: ../options/ellps.rst
+
+.. option:: +datum=<value>
+
+    Declare the datum used with the coordinates. Available options are:
+    ``WGS84``, ``GGRS87``, ``NAD38``, ``NAD27``, ``potsdam``, ``carthage``,
+    ``hermannskogel``, ``ire65``, ``nzgd49``, ``OSGB336``.
+
+    .. note::
+
+        The ``+datum`` option is primarily available to support the legacy
+        use of PROJ.4 strings as CRS descriptors and should in most cases
+        be avoided.
+
+.. option:: +towgs84=<list>
+
+    A list of three or seven :ref:`Helmert <helmert>` parameters that maps
+    the input coordinates to the WGS84 datum.
diff --git a/_sources/operations/conversions/noop.rst.txt b/_sources/operations/conversions/noop.rst.txt
new file mode 100644
index 00000000..a35b2b58
--- /dev/null
+++ b/_sources/operations/conversions/noop.rst.txt
@@ -0,0 +1,28 @@
+.. _noop:
+
+================================================================================
+No operation
+================================================================================
+
+.. versionadded:: 6.1.0
+
+Pass a coordinate through unchanged.
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | noop                                                   |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 4D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Any                                                    |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Any                                                    |
++---------------------+--------------------------------------------------------+
+
+The no operation is a dummy operation that returns whatever is passed to it
+as seen in this example::
+
+    $ echo 12 34 56 78 | cct +proj=noop
+      12.0000        34.0000       56.0000       78.0000
+
+The operation has no options and default options will not affect the output.
+
diff --git a/_sources/operations/conversions/pop.rst.txt b/_sources/operations/conversions/pop.rst.txt
new file mode 100644
index 00000000..2c6d264a
--- /dev/null
+++ b/_sources/operations/conversions/pop.rst.txt
@@ -0,0 +1,94 @@
+.. _pop:
+
+================================================================================
+Pop coordinate value to pipeline stack
+================================================================================
+
+.. versionadded:: 6.0.0
+
+Retrieve components of a coordinate that was saved in a previous pipeline step.
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | pop                                                    |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 4D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Any                                                    |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Any                                                    |
++---------------------+--------------------------------------------------------+
+
+This operations makes it possible to retrieve coordinate components that was
+saved in previous pipeline steps. A retrieved coordinate component is loaded,
+or *popped*, from a memory stack that is part of a :ref:`pipeline<pipeline>`.
+The pipeline coordinate stack is inspired by the stack data structure that is
+commonly used in computer science. There's four stacks available: One four each
+coordinate dimension. The dimensions, or coordinate components, are numbered
+1--4. It is only possible to move data to and from the stack within the same
+coordinate component number. Values can be saved to the stack by using the
+:ref:`push operation<push>`.
+
+If the pop operation is used by itself, e.g. not in a pipeline, it will
+function as a no-operation that passes the coordinate through unchanged.
+Similarly, if no coordinate component is available on the stack to be popped
+the operation does nothing.
+
+Examples
+################################################################################
+
+A common use of the :ref:`push<push>` and pop operations is in 3D
+:ref:`Helmert<helmert>` transformations where only the horizontal components
+are needed. This is often the case when combining heights from a legacy
+vertical reference with a modern geocentric reference. Below is a an example of
+such a transformation, where the horizontal part is transformed with a Helmert
+operation but the vertical part is kept exactly as the input was.
+
+::
+
+   $ echo 12 56 12.3 2020 | cct +proj=pipeline  \
+   +step +proj=push +v_3                        \
+   +step +proj=cart +ellps=GRS80                \
+   +step +proj=helmert +x=3000 +y=1000 +z=2000  \
+   +step +proj=cart +ellps=GRS80 +inv           \
+   +step +proj=pop +v_3                         \
+
+    12.0056753463   55.9866540552       12.3000     2000.0000
+
+Note that the third coordinate component in the output is the same as the input.
+
+The same transformation without the push and pop operations would look like this::
+
+   $ echo 12 56 12.3 2020 | cct +proj=pipeline  \
+   +step +proj=cart +ellps=GRS80                \
+   +step +proj=helmert +x=3000 +y=1000 +z=2000  \
+   +step +proj=cart +ellps=GRS80 +inv           \
+
+         12.0057        55.9867     3427.7404     2000.0000
+
+Here the vertical component is adjusted significantly.
+
+Parameters
+################################################################################
+
+.. option:: +v_1
+
+   Retrieves the first coordinate component from the pipeline stack
+
+.. option:: +v_2
+
+   Retrieves the second coordinate component from the pipeline stack
+
+.. option:: +v_3
+
+   Retrieves the third coordinate component from the pipeline stack
+
+.. option:: +v_4
+
+   Retrieves the fourth coordinate component from the pipeline stack
+
+
+Further reading
+################################################################################
+
+#. `Stack data structure on Wikipedia <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>`_
+
diff --git a/_sources/operations/conversions/push.rst.txt b/_sources/operations/conversions/push.rst.txt
new file mode 100644
index 00000000..a1f4423a
--- /dev/null
+++ b/_sources/operations/conversions/push.rst.txt
@@ -0,0 +1,93 @@
+.. _push:
+
+================================================================================
+Push coordinate value to pipeline stack
+================================================================================
+
+.. versionadded:: 6.0.0
+
+Save components of a coordinate from one step of a pipeline and make it
+available for retrieving in another pipeline step.
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | push                                                   |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 4D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Any                                                    |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Any                                                    |
++---------------------+--------------------------------------------------------+
+
+This operations allows for components of coordinates to be saved for
+application in a later step. A saved coordinate component is moved, or
+*pushed*, to a memory stack that is part of a :ref:`pipeline<pipeline>`. The
+pipeline coordinate stack is inspired by the stack data structure that is
+commonly used in computer science. There's four stacks available: One four each
+coordinate dimension. The dimensions, or coordinate components, are numbered
+1--4. It is only possible to move data to and from the stack within the same
+coordinate component number. Values can be moved off the stack again by using
+the :ref:`pop operation<pop>`.
+
+If the push operation is used by itself, e.g. not in a pipeline, it will
+function as a no-operation that passes the coordinate through unchanged.
+
+Examples
+################################################################################
+
+A common use of the push and :ref:`pop<pop>` operations is in 3D
+:ref:`Helmert<helmert>` transformations where only the horizontal components
+are needed. This is often the case when combining heights from a legacy
+vertical reference with a modern geocentric reference. Below is a an example of
+such a transformation, where the horizontal part is transformed with a Helmert
+operation but the vertical part is kept exactly as the input was.
+
+::
+
+   $ echo 12 56 12.3 2020 | cct +proj=pipeline  \
+   +step +proj=push +v_3                        \
+   +step +proj=cart +ellps=GRS80                \
+   +step +proj=helmert +x=3000 +y=1000 +z=2000  \
+   +step +proj=cart +ellps=GRS80 +inv           \
+   +step +proj=pop +v_3                         \
+
+    12.0056753463   55.9866540552       12.3000     2000.0000
+
+Note that the third coordinate component in the output is the same as the input.
+
+The same transformation without the push and pop operations would look like this::
+
+   $ echo 12 56 12.3 2020 | cct +proj=pipeline  \
+   +step +proj=cart +ellps=GRS80                \
+   +step +proj=helmert +x=3000 +y=1000 +z=2000  \
+   +step +proj=cart +ellps=GRS80 +inv           \
+
+         12.0057        55.9867     3427.7404     2000.0000
+
+Here the vertical component is adjusted significantly.
+
+Parameters
+################################################################################
+
+.. option:: +v_1
+
+   Stores the first coordinate component on the pipeline stack
+
+.. option:: +v_2
+
+   Stores the second coordinate component on the pipeline stack
+
+.. option:: +v_3
+
+   Stores the third coordinate component on the pipeline stack
+
+.. option:: +v_4
+
+   Stores the fourth coordinate component on the pipeline stack
+
+
+Further reading
+################################################################################
+
+#. `Stack data structure on Wikipedia <https://en.wikipedia.org/wiki/Stack_(abstract_data_type)>`_
+
diff --git a/_sources/operations/conversions/set.rst.txt b/_sources/operations/conversions/set.rst.txt
new file mode 100644
index 00000000..635d08d3
--- /dev/null
+++ b/_sources/operations/conversions/set.rst.txt
@@ -0,0 +1,76 @@
+.. _set:
+
+================================================================================
+Set coordinate value
+================================================================================
+
+.. versionadded:: 7.0.0
+
+Set component(s) of a coordinate to a fixed value.
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | set                                                    |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 4D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Any                                                    |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Any                                                    |
++---------------------+--------------------------------------------------------+
+
+This operations allows for components of coordinates to be set to a fixed value.
+This may be useful in :ref:`pipeline<pipeline>` when a step requires some
+component, typically an elevation or a date, to be set to a fixed value.
+
+Example
+################################################################################
+
+In the ETRS89 to Dutch RD with NAP height transformation, the used ellipsoidal
+height for the Helmert transformation is not the NAP height, but the height is
+set to 0 m. This is an unconventional trick to get the same results as when the
+effect of the Helmert transformation is included in the horizontal NTv2 grid.
+For the forward transformation from ETRS89 to RD with NAP height, we need to set
+the ellipsoidal ETRS89 height for the Helmert transformation to the equivalent
+of 0 m NAP. This is 43 m for the centre of the Netherlands and this value can
+be used as an approximation elsewhere (the effect of this approximation is
+below 1 mm for the horizontal coordinates, in an area up to hundreds of km
+outside the Netherlands).
+
+The ``+proj=set +v_3=0`` close to the end of the pipeline is to make it usable in
+the reverse direction.
+
+::
+
+   $ cct -t 0 -d 4 +proj=pipeline \
+        +step +proj=unitconvert +xy_in=deg +xy_out=rad \
+        +step +proj=axisswap +order=2,1 \
+        +step +proj=vgridshift +grids=nlgeo2018.gtx \
+        +step +proj=push +v_3 \
+        +step +proj=set +v_3=43 \
+        +step +proj=cart +ellps=GRS80 \
+        +step +proj=helmert +x=-565.7346 +y=-50.4058 +z=-465.2895 +rx=-0.395023 +ry=0.330776 +rz=-1.876073 +s=-4.07242 +convention=coordinate_frame +exact \
+        +step +proj=cart +inv +ellps=bessel \
+        +step +proj=hgridshift +inv +grids=rdcorr2018.gsb,null \
+        +step +proj=sterea +lat_0=52.156160556 +lon_0=5.387638889 +k=0.9999079 +x_0=155000 +y_0=463000 +ellps=bessel \
+        +step +proj=set +v_3=0 \
+        +step +proj=pop +v_3
+
+Parameters
+################################################################################
+
+.. option:: +v_1=value
+
+   Set the first coordinate component to the specified value
+
+.. option:: +v_2=value
+
+   Set the second coordinate component to the specified value
+
+.. option:: +v_3=value
+
+   Set the third coordinate component to the specified value
+
+.. option:: +v_4=value
+
+   Set the fourth coordinate component to the specified value
+
diff --git a/_sources/operations/conversions/topocentric.rst.txt b/_sources/operations/conversions/topocentric.rst.txt
new file mode 100644
index 00000000..14019965
--- /dev/null
+++ b/_sources/operations/conversions/topocentric.rst.txt
@@ -0,0 +1,117 @@
+.. _topocentric:
+
+================================================================================
+Geocentric to topocentric conversion
+================================================================================
+
+.. versionadded:: 8.0.0
+
+Convert geocentric coordinates to topocentric coordinates (in the forward path).
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | topocentric                                            |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 3D                                                     |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Geocentric cartesian coordinates                       |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Topocentric cartesian coordinates                      |
++---------------------+--------------------------------------------------------+
+
+This operation converts geocentric coordinate values (X, Y, Z) to topocentric
+(E/East, N/North, U/Up) values. This is also sometimes known as the ECEF (Earth
+Centered Earth Fixed) to ENU conversion.
+
+Topocentric coordinates are expressed in a frame whose East and North axis form
+a local tangent plane to the Earth's ellipsoidal surface fixed to a specific
+location (the topocentric origin), and the Up axis points upwards along the
+normal to that plane.
+
+.. image:: ./images/ECEF_ENU_Longitude_Latitude_relationships.png
+   :align: center
+   :scale: 100%
+   :alt:   ENU coordinate frame
+
+..
+  Source : https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates#/media/File:ECEF_ENU_Longitude_Latitude_relationships.svg
+  Public domain
+..
+
+The topocentric origin is a required parameter of the conversion, and can be
+expressed either as geocentric coordinates (``X_0``, ``Y_0`` and ``Z_0``) or
+as geographic coordinates (``lat_0``, ``lon_0``, ``h_0``).
+
+When conversion between geographic and topocentric coordinates is desired, the
+topocentric conversion must be preceded by the :ref:`cart` conversion to
+perform the initial geographic to geocentric coordinates conversion.
+
+The formulas used come from the "Geocentric/topocentric conversions" paragraph
+of :cite:`IOGP2018`. ``+proj=topocentric`` alone corresponds to the ``EPSG:9836``
+conversion method, ``+proj=cart`` followed by ``+proj=topocentric`` corresponds
+to ``EPSG:9837``.
+
+Usage
+################################################################################
+
+Convert geocentric coordinates to topocentric coordinates, with the topocentric
+origin specified in geocentric coordinates::
+
+    echo 3771793.968 140253.342 5124304.349 2020 | \
+        cct -d 3 +proj=topocentric +ellps=WGS84 +X_0=3652755.3058 +Y_0=319574.6799 +Z_0=5201547.3536
+
+    -189013.869    -128642.040     -4220.171     2020.0000
+
+Convert geographic coordinates to topocentric coordinates, with the topocentric
+origin specified in geographic coordinates::
+
+    echo 2.12955 53.80939444 73 2020 | cct -d 3 +proj=pipeline \
+        +step +proj=cart +ellps=WGS84 \
+        +step +proj=topocentric +ellps=WGS84 +lon_0=5 +lat_0=55 +h_0=200
+
+    -189013.869    -128642.040     -4220.171     2020.0000
+
+
+Parameters
+################################################################################
+
+.. include:: ../options/ellps.rst
+
+Topocentric origin described as geocentric coordinates
+------------------------------------------------------
+
+.. note::
+
+    The below options are mutually exclusive with the ones to express the origin as geographic coordinates.
+
+.. option:: +X_0=<value>
+
+    Geocentric X value of the topocentric origin (in metre)
+
+.. option:: +Y_0=<value>
+
+    Geocentric Y value of the topocentric origin (in metre)
+
+.. option:: +Z_0=<value>
+
+    Geocentric Z value of the topocentric origin (in metre)
+
+Topocentric origin described as geographic coordinates
+------------------------------------------------------
+
+.. note::
+
+    The below options are mutually exclusive with the ones to express the origin as geocentric coordinates.
+
+.. option:: +lat_0=<value>
+
+    Latitude of topocentric origin (in degree)
+
+.. option:: +lon_0=<value>
+
+    Longitude of topocentric origin (in degree)
+
+.. option:: +h_0=<value>
+
+    Ellipsoidal height of topocentric origin (in metre)
+
+    *Defaults to 0.0.*
diff --git a/_sources/operations/conversions/unitconvert.rst.txt b/_sources/operations/conversions/unitconvert.rst.txt
new file mode 100644
index 00000000..13ca9228
--- /dev/null
+++ b/_sources/operations/conversions/unitconvert.rst.txt
@@ -0,0 +1,182 @@
+.. _unitconvert:
+
+================================================================================
+Unit conversion
+================================================================================
+
+.. versionadded:: 5.0.0
+
+Convert between various distance, angular and time units.
+
++---------------------+--------------------------------------------------------+
+| **Alias**           | unitconvert                                            |
++---------------------+--------------------------------------------------------+
+| **Domain**          | 2D, 3D or 4D                                           |
++---------------------+--------------------------------------------------------+
+| **Input type**      | Any                                                    |
++---------------------+--------------------------------------------------------+
+| **Output type**     | Any                                                    |
++---------------------+--------------------------------------------------------+
+
+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 `unitconvert` operation takes care
+of that.
+
+Many North American systems are defined with coordinates in feet. For example
+in Vermont::
+
+    +proj=pipeline
+    +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k_0=0.999964286 +x_0=500000.00001016 +y_0=0
+    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+
+Often when working with GNSS data the timestamps are presented in GPS-weeks,
+but when the data transformed with the `helmert` operation timestamps are
+expected to be in units of decimalyears. This can be fixed with `unitconvert`::
+
+    +proj=pipeline
+    +step +proj=unitconvert +t_in=gps_week +t_out=decimalyear
+    +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ...
+
+Parameters
+################################################################################
+
+.. option:: +xy_in=<unit> or <conversion_factor>
+
+    Horizontal input units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units. `<conversion_factor>` is the conversion factor
+    from the input unit to metre for linear units, or to radian for angular
+    units.
+
+.. option:: +xy_out=<unit> or <conversion_factor>
+
+    Horizontal output units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units. `<conversion_factor>` is the conversion factor
+    from the output unit to metre for linear units, or to radian for angular
+    units.
+
+.. option:: +z_in=<unit> or <conversion_factor>
+
+    Vertical output units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units. `<conversion_factor>` is the conversion factor
+    from the input unit to metre for linear units, or to radian for angular
+    units.
+
+.. option:: +z_out=<unit> or <conversion_factor>
+
+    Vertical output units. See :ref:`distance_units` and :ref:`angular_units`
+    for a list of available units.  `<conversion_factor>` is the conversion factor
+    from the output unit to metre for linear units, or to radian for angular
+    units.
+
+.. option:: +t_in=<unit>
+
+    Temporal input units. See :ref:`time_units` for a list of available units.
+
+.. option:: +t_out=<unit>
+
+    Temporal output units. See :ref:`time_units` for a list of available units.
+
+.. _distance_units:
+
+Distance units
+###############################################################################
+
+In the table below all distance units supported by PROJ are listed.
+The same list can also be produced on the command line with :program:`proj` or
+:program:`cs2cs`, by adding the `-lu` flag when calling the utility.
+
++----------+---------------------------------+
+| Label    | Name                            |
++==========+=================================+
+|     km   | Kilometer                       |
++----------+---------------------------------+
+|      m   | Meter                           |
++----------+---------------------------------+
+|     dm   | Decimeter                       |
++----------+---------------------------------+
+|     cm   | Centimeter                      |
++----------+---------------------------------+
+|     mm   | Millimeter                      |
++----------+---------------------------------+
+|    kmi   | International Nautical Mile     |
++----------+---------------------------------+
+|     in   | International Inch              |
++----------+---------------------------------+
+|     ft   | International Foot              |
++----------+---------------------------------+
+|     yd   | International Yard              |
++----------+---------------------------------+
+|     mi   | International Statute Mile      |
++----------+---------------------------------+
+|   fath   | International Fathom            |
++----------+---------------------------------+
+|     ch   | International Chain             |
++----------+---------------------------------+
+|   link   | International Link              |
++----------+---------------------------------+
+|  us-in   | U.S. Surveyor's Inch            |
++----------+---------------------------------+
+|  us-ft   | U.S. Surveyor's Foot            |
++----------+---------------------------------+
+|  us-yd   | U.S. Surveyor's Yard            |
++----------+---------------------------------+
+|  us-ch   | U.S. Surveyor's Chain           |
++----------+---------------------------------+
+|  us-mi   | U.S. Surveyor's Statute Mile    |
++----------+---------------------------------+
+| ind-yd   | Indian Yard                     |
++----------+---------------------------------+
+| ind-ft   | Indian Foot                     |
++----------+---------------------------------+
+| ind-ch   | Indian Chain                    |
++----------+---------------------------------+
+
+.. _angular_units:
+
+Angular units
+###############################################################################
+
+.. versionadded:: 5.2.0
+
+In the table below all angular units supported by PROJ `unitconvert` are listed.
+
++----------+---------------------------------+
+| Label    | Name                            |
++==========+=================================+
+|    deg   | Degree                          |
++----------+---------------------------------+
+|   grad   | Grad                            |
++----------+---------------------------------+
+|    rad   | Radian                          |
++----------+---------------------------------+
+
+.. _time_units:
+
+Time units
+###############################################################################
+
+In the table below all time units supported by PROJ are listed.
+
+    .. note::
+
+        When converting time units from a date-only format (`yyyymmdd`), PROJ
+        assumes a time value of 00:00 midnight.  When converting time units
+        to a date-only format, PROJ rounds to the *nearest* date at 00:00
+        midnight.  That is, any time values less than 12:00 noon will round to
+        00:00 on the same day.  Time values greater than or equal to 12:00 noon
+        will round to 00:00 on the following day.
+
+
++--------------+-----------------------------+
+| Label        | Name                        |
++==============+=============================+
+| mjd          | Modified Julian date        |
++--------------+-----------------------------+
+| decimalyear  | Decimal year                |
++--------------+-----------------------------+
+| gps_week     | GPS Week                    |
++--------------+-----------------------------+
+| yyyymmdd     | Date in yyyymmdd format     |
++--------------+-----------------------------+
+