Merge pull request #1903 from rouault/add_proj_download

Add projsync utility

10 files changed, 179 insertions, 6 deletions

diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst
index 96b5f13b..a9d9e61e 100644
--- a/docs/source/apps/cct.rst
+++ b/docs/source/apps/cct.rst
@@ -190,7 +190,7 @@ Hence, in honour of *cct* (the geodesist) this is :program:`cct` (the program).
     See also
     ********
 
-    **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**
+    **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst
index c95bbaed..1a1e785d 100644
--- a/docs/source/apps/cs2cs.rst
+++ b/docs/source/apps/cs2cs.rst
@@ -230,7 +230,7 @@ outputs
     See also
     ********
 
-    **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**
+    **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/geod.rst b/docs/source/apps/geod.rst
index c03dbb74..5267c184 100644
--- a/docs/source/apps/geod.rst
+++ b/docs/source/apps/geod.rst
@@ -200,7 +200,7 @@ Further reading
     See also
     ********
 
-    **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**
+    **proj(1)**, **cs2cs(1)**, **cct(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/gie.rst b/docs/source/apps/gie.rst
index ac197d44..af6f528e 100644
--- a/docs/source/apps/gie.rst
+++ b/docs/source/apps/gie.rst
@@ -366,7 +366,7 @@ So in honour, and hopefully also in the spirit, of Gerald Ian Evenden
     See also
     ********
 
-    **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**
+    **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**, **projinfo(1)**, **projsync(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst
index 381b8933..751be591 100644
--- a/docs/source/apps/index.rst
+++ b/docs/source/apps/index.rst
@@ -24,3 +24,4 @@ operations.
    gie
    proj
    projinfo
+   projsync
diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst
index 21c2ea61..488d1b36 100644
--- a/docs/source/apps/proj.rst
+++ b/docs/source/apps/proj.rst
@@ -214,7 +214,7 @@ data will appear as three lines of::
     See also
     ********
 
-    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**
+    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst
index 0b65b8a0..91d09941 100644
--- a/docs/source/apps/projinfo.rst
+++ b/docs/source/apps/projinfo.rst
@@ -416,7 +416,7 @@ Output:
     See also
     ********
 
-    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**
+    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**, **projsync(1)**
 
     Bugs
     ****
diff --git a/docs/source/apps/projsync.rst b/docs/source/apps/projsync.rst
new file mode 100644
index 00000000..9756e0c4
--- /dev/null
+++ b/docs/source/apps/projsync.rst
@@ -0,0 +1,160 @@
+.. _projsync:
+
+================================================================================
+projsync
+================================================================================
+
+.. Index:: projsync
+
+.. only:: html
+
+    .. versionadded:: 7.0.0
+
+    Tool for synchronizing PROJ datum and transformation support data.
+
+Synopsis
+********
+
+    | **projsync**
+    |      [--endpoint URL]
+    |      [--local-geojson-file FILENAME]
+    |      ([--user-writable-directory] | [--system-directory] | [--target-dir DIRNAME])
+    |      [--bbox west_long,south_lat,east_long,north_lat]
+    |      [--spatial-test contains|intersects]
+    |      [--source-id ID] [--area-of-use NAME]
+    |      [--file NAME]
+    |      [--all] [--exclude-world-coverage]
+    |      [--quiet] [--dry-run] [--list-files]
+
+Description
+***********
+
+:program:`projsync` is a program that downloads remote resource files
+into a local directory. This is an alternative to downloading a proj-data-X.Y.Z
+archive file, or using the on-demand :ref:`networking capabilities <network>` of PROJ.
+
+The following control parameters can appear in any order:
+
+.. program:: projsync
+
+.. option:: --endpoint URL
+
+    Defines the URL where to download the master ``files.geojson`` file and then
+    the resource files. Defaults to the value set in :ref:`proj-ini`
+
+.. option:: --local-geojson-file FILENAME
+
+    Defines the filename for the master GeoJSON files that references resources.
+    Defaults to ${endpoint}/files.geojson
+
+.. option:: --user-writable-directory
+
+    Specifies that resource files must be downloaded in the
+    :ref:`user writable directory <user_writable_directory>`. This is the default.
+
+.. option:: --system-directory
+
+    Specifies that resource files must be downloaded in the
+    ${installation_prefix}/share/proj directory. The user launching projsync
+    should make sure it has writing rights in that directory.
+
+.. option:: --target-dir DIRNAME
+
+    Directory into which resource files must be downloaded.
+
+.. option:: --bbox west_long,south_lat,east_long,north_lat
+
+    Specify an area of interest to restrict the resources to download.
+    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.
+
+.. option:: --spatial-test contains|intersects
+
+    Specify how the extent of the resource files
+    are compared to the area of use specified explicitly with :option:`--bbox`.
+    By default, any resource files whose extent intersects the value specified
+    by :option:`--bbox` will be selected.
+    If using the ``contains`` strategy, only resource files whose extent is
+    contained in the value specified by :option:`--bbox` will be selected.
+
+.. option:: --source-id ID
+
+    Restrict resource files to be downloaded to those whose source_id property
+    contains the ID value. Specifying ``?`` as ID will list all possible values.
+
+.. option:: --area-of-use NAME
+
+    Restrict resource files to be downloaded to those whose area_of_use property
+    contains the NAME value. Specifying ``?`` as NAME will list all possible values.
+
+.. option:: --file NAME
+
+    Restrict resource files to be downloaded to those whose name property
+    contains the NAME value. Specifying ``?`` as NAME will list all possible values.
+
+.. option:: --all
+
+    Ask to download all files.
+
+.. option:: --exclude-world-coverage
+
+    Exclude files which have world coverage.
+
+.. option:: -q / --quiet
+
+    Quiet mode
+
+.. option:: --dry-run
+
+    Simulate the behaviour of the tool without downloading resource files.
+
+.. option:: --list-files
+
+    List file names, with the source_id and area_of_use properties.
+
+
+At least one of  :option:`--list-files`,  :option:`--file`,  :option:`--source-id`,
+:option:`--area-of-use`,  :option:`--bbox` or  :option:`--all` must be specified.
+
+Options :option:`--file`,  :option:`--source-id`, :option:`--area-of-use` and
+:option:`--bbox` are combined with a AND logic.
+
+Examples
+********
+
+1. Download all resource files
+
+.. code-block:: console
+
+      projsync --all
+
+2. Download resource files covering specified point and attributing to an agency
+
+.. code-block:: console
+
+      projsync --source-id fr_ign --bbox 2,49,2,49
+
+
+.. only:: man
+
+    See also
+    ********
+
+    **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**, **projinfo(1)**
+
+    Bugs
+    ****
+
+    A list of know bugs can be found at https://github.com/OSGeo/PROJ/issues
+    where new bug reports can be submitted to.
+    Bugs specific to resource files should be submitted to
+    https://github.com/OSGeo/PROJ-data/issues
+
+    Home page
+    *********
+
+    https://proj.org/
diff --git a/docs/source/conf.py b/docs/source/conf.py
index f2fa3961..081b0a94 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -346,6 +346,13 @@ man_pages = [
         ['Even Rouault'],
         1
     ),
+    (
+        'apps/projsync',
+        'projsync',
+        u'Downloading tool of resource files',
+        ['Even Rouault'],
+        1
+    ),
 ]
 
 # If true, show URL addresses after external links.
diff --git a/docs/source/usage/network.rst b/docs/source/usage/network.rst
index 295232b0..1b42d0aa 100644
--- a/docs/source/usage/network.rst
+++ b/docs/source/usage/network.rst
@@ -76,6 +76,11 @@ capability to download whole grids in the
 :ref:`PROJ user writable directory <user_writable_directory>` by using the
 :cpp:func:`proj_is_download_needed` and :cpp:func:`proj_download_file` functions.
 
+Download utility
+----------------
+
+:ref:`projsync` is a tool for downloading resource files.
+
 
 Mirroring
 ---------