Move 'Coordinate operations' to top level of docs [skip ci]

6 files changed, 205 insertions, 0 deletions

diff --git a/docs/source/operations/conversions/axisswap.rst b/docs/source/operations/conversions/axisswap.rst
new file mode 100644
index 00000000..ddaad075
--- /dev/null
+++ b/docs/source/operations/conversions/axisswap.rst
@@ -0,0 +1,39 @@
+.. _axisswap:
+
+================================================================================
+Axis swap
+================================================================================
+
+Change the order and sign of 2,3 or 4 axes.
+
++--------------+---------------------------------------------------------------+
+| **Options**                                                                  |
++--------------+---------------------------------------------------------------+
+| `+order`     | Ordered comma-separated list of axis, e.g. `+order=2,1,3,4`   |
++--------------+---------------------------------------------------------------+
+
+
+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.
+
+Examples
+################################################################################
+
+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
diff --git a/docs/source/operations/conversions/cart.rst b/docs/source/operations/conversions/cart.rst
new file mode 100644
index 00000000..0c3c7c23
--- /dev/null
+++ b/docs/source/operations/conversions/cart.rst
@@ -0,0 +1,24 @@
+.. _cart:
+
+================================================================================
+Cartesian to geodetic conversion
+================================================================================
+
+Convert geodetic coordinates to cartesian coordinates.
+
++--------------+--------------------------------------------------------------------+
+| **Options**                                                                       |
++--------------+--------------------------------------------------------------------+
+| `+ellps`     |  Ellipsoid of the input coordinates. If used together with the     |
+|              |  ellipsoid parameters below, ``+ellps`` is overwritten.            |
++--------------+--------------------------------------------------------------------+
+| `+a`         | Semi-major radius of ellipsoid axis.                               |
++--------------+--------------------------------------------------------------------+
+| `+b`         | Semi-minor radius of ellipsoid axis.                               |
++--------------+--------------------------------------------------------------------+
+| `+es`        | Eccentricity of ellipsoid.                                         |
++--------------+--------------------------------------------------------------------+
+| `+f`         | Flattening of ellipsoid.                                           |
++--------------+--------------------------------------------------------------------+
+
+
diff --git a/docs/source/operations/conversions/index.rst b/docs/source/operations/conversions/index.rst
new file mode 100644
index 00000000..af27e2fd
--- /dev/null
+++ b/docs/source/operations/conversions/index.rst
@@ -0,0 +1,18 @@
+.. _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
+   lonlat
+   latlon
+   unitconvert
diff --git a/docs/source/operations/conversions/latlon.rst b/docs/source/operations/conversions/latlon.rst
new file mode 100644
index 00000000..6712fa7b
--- /dev/null
+++ b/docs/source/operations/conversions/latlon.rst
@@ -0,0 +1,6 @@
+.. _latlon:
+
+********************************************************************************
+Lat/long (Geodetic alias)
+********************************************************************************
+
diff --git a/docs/source/operations/conversions/lonlat.rst b/docs/source/operations/conversions/lonlat.rst
new file mode 100644
index 00000000..589cc813
--- /dev/null
+++ b/docs/source/operations/conversions/lonlat.rst
@@ -0,0 +1,6 @@
+.. _lonlat:
+
+********************************************************************************
+Lat/long (Geodetic)
+********************************************************************************
+
diff --git a/docs/source/operations/conversions/unitconvert.rst b/docs/source/operations/conversions/unitconvert.rst
new file mode 100644
index 00000000..73e517bd
--- /dev/null
+++ b/docs/source/operations/conversions/unitconvert.rst
@@ -0,0 +1,112 @@
+.. _unitconvert:
+
+================================================================================
+Unit conversion
+================================================================================
+
+Convert between various distance and time units.
+
++--------------+--------------------------------------------------------------------+
+| **Options**                                                                       |
++--------------+--------------------------------------------------------------------+
+| `+xy_in`     | Input unit of the horizontal components.                           |
++--------------+--------------------------------------------------------------------+
+| `+xy_out`    | Output unit of the horizontal components.                          |
++--------------+--------------------------------------------------------------------+
+| `+z_in`      | Input unit of the vertical component.                              |
++--------------+--------------------------------------------------------------------+
+| `+z_out`     | Output unit of the vertical component.                             |
++--------------+--------------------------------------------------------------------+
+| `+t_in`      | Input unit of the time component.                                  |
++--------------+--------------------------------------------------------------------+
+| `+t_out`     | Output unit of the time component.                                 |
++--------------+--------------------------------------------------------------------+
+
+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.999964286 +x_0=500000.00001016 +y_0=0
+    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+
+Often when working with GNNS 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=gpsweek +t_out=decimalyear
+    +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ...
+
+
+Distance units
+###############################################################################
+
+In the table below all distance units supported by PROJ is listed.
+The same list can also be produced on the command line with `proj` or `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                    |
++----------+---------------------------------+
+
+
+Time units
+###############################################################################
+
+In the table below all time units supported by PROJ is listed.
+
++--------------+-----------------------------+
+| mjd          | Modfied Julian date         |
++--------------+-----------------------------+
+| decimalyear  | Decimal year                |
++--------------+-----------------------------+
+| gps_week     | GPS Week                    |
++--------------+-----------------------------+
+