From 829decbc00d3841832ed6528d2e7c3ce9633f139 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 22 Feb 2019 08:21:30 +0100 Subject: [PATCH 1/7] Some improvements to the docs for tmerc and omerc --- docs/source/operations/projections/omerc.rst | 90 +++++++++++++++++++- docs/source/operations/projections/tmerc.rst | 15 +++- docs/source/references.bib | 21 +++++ 3 files changed, 121 insertions(+), 5 deletions(-) diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index 7131df6255..ee7b970f46 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -4,6 +4,53 @@ Oblique Mercator ******************************************************************************** +The Oblique Mercator projection is a cylindrical map projection that closes the +gap between the Mercator and the Transverse Mercator projections. + +Figuratively, the cylinder used for developing the Mercator projection touches +the planet along the Equator, while that of the Transverse Mercator touches the +planet along a meridian, i.e. along a line perpendicular to the Equator. + +The cylinder for the Oblique Mercator, however, touches the planet along a line +at an arbitrary angle with the Equator. Hence, the Oblique Mercator projection +is useful for mapping areas having their greatest extent along a direction that +is neither north-south, nor east-west. + +The Mercator and the Transverse Mercator projections are both limiting forms of +the Oblique Mercator: The Mercator projection is equivalent to an Oblique Mercator +with central line along the Equator, while the Transverse Mercator is equivalent +to an Oblique Mercator with central line along a meridian. + +For the sphere, the construction of the Oblique Mercator projection can be +imagined as "tilting the cylinder of a plain Mercator projection", +so the cylinder, instead of touching the equator, touches an arbitrary great circle +on the sphere. The great circle is defined by the tilt angle of the central line, +hence putting land masses along that great circle near the centre of the map, +where the Equator would go in the plain Mercator case. + +The ellipsoidal case, developed by Hotine, and refined by Snyder :cite:`Snyder1987` +is more complex, involving initial steps projecting from the ellipsoid to another +curved surface, the "aposphere", then projection from the aposphere to the skew +uv-plane, before finally rectifying the skew uv-plane onto the map XY plane. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but reasonably accurate only within 15 degrees | +| | of the oblique central line | ++---------------------+----------------------------------------------------------+ +| **Alias** | omerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + + .. figure:: ./images/omerc.png :width: 500 px :align: center @@ -11,6 +58,44 @@ Oblique Mercator proj-string: ``+proj=omerc +lat_1=45 +lat_2=55`` + +Usage +######## + +The tilt angle (azimuth) of the central line can be given in two different ways. +In the first case, the azimuth is given directly, using the option :option:`+alpha` +and defining the centre of projection using the options :option:`+lonc` and +:option:`+lat_0`. +In the second case, the azimuth is given indirectly by specifying two points on +the central line, using the options +:option:`+lat_1`, :option:`+lon_1`, :option:`+lat_2`, and :option:`+lon_2`. + +Example: Verify that the Mercator projection is a limiting form of the Oblique +Mercator + + $ echo 12 55 | proj +proj=merc +ellps=GRS80 + 1335833.89 7326837.71 + # First case: Azimuth given directly + $ echo 12 55 | proj +proj=omerc +lonc=0 +alpha=90 +ellps=GRS80 + 1335833.89 7326837.71 + +Example: + $ Second case: Indirectly + $ echo 12 55 | proj +proj=omerc +lon_1=-1 +lat_1=1 +lon_2=0 +lat_2=0 +ellps=GRS80 + 349567.57 6839490.50 + + +Example: An approximation of the Danish "System 34" from :cite:`Rittri2012` + + $ echo 10.536498003 56.229892362 | proj +proj=omerc +axis=wnu +lonc=9.46 +lat_0=56.13333333 +x_0=-266906.229 +y_0=189617.957 +k=0.9999537 +alpha=-0.76324 +gamma=0 +ellps=GRS80 + 200000.13 199999.89 + +The input coordinate represents the System 34 datum point "Agri Bavnehoj", with coordinates +(200000, 200000) by definition. So at the datum point, the approximation is off by about 17 cm. +This use case represents a datum shift from a cylinder projection on an old, slightly +misaligned datum, to a similar projection on a modern datum. + + Parameters ################################################################################ @@ -62,7 +147,10 @@ Optional .. option:: +no_rot - Do not rotate axis. + No rectification (not "no rotation" as one may well assume). + Do not take the last step from the skew uv-plane to the map + XY plane. This option is probably only marginally useful, but + remains for (mostly) historical reasons. .. option:: +no_off diff --git a/docs/source/operations/projections/tmerc.rst b/docs/source/operations/projections/tmerc.rst index fd6000016e..a52e40592d 100644 --- a/docs/source/operations/projections/tmerc.rst +++ b/docs/source/operations/projections/tmerc.rst @@ -28,7 +28,7 @@ The transverse Mercator projection in its various forms is the most widely used .. figure:: ./images/tmerc.png :width: 500 px :align: center - :alt: Transverse Mercator + :alt: Transverse Mercator proj-string: ``+proj=tmerc`` @@ -79,7 +79,9 @@ Parameters .. versionadded:: 6.0.0 - Use faster, less accurate algorithm for the Transverse Mercator. + Use the algorithm described in section "Elliptical Form" below. + It is faster than the default algorithm, but also diverges faster + as the distance from the central meridian increases. .. include:: ../options/lon_0.rst @@ -98,7 +100,7 @@ Parameters Mathematical definition ####################### -The formulas describing the Transverse Mercator are all taken from Evenden's [Evenden2005]_. +The formulas describing the Transverse Mercator below are quoted from Evenden's [Evenden2005]_. :math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. @@ -148,6 +150,11 @@ Inverse projection Elliptical form *************** +The formulas below describe the algorithm used when giving the +:option:`+approx` option. They are originally from :cite:`Snyder1987`, +but here quoted from :cite:`Evenden1995`. +The default algorithm is given by Poder and Engsager in :cite:`Poder1998` + Forward projection ================== @@ -169,7 +176,7 @@ Forward projection .. math:: - x &= k_0 \lambda \cos \phi \\ + x &= k_0 \lambda \cos \phi \\ &+ \frac{k_0 \lambda^3 \cos^3\phi}{3!}(1-t^2+\eta^2) \\ &+ \frac{k_0 \lambda^5 \cos^5\phi}{5!}(5-18t^2+t^4+14\eta^2-58t^2\eta^2) \\ &+\frac{k_0 \lambda^7 \cos^7\phi}{7!}(61-479t^2+179t^4-t^6) diff --git a/docs/source/references.bib b/docs/source/references.bib index b36e1e2de5..a2017ef5f6 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -197,6 +197,27 @@ @TechReport{ONeilLaubscher1976 Url = {https://archive.org/details/DTIC_ADA026294} } +@techreport{Poder1998, + author = {Knud Poder and Karsten Engsager}, + year = {1998}, + title = {Some Conformal Mappings and Transformations for Geodesy + and Topographic Cartography}, + address = {Copenhagen, Denmark}, + institution = {National Survey and Cadastre}, + type = {National Survey and Cadastre Publications}, + series = {4}, + volume = {6}, + isbn = {87-7866-085-8}, + pages = {63} +} + +@Misc{Rittri2012, + author = {Mikael Rittri}, + title = {New omerc approximations of Denmark System 34}, + year = {2012}, + url = {http://lists.maptools.org/pipermail/proj/2012-June/006323.html} +} + @article{Ruffhead2016, author = {A. C. Ruffhead}, title = {Introduction to multiple regression equations in datum transformations and their reversibility}, From aa628825d962046655f7a033ee364c15ac97605a Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 22 Feb 2019 08:53:36 +0100 Subject: [PATCH 2/7] correct a bad example code definition --- docs/source/operations/projections/omerc.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index ee7b970f46..f009faf26b 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -74,13 +74,13 @@ Example: Verify that the Mercator projection is a limiting form of the Oblique Mercator $ echo 12 55 | proj +proj=merc +ellps=GRS80 - 1335833.89 7326837.71 - # First case: Azimuth given directly + 1335833.89 7326837.71 + $ echo 12 55 | proj +proj=omerc +lonc=0 +alpha=90 +ellps=GRS80 - 1335833.89 7326837.71 + 1335833.89 7326837.71 + +Example: Second case - indirectly given azimuth -Example: - $ Second case: Indirectly $ echo 12 55 | proj +proj=omerc +lon_1=-1 +lat_1=1 +lon_2=0 +lat_2=0 +ellps=GRS80 349567.57 6839490.50 From 43eba009c1ae71976b72548901d301f00f0427dc Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 22 Feb 2019 09:07:41 +0100 Subject: [PATCH 3/7] move some text around as requested in review --- docs/source/operations/projections/omerc.rst | 52 ++++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index f009faf26b..eedf124398 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -7,32 +7,6 @@ Oblique Mercator The Oblique Mercator projection is a cylindrical map projection that closes the gap between the Mercator and the Transverse Mercator projections. -Figuratively, the cylinder used for developing the Mercator projection touches -the planet along the Equator, while that of the Transverse Mercator touches the -planet along a meridian, i.e. along a line perpendicular to the Equator. - -The cylinder for the Oblique Mercator, however, touches the planet along a line -at an arbitrary angle with the Equator. Hence, the Oblique Mercator projection -is useful for mapping areas having their greatest extent along a direction that -is neither north-south, nor east-west. - -The Mercator and the Transverse Mercator projections are both limiting forms of -the Oblique Mercator: The Mercator projection is equivalent to an Oblique Mercator -with central line along the Equator, while the Transverse Mercator is equivalent -to an Oblique Mercator with central line along a meridian. - -For the sphere, the construction of the Oblique Mercator projection can be -imagined as "tilting the cylinder of a plain Mercator projection", -so the cylinder, instead of touching the equator, touches an arbitrary great circle -on the sphere. The great circle is defined by the tilt angle of the central line, -hence putting land masses along that great circle near the centre of the map, -where the Equator would go in the plain Mercator case. - -The ellipsoidal case, developed by Hotine, and refined by Snyder :cite:`Snyder1987` -is more complex, involving initial steps projecting from the ellipsoid to another -curved surface, the "aposphere", then projection from the aposphere to the skew -uv-plane, before finally rectifying the skew uv-plane onto the map XY plane. - +---------------------+----------------------------------------------------------+ | **Classification** | Conformal cylindrical | +---------------------+----------------------------------------------------------+ @@ -62,6 +36,32 @@ uv-plane, before finally rectifying the skew uv-plane onto the map XY plane. Usage ######## +Figuratively, the cylinder used for developing the Mercator projection touches +the planet along the Equator, while that of the Transverse Mercator touches the +planet along a meridian, i.e. along a line perpendicular to the Equator. + +The cylinder for the Oblique Mercator, however, touches the planet along a line +at an arbitrary angle with the Equator. Hence, the Oblique Mercator projection +is useful for mapping areas having their greatest extent along a direction that +is neither north-south, nor east-west. + +The Mercator and the Transverse Mercator projections are both limiting forms of +the Oblique Mercator: The Mercator projection is equivalent to an Oblique Mercator +with central line along the Equator, while the Transverse Mercator is equivalent +to an Oblique Mercator with central line along a meridian. + +For the sphere, the construction of the Oblique Mercator projection can be +imagined as "tilting the cylinder of a plain Mercator projection", +so the cylinder, instead of touching the equator, touches an arbitrary great circle +on the sphere. The great circle is defined by the tilt angle of the central line, +hence putting land masses along that great circle near the centre of the map, +where the Equator would go in the plain Mercator case. + +The ellipsoidal case, developed by Hotine, and refined by Snyder :cite:`Snyder1987` +is more complex, involving initial steps projecting from the ellipsoid to another +curved surface, the "aposphere", then projection from the aposphere to the skew +uv-plane, before finally rectifying the skew uv-plane onto the map XY plane. + The tilt angle (azimuth) of the central line can be given in two different ways. In the first case, the azimuth is given directly, using the option :option:`+alpha` and defining the centre of projection using the options :option:`+lonc` and From 898114d7679cebd87a5b8b329eb4b4d91d3ee166 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 22 Feb 2019 09:09:25 +0100 Subject: [PATCH 4/7] whoops - move slightly back again --- docs/source/operations/projections/omerc.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index eedf124398..d522ea9244 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -33,9 +33,6 @@ gap between the Mercator and the Transverse Mercator projections. proj-string: ``+proj=omerc +lat_1=45 +lat_2=55`` -Usage -######## - Figuratively, the cylinder used for developing the Mercator projection touches the planet along the Equator, while that of the Transverse Mercator touches the planet along a meridian, i.e. along a line perpendicular to the Equator. @@ -62,6 +59,10 @@ is more complex, involving initial steps projecting from the ellipsoid to anothe curved surface, the "aposphere", then projection from the aposphere to the skew uv-plane, before finally rectifying the skew uv-plane onto the map XY plane. + +Usage +######## + The tilt angle (azimuth) of the central line can be given in two different ways. In the first case, the azimuth is given directly, using the option :option:`+alpha` and defining the centre of projection using the options :option:`+lonc` and From 02d4bdc52ffce4bf83a87b186f6699772b6252df Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 22 Feb 2019 12:10:05 +0100 Subject: [PATCH 5/7] learning some reST, improving some different highlighting effects --- docs/source/operations/projections/omerc.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index d522ea9244..18a388bf9d 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -74,6 +74,8 @@ the central line, using the options Example: Verify that the Mercator projection is a limiting form of the Oblique Mercator +:: + $ echo 12 55 | proj +proj=merc +ellps=GRS80 1335833.89 7326837.71 @@ -82,12 +84,16 @@ Mercator Example: Second case - indirectly given azimuth +:: + $ echo 12 55 | proj +proj=omerc +lon_1=-1 +lat_1=1 +lon_2=0 +lat_2=0 +ellps=GRS80 349567.57 6839490.50 Example: An approximation of the Danish "System 34" from :cite:`Rittri2012` +:: + $ echo 10.536498003 56.229892362 | proj +proj=omerc +axis=wnu +lonc=9.46 +lat_0=56.13333333 +x_0=-266906.229 +y_0=189617.957 +k=0.9999537 +alpha=-0.76324 +gamma=0 +ellps=GRS80 200000.13 199999.89 @@ -150,8 +156,8 @@ Optional No rectification (not "no rotation" as one may well assume). Do not take the last step from the skew uv-plane to the map - XY plane. This option is probably only marginally useful, but - remains for (mostly) historical reasons. + XY plane. + .. note:: This option is probably only marginally useful, but remains for (mostly) historical reasons. .. option:: +no_off From dd459e66d7493d918ae175e0f9d68e70084ecafd Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 22 Feb 2019 13:02:33 +0100 Subject: [PATCH 6/7] Correction of PROJ mailing list URL in references.bib --- docs/source/references.bib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/references.bib b/docs/source/references.bib index a2017ef5f6..a15aa07aee 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -215,7 +215,7 @@ @Misc{Rittri2012 author = {Mikael Rittri}, title = {New omerc approximations of Denmark System 34}, year = {2012}, - url = {http://lists.maptools.org/pipermail/proj/2012-June/006323.html} + url = {https://lists.osgeo.org/pipermail/proj/2012-June/005926.html} } @article{Ruffhead2016, From 6e30e855c72f9217ca38e57cdb07c083fee0b564 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 24 Feb 2019 14:14:53 +0100 Subject: [PATCH 7/7] Add a blank line above "..note::" It won't render correctly otherwise. --- docs/source/operations/projections/omerc.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index 18a388bf9d..ba2edf457a 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -157,6 +157,7 @@ Optional No rectification (not "no rotation" as one may well assume). Do not take the last step from the skew uv-plane to the map XY plane. + .. note:: This option is probably only marginally useful, but remains for (mostly) historical reasons. .. option:: +no_off