Network capabilities

Added in version 7.0.

PROJ 7.0 has introduced, per PROJ RFC 4: Remote access to grids and GeoTIFF grids, the capability to work with grid files that are not installed on the local machine where PROJ is executed.

This enables to transparently download the parts of grids that are needed to perform a coordinate transformation.

CDN of GeoTIFF grids

Files are accessed by default through a CDN (Content Delivery Network), accessible through https://cdn.proj.org, that contains Geodetic TIFF grids (GTG) datasets which are mirrored and managed by the https://github.com/OSGeo/PROJ-data/ GitHub project. Files in the CDN are designed to be used by PROJ 7 or later, but any software project wishing to use the CDN for shifting support are encouraged to participate in the project and leverage the CDN.

How to enable network capabilities ?

This capability assumes that PROJ has been build against libcurl, and that the user authorizes network access.

Authorizing network access can be done in multiple ways:

  • enabling / uncommenting the network = on line of proj.ini

  • defining the PROJ_NETWORK environment variable to ON

  • or using the proj_context_set_enable_network() with a enabled = TRUE value.

Note

Instead of using the libcurl implementation, an application using the PROJ API can supply its own network implementation through C function callbacks with proj_context_set_network_callbacks(). Enabling network use must still be done with one of the above mentioned method.

Setting endpoint

When this is enabled, and a grid is not found in the various locations where resource files are looked for, PROJ will then attempt at loading the file from a remote server, which defaults to https://cdn.proj.org in proj.ini. This location can be changed with the PROJ_NETWORK_ENDPOINT environment variable or with proj_context_set_url_endpoint().

Caching

To avoid repeated access to network, a local cache of downloaded chunks of grids is implemented as SQLite3 database, cache.db, stored in the PROJ user writable directory.

This local caching is enabled by default (can be changed in proj.ini or with proj_grid_cache_set_enable()). The default maximum size of the cache is 300 MB, which is more than half of the total size of grids available, at time of writing. This size can also be customized in proj.ini or with proj_grid_cache_set_max_size()

Download API

When on-demand loading of grid is not desirable, the PROJ API also offers the capability to download whole grids in the PROJ user writable directory by using the proj_is_download_needed() and proj_download_file() functions.

Download utility

projsync is a tool for downloading resource files.

Mirroring

If you are able, you are encouraged to mirror the grids via AWS S3 command line:

aws s3 sync s3://cdn.proj.org .

If direct S3 access is not possible, you can also use wget to locally mirror the data:

wget --mirror https://cdn.proj.org/

Acknowledgements

The s3://cdn.proj.org bucket is hosted by the Amazon Public Datasets program. CDN services are provided by the AWS Public Dataset team via CloudFront