Merge pull request #2206 from rouault/deformation_model_for_merge

 Add a +proj=defmodel transformation for multi-component time-based deformation models

4 files changed, 91 insertions, 8 deletions

diff --git a/docs/source/operations/transformations/defmodel.rst b/docs/source/operations/transformations/defmodel.rst
new file mode 100644
index 00000000..fe2ac66a
--- /dev/null
+++ b/docs/source/operations/transformations/defmodel.rst
@@ -0,0 +1,61 @@
+.. _defmodel:
+
+================================================================================
+Multi-component time-based deformation model
+================================================================================
+
+.. versionadded:: 7.1.0
+
++---------------------+--------------------------------------------------------------------+
+| **Input type**      | Geodetic or projected coordinates (horizontal), meters (vertical), |
+|                     | decimalyear (temporal)                                             |
++---------------------+--------------------------------------------------------------------+
+| **Output type**     | Geodetic or projected coordinates (horizontal), meters (vertical), |
+|                     | decimalyear (temporal)                                             |
++---------------------+--------------------------------------------------------------------+
+| **Domain**          | 4D                                                                 |
++---------------------+--------------------------------------------------------------------+
+| **Available forms** | Forward and inverse                                                |
++---------------------+--------------------------------------------------------------------+
+
+The defmodel transformation can be used to represent most deformation models
+currently in use, in particular for areas subject to complex deformation, including
+large scale secular crustal deformation near plate boundaries and vertical deformation
+due to Glacial Isostatic Adjustment (GIA). These can often be represented by a constant
+velocity model. Additionally, many areas suffer episodic deformation events such as
+earthquakes and aseismic slow slip event.
+
+The transformation relies on a "master" JSON file, describing general metadata on
+the deformation model, its spatial and temporal extent, and listing spatial
+components whose values are stored in :ref:`Geodetic TIFF grids (GTG) <geodetictiffgrids>`.
+The valuation of each component is modulated by a time function (constant, step,
+reverse step, velocity, piecewise, exponential).
+
+All details on the content of this JSON file are given in the `Proposal for encoding
+of a Deformation Model <https://github.com/linz/deformation-model-format/blob/master/doc/JsonGeotiffDeformationModelFormat_20200501.pdf>`__
+
+If input coordinates are given in the geographic domain (resp. projected domain),
+the output will also be in the geographic domain (resp. projected domain).
+The domain should be the corresponding to the source_crs metadata of the model.
+
+This transformation is a generalization of the :ref:`Kinematic datum shifting utilizing a deformation model <deformation>` transformation.
+
+Parameters
+-------------------------------------------------------------------------------
+
+Required
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. option:: +model=<filename>
+
+    Filename to the JSON master file for the deformation model.
+
+
+Example
+-------------------------------------------------------------------------------
+
+Transformating a point with the LINZ NZGD2000 deformation model:
+
+::
+
+    echo 166.7133850980 -44.5105886020 293.3700 2007.689 | cct +proj=defmodel +model=nzgd2000-20180701.json
diff --git a/docs/source/operations/transformations/deformation.rst b/docs/source/operations/transformations/deformation.rst
index 02924a25..c28e9404 100644
--- a/docs/source/operations/transformations/deformation.rst
+++ b/docs/source/operations/transformations/deformation.rst
@@ -38,6 +38,8 @@ construction of new grids is recommended.
 Starting with PROJ 7.0, use of a GeoTIFF format is recommended to store both
 the horizontal and vertical velocities.
 
+More complex deformations can be done with the :ref:`Multi-component time-based deformation model <defmodel>` transformation.
+
 Example
 -------------------------------------------------------------------------------
 
diff --git a/docs/source/operations/transformations/index.rst b/docs/source/operations/transformations/index.rst
index 6bd503d4..9f7900f1 100644
--- a/docs/source/operations/transformations/index.rst
+++ b/docs/source/operations/transformations/index.rst
@@ -11,6 +11,7 @@ systems are based on different datums.
    :maxdepth: 1
 
    affine
+   defmodel
    deformation
    geogoffset
    helmert
diff --git a/docs/source/specifications/geodetictiffgrids.rst b/docs/source/specifications/geodetictiffgrids.rst
index 861e8b82..7c05867b 100644
--- a/docs/source/specifications/geodetictiffgrids.rst
+++ b/docs/source/specifications/geodetictiffgrids.rst
@@ -137,9 +137,9 @@ is an easy way to inspect such grid files:
 
     * SamplesPerPixel = 1 for vertical shift grids.
 
-   In the future, different values of SamplesPerPixel may be used to accommodate
-   for other needs. For example for deformation models, SamplesPerPixel = 3 to combine
-   horizontal and vertical adjustments.
+    * SamplesPerPixel = 3 for deformation models combining
+      horizontal and vertical adjustments.
+
    And even for the current identified needs of horizontal or vertical shifts,
    more samples may be present (to indicate for example uncertainties), but
    will be ignored by PROJ.
@@ -215,28 +215,32 @@ is an easy way to inspect such grid files:
     - ``HORIZONTAL_OFFSET``: implies the presence of at least two samples.
       The first sample must contain the latitude offset and the second
       sample must contain the longitude offset.
-      Corresponds to PROJ ``hgridshift`` method.
+      Corresponds to PROJ :ref:`hgridshift` method.
 
     - ``VERTICAL_OFFSET_GEOGRAPHIC_TO_VERTICAL``: implies the presence of at least one sample.
       The first sample must contain the vertical adjustment. Must be used when
       the source/interpolation CRS is a Geographic CRS and the target CRS a Vertical CRS.
-      Corresponds to PROJ ``vgridshift`` method.
+      Corresponds to PROJ  :ref:`vgridshift` method.
 
     - ``VERTICAL_OFFSET_VERTICAL_TO_VERTICAL``: implies the presence of at least one sample.
       The first sample must contain the vertical adjustment. Must be used when
       the source and target CRS are Vertical CRS.
-      Corresponds to PROJ ``vgridshift`` method.
+      Corresponds to PROJ :ref:`vgridshift` method.
 
     - ``GEOCENTRIC_TRANSLATION``: implies the presence of at least 3 samples.
       The first 3 samples must be respectively the geocentric adjustments along
       the X, Y and Z axis. Must be used when the source and target CRS are
       geocentric CRS. The interpolation CRS must be a geographic CRS.
-      Corresponds to PROJ ``xyzgridshift`` method.
+      Corresponds to PROJ :ref:`xyzgridshift` method.
 
     - ``VELOCITY``: implies the presence of at least 3 samples.
       The first 3 samples must be respectively the velocities along
       the E(ast), N(orth), U(p) axis in the local topocentric coordinate system.
-      Corresponds to PROJ ``deformation`` method.
+      Corresponds to PROJ :ref:`deformation` method.
+
+    - ``DEFORMATION_MODEL``: implies the presence of the ``DISPLACEMENT_TYPE``
+      and ``UNCERTAINTY_TYPE`` metadata items.
+      Corresponds to PROJ :ref:`defmodel` method.
 
     For example:
 
@@ -284,6 +288,11 @@ is an easy way to inspect such grid files:
       Sample values should be the velocity in a linear/time unit in a ENU local
       topocentric coordinate system.
 
+    + ``east_offset`` / ``north_offset`` / ``vertical_offset``: valid for
+      TYPE=DEFORMATION_MODEL.
+      For east_offset and north_offset, the unit might be degree or metre.
+      For vertical_offset, the unit must be metre.
+
     For example:
 
     .. code-block:: xml
@@ -337,6 +346,16 @@ is an easy way to inspect such grid files:
         <Item name="UNITTYPE" sample="0" role="unittype">arc-second</Item>
         <Item name="UNITTYPE" sample="1" role="unittype">arc-second</Item>
 
+  * For TYPE=DEFORMATION_MODEL, the type of the displacement must be specified
+    with a `Item` whose ``name`` is set to ``DISPLACEMENT_TYPE``.
+
+    The accepted values are: ``HORIZONTAL``, ``VERTICAL``, ``3D`` or ``NONE``
+
+  * For TYPE=DEFORMATION_MODEL, the type of the uncertainty must be specified
+    with a `Item` whose ``name`` is set to ``UNCERTAINTY_TYPE``.
+
+    The accepted values are: ``HORIZONTAL``, ``VERTICAL``, ``3D`` or ``NONE``
+
   * The ``target_crs_epsg_code`` metadata item should be present.
     For a horizontal shift grid, this is the EPSG
     code of the target geographic CRS. For a vertical shift grid, this is the