From 0d962162010bc736379e3bca84996e97cb84376d Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Wed, 30 Oct 2019 15:22:17 +0000 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/usage/index.rst | 2 + docs/source/usage/projjson.rst | 261 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 263 insertions(+) create mode 100644 docs/source/usage/projjson.rst (limited to 'docs/source/usage') 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 2637f3c52c4d4d7d6a5b02fdac3bdb278d75698e Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sun, 3 Nov 2019 15:04:19 +0000 Subject: Doc: fixes in usage/transformation.rst - Section about cs2cs no longer applies to PROJ 6. Ammended to underline that. - Remove no longer relevant/unclear caveats. --- docs/source/usage/transformation.rst | 59 ++++++++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 13 deletions(-) (limited to 'docs/source/usage') diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst index 861e1b4b..c9c16b3e 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. -- cgit v1.2.3 From da5bd4b7046efd78237dc209d53a3f542c3b3a12 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 5 Nov 2019 08:22:43 +0100 Subject: Doc: fix formatting in usage/transformation.rst --- docs/source/usage/transformation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/usage') diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst index c9c16b3e..a11992cf 100644 --- a/docs/source/usage/transformation.rst +++ b/docs/source/usage/transformation.rst @@ -13,7 +13,7 @@ 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 -*PROJ 4.x/5.x :program:`cs2cs` / :c:func:`pj_transform`* +*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 -- cgit v1.2.3 From e4045d66ec97bc010aff757e708f55e738a13c50 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Thu, 21 Nov 2019 21:16:20 +0100 Subject: projjson.rst: typo fix --- docs/source/usage/projjson.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/usage') diff --git a/docs/source/usage/projjson.rst b/docs/source/usage/projjson.rst index 09123711..79e87c15 100644 --- a/docs/source/usage/projjson.rst +++ b/docs/source/usage/projjson.rst @@ -8,7 +8,7 @@ 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 +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. -- cgit v1.2.3