diff options
Diffstat (limited to 'docs/source/operations')
20 files changed, 453 insertions, 20 deletions
diff --git a/docs/source/operations/conversions/index.rst b/docs/source/operations/conversions/index.rst index a9d137ab..42ad079d 100644 --- a/docs/source/operations/conversions/index.rst +++ b/docs/source/operations/conversions/index.rst @@ -15,6 +15,7 @@ conversions. cart geoc latlon + noop pop push unitconvert diff --git a/docs/source/operations/conversions/noop.rst b/docs/source/operations/conversions/noop.rst new file mode 100644 index 00000000..a35b2b58 --- /dev/null +++ b/docs/source/operations/conversions/noop.rst @@ -0,0 +1,28 @@ +.. _noop: + +================================================================================ +No operation +================================================================================ + +.. versionadded:: 6.1.0 + +Pass a coordinate through unchanged. + ++---------------------+--------------------------------------------------------+ +| **Alias** | noop | ++---------------------+--------------------------------------------------------+ +| **Domain** | 4D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Any | ++---------------------+--------------------------------------------------------+ +| **Output type** | Any | ++---------------------+--------------------------------------------------------+ + +The no operation is a dummy operation that returns whatever is passed to it +as seen in this example:: + + $ echo 12 34 56 78 | cct +proj=noop + 12.0000 34.0000 56.0000 78.0000 + +The operation has no options and default options will not affect the output. + diff --git a/docs/source/operations/projections/aea.rst b/docs/source/operations/projections/aea.rst index 211ce83c..70b3e75e 100644 --- a/docs/source/operations/projections/aea.rst +++ b/docs/source/operations/projections/aea.rst @@ -25,17 +25,21 @@ Albers Equal Area :align: center :alt: Albers Equal Area - proj-string: ``+proj=aea`` + proj-string: ``+proj=aea +lat_1=29.5 +lat_2=42.5`` Options ################################################################################ -.. note:: All options are optional for the Albers Equal Area projection. +Required +-------------------------------------------------------------------------------- .. include:: ../options/lat_1.rst .. include:: ../options/lat_2.rst +Optional +-------------------------------------------------------------------------------- + .. include:: ../options/lon_0.rst .. include:: ../options/ellps.rst diff --git a/docs/source/operations/projections/comill.rst b/docs/source/operations/projections/comill.rst new file mode 100644 index 00000000..fa04ec18 --- /dev/null +++ b/docs/source/operations/projections/comill.rst @@ -0,0 +1,46 @@ +.. _comill: + +******************************************************************************** +Compact Miller +******************************************************************************** + +The Compact Miller projection is a cylindrical map projection with a +height-to-width ratio of 0.6:1. + +See :cite:`Jenny2015` + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | comill | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/comill.png + :width: 500 px + :align: center + :alt: Compact Miller + + proj-string: ``+proj=comill`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/docs/source/operations/projections/images/times.png b/docs/source/operations/projections/images/times.png Binary files differnew file mode 100644 index 00000000..b7d9c481 --- /dev/null +++ b/docs/source/operations/projections/images/times.png diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index e6ec9076..c5b249c9 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -31,6 +31,7 @@ Projections map the spherical 3D space to a flat 2D space. cea chamb collg + comill crast denoy eck1 @@ -83,11 +84,13 @@ Projections map the spherical 3D space to a flat 2D space. merc mil_os mill + misrsom moll murd1 murd2 murd3 natearth + natearth2 nell nell_h nicol @@ -99,6 +102,7 @@ Projections map the spherical 3D space to a flat 2D space. omerc ortel ortho + patterson pconic poly putp1 @@ -115,6 +119,7 @@ Projections map the spherical 3D space to a flat 2D space. robin rouss rpoly + sch sinu somerc stere @@ -122,6 +127,7 @@ Projections map the spherical 3D space to a flat 2D space. gstmerc tcc tcea + times tissot tmerc tobmerc diff --git a/docs/source/operations/projections/lcc.rst b/docs/source/operations/projections/lcc.rst index 3b2032d6..d3ba026f 100644 --- a/docs/source/operations/projections/lcc.rst +++ b/docs/source/operations/projections/lcc.rst @@ -42,19 +42,23 @@ justifies adding this otherwise non-standard projection. :align: center :alt: Lambert Conformal Conic - proj-string: ``+proj=lcc +lon_0=-90`` + proj-string: ``+proj=lcc +lon_0=-90 +lat_1=33 +lat_2=45`` Parameters ################################################################################ -.. note:: All parameters are optional for the projection. +Required +-------------------------------------------------------------------------------- + +.. include:: ../options/lat_1.rst + +Optional +-------------------------------------------------------------------------------- .. include:: ../options/lon_0.rst .. include:: ../options/lat_0.rst -.. include:: ../options/lat_1.rst - .. include:: ../options/lat_2.rst .. include:: ../options/ellps.rst diff --git a/docs/source/operations/projections/misrsom.rst b/docs/source/operations/projections/misrsom.rst new file mode 100644 index 00000000..bb738fa0 --- /dev/null +++ b/docs/source/operations/projections/misrsom.rst @@ -0,0 +1,36 @@ +.. _misrsom: + +******************************************************************************** +Space oblique for MISR +******************************************************************************** + +.. figure:: ./images/misrsom.png + :width: 500 px + :align: center + :alt: Space oblique for MISR + + proj-string: ``+proj=misrsom +path=1`` + +Parameters +################################################################################ + +Required +-------------------------------------------------------------------------------- + +.. option:: +path=<value> + + Selected path of satellite. Value between 1 and 233. + + +Optional +-------------------------------------------------------------------------------- + +.. include:: ../options/lon_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/docs/source/operations/projections/natearth2.rst b/docs/source/operations/projections/natearth2.rst new file mode 100644 index 00000000..a5128ea9 --- /dev/null +++ b/docs/source/operations/projections/natearth2.rst @@ -0,0 +1,49 @@ +.. _natearth2: + +******************************************************************************** +Natural Earth II +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | natearth2 | ++---------------------+--------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + + +.. figure:: ./images/natearth2.png + :width: 500 px + :align: center + :alt: Natural Earth II + + proj-string: ``+proj=natearth2`` + +The Natural Earth II projection is intended for making world maps. At high +latitudes, meridians bend steeply toward short pole lines resulting in a map +with highly rounded corners that resembles an elongated globe. + +See :cite:`Savric2015` + + +Parameters +################################################################################ + +.. note:: All parameters for the projection are optional. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/docs/source/operations/projections/ob_tran.rst b/docs/source/operations/projections/ob_tran.rst index d0a051e0..378f1333 100644 --- a/docs/source/operations/projections/ob_tran.rst +++ b/docs/source/operations/projections/ob_tran.rst @@ -17,7 +17,7 @@ Usage All of the projections of spherical library can be used as an oblique projection by means of the General Oblique Transformation. The user performs the oblique transformation by selecting the oblique projection -``+proj=obt_ran``, specifying the translation factors, :option:`+o_lat_p`, and +``+proj=ob_tran``, specifying the translation factors, :option:`+o_lat_p`, and :option:`+o_lon_p`, and the projection to be used, :option:`+o_proj`. In the example of the Fairgrieve projection the latitude and longitude of the pole of the new coordinates, :math:`\alpha` and :math:`\beta` respectively, are to be placed diff --git a/docs/source/operations/projections/omerc.rst b/docs/source/operations/projections/omerc.rst index 7131df62..ba2edf45 100644 --- a/docs/source/operations/projections/omerc.rst +++ b/docs/source/operations/projections/omerc.rst @@ -4,6 +4,27 @@ Oblique Mercator ******************************************************************************** +The Oblique Mercator projection is a cylindrical map projection that closes the +gap between the Mercator and the Transverse Mercator projections. + ++---------------------+----------------------------------------------------------+ +| **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 +32,77 @@ Oblique Mercator proj-string: ``+proj=omerc +lat_1=45 +lat_2=55`` + +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. + + +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 + + $ echo 12 55 | proj +proj=omerc +lonc=0 +alpha=90 +ellps=GRS80 + 1335833.89 7326837.71 + +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 + +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 +154,11 @@ 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. + + .. note:: This option is probably only marginally useful, but remains for (mostly) historical reasons. .. option:: +no_off diff --git a/docs/source/operations/projections/patterson.rst b/docs/source/operations/projections/patterson.rst new file mode 100644 index 00000000..b68a14d0 --- /dev/null +++ b/docs/source/operations/projections/patterson.rst @@ -0,0 +1,46 @@ +.. _patterson: + +******************************************************************************** +Patterson +******************************************************************************** + +The Patterson projection is a cylindrical map projection designed for +general-purpose mapmaking. + +See :cite:`Patterson2014` + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | patterson | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/patterson.png + :width: 500 px + :align: center + :alt: Patterson + + proj-string: ``+proj=patterson`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/docs/source/operations/projections/sch.rst b/docs/source/operations/projections/sch.rst new file mode 100644 index 00000000..f987d75d --- /dev/null +++ b/docs/source/operations/projections/sch.rst @@ -0,0 +1,65 @@ +.. _sch: + +******************************************************************************** +Spherical Cross-track Height +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Miscellaneous | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse. | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Alias** | sch | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | 3D coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+--------------------------------------------------------+ + + proj-string: ``+proj=sch +plat_0=XX +plon_0=XX +phdg_0=XX`` + +The SCH coordinate system is a sensor aligned coordinate system developed at +JPL (Jet Propulsion Laboratory) for radar mapping missions. + +See :cite:`Hensley2002` + + +Parameters +################################################################################ + +Required +------------------------------------------------------------------------------- + +.. option:: +plat_0=<value> + + Peg latitude (in degree) + +.. option:: +plon_0=<value> + + Peg longitude (in degree) + +.. option:: +phdg_0=<value> + + Peg heading (in degree) + +Optional +------------------------------------------------------------------------------- + +.. option:: +h_0=<value> + + Average height (in metre) + + *Defaults to 0.0.* + +.. include:: ../options/lon_0.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst + +.. include:: ../options/ellps.rst + +.. include:: ../options/R.rst diff --git a/docs/source/operations/projections/times.rst b/docs/source/operations/projections/times.rst new file mode 100644 index 00000000..33e12148 --- /dev/null +++ b/docs/source/operations/projections/times.rst @@ -0,0 +1,43 @@ +.. _times: + +******************************************************************************** +Times +******************************************************************************** + +See :cite:`Snyder1993`, p.213-214. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Alias** | times | ++---------------------+----------------------------------------------------------+ +| **Domain** | 2D | ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates | ++---------------------+----------------------------------------------------------+ +| **Output type** | Projected coordinates | ++---------------------+----------------------------------------------------------+ + +.. figure:: ./images/times.png + :width: 500 px + :align: center + :alt: Times + + proj-string: ``+proj=times`` + +Parameters +################################################################################ + +.. note:: All parameters are optional for projection. + +.. include:: ../options/lon_0.rst + +.. include:: ../options/R.rst + +.. include:: ../options/x_0.rst + +.. include:: ../options/y_0.rst diff --git a/docs/source/operations/projections/tmerc.rst b/docs/source/operations/projections/tmerc.rst index fd600001..a52e4059 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/operations/projections/tobmerc.rst b/docs/source/operations/projections/tobmerc.rst index d9a3eb05..69a4855d 100644 --- a/docs/source/operations/projections/tobmerc.rst +++ b/docs/source/operations/projections/tobmerc.rst @@ -66,7 +66,7 @@ Mathematical definition ####################### The formulas describing the Tobler-Mercator are taken from Waldo Tobler's -article :cite:`Tobler2017` +article :cite:`Tobler2018` Spherical form ************** diff --git a/docs/source/operations/projections/urm5.rst b/docs/source/operations/projections/urm5.rst index c44632d4..4d2dd557 100644 --- a/docs/source/operations/projections/urm5.rst +++ b/docs/source/operations/projections/urm5.rst @@ -14,12 +14,14 @@ Urmaev V Parameters ################################################################################ -.. note:: All parameters are optional for the projection. - +Required parameters +-------------------------------------------------------------------------------- .. option:: +n=<value> Set the :math:`n` constant. Value between 0 and 1. +Optional parameters +-------------------------------------------------------------------------------- .. option:: +q=<value> Set the :math:`q` constant. diff --git a/docs/source/operations/transformations/geogoffset.rst b/docs/source/operations/transformations/geogoffset.rst index f643485e..6ca4f64c 100644 --- a/docs/source/operations/transformations/geogoffset.rst +++ b/docs/source/operations/transformations/geogoffset.rst @@ -21,11 +21,11 @@ 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 (:cite:`EPSGGuidanceNumber7Part2`) +geographic 3D) in the EPSG dataset (:cite:`IOGP2018`) 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 +height and the output vertical component is the ellipsoid height (dh being the geoid undulation). It can also be used to implement the method Vertical offset (code 9616) diff --git a/docs/source/operations/transformations/horner.rst b/docs/source/operations/transformations/horner.rst index dd9b9cc9..5c88c292 100644 --- a/docs/source/operations/transformations/horner.rst +++ b/docs/source/operations/transformations/horner.rst @@ -28,7 +28,7 @@ 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`. +:cite:`Ruffhead2016` and :cite:`IOGP2018`. The polynomial evaluation in real number space is defined by the following equations: diff --git a/docs/source/operations/transformations/vgridshift.rst b/docs/source/operations/transformations/vgridshift.rst index 484ad4bf..04be5b1b 100644 --- a/docs/source/operations/transformations/vgridshift.rst +++ b/docs/source/operations/transformations/vgridshift.rst @@ -23,7 +23,7 @@ a specific amount determined by the loaded grids. The simplest use case of the horizontal grid shift is applying a single grid. Here we change the vertical reference from the ellipsoid to the global geoid model, EGM96:: - +proj=vgridshift +grids=egm96_16.gtx + +proj=vgridshift +grids=egm96_15.gtx More than one grid can be loaded at the same time, for instance in the case where @@ -31,7 +31,7 @@ a better geoid model than the global is available for a certain area. Here the gridshift is set up so that the local DVR90 geoid model takes precedence over the global model:: - +proj=vgridshift +grids=@dvr90.gtx,egm96_16.gtx + +proj=vgridshift +grids=@dvr90.gtx,egm96_15.gtx The ``@`` in the above example states that the grid is optional, in case the grid is not found in the PROJ search path. The list of grids is prioritized so that |
