Transformation Grids

Transformation grids improve accuracy when you are performing datum transformations.

More information about the data available is located under the PROJ resource files documentation.

Note

pyproj API for managing the Data Directory and PROJ Network Settings.

Note

pyproj 3 wheels do not include any transformation grids.

Downloading data

PROJ 7+

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.

Available methods for download include:

• Mirroring the data:

  To download to the PROJ user-writable data directory:

  New in version 7.1.0.

  export PROJ_DOWNLOAD_DIR=$(python -c "import pyproj; print(pyproj.datadir.get_user_data_dir())")
  

  To download to the main PROJ data directory:

  export PROJ_DOWNLOAD_DIR=$(python -c "import pyproj; print(pyproj.datadir.get_data_dir())")
  

  Download the files with either:

  aws s3 sync s3://cdn.proj.org ${PROJ_DOWNLOAD_DIR}
  

  or:

  wget --mirror https://cdn.proj.org/ -P ${PROJ_DOWNLOAD_DIR}
  

• The projsync command line program.

• pyproj sync command line program (pyproj 3+; useful if you use pyproj wheels).

• Enabling PROJ network capabilities. See also PROJ Network Settings.

• Download stable from https://download.osgeo.org/proj or latest from https://github.com/OSGeo/PROJ-data

• Use conda with the conda-forge channel:

  conda install -c conda-forge proj-data
  

PROJ <= 6

Available methods for download include:

• Download stable from https://download.osgeo.org/proj or latest from https://github.com/OSGeo/proj-datumgrid

• Use conda with the conda-forge channel:

  conda install -c conda-forge proj-datumgrid-europe proj-datumgrid-north-america proj-datumgrid-oceania proj-datumgrid-world
  

What grids to download?

• Only using the pyproj.crs.CRS or pyproj.Geod classes? Then no grids are needed.

• Have a machine that can hold and extra 500 MB - 1 GB of data? Then downloading all grids shouldn’t be an issue.

• Have a machine with limited space, a great network connection, and PROJ 7+? Look into PROJ network capabilities. See also PROJ Network Settings.

• Have a machine with limited space and want to pre-download files?

  You can enable enable Debugging Internal PROJ with pyproj 3+ and perform a transformation. The logs will show the grids PROJ searches for.

  Additionally, the pyproj.transformer.TransformerGroup can assist finding the grids you need to download.

  Warning

  There are cases where the URL to download the grid is missing.

  >>> from pyproj.transformer import TransformerGroup
  >>> tg = trans_group = TransformerGroup(4326, 2964)
  UserWarning: Best transformation is not available due to missing Grid(short_name=us_noaa_alaska.tif, full_name=, package_name=, url=https://cdn.proj.org/us_noaa_alaska.tif, direct_download=True, open_license=True, available=False)
  >>> tg
  <TransformerGroup: best_available=False>
  - transformers: 8
  - unavailable_operations: 2
  >>> tg.transformers[0].description
  'Inverse of NAD27 to WGS 84 (7) + Alaska Albers'
  >>> tg.unavailable_operations[0].name
  'Inverse of NAD27 to WGS 84 (85) + Alaska Albers'
  >>> tg.unavailable_operations[0].grids[0].url
  'https://cdn.proj.org/us_noaa_alaska.tif'
  >>> tg.download_grids(verbose=True)  # pyproj 3+
  Downloading: https://cdn.proj.org/us_noaa_alaska.tif
  Downloading: https://cdn.proj.org/ca_nrc_ntv2_0.tif