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

1 files changed, 98 insertions, 0 deletions

diff --git a/docs/source/operations/pipeline.rst b/docs/source/operations/pipeline.rst
new file mode 100644
index 00000000..18637712
--- /dev/null
+++ b/docs/source/operations/pipeline.rst
@@ -0,0 +1,98 @@
+.. _pipeline:
+
+================================================================================
+The pipeline operator
+================================================================================
+
+Construct complex operations by daisy-chaining operations in a sequential pipeline.
+
++-----------------+--------------------------------------------------------------------+
+| **Input type**  | Any.                                                               |
++-----------------+--------------------------------------------------------------------+
+| **Output type** | Any.                                                               |
++-----------------+--------------------------------------------------------------------+
+| **Options**                                                                          |
++-----------------+--------------------------------------------------------------------+
+| `step`          | Separate each step in a pipeline.                                  |
++-----------------+--------------------------------------------------------------------+
+| `inv`           | Invert a step in a pipeline.                                       |
++-----------------+--------------------------------------------------------------------+
+
+.. note:: See the section on :ref:`transformation` for a more thorough introduction
+          to the concept of transformation pipelines in PROJ.
+
+
+With the pipeline operation it is possible to perform several operations after each
+other on the same input data. This feature makes it possible to create transformations
+that are made up of more than one operation, e.g. performing a datum shift and then
+applying a suitable map projection. Theoretically any transformation between two
+coordinate reference systems is possible to perform using the pipeline operation,
+provided that the necessary coordinate operations in each step is available in PROJ.
+
+A pipeline is made up of a number of steps, with each step being a coordinate operation
+in itself. By connecting these individual steps sequentially we end up with a concatenated
+coordinate operation. An example of this is a transformation from geodetic coordinates
+on the GRS80 ellipsoid to a projected system where the east-west and north-east axes has
+been swapped:
+
+::
+
+    +proj=pipeline +ellps=GRS80 +step +proj=merc +step +proj=axisswap +order=2,1
+
+Here the first step is applying the :ref:`merc` projection and the second step is
+applying the :ref:`axisswap` conversion. Note that the `+ellps=GRS80` is specified
+before the first occurence of `+step`. This means that the GRS80 ellipsoid is used
+in both steps, since any parameter stated before the first occurence of `+step` is
+treated as a global parameter and is transferred to each individual steps.
+
+
+Rules for pipelines
+-------------------------------------------------------------------------------
+
+**1. Pipelines must consist of at least one step.**
+
+::
+
+    +proj=pipeline
+
+Will result in an error.
+
+**2. Pipelines can only be nested if the nested pipeline is defined in an init-file.**
+
+::
+
+    +proj=pipeline
+    +step +proj=pipeline +step +proj=merc +step +proj=axisswap +order=2,1
+    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+
+Results in an error, while
+
+::
+
+    +proj=pipeline
+    +step +init=predefined_pipelines:projectandswap
+    +step +proj=unitconvert +xy_in=m +xy_out=us-ft
+
+does not.
+
+**3. Pipelines without a forward path can't be constructed.**
+
+::
+
+    +proj=pipeline +step +inv +proj=urm5
+
+Will result in an error since :ref:`urm5` does not have an inverse operation defined.
+
+**4. Parameters added before the first `+step` are global and will be applied to all steps.**
+
+In the following the GRS80 ellipsoid will be applied to all steps.
+
+::
+
+    +proj=pipeline +ellps=GRS80
+    +step +proj=cart
+    +step +proj=helmert +x=10 +y=3 +z=1
+    +step +proj=cart +inv
+    +step +proj=merc
+
+