Merge branch '6.2' of https://github.com/OSGeo/proj.4 into 6.2

author: Kristian Evers <kristianevers@gmail.com> 2019-11-28 14:58:14 +0100
committer: Kristian Evers <kristianevers@gmail.com> 2019-11-28 14:58:14 +0100
commit: ac2762b581918dd3fcecf2a4d0dd72f92ca87011 (patch)
tree: d0158eb03d39b9d2249a30ea88f333c8e560f351 /docs/source
parent: 2bc1e2e1a9d0a7abe410ee99d39236570474cfde (diff)
parent: bce4b158ab5f7d146de8e8fc98df4612dc8c2c9e (diff)
download: PROJ-ac2762b581918dd3fcecf2a4d0dd72f92ca87011.tar.gz
PROJ-ac2762b581918dd3fcecf2a4d0dd72f92ca87011.zip
16 files changed, 587 insertions, 67 deletions
diff --git a/docs/source/_extensions/redirects.py b/docs/source/_extensions/redirects.py
new file mode 100644
index 00000000..6a59b622
--- /dev/null
+++ b/docs/source/_extensions/redirects.py
@@ -0,0 +1,39 @@
+import os
+
+# https://tech.signavio.com/2017/managing-sphinx-redirects
+
+
+template="""<html>
+  <head>
+    <meta http-equiv="refresh" content="1; url=%s" />
+    <script>
+      window.location.href = "%s"
+    </script>
+  </head>
+</html>"""
+
+
+def gather_redirects():
+    output = {}
+
+    output.update({ 'projjson.html' : 'usage/projjson.html' })
+    return output
+
+from shutil import copyfile
+# copy legacy redirects
+def copy_legacy_redirects(app, docname): # Sphinx expects two arguments
+    if app.builder.name == 'html':
+        for key in app.config.redirect_files:
+            src = key
+            tgt = app.config.redirect_files[key]
+            html = template % (tgt, tgt)
+            with open(os.path.join(app.outdir, src), 'wb') as f:
+                f.write(html.encode('utf-8'))
+                f.close()
+
+
+
+def setup(app):
+    app.add_config_value('redirect_files', {}, 'html')
+    app.connect('build-finished', copy_legacy_redirects)
+    return { 'parallel_read_safe': False, 'parallel_write_safe': True }
diff --git a/docs/source/about.rst b/docs/source/about.rst
index f78de532..6ecbb1bc 100644
--- a/docs/source/about.rst
+++ b/docs/source/about.rst
@@ -2,27 +2,11 @@
 About
 ###############################################################################
 
-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.
-
-PROJ includes :ref:`command line applications<apps>` 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<reference>`, or API in short. The API
-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 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.
-
-  .. image:: ../images/OSGeo_community.png
-     :scale: 30 %
-     :alt: OSGeo Community
+.. include:: about_core.rst
+
+.. image:: ../images/OSGeo_community.png
+    :scale: 30 %
+    :alt: OSGeo Community
 
 Citation
 -------------------------------------------------------------------------------
@@ -31,6 +15,8 @@ Citation
 .. include:: ../../CITATION
 
 
+.. _license:
+
 License
 -------------------------------------------------------------------------------
 
diff --git a/docs/source/about_core.rst b/docs/source/about_core.rst
new file mode 100644
index 00000000..5f4238bc
--- /dev/null
+++ b/docs/source/about_core.rst
@@ -0,0 +1,18 @@
+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. PROJ
+is released under the :ref:`X/MIT open source license <license>`
+
+PROJ includes :ref:`command line applications<apps>` 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<reference>`, or API in short. The API
+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 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.
+\ No newline at end of file
diff --git a/docs/source/community/code_of_conduct.rst b/docs/source/community/code_of_conduct.rst
new file mode 100644
index 00000000..175b184a
--- /dev/null
+++ b/docs/source/community/code_of_conduct.rst
@@ -0,0 +1,92 @@
+.. _code_of_conduct:
+
+===========================
+Code of Conduct
+===========================
+
+The PROJ project has adopted the
+`Contributor Covenant Code of Conduct <https://www.contributor-covenant.org/>`_.
+Everyone who participates in the PROJ community is expected to follow the
+code of conduct as written below.
+
+
+Our Pledge
+----------
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+Our Standards
+-------------
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+Our Responsibilities
+--------------------
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+Scope
+-----
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+Enforcement
+-----------
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at `kristianevers@gmail.com <mailto:kristianevers@gmail.com>`_.
+All complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+Attribution
+-----------
+
+This Code of Conduct is adapted from the
+`Contributor Covenant <https://www.contributor-covenant.org>`_, version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
+
diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst
index ccdbceca..b0d1ce3a 100644
--- a/docs/source/community/index.rst
+++ b/docs/source/community/index.rst
@@ -14,4 +14,5 @@ contributor the community is always very welcoming.
    channels
    contributing
    code_contributions
+   code_of_conduct
    rfc/index
diff --git a/docs/source/community/rfc/rfc-2.rst b/docs/source/community/rfc/rfc-2.rst
index e6f013a3..df6f742d 100644
--- a/docs/source/community/rfc/rfc-2.rst
+++ b/docs/source/community/rfc/rfc-2.rst
@@ -6,7 +6,7 @@ PROJ RFC 2: Initial integration of "GDAL SRS barn" work
 
 :Author: Even Rouault
 :Contact: even.rouault at spatialys.com
-:Status: Adopted (not yet merged into master)
+:Status: Adopted, implemented in PROJ 6.0
 :Initial version: 2018-10-09
 :Last Updated: 2018-10-31
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
index dd7adc2d..1008b79e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -20,6 +20,7 @@ import datetime
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('_extensions'))
 
 import bibstyle
 
@@ -35,6 +36,7 @@ extensions = [
     'sphinx.ext.mathjax',
     'sphinxcontrib.bibtex',
     'breathe',
+    'redirects',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -66,7 +68,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.2.0'
+version = '6.2.1'
 
 # use same |release| as |version|
 release = version
@@ -130,8 +132,20 @@ html_theme = "sphinx_rtd_theme"
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {}
-
+html_theme_options = {
+    'canonical_url': 'https://proj.org',
+    'logo_only': True,
+    'display_version': True,
+    'prev_next_buttons_location': 'both',
+    'style_external_links': False,
+    'style_nav_header_background': '#353130',
+    # Toc options
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    #'navigation_depth': 4,
+    'includehidden': True,
+    'titles_only': False
+}
 # Add any paths that contain custom themes here, relative to this directory.
 
 
@@ -144,7 +158,7 @@ html_theme_options = {}
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '../images/logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -157,6 +171,12 @@ html_theme_options = {}
 html_static_path = ['_static']
 
 html_context = {
+    'display_github': True,
+    'theme_vcs_pageview_mode': 'edit',
+    'github_user': 'OSGeo',
+    'github_repo': 'PROJ',
+    # TODO: edit when switching active branch
+    'github_version': '/6.2/docs/source/',
     'css_files': [
         '_static/theme_overrides.css',  # override wide tables in RTD theme
     ],
@@ -358,3 +378,6 @@ texinfo_documents = [
 breathe_projects = {
     "cpp_stuff":"../build/xml/",
 }
+
+import redirects
+redirect_files = redirects.gather_redirects()
diff --git a/docs/source/download.rst b/docs/source/download.rst
index 9ec03368..36e2a897 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-09-01** `proj-6.2.0.tar.gz`_ (`md5`_)
+* **2019-11-01** `proj-6.2.1.tar.gz`_ (`md5`_)
 * **2018-09-15** `proj-datumgrid-1.8.zip`_
 * **2019-09-01** `proj-datumgrid-europe-1.4.zip`_
 * **2019-03-01** `proj-datumgrid-north-america-1.2.zip`_
@@ -24,6 +24,7 @@ Current Release
 Past Releases
 --------------------------------------------------------------------------------
 
+* **2019-09-01** `proj-6.2.0.tar.gz`_
 * **2019-07-01** `proj-6.1.1.tar.gz`_
 * **2019-05-15** `proj-6.1.0.tar.gz`_
 * **2019-03-01** `proj-6.0.0.tar.gz`_
@@ -44,6 +45,7 @@ Past Releases
 * **2018-03-01** `proj-datumgrid-europe-1.0.zip`_
 * **2018-03-01** `proj-datumgrid-north-america-1.0.zip`_
 
+.. _`proj-6.2.1.tar.gz`: https://download.osgeo.org/proj/proj-6.2.1.tar.gz
 .. _`proj-6.2.0.tar.gz`: https://download.osgeo.org/proj/proj-6.2.0.tar.gz
 .. _`proj-6.1.1.tar.gz`: https://download.osgeo.org/proj/proj-6.1.1.tar.gz
 .. _`proj-6.1.0.tar.gz`: https://download.osgeo.org/proj/proj-6.1.0.tar.gz
@@ -68,5 +70,5 @@ Past Releases
 .. _`proj-datumgrid-north-america-1.2.zip`: https://download.osgeo.org/proj/proj-datumgrid-north-america-1.2.zip
 .. _`proj-datumgrid-oceania-1.0.zip`: https://download.osgeo.org/proj/proj-datumgrid-oceania-1.0.zip
 .. _`proj-datumgrid-world-1.0.zip`: https://download.osgeo.org/proj/proj-datumgrid-world-1.0.zip
-.. _`md5`: https://download.osgeo.org/proj/proj-6.2.0.tar.gz.md5
+.. _`md5`: https://download.osgeo.org/proj/proj-6.2.1.tar.gz.md5
 .. _`proj.pdf`: https://raw.githubusercontent.com/OSGeo/PROJ/gh-pages/proj.pdf
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index e7265d48..0096accb 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -115,7 +115,7 @@ There are however exceptions, especially when dealing with coordinate systems th
 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
+cartesian 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.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 69f483ce..e9590d99 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -24,23 +24,7 @@ PROJ
 
 .. only:: html
 
-    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.
-
-    PROJ includes :ref:`command line applications<apps>` 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<reference>`, or API in short. The API
-    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 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.
+    .. include:: about_core.rst
 
     You can download the source code for PROJ on the :ref:`download section<download>`
     and find links to prepackaged executables in the
diff --git a/docs/source/install.rst b/docs/source/install.rst
index d3c2fab6..fa13046b 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -42,8 +42,8 @@ files is available on `DockerHub`_. Get the package with::
 
     docker pull osgeo/proj
 
-.. _`Docker`: https://docker.org
-.. _`DockerHub`: https://hub.docker.com/r/osgeo/proj.4/
+.. _`Docker`: https://www.docker.com/
+.. _`DockerHub`: https://hub.docker.com/r/osgeo/proj/
 
 Windows
 --------------------------------------------------------------------------------
@@ -94,6 +94,13 @@ On Debian and similar systems (e.g. Ubuntu) the APT package manager is used::
 
     sudo apt-get install proj-bin
 
+Fedora
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+On Fedora the dnf package manager is used::
+
+    sudo dnf install proj
+
 Red Hat
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
diff --git a/docs/source/news.rst b/docs/source/news.rst
index 2a6e8e47..17e573a7 100644
--- a/docs/source/news.rst
+++ b/docs/source/news.rst
@@ -3,6 +3,77 @@
 News
 ###############################################################################
 
+6.2.1 Release Notes
+++++++++++++++++++++++++++++++++++++++++
+*November 1st 2019*
+
+Updates
+-------
+
+* Update the EPSG database to version 9.8.2
+
+Bug fixes
+----------
+
+* Fixed erroneous spelling of "Potsdam" (`#1573 <https://github.com/OSGeo/PROJ/issues/1573>`_)
+
+* Calculate y-coordinate correctly in :ref:`bertin1953` in all cases (`#1579 <https://github.com/OSGeo/PROJ/issues/1579>`_)
+
+* :c:func:`proj_create_crs_to_crs_from_pj()`: make the PJ* arguments const PJ* (`#1583 <https://github.com/OSGeo/PROJ/issues/1583>`_)
+
+* :c:func:`PROJStringParser::createFromPROJString()`: avoid potential infinite
+  recursion (`#1574 <https://github.com/OSGeo/PROJ/issues/1574>`_)
+
+* Avoid core dump when setting ``ctx==NULL`` in functions
+  :c:func:`proj_coordoperation_is_instantiable` and
+  :c:func:`proj_coordoperation_has_ballpark_transformation` (`#1590 <https://github.com/OSGeo/PROJ/issues/1590>`_)
+
+* :c:func:`createOperations()`: fix conversion from/to PROJ.4 CRS strings with
+  non-ISO-kosher options and ``+towgs84``/``+nadgrids`` (`#1602 <https://github.com/OSGeo/PROJ/issues/1602>`_)
+
+* :c:func:`proj_trans_generic()`: properly set coordinate time to ``HUGE_VAL``
+  when no value is passed to the function (`#1604 <https://github.com/OSGeo/PROJ/issues/1604>`_)
+
+* Fix support for ``+proj=ob_tran +o_proj=lonlat/latlong/latlon`` instead of only
+  only allowing ``+o_proj=longlat`` (`#1601 <https://github.com/OSGeo/PROJ/issues/1601>`_)
+
+* Improve backwards compatibility of vertical transforms (`#1613 <https://github.com/OSGeo/PROJ/issues/1613>`_)
+
+* Improve emulation of deprecated ``+init`` style initialization (`#1614 <https://github.com/OSGeo/PROJ/issues/1614>`_)
+
+* :program:`cs2cs`: autopromote CRS to 3D when there's a mix of 2D and 3D (`#1563 <https://github.com/OSGeo/PROJ/issues/1563>`_)
+
+* Avoid divisions by zero in odd situations (`#1620 <https://github.com/OSGeo/PROJ/issues/1620>`_)
+
+* Avoid compile error on Solaris (`#1639 <https://github.com/OSGeo/PROJ/issues/1639>`_)
+
+* :c:func:`proj_create_crs_to_crs()`: fix when there are only transformations with
+  ballpark steps (`#1643 <https://github.com/OSGeo/PROJ/issues/1643>`_)
+
+* PROJ string CRS ingester: recognize more unit-less parameters, and general
+  handling of ``+key=string_value`` parameters (`#1645 <https://github.com/OSGeo/PROJ/issues/1645>`_)
+
+* Only call pkg-config in configure when necessary (`#1652 <https://github.com/OSGeo/PROJ/issues/1652>`_)
+
+* :ref:`aeqd`: for spherical forward path, go to higher precision ellipsoidal
+  case when the point coordinates are super close to the origin (`#1654 <https://github.com/OSGeo/PROJ/issues/1654>`_)
+
+* :c:func:`proj_create_crs_to_crs()`: remove elimination of Ballpark operations
+  that caused transformation failures in some cases (`#1665 <https://github.com/OSGeo/PROJ/issues/1665>`_)
+
+* :c:func:`createOperations()`: allow transforming from a compoundCRS of a bound
+  verticalCRS to a 2D CRS (`#1667 <https://github.com/OSGeo/PROJ/issues/1667>`_)
+
+* Avoid segfaults in case of out-of-memory situations (`#1679 <https://github.com/OSGeo/PROJ/issues/1679>`_)
+
+* :c:func:`createOperations()`: fix double vertical unit conversion from CompoundCRS
+  to other CRS when the horizontal part of the projected CRS uses non-metre
+  unit (#1683)(`#1683 <https://github.com/OSGeo/PROJ/issues/1683>`_)
+
+* :c:func:`importFromWkt()`: fix axis orientation for non-standard ESRI WKT (`#1690 <https://github.com/OSGeo/PROJ/issues/1690>`_)
+
+
+
 6.2.0 Release Notes
 ++++++++++++++++++++++++++++++++++++++++
 *September 1st 2019*
@@ -10,7 +81,7 @@ News
 Updates
 -------
 
- * Introduced PROJJSON, a JSON encoding of WKT2 (`#1547 <https://github.com/OSGeo/PROJ/issues/15475>`_)
+ * Introduced :ref:`PROJJSON`, a JSON encoding of WKT2 (`#1547 <https://github.com/OSGeo/PROJ/issues/1547>`_)
  * Support CRS instantiation of OGC URN's (`#1505 <https://github.com/OSGeo/PROJ/issues/1505>`_)
 
  * Expose scope and remarks of database objects (`#1537 <https://github.com/OSGeo/PROJ/issues/1537>`_)
diff --git a/docs/source/operations/projections/ob_tran.rst b/docs/source/operations/projections/ob_tran.rst
index 378f1333..3a23259d 100644
--- a/docs/source/operations/projections/ob_tran.rst
+++ b/docs/source/operations/projections/ob_tran.rst
@@ -19,9 +19,10 @@ oblique projection by means of the General Oblique Transformation. The user
 performs the oblique transformation by selecting the oblique projection
 ``+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
-at 45°N and 90°W and use the :ref:`moll` projection. Because the central meridian
+example of the Fairgrieve projection, the latitude and longitude of the North pole
+of the unrotated geographic CRS, :math:`\alpha` and :math:`\beta` respectively,
+expressed in the rotated geographic CRS, are to be placed
+at 45°N and 90°W  and the :ref:`moll` projection is used. Because the central meridian
 of the translated coordinates will follow the :math:`\beta` meridian it is
 necessary to translate the translated system so that the Greenwich meridian
 will pass through the center of the projection by offsetting the central meridian.
@@ -50,11 +51,11 @@ New pole
 
 .. option:: +o_lat_p=<latitude>
 
-    Latitude of new pole for oblique projection.
+    Latitude of the North pole of the unrotated source CRS, expressed in the rotated geographic CRS.
 
 .. option:: +o_lon_p=<longitude>
 
-    Longitude of new pole for oblique projection.
+    Longitude of the North pole of the unrotated source CRS, expressed in the rotated geographic CRS.
 
 Rotate about point
 ................................................................................
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index 823e8fe7..c31c6dce 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -17,3 +17,5 @@ command line applications or the C API that is a part of the software package.
    transformation
    environmentvars
    differences
+   projjson
+
diff --git a/docs/source/usage/projjson.rst b/docs/source/usage/projjson.rst
new file mode 100644
index 00000000..79e87c15
--- /dev/null
+++ b/docs/source/usage/projjson.rst
@@ -0,0 +1,261 @@
+.. _projjson:
+
+================================================================================
+PROJJSON
+================================================================================
+
+PROJJSON is a JSON encoding of
+`WKT2:2019 / ISO-19162:2019 <http://docs.opengeospatial.org/is/18-010r7/18-010r7.html>`_,
+which itself implements the model of
+`OGC Topic 2: Referencing by coordinates <http://docs.opengeospatial.org/as/18-005r4/18-005r4.html>`_.
+Apart from the difference of encodings, the semantics is intended to be exactly
+the same as WKT2:2019.
+
+PROJJSON is available as input and output of PROJ since PROJ 6.2.
+
+The current version is 0.1.
+
+Schema
+------
+
+A JSON schema of its grammar is available at
+https://proj.org/schemas/v0.1/projjson.schema.json
+
+Content
+-------
+
+The high level objects are:
+
+* Coordinate Reference Systems (CRS):
+
+  - Common ones:
+
+    + ``GeographicCRS``
+    + ``GeodeticCRS``
+    + ``ProjectedCRS``
+    + ``CompoundCRS``
+    + ``BoundCRS``
+
+  - More esoteric ones:
+
+    + ``VerticalCRS``
+    + ``EngineeringCRS``
+    + ``TemporalCRS``
+    + ``ParametricCRS``
+    + ``DerivedGeographicCRS``
+    + ``DerivedGeodeticCRS``
+    + ``DerivedProjectedCRS``
+    + ``DerivedVerticalCRS``
+    + ``DerivedEngineeringCRS``
+    + ``DerivedTemporalCRS``
+    + ``DerivedParametricCRS``
+
+* Coordinate operations:
+
+  - ``Transformation``
+  - ``Conversion``
+  - ``ConcatenatedOperation``
+
+* Others:
+
+  - ``PrimeMeridian``
+  - ``Ellipsoid``
+  - ``Datum``
+  - ``DatumEnsemble``
+
+Examples
+--------
+
+GeographicCRS
++++++++++++++
+
+The following invokation
+
+::
+
+    projinfo EPSG:4326 -o PROJJSON -q
+
+will output:
+
+.. code-block:: json
+
+    {
+        "$schema": "https://proj.org/schemas/v0.1/projjson.schema.json",
+        "type": "GeographicCRS",
+        "name": "WGS 84",
+        "datum": {
+            "type": "GeodeticReferenceFrame",
+            "name": "World Geodetic System 1984",
+            "ellipsoid": {
+                "name": "WGS 84",
+                "semi_major_axis": 6378137,
+                "inverse_flattening": 298.257223563
+            }
+        },
+        "coordinate_system": {
+            "subtype": "ellipsoidal",
+            "axis": [
+            {
+                "name": "Geodetic latitude",
+                "abbreviation": "Lat",
+                "direction": "north",
+                "unit": "degree"
+            },
+            {
+                "name": "Geodetic longitude",
+                "abbreviation": "Lon",
+                "direction": "east",
+                "unit": "degree"
+            }
+            ]
+        },
+        "area": "World",
+        "bbox": {
+            "south_latitude": -90,
+            "west_longitude": -180,
+            "north_latitude": 90,
+            "east_longitude": 180
+        },
+        "id": {
+            "authority": "EPSG",
+            "code": 4326
+        }
+    }
+
+
+ProjectedCRS
+++++++++++++
+
+The following invokation
+
+::
+
+    projinfo EPSG:32631 -o PROJJSON -q
+
+will output:
+
+.. code-block:: json
+
+    {
+        "$schema": "https://proj.org/schemas/v0.1/projjson.schema.json",
+        "type": "ProjectedCRS",
+        "name": "WGS 84 / UTM zone 31N",
+        "base_crs": {
+            "name": "WGS 84",
+            "datum": {
+                "type": "GeodeticReferenceFrame",
+                "name": "World Geodetic System 1984",
+                "ellipsoid": {
+                    "name": "WGS 84",
+                    "semi_major_axis": 6378137,
+                    "inverse_flattening": 298.257223563
+                }
+            },
+            "coordinate_system": {
+                "subtype": "ellipsoidal",
+                "axis": [
+                {
+                    "name": "Geodetic latitude",
+                    "abbreviation": "Lat",
+                    "direction": "north",
+                    "unit": "degree"
+                },
+                {
+                    "name": "Geodetic longitude",
+                    "abbreviation": "Lon",
+                    "direction": "east",
+                    "unit": "degree"
+                }
+                ]
+            },
+            "id": {
+                "authority": "EPSG",
+                "code": 4326
+            }
+        },
+        "conversion": {
+            "name": "UTM zone 31N",
+            "method": {
+                "name": "Transverse Mercator",
+                "id": {
+                    "authority": "EPSG",
+                    "code": 9807
+                }
+            },
+            "parameters": [
+            {
+                "name": "Latitude of natural origin",
+                "value": 0,
+                "unit": "degree",
+                "id": {
+                "authority": "EPSG",
+                "code": 8801
+                }
+            },
+            {
+                "name": "Longitude of natural origin",
+                "value": 3,
+                "unit": "degree",
+                "id": {
+                "authority": "EPSG",
+                "code": 8802
+                }
+            },
+            {
+                "name": "Scale factor at natural origin",
+                "value": 0.9996,
+                "unit": "unity",
+                "id": {
+                "authority": "EPSG",
+                "code": 8805
+                }
+            },
+            {
+                "name": "False easting",
+                "value": 500000,
+                "unit": "metre",
+                "id": {
+                "authority": "EPSG",
+                "code": 8806
+                }
+            },
+            {
+                "name": "False northing",
+                "value": 0,
+                "unit": "metre",
+                "id": {
+                "authority": "EPSG",
+                "code": 8807
+                }
+            }
+            ]
+        },
+        "coordinate_system": {
+            "subtype": "Cartesian",
+            "axis": [
+            {
+                "name": "Easting",
+                "abbreviation": "E",
+                "direction": "east",
+                "unit": "metre"
+            },
+            {
+                "name": "Northing",
+                "abbreviation": "N",
+                "direction": "north",
+                "unit": "metre"
+            }
+            ]
+        },
+        "area": "World - N hemisphere - 0°E to 6°E - by country",
+        "bbox": {
+            "south_latitude": 0,
+            "west_longitude": 0,
+            "north_latitude": 84,
+            "east_longitude": 6
+        },
+        "id": {
+            "authority": "EPSG",
+            "code": 32631
+        }
+    }
diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst
index 861e1b4b..a11992cf 100644
--- a/docs/source/usage/transformation.rst
+++ b/docs/source/usage/transformation.rst
@@ -12,7 +12,8 @@ large scale cartographic projections as well as coordinate transformation at a
 geodetic high precision level. This chapter delves into the details of how
 geodetic transformations of varying complexity can be performed.
 
-In PROJ, two frameworks for geodetic transformations exists, the *cs2cs*
+In PROJ, two frameworks for geodetic transformations exists, the
+*PROJ 4.x/5.x* / :program:`cs2cs` / :c:func:`pj_transform`
 framework and the *transformation pipelines* framework. The first is the original,
 and limited, framework for doing geodetic transforms in PROJ The latter is a
 newer addition that aims to be a more complete transformation framework. Both are
@@ -133,7 +134,7 @@ coordinate timestamps back to GPS weeks.
     step proj=unitconvert t_in=decimalyear t_out=gps_week
 
 
-cs2cs paradigm
+PROJ 4.x/5.x paradigm
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 .. _cs2cs_specific_options:
 
@@ -148,9 +149,19 @@ cs2cs paradigm
     +vto_meter     Vertical conversion to meters
     ============   ==============================================================
 
-The *cs2cs* framework delivers a subset of the geodetic transformations available
+.. warning::
+    This section documents the behaviour of PROJ 4.x and 5.x. In PROJ 6.x,
+    :program:`cs2cs` has been reworked to use :c:func:`proj_create_crs_to_crs` internally,
+    with *late binding* capabilities, and thus is no longer constrained to using
+    WGS84 as a pivot (also called as *early binding* method).
+    When :program:`cs2cs` of PROJ 6 is used with PROJ.4 expanded strings to describe the CRS,
+    including ``+towgs84``, ``+nadgrids`` and ``+geoidgrids``, it will generally give
+    the same results as earlier PROJ versions. When used with AUTHORITY:CODE
+    CRS descriptions, it may return different results.
+
+The *cs2cs* framework in PROJ 4 and 5 delivers a subset of the geodetic transformations available
 with the *pipeline* framework. Coordinate transformations done in this framework
-are transformed in a two-step process with WGS84 as a pivot datum That is, the
+were transformed in a two-step process with WGS84 as a pivot datum. That is, the
 input coordinates are transformed to WGS84 geodetic coordinates and then transformed
 from WGS84 coordinates to the specified output coordinate reference system, by
 utilizing either the Helmert transform, datum shift grids or a combination of both.
@@ -173,7 +184,7 @@ Both grid correction methods allow inclusion of more than one grid in the same
 transformation
 
 In contrast to the *transformation pipeline* framework, transformations with the
-*cs2cs* framework are expressed as two separate proj-strings. One proj-string *to*
+*cs2cs* framework in PROJ 4 and 5 were expressed as two separate proj-strings. One proj-string *to*
 WGS84 and one *from* WGS84. Together they form the mapping from the source
 coordinate reference system to the destination coordinate reference system.
 When used with the ``cs2cs`` the source and destination CRS's are separated by the
@@ -189,6 +200,21 @@ to WGS84 with the ``+towgs84`` parameter.
     20 35
     20d0'5.467"E    35d0'9.575"N 0.000
 
+With PROJ 6, you can simply use the following:
+
+.. note:: With PROJ 6, the order of coordinates for EPSG geographic coordinate
+          reference systems is latitude first, longitude second.
+
+::
+
+    cs2cs "GGRS87" "WGS 84"
+    35 20
+    35d0'9.575"N	20d0'5.467"E 0.000
+
+    cs2cs EPSG:4121 EPSG:4326
+    35 20
+    35d0'9.575"N	20d0'5.467"E 0.000
+
 The EPSG database provides this example for transforming from WGS72 to WGS84
 using an approximated 7 parameter transformation.
 
@@ -199,6 +225,19 @@ using an approximated 7 parameter transformation.
     4 55
     4d0'0.554"E     55d0'0.09"N 0.000
 
+With PROJ 6, you can simply use the following (note the reversed order for
+latitude and longitude)
+
+::
+
+    cs2cs "WGS 72" "WGS 84"
+    55 4
+    55d0'0.09"N	4d0'0.554"E 0.000
+
+    cs2cs EPSG:4322 EPSG:4326
+    55 4
+    55d0'0.09"N	4d0'0.554"E 0.000
+
 
 Grid Based Datum Adjustments
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -266,8 +305,8 @@ fallback to using the ``ntv1_can.dat`` file.
 The null Grid
 ................................................................................
 
-A special ``null`` grid shift file is shift with releases after 4.4.6 (not
-inclusive).  This file provides a zero shift for the whole world.  It may be
+A special ``null`` grid shift file is distributed with PROJ.
+This file provides a zero shift for the whole world.  It may be
 listed at the end of a nadgrids file list if you want a zero shift to be
 applied to points outside the valid region of all the other grids.  Normally if
 no grid is found that contains the point to be transformed an error will occur.
@@ -301,13 +340,7 @@ Caveats
   Careful selection of files and file order is necessary.  In some cases
   border spanning datasets may need to be pre-segmented into Canadian and
   American points so they can be properly grid shifted
-* There are additional grids for shifting between NAD83 and various HPGN
-  versions of the NAD83 datum.  Use of these haven't been tried recently so
-  you may encounter problems.  The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla
-  are examples of high precision grid shifts.  Take care!
 * Additional detail on the grid shift being applied can be found by setting
   the PROJ_DEBUG environment variable to a value.  This will result in output
   to stderr on what grid is used to shift points, the bounds of the various
   grids loaded and so forth
-* The *cs2cs* framework always assumes that grids contain a shift **to**  NAD83 (essentially
-  WGS84). Other types of grids can be used with the *pipeline* framework.
author	Kristian Evers <kristianevers@gmail.com>	2019-11-28 14:58:14 +0100
committer	Kristian Evers <kristianevers@gmail.com>	2019-11-28 14:58:14 +0100
commit	ac2762b581918dd3fcecf2a4d0dd72f92ca87011 (patch)
tree	d0158eb03d39b9d2249a30ea88f333c8e560f351 /docs/source
parent	2bc1e2e1a9d0a7abe410ee99d39236570474cfde (diff)
parent	bce4b158ab5f7d146de8e8fc98df4612dc8c2c9e (diff)
download	PROJ-ac2762b581918dd3fcecf2a4d0dd72f92ca87011.tar.gz PROJ-ac2762b581918dd3fcecf2a4d0dd72f92ca87011.zip