blob: 90112c052a30b4502bc0a80c345fb10d53d0c025 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
.. _pipeline:
================================================================================
The pipeline operator
================================================================================
.. versionadded:: 5.0.0
Construct complex operations by daisy-chaining operations in a sequential pipeline.
+-----------------+--------------------------------------------------------------------+
| **Alias** | pipeline |
+-----------------+--------------------------------------------------------------------+
| **Domain** | 2D, 3D and 4D |
+-----------------+--------------------------------------------------------------------+
| **Input type** | Any |
+-----------------+--------------------------------------------------------------------+
| **Output type** | Any |
+-----------------+--------------------------------------------------------------------+
.. 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 occurrence of `+step`. This means that the GRS80 ellipsoid is used
in both steps, since any parameter stated before the first occurrence 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.
.. _global-pipeline-parameter:
**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
**5. Units of operations must match between steps.**
.. versionadded:: 5.1.0
The output units of step *n* must match the expected input unit of step *n+1*. E.g., you can't
pass an operation that outputs projected coordinates to an operation that expects angular units
(degrees). An example of such a unit mismatch is displayed below.
::
+proj=pipeline
+step +proj=merc # Mercator outputs projected coordinates
+step +proj=robin # The Robinson projection expects angular input
Parameters
-------------------------------------------------------------------------------
Required
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. option:: +step
Separate each step in a pipeline.
Optional
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.. option:: +inv
Invert a step in a pipeline.
.. option:: +omit_fwd
.. versionadded:: 6.3.0
Skip a step of the pipeline when it is followed in the forward path.
The following example shows a combined use of :ref:`push <push>` and :ref:`pop <pop>` operators,
with ``omit_fwd`` and ``omit_inv`` options, to implement a vertical adjustment that must
be done in a interpolation CRS that is different from the horizontal CRS
used in input and output. +omit_fwd in the forward path avoid a useless
inverse horizontal transformation and relies on the pop operator to restore
initial horizontal coordinates. +omit_inv serves the similar purpose when
the pipeline is executed in the reverse direction
::
+proj=pipeline
+step +proj=unitconvert +xy_in=deg +xy_out=rad
+step +proj=push +v_1 +v_2
+step +proj=hgridshift +grids=nvhpgn.gsb +omit_inv
+step +proj=vgridshift +grids=g1999u05.gtx +multiplier=1
+step +inv +proj=hgridshift +grids=nvhpgn.gsb +omit_fwd
+step +proj=pop +v_1 +v_2
+step +proj=unitconvert +xy_in=rad +xy_out=deg
.. option:: +omit_inv
.. versionadded:: 6.3.0
Skip a step of the pipeline when it is followed in the reverse path.
|
