From 24510326837c79f902b040b0987f225af8fcd4f9 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 23 Feb 2019 10:39:23 +0100 Subject: Doc: add minimal documentation for patterson projection --- docs/source/operations/projections/index.rst | 1 + docs/source/operations/projections/patterson.rst | 46 ++++++++++++++++++++++++ docs/source/references.bib | 10 ++++++ 3 files changed, 57 insertions(+) create mode 100644 docs/source/operations/projections/patterson.rst (limited to 'docs/source') diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index e6ec9076..5e612d9f 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -99,6 +99,7 @@ Projections map the spherical 3D space to a flat 2D space. omerc ortel ortho + patterson pconic poly putp1 diff --git a/docs/source/operations/projections/patterson.rst b/docs/source/operations/projections/patterson.rst new file mode 100644 index 00000000..11211a5f --- /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:`Patterson2015` + ++---------------------+----------------------------------------------------------+ +| **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/references.bib b/docs/source/references.bib index b36e1e2d..0d9fc8a4 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -197,6 +197,16 @@ Url = {https://archive.org/details/DTIC_ADA026294} } +@Article{Patterson2015, + Title = {Introducing the Patterson Cylindrical Projection}, + Author = {Tom Patterson, Bojan Šavrič, Bernhard Jenny}, + Journal = {Cartographic Perspectives}, + Year = {2015}, + Number = {78}, + + Doi = {10.14714/CP78.1270} +} + @article{Ruffhead2016, author = {A. C. Ruffhead}, title = {Introduction to multiple regression equations in datum transformations and their reversibility}, -- cgit v1.2.3 From aefbc02bf1fcbf2c75143ac43889664f269484cb Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 23 Feb 2019 11:32:28 +0100 Subject: Doc: add minimal doumentation for comill / Compact Miller projection --- docs/source/operations/projections/comill.rst | 46 +++++++++++++++++++++++++++ docs/source/operations/projections/index.rst | 1 + docs/source/references.bib | 10 ++++++ 3 files changed, 57 insertions(+) create mode 100644 docs/source/operations/projections/comill.rst (limited to 'docs/source') diff --git a/docs/source/operations/projections/comill.rst b/docs/source/operations/projections/comill.rst new file mode 100644 index 00000000..94b2695c --- /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:`Jenny2014` + ++---------------------+----------------------------------------------------------+ +| **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/index.rst b/docs/source/operations/projections/index.rst index 5e612d9f..63752b8c 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 diff --git a/docs/source/references.bib b/docs/source/references.bib index 0d9fc8a4..9039931a 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -140,6 +140,16 @@ Doi = {10.5281/zenodo.32050} } +@Article{Jenny2014, + Title = {A compromise aspect-adaptive cylindrical projection for world maps}, + Author = {Bernhard Jenny, Bojan Šavrič, Tom Patterson}, + Journal = {International Journal of Geographical Information Science}, + Year = {2014}, + + Doi = {10.1080/13658816.2014.997734}, + Url = {http://www.cartography.oregonstate.edu/pdf/2015_Jenny_etal_ACompromiseAspect-adaptiveCylindricalProjectionForWorldMaps.pdf} +} + @Article{Karney2013, Title = {Algorithms for geodesics}, Author = {C. F. F. Karney}, -- cgit v1.2.3 From 2d4ff76329ce598e9d11688fa47cc5bd0a9f37af Mon Sep 17 00:00:00 2001 From: Bas Couwenberg Date: Sat, 23 Feb 2019 12:02:16 +0100 Subject: Fix spelling errors. * specfied -> specified --- docs/source/apps/projinfo.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index af9ed171..fb17e480 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -103,7 +103,7 @@ The following control parameters can appear in any order: .. option:: --spatial-test contains|intersects Specify how the area of use of coordinate operations found in the database - are compared to the area of use specfied explicitly with :option:`--area` or :option:`--bbox`, + are compared to the area of use specified explicitly with :option:`--area` or :option:`--bbox`, or derivedi implictly from the area of use of the source and target CRS. By default, projinfo will only keep coordinate operations whose are of use is strictly within the area of interest (``contains`` strategy). -- cgit v1.2.3 From 02849460e7e89a2c8457d6c5fec2cea6b1f17fe1 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 23 Feb 2019 12:53:52 +0100 Subject: Doc: add minimal doumentation for natearth2 projection --- docs/source/operations/projections/index.rst | 1 + docs/source/operations/projections/natearth2.rst | 49 ++++++++++++++++++++++++ docs/source/references.bib | 10 +++++ 3 files changed, 60 insertions(+) create mode 100644 docs/source/operations/projections/natearth2.rst (limited to 'docs/source') diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index 63752b8c..1e893e97 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -89,6 +89,7 @@ Projections map the spherical 3D space to a flat 2D space. murd2 murd3 natearth + natearth2 nell nell_h nicol diff --git a/docs/source/operations/projections/natearth2.rst b/docs/source/operations/projections/natearth2.rst new file mode 100644 index 00000000..ec33141d --- /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:`Savric2016` + + +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/references.bib b/docs/source/references.bib index 9039931a..fe332eab 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -236,6 +236,16 @@ Year = {1993} } +@Article{Savric2016, + Title = {The Natural Earth II world map projection}, + Author = {Bojan Šavrič, Tom Patterson, Bernhard Jenny}, + Journal = {International Journal of Geographical Information Science}, + Year = {2016}, + + Doi = {10.1080/23729333.2015.1093312}, + Url = {http://berniejenny.info/pdf/2016_Savric_etal_NaturalEarthII.pdf} +} + @Article{Savric2018, Author = {B. Šavrič and T. Patterson and B. Jenny}, Title = {The Equal Earth map projection}, -- cgit v1.2.3 From d775b0b07bf8b7f3c78ec259238265d15abac224 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 23 Feb 2019 15:16:56 +0100 Subject: Doc: add minimal documentation for sch projection --- docs/source/operations/projections/index.rst | 1 + docs/source/operations/projections/sch.rst | 65 ++++++++++++++++++++++++++++ docs/source/references.bib | 8 ++++ 3 files changed, 74 insertions(+) create mode 100644 docs/source/operations/projections/sch.rst (limited to 'docs/source') diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index 1e893e97..b2f57987 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -118,6 +118,7 @@ Projections map the spherical 3D space to a flat 2D space. robin rouss rpoly + sch sinu somerc stere 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= + + Peg latitude (in degree) + +.. option:: +plon_0= + + Peg longitude (in degree) + +.. option:: +phdg_0= + + Peg heading (in degree) + +Optional +------------------------------------------------------------------------------- + +.. option:: +h_0= + + 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/references.bib b/docs/source/references.bib index fe332eab..8a0de291 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -140,6 +140,14 @@ Doi = {10.5281/zenodo.32050} } +@Article{Hensley2002, + Title = {Improved Processing of AIRSAR Data Based on the GeoSAR Processor}, + Author = {Scott Hensley and Elaine Chapin and Adam Freedman and Thierry Michel}, + Journal = {Airsar earth science and applications workshop}, + Year = {2002}, + Url = {https://airsar.jpl.nasa.gov/documents/workshop2002/papers/T3.pdf} +} + @Article{Jenny2014, Title = {A compromise aspect-adaptive cylindrical projection for world maps}, Author = {Bernhard Jenny, Bojan Šavrič, Tom Patterson}, -- cgit v1.2.3 From 25564ae152bfe06e765a49a7d5666645037ad0a5 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 23 Feb 2019 15:41:34 +0100 Subject: Doc: add minimal doumentation for times projection --- .../source/operations/projections/images/times.png | Bin 0 -> 421132 bytes docs/source/operations/projections/index.rst | 1 + docs/source/operations/projections/times.rst | 43 +++++++++++++++++++++ 3 files changed, 44 insertions(+) create mode 100644 docs/source/operations/projections/images/times.png create mode 100644 docs/source/operations/projections/times.rst (limited to 'docs/source') diff --git a/docs/source/operations/projections/images/times.png b/docs/source/operations/projections/images/times.png new file mode 100644 index 00000000..b7d9c481 Binary files /dev/null and b/docs/source/operations/projections/images/times.png differ diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index b2f57987..6ad4c3ff 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -126,6 +126,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/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 -- cgit v1.2.3 From 55cbf65df79dfa2616aeb337aafcc95afa73273a Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 23 Feb 2019 15:50:30 +0100 Subject: Doc: add minimal doumentation for misrsom projection --- docs/source/operations/projections/index.rst | 1 + docs/source/operations/projections/misrsom.rst | 36 ++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 docs/source/operations/projections/misrsom.rst (limited to 'docs/source') diff --git a/docs/source/operations/projections/index.rst b/docs/source/operations/projections/index.rst index 6ad4c3ff..c5b249c9 100644 --- a/docs/source/operations/projections/index.rst +++ b/docs/source/operations/projections/index.rst @@ -84,6 +84,7 @@ Projections map the spherical 3D space to a flat 2D space. merc mil_os mill + misrsom moll murd1 murd2 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= + + 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 -- cgit v1.2.3 From 38a1525b01b45420de01b0df71befd030253ebe3 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Sun, 24 Feb 2019 14:21:26 +0100 Subject: Some improvements to the docs for tmerc and omerc (#1281) --- docs/source/operations/projections/omerc.rst | 98 +++++++++++++++++++++++++++- docs/source/operations/projections/tmerc.rst | 15 +++-- docs/source/references.bib | 21 ++++++ 3 files changed, 129 insertions(+), 5 deletions(-) (limited to 'docs/source') 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/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/references.bib b/docs/source/references.bib index 8a0de291..df1dc66c 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -215,6 +215,20 @@ 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} +} + @Article{Patterson2015, Title = {Introducing the Patterson Cylindrical Projection}, Author = {Tom Patterson, Bojan Šavrič, Bernhard Jenny}, @@ -225,6 +239,13 @@ Doi = {10.14714/CP78.1270} } +@Misc{Rittri2012, + author = {Mikael Rittri}, + title = {New omerc approximations of Denmark System 34}, + year = {2012}, + url = {https://lists.osgeo.org/pipermail/proj/2012-June/005926.html} +} + @article{Ruffhead2016, author = {A. C. Ruffhead}, title = {Introduction to multiple regression equations in datum transformations and their reversibility}, -- cgit v1.2.3 From 0f056c7fd99214bd3cfc9a5d9e30ee5bd76cc44f Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sun, 24 Feb 2019 20:29:52 +0100 Subject: Doc: fix plotdefs.json, and aea and lcc descriptions, to take into account removal of proj_def.dat --- docs/source/operations/projections/aea.rst | 8 ++++++-- docs/source/operations/projections/lcc.rst | 12 ++++++++---- 2 files changed, 14 insertions(+), 6 deletions(-) (limited to 'docs/source') 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/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 -- cgit v1.2.3 From 2b880212e9b2ff6faeafb1f98c8fa76469c5907a Mon Sep 17 00:00:00 2001 From: Mike Taves Date: Thu, 28 Feb 2019 22:49:31 +1300 Subject: Miscellaneous documentation fixes - Corrections to BibTeX references, normalise format with JabRef - Typos in projinfo - Simplify update CITATION step --- docs/source/about.rst | 15 +- docs/source/apps/projinfo.rst | 4 +- docs/source/operations/projections/comill.rst | 2 +- docs/source/operations/projections/natearth2.rst | 4 +- docs/source/operations/projections/patterson.rst | 2 +- docs/source/references.bib | 171 ++++++++++++----------- 6 files changed, 100 insertions(+), 98 deletions(-) (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst index 5e625288..5171e4c7 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -23,22 +23,9 @@ datums using all but the most obscure geodetic techniques. Citation ------------------------------------------------------------------------------- -To cite PROJ in publications use: - PROJ contributors (2018). PROJ coordinate transformation software - library. Open Source Geospatial Foundation. URL https://proj4.org/. +.. include:: ../../CITATION -A BibTeX entry for LaTeX users is - -.. code-block:: latex - - @Manual{, - title = {{PROJ} coordinate transformation software library}, - author = {{PROJ contributors}}, - organization = {Open Source Geospatial Foundation}, - year = {2018}, - url = {https://proj4.org/}, - } License ------------------------------------------------------------------------------- diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index fb17e480..151b3079 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -67,7 +67,7 @@ The following control parameters can appear in any order: .. option:: --summary When listing coordinate operations available between 2 CRS, return the - result in a summary format, mentionning only the name of the coordinate + result in a summary format, mentioning only the name of the coordinate operation, its accuracy and its area of use. .. note:: only used for coordinate operation computation @@ -104,7 +104,7 @@ The following control parameters can appear in any order: Specify how the area of use of coordinate operations found in the database are compared to the area of use specified explicitly with :option:`--area` or :option:`--bbox`, - or derivedi implictly from the area of use of the source and target CRS. + or derived implicitly from the area of use of the source and target CRS. By default, projinfo will only keep coordinate operations whose are of use is strictly within the area of interest (``contains`` strategy). If using the ``intersects`` strategy, the spatial test is relaxed, and any diff --git a/docs/source/operations/projections/comill.rst b/docs/source/operations/projections/comill.rst index 94b2695c..fa04ec18 100644 --- a/docs/source/operations/projections/comill.rst +++ b/docs/source/operations/projections/comill.rst @@ -7,7 +7,7 @@ Compact Miller The Compact Miller projection is a cylindrical map projection with a height-to-width ratio of 0.6:1. -See :cite:`Jenny2014` +See :cite:`Jenny2015` +---------------------+----------------------------------------------------------+ | **Classification** | Cylindrical | diff --git a/docs/source/operations/projections/natearth2.rst b/docs/source/operations/projections/natearth2.rst index ec33141d..a5128ea9 100644 --- a/docs/source/operations/projections/natearth2.rst +++ b/docs/source/operations/projections/natearth2.rst @@ -30,9 +30,9 @@ Natural Earth II 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 +with highly rounded corners that resembles an elongated globe. -See :cite:`Savric2016` +See :cite:`Savric2015` Parameters diff --git a/docs/source/operations/projections/patterson.rst b/docs/source/operations/projections/patterson.rst index 11211a5f..b68a14d0 100644 --- a/docs/source/operations/projections/patterson.rst +++ b/docs/source/operations/projections/patterson.rst @@ -7,7 +7,7 @@ Patterson The Patterson projection is a cylindrical map projection designed for general-purpose mapmaking. -See :cite:`Patterson2015` +See :cite:`Patterson2014` +---------------------+----------------------------------------------------------+ | **Classification** | Cylindrical | diff --git a/docs/source/references.bib b/docs/source/references.bib index df1dc66c..7c1be5c8 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -3,7 +3,7 @@ @Article{Altamimi2002, - Title = {ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications}, + Title = {{ITRF2000}: A new release of the {International Terrestrial Reference Frame} for earth science applications}, Author = {Z. Altamimi and P. Sillard and C. Boucher}, Journal = {Journal of Geophysical Research: Solid Earth}, Year = {2002}, @@ -73,7 +73,7 @@ @Article{EberHewitt1979, Title = {Conversion algorithms for the {CalCOFI} station grid}, - Author = {L. E. Eber and R.P. Hewitt}, + Author = {L. E. Eber and R. P. Hewitt}, Journal = {California Cooperative Oceanic Fisheries Investigations Reports}, Year = {1979}, Pages = {135--137}, @@ -82,14 +82,6 @@ Url = {http://www.calcofi.org/publications/calcofireports/v20/Vol_20_Eber___Hewitt.pdf} } -@Manual{EPSGGuidanceNumber7Part2, - Title = {Geomatics Guidance Note 7, part 2 - Coordinate Conversions & Transformations including Formulas}, - Institution = {International Association For Oil And Gas Producers}, - Year = {2018}, - - Url = {https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/} -} - @Manual{Evenden2005, Title = {libproj4: A Comprehensive Library of Cartographic Projection Functions (Preliminary Draft)}, Author = {G. I. Evenden}, @@ -140,19 +132,24 @@ Doi = {10.5281/zenodo.32050} } -@Article{Hensley2002, - Title = {Improved Processing of AIRSAR Data Based on the GeoSAR Processor}, - Author = {Scott Hensley and Elaine Chapin and Adam Freedman and Thierry Michel}, - Journal = {Airsar earth science and applications workshop}, +@InProceedings{Hensley2002, + Title = {Improved Processing of {AIRSAR} Data Based on the {GeoSAR} Processor}, + Author = {S. Hensley and E. Chapin and A. Freedman and T. Michel}, + Booktitle = {AIRSAR Earth Science and Application Workshop}, Year = {2002}, + Organization = {Jet Propulsion Laboratory}, + Url = {https://airsar.jpl.nasa.gov/documents/workshop2002/papers/T3.pdf} } -@Article{Jenny2014, +@Article{Jenny2015, Title = {A compromise aspect-adaptive cylindrical projection for world maps}, - Author = {Bernhard Jenny, Bojan Šavrič, Tom Patterson}, + Author = {B. Jenny and B. Šavrič and T. Patterson}, Journal = {International Journal of Geographical Information Science}, - Year = {2014}, + Year = {2015}, + Number = {6}, + Pages = {935--952}, + Volume = {29}, Doi = {10.1080/13658816.2014.997734}, Url = {http://www.cartography.oregonstate.edu/pdf/2015_Jenny_etal_ACompromiseAspect-adaptiveCylindricalProjectionForWorldMaps.pdf} @@ -215,90 +212,99 @@ 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} -} - -@Article{Patterson2015, - Title = {Introducing the Patterson Cylindrical Projection}, - Author = {Tom Patterson, Bojan Šavrič, Bernhard Jenny}, +@Article{Patterson2014, + Title = {Introducing the {Patterson} Cylindrical Projection}, + Author = {T. Patterson and B. Šavrič and B. Jenny}, Journal = {Cartographic Perspectives}, - Year = {2015}, - Number = {78}, + Year = {2014}, + Volume = {78}, Doi = {10.14714/CP78.1270} } -@Misc{Rittri2012, - author = {Mikael Rittri}, - title = {New omerc approximations of Denmark System 34}, - year = {2012}, - url = {https://lists.osgeo.org/pipermail/proj/2012-June/005926.html} -} +@TechReport{Poder1998, + Title = {Some Conformal Mappings and Transformations for Geodesy and Topographic Cartography}, + Author = {K. Poder and K. Engsager}, + Institution = {National Survey and Cadastre}, + Year = {1998}, + + Address = {Copenhagen, Denmark}, + Type = {National Survey and Cadastre Publications}, -@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}, + ISBN = {87-7866-085-8}, + Pages = {63}, + Series = {4}, + Volume = {6} } -@Book{Snyder1993, - Title = {Flattening the Earth}, - Author = {J. P. Snyder}, - Publisher = {University of Chicago Press}, - Year = {1993} +@Misc{Rittri2012, + Title = {New omerc approximations of {Denmark System 34}}, + + Author = {M. Rittri}, + HowPublished = {e-mail}, + Year = {2012}, + + Url = {https://lists.osgeo.org/pipermail/proj/2012-June/005926.html} } -@Article{Savric2016, - Title = {The Natural Earth II world map projection}, - Author = {Bojan Šavrič, Tom Patterson, Bernhard Jenny}, - Journal = {International Journal of Geographical Information Science}, +@Article{Ruffhead2016, + Title = {Introduction to multiple regression equations in datum transformations and their reversibility}, + Author = {A. C. Ruffhead}, + Journal = {Survey Review}, Year = {2016}, + Number = {358}, + Pages = {82-90}, + Volume = {50}, - Doi = {10.1080/23729333.2015.1093312}, - Url = {http://berniejenny.info/pdf/2016_Savric_etal_NaturalEarthII.pdf} + Doi = {10.1080/00396265.2016.1244143}, + Publisher = {Taylor \& Francis} } @Article{Savric2018, + Title = {The {Equal Earth} map projection}, Author = {B. Šavrič and T. Patterson and B. Jenny}, - Title = {The Equal Earth map projection}, Journal = {International Journal of Geographical Information Science}, Year = {2018}, - Publisher = {Taylor & Francis}, + Number = {3}, + Volume = {33}, + Doi = {10.1080/13658816.2018.1504949}, - Url = {https://www.researchgate.net/profile/Bojan_Savric2/publication/326879978_The_Equal_Earth_map_projection/links/5b69d0ae299bf14c6d951b77/The-Equal-Earth-map-projection.pdf} + Url = {https://www.researchgate.net/publication/326879978_The_Equal_Earth_map_projection} +} + +@Article{Savric2015, + Title = {The {Natural Earth II} world map projection}, + Author = {B. Šavrič and T. Patterson and B. Jenny}, + Journal = {International Journal of Geographical Information Science}, + Year = {2015}, + Number = {2}, + Pages = {123--133}, + Volume = {1}, + + Doi = {10.1080/23729333.2015.1093312}, + Url = {https://www.researchgate.net/publication/290447301_The_Natural_Earth_II_world_map_projection} +} + +@Book{Snyder1993, + Title = {Flattening the Earth}, + Author = {J. P. Snyder}, + Publisher = {University of Chicago Press}, + Year = {1993} } @Article{Snyder1988, - Author = {J. P. Snyder }, Title = {New Equal-Area Map Projections For Noncircular Regions}, + Author = {J. P. Snyder}, Journal = {The American Cartographer}, - Volume = {15}, - Number = {4}, - Pages = {341-356}, Year = {1988}, - Publisher = {Taylor and Francis}, + Number = {4}, + Pages = {341--356}, + Volume = {15}, - Doi = {10.1559/152304088783886784} + Doi = {10.1559/152304088783886784}, + Publisher = {Taylor and Francis} } - @TechReport{Snyder1987, Title = {Map Projections --- {A} Working Manual}, Author = {J. P. Snyder}, @@ -319,15 +325,16 @@ } @Article{Tobler2017, + Title = {A new companion for {Mercator}}, 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}, + Number = {3}, + Pages = {284--285}, + Volume = {45}, + Doi = {10.1080/15230406.2017.1308837}, + Publisher = {Taylor \& Francis} } @Article{Verey2017, @@ -377,3 +384,11 @@ Doi = {10.2307/1219899} } +@Manual{EPSGGuidanceNumber7Part2, + Title = {Geomatics Guidance Note 7, part 2 - Coordinate Conversions \& Transformations including Formulas}, + Year = {2018}, + + Institution = {International Association For Oil And Gas Producers}, + Url = {https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/} +} + -- cgit v1.2.3 From a37f5fabc086ae4b9f30321b4647bfbba67e5afe Mon Sep 17 00:00:00 2001 From: Dan Baston Date: Fri, 1 Mar 2019 12:04:34 -0500 Subject: Minor doc edits --- docs/source/about.rst | 6 +++--- docs/source/download.rst | 2 +- docs/source/faq.rst | 40 ++++++++++++++++++++-------------------- docs/source/index.rst | 6 +++--- docs/source/install.rst | 4 ++-- 5 files changed, 29 insertions(+), 29 deletions(-) (limited to 'docs/source') diff --git a/docs/source/about.rst b/docs/source/about.rst index 5171e4c7..3486f23f 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -2,7 +2,7 @@ About ############################################################################### -PROJ is a generic coordinate transformation software, that transforms geospatial +PROJ is a generic coordinate transformation software that transforms geospatial coordinates from one coordinate reference system (CRS) to another. This includes cartographic projections as well as geodetic transformations. @@ -10,13 +10,13 @@ PROJ includes :ref:`command line applications` for easy conversion of coordinates from text files or directly from user input. In addition to the command line utilities PROJ also exposes an :ref:`application programming interface`, or API in short. The API -let developers use the functionality of PROJ in their own software without having +lets developers use the functionality of PROJ in their own software without having to implement similar functionality themselves. PROJ started purely as a cartography application letting users convert geodetic coordinates into projected coordinates using a number of different cartographic projections. Over the years, as the need has become apparent, support for datum -shifts has slowly worked it's way into PROJ as well. Today PROJ support more +shifts has slowly worked its way into PROJ as well. Today PROJ supports more than a hundred different map projections and can transform coordinates between datums using all but the most obscure geodetic techniques. diff --git a/docs/source/download.rst b/docs/source/download.rst index 8eba39ba..b655bed6 100644 --- a/docs/source/download.rst +++ b/docs/source/download.rst @@ -5,7 +5,7 @@ Download ================================================================================ Here you can download current and previous releases of PROJ. We only supply a -distribution of the source code and various resource files archives. See +distribution of the source code and various resource file archives. See :ref:`install` for information on how to get pre-built packages of PROJ. .. _current_release: diff --git a/docs/source/faq.rst b/docs/source/faq.rst index f72ec132..21fe158b 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -17,7 +17,7 @@ Where can I find the list of projections and their arguments? :doc:`Here<../operations/projections/index>`. -Additinoally, the ``proj`` command itself can report the list of projections +Additionally, the :program:`proj` command itself can report the list of projections using the ``-lp`` option, the list of ellipsoids with the ``-le`` option, the list of units with the ``-lu`` option, and the list of built-in datums with the ``-ld`` option. @@ -25,7 +25,7 @@ the ``-ld`` option. How do I do datum shifts between NAD27 and NAD83? -------------------------------------------------------------------------------- -Using the ``cs2cs`` application. The following example demonstrates using the +Using the :program:`cs2cs` application. The following example demonstrates using the default shift parameters for NAD27 to NAD83: :: @@ -46,23 +46,23 @@ How do I build/configure PROJ to support datum shifting? -------------------------------------------------------------------------------- After downloading and unpacking the PROJ source, also download and unpack the -set of datum shift files. See :ref:`download` for instructions how to fetch -and install these files +set of datum shift files. See :ref:`download` for instructions how to fetch +and install these files. A default build and install on Unix will normally build knowledge of the directory where the grid shift files are installed into the PROJ library (usually ``/usr/local/share/proj``). On Windows the library is normally built thinking that C:\PROJ\NAD is the installed directory for the grid shift files. -If the built in concept of the PROJ data directory is incorrect, the ``PROJ_LIB`` -environment can be defined with the correct directory. +If the built-in concept of the PROJ data directory is incorrect, the :envvar:`PROJ_LIB` +environment variable can be defined with the correct directory. How do I debug problems with NAD27/NAD83 datum shifting? -------------------------------------------------------------------------------- -1. Verify that you have the binary files (eg. ``/usr/local/share/proj/conus``) +1. Verify that you have the binary files (e.g. ``/usr/local/share/proj/conus``) installed on your system. If not, see the previous question. 2. Try a datum shifting operation in relative isolation, such as with the :program:`cs2cs` - command listed above. Do you get reasonable results? If not it is likely + command listed above. Do you get reasonable results? If not, it is likely that the grid shift files aren't being found. Perhaps you need to define :envvar:`PROJ_LIB`? 3. The :program:`cs2cs` command and the underlying :c:func:`pj_transform()` API know how to do a @@ -91,16 +91,16 @@ How do I debug problems with NAD27/NAD83 datum shifting? ``PROJ_DEBUG`` support is not yet very mature in the PROJ library. 5. The :option:`-v` flag to :program:`cs2cs` can be useful in establishing more detail on what - parameters being used internally for a coordinate system. This will include + parameters are used internally for a coordinate system. This will include expanding the definition of ``+datum`` clause. How do I use EPSG coordinate system codes with PROJ? -------------------------------------------------------------------------------- There is somewhat imperfect translation between 2D geographic and projected -coordinate system codes and PROJ descriptions of the coordinate system +coordinate system codes and PROJ descriptions of the coordinate systems available in the ``epsg`` definition file that normally lives in the ``proj/data`` -directory. If installed (it is installed by default on Unix), it is possible +directory. If installed (as is the default on Unix), it is possible to use EPSG numbers like this: :: @@ -120,10 +120,10 @@ to use EPSG numbers like this: # # +proj=latlong +datum=NAD27 +ellps=clrk66 +nadgrids=conus,ntv1_can.dat -The ``proj/data/epsg`` file can be browsed and searched in a text editor for -coordinate systems. There are known to be problems with some coordinate -systems, and any coordinate systems with odd axes, a non-greenwich prime -meridian or other quirkiness are unlikely to work properly. Caveat Emptor! +The ``proj/data/epsg`` file can be browsed and searched for coordinate systems +using a text editor. There are known to be problems with some coordinate +systems. In particular, any coordinate system with odd axes, a non-greenwich prime +meridian, or other quirky characteristics is unlikely to work properly. Caveat Emptor! How do I use 3 parameter and 7 parameter datum shifting -------------------------------------------------------------------------------- @@ -144,7 +144,7 @@ formatting of numbers, altering the role of commas and periods in numbers, then PROJ will not work. This problem is common in some European locales. On UNIX-like platforms, this problem can be avoided by forcing the use of the -default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable to C. +default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable to ``C``. :: @@ -160,7 +160,7 @@ default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable Changing Ellipsoid / Why can't I convert from WGS84 to Google Earth / Virtual Globe Mercator? ---------------------------------------------------------------------------------------------- -The coordinate system definition for Google Earth, and Virtual Globe Mercator +The coordinate system definition for Google Earth and Virtual Globe Mercator is as follows, which uses a sphere as the earth model for the Mercator projection. @@ -177,8 +177,8 @@ But, if you do something like: +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs -to convert between WGS84 and mercator on the sphere there will be substantial -shifts in the Y mercator coordinates. This is because internally :program:`cs2cs` is +to convert between WGS84 and Mercator on the sphere there will be substantial +shifts in the Y Mercator coordinates. This is because internally :program:`cs2cs` is having to adjust the lat/long coordinates from being on the sphere to being on the WGS84 datum which has a quite differently shaped ellipsoid. @@ -200,7 +200,7 @@ Note the strategic addition of ``+nadgrids=@null`` to the spherical projection definition. Similar issues apply with many other datasets distributed with projections -based on a spherical earth model - such as many NASA datasets. This coordinate +based on a spherical earth model, such as many NASA datasets. This coordinate system is now known by the EPSG code 3857 and has in the past been known as EPSG:3785 and EPSG:900913. When using this coordinate system with GDAL/OGR it is helpful to include the +wktext so the exact PROJ string will be preserved diff --git a/docs/source/index.rst b/docs/source/index.rst index 33fd096d..69f483ce 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,7 +24,7 @@ PROJ .. only:: html - PROJ is a generic coordinate transformation software, that transforms geospatial + PROJ is a generic coordinate transformation software that transforms geospatial coordinates from one coordinate reference system (CRS) to another. This includes cartographic projections as well as geodetic transformations. @@ -32,13 +32,13 @@ PROJ coordinates from text files or directly from user input. In addition to the command line utilities PROJ also exposes an :ref:`application programming interface`, or API in short. The API - let developers use the functionality of PROJ in their own software without having + lets developers use the functionality of PROJ in their own software without having to implement similar functionality themselves. PROJ started purely as a cartography application letting users convert geodetic coordinates into projected coordinates using a number of different cartographic projections. Over the years, as the need has become apparent, support for datum - shifts has slowly worked it's way into PROJ as well. Today PROJ support more + shifts has slowly worked its way into PROJ as well. Today PROJ supports more than a hundred different map projections and can transform coordinates between datums using all but the most obscure geodetic techniques. diff --git a/docs/source/install.rst b/docs/source/install.rst index ec441c1e..c050b86a 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -54,9 +54,9 @@ To install PROJ do the following: 3. Select "Advanced Install" and press Next. 4. Select "Install from Internet" and press Next. 5. Select a installation directory. The default suggestion is fine in most cases. Press Next. -6. Select "Local packacke directory". The suggestions is fine in most cases. Press Next. +6. Select "Local package directory". The default suggestion is fine in most cases. Press Next. 7. Select "Direct connection" and press Next. -8. Choose the download.osgeo.org and press Next. +8. Choose the download.osgeo.org server and press Next. 9. Find "proj" under "Commandline_Utilities" and click the package in the "New" column until the version you want to install appears. 10. Press next to install PROJ. -- cgit v1.2.3 From 519c6bcac04a9e0f74511aa241ad8cfd3191ccd8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Fri, 1 Mar 2019 19:13:31 +0100 Subject: Update docs and travis for 6.0.0 release --- docs/source/download.rst | 22 +++++--- docs/source/news.rst | 127 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+), 7 deletions(-) (limited to 'docs/source') diff --git a/docs/source/download.rst b/docs/source/download.rst index 8eba39ba..6e938644 100644 --- a/docs/source/download.rst +++ b/docs/source/download.rst @@ -13,28 +13,33 @@ distribution of the source code and various resource files archives. See Current Release -------------------------------------------------------------------------------- -* **2018-09-15** `proj-5.2.0.tar.gz`_ (`md5`_) +* **2019-03-01** `proj-6.6.0.tar.gz`_ (`md5`_) * **2018-09-15** `proj-datumgrid-1.8.zip`_ -* **2018-09-15** `proj-datumgrid-europe-1.1.zip`_ -* **2018-09-15** `proj-datumgrid-north-america-1.1.zip`_ +* **2019-03-01** `proj-datumgrid-europe-1.2.zip`_ +* **2019-03-01** `proj-datumgrid-north-america-1.2.zip`_ * **2018-03-01** `proj-datumgrid-oceania-1.0.zip`_ +* **2019-03-01** `proj-datumgrid-world-1.0.zip`_ * **PDF Manual** `proj.pdf`_ Past Releases -------------------------------------------------------------------------------- -* **2018-06-01** `proj-5.1.0.tar.gz`_ (`md5`_) -* **2018-04-01** `proj-5.0.1.tar.gz`_ (`md5`_) +* **2018-09-15** `proj-5.2.0.tar.gz`_ +* **2018-06-01** `proj-5.1.0.tar.gz`_ +* **2018-04-01** `proj-5.0.1.tar.gz`_ * **2018-03-01** `proj-5.0.0.tar.gz`_ * **2016-09-02** `proj-4.9.3.tar.gz`_ * **2015-09-13** `proj-4.9.2.tar.gz`_ * **2015-03-04** `proj-4.9.1.tar.gz`_ -* **2016-09-11** `proj-datumgrid-1.6.zip`_ * **2018-03-01** `proj-datumgrid-1.7.zip`_ +* **2016-09-11** `proj-datumgrid-1.6.zip`_ +* **2018-09-15** `proj-datumgrid-europe-1.1.zip`_ +* **2018-09-15** `proj-datumgrid-north-america-1.1.zip`_ * **2018-03-01** `proj-datumgrid-europe-1.0.zip`_ * **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_ +.. _`proj-6.0.0.tar.gz`: http://download.osgeo.org/proj/proj-6.0.0.tar.gz .. _`proj-5.2.0.tar.gz`: http://download.osgeo.org/proj/proj-5.2.0.tar.gz .. _`proj-5.1.0.tar.gz`: http://download.osgeo.org/proj/proj-5.1.0.tar.gz .. _`proj-5.0.1.tar.gz`: http://download.osgeo.org/proj/proj-5.0.1.tar.gz @@ -47,8 +52,11 @@ Past Releases .. _`proj-datumgrid-1.8.zip`: http://download.osgeo.org/proj/proj-datumgrid-1.8.zip .. _`proj-datumgrid-europe-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.0.zip .. _`proj-datumgrid-europe-1.1.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.1.zip +.. _`proj-datumgrid-europe-1.2.zip`: http://download.osgeo.org/proj/proj-datumgrid-europe-1.2.zip .. _`proj-datumgrid-north-america-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.0.zip .. _`proj-datumgrid-north-america-1.1.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.1.zip +.. _`proj-datumgrid-north-america-1.2.zip`: http://download.osgeo.org/proj/proj-datumgrid-north-america-1.2.zip .. _`proj-datumgrid-oceania-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip -.. _`md5`: http://download.osgeo.org/proj/proj-5.2.0.tar.gz.md5 +.. _`proj-datumgrid-world-1.0.zip`: http://download.osgeo.org/proj/proj-datumgrid-world-1.0.zip +.. _`md5`: http://download.osgeo.org/proj/proj-6.0.0.tar.gz.md5 .. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/proj.4/gh-pages/proj.pdf diff --git a/docs/source/news.rst b/docs/source/news.rst index 4f95d954..8c7d4c43 100644 --- a/docs/source/news.rst +++ b/docs/source/news.rst @@ -3,6 +3,133 @@ News ############################################################################### +6.0.0 Release Notes +++++++++++++++++++++++++++++++++++++++++ +*Marhc 1st 2019* + + +PROJ 6 has undergone extensive changes to increase its functional scope from a +cartographic projection engine with so-called "early-binding" geodetic datum +transformation capabilities to a more complete library supporting coordinate +transformations and coordinate reference systems. + +As a foundation for other enhancements, PROJ now includes a C++ implementation +of the modelisation propopsed by the ISO-19111:2019 standard / OGC Abstract +Specification Topic 2: "Referencing By Coordinates", for geodetic reference +frames (datums), coordinate reference systems and coordinate operations. +Construction and query of those geodetic objects is available through a new C++ +API, and also accessible for the most part from bindings in the C API. + +Those geodetic objects can be imported and exported from and into the OGC +Well-Known Text format (WKT) in its different variants: ESRI WKT, GDAL WKT 1, +WKT2:2015 (ISO 19162:2015) and WKT2:2018 (ISO 19162:2018). Import and export of +CRS objects from and into PROJ strings is also supported. This functionality +was previously available in the GDAL software library (except WKT2 support +which is a new feature), and is now an integral part of PROJ. + +A unified database of geodetic objects, coordinate reference systems and their +metadata, and coordinate operations between those CRS is now available in a +SQLite3 database file, proj.db. This includes definitions imported from the +IOGP EPSG dataset (v9.6.0 release), the IGNF (French national mapping agency) +geodetic registry and the ESRI projection engine database. PROJ is now the +reference software in the "OSGeo C stack" for this CRS and coordinate operation +database, whereas previously this functionality was spread over PROJ, GDAL and +libgeotiff, and used CSV or other adhoc text-based formats. + +Late-binding coordinate operation capabilities, that takes metadata such as +area of use and accuracy into account, has been added. This can avoid in a +number of situations the past requirement of using WGS84 as a pivot system, +which could cause unneeded accuracy loss, or was not doable at all sometimes +when transformation to WGS84 was not available. Those late-binding capabilities +are now used by the proj_create_crs_to_crs() function and the cs2cs utility. + +A new command line utility, projinfo, has been added to query information about +a geodetic object of the database, import and export geodetic objects from/into +WKT and PROJ strings, and display coordinate operations available between two +CRSs. + + UPDATES + ------- + + o Removed projects.h as a public interface (`#835 <`_) + + o Deprecated the proj_api.h interface. The header file is still available + but will be removed with the next major version release of PROJ. It is + now required to define ACCEPT_USE_OF_DEPRECATED_PROJ_API_H before the + interface can be used (`#836 <`_) + + o Removed support for the nmake build system (`#838 `_) + + o Removed support for the proj_def.dat defaults file (`#201 `_) + + o C++11 required for building PROJ (`#1203 `_) + + o Added build dependency on SQLite 3.7 (`#1175 `_) + + o Added projinfo command line application (`#1189 `_) + + o Added many functions to proj.h for handling ISO19111 functionality (`#1175 `_) + + o Added C++ API exposing ISO19111 functionality (`#1175 `_) + + o Updated cs2cs to use late-binding features (`#1182 `_) + + o Removed the nad2bin application. Now available in the proj-datumgrid + git repository (`#1236 `_) + + o Removed support for Chebyshev polynomials in proj (`#1226 `_) + + o Removed proj_geocentric_latitude from proj.h API (`#1170 `_) + + o Changed behaviour of proj: Now only allow initialization of + projections (`#1162 `_) + + o Changed behaviour of tmerc: Now default to the Extended Transverse + Mercator algorithm (etmerc). Old implementation available by adding + +approx (`#404 `_) + + o Chaged behaviour: Default ellipsoid now set to GRS80 (was WGS84) (`#1210 `_) + + o Allow multiple directories in PROJ_LIB environment variable (`#1281 `_) + + o Added Lambert Conic Conformal (2SP Michigan) projection (`#1142 `_) + + o Added Bertin1953 projection (`#1133 `_) + + o Added Tobler-Mercator projection (`#1153 `_) + + o Added Molodensky-Badekas transform (`#1160 `_) + + o Added push and pop coordinate operations (`#1250 `_) + + o Removed +t_obs parameter from helmert and deformation (`#1264 `_) + + o Added +dt parameter to deformation as replacement for + removed +t_obs (`#1264 `_) + + BUG FIXES + --------- + + o Read +towgs84 values correctly on locales not using dot as comma separator (`#1136 `_) + + o Fixed file offset for reading of shift values in NTv1 files (`#1144 `_) + + o Avoid problems with PTHREAD_MUTEX_RECURSIVE when using CMake (`#1158 `_) + + o Avoid raising errors when setting ellipsoid flattening to zero (`#1191 `_) + + o Fixed lower square calculations in rHealpix projection (`#1206 `_) + + o Allow Molodensky transform parameters to be zero (`#1194 `_) + + o Fixed wrong parameter in ITRF2000 init file (`#1240 `_) + + o Fixed use of grid paths including spaces (`#1152 `_) + + o Robinson: fix wrong values for forward path for latitudes >= 87.5, + and fix inaccurate inverse method (`#1172 `_) + + PROJ 5.2.0 ++++++++++++++++++++++++++++++++++++++++ *September 15th 2018* -- cgit v1.2.3 From e03bfb35013fc0ab1843c906806f8e162db4a59d Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Fri, 1 Mar 2019 19:22:55 +0100 Subject: Fix typos in docs/source/news.rst --- docs/source/news.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/news.rst b/docs/source/news.rst index 8c7d4c43..312f6ecf 100644 --- a/docs/source/news.rst +++ b/docs/source/news.rst @@ -5,7 +5,7 @@ News 6.0.0 Release Notes ++++++++++++++++++++++++++++++++++++++++ -*Marhc 1st 2019* +*March 1st 2019* PROJ 6 has undergone extensive changes to increase its functional scope from a @@ -51,12 +51,12 @@ CRSs. UPDATES ------- - o Removed projects.h as a public interface (`#835 <`_) + o Removed projects.h as a public interface (`#835 `_) o Deprecated the proj_api.h interface. The header file is still available but will be removed with the next major version release of PROJ. It is now required to define ACCEPT_USE_OF_DEPRECATED_PROJ_API_H before the - interface can be used (`#836 <`_) + interface can be used (`#836 `_) o Removed support for the nmake build system (`#838 `_) -- cgit v1.2.3 From a6add0dc054a55334ee880d83aca8c19510ab858 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Fri, 1 Mar 2019 19:25:43 +0100 Subject: Bump version numbers in preparation for 6.1.0 --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 0fd8d540..0abc17ff 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -66,7 +66,7 @@ copyright = u'1983-{0}'.format(now.year) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -version = '6.0.0' +version = '6.1.0' # use same |release| as |version| release = version -- cgit v1.2.3 From 527d76a9badb8398d05b1c3bac7abfecc2f720c5 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Fri, 1 Mar 2019 19:29:38 +0100 Subject: Doc: fix various warnings/errors raised by Sphinx --- docs/source/download.rst | 2 +- docs/source/news.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/source') diff --git a/docs/source/download.rst b/docs/source/download.rst index da3f900e..f0939637 100644 --- a/docs/source/download.rst +++ b/docs/source/download.rst @@ -13,7 +13,7 @@ distribution of the source code and various resource file archives. See Current Release -------------------------------------------------------------------------------- -* **2019-03-01** `proj-6.6.0.tar.gz`_ (`md5`_) +* **2019-03-01** `proj-6.0.0.tar.gz`_ (`md5`_) * **2018-09-15** `proj-datumgrid-1.8.zip`_ * **2019-03-01** `proj-datumgrid-europe-1.2.zip`_ * **2019-03-01** `proj-datumgrid-north-america-1.2.zip`_ diff --git a/docs/source/news.rst b/docs/source/news.rst index 312f6ecf..cf9fdbb2 100644 --- a/docs/source/news.rst +++ b/docs/source/news.rst @@ -48,8 +48,8 @@ a geodetic object of the database, import and export geodetic objects from/into WKT and PROJ strings, and display coordinate operations available between two CRSs. - UPDATES - ------- +UPDATES +------- o Removed projects.h as a public interface (`#835 `_) @@ -107,8 +107,8 @@ CRSs. o Added +dt parameter to deformation as replacement for removed +t_obs (`#1264 `_) - BUG FIXES - --------- +BUG FIXES +--------- o Read +towgs84 values correctly on locales not using dot as comma separator (`#1136 `_) -- cgit v1.2.3 From 22382726ef34f8da797b69eb8f42cc5ce5f415c0 Mon Sep 17 00:00:00 2001 From: Mike Taves Date: Sun, 3 Mar 2019 22:57:09 +1300 Subject: Configure bibstyle to abbreviate names --- docs/source/bibstyle.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/bibstyle.py b/docs/source/bibstyle.py index 8e2cc02a..addfedbd 100644 --- a/docs/source/bibstyle.py +++ b/docs/source/bibstyle.py @@ -1,5 +1,6 @@ ############################################################################### # +# Project: PROJ # Purpose: Configure custom bibliography style for sphinxcontrib-bibtex # Author: Mike Toews # @@ -53,11 +54,15 @@ class LinkLabelStyle(LabelStyle): class CustomStyle(UnsrtStyle): """Citation style in the References section""" + # TODO: Make more Harvard-like, i.e. year after name(s) default_label_style = 'linklabel' default_name_style = 'lastfirst' default_sorting_style = 'author_year_title' - # TODO: Make more Harvard-like, i.e. year after name(s) + + def __init__(self, **kwargs): + kwargs['abbreviate_names'] = True + UnsrtStyle.__init__(self, **kwargs) register_plugin('pybtex.style.labels', 'linklabel', LinkLabelStyle) -- cgit v1.2.3 From c161062d308baf927500f2b02420de218d7fb9be Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Mar 2019 11:49:09 +0100 Subject: Sphinxify formatting of recent news entry --- docs/source/news.rst | 88 +++++++++++++++++++++++++++------------------------- 1 file changed, 46 insertions(+), 42 deletions(-) (limited to 'docs/source') diff --git a/docs/source/news.rst b/docs/source/news.rst index cf9fdbb2..8ec69dcf 100644 --- a/docs/source/news.rst +++ b/docs/source/news.rst @@ -51,83 +51,87 @@ CRSs. UPDATES ------- - o Removed projects.h as a public interface (`#835 `_) +* Removed projects.h as a public interface (`#835 `_) - o Deprecated the proj_api.h interface. The header file is still available - but will be removed with the next major version release of PROJ. It is - now required to define ACCEPT_USE_OF_DEPRECATED_PROJ_API_H before the - interface can be used (`#836 `_) +* Deprecated the proj_api.h interface. The header file is still available + but will be removed with the next major version release of PROJ. It is + now required to define :c:macro:`ACCEPT_USE_OF_DEPRECATED_PROJ_API_H` + before the interface can be used (`#836 `_) - o Removed support for the nmake build system (`#838 `_) +* Removed support for the nmake build system (`#838 `_) - o Removed support for the proj_def.dat defaults file (`#201 `_) +* Removed support for the ``proj_def.dat`` defaults file (`#201 `_) - o C++11 required for building PROJ (`#1203 `_) +* C++11 required for building PROJ (`#1203 `_) - o Added build dependency on SQLite 3.7 (`#1175 `_) +* Added build dependency on SQLite 3.7 (`#1175 `_) - o Added projinfo command line application (`#1189 `_) +* Added :program:`projinfo` command line application (`#1189 `_) - o Added many functions to proj.h for handling ISO19111 functionality (`#1175 `_) +* Added many functions to ``proj.h`` for handling ISO19111 functionality (`#1175 `_) - o Added C++ API exposing ISO19111 functionality (`#1175 `_) +* Added C++ API exposing ISO19111 functionality (`#1175 `_) - o Updated cs2cs to use late-binding features (`#1182 `_) +* Updated :program:`cs2cs` to use late-binding features (`#1182 `_) - o Removed the nad2bin application. Now available in the proj-datumgrid - git repository (`#1236 `_) +* Removed the ``nad2bin`` application. Now available in the + `proj-datumgrid `_ + git repository (`#1236 `_) - o Removed support for Chebyshev polynomials in proj (`#1226 `_) +* Removed support for Chebyshev polynomials in :program:`proj` + (`#1226 `_) - o Removed proj_geocentric_latitude from proj.h API (`#1170 `_) +* Removed :c:func:`proj_geocentric_latitude` from `proj.h` API + (`#1170 `_) - o Changed behaviour of proj: Now only allow initialization of - projections (`#1162 `_) +* Changed behaviour of :program:`proj`: Now only allow initialization of + projections (`#1162 `_) - o Changed behaviour of tmerc: Now default to the Extended Transverse - Mercator algorithm (etmerc). Old implementation available by adding - +approx (`#404 `_) +* Changed behaviour of :ref:`tmerc `: Now defaults to the Extended + Transverse Mercator algorithm (``etmerc``). Old implementation available + by adding ``+approx`` + (`#404 `_) - o Chaged behaviour: Default ellipsoid now set to GRS80 (was WGS84) (`#1210 `_) +* Chaged behaviour: Default ellipsoid now set to GRS80 (was WGS84) (`#1210 `_) - o Allow multiple directories in PROJ_LIB environment variable (`#1281 `_) +* Allow multiple directories in :envvar:`PROJ_LIB` environment variable (`#1281 `_) - o Added Lambert Conic Conformal (2SP Michigan) projection (`#1142 `_) +* Added :ref:`Lambert Conic Conformal (2SP Michigan) ` projection (`#1142 `_) - o Added Bertin1953 projection (`#1133 `_) +* Added :ref:`Bertin1953 ` projection (`#1133 `_) - o Added Tobler-Mercator projection (`#1153 `_) +* Added :ref:`Tobler-Mercator ` projection (`#1153 `_) - o Added Molodensky-Badekas transform (`#1160 `_) +* Added :ref:`Molodensky-Badekas ` transform (`#1160 `_) - o Added push and pop coordinate operations (`#1250 `_) +* Added :ref:`push ` and :ref:`pop ` coordinate operations (`#1250 `_) - o Removed +t_obs parameter from helmert and deformation (`#1264 `_) +* Removed ``+t_obs`` parameter from helmert and deformation (`#1264 `_) - o Added +dt parameter to deformation as replacement for - removed +t_obs (`#1264 `_) +* Added :option:`+dt` parameter to deformation as replacement for + removed ``+t_obs`` (`#1264 `_) BUG FIXES --------- - o Read +towgs84 values correctly on locales not using dot as comma separator (`#1136 `_) +* Read :option:`+towgs84` values correctly on locales not using dot as comma separator (`#1136 `_) - o Fixed file offset for reading of shift values in NTv1 files (`#1144 `_) +* Fixed file offset for reading of shift values in NTv1 files (`#1144 `_) - o Avoid problems with PTHREAD_MUTEX_RECURSIVE when using CMake (`#1158 `_) +* Avoid problems with :c:macro:`PTHREAD_MUTEX_RECURSIVE` when using CMake (`#1158 `_) - o Avoid raising errors when setting ellipsoid flattening to zero (`#1191 `_) +* Avoid raising errors when setting ellipsoid flattening to zero (`#1191 `_) - o Fixed lower square calculations in rHealpix projection (`#1206 `_) +* Fixed lower square calculations in :ref:`rHealpix ` projection (`#1206 `_) - o Allow Molodensky transform parameters to be zero (`#1194 `_) +* Allow :ref:`Molodensky ` transform parameters to be zero (`#1194 `_) - o Fixed wrong parameter in ITRF2000 init file (`#1240 `_) +* Fixed wrong parameter in ``ITRF2000`` init file (`#1240 `_) - o Fixed use of grid paths including spaces (`#1152 `_) +* Fixed use of grid paths including spaces (`#1152 `_) - o Robinson: fix wrong values for forward path for latitudes >= 87.5, - and fix inaccurate inverse method (`#1172 `_) +* :ref:`Robinson `: fix wrong values for forward path for latitudes >= 87.5, + and fix inaccurate inverse method (`#1172 `_) PROJ 5.2.0 -- cgit v1.2.3 From a33feebf7d97a9acf18ee0913dbfd536279d9c14 Mon Sep 17 00:00:00 2001 From: Mike Taves Date: Mon, 4 Mar 2019 00:07:48 +1300 Subject: Further corrections to BibTeX - Use names as published - Change Tobler2017 -> Tobler2018 - Change EPSGGuidanceNumber7Part2 -> IOGP2018 --- docs/source/operations/projections/tobmerc.rst | 2 +- .../operations/transformations/geogoffset.rst | 4 +- docs/source/operations/transformations/horner.rst | 2 +- docs/source/references.bib | 87 ++++++++++++---------- 4 files changed, 53 insertions(+), 42 deletions(-) (limited to 'docs/source') 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/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/references.bib b/docs/source/references.bib index 7c1be5c8..43b187b2 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -4,7 +4,7 @@ @Article{Altamimi2002, Title = {{ITRF2000}: A new release of the {International Terrestrial Reference Frame} for earth science applications}, - Author = {Z. Altamimi and P. Sillard and C. Boucher}, + Author = {Zuheir Altamimi and Patrick Sillard and Claude Boucher}, Journal = {Journal of Geophysical Research: Solid Earth}, Year = {2002}, Number = {B10}, @@ -22,12 +22,13 @@ Pages = {241--254}, Volume = {4}, - Url = {https://arxiv.org/abs/0908.1824} + Archiveprefix = {arXiv}, + Eprint = {0908.1824} } @Article{CalabrettaGreisen2002, Title = {Representations of celestial coordinates in {FITS}}, - Author = {Calabretta, M. R. and Greisen, E. W.}, + Author = {M. R. Calabretta and E. W. Greisen}, Journal = {Astronomy \& Astrophysics}, Year = {2002}, Number = {3}, @@ -39,7 +40,7 @@ @TechReport{ChanONeil1975, Title = {Feasibility Study of a Quadrilateralized Spherical Cube Earth Data Base}, - Author = {Chan, F. K. and O'Neill, E. M.}, + Author = {F. K. Chan and E. M. O'Neill}, Institution = {Computer Sciences Corporation, System Sciences Division}, Year = {1975}, @@ -68,12 +69,14 @@ Institution = {Department of Mathematical and Geospatial Sciences, RMIT University}, Year = {2004}, + Address = {Melborne, Australia}, + Url = {http://www.mygeodesy.id.au/documents/Molodensky%20V2.pdf} } @Article{EberHewitt1979, Title = {Conversion algorithms for the {CalCOFI} station grid}, - Author = {L. E. Eber and R. P. Hewitt}, + Author = {L. E. Eber and Roger P. Hewitt}, Journal = {California Cooperative Oceanic Fisheries Investigations Reports}, Year = {1979}, Pages = {135--137}, @@ -84,7 +87,7 @@ @Manual{Evenden2005, Title = {libproj4: A Comprehensive Library of Cartographic Projection Functions (Preliminary Draft)}, - Author = {G. I. Evenden}, + Author = {Gerald I. Evenden}, Year = {2005}, Url = {https://github.com/OSGeo/proj.4/blob/master/docs/old/libproj.pdf} @@ -92,7 +95,7 @@ @Manual{Evenden1995, Title = {Cartographic Projection Procedures for the {UNIX} Environment --- {A} User's Manual}, - Author = {G. I. Evenden}, + Author = {Gerald I. Evenden}, Year = {1995}, Url = {https://pubs.usgs.gov/of/1990/of90-284/ofr90-284.pdf} @@ -100,10 +103,12 @@ @InProceedings{EversKnudsen2017, Title = {Transformation pipelines for {PROJ.4}}, - Author = {K. Evers and T. Knudsen}, + Author = {Kristian Evers and Thomas Knudsen}, Booktitle = {FIG Working Week 2017 Proceedings}, Year = {2017}, + Address = {Helsinki, Finland}, + Url = {http://www.fig.net/resources/proceedings/fig_proceedings/fig2017/papers/iss6b/ISS6B_evers_knudsen_9156.pdf} } @@ -134,17 +139,30 @@ @InProceedings{Hensley2002, Title = {Improved Processing of {AIRSAR} Data Based on the {GeoSAR} Processor}, - Author = {S. Hensley and E. Chapin and A. Freedman and T. Michel}, + Author = {Scott Hensley and Elaine Chapin and Adam Freedman and Thierry Michel}, Booktitle = {AIRSAR Earth Science and Application Workshop}, Year = {2002}, + + Address = {Pasadena, California}, Organization = {Jet Propulsion Laboratory}, Url = {https://airsar.jpl.nasa.gov/documents/workshop2002/papers/T3.pdf} } +@TechReport{IOGP2018, + Title = {Geomatics Guidance Note 7, part 2: Coordinate Conversions \& Transformations including Formulas}, + Author = {IOGP}, + Institution = {International Association For Oil And Gas Producers}, + Year = {2018}, + Number = {373-7-2}, + Type = {IOGP Publication}, + + Url = {https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/} +} + @Article{Jenny2015, Title = {A compromise aspect-adaptive cylindrical projection for world maps}, - Author = {B. Jenny and B. Šavrič and T. Patterson}, + Author = {Bernhard Jenny and Bojan Šavrič and Tom Patterson}, Journal = {International Journal of Geographical Information Science}, Year = {2015}, Number = {6}, @@ -157,7 +175,7 @@ @Article{Karney2013, Title = {Algorithms for geodesics}, - Author = {C. F. F. Karney}, + Author = {Charles F. F. Karney}, Journal = {Journal of Geodesy}, Year = {2013}, Number = {1}, @@ -169,7 +187,7 @@ @Article{Karney2011, Title = {Geodesics on an ellipsoid of revolution}, - Author = {C. F. F. Karney}, + Author = {Charles F. F. Karney}, Journal = {ArXiv e-prints}, Year = {2011}, @@ -180,7 +198,7 @@ @Article{Komsta2016, Title = {{ATPOL} geobotanical grid revisited -- a proposal of coordinate conversion algorithms}, - Author = {Ł. Komsta}, + Author = {Łukasz Komsta}, Journal = {Annales UMCS Sectio E Agricultura}, Year = {2016}, Number = {1}, @@ -190,10 +208,10 @@ @InProceedings{LambersKolb2012, Title = {Ellipsoidal Cube Maps for Accurate Rendering of Planetary-Scale Terrain Data}, - Author = {M. Lambers and A. Kolb}, + Author = {Lambers, Martin and Kolb, Andreas}, Booktitle = {Pacific Graphics Short Papers}, Year = {2012}, - Editor = {C. Bregler and P. Sander and M. Wimmer}, + Editor = {Chris Bregler and Pedro Sander and Michael Wimmer}, Publisher = {The Eurographics Association}, Doi = {10.2312/PE/PG/PG2012short/005-010} @@ -214,7 +232,7 @@ @Article{Patterson2014, Title = {Introducing the {Patterson} Cylindrical Projection}, - Author = {T. Patterson and B. Šavrič and B. Jenny}, + Author = {Tom Patterson and Bojan Šavrič and Bernhard Jenny}, Journal = {Cartographic Perspectives}, Year = {2014}, Volume = {78}, @@ -224,7 +242,7 @@ @TechReport{Poder1998, Title = {Some Conformal Mappings and Transformations for Geodesy and Topographic Cartography}, - Author = {K. Poder and K. Engsager}, + Author = {Knud Poder and Karsten Engsager}, Institution = {National Survey and Cadastre}, Year = {1998}, @@ -240,7 +258,7 @@ @Misc{Rittri2012, Title = {New omerc approximations of {Denmark System 34}}, - Author = {M. Rittri}, + Author = {Mikael Rittri}, HowPublished = {e-mail}, Year = {2012}, @@ -253,7 +271,7 @@ Journal = {Survey Review}, Year = {2016}, Number = {358}, - Pages = {82-90}, + Pages = {82--90}, Volume = {50}, Doi = {10.1080/00396265.2016.1244143}, @@ -262,10 +280,11 @@ @Article{Savric2018, Title = {The {Equal Earth} map projection}, - Author = {B. Šavrič and T. Patterson and B. Jenny}, + Author = {Bojan Šavrič and Tom Patterson and Bernhard Jenny}, Journal = {International Journal of Geographical Information Science}, Year = {2018}, Number = {3}, + Pages = {454--465}, Volume = {33}, Doi = {10.1080/13658816.2018.1504949}, @@ -274,8 +293,8 @@ @Article{Savric2015, Title = {The {Natural Earth II} world map projection}, - Author = {B. Šavrič and T. Patterson and B. Jenny}, - Journal = {International Journal of Geographical Information Science}, + Author = {Bojan Šavrič and Tom Patterson and Bernhard Jenny}, + Journal = {International Journal of Cartography}, Year = {2015}, Number = {2}, Pages = {123--133}, @@ -287,14 +306,14 @@ @Book{Snyder1993, Title = {Flattening the Earth}, - Author = {J. P. Snyder}, + Author = {John P. Snyder}, Publisher = {University of Chicago Press}, Year = {1993} } @Article{Snyder1988, Title = {New Equal-Area Map Projections For Noncircular Regions}, - Author = {J. P. Snyder}, + Author = {John P. Snyder}, Journal = {The American Cartographer}, Year = {1988}, Number = {4}, @@ -307,7 +326,7 @@ @TechReport{Snyder1987, Title = {Map Projections --- {A} Working Manual}, - Author = {J. P. Snyder}, + Author = {John P. Snyder}, Institution = {U.S. Geological Survey}, Year = {1987}, Number = {1395}, @@ -324,11 +343,11 @@ Edition = {15th} } -@Article{Tobler2017, +@Article{Tobler2018, Title = {A new companion for {Mercator}}, - Author = {W. Tobler}, + Author = {Waldo Tobler}, Journal = {Cartography and Geographic Information Science}, - Year = {2017}, + Year = {2018}, Number = {3}, Pages = {284--285}, Volume = {45}, @@ -363,7 +382,7 @@ @Article{WeberMoore2013, Title = {Corrected Conversion Algorithms For The {CalCOFI} Station Grid And Their Implementation In Several Computer Languages}, - Author = {E. D. Weber and T. J. Moore}, + Author = {Edward D. Weber and Thomas J. Moore}, Journal = {California Cooperative Oceanic Fisheries Investigations Reports}, Year = {2013}, Pages = {1--10}, @@ -374,7 +393,7 @@ @Article{Zajac1978, Title = {Atlas of Distribution of Vascular Plants in {Poland} ({ATPOL})}, - Author = {A. Zajaç}, + Author = {Adam Zajaç}, Journal = {Taxon}, Year = {1978}, Number = {5/6}, @@ -384,11 +403,3 @@ Doi = {10.2307/1219899} } -@Manual{EPSGGuidanceNumber7Part2, - Title = {Geomatics Guidance Note 7, part 2 - Coordinate Conversions \& Transformations including Formulas}, - Year = {2018}, - - Institution = {International Association For Oil And Gas Producers}, - Url = {https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/} -} - -- cgit v1.2.3 From 76033f2d8b91518301a8421feb0be74fe374b53d Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 4 Mar 2019 22:40:44 +0100 Subject: Improve formatting of program references on apps index --- docs/source/apps/index.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs/source') diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst index 8c2c8222..381b8933 100644 --- a/docs/source/apps/index.rst +++ b/docs/source/apps/index.rst @@ -4,15 +4,16 @@ Applications ================================================================================ -Bundled with PROJ comes a set of small command line utilities. The ``proj`` +Bundled with PROJ comes a set of small command line utilities. The :program:`proj` program is limited to converting between geographic and projection coordinates -within one datum. The ``cs2cs`` program operates similarly, but allows +within one datum. The :program:`cs2cs` program operates similarly, but allows translation between any pair of definable coordinate systems, including support -for datum transformation. The ``geod`` program provides the ability to do -geodesic (great circle) computations. ``gie`` is the program used for -regression tests in PROJ. ``cct`` a 4D equivalent to the ``proj`` program, -performs transformation coordinate systems on a set of input points. -``projinfo`` performs queries for geodetic objects and coordinate operations. +for datum transformation. The :program:`geod` program provides the ability to do +geodesic (great circle) computations. :program:`gie` is the program used for +regression tests in PROJ. :program:`cct`, a 4D equivalent to the :program:`proj` +program, performs transformation coordinate systems on a set of input points. +:program:`projinfo` performs queries for geodetic objects and coordinate +operations. .. toctree:: :maxdepth: 1 -- cgit v1.2.3 From 2ff2cdea0a40857e9e65bee47b6f2c9076ef5a79 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Mar 2019 11:12:29 +0100 Subject: Fix bad rst formatting --- docs/source/usage/differences.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/differences.rst b/docs/source/usage/differences.rst index d5eebe8e..4d05543a 100644 --- a/docs/source/usage/differences.rst +++ b/docs/source/usage/differences.rst @@ -97,8 +97,8 @@ Effectively this means that the direction of the operation has been reversed, so that what in PROJ 5 was a forward operation is now an inverse operation and vice versa. -Pipelines written for PROJ 5 can be migrated to PROJ 6 by adding :option:` -+inv` to forward steps involving the deformation operation. Similarly +Pipelines written for PROJ 5 can be migrated to PROJ 6 by adding :option:`+inv` +to forward steps involving the deformation operation. Similarly :option:`+inv` should be removed from inverse steps to be compatible with PROJ 6. @@ -113,4 +113,4 @@ the time span for which they wish to apply a given deformation. The parameter exclusive with :option:`+t_epoch`. :option:`+dt` is used when deformation for a set amount of time is needed and :option:`+t_epoch` is used (in conjunction with the observation time of the input coordinate) when -deformation from a specific epoch to the observation time is needed. \ No newline at end of file +deformation from a specific epoch to the observation time is needed. -- cgit v1.2.3 From a30685b6e76092c89c6a9ec03c0d29e3dcad2850 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Mar 2019 15:02:10 +0100 Subject: Make proper reference to 'gie --list' --- docs/source/apps/gie.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/apps/gie.rst b/docs/source/apps/gie.rst index 8cbd2336..bab0ec69 100644 --- a/docs/source/apps/gie.rst +++ b/docs/source/apps/gie.rst @@ -172,7 +172,7 @@ gie command language proj=urm5 n=0.5 inv expect failure pjd_err_malformed_pipeline - See ``gie -l`` for a list of error codes that can be expected. + See :option:`gie --list<--list>` for a list of error codes that can be expected. .. option:: tolerance @@ -273,7 +273,7 @@ gie command language expect 173 -45 - See ``gie -l`` for a list of error codes that can be ignored. + See :option:`gie --list<--list>` for a list of error codes that can be ignored. .. option:: require_grid -- cgit v1.2.3 From ab49a9308b604a5c94507e02100af1aa8d16642a Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Mon, 11 Mar 2019 17:02:22 +0100 Subject: Doc: fix typo in ob_tran --- docs/source/operations/projections/ob_tran.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') 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 -- cgit v1.2.3 From c288debe029667515656213b0ba81956c3ede26d Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 14 Mar 2019 23:05:25 +0100 Subject: Doc: State that +n is a required for param for urm5 --- docs/source/operations/projections/urm5.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/source') 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= Set the :math:`n` constant. Value between 0 and 1. +Optional parameters +-------------------------------------------------------------------------------- .. option:: +q= Set the :math:`q` constant. -- cgit v1.2.3 From de5181ffaf298cbee11e0164a2fbf1ead220d9a1 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Mar 2019 13:06:48 +0100 Subject: Remove outdated questions from FAQ More or less all old questions from the FAQ has been removed and replaced by new questions that align better with the current state of the project. --- docs/source/community/contributing.rst | 2 + docs/source/faq.rst | 260 +++++++-------------------------- 2 files changed, 56 insertions(+), 206 deletions(-) (limited to 'docs/source') diff --git a/docs/source/community/contributing.rst b/docs/source/community/contributing.rst index 867f7e1a..8ead82bd 100644 --- a/docs/source/community/contributing.rst +++ b/docs/source/community/contributing.rst @@ -36,6 +36,8 @@ the place to go. Please *do not* use the GitHub issue tracker as a support forum. Your question is much more likely to be answered on the mailing list, as many more people follow that than the issue tracker. +.. _add_bug_report: + Adding bug reports ------------------ diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 21fe158b..d6f118ce 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -10,208 +10,73 @@ FAQ :depth: 3 :backlinks: none - - -Where can I find the list of projections and their arguments? +Which file formats does PROJ support? -------------------------------------------------------------------------------- -:doc:`Here<../operations/projections/index>`. +The :ref:`command line applications ` that come with PROJ only support text +input and output (apart from :program:`proj` which accepts a simple binary data +stream as well). :program:`proj`, :program:`cs2cs` and :program:`cct` expects +text files with one coordinate per line with each coordinate dimension in a +separate column. + +.. note:: -Additionally, the :program:`proj` command itself can report the list of projections -using the ``-lp`` option, the list of ellipsoids with the ``-le`` option, -the list of units with the ``-lu`` option, and the list of built-in datums with -the ``-ld`` option. + If your data is stored in a common geodata file format chances are that + you can use `GDAL `_ as a frontend to PROJ and transform your data with the + :program:`ogr2ogr` application. -How do I do datum shifts between NAD27 and NAD83? +Can I transform from *abc* to *xyz*? -------------------------------------------------------------------------------- -Using the :program:`cs2cs` application. The following example demonstrates using the -default shift parameters for NAD27 to NAD83: - -:: +Probably. PROJ supports transformations between most coordinate reference systems +registered in the EPSG registry, as well as a number of other coordinate reference +systems. The best way to find out is to test it with the :program:`projinfo` +application. Here's an example checking if there's a transformation between +ETRS89/UTM32N (EPSG:25832) and ETRS89/DKTM1 (EPSG:4093): - % cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 -117 30 +.. code-block:: console -producing: + $ ./projinfo -s EPSG:25832 -t EPSG:4093 -o PROJ + Candidate operations found: 1 + ------------------------------------- + Operation n°1: -:: + unknown id, Inverse of UTM zone 32N + DKTM1, 0 m, World - 117d0'2.901"W 30d0'0.407"N 0.000 + PROJ string: + +proj=pipeline +step +inv +proj=utm +zone=32 +ellps=GRS80 + +step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.99998 +x_0=200000 +y_0=-5000000 +ellps=GRS80 -In order for datum shifting to work properly the various grid shift files must -be available. See below. More details are available in the -section on :doc:`resource files`. +See the :program:`projinfo` :ref:`documentation ` for more info on +how to use it. -How do I build/configure PROJ to support datum shifting? +Coordinate reference system *xyz* is not in the EPSG registry, what do I do? -------------------------------------------------------------------------------- -After downloading and unpacking the PROJ source, also download and unpack the -set of datum shift files. See :ref:`download` for instructions how to fetch -and install these files. +Generally PROJ will accept coordinate reference system descriptions in the form +of WKT, WKT2 and PROJ strings. If you are able to describe your desired CRS +in either of those formats there's a good chance that PROJ will be able to make +sense of it. -A default build and install on Unix will normally build knowledge of the -directory where the grid shift files are installed into the PROJ library -(usually ``/usr/local/share/proj``). On Windows the library is normally built -thinking that C:\PROJ\NAD is the installed directory for the grid shift files. -If the built-in concept of the PROJ data directory is incorrect, the :envvar:`PROJ_LIB` -environment variable can be defined with the correct directory. +If it is important to you that a given CRS is added to the EPSG registry, you +should contact your local geodetic authority and ask them to submit the CRS for +inclusion in the registry. -How do I debug problems with NAD27/NAD83 datum shifting? +I found a bug in PROJ, how do I get it fixed? -------------------------------------------------------------------------------- -1. Verify that you have the binary files (e.g. ``/usr/local/share/proj/conus``) - installed on your system. If not, see the previous question. -2. Try a datum shifting operation in relative isolation, such as with the :program:`cs2cs` - command listed above. Do you get reasonable results? If not, it is likely that - the grid shift files aren't being found. Perhaps you need to define - :envvar:`PROJ_LIB`? -3. The :program:`cs2cs` command and the underlying :c:func:`pj_transform()` API know how to do a - grid shift as part of a more complex coordinate transformation; however, it - is imperative that both the source and destination coordinate system be - defined with appropriate datum information. That means that implicitly or - explicitly there must be a ``+datum=`` clause, a ``+nadgrids=`` clause or a - ``+towgs84=`` clause. For instance - ``cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +ellps=WGS84`` won't work because defining the output - coordinate system as using the ellipse WGS84 isn't the same as defining it - to use the datum WGS84 (use ``+datum=WGS84``). If either the input or output - are not identified as having a datum, the datum shifting (and ellipsoid - change) step is just quietly skipped! -4. The :envvar:`PROJ_DEBUG` environment can be defined (any value) to force extra output - from the PROJ library to stderr (the text console normally) with - information on what data files are being opened and in some cases why a - transformation fails. - - :: - - export PROJ_DEBUG=ON - cs2cs ... - - - .. note:: - ``PROJ_DEBUG`` support is not yet very mature in the PROJ library. - -5. The :option:`-v` flag to :program:`cs2cs` can be useful in establishing more detail on what - parameters are used internally for a coordinate system. This will include - expanding the definition of ``+datum`` clause. - -How do I use EPSG coordinate system codes with PROJ? --------------------------------------------------------------------------------- +Please report bugs that you find to the issue tracker on GitHub. :ref:`Here's how +`. -There is somewhat imperfect translation between 2D geographic and projected -coordinate system codes and PROJ descriptions of the coordinate systems -available in the ``epsg`` definition file that normally lives in the ``proj/data`` -directory. If installed (as is the default on Unix), it is possible -to use EPSG numbers like this: - -:: - - - % cs2cs -v +init=epsg:26711 - # ---- From Coordinate System ---- - #Universal Transverse Mercator (UTM) - # Cyl, Sph - # zone= south - # +init=epsg:26711 +proj=utm +zone=11 +ellps=clrk66 +datum=NAD27 +units=m - # +no_defs +nadgrids=conus,ntv1_can.dat - #--- following specified but NOT used - # +ellps=clrk66 - # ---- To Coordinate System ---- - #Lat/long (Geodetic) - # - # +proj=latlong +datum=NAD27 +ellps=clrk66 +nadgrids=conus,ntv1_can.dat - -The ``proj/data/epsg`` file can be browsed and searched for coordinate systems -using a text editor. There are known to be problems with some coordinate -systems. In particular, any coordinate system with odd axes, a non-greenwich prime -meridian, or other quirky characteristics is unlikely to work properly. Caveat Emptor! - -How do I use 3 parameter and 7 parameter datum shifting --------------------------------------------------------------------------------- - -Datum shifts can be approximated with 3 and 7 parameter transformations. Their -use with :program:`cs2cs` is more fully described in the -:ref:`geodetic transformation` section. - -More generically, the :ref:`helmert` can be used with :program:`cct`. +If you know how to program you can also try to fix it yourself. You are welcome +to ask for guidance on one of the :ref:`communication channels ` used +by the project. - -Does PROJ work in different international numeric locales? +How do I contribute to PROJ? -------------------------------------------------------------------------------- -No. PROJ makes extensive use of the :c:func:`sprintf()` and :c:func:`atof()` C functions -internally to translate numeric values. If a locale is in effect that modifies -formatting of numbers, altering the role of commas and periods in numbers, then -PROJ will not work. This problem is common in some European locales. - -On UNIX-like platforms, this problem can be avoided by forcing the use of the -default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable to ``C``. - -:: - - $ export LC_NUMERIC=C - $ proj ... - -.. note:: - - NOTE: Per ticket #49, in PROJ 4.7.0 and later pj_init() operates with locale - overridden to "C" to avoid most locale specific processing for applications - using the API. Command line tools may still have issues. - -Changing Ellipsoid / Why can't I convert from WGS84 to Google Earth / Virtual Globe Mercator? ----------------------------------------------------------------------------------------------- - -The coordinate system definition for Google Earth and Virtual Globe Mercator -is as follows, which uses a sphere as the earth model for the Mercator -projection. - -:: - - +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 - +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs - -But, if you do something like: - -:: - - cs2cs +proj=latlong +datum=WGS84 - +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 - +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs - -to convert between WGS84 and Mercator on the sphere there will be substantial -shifts in the Y Mercator coordinates. This is because internally :program:`cs2cs` is -having to adjust the lat/long coordinates from being on the sphere to being on -the WGS84 datum which has a quite differently shaped ellipsoid. - -In this case, and many other cases using spherical projections, the desired -approach is to actually treat the lat/long locations on the sphere as if they -were on WGS84 without any adjustments when using them for converting to other -coordinate systems. The solution is to "trick" PROJ into applying no change -to the lat/long values when going to (and through) WGS84. This can be -accomplished by asking PROJ to use a null grid shift file for switching from -your spherical lat/long coordinates to WGS84. - -:: - - cs2cs +proj=latlong +datum=WGS84 \ - +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 \ - +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs - -Note the strategic addition of ``+nadgrids=@null`` to the spherical projection -definition. - -Similar issues apply with many other datasets distributed with projections -based on a spherical earth model, such as many NASA datasets. This coordinate -system is now known by the EPSG code 3857 and has in the past been known as -EPSG:3785 and EPSG:900913. When using this coordinate system with GDAL/OGR it -is helpful to include the +wktext so the exact PROJ string will be preserved -in the WKT representation (otherwise key parameters like ``+nadgrids=@null`` will -be dropped): - -:: - - +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 - +units=m +nadgrids=@null +wktext +no_defs - +Any contributions from the PROJ community is welcome. See :ref:`contributing` for +more details. How do I calculate distances/directions on the surface of the earth? -------------------------------------------------------------------------------- @@ -219,32 +84,15 @@ How do I calculate distances/directions on the surface of the earth? These are called geodesic calculations. There is a page about it here: :ref:`geodesic`. - -What options does PROJ allow for the shape of the Earth (geodesy)? --------------------------------------------------------------------------------- - -See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c -for possible ellipse options. For example, putting ``+ellps=WGS84`` uses -the ``WGS84`` Earth shape. - -What if I want a spherical Earth? --------------------------------------------------------------------------------- - -Use ``+ellps=sphere``. See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c -for the radius used in this case. - -How do I change the radius of the Earth? How do I use PROJ for work on Mars? --------------------------------------------------------------------------------- - -You can supply explicit values for the semi minor and semi major axes instead -of using the symbolic "sphere" value. Eg, if the radius were 2000000m: - -:: - - +proj=laea +lon_0=-40.000000 +lat_0=74.000000 +x_0=1000000 +y_0=1700000 +a=2000000 +b=2000000" - -How do I do False Eastings and False Northings? +What is the best format for describing coordinate reference systems? -------------------------------------------------------------------------------- -Use ``+x_0`` and ``+y_0`` in the projection string. +A coordinate reference system (CRS) can in PROJ be described in several ways: +As PROJ strings, Well-Known Text (WKT) and as spatial reference ID's (such as EPSG +codes). Generally, WKT or SRID's are preferred over PROJ strings as they can +contain more information about a given CRS. Conversions between WKT and PROJ +strings will in most cases cause a loss of information, potentially leading to +erroneous transformations. +For compatibility reasons PROJ supports several WKT dialects +(see :option:`projinfo -o`). If possible WKT2 should be used. -- cgit v1.2.3 From c5cc0f74fd912cef2872da227fa2bb2b47f116c6 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Tue, 19 Mar 2019 11:11:42 +0100 Subject: Doc: impove doc about OGC URN --- docs/source/apps/projinfo.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index 151b3079..d4c0a6ba 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -30,9 +30,11 @@ Synopsis | where {object_definition} or {object_definition} is a PROJ string, a - WKT string, an object name or a AUTHORITY:CODE + WKT string, an object name, AUTHORITY:CODE (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS - found in the proj.db database). + found in the proj.db database) or a OGC URN (such as "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671", "urn:ogc:def:ellipsoid:EPSG::7001" + or "urn:ogc:def:datum:EPSG::6326") Description *********** -- cgit v1.2.3 From 5d74522573291a8af698acf3102a662eb3a675eb Mon Sep 17 00:00:00 2001 From: Nyall Dawson Date: Thu, 21 Mar 2019 17:30:06 +1000 Subject: Add -k ellipsoid option to projinfo (#1338) Allows querying of ellipsoid definitions by auth:code lookup --- docs/source/apps/projinfo.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index d4c0a6ba..7e84823b 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -16,7 +16,7 @@ Synopsis ******** | **projinfo** - | [-o formats] [-k crs|operation] [--summary] [-q] + | [-o formats] [-k crs|operation|ellipsoid] [--summary] [-q] | [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] | [--spatial-test contains|intersects] | [--crs-extent-use none|both|intersection|smallest] @@ -60,10 +60,10 @@ The following control parameters can appear in any order: Except ``all`` and ``default``, other formats can be preceded by ``-`` to disable them. -.. option:: -k crs|operation +.. option:: -k crs|operation|ellipsoid When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object - in case there are CRS or coordinate operations with the same CODE. + in case there are CRS, coordinate operations or ellipsoids with the same CODE. The default is crs. .. option:: --summary -- cgit v1.2.3 From 1eadd02ac0b28486e98aed9407f27c4956619bae Mon Sep 17 00:00:00 2001 From: Chris Mayo Date: Sun, 24 Mar 2019 11:56:35 +0000 Subject: Doc: consistently use +opt and brackets +opt represents one parameter. An ellipsis indicates additional instances of the previous parameter may be given. Spaces are used between parameters and before an ellipsis, not purely to format brackets. See man(1) SYNOPSIS conventions. --- docs/source/apps/cct.rst | 4 ++-- docs/source/apps/cs2cs.rst | 10 +++++----- docs/source/apps/geod.rst | 6 +++--- docs/source/apps/proj.rst | 8 ++++---- 4 files changed, 14 insertions(+), 14 deletions(-) (limited to 'docs/source') diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst index 249d523a..629e181c 100644 --- a/docs/source/apps/cct.rst +++ b/docs/source/apps/cct.rst @@ -13,7 +13,7 @@ cct Synopsis ******** - **cct** [ **-cIostvz** [ args ] ] *+opts[=arg]* file[s] + **cct** [**-cIostvz** [args]] *+opt[=arg]* ... file ... Description *********** @@ -70,7 +70,7 @@ The following control parameters can appear in any order: Print version number. -The *+args* arguments are associated with coordinate operation parameters. +The *+opt* arguments are associated with coordinate operation parameters. Usage varies with operation. .. only:: html diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index 579dc65e..afe5a610 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -11,11 +11,11 @@ cs2cs Synopsis ******** - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s] + **cs2cs** [**-eEfIlrstvwW** [args]] [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ... or - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} +to {target_crs} file[s] + **cs2cs** [**-eEfIlrstvwW** [args]] {source_crs} +to {target_crs} file ... where {source_crs} or {target_crs} is a PROJ string, a WKT string or a AUTHORITY:CODE (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS @@ -25,7 +25,7 @@ or or - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} {target_crs} + **cs2cs** [**-eEfIlrstvwW** [args]] {source_crs} {target_crs} .. versionadded:: 6.0.0 @@ -132,12 +132,12 @@ The following control parameters can appear in any order: .. only:: man - The *+args* run-line arguments are associated with cartographic + The *+opt* run-line arguments are associated with cartographic parameters. .. only:: html - The *+args* run-line arguments are associated with cartographic + The *+opt* run-line arguments are associated with cartographic parameters. Usage varies with projection and for a complete description consult the :ref:`projection pages `. diff --git a/docs/source/apps/geod.rst b/docs/source/apps/geod.rst index e890aede..2897445d 100644 --- a/docs/source/apps/geod.rst +++ b/docs/source/apps/geod.rst @@ -7,9 +7,9 @@ geod Synopsis ******** - **geod** *+ellps=* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] + **geod** *+ellps=* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... - **invgeod** *+ellps=* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] + **invgeod** *+ellps=* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... Description *********** @@ -85,7 +85,7 @@ The following command-line options can appear in any order: This option causes the azimuthal values to be output as unsigned DMS numbers between 0 and 360 degrees. Also note :option:`-f`. -The *+args* command-line options are associated with geodetic +The *+opt* command-line options are associated with geodetic parameters for specifying the ellipsoidal or sphere to use. controls. The options are processed in left to right order from the command line. Reentry of an option is ignored with diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst index 7585411f..2dbd104a 100644 --- a/docs/source/apps/proj.rst +++ b/docs/source/apps/proj.rst @@ -12,9 +12,9 @@ proj Synopsis ******** - **proj** [ **-beEfiIlmorsStTvVwW** ] [ args ] ] [ *+args* ] file[s] + **proj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... - **invproj** [ **-beEfiIlmorsStTvVwW** ] [ args ] ] [ *+args* ] file[s] + **invproj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... Description @@ -156,7 +156,7 @@ The following control parameters can appear in any order the projected point. :option:`-v` is implied with this option. -The *+args* run-line arguments are associated with cartographic parameters. +The *+opt* run-line arguments are associated with cartographic parameters. Additional projection control parameters may be contained in two auxiliary control files: the first is optionally referenced with the *+init=file:id* and the second is always processed after the name of the @@ -167,7 +167,7 @@ also used for supporting files like datum shift files. .. only:: html - Usage of *+args* varies with projection and for a complete description + Usage of *+opt* varies with projection and for a complete description consult the :ref:`projection pages `. -- cgit v1.2.3 From 999439858dd9cc98d0deb47169318f0124164bbb Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Thu, 28 Mar 2019 13:45:17 +0100 Subject: Doc: document --identify switch of projinfo (fixes #1332) --- docs/source/apps/projinfo.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/source') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index 7e84823b..c8219838 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -193,6 +193,16 @@ The following control parameters can appear in any order: and their entries can refer to entries of the main database. The option may be repeated to specify several auxiliary databases. +.. option:: --identify + + When used with an object definition, this queries the PROJ database to find + known objects, typically CRS, that are close or identical to the object. + Each candidate object is associated with an approximate likelihood percentage. + This is useful when used with a WKT string that lacks a EPSG identifier, + such as ESRI WKT1. This might also be used with PROJ strings. + For example, `+proj=utm +zone=31 +datum=WGS84 +type=crs` will be identified + with a likelihood of 70% to EPSG:32631 + .. option:: --c-ify For developers only. Modify the string output of the utility so that it -- cgit v1.2.3 From fec376c3eb0e17443c4338f217b70278247973df Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 28 Mar 2019 11:24:43 +0100 Subject: Docs: Clarify axis ordering used in proj_trans_generic() --- docs/source/development/reference/functions.rst | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 4052ff82..0066c3a2 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -221,10 +221,16 @@ Coordinate transformation 3. of length one, i.e. a constant, which will be treated as a fully populated array of that constant value + .. note:: Even though he coordinate components are named :c:data:`x`, :c:data:`y`, + :c:data:`z` and :c:data:`t`, axis ordering of the to and from CRS + is respected. Transformations exhibit the same behaviour + as if they were gathered in a :c:type:`PJ_COORD` struct. + + The strides, :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, represent the step length, in bytes, between consecutive elements of the corresponding array. This makes it possible for - :c:func:`proj_transform` to handle transformation of a large class of application + :c:func:`proj_trans_generic` to handle transformation of a large class of application specific data structures, without necessarily understanding the data structure format, as in: @@ -250,21 +256,22 @@ Coordinate transformation 0, 0 /* and the time is the constant 0.00 s */ ); - This is similar to the inner workings of the deprecated pj_transform function, but the - stride functionality has been generalized to work for any size of basic unit, - not just a fixed number of doubles. + This is similar to the inner workings of the deprecated :c:func:`pj_transform` + function, but the stride functionality has been generalized to work for any + size of basic unit, not just a fixed number of doubles. In most cases, the stride will be identical for x, y, z, and t, since they will - typically be either individual arrays (stride = sizeof(double)), or strided - views into an array of application specific data structures (stride = sizeof (...)). + typically be either individual arrays (``stride = sizeof(double)``), or strided + views into an array of application specific data structures (``stride = sizeof (...)``). But in order to support cases where :c:data:`x`, :c:data:`y`, :c:data:`z`, and :c:data:`t` come from heterogeneous sources, individual strides, :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, are used. - .. note:: Since :c:func:`proj_transform` does its work *in place*, this means that even the - supposedly constants (i.e. length 1 arrays) will return from the call in altered - state. Hence, remember to reinitialize between repeated calls. + .. note:: Since :c:func:`proj_trans_generic` does its work *in place*, + this means that even the supposedly constants (i.e. length 1 arrays) + will return from the call in altered state. Hence, remember to + reinitialize between repeated calls. :param PJ* P: Transformation object :param `direction`: Transformation direction -- cgit v1.2.3 From 27bae3c269fb266daed557abaf86abc1a950ede5 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 28 Mar 2019 13:29:29 +0100 Subject: Doc: Add FAQ question about inconsistent axis ordering --- docs/source/faq.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++ docs/source/references.bib | 13 ++++++++++ 2 files changed, 73 insertions(+) (limited to 'docs/source') diff --git a/docs/source/faq.rst b/docs/source/faq.rst index d6f118ce..e6a2e54a 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -96,3 +96,63 @@ erroneous transformations. For compatibility reasons PROJ supports several WKT dialects (see :option:`projinfo -o`). If possible WKT2 should be used. + +Why is the axis ordering in PROJ not consistent? +-------------------------------------------------------------------------------- + +PROJ respects the axis ordering as it was defined by the authority in charge of +a given coordinate reference system. This is in accordance to the ISO19111 standard +:cite:`ISO19111`. Unfortunately most GIS software on the market doesn't follow this +standard. Before version 6, PROJ did not respect the standard either. This causes +some problems while the rest of the industry conforms to the standard. PROJ intends +to spearhead this effort, hopefully setting a good example for the rest of the +geospatial industry. + +Customarily in GIS the first component in a coordinate tuple has been aligned with +the east/west direction and the second component with the north/south direction. +For many coordinate reference systems this is also what is defined by the authority. +There are however exceptions, especially when dealing with coordinate systems that +don't align with the cardinal directions of a compass. For example it is not +obvious which coordinate component aligns to which axis in a skewed coordinate +system with a 45 degrees angle against the north direction. Similarly, a geocentric +cartesain coordinate system usually has the z-component aligned with the rotational +axis of the earth and hence the axis points towards north. Both cases are +incompatible with the convention of always having the x-component be the east/west +axis, the y-component the north/south axis and the z-component the up/down axis. + +In most cases coordinate reference systems with geodetic coordinates expect the +input ordered as latitude/longitude (typically with the EPSG dataset), however, +internally PROJ expects an longitude/latitude ordering for all projections. This +is generally hidden for users but in a few cases it is exposed at the surface +level of PROJ, most prominently in the :program:`proj` utility which expects +longitude/latitude ordering of input date (unless :program:`proj -r` is used). + +In case of doubt about the axis order of a specific CRS :program:`projinfo` is +able to provide an answer. Simply look up the CRS and examine the axis specification +of the Well-Known Text output: + +.. code-block:: console + + projinfo EPSG:4326 + PROJ.4 string: + +proj=longlat +datum=WGS84 +no_defs +type=crs + + WKT2_2018 string: + GEOGCRS["WGS 84", + DATUM["World Geodetic System 1984", + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["geodetic latitude (Lat)",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["geodetic longitude (Lon)",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]], + USAGE[ + SCOPE["unknown"], + AREA["World"], + BBOX[-90,-180,90,180]], + ID["EPSG",4326]] diff --git a/docs/source/references.bib b/docs/source/references.bib index 43b187b2..9829495f 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -160,6 +160,19 @@ Url = {https://www.iogp.org/bookstore/product/coordinate-conversions-and-transformation-including-formulas/} } +@TechReport{ISO19111, + Title = {{Geographic information -- Referencing by coordinates}}, + Author = {ISO}, + Year = {2019}, + Type = {Standard}, + Key = {ISO 19111:2019}, + Month = Jan, + Volume = {2019}, + Address = {Geneva, CH}, + Institution = {International Organization for Standardization}, + Url = {http://docs.opengeospatial.org/as/18-005r4/18-005r4.html} +} + @Article{Jenny2015, Title = {A compromise aspect-adaptive cylindrical projection for world maps}, Author = {Bernhard Jenny and Bojan Šavrič and Tom Patterson}, -- cgit v1.2.3 From 3d670b859026218045cf972e4b38af9e3e9a3c6f Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 28 Mar 2019 20:52:33 +0100 Subject: Add no-op operation. It does nothing. --- docs/source/operations/conversions/index.rst | 1 + docs/source/operations/conversions/noop.rst | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 docs/source/operations/conversions/noop.rst (limited to 'docs/source') 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. + -- cgit v1.2.3 From 2a0ad3d42c7342ee060791aba01f70f058238dce Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 2 Apr 2019 12:59:55 +0200 Subject: Docs: Clarify that angular in proj_angular_input/output means radians --- docs/source/development/reference/functions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 0066c3a2..00653ad9 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -638,23 +638,23 @@ Various .. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir) - Check if a operation expects angular input. + Check if a operation expects input in radians or not. :param `P`: Transformation object :type `P`: const PJ* :param `direction`: Starting direction of transformation :type `direction`: PJ_DIRECTION - :returns: :c:type:`int` 1 if angular input is expected, otherwise 0 + :returns: :c:type:`int` 1 if input units is expected in radians, otherwise 0 .. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir) - Check if an operation returns angular output. + Check if an operation returns output in radians or not. :param `P`: Transformation object :type `P`: const PJ* :param `direction`: Starting direction of transformation :type `direction`: PJ_DIRECTION - :returns: :c:type:`int` 1 if angular output is returned, otherwise 0 + :returns: :c:type:`int` 1 if output units is expected in radians, otherwise 0 C API for ISO-19111 functionality +++++++++++++++++++++++++++++++++ -- cgit v1.2.3 From 996930229a83cf84e465ab20de70eda4745bd097 Mon Sep 17 00:00:00 2001 From: snowman2 Date: Mon, 1 Apr 2019 19:43:14 -0500 Subject: added documentation for the priority of searcing for PROJ resource files --- docs/source/usage/environmentvars.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/source') diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst index 478e2eab..c8dfe28e 100644 --- a/docs/source/usage/environmentvars.rst +++ b/docs/source/usage/environmentvars.rst @@ -40,6 +40,16 @@ done by setting the variable with no content:: in other locations as well, amongst those are the users home directory, ``/usr/share/proj`` and the current folder. + You can also set the location of the resource files using + :func:`proj_context_set_search_paths` in the `proj.h` API header. + +.. versionchanged:: 6.1.0 + + Starting with PROJ version 6.1.0, the paths set by + :func:`proj_context_set_search_paths` will have priority over the + :envvar:`PROJ_LIB` to allow for mutliple versions of PROJ + resource files on your system without conflicting. + .. envvar:: PROJ_DEBUG Set the debug level of PROJ. The default debug level is zero, which results -- cgit v1.2.3 From 967de3bd79a0f0dbd672ad45340be046e26cc7af Mon Sep 17 00:00:00 2001 From: Andrew Hardin Date: Mon, 8 Apr 2019 14:18:00 -0600 Subject: Change egm96_16 to egm96_15. --- docs/source/operations/transformations/vgridshift.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') 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 -- cgit v1.2.3 From 79bb57eecdd7b6cdf0bc34a1cf1705aa9456043d Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 9 Apr 2019 15:08:32 +0200 Subject: DOC: update line numbers in dev quickstart example --- docs/source/development/quickstart.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index 960cddbf..267270fb 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -35,7 +35,7 @@ this in detail. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 48 + :lines: 49 :dedent: 4 Next we create the ``PJ`` transformation object ``P`` with the function @@ -51,7 +51,7 @@ details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 50-52 + :lines: 51-53 :dedent: 4 PROJ uses it's own data structures for handling coordinates. Here we use a @@ -62,17 +62,17 @@ for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 56 + :lines: 57 :dedent: 4 -The coordinate defined above is transformed with ``proj_trans_coord``. For this +The coordinate defined above is transformed with ``proj_trans``. For this a ``PJ`` object, a transformation direction (either forward or inverse) and the coordinate is needed. The transformed coordinate is returned in ``b``. Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 59-60 + :lines: 60-61 :dedent: 4 The inverse transformation (UTM to geodetic) is done similar to above, @@ -80,14 +80,14 @@ this time using ``PJ_INV`` as the direction. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 61-62 + :lines: 62-63 :dedent: 4 Before ending the program the allocated memory needs to be released again: .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 65-66 + :lines: 66-67 :dedent: 4 -- cgit v1.2.3 From fb125618fd18f112ed6f37662b021d07a602ff90 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 10 Apr 2019 11:38:23 +0200 Subject: DOC: add sphinx links to reference in dev quickstart (#1420) --- docs/source/development/quickstart.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index 267270fb..b6c5d17c 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -28,7 +28,7 @@ See the :doc:`reference for more info on data types `. :lines: 43-45 :dedent: 4 -For use in multi-threaded programs the ``PJ_CONTEXT`` threading-context is used. +For use in multi-threaded programs the :c:type:`PJ_CONTEXT` threading-context is used. In this particular example it is not needed, but for the sake of completeness it created here. The section on :doc:`threads ` discusses this in detail. @@ -38,15 +38,15 @@ this in detail. :lines: 49 :dedent: 4 -Next we create the ``PJ`` transformation object ``P`` with the function -``proj_create``. ``proj_create`` takes the threading context ``C`` created above, -and a proj-string that defines the desired transformation. Here we transform -from geodetic coordinate to UTM zone 32N. +Next we create the :c:type:`PJ` transformation object ``P`` with the function +:c:func:`proj_create`. :c:func:`proj_create` takes the threading context ``C`` +created above, and a proj-string that defines the desired transformation. +Here we transform from geodetic coordinate to UTM zone 32N. It is recommended to create one threading-context per thread used by the program. -This ensures that all ``PJ`` objects created in the same context will be sharing -resources such as error-numbers and loaded grids. -In case the creation of the ``PJ`` object fails an error message is displayed and -the program returns. See :doc:`errorhandling` for further +This ensures that all :c:type:`PJ` objects created in the same context will be +sharing resources such as error-numbers and loaded grids. +In case the creation of the :c:type:`PJ` object fails an error message is +displayed and the program returns. See :doc:`errorhandling` for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c @@ -55,9 +55,9 @@ details. :dedent: 4 PROJ uses it's own data structures for handling coordinates. Here we use a -``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note -that the input values are converted to radians with ``proj_torad``. This is -necessary since PROJ is using radians internally. See :doc:`transformations` +:c:type:`PJ_COORD` which is easily assigned with the function :c:func:`proj_coord`. +Note that the input values are converted to radians with :c:func:`proj_torad`. +This is necessary since PROJ is using radians internally. See :doc:`transformations` for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c @@ -65,10 +65,10 @@ for further details. :lines: 57 :dedent: 4 -The coordinate defined above is transformed with ``proj_trans``. For this -a ``PJ`` object, a transformation direction (either forward or inverse) and the -coordinate is needed. The transformed coordinate is returned in ``b``. -Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. +The coordinate defined above is transformed with :c:func:`proj_trans`. For this +a :c:type:`PJ` object, a transformation direction (either forward or inverse) +and the coordinate is needed. The transformed coordinate is returned in ``b``. +Here the forward (:c:type:`PJ_FWD`) transformation from geodetic to UTM is made. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c @@ -76,7 +76,7 @@ Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. :dedent: 4 The inverse transformation (UTM to geodetic) is done similar to above, -this time using ``PJ_INV`` as the direction. +this time using :c:type:`PJ_INV` as the direction. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c -- cgit v1.2.3 From a8080f3f17f96449a6c706bfed9ab3d7f9a75e5b Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Fri, 19 Apr 2019 22:53:31 +0200 Subject: Doc: update quickstart with PROJ 6 API (fixes #1403) --- docs/source/development/quickstart.rst | 91 ++++++++++++++++++++----- docs/source/development/reference/functions.rst | 19 ++++++ 2 files changed, 94 insertions(+), 16 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index b6c5d17c..d53d98fd 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -25,7 +25,7 @@ See the :doc:`reference for more info on data types `. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 43-45 + :lines: 43-46 :dedent: 4 For use in multi-threaded programs the :c:type:`PJ_CONTEXT` threading-context is used. @@ -35,13 +35,43 @@ this in detail. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 49 + :lines: 50 :dedent: 4 Next we create the :c:type:`PJ` transformation object ``P`` with the function -:c:func:`proj_create`. :c:func:`proj_create` takes the threading context ``C`` -created above, and a proj-string that defines the desired transformation. -Here we transform from geodetic coordinate to UTM zone 32N. +:c:func:`proj_create_crs_to_crs`. :c:func:`proj_create_crs_to_crs` takes the threading context ``C`` +created above, a string that describes the source coordinate reference system (CRS), +a string that describes the target CRS and an optional description of the area of +use. +The strings for the source or target CRS may be PROJ strings (``+proj=longlat +datum=WGS84``), +CRS identified by their code (``EPSG:4326`` or ``urn:ogc:def:crs:EPSG::4326``) or +by a well-known text (WKT) string ( +:: + + GEOGCRS["WGS 84", + DATUM["World Geodetic System 1984", + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["geodetic latitude (Lat)",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["geodetic longitude (Lon)",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]], + USAGE[ + SCOPE["unknown"], + AREA["World"], + BBOX[-90,-180,90,180]], + ID["EPSG",4326]] + +). +The use of PROJ strings to describe a CRS is considered as legacy (one of the +main weakness of PROJ strings is their inability to describe a geodetic datum, +other than the few ones hardcoded in the ``+datum`` parameter). +Here we transform from geographic coordinates to UTM zone 32N. It is recommended to create one threading-context per thread used by the program. This ensures that all :c:type:`PJ` objects created in the same context will be sharing resources such as error-numbers and loaded grids. @@ -51,43 +81,72 @@ details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 51-53 + :lines: 52-60 :dedent: 4 -PROJ uses it's own data structures for handling coordinates. Here we use a +:c:func:`proj_create_crs_to_crs` creates a transformation object, which accepts +coordinates expressed in the units and axis order of the definition of the +source CRS, and return transformed coordinates in the units and axis order of +the definition of the target CRS. +For almost most geographic CRS, the units will be in most cases degrees (in +rare cases, such as EPSG:4807 / NTF (Paris), this can be grads). For geographic +CRS defined by the EPSG authority, the order of coordinates is latitude first, +longitude second. When using a PROJ string, on contrary the order will be +longitude first, latitude second. +For projected CRS, the units may vary (metre, us-foot, etc..). For projected +CRS defined by the EPSG authority, and with EAST / NORTH directions, the order +might be easting first, northing second, or the reverse. When using a PROJ string, +the order will be easting first, northing second, except if the ``+axis`` +parameter modifies it. + +If for the needs of your software, you want +a uniform axis order (and thus do not care about axis order mandated by the +authority defining the CRS), the :c:func:`proj_normalize_for_visualization` +function can be used to modify the PJ* object returned by +:c:func:`proj_create_crs_to_crs` so that it accepts as input and returns as +output coordinates using the traditional GIS order, that is longitude, latitude +(followed by elevation, time) for geographic CRS and easting, northing for most +projected CRS. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 65-71 + :dedent: 4 + +PROJ uses its own data structures for handling coordinates. Here we use a :c:type:`PJ_COORD` which is easily assigned with the function :c:func:`proj_coord`. -Note that the input values are converted to radians with :c:func:`proj_torad`. -This is necessary since PROJ is using radians internally. See :doc:`transformations` -for further details. +When using +proj=longlat, the order of coordinates is longitude, latitude, +and values are expressed in degrees. If you used instead a EPSG geographic CRS, +like EPSG:4326 (WGS84), it would be latitude, longitude. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 57 + :lines: 76 :dedent: 4 The coordinate defined above is transformed with :c:func:`proj_trans`. For this a :c:type:`PJ` object, a transformation direction (either forward or inverse) and the coordinate is needed. The transformed coordinate is returned in ``b``. -Here the forward (:c:type:`PJ_FWD`) transformation from geodetic to UTM is made. +Here the forward (:c:type:`PJ_FWD`) transformation from geographic to UTM is made. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 60-61 + :lines: 79-80 :dedent: 4 -The inverse transformation (UTM to geodetic) is done similar to above, +The inverse transformation (UTM to geographic) is done similar to above, this time using :c:type:`PJ_INV` as the direction. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 62-63 + :lines: 81-82 :dedent: 4 Before ending the program the allocated memory needs to be released again: .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 66-67 + :lines: 85-86 :dedent: 4 diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 00653ad9..319face3 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -144,6 +144,25 @@ paragraph for more details. :type `area`: PJ_AREA :returns: :c:type:`PJ*` +.. c:function:: PJ *proj_normalize_for_visualization(PJ_CONTEXT *ctx, const PJ* obj) + + .. versionadded:: 6.1.0 + + Returns a PJ* object whose axis order is the one expected for + visualization purposes. + + The input object must be a coordinate operation, that has been created with + proj_create_crs_to_crs(). + If the axis order of its source or target CRS is northing,easting, then an + axis swap operation will be inserted. + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context. + :param `obj`: Object of type CoordinateOperation + :returns: :c:type:`PJ*` + + .. c:function:: PJ* proj_destroy(PJ *P) Deallocate a :c:type:`PJ` transformation object. -- cgit v1.2.3 From c7417323daf1323e6ecad6cc1ba9c116397d8b00 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Fri, 19 Apr 2019 23:23:35 +0200 Subject: Doc: add a PROJ 4 -> 6 migration (fixes #1407) --- docs/source/development/migration.rst | 187 ++++++++++++++++++++++++++++++---- 1 file changed, 168 insertions(+), 19 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst index 99143f20..df622ecb 100644 --- a/docs/source/development/migration.rst +++ b/docs/source/development/migration.rst @@ -1,5 +1,150 @@ .. _API_migration: +================================================================================ +Version 4 to 6 API Migration +================================================================================ + +This is a transition guide for developers wanting to migrate their code to use +PROJ version 6. + +Code example +############################################################################### + +The difference between the old and new API is shown here with a few examples. Below +we implement the same program with the two different API's. The program reads +input longitude and latitude from the command line and convert them to +projected coordinates with the Mercator projection. + +We start by writing the program for PROJ 4: + +.. code-block:: C + + #include + + main(int argc, char **argv) { + projPJ pj_merc, pj_latlong; + double x, y; + + if (!(pj_longlat = pj_init_plus("+proj=longlat +ellps=clrk66")) ) + return 1; + if (!(pj_merc = pj_init_plus("+proj=merc +datum=clrk66 +lat_ts=33")) ) + return 1; + + while (scanf("%lf %lf", &x, &y) == 2) { + x *= DEG_TO_RAD; /* longitude */ + y *= DEG_TO_RAD; /* latitude */ + p = pj_transform(pj_longlat, pj_merc, 1, 1, &x, &y, NULL ); + printf("%.2f\t%.2f\n", x, y); + } + + pj_free(pj_longlat); + pj_free(pj_merc); + + return 0; + } + +The same program implemented using PROJ 6: + +.. code-block:: C + + #include + + main(int argc, char **argv) { + PJ *P; + PJ_COORD c; + + /* NOTE: the use of PROJ strings to describe CRS is strongly discouraged */ + /* in PROJ 6, as PROJ strings are a poor way of describing a CRS, and */ + /* more precise its geodetic datum. */ + /* Use of codes provided by authorities (such as "EPSG:4326", etc...) */ + /* or WKT strings will bring the full power of the "transformation */ + /* engine" used by PROJ to determine the best transformation(s) between */ + /* two CRS. */ + P = proj_create_crs_to_crs(PJ_DEFAULT_CTX, + "+proj=longlat +ellps=clrs66", + "+proj=merc +ellps=clrk66 +lat_ts=33", + NULL); + if (P==0) + return 1; + + { + /* For that particular use case, this is not needed. */ + /* proj_normalize_for_visualization() ensures that the coordinate */ + /* order expected and returned by proj_trans() will be longitude, */ + /* latitude for geographic CRS, and easting, northing for projected */ + /* CRS. If instead of using PROJ strings as above, "EPSG:XXXX" codes */ + /* had been used, this might had been necessary. */ + PJ* P_for_GIS = proj_normalize_for_visualization(C, P); + if( 0 == P_for_GIS ) { + proj_destroy(P); + return 1; + } + proj_destroy(P); + P = P_for_GIS; + } + + while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) { + /* No need to convert to radian */ + c = proj_trans(P, PJ_FWD, c); + printf("%.2f\t%.2f\n", c.xy.x, c.xy.y); + } + + proj_destroy(P); + } + + +Function mapping from old to new API +############################################################################### + ++---------------------------------------+-------------------------------------------------+ +| Old API functions | New API functions | ++=======================================+=================================================+ +| pj_fwd | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| pj_inv | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| pj_fwd3 | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| pj_inv3 | :c:func:`proj_trans` | ++---------------------------------------+-------------------------------------------------+ +| pj_transform | :c:func:`proj_create_crs_to_crs` + | +| | (:c:func:`proj_normalize_for_visualization` +) | +| | :c:func:`proj_trans`, | +| | :c:func:`proj_trans_array` or | +| | :c:func:`proj_trans_generic` | ++---------------------------------------+-------------------------------------------------+ +| pj_init | :c:func:`proj_create` / | +| | :c:func:`proj_create_crs_to_crs` | ++---------------------------------------+-------------------------------------------------+ +| pj_init | :c:func:`proj_create` / | +| | :c:func:`proj_create_crs_to_crs` | ++---------------------------------------+-------------------------------------------------+ +| pj_free | :c:func:`proj_destroy` | ++---------------------------------------+-------------------------------------------------+ +| pj_is_latlong | :c:func:`proj_get_type` | ++---------------------------------------+-------------------------------------------------+ +| pj_is_geocent | :c:func:`proj_get_type` | ++---------------------------------------+-------------------------------------------------+ +| pj_get_def | :c:func:`proj_pj_info` | ++---------------------------------------+-------------------------------------------------+ +| pj_latlong_from_proj | *No direct equivalent*, but can be accomplished | +| | by chaining :c:func:`proj_create`, | +| | :c:func:`proj_crs_get_horizontal_datum` and | +| | :c:func:`proj_create_geographic_crs_from_datum` | ++---------------------------------------+-------------------------------------------------+ +| pj_set_finder | :c:func:`proj_context_set_file_finder` | ++---------------------------------------+-------------------------------------------------+ +| pj_set_searchpath | :c:func:`proj_context_set_search_paths` | ++---------------------------------------+-------------------------------------------------+ +| pj_deallocate_grids | *No equivalent* | ++---------------------------------------+-------------------------------------------------+ +| pj_strerrno | *No equivalent* | ++---------------------------------------+-------------------------------------------------+ +| pj_get_errno_ref | :c:func:`proj_errno` | ++---------------------------------------+-------------------------------------------------+ +| pj_get_release | :c:func:`proj_info` | ++---------------------------------------+-------------------------------------------------+ + ================================================================================ Version 4 to 5 API Migration ================================================================================ @@ -66,7 +211,7 @@ Code example The difference between the old and new API is shown here with a few examples. Below we implement the same program with the two different API's. The program reads -input latitude and longitude from the command line and convert them to +input longitude and latitude from the command line and convert them to projected coordinates with the Mercator projection. We start by writing the program for PROJ v. 4: @@ -76,21 +221,24 @@ We start by writing the program for PROJ v. 4: #include main(int argc, char **argv) { - projPJ pj_merc, pj_latlong; + projPJ pj_merc, pj_longlat; double x, y; - if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) + if (!(pj_longlat = pj_init_plus("+proj=longlat +ellps=clrk66")) ) return 1; - if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) + if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) return 1; while (scanf("%lf %lf", &x, &y) == 2) { - x *= DEG_TO_RAD; - y *= DEG_TO_RAD; - p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL ); + x *= DEG_TO_RAD; /* longitude */ + y *= DEG_TO_RAD; /* latitude */ + p = pj_transform(pj_longlat, pj_merc, 1, 1, &x, &y, NULL ); printf("%.2f\t%.2f\n", x, y); } + pj_free(pj_longlat); + pj_free(pj_merc); + return 0; } @@ -115,6 +263,7 @@ The same program implemented using PROJ v. 5: printf("%.2f\t%.2f\n", c.xy.x, c.xy.y); } + proj_destroy(P); } Looking at the two different programs, there's a few immediate @@ -155,27 +304,27 @@ Function mapping from old to new API +---------------------------------------+---------------------------------------+ | Old API functions | New API functions | +=======================================+=======================================+ -| pj_fwd | proj_trans | +| pj_fwd | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ -| pj_inv | proj_trans | +| pj_inv | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ -| pj_fwd3 | proj_trans | +| pj_fwd3 | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ -| pj_inv3 | proj_trans | +| pj_inv3 | :c:func:`proj_trans` | +---------------------------------------+---------------------------------------+ | pj_transform | proj_trans_array or proj_trans_generic| +---------------------------------------+---------------------------------------+ -| pj_init | proj_create | +| pj_init | :c:func:`proj_create` | +---------------------------------------+---------------------------------------+ -| pj_init_plus | proj_create | +| pj_init_plus | :c:func:`proj_create` | +---------------------------------------+---------------------------------------+ -| pj_free | proj_destroy | +| pj_free | :c:func:`proj_destroy` | +---------------------------------------+---------------------------------------+ -| pj_is_latlong | proj_angular_output | +| pj_is_latlong | :c:func:`proj_angular_output` | +---------------------------------------+---------------------------------------+ -| pj_is_geocent | proj_angular_outout | +| pj_is_geocent | :c:func:`proj_angular_output` | +---------------------------------------+---------------------------------------+ -| pj_get_def | proj_pj_info | +| pj_get_def | :c:func:`proj_pj_info` | +---------------------------------------+---------------------------------------+ | pj_latlong_from_proj | *No equivalent* | +---------------------------------------+---------------------------------------+ @@ -187,7 +336,7 @@ Function mapping from old to new API +---------------------------------------+---------------------------------------+ | pj_strerrno | *No equivalent* | +---------------------------------------+---------------------------------------+ -| pj_get_errno_ref | proj_errno | +| pj_get_errno_ref | :c:func:`proj_errno` | +---------------------------------------+---------------------------------------+ -| pj_get_release | proj_info | +| pj_get_release | :c:func:`proj_info` | +---------------------------------------+---------------------------------------+ -- cgit v1.2.3 From 5d6945e76ba83af90bc94501f79fc0c51011c724 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sat, 20 Apr 2019 16:36:28 +0200 Subject: Docs: Update link to Dutch grid files Closes #1435 --- docs/source/resource_files.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/resource_files.rst b/docs/source/resource_files.rst index 53843571..d6f64175 100644 --- a/docs/source/resource_files.rst +++ b/docs/source/resource_files.rst @@ -106,7 +106,7 @@ Brazil Netherlands ................................................................................ -`Dutch grid `__ (Registration required before download) +`Dutch grid `__ (Registration required before download) Portugal ................................................................................ -- cgit v1.2.3 From 292807eee9e1194175b64cb5c0a9f0b432352abc Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Mon, 22 Apr 2019 20:05:36 +0200 Subject: proj_create(): add support for compoundCRS and concatenatedOperation named from their components Support following syntaxes: - OGC URN combining references for compoundCRS: e.g. "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" - its GDAL shortcut: e.g. "EPSG:2393+5717" - OGC URN combining references for concatenated operations: e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618" --- docs/source/apps/projinfo.rst | 17 +++++++++++------ docs/source/development/reference/functions.rst | 17 +++++++++++++---- 2 files changed, 24 insertions(+), 10 deletions(-) (limited to 'docs/source') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index c8219838..955b9a18 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -29,12 +29,17 @@ Synopsis | {object_definition} | (-s {srs_def} -t {srs_def}) | - where {object_definition} or {object_definition} is a PROJ string, a - WKT string, an object name, AUTHORITY:CODE - (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS - found in the proj.db database) or a OGC URN (such as "urn:ogc:def:crs:EPSG::4326", - "urn:ogc:def:coordinateOperation:EPSG::1671", "urn:ogc:def:ellipsoid:EPSG::7001" - or "urn:ogc:def:datum:EPSG::6326") + where {object_definition} or {srs_def} is + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") Description *********** diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 00653ad9..aa177b31 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -29,9 +29,17 @@ paragraph for more details. .. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition) - Create a transformation object, or a CRS object, from a proj-string, - a WKT string, or object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", - "urn:ogc:def:coordinateOperation:EPSG::1671"). + Create a transformation object, or a CRS object, from: + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") Example call: @@ -110,7 +118,8 @@ paragraph for more details. - the name of a CRS as found in the PROJ database, e.g "WGS84", "NAD27", etc. - - more generally any string accepted by :c:func:`proj_create` + - more generally any string accepted by :c:func:`proj_create` representing + a CRS An "area of use" can be specified in area. When it is supplied, the more accurate transformation between two given systems can be chosen. -- cgit v1.2.3 From c8c3f0bec38a643a3d7391213b6dbc99363d75e4 Mon Sep 17 00:00:00 2001 From: Peter Limkilde Svendsen Date: Mon, 6 May 2019 16:59:05 +0200 Subject: Fix typos in geodesic doc --- docs/source/geodesic.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/geodesic.rst b/docs/source/geodesic.rst index c7753404..11bb5e5c 100644 --- a/docs/source/geodesic.rst +++ b/docs/source/geodesic.rst @@ -93,7 +93,7 @@ The routines also calculate several other quantities of interest On a flat surface, we have :math:`m_{12}=s_{12}`. * :math:`M_{12}` and :math:`M_{21}` are geodesic scales. If two geodesics are parallel at point 1 and separated by a small distance - :\math`dt`, then they are separated by a distance :math:`M_{12}\,dt` at + :math:`dt`, then they are separated by a distance :math:`M_{12}\,dt` at point 2. :math:`M_{21}` is defined similarly (with the geodesics being parallel to one another at point 2). :math:`M_{12}` and :math:`M_{21}` are dimensionless quantities. On a flat surface, @@ -159,7 +159,7 @@ areas is based on :cite:`Danielsen1989`. These improve on the work of :cite:`Vincenty1975` in the following respects: * The results are accurate to round-off for terrestrial ellipsoids (the - error in the distance is less then 15 nanometers, compared to 0.1 mm + error in the distance is less than 15 nanometers, compared to 0.1 mm for Vincenty). * The solution of the inverse problem is always found. (Vincenty's method fails to converge for nearly antipodal points.) -- cgit v1.2.3