Merge remote-tracking branch 'osgeo/master'

5 files changed, 161 insertions, 10 deletions

diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
index 7df8890f..4706459a 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/apps/cs2cs.rst
@@ -13,7 +13,7 @@ Synopsis
 
     | **cs2cs** [**-eEfIlrstvwW** [args]]
     |           [[--area <name_or_code>] | [--bbox <west_long,south_lat,east_long,north_lat>]]
-    |           [--authority <name>]
+    |           [--authority <name>] [--no-ballpark] [--accuracy <accuracy>]
     |           ([*+opt[=arg]* ...] [+to *+opt[=arg]* ...] | {source_crs} {target_crs})
     |           file ...
 
@@ -166,6 +166,19 @@ The following control parameters can appear in any order:
     `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.
 
+.. option:: --no-ballpark
+
+    .. versionadded:: 8.0.0
+
+    Disallow any coordinate operation that is, or contains, a
+    :term:`Ballpark transformation`
+
+.. option:: --accuracy <accuracy>
+
+    .. versionadded:: 8.0.0
+
+    Sets the minimum desired accuracy for candidate coordinate operations.
+
 .. option:: --authority <name>
 
     .. versionadded:: 8.0.0
diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst
index 803c0a65..f0f66620 100644
--- a/docs/source/apps/projinfo.rst
+++ b/docs/source/apps/projinfo.rst
@@ -22,7 +22,7 @@ Synopsis
     |    [--crs-extent-use none|both|intersection|smallest]
     |    [--grid-check none|discard_missing|sort|known_available]
     |    [--pivot-crs always|if_no_direct_transformation|never|{auth:code[,auth:code]*}]
-    |    [--show-superseded] [--hide-ballpark]
+    |    [--show-superseded] [--hide-ballpark] [--accuracy {accuracy}]
     |    [--allow-ellipsoidal-height-as-vertical-crs]
     |    [--boundcrs-to-wgs84]
     |    [--main-db-path path] [--aux-db-path path]*
@@ -213,6 +213,14 @@ The following control parameters can appear in any order:
 
     .. note:: only used for coordinate operation computation
 
+.. option:: --accuracy {accuracy}
+
+    .. versionadded:: 8.0
+
+    Sets the minimum desired accuracy for returned coordinate operations.
+
+    .. note:: only used for coordinate operation computation
+
 .. option:: --allow-ellipsoidal-height-as-vertical-crs
 
     .. versionadded:: 8.0
diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst
index 8e0141df..ed219daf 100644
--- a/docs/source/development/reference/datatypes.rst
+++ b/docs/source/development/reference/datatypes.rst
@@ -804,6 +804,102 @@ Info structures
         Date of last update of the init-file.
 
 
+.. _error_codes:
+
+Error codes
+-----------
+
+.. versionadded:: 8.0.0
+
+Three classes of errors are defined below. The belonging of a given error
+code to a class can bit tested with a binary and test. The error class itself
+can be used as an error value in some rare cases where the error does not
+fit into a more precise error value.
+
+Those error codes are still quite generic for a number of them. Details on the
+actual errors will be typically logged with the PJ_LOG_ERROR level.
+
+Errors in class PROJ_ERR_INVALID_OP
++++++++++++++++++++++++++++++++++++
+
+.. c:macro:: PROJ_ERR_INVALID_OP
+
+    Class of error codes typically related to coordinate operation initalization,
+    typically when creating a PJ* object from a PROJ string.
+
+    .. note:: some of them can also be emitted during coordinate transformation,
+              like PROJ_ERR_INVALID_OP_FILE_NOT_FOUND_OR_INVALID in case the resource loading
+              is differed until it is really needed.
+
+.. c:macro:: PROJ_ERR_INVALID_OP_WRONG_SYNTAX
+
+    Invalid pipeline structure, missing +proj argument, etc.
+
+.. c:macro:: PROJ_ERR_INVALID_OP_MISSING_ARG
+
+    Missing required operation parameter
+
+.. c:macro:: PROJ_ERR_INVALID_OP_ILLEGAL_ARG_VALUE
+
+    One of the operation parameter has an illegal value.
+
+.. c:macro:: PROJ_ERR_INVALID_OP_MUTUALLY_EXCLUSIVE_ARGS
+
+    Mutually exclusive arguments
+
+.. c:macro:: PROJ_ERR_INVALID_OP_FILE_NOT_FOUND_OR_INVALID
+
+    File not found or with invalid content (particular case of PROJ_ERR_INVALID_OP_ILLEGAL_ARG_VALUE)
+
+Errors in class PROJ_ERR_COORD_TRANSFM
+++++++++++++++++++++++++++++++++++++++
+
+.. c:macro:: PROJ_ERR_COORD_TRANSFM
+
+    Class of error codes related to transformation on a specific coordinate.
+
+.. c:macro:: PROJ_ERR_COORD_TRANSFM_INVALID_COORD
+
+    Invalid input coordinate. e.g a latitude > 90°.
+
+.. c:macro:: PROJ_ERR_COORD_TRANSFM_OUTSIDE_PROJECTION_DOMAIN
+
+    Coordinate is outside of the projection domain. e.g approximate mercator with \|longitude - lon_0\| > 90°,
+    or iterative convergence method failed.
+
+.. c:macro:: PROJ_ERR_COORD_TRANSFM_NO_OPERATION
+
+    No operation found, e.g if no match the required accuracy, or if ballpark transformations
+    were asked to not be used and they would be only such candidate.
+
+.. c:macro:: PROJ_ERR_COORD_TRANSFM_OUTSIDE_GRID
+
+    Point to transform falls outside grid/subgrid/TIN.
+
+.. c:macro:: PROJ_ERR_COORD_TRANSFM_GRID_AT_NODATA
+
+    Point to transform falls in a grid cell that evaluates to nodata.
+
+Errors in class PROJ_ERR_OTHER
+++++++++++++++++++++++++++++++
+
+.. c:macro:: PROJ_ERR_OTHER
+
+    Class of error codes that do not fit into one of the above class.
+
+.. c:macro:: PROJ_ERR_OTHER_API_MISUSE
+
+    Error related to a misuse of PROJ API.
+
+.. c:macro:: PROJ_ERR_OTHER_NO_INVERSE_OP
+
+    No inverse method available
+
+.. c:macro:: PROJ_ERR_OTHER_NETWORK_ERROR
+
+    Failure when accessing a network resource.
+
+
 Logging
 -------------------------------------------------------------------------------
 
diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst
index b37eacdd..34fe59ed 100644
--- a/docs/source/development/reference/functions.rst
+++ b/docs/source/development/reference/functions.rst
@@ -195,6 +195,11 @@ paragraph for more details.
       If authority is a non-empty string different of ``any``, then coordinate operations
       will be searched only in that authority namespace (e.g ``EPSG``).
 
+    - ACCURACY=value: to set the minimum desired accuracy (in metres) of the
+      candidate coordinate operations.
+
+    - ALLOW_BALLPARK=YES/NO: can be set to NO to disallow the use of
+      :term:`Ballpark transformation` in the candidate coordinate operations.
 
 .. doxygenfunction:: proj_normalize_for_visualization
    :project: doxygen_api
@@ -368,13 +373,22 @@ Coordinate transformation
 
     Batch transform an array of :c:type:`PJ_COORD`.
 
+    Performs transformation on all points, even if errors occur on some points
+    (new to 8.0. Previous versions would exit early in case of failure on a given point)
+
+    Individual points that fail to transform will have their components set to
+    ``HUGE_VAL``
+
     :param P: Transformation object
     :type P: :c:type:`PJ` *
     :param `direction`: Transformation direction.
     :type `direction`: PJ_DIRECTION
     :param n: Number of coordinates in :c:data:`coord`
     :type n: `size_t`
-    :returns: `int` 0 if all observations are transformed without error, otherwise returns error number
+    :returns: `int` 0 if all observations are transformed without error, otherwise returns error number.
+              This error number will be a precise error number if all coordinates that fail to transform
+              for the same reason, or a generic error code if they fail for different
+              reasons.
 
 
 Error reporting
@@ -388,6 +402,8 @@ Error reporting
     context is read. A text representation of the error number can be retrieved
     with :c:func:`proj_errno_string`.
 
+    Consult :ref:`error_codes` for the list of error codes (PROJ >= 8.0)
+
     :param P: Transformation object
     :type P: :c:type:`PJ` *
 
@@ -400,6 +416,8 @@ Error reporting
     transformation. A text representation of the error number can be retrieved
     with :c:func:`proj_errno_string`.
 
+    Consult :ref:`error_codes` for the list of error codes (PROJ >= 8.0)
+
     :param ctx: threading context.
     :type ctx: :c:type:`PJ_CONTEXT` *
 
@@ -464,6 +482,22 @@ Error reporting
 
     Get a text representation of an error number.
 
+    .. deprecated:: This function is potentially thread-unsafe, replaced by :c:func:`proj_context_errno_string`.
+
+    :param err: Error number.
+    :type err: `int`
+
+    :returns: `const char*` String with description of error.
+
+.. c:function:: const char* proj_context_errno_string(PJ_CONTEXT* ctx, int err)
+
+    .. versionadded:: 8.0.0
+
+    Get a text representation of an error number.
+
+    :param ctx: threading context.
+    :type ctx: :c:type:`PJ_CONTEXT` *
+
     :param err: Error number.
     :type err: `int`
 
diff --git a/docs/source/resource_files.rst b/docs/source/resource_files.rst
index ae3a808d..22edbc90 100644
--- a/docs/source/resource_files.rst
+++ b/docs/source/resource_files.rst
@@ -151,7 +151,7 @@ proj-datumgrid
     series of packages are not maintained anymore and are only kept available for
     legacy purposes.
 
-For a functioning builds of PROJ prior to version 7, installation of the
+For a functioning build of PROJ prior to version 7, installation of the
 `proj-datumgrid <https://github.com/OSGeo/proj-datumgrid>`_ is needed. If you
 have installed PROJ from a package system chances are that this will already be
 done for you. The *proj-datumgrid* package provides transformation grids that
@@ -197,7 +197,7 @@ includes grids that have global extent, e.g. the global geoid model EGM08.
 
 All packages above come in different versions, e.g proj-datumgrid-1.8 or
 proj-datumgrid-europe-1.4. The `-latest` packages are symbolic links to the
-latest version of a given packages. That means that the link
+latest version of a given package. That means that the link
 https://download.osgeo.org/proj/proj-datumgrid-north-america-latest.zip is
 equivalent to https://download.osgeo.org/proj/proj-datumgrid-north-america-1.2.zip
 (as of the time of writing this).
@@ -278,7 +278,7 @@ than one foot over the last two decades).
 Getting and building HTDP
 ................................................................................
 
-The HTDP modelling program is in written FORTRAN.  The source and documentation
+The HTDP modelling program is written in FORTRAN.  The source and documentation
 can be found on the HTDP page at http://www.ngs.noaa.gov/TOOLS/Htdp/Htdp.shtml
 
 On linux systems it will be necessary to install `gfortran` or some FORTRAN
@@ -322,10 +322,10 @@ Usage
             [-htdp <path_to_exe>] [-wrkdir <dirpath>] [-kwf]
             -o <output_grid_name>
 
- -griddef: by default the following values for roughly the continental USA
-           at a six minute step size are used:
-           -127 50 -66 25 251 611
- -kwf: keep working files in the working directory for review.
+     -griddef: by default the following values for roughly the continental USA
+               at a six minute step size are used:
+               -127 50 -66 25 251 611
+     -kwf: keep working files in the working directory for review.
 
 ::