Merge pull request #1228 from rouault/cs2cs_doc_update

Doc: update cs2cs, C API regarding area of use (fixes #1186), add doc for projinfo (fixes #1183)

8 files changed, 431 insertions, 32 deletions

diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst
index 25611597..249d523a 100644
--- a/docs/source/apps/cct.rst
+++ b/docs/source/apps/cct.rst
@@ -179,7 +179,7 @@ Hence, in honour of *cct* (the geodesist) this is :program:`cct` (the program).
     See also
     ********
 
-    **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)**
+    **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
index 29ea5b42..8df67d72 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/apps/cs2cs.rst
@@ -6,19 +6,35 @@ cs2cs
 
 .. only:: html
 
-    Cartographic coordinate system filter.
+    Filter for transformations between two coordinate reference systems.
 
 Synopsis
 ********
 
     **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s]
 
+or
+
+    **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} +to {target_crs} file[s]
+
+    where {source_crs} or {target_crs} is a PROJ string, a WKT string or a AUTHORITY:CODE
+    (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS
+    found in the proj.db database), expressing a coordinate reference system.
+
+.. versionadded:: 6.0.0
+
+or
+
+    **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} {target_crs}
+
+.. versionadded:: 6.0.0
+
 Description
 ***********
 
 :program:`cs2cs` performs transformation between the source and destination
-cartographic coordinate system on a set of input points. The coordinate
-system transformation can include translation between projected and
+cartographic coordinate reference system on a set of input points. The coordinate
+reference system transformation can include translation between projected and
 geographic coordinates as well as the application of datum shifts.
 
 The following control parameters can appear in any order:
@@ -125,22 +141,21 @@ The following control parameters can appear in any order:
     parameters. Usage varies with projection and for a complete description
     consult the :ref:`projection pages <projections>`.
 
-The :program:`cs2cs` program requires two coordinate system definitions. The first (or
+The :program:`cs2cs` program requires two coordinate reference system (CRS) definitions. The first (or
 primary is defined based on all projection parameters not appearing after the
 *+to* argument. All projection parameters appearing after the *+to* argument
-are considered the definition of the second coordinate system. If there is no
-second coordinate system defined, a geographic coordinate system based on the
-datum and ellipsoid of the source coordinate system is assumed. Note that the
-source and destination coordinate system can both be projections, both be
-geographic, or one of each and may have the same or different datums.
-
-Additional projection control parameters may be contained in two auxiliary
-control files: the first is optionally referenced with the
-*+init=file:id* and the second is always processed after the name of the
-projection has been established from either the run-line or the contents of
-*+init* file. The environment parameter :envvar:`PROJ_LIB` establishes the default
-directory for a file reference without an absolute path. This is also used
-for supporting files like datum shift files.
+are considered the definition of the second CRS. If there is no
+second CRS defined, a geographic CRS based on the
+datum and ellipsoid of the source CRS is assumed. Note that the
+source and destination CRS can both of same or different nature (geographic,
+projected, compound CRS), or one of each and may have the same or different datums.
+
+When using a WKT definition or a AUTHORITY:CODE, the axis order of the CRS will
+be enforced. So for example if using EPSG:4326, the first value expected (or
+returned) will be a latitude.
+
+The environment parameter :envvar:`PROJ_LIB` establishes the
+directory for resource files (database, datum shift grids, etc.)
 
 One or more files (processed in left to right order) specify the source of
 data to be transformed. A ``-`` will specify the location of processing standard
@@ -157,8 +172,11 @@ places), while projected (cartesian) coordinates will be in linear
 (meter, feet) units.
 
 
-Example
-*******
+Examples
+********
+
+Using PROJ strings
+------------------
 
 The following script
 
@@ -179,12 +197,30 @@ The x-y output data will appear as three lines of:
 
     1402285.98  5076292.42 -0.00
 
+
+Using EPSG codes
+----------------
+
+Transforming from WGS 84 latitude/longitude (in that order) to UTM Zone 31N/WGS 84
+
+::
+
+    cs2cs EPSG:4326 EPSG:32631 <<EOF
+    45N 2E
+    EOF
+
+outputs
+
+::
+
+    421184.70   4983436.77 0.00
+
 .. only:: man
 
     See also
     ********
 
-    **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**
+    **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst
index 91f5c4ff..8c2c8222 100644
--- a/docs/source/apps/index.rst
+++ b/docs/source/apps/index.rst
@@ -8,15 +8,18 @@ Bundled with PROJ comes a set of small command line utilities. The ``proj``
 program is limited to converting between geographic and projection coordinates
 within one datum. The ``cs2cs`` program operates similarly, but allows
 translation between any pair of definable coordinate systems, including support
-for basic datum translation. The ``geod`` program provides the ability to do
+for datum transformation. The ``geod`` program provides the ability to do
 geodesic (great circle) computations. ``gie`` is the program used for
-regression tests in PROJ.
+regression tests in PROJ. ``cct`` a 4D equivalent to the ``proj`` program,
+performs transformation coordinate systems on a set of input points.
+``projinfo`` performs queries for geodetic objects and coordinate operations.
 
 .. toctree::
    :maxdepth: 1
 
-   proj
    cct
    cs2cs
    geod
    gie
+   proj
+   projinfo
diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst
index 2928193c..7585411f 100644
--- a/docs/source/apps/proj.rst
+++ b/docs/source/apps/proj.rst
@@ -218,7 +218,7 @@ data will appear as three lines of::
     See also
     ********
 
-    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**
+    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst
new file mode 100644
index 00000000..cbfd44d4
--- /dev/null
+++ b/docs/source/apps/projinfo.rst
@@ -0,0 +1,311 @@
+.. _projinfo:
+
+================================================================================
+projinfo
+================================================================================
+
+.. Index:: projinfo
+
+.. only:: html
+
+    .. versionadded:: 6.0.0
+
+    Geodetic object and coordinate operation queries
+
+Synopsis
+********
+
+    | **projinfo**
+    |    [-o formats] [-k crs|operation] [--summary] [-q]
+    |    [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]]
+    |    [--spatial-test contains|intersects]
+    |    [--crs-extent-use none|both|intersection|smallest]
+    |    [--grid-check none|discard_missing|sort] [--show-superseded]
+    |    [--pivot-crs none|{auth:code[,auth:code]*}]
+    |    [--boundcrs-to-wgs84]
+    |    [--main-db-path path] [--aux-db-path path]*
+    |    [--identify]
+    |    [--c-ify] [--single-line]
+    |    {object_definition} | (-s {srs_def} -t {srs_def})
+    |
+
+    where {object_definition} or {object_definition} is a PROJ string, a
+    WKT string, an object name or a AUTHORITY:CODE
+    (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS
+    found in the proj.db database).
+
+Description
+***********
+
+:program:`projinfo` is a program that can query information on a geodetic object,
+coordinate reference system (CRS) or coordinate operation, when the ``-s`` and ``-t``
+options are specified, and display it under different formats (PROJ string, WKT string).
+
+It can also be used to query coordinate operations available between two CRS.
+
+The program is named with some reference to the GDAL :program:`gdalsrsinfo` that offers
+partly similar services.
+
+
+The following control parameters can appear in any order:
+
+.. program:: projinfo
+
+.. option:: -o formats
+
+    formats is a comma separated combination of:
+    ``all``, ``default``, ``PROJ``, ``WKT_ALL``, ``WKT2_2015``, ``WKT2_2018``, ``WKT1_GDAL``, ``WKT1_ESRI``.
+
+    Except ``all`` and ``default``, other formats can be preceded by ``-`` to disable them.
+
+.. option:: -k crs|operation
+
+    When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object
+    in case there are CRS or coordinate operations with the same CODE.
+    The default is crs.
+
+.. option:: --summary
+
+    When listing coordinate operations available between 2 CRS, return the
+    result in a summary format, mentionning only the name of the coordinate
+    operation, its accuracy and its area of use.
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: -q
+
+    Turn on quiet mode. Quiet mode is only available for queries on single objects,
+    and only one output format is selected. In that mode, only the PROJ or WKT
+    string is displayed, without other introduction output. The output is then
+    potentially compatible of being piped in other utilities.
+
+.. option:: --area name_or_code
+
+    Specify an area of interest to restrict the results when researching
+    coordinate operations between 2 CRS. The area of interest can be specified either
+    as a name (e.g "Denmark - onshore") or a AUTHORITY:CODE (EPSG:3237)
+    This option is exclusive of :option:`--bbox`.
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: --bbox west_long,south_lat,east_long,north_lat
+
+    Specify an area of interest to restrict the results when researching
+    coordinate operations between 2 CRS. The area of interest is specified as a
+    bounding box with geographic coordinates, expressed in degrees in a
+    unspecified geographic CRS.
+    `west_long` and `east_long` should be in the [-180,180] range, and
+    `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than
+    `east_long`, except in the case where the area of interest crosses the antimeridian.
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: --spatial-test contains|intersects
+
+    Specify how the area of use of coordinate operations found in the database
+    are compared to the area of use specfied explicitly with :option:`--area` or :option:`--bbox`,
+    or derivedi implictly from the area of use of the source and target CRS.
+    By default, projinfo will only keep coordinate operations whose are of use
+    is strictly within the area of interest (``contains`` strategy).
+    If using the ``intersects`` strategy, the spatial test is relaxed, and any
+    coordinate operation whose area of use at least partly intersects the
+    area of interest is listed.
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: --crs-extent-use none|both|intersection|smallest
+
+    Specify which area of interest to consider when no explicit one is specified
+    with :option:`--area` or :option:`--bbox` options.
+    By default (``smallest`` strategy), the area of
+    use of the source or target CRS will be looked, and the one that is the
+    smallest one in terms of area will be used as the area of interest.
+    If using ``none``, no area of interest is used.
+    If using ``both``, only coordinate operations that relate (contain or intersect
+    depending of the :option:`--spatial-test` strategy) to the area of use of both CRS
+    are selected.
+    If using ``intersection``, the area of interest is the intersection of the
+    bounding box of the area of use of the source and target CRS
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: --grid-check none|discard_missing|sort
+
+    Specify how the presence or absence of a horizontal or vertical shift grid
+    required for a coordinate operation affects the results returned when
+    researching coordinate operations between 2 CRS.
+    The default strategy is ``sort``: in that case, all candidate
+    operations are returned, but the actual availability of the grids is used
+    to determine the sorting order. That is, if a coordinate operation involves
+    using a grid that is not available in the PROJ resource directories
+    (determined by the :envvar:`PROJ_LIB` environment variable, it will be listed in
+    the bottom of the results.
+    The ``none`` strategy completely disables the checks of presence of grids and
+    this returns the results as if all the grids where available.
+    The ``discard_missing`` strategy discards results that involve grids not
+    present in the PROJ resource directories.
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: -show-superseded
+
+    When enabled, coordinate operations that are superseded by others will be
+    listed. Note that supersession is not equivalent to deprecation: superseded
+    operations are still considered valid although they have a better equivalent,
+    whereas deprecated operations have been determined to be erroneous and are
+    not considered at all.
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: --pivot-crs none|{auth:code[,auth:code]*}
+
+    Determine if intermediate (pivot) CRS can be used when researching coordinate
+    operation between 2 CRS. A typical example is the WGS84 pivot. By default,
+    projinfo will consider any potential pivot. If using the ``none`` strategy,
+    only direct transformations between the source and target CRS will be
+    used. It is also possible to restrict the pivot CRS to consider by specifying
+    one or several CRS by their AUTHORITY:CODE.
+
+    .. note:: only used for coordinate operation computation
+
+.. option:: --boundcrs-to-wgs84
+
+    When specified, this option researches a coordinate operation from the
+    base geographic CRS of the single CRS, source or target CRS to the WGS84
+    geographic CRS, and if found, wraps those CRS into a BoundCRS object.
+    This is mostly to be used for early-binding approaches.
+
+.. option:: --main-db-path path
+
+    Specify the name and path of the database to be used by projinfo. The
+    default is proj.db in the PROJ resource directories.
+
+.. option:: --aux-db-path path
+
+    Specify the name and path of auxiliary databases, that are to be combined
+    with the main database. Those auxiliary databases must have a table
+    structure that is identical to the main database, but can be partly filled
+    and their entries can refer to entries of the main database.
+    The option may be repeated to specify several auxiliary databases.
+
+.. option:: --c-ify
+
+    For developers only. Modify the string output of the utility so that it
+    is easy to put those strings in C/C++ code
+
+.. option:: --single-line
+
+    Output WKT strings on a single line, instead of multiple intended lines by
+    default.
+
+Examples
+********
+
+1. Query the CRS object corresponding to EPSG:4326
+
+.. code-block:: console
+
+      projinfo EPSG:4326
+
+Output:
+
+::
+
+    PROJ.4 string:
+    +proj=longlat +datum=WGS84 +no_defs +type=crs
+
+    WKT2_2018 string:
+    GEOGCRS["WGS 84",
+        DATUM["World Geodetic System 1984",
+            ELLIPSOID["WGS 84",6378137,298.257223563,
+                LENGTHUNIT["metre",1]]],
+        PRIMEM["Greenwich",0,
+            ANGLEUNIT["degree",0.0174532925199433]],
+        CS[ellipsoidal,2],
+            AXIS["geodetic latitude (Lat)",north,
+                ORDER[1],
+                ANGLEUNIT["degree",0.0174532925199433]],
+            AXIS["geodetic longitude (Lon)",east,
+                ORDER[2],
+                ANGLEUNIT["degree",0.0174532925199433]],
+        USAGE[
+            SCOPE["unknown"],
+            AREA["World"],
+            BBOX[-90,-180,90,180]],
+        ID["EPSG",4326]]
+
+
+2. List the coordinate operations between NAD27 (designed with its CRS name)
+   and NAD83 (designed with its EPSG code 4269) within an area of interest
+
+.. code-block:: console
+
+        projinfo -s NAD27 -t EPSG:4269 --area "USA - Missouri"
+
+Output:
+
+::
+
+    DERIVED_FROM(EPSG):1241, NAD27 to NAD83 (1), 0.15 m, USA - CONUS including EEZ
+
+    PROJ string:
+    +proj=pipeline +step +proj=axisswap +order=2,1 +step +proj=unitconvert \
+    +xy_in=deg +xy_out=rad +step +proj=hgridshift +grids=conus \
+    +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1
+
+    WKT2_2018 string:
+    COORDINATEOPERATION["NAD27 to NAD83 (1)",
+        SOURCECRS[
+            GEOGCRS["NAD27",
+                DATUM["North American Datum 1927",
+                    ELLIPSOID["Clarke 1866",6378206.4,294.978698213898,
+                        LENGTHUNIT["metre",1]]],
+                PRIMEM["Greenwich",0,
+                    ANGLEUNIT["degree",0.0174532925199433]],
+                CS[ellipsoidal,2],
+                    AXIS["geodetic latitude (Lat)",north,
+                        ORDER[1],
+                        ANGLEUNIT["degree",0.0174532925199433]],
+                    AXIS["geodetic longitude (Lon)",east,
+                        ORDER[2],
+                        ANGLEUNIT["degree",0.0174532925199433]]]],
+        TARGETCRS[
+            GEOGCRS["NAD83",
+                DATUM["North American Datum 1983",
+                    ELLIPSOID["GRS 1980",6378137,298.257222101,
+                        LENGTHUNIT["metre",1]]],
+                PRIMEM["Greenwich",0,
+                    ANGLEUNIT["degree",0.0174532925199433]],
+                CS[ellipsoidal,2],
+                    AXIS["geodetic latitude (Lat)",north,
+                        ORDER[1],
+                        ANGLEUNIT["degree",0.0174532925199433]],
+                    AXIS["geodetic longitude (Lon)",east,
+                        ORDER[2],
+                        ANGLEUNIT["degree",0.0174532925199433]]]],
+        METHOD["CTABLE2"],
+        PARAMETERFILE["Latitude and longitude difference file","conus"],
+        OPERATIONACCURACY[0.15],
+        USAGE[
+            SCOPE["unknown"],
+            AREA["USA - CONUS including EEZ"],
+            BBOX[23.81,-129.17,49.38,-65.69]],
+        ID["DERIVED_FROM(EPSG)",1241]]
+
+.. only:: man
+
+    See also
+    ********
+
+    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**
+
+    Bugs
+    ****
+
+    A list of know bugs can be found at https://github.com/OSGeo/proj.4/issues
+    where new bug reports can be submitted to.
+
+    Home page
+    *********
+
+    https://proj4.org/
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 612c7c7e..0fd8d540 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -319,6 +319,13 @@ man_pages = [
         ['Thomas Knudsen'],
         1
     ),
+    (
+        'apps/projinfo',
+        'projinfo',
+        u'Geodetic object and coordinate operation queries',
+        ['Even Rouault'],
+        1
+    ),
 ]
 
 # If true, show URL addresses after external links.
diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst
index 25e7ffd2..18bd7efd 100644
--- a/docs/source/development/reference/datatypes.rst
+++ b/docs/source/development/reference/datatypes.rst
@@ -60,11 +60,12 @@ Transformation objects
 
 .. c:type:: PJ_AREA
 
+    .. versionadded:: 6.0.0
+
     Opaque object describing an area in which a transformation is performed.
 
-    .. note:: This object is not fully implemented yet. It is to be used with
-              :c:func:`proj_create_crs_to_crs` to select the best transformation
-              between the two input coordinate reference systems.
+    It is used with :c:func:`proj_create_crs_to_crs` to select the best transformation
+    between the two input coordinate reference systems.
 
 2 dimensional coordinates
 --------------------------------------------------------------------------------
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index aa548664..87271117 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -127,10 +127,10 @@ paragraph for more details.
     The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`.
 
     :param PJ_CONTEXT* ctx: Threading context.
-    :param `srid_from`: Source SRID.
-    :type `srid_from`: const char*
-    :param `srid_to`: Destination SRID.
-    :type `srid_to`: const char*
+    :param `source_crs`: Source CRS.
+    :type `source_crs`: const char*
+    :param `target_crs`: Destination SRS.
+    :type `target_crs`: const char*
     :param `area`: Descriptor of the desired area for the transformation.
     :type `area`: PJ_AREA
     :returns: :c:type:`PJ*`
@@ -142,6 +142,45 @@ paragraph for more details.
     :param PJ* P:
     :returns: :c:type:`PJ*`
 
+Area of interest
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. versionadded:: 6.0.0
+
+
+.. c:function:: PJ_AREA* proj_area_create(void)
+
+    Create an area of use.
+
+    Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to
+    specify the area of use for the choice of relevant coordinate operations.
+
+    :returns: :c:type:`PJ_AREA*` to be deallocated with :c:func:`proj_area_destroy`
+
+
+.. c:function:: void proj_area_set_bbox(PJ_AREA *area, double west_lon_degree, double south_lat_degree, double east_lon_degree, double north_lat_degree)
+
+    Set the bounding box of the area of use
+
+    Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to
+    specify the area of use for the choice of relevant coordinate operations.
+
+    In the case of an area of use crossing the antimeridian (longitude +/- 180 degrees),
+    `west_lon_degree` will be greater than `east_lon_degree`.
+
+    :param `area`: Pointer to an object returned by :c:func:`proj_area_create`.
+    :param `west_lon_degree`: West longitude, in degrees. In [-180,180] range.
+    :param `south_lat_degree`: South latitude, in degrees. In [-90,90] range.
+    :param `east_lon_degree`: East longitude, in degrees. In [-180,180] range.
+    :param `north_lat_degree`: North latitude, in degrees. In [-90,90] range.
+
+.. c:function:: void proj_area_destroy(PJ_AREA* area)
+
+    Deallocate a :c:type:`PJ_AREA` object.
+
+    :param PJ_AREA* area
+
+
 .. _coord_trans_functions:
 
 Coordinate transformation
@@ -604,6 +643,8 @@ Various
 C API for ISO-19111 functionality
 +++++++++++++++++++++++++++++++++
 
+.. versionadded:: 6.0.0
+
 The PJ* objects returned by :c:func:`proj_create_from_wkt`,
 :c:func:`proj_create_from_database` and other functions in that section
 will have generally minimal interaction with the functions declared in the