Codebase list python-pyproj / upstream/3.0_rc2 docs / transformation_grids.rst
upstream/3.0_rc2

Tree @upstream/3.0_rc2 (Download .tar.gz)

transformation_grids.rst @upstream/3.0_rc2 — raw · history · blame 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
.. _transformation_grids:

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 <https://proj.org/resource_files.html#transformation-grids>`__
documentation.

.. note:: `pyproj` API for managing the :ref:`data_directory` and :ref:`network`.

.. 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 <https://proj.org/community/rfc/rfc-4.html#rfc4>`__,
the capability to work with grid files that are not installed on the local machine where PROJ is executed.

Available methods for download include:

- `Mirroing the data <https://proj.org/usage/network.html#mirroring>`__:

  To download to PROJ user writable data directory:

  .. versionadded:: 7.1.0

  .. code-block:: bash

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

  To download to the main PROJ data data directory:

  .. code-block:: bash

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

  Download the files:

  .. code-block:: bash

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

  .. code-block:: bash

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

- The `projsync <https://proj.org/apps/projsync.html>`__ command line program.

- `pyproj sync <cli.html#sync>`__ command line program (pyproj 3+; useful if you use pyproj wheels).

- Enabling `PROJ network <https://proj.org/usage/network.html>`__ capabilities. See also :ref:`network`.

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

- Use `conda <https://conda.io/en/latest/>`__ with the `conda-forge <https://conda-forge.org/>`__ channel:

  .. code-block:: bash

     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 <https://conda.io/en/latest/>`__ with the `conda-forge <https://conda-forge.org/>`__ channel:

  .. code-block:: bash

     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 :obj:`pyproj.crs.CRS` or :obj:`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 <https://proj.org/usage/network.html>`__ capabilities. See also :ref:`network`.

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

  You can enable enable :ref:`debugging-internal-proj` with pyproj 3+ and perform a transformation.
  The logs will show the grids PROJ searches for.

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

  .. code-block:: python

    >>> 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