From fc769bbd9a4fb61e96e500788d24d1d12019a4d0 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Tue, 29 Oct 2019 23:34:59 +0100 Subject: news.rst: fix hyperlink --- docs/source/news.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/news.rst b/docs/source/news.rst index 2a6e8e47..1fba43b9 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 `_) + * Introduced PROJJSON, a JSON encoding of WKT2 (`#1547 `_) * Support CRS instantiation of OGC URN's (`#1505 `_) * Expose scope and remarks of database objects (`#1537 `_) -- cgit v1.2.3 From 6ce8ef30389480b3fabc3991bdf2b476d9435b60 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Wed, 30 Oct 2019 16:22:17 +0100 Subject: Document PROJJSON More could probably be written, but at least this can serve as a landing/reference page for other documents/specifications to point to. --- docs/source/news.rst | 2 +- docs/source/usage/index.rst | 2 + docs/source/usage/projjson.rst | 261 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 264 insertions(+), 1 deletion(-) create mode 100644 docs/source/usage/projjson.rst (limited to 'docs/source') 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 `_) + * Introduced :ref:`PROJJSON`, a JSON encoding of WKT2 (`#1547 `_) * Support CRS instantiation of OGC URN's (`#1505 `_) * Expose scope and remarks of database objects (`#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 `_, +which itself implements the model of +`OGC Topic 2: Referencing by coordinates `_. +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 + } + } -- cgit v1.2.3 From 1920c5cee79f258a69f1000124fd6fbde20f1490 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Wed, 30 Oct 2019 17:41:10 +0100 Subject: Doc: add a redirects extension, and make a projjson.html redirect at the top to its current location --- docs/source/_extensions/redirects.py | 39 ++++++++++++++++++++++++++++++++++++ docs/source/conf.py | 5 +++++ 2 files changed, 44 insertions(+) create mode 100644 docs/source/_extensions/redirects.py (limited to 'docs/source') 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=""" + + + + +""" + + +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() -- cgit v1.2.3