From 1583a566a208d2451fb1acc8bcf16fbd8151983e Mon Sep 17 00:00:00 2001
From: Even Rouault <even.rouault@spatialys.com>
Date: Sat, 29 Sep 2018 10:01:48 +0200
Subject: Add geographic offset transformation method.

The Geographic offsets transformation adds an offset to the geographic longitude,
latitude coordinates, and an offset to the ellipsoidal height.
This method is normally only used when low accuracy is tolerated. It is documented
as coordinate operation method code 9619 (for geographic 2D) and 9660 (for
geographic 3D) in the EPSG dataset.

It can also be used to implement the method Geographic2D with Height Offsets
(code 9618) by noting that the input vertical component is a gravity-related
height and the output vertical component is the ellispoid height (dh being
the geoid undulation).

It can also be used to implement the method Vertical offset (code 9616)

It is used for example to transform:
- from the old Greek geographic 2D CRS to the newer GGRS87 CRS
- from Tokyo + JSLD69 height to WGS 84
- from Baltic 1977 height to Black Sea height

It is also useful to document the implicit zero-offset transformation
we do in pipelines such as

+proj=pipeline +step +inv +proj=longlat +ellps=A
               +step +proj=longlat +ellps=B

that can be explicited as

+proj=pipeline +step +inv +proj=longlat +ellps=A
               +step +proj=geogoffset [+dlon=0 +dlat=0 +dh=0]
               +step +proj=longlat +ellps=B
---
 .../operations/transformations/geogoffset.rst      | 68 ++++++++++++++++++++++
 docs/source/operations/transformations/index.rst   |  1 +
 2 files changed, 69 insertions(+)
 create mode 100644 docs/source/operations/transformations/geogoffset.rst

(limited to 'docs/source/operations/transformations')

diff --git a/docs/source/operations/transformations/geogoffset.rst b/docs/source/operations/transformations/geogoffset.rst
new file mode 100644
index 00000000..91c91c83
--- /dev/null
+++ b/docs/source/operations/transformations/geogoffset.rst
@@ -0,0 +1,68 @@
+.. _geogoffset:
+
+================================================================================
+Geographic offsets
+================================================================================
+
+.. versionadded:: 6.0.0
+
+The Geographic offsets transformation adds an offset to the geographic longitude,
+latitude coordinates, and an offset to the ellipsoidal height.
+
++---------------------+----------------------------------------------------------+
+| **Alias**           | geogoffset                                               |
++---------------------+----------------------------------------------------------+
+| **Domain**          | 3D                                                       |
++---------------------+----------------------------------------------------------+
+| **Input type**      | Geodetic coordinates (horizontal), meters (vertical)     |
++---------------------+----------------------------------------------------------+
+| **output type**     | Geodetic coordinates (horizontal), meters (vertical)     |
++---------------------+----------------------------------------------------------+
+
+This method is normally only used when low accuracy is tolerated. It is documented
+as coordinate operation method code 9619 (for geographic 2D) and 9660 (for
+geographic 3D) in the EPSG dataset (:cite:`EPSGGuidanceNumber7Part2`)
+
+It can also be used to implement the method Geographic2D with Height Offsets
+(code 9618) by noting that the input vertical component is a gravity-related
+height and the output vertical component is the ellispoid height (dh being
+the geoid undulation).
+
+It can also be used to implement the method Vertical offset (code 9616)
+
+The reverse transformation simply consists in subtracting the offsets.
+
+Examples
+###############################################################################
+
+Geographic offset from the old Greek geographic 2D CRS to the newer GGRS87 CRS::
+
+    proj=geogoffset dlon=0.28 dlat=-5.86
+
+Conversion from Tokyo + JSLD69 height to WGS 84::
+
+    proj=geogoffset dlon=-13.97 dlat=7.94 dh=26.9
+
+Conversion from Baltic 1977 height to Black Sea height::
+
+    proj=geogoffset dh=0.4
+
+
+Parameters
+################################################################################
+
+Optional
+-------------------------------------------------------------------------------
+
+.. option:: +dlon=<value>
+
+    Offset in longitude, expressed in arc-second, to add.
+
+.. option:: +dlat=<value>
+
+    Offset in latitude, expressed in arc-second, to add.
+
+.. option:: +dh=<value>
+
+    Offset in height, expressed in meter, to add.
+
diff --git a/docs/source/operations/transformations/index.rst b/docs/source/operations/transformations/index.rst
index 5112ffa2..c2fe6baa 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
 
    deformation
+   geogoffset
    helmert
    molodensky
    hgridshift
-- 
cgit v1.2.3