diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/conf.py | 2 | ||||
| -rw-r--r-- | docs/source/operations/projections/bertin1953.rst | 64 | ||||
| -rw-r--r-- | docs/source/operations/projections/images/bertin1953.png | bin | 0 -> 177358 bytes | |||
| -rw-r--r-- | docs/source/operations/projections/images/tobmerc.png | bin | 0 -> 575982 bytes | |||
| -rw-r--r-- | docs/source/operations/projections/index.rst | 2 | ||||
| -rw-r--r-- | docs/source/operations/projections/lcc.rst | 51 | ||||
| -rw-r--r-- | docs/source/operations/projections/tobmerc.rst | 100 | ||||
| -rw-r--r-- | docs/source/operations/transformations/horner.rst | 213 | ||||
| -rw-r--r-- | docs/source/operations/transformations/index.rst | 1 | ||||
| -rw-r--r-- | docs/source/references.bib | 24 |
10 files changed, 456 insertions, 1 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py index 8892dffc..434e4d73 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -85,7 +85,7 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ['operations/options/*.rst'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/source/operations/projections/bertin1953.rst b/docs/source/operations/projections/bertin1953.rst new file mode 100644 index 00000000..8be521f3 --- /dev/null +++ b/docs/source/operations/projections/bertin1953.rst @@ -0,0 +1,64 @@ +.. _bertin1953: + +******************************************************************************** +Bertin 1953 +******************************************************************************** + +.. versionadded:: 6.0.0 + ++---------------------+-------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+-------------------------------+ +| **Available forms** | Forward, spherical projection | ++---------------------+-------------------------------+ +| **Defined area** | Global | ++---------------------+-------------------------------+ +| **Alias** | bertin1953 | ++---------------------+-------------------------------+ +| **Domain** | 2D | ++---------------------+-------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+-------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+-------------------------------+ + + + +.. figure:: ./images/bertin1953.png + :width: 500 px + :align: center + :alt: Bertin 1953 + + proj-string: ``+proj=bertin1953`` + + +The Bertin 1953 projection is intended for making world maps. Created by Jacques Bertin +in 1953, this projection was the go-to choice of the French cartographic school when they +wished to represent phenomena on a global scale. The projection was formulated in 2017 +by Philippe Rivière for visionscarto.net. + + +Usage +############################################################################### + +The Bertin 1953 projection has no special options. Its rotation parameters +are fixed. Here is an example of a forward projection with scale 1: + + $ echo 122 47 | src/proj +proj=bertin1953 +R=1 + 0.72 0.73 + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +Further reading +################################################################################ + +#. Philippe Rivière (2017). `Bertin Projection (1953) <https://visionscarto.net/bertin-projection-1953>`, Visionscarto.net. diff --git a/docs/source/operations/projections/images/bertin1953.png b/docs/source/operations/projections/images/bertin1953.png Binary files differnew file mode 100644 index 00000000..9b272033 --- /dev/null +++ b/docs/source/operations/projections/images/bertin1953.png diff --git a/docs/source/operations/projections/images/tobmerc.png b/docs/source/operations/projections/images/tobmerc.png Binary files differnew file mode 100644 index 00000000..291bdac9 --- /dev/null +++ b/docs/source/operations/projections/images/tobmerc.png diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index a48eabe6..572deb1a 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -20,6 +20,7 @@ Projections map the spherical 3D space to a flat 2D space. apian august bacon + bertin1953 bipc boggs bonne @@ -124,6 +125,7 @@ Projections map the spherical 3D space to a flat 2D space. tcea tissot tmerc + tobmerc tpeqd tpers ups diff --git a/docs/source/operations/projections/lcc.rst b/docs/source/operations/projections/lcc.rst index 6db2a73c..3b2032d6 100644 --- a/docs/source/operations/projections/lcc.rst +++ b/docs/source/operations/projections/lcc.rst @@ -4,6 +4,39 @@ Lambert Conformal Conic ******************************************************************************** +A Lambert Conformal Conic projection (LCC) is a conic map projection +used for aeronautical charts, portions of the State Plane Coordinate +System, and many national and regional mapping systems. It is one of +seven projections introduced by Johann Heinrich Lambert in 1772. + +It has several different forms: with one and two standard parallels +(referred to as 1SP and 2SP in EPSG guidance notes). Additionally we +provide "2SP Michigan" form which is very similar to normal 2SP, but +with a scaling factor on the ellipsoid (given as `k_0` parameter). +It is implemented as per EPSG Guidance Note 7-2 (version 54, August +2018, page 25). It is used in a few systems in the EPSG database which +justifies adding this otherwise non-standard projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection.| +| | One or two standard parallels (1SP and 2SP). | +| | "LCC 2SP Michigan" form can be used by setting | +| | `+k_0` parameter to specify elliposid scale. | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Best for regions predominantly east–west in extent and | +| | located in the middle north or south latitudes. | ++---------------------+----------------------------------------------------------+ +| **Alias** | lcc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + .. figure:: ./images/lcc.png :width: 500 px :align: center @@ -31,3 +64,21 @@ Parameters .. include:: ../options/x_0.rst .. include:: ../options/y_0.rst + +.. option:: +k_0=<value> + + This parameter can represent two different values depending on the + form of the projection. In LCC 1SP it determines the scale factor + at natural origin. In LCC 2SP Michigan it determines the ellipsoid + scale factor. + + *Defaults to 1.0.* + +Further reading +############### + +#. `Wikipedia <https://en.wikipedia.org/wiki/Lambert_conformal_conic_projection>`_ +#. `Wolfram Mathworld <http://mathworld.wolfram.com/LambertConformalConicProjection.html>`_ +#. `John P. Snyder "Map projections: A working manual" (pp. 104-110) <https://pubs.er.usgs.gov/publication/pp1395>`_ +#. `ArcGIS documentation on "Lambert Conformal Conic" <http://desktop.arcgis.com/en/arcmap/10.3/guide-books/map-projections/lambert-conformal-conic.htm>`_ +#. `EPSG Guidance Note 7-2 (version 54, August 2018, page 25) <http://www.epsg.org/Guidancenotes.aspx>`_ diff --git a/docs/source/operations/projections/tobmerc.rst b/docs/source/operations/projections/tobmerc.rst new file mode 100644 index 00000000..d9a3eb05 --- /dev/null +++ b/docs/source/operations/projections/tobmerc.rst @@ -0,0 +1,100 @@ +.. _tobmerc: + +******************************************************************************** +Tobler-Mercator +******************************************************************************** + +.. versionadded:: 6.0.0 + +Equal area cylindrical projection with the same latitudinal spacing as +Mercator projection. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical equal area | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical only | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, conventionally truncated at about 80 degrees | +| | north and south | ++---------------------+----------------------------------------------------------+ +| **Alias** | tobmerc | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/tobmerc.png + :width: 500 px + :align: center + :alt: Tobler-Mercator + + proj-string: ``+proj=tobmerc`` + +Usage +##### + +The inappropriate use of the Mercator projection has declined but still +occasionally occurs. One method of contrasting the Mercator projection is to +present an alternative in the form of an equal area projection. The map +projection derived here is thus not simply a pretty Christmas tree ornament: +it is instead a complement to Mercator's conformal navigation anamorphose +and can be displayed as an alternative. The equations for the new map +projection preserve the latitudinal stretching of the Mercator while +adjusting the longitudinal spacing. This allows placement of the new map +adjacent to that of Mercator. The surface area, while drastically warped, +maintains the correct magnitude. + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/k_0.rst + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/R.rst + +Mathematical definition +####################### + +The formulas describing the Tobler-Mercator are taken from Waldo Tobler's +article :cite:`Tobler2017` + +Spherical form +************** +For the spherical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = \cos^2 \phi_{ts} + +Forward projection +================== + +.. math:: + + x = k_0 \lambda + +.. math:: + + y = k_0 \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0} + +.. math:: + + \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y/k_0} \right] diff --git a/docs/source/operations/transformations/horner.rst b/docs/source/operations/transformations/horner.rst new file mode 100644 index 00000000..dd9b9cc9 --- /dev/null +++ b/docs/source/operations/transformations/horner.rst @@ -0,0 +1,213 @@ +.. _horner: + +================================================================================ +Horner polynomial evaluation +================================================================================ + +.. versionadded:: 5.0.0 + ++-----------------+-------------------------------------------------------------------+ +| **Alias** | horner | ++-----------------+-------------------------------------------------------------------+ +| **Domain** | 2D and 3D | ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Geodetic and projected coordinates | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Geodetic and projected coordinates | ++-----------------+-------------------------------------------------------------------+ + +The Horner polynomial evaluation scheme is used for transformations between reference +frames where one or both are inhomogenous or internally distorted. This will typically +be reference frames created before the introduction of space geodetic techniques such +as GPS. + +Horner polynomials, or Multiple Regression Equations as they are also known as, have +their strength in being able to create complicated mappings between coordinate +reference frames while still being lightweight in both computational cost and disk +space used. + +PROJ implements two versions of the Horner evaluation scheme: Real and complex +polynomial evaluation. Below both are briefly described. For more details consult +:cite:`Ruffhead2016` and :cite:`EPSGGuidanceNumber7Part2`. + +The polynomial evaluation in real number space is defined by the following equations: + +.. math:: + :label: real_poly + + \Delta X = \sum_{i,j} u_{i,j} U^i V^j + + \Delta Y = \sum_{i,j} v_{i,j} U^i V^j + +where + +.. math:: + :label: UV + + U = X_{in} - X_{origin} + + V = Y_{in} - Y_{origin} + +and :math:`u_{i,j}` and :math:`v_{i,j}` are coefficients that make up +the polynomial. + +The final coordinates are determined as + +.. math:: + :label: xy_out + + X_{out} = X_{in} + \Delta X + + Y_{out} = Y_{in} + \Delta Y + +The inverse transform is the same as the above but requires a different set of +coefficients. + +Evaluation of the complex polynomials are defined by the following equations: + +.. math:: + :label: complex_poly + + \Delta X + i \Delta Y = \sum_{j=1}^n (c_{2j-1} + i c_{2j}) (U + i V)^j + +Where :math:`n` is the degree of the polynomial. :math:`U` and :math:`V` are +defined as in :eq:`UV` and the resulting coordinates are again determined +by :eq:`xy_out`. + +Examples +################################################################################ + +Mapping between Danish TC32 and ETRS89/UTM zone 32 using polynomials in real +number space:: + + +proj=horner + +ellps=intl + +range=500000 + +fwd_origin=877605.269066,6125810.306769 + +inv_origin=877605.760036,6125811.281773 + +deg=4 + +fwd_v=6.1258112678e+06,9.9999971567e-01,1.5372750011e-10,5.9300860915e-15,2.2609497633e-19,4.3188227445e-05,2.8225130416e-10,7.8740007114e-16,-1.7453997279e-19,1.6877465415e-10,-1.1234649773e-14,-1.7042333358e-18,-7.9303467953e-15,-5.2906832535e-19,3.9984284847e-19 + +fwd_u=8.7760574982e+05,9.9999752475e-01,2.8817299305e-10,5.5641310680e-15,-1.5544700949e-18,-4.1357045890e-05,4.2106213519e-11,2.8525551629e-14,-1.9107771273e-18,3.3615590093e-10,2.4380247154e-14,-2.0241230315e-18,1.2429019719e-15,5.3886155968e-19,-1.0167505000e-18 + +inv_v=6.1258103208e+06,1.0000002826e+00,-1.5372762184e-10,-5.9304261011e-15,-2.2612705361e-19,-4.3188331419e-05,-2.8225549995e-10,-7.8529116371e-16,1.7476576773e-19,-1.6875687989e-10,1.1236475299e-14,1.7042518057e-18,7.9300735257e-15,5.2881862699e-19,-3.9990736798e-19 + +inv_u=8.7760527928e+05,1.0000024735e+00,-2.8817540032e-10,-5.5627059451e-15,1.5543637570e-18,4.1357152105e-05,-4.2114813612e-11,-2.8523713454e-14,1.9109017837e-18,-3.3616407783e-10,-2.4382678126e-14,2.0245020199e-18,-1.2441377565e-15,-5.3885232238e-19,1.0167203661e-18 + + +Mapping between Danish System Storebælt and ETRS89/UTM zone 32 using complex +polynomials:: + + +proj=horner + +ellps=intl + +range=500000 + +fwd_origin=4.94690026817276e+05,6.13342113183056e+06 + +inv_origin=6.19480258923588e+05,6.13258568148837e+06 + +deg=3 + +fwd_c=6.13258562111350e+06,6.19480105709997e+05,9.99378966275206e-01,-2.82153291753490e-02,-2.27089979140026e-10,-1.77019590701470e-09,1.08522286274070e-14,2.11430298751604e-15 + +inv_c=6.13342118787027e+06,4.94690181709311e+05,9.99824464710368e-01,2.82279070814774e-02,7.66123542220864e-11,1.78425334628927e-09,-1.05584823306400e-14,-3.32554258683744e-15 + +Parameters +################################################################################ + +Setting up Horner polynomials requires many coefficients being explicitly +written, even for polynomials of low degree. For this reason it is recommended +to store the polynomial definitions in an :ref:`init file <init_files>` for +easier writing and reuse. + +Required +------------------------------------------------------------------------------- + +Below is a list of required parameters that can be set for the Horner polynomial +transformation. As stated above, the transformation takes to forms, either using +real or complex polynomials. These are divided into separate sections below. +Parameters from the two sections are mutually exclusive, that is parameters +describing real and complex polynomials can't be mixed. + +.. include:: ../options/ellps.rst + +.. option:: +deg=<value> + + Degree of polynomial + +.. option:: +fwd_origin=<northing,easting> + + Coordinate of origin for the forward mapping + +.. option:: +inv_origin=<northing,easting> + + Coordinate of origin for the inverse mapping + +Real polynomials +.............................................................................. + +The following parameters has to be set if the transformation consists of +polynomials in real space. Each parameter takes a comma-separated list of +coefficients. The number of coefficients is governed by the degree, :math:`d`, +of the polynomial: + +.. math:: + + N = \frac{(d + 1)(d + 2)}{2} + +.. option:: +fwd_u=<u_11,u_12,...,u_ij,..,u_mn> + + Coefficients for the forward transformation i.e. latitude to northing + as described in :eq:`real_poly`. + +.. option:: +fwd_v=<v_11,v_12,...,v_ij,..,v_mn> + + Coefficients for the forward transformation i.e. longitude to easting + as described in :eq:`real_poly`. + +.. option:: +inv_u=<u_11,u_12,...,u_ij,..,u_mn> + + Coefficients for the inverse transformation i.e. latitude to northing + as described in :eq:`real_poly`. + +.. option:: +inv_v=<v_11,v_12,...,v_ij,..,v_mn> + + Coefficients for the inverse transformation i.e. longitude to easting + as described in :eq:`real_poly`. + + + +Complex polynomials +.............................................................................. + +The following parameters has to be set if the transformation consists of +polynomials in complex space. Each parameter takes a comma-separated list of +coefficients. The number of coefficients is governed by the degree, :math:`d`, +of the polynomial: + +.. math:: + + N = 2d + 2 + +.. option:: +fwd_c=<c_1,c_2,...,c_N> + + Coefficients for the complex forward transformation + as described in :eq:`complex_poly`. + +.. option:: +inv_c=<c_1,c_2,...,c_N> + + Coefficients for the complex inverse transformation + as described in :eq:`complex_poly`. + +Optional +------------------------------------------------------------------------------- + +.. option:: +range=<value> + + Radius of the region of validity. + +.. option:: +uneg + + Express latitude as southing. Only applies for complex polynomials. + +.. option:: +vneg + + Express longitude as westing. Only applies for complex polynomials. + + +Further reading +################################################################################ + +#. `Wikipedia <https://en.wikipedia.org/wiki/Horner%27s_method>`_ diff --git a/docs/source/operations/transformations/index.rst b/docs/source/operations/transformations/index.rst index 121215f7..45c4a80b 100644 --- a/docs/source/operations/transformations/index.rst +++ b/docs/source/operations/transformations/index.rst @@ -14,6 +14,7 @@ systems are based on different datums. deformation geogoffset helmert + horner molodensky hgridshift vgridshift diff --git a/docs/source/references.bib b/docs/source/references.bib index 0fb077ec..1e6929bb 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -197,6 +197,18 @@ Url = {https://archive.org/details/DTIC_ADA026294} } +@article{Ruffhead2016, + author = {A. C. Ruffhead}, + title = {Introduction to multiple regression equations in datum transformations and their reversibility}, + journal = {Survey Review}, + volume = {50}, + number = {358}, + pages = {82-90}, + year = {2016}, + publisher = {Taylor & Francis}, + doi = {10.1080/00396265.2016.1244143}, +} + @Book{Snyder1993, Title = {Flattening the Earth}, Author = {J. P. Snyder}, @@ -247,6 +259,18 @@ Edition = {15th} } +@Article{Tobler2017, + Author = {W. Tobler}, + Title = {A new companion for Mercator}, + Journal = {Cartography and Geographic Information Science}, + Volume = {45}, + Number = {3}, + Pages = {284-285}, + Publisher = {Taylor & Francis}, + Year = {2017}, + Doi = {10.1080/15230406.2017.1308837}, +} + @Article{Verey2017, Title = {Theoretical analysis and practical consequences of adopting a model {ATPOL} grid as a conical projection defining the conversion of plane coordinates to the {WGS} 84 ellipsoid}, Author = {M. Verey}, |
