aboutsummaryrefslogtreecommitdiff
path: root/docs/source
diff options
context:
space:
mode:
authorEven Rouault <even.rouault@spatialys.com>2019-10-31 13:37:48 +0100
committerGitHub <noreply@github.com>2019-10-31 13:37:48 +0100
commitbb3da7f1e4a52f12b6df48f4a427a8772e63ab18 (patch)
treefe1eb0051a9aa19c5bbb179088a9cce9e9dd8ef9 /docs/source
parent67657e7e74f688b73ac039ccd382be69b94b3668 (diff)
parent1920c5cee79f258a69f1000124fd6fbde20f1490 (diff)
downloadPROJ-bb3da7f1e4a52f12b6df48f4a427a8772e63ab18.tar.gz
PROJ-bb3da7f1e4a52f12b6df48f4a427a8772e63ab18.zip
Merge pull request #1701 from rouault/doc_projjson
Document PROJJSON
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/_extensions/redirects.py39
-rw-r--r--docs/source/conf.py5
-rw-r--r--docs/source/news.rst2
-rw-r--r--docs/source/usage/index.rst2
-rw-r--r--docs/source/usage/projjson.rst261
5 files changed, 308 insertions, 1 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/conf.py b/docs/source/conf.py
index 243c93b7..cd004777 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.
@@ -370,3 +372,6 @@ texinfo_documents = [
breathe_projects = {
"cpp_stuff":"../build/xml/",
}
+
+import redirects
+redirect_files = redirects.gather_redirects()
diff --git a/docs/source/news.rst b/docs/source/news.rst
index 1fba43b9..bb8f63f9 100644
--- a/docs/source/news.rst
+++ b/docs/source/news.rst
@@ -10,7 +10,7 @@ News
Updates
-------
- * Introduced PROJJSON, a JSON encoding of WKT2 (`#1547 <https://github.com/OSGeo/PROJ/issues/1547>`_)
+ * 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/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..09123711
--- /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 intented 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
+ }
+ }
generated by cgit v1.2.3 (git 2.25.1) at 2025-12-28 07:29:57 +0000