From a234207957043503814a6a3eebc497d2e471dda3 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Fri, 12 Mar 2021 23:18:35 +0100 Subject: projinfo: add a '-o SQL --output-id AUTH:CODE' SQL output --- docs/source/apps/projinfo.rst | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) (limited to 'docs/source/apps') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index 826cd244..c7a56689 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -27,6 +27,7 @@ Synopsis | [--boundcrs-to-wgs84] | [--main-db-path path] [--aux-db-path path]* | [--identify] [--3d] + | [--output-id AUTH:CODE] | [--c-ify] [--single-line] | --searchpaths | --remote-data | {object_definition} | | {object_reference} | (-s {srs_def} -t {srs_def}) @@ -78,7 +79,7 @@ The following control parameters can appear in any order: .. option:: -o formats formats is a comma separated combination of: - ``all``, ``default``, ``PROJ``, ``WKT_ALL``, ``WKT2:2015``, ``WKT2:2019``, ``WKT1:GDAL``, ``WKT1:ESRI``, ``PROJJSON``. + ``all``, ``default``, ``PROJ``, ``WKT_ALL``, ``WKT2:2015``, ``WKT2:2019``, ``WKT1:GDAL``, ``WKT1:ESRI``, ``PROJJSON``, ``SQL``. Except ``all`` and ``default``, other formats can be preceded by ``-`` to disable them. @@ -87,6 +88,8 @@ The following control parameters can appear in any order: .. note:: Before PROJ 6.3.0, WKT1:GDAL was implicitly calling --boundcrs-to-wgs84. This is no longer the case. + .. note:: When SQL is specified, :option:`--output-id` must be specified. + .. option:: -k crs|operation|datum|ensemble|ellipsoid When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object @@ -271,6 +274,12 @@ The following control parameters can appear in any order: automatically promoted to a 3D version, where its vertical axis is the ellipsoidal height in metres, using the ellipsoid of the base geodetic CRS. +.. option:: --output-id=AUTH:NAME + + .. versionadded:: 8.1 + + Identifier to assign to the object (for SQL output). + .. option:: --c-ify For developers only. Modify the string output of the utility so that it @@ -442,6 +451,24 @@ Output: } } +4. Exporting the SQL statements to insert a new CRS in the database. + +.. code-block:: console + + projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs" --output-id HOBU:MY_CRS -o SQL -q + +Output: + +.. code-block:: sql + + INSERT INTO geodetic_crs VALUES('HOBU','GEODETIC_CRS_MY_CRS','unknown','','geographic 2D','EPSG','6424','EPSG','6326',NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_GEODETIC_CRS_MY_CRS','geodetic_crs','HOBU','GEODETIC_CRS_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + INSERT INTO conversion VALUES('HOBU','CONVERSION_MY_CRS','unknown','','EPSG','9805','Mercator (variant B)','EPSG','8823','Latitude of 1st standard parallel',5,'EPSG','9122','EPSG','8802','Longitude of natural origin',0,'EPSG','9122','EPSG','8806','False easting',0,'EPSG','9001','EPSG','8807','False northing',0,'EPSG','9001',NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_CONVERSION_MY_CRS','conversion','HOBU','CONVERSION_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + INSERT INTO projected_crs VALUES('HOBU','MY_CRS','unknown','','EPSG','4400','HOBU','GEODETIC_CRS_MY_CRS','HOBU','CONVERSION_MY_CRS',NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_PROJECTED_CRS_MY_CRS','projected_crs','HOBU','MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + + .. only:: man -- cgit v1.2.3 From 8a67a3fb96ffdb29887b2954dd4bb8af92f6960d Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 13 Mar 2021 11:46:08 +0100 Subject: SQL output: add capability to restrict the authorities into which to look for intermediate objects --- docs/source/apps/projinfo.rst | 72 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 69 insertions(+), 3 deletions(-) (limited to 'docs/source/apps') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index c7a56689..34df3bca 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -25,6 +25,7 @@ Synopsis | [--show-superseded] [--hide-ballpark] [--accuracy {accuracy}] | [--allow-ellipsoidal-height-as-vertical-crs] | [--boundcrs-to-wgs84] + | [--authority name] | [--main-db-path path] [--aux-db-path path]* | [--identify] [--3d] | [--output-id AUTH:CODE] @@ -240,6 +241,16 @@ The following control parameters can appear in any order: geographic CRS, and if found, wraps those CRS into a BoundCRS object. This is mostly to be used for early-binding approaches. +.. option:: --authority name + + Specify the name of the authority into which to restrict looks up for + objects, when specifying an object by name or when coordinate operations are + computed. The default is to allow all authorities. + + When used with SQL output, this restricts the authorities to which intermediate + objects can belong to (the default is EPSG and PROJ). Note that the authority + of the :option:`--output-id` option will also be implicitly added. + .. option:: --main-db-path path Specify the name and path of the database to be used by projinfo. The @@ -451,11 +462,22 @@ Output: } } -4. Exporting the SQL statements to insert a new CRS in the database. +4. Exporting the SQL statements to insert a new CRS in an auxiliary database. .. code-block:: console - projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs" --output-id HOBU:MY_CRS -o SQL -q + # Get the SQL statements for a custom CRS + projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs +title=my_crs" --output-id HOBU:MY_CRS -o SQL -q > my_crs.sql + cat my_crs.sql + + # Initialize an auxiliary database with the schema of the reference database + echo ".schema" | sqlite3 /path/to/proj.db | sqlite3 aux.db + + # Append the content of the definition of HOBU:MY_CRS + sqlite3 aux.db < my_crs.db + + # Check that everything works OK + projinfo --aux-db-path aux.db HOBU:MY_CRS Output: @@ -465,9 +487,53 @@ Output: INSERT INTO usage VALUES('HOBU','USAGE_GEODETIC_CRS_MY_CRS','geodetic_crs','HOBU','GEODETIC_CRS_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); INSERT INTO conversion VALUES('HOBU','CONVERSION_MY_CRS','unknown','','EPSG','9805','Mercator (variant B)','EPSG','8823','Latitude of 1st standard parallel',5,'EPSG','9122','EPSG','8802','Longitude of natural origin',0,'EPSG','9122','EPSG','8806','False easting',0,'EPSG','9001','EPSG','8807','False northing',0,'EPSG','9001',NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,0); INSERT INTO usage VALUES('HOBU','USAGE_CONVERSION_MY_CRS','conversion','HOBU','CONVERSION_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); - INSERT INTO projected_crs VALUES('HOBU','MY_CRS','unknown','','EPSG','4400','HOBU','GEODETIC_CRS_MY_CRS','HOBU','CONVERSION_MY_CRS',NULL,0); + INSERT INTO projected_crs VALUES('HOBU','MY_CRS','my_crs','','EPSG','4400','HOBU','GEODETIC_CRS_MY_CRS','HOBU','CONVERSION_MY_CRS',NULL,0); INSERT INTO usage VALUES('HOBU','USAGE_PROJECTED_CRS_MY_CRS','projected_crs','HOBU','MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); +:: + + PROJ.4 string: + +proj=merc +lat_ts=5 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs +type=crs + + WKT2:2019 string: + PROJCRS["my_crs", + BASEGEOGCRS["unknown", + ENSEMBLE["World Geodetic System 1984 ensemble", + MEMBER["World Geodetic System 1984 (Transit)"], + MEMBER["World Geodetic System 1984 (G730)"], + MEMBER["World Geodetic System 1984 (G873)"], + MEMBER["World Geodetic System 1984 (G1150)"], + MEMBER["World Geodetic System 1984 (G1674)"], + MEMBER["World Geodetic System 1984 (G1762)"], + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]], + ENSEMBLEACCURACY[2.0]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + ID["HOBU","GEODETIC_CRS_MY_CRS"]], + CONVERSION["unknown", + METHOD["Mercator (variant B)", + ID["EPSG",9805]], + PARAMETER["Latitude of 1st standard parallel",5, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8823]], + PARAMETER["Longitude of natural origin",0, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8802]], + PARAMETER["False easting",0, + LENGTHUNIT["metre",1], + ID["EPSG",8806]], + PARAMETER["False northing",0, + LENGTHUNIT["metre",1], + ID["EPSG",8807]]], + CS[Cartesian,2], + AXIS["(E)",east, + ORDER[1], + LENGTHUNIT["metre",1]], + AXIS["(N)",north, + ORDER[2], + LENGTHUNIT["metre",1]], + ID["HOBU","MY_CRS"]] .. only:: man -- cgit v1.2.3 From eda2311513a67d274d67f5ae8fb3042d78fe3b96 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 13 Mar 2021 16:48:21 +0100 Subject: projinfo: add a --dump-db-structure switch --- docs/source/apps/projinfo.rst | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'docs/source/apps') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index 34df3bca..bb4f831d 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -27,11 +27,13 @@ Synopsis | [--boundcrs-to-wgs84] | [--authority name] | [--main-db-path path] [--aux-db-path path]* + | [--dump-db-structure] | [--identify] [--3d] | [--output-id AUTH:CODE] | [--c-ify] [--single-line] - | --searchpaths | --remote-data | {object_definition} | - | {object_reference} | (-s {srs_def} -t {srs_def}) + | --searchpaths | --remote-data | + | --dump-db-structure [{object_definition} | {object_reference}] | + | {object_definition} | {object_reference} | (-s {srs_def} -t {srs_def}) | where {object_definition} or {srs_def} is one of the possibilities accepted @@ -274,6 +276,15 @@ The following control parameters can appear in any order: For example, `+proj=utm +zone=31 +datum=WGS84 +type=crs` will be identified with a likelihood of 70% to EPSG:32631 +.. option:: --dump-db-structure + + .. versionadded:: 8.1 + + Outputs the sequence of SQL statements to create a new empty valid auxiliary + database. This option can be specified as the only switch of the utility. + If also specifying a CRS object and the :option:`--output-id` option, the + definition of the object as SQL statements will be appended. + .. option:: --3d .. versionadded:: 6.3 @@ -479,6 +490,16 @@ Output: # Check that everything works OK projinfo --aux-db-path aux.db HOBU:MY_CRS +or more simply: + +.. code-block:: console + + # Create an auxiliary database with the definition of a custom CRS. + projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs +title=my_crs" --output-id HOBU:MY_CRS --dump-db-structure | sqlite3 aux.db + + # Check that everything works OK + projinfo --aux-db-path aux.db HOBU:MY_CRS + Output: .. code-block:: sql -- cgit v1.2.3 From eae06c94dba10640ca2d669c4e7b356a1613f9f3 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Mon, 15 Mar 2021 16:28:37 +0100 Subject: Doc improvements regarding recomandation not to alter official registries and use auxiliary databases --- docs/source/apps/projinfo.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/source/apps') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index bb4f831d..6c090494 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -302,6 +302,20 @@ The following control parameters can appear in any order: Identifier to assign to the object (for SQL output). + It is strongly recommended that new objects should not be added in common + registries, such as ``EPSG``, ``ESRI``, ``IAU``, etc. + Users should use a custom authority name instead. If a new object should be + added to the official EPSG registry, users are invited to follow the + procedure explained at https://epsg.org/dataset-change-requests.html. + + Combined with :option:`--dump-db-structure`, users can create + auxiliary databases, instead of directly modifying the main proj.db database. + See the :ref:`example how to export to an auxiliary database `. + + Those auxiliary databases can be specified through + :cpp:func:`proj_context_set_database_path` or the :envvar:`PROJ_AUX_DB` + environment variable. + .. option:: --c-ify For developers only. Modify the string output of the utility so that it @@ -473,6 +487,8 @@ Output: } } +.. _projinfo_aux_db_example: + 4. Exporting the SQL statements to insert a new CRS in an auxiliary database. .. code-block:: console -- cgit v1.2.3