Merge pull request #3304 from kbevers/tutorials

Tutorials for the docs

docs/source/index.rst

@@ -19,6 +19,7 @@ PROJ
    development/index
    specifications/index
    community/index
+   tutorials/index
    faq
    glossary
    zreferences

docs/source/tutorials/EUREF2019/answers.rst

@@ -0,0 +1,133 @@
+.. _euref2019_answers:
+
+Answers to the PROJ tutorial exercises
+++++++++++++++++++++++++++++++++++++++++
+
+Projections.1: UTM
+-------------------
+
+.. code-block::
+
+    1.      +proj=utm +zone=35
+    2.      +proj=utm +zone=60 +south
+    3.      +proj=utm +zone=35 +ellps=intl
+
+
+Projections2.: LCC
+-------------------
+
+.. code-block::
+
+        1.      +proj=lcc +lat_1=59.8
+        2.      +proj=lcc +lat_1=59.8   +k_0=0.99998
+        3.      +proj=lcc +lat_1=59.437 +lat_2=60.171
+        4.      +proj=lcc +lat_1=59.8   +lat_0=59.8   +lon_0=24.8
+        5.      +proj=lcc +lat_1=59.8   +lat_0=59.8   +lon_0=24.8  +x_0=1000000 +y_0=1000000
+
+
+
+Ellipsoids
+-----------
+
+.. code-block::
+
+        1.      +R=1
+        2.      +ellps=intl
+        3.      +a=6378388.0 +rf=297.0
+        4.      +a=6378206.4 +b=6356583.8
+
+
+Helmert
+--------
+
+.. code-block::
+
+        1.      +proj=helmert +x=-97 +y=-103 +z=-120
+        2.      +proj=helmert +x=-81.1 +y=-89.4 +z=-115.8 +rx=0.485 +ry=0.024 +rz=0.413 +s=-0.54 +convention=position_vector
+        3a.     +proj=helmert +x=582 +y=105 +z=414 +rx=-1.04 +ry=-0.35 +rz=3.08 +s=8.3
+        3b.     +proj=helmert +x=582 +y=105 +z=414 +rx=1.04 +ry=0.35 +rz=-3.08 +s=8.3
+        1.      +proj=helmert   +convention=position_vector +x=-0.0016  +y=-0.0019  +z=-0.0024 +s=2e-05 +dz=0.0001 +ds=-3e-05 +t_epoch=2010
+
+
+Conversions
+------------
+
+.. code-block::
+
+        1.      +proj=unitconvert +xy_in=m  +xy_out=us-ft
+        2.      +proj=axisswap +order=2,1
+        3.      +proj=cart +ellps=intl
+
+
+Gridshifts
+-----------
+
+.. code-block::
+
+        1.      +proj=hgridshift +grids=de_adv_BETA2007.tif
+        2.      +proj=vgridshift +grids=us_nga_egm96_15.tif
+
+Pipelines
+----------
+
+.. code-block::
+
+        1.      +proj=pipeline +ellps=GRS80
+                +step +proj=cart
+                +step +proj=helmert +x=100 +y=200 +z=300 +convention=position_vector
+                +step +inv +proj=cart
+
+        2.      +proj=pipeline
+                +step +proj=hgridshift +grids=de_adv_BETA2007.tif
+                +step +proj=vgridshift +grids=us_nga_egm96_15.tif
+
+        2.1:    In principle, yes - practically, no.
+        2.2:    Which grids is applied first depends on how the systems are defined.
+                If a geoid model is fitted to a certain datum, you need to make sure that
+                the input to the vgridshift operation is in that datum. That is your
+                responsibility to check - PROJ can't figure that out on its own. In this
+                case, the EGM96 geoid is fitted to WGS84. The BETA2007 grid results in
+                ETRS89 coordinates which for all but the most high accuracy application
+                can be regarded as equivalent to WGS84. Hence we do the horizontal grid
+                shift first.
+
+        3.      +proj=pipeline
+                +step +inv +proj=utm +zone=32
+                +step +proj=cart +ellps=intl
+                +step +proj=helmert +x=-81.1 +y=-89.4 +z=-115.8
+                +rx=0.485 +ry=0.024 +rz=0.413 +s=-0.54 +convention=position_vector
+                +step +inv +proj=cart +ellps=GRS80
+                +step +proj=utm +zone=33
+
+
+        4.      +proj=pipeline
+                +step +proj=axisswap +order=2,1
+                +step +proj=unitconvert +xy_in=deg +xy_out=rad
+                +step +proj=push +v_3 +step +proj=cart +ellps=bessel
+                +step +proj=helmert +x=598.1 +y=73.7 +z=418.2
+                +rx=0.202 +ry=0.045 +rz=-2.455 +s=6.7 +convention=position_vector
+                +step +inv +proj=cart +ellps=GRS80
+                +step +proj=pop +v_3
+                +step +proj=unitconvert +xy_in=rad +xy_out=deg
+                +step +proj=axisswap +order=2,1
+
+        4.1:    Latitude (deg), longitude (deg), height (m)
+        4.2:    Latitude (deg), longitude (deg), height (m)
+        4.3:    Retain the original height of the input coordinate:
+                Without the push/pop steps the height would be affected by
+                the Helmert step.
+
+Projections.3: Tranverse Mercator
+---------------------------------
+
+.. code-block::
+
+        1.      +proj=tmerc
+        2.      +proj=tmerc +k_0=0.9996 +lon_0=27 +x_0=500000
+        3a.     1 cm
+        3b.     250 km
+        3c.     100 km
+        3d.      10 km
+        3e.     500  m
+        3f.       2  m
+        3g.       5 um

docs/source/tutorials/EUREF2019/exercises/conversions.gie

@@ -0,0 +1,118 @@
+###############################################################################
+
+                                Coordinate Conversions
+
+In ISO19111 terms, a coordinate conversion is an operation that changes
+coordinates in a source coordinate reference system to coordinates in a target
+coordinate reference system in which both coordinate reference systems are based
+on the same datum. Technically this is also true for PROJ although the term is
+usually narrowed a bit, excluding projections since those are the origin of
+PROJ they get special treatment.
+
+In this exercise we will be looking at three coordinate conversions that in
+combination with other operations are very powerful: Unit conversions, axis
+swapping and geodetic to cartesian conversion.  Here we only look at the
+conversions by themselves which isn't particularly useful, apart from the
+educational purpose. When used in transformation pipelines they reveal their
+true power. We will explore that further in the pipelines.gie exercises.
+
+See [0] for a list of all conversions available in PROJ.
+
+[0] https://proj.org/operations/conversions/index.html
+
+###############################################################################
+<gie>
+
+
+1. Unit conversion from meters to feet
+-------------------------------------------------------------------------------
+Many projected coordinate systems are defined in terms of units other than the
+meter. In this exercise we will transform the horizontal part of a coordinate
+from meters to feet.
+
+Hints:
+
+    - Consult the documentation to find out how to set up the transformation:
+      https://proj.org/operations/conversions/unitconvert.html
+
+    - You can use `proj -lu` to learn which units is supported by PROJ.
+
+    - Note that the horizontal, vertical and temporal parts are treated
+      separately by the unit convert operator.
+
+-------------------------------------------------------------------------------
+
+operation   <your answer here>
+tolerance   1 mm
+
+accept      100.0       123.0       432.0
+expect      328.0833    403.5425    432.0
+
+-------------------------------------------------------------------------------
+
+
+2. Swapping axes
+-------------------------------------------------------------------------------
+Many coordinate reference systems are defined such that the axis order is
+different than the (east, north, up, time) PROJ defaults to. An example of this
+is the standard representation of a latitude/longitude-pair, where the north
+component of the coordinate comes first. For this reason we need an operation
+that can swap the axes around so that a given coordinate reference system can
+be represented correctly, conforming to the intention of the defining authority.
+
+Set up an operation that puts a longitude/latitude pair on the standard
+latitude/longitude form.
+
+Hints:
+
+    - Consult the documentation to find out how to set up the transformation:
+      https://proj.org/operations/conversions/axisswap.html
+
+    - Remember that the axisswap operation doesn't know anything about the
+      nature of the coordinate that is passed to it - it only cares about the
+      the order of the input.
+
+-------------------------------------------------------------------------------
+
+operation   <your answer here>
+tolerance   1 mm
+
+accept      140.0     75.0    # somewhere in Siberia
+expect       75.0    140.0
+
+-------------------------------------------------------------------------------
+
+
+3. Geodetic to cartesian conversion
+-------------------------------------------------------------------------------
+Some transformations, most notably the Helmert transformation, operates on
+cartesian geocentric coordinates. Geodetic coordinates (latitude and longitude)
+is the most commonly used coordinate representation. It is only natural to have
+a way to convert between the two representations.
+
+Set up a transformation that convert geodetic coordinates to cartesian
+geocentric coordinates on the Hayford ellipsoid.
+
+
+Hints:
+
+    - Consult the documentation to find out how to set up the transformation:
+      https://proj.org/operations/conversions/cart.html
+
+    - Remember that `proj -le` returns a list of available ellipsoid models
+
+    - Remember that the Hayford ellipsoid is known under a number of other
+      names - most of them including the term "international".
+
+-------------------------------------------------------------------------------
+
+operation   <your answer here>
+tolerance   1 mm
+
+accept      24.745          59.437          0  # Talinn, Estonia
+expect      2952883.7000    1360985.5908    5468966.6589
+
+-------------------------------------------------------------------------------
+
+
+</gie>

docs/source/tutorials/EUREF2019/exercises/conversions.rst

@@ -0,0 +1,94 @@
+.. _euref2019_conversions:
+
+Coordinate conversions
+++++++++++++++++++++++++++++
+
+In ISO19111 terms, a coordinate conversion is an operation that changes
+coordinates in a source coordinate reference system to coordinates in a target
+coordinate reference system in which both coordinate reference systems are based
+on the same datum. Technically this is also true for PROJ although the term is
+usually narrowed a bit, excluding projections since those are the origin of
+PROJ they get special treatment.
+
+In this exercise we will be looking at three coordinate conversions that in
+combination with other operations are very powerful: Unit conversions, axis
+swapping and geodetic to cartesian conversion.  Here we only look at the
+conversions by themselves which isn't particularly useful, apart from the
+educational purpose. When used in transformation pipelines they reveal their
+true power. We will explore that further in the pipelines.gie exercises.
+
+See :ref:`conversions_list` for a list of all conversions available in PROJ.
+
+Download the :program:`gie` file for the exercise: :download:`conversions.gie <conversions.gie>`.
+
+1. Unit conversion from meters to feet
+----------------------------------------
+
+Many projected coordinate systems are defined in terms of units other than the
+meter. In this exercise we will transform the horizontal part of a coordinate
+from meters to feet.
+
+.. hint::
+
+    Consult :ref:`unitconvert` to find out how to set up the transformation
+
+.. hint:: You can use ``proj -lu`` to learn which units is supported by PROJ.
+
+.. hint::
+
+    Note that the horizontal, vertical and temporal parts are treated
+    separately by the unit convert operator.
+
+.. literalinclude:: conversions.gie
+  :lines: 45-49
+
+
+2. Swapping axes
+------------------
+
+Many coordinate reference systems are defined such that the axis order is
+different than the (east, north, up, time) PROJ defaults to. An example of this
+is the standard representation of a latitude/longitude-pair, where the north
+component of the coordinate comes first. For this reason we need an operation
+that can swap the axes around so that a given coordinate reference system can
+be represented correctly, conforming to the intention of the defining authority.
+
+Set up an operation that puts a longitude/latitude pair on the standard
+latitude/longitude form.
+
+.. hint::
+
+    Consult :ref:`axisswap` to find out how to set up the transformation
+
+.. hint::
+
+    Remember that the axisswap operation doesn't know anything about the
+    nature of the coordinate that is passed to it - it only cares about the
+    the order of the input.
+
+.. literalinclude:: conversions.gie
+  :lines: 77-81
+
+3. Geodetic to cartesian conversion
+------------------------------------
+Some transformations, most notably the Helmert transformation, operate on
+cartesian geocentric coordinates. Geodetic coordinates (latitude and longitude)
+is the most commonly used coordinate representation. It is only natural to have
+a way to convert between the two representations.
+
+Set up a transformation that convert geodetic coordinates to cartesian
+geocentric coordinates on the Hayford ellipsoid.
+
+.. hint::
+
+    Consult :ref:`cart` to find out how to set up the transformation
+
+.. hint:: Remember that `proj -le` returns a list of available ellipsoid models
+
+.. hint::
+    Remember that the Hayford ellipsoid is known under a number of other
+    names - most of them including the term "international".
+
+
+.. literalinclude:: conversions.gie
+  :lines: 109-113