diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/install.rst | 5 | ||||
| -rw-r--r-- | docs/source/resource_files.rst | 139 |
2 files changed, 59 insertions, 85 deletions
diff --git a/docs/source/install.rst b/docs/source/install.rst index 08edba8d..1a055b4c 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -34,6 +34,9 @@ the `proj-datumgrid-europe` package:: Available is also the ``proj-datumgrid-north-america``, ``proj-datumgrid-oceania`` and ``proj-datumgrid-world``. +.. tip:: + Read more about the various datumgrid packages available :ref:`here<datumgrid>`. + Docker +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -123,7 +126,7 @@ PROJ is also available from the MacPorts system:: Compilation and installation from source code ################################################################################ -The classical way of installing PROJ is via the source code distribution. The +The classic way of installing PROJ is via the source code distribution. The most recent version is available from the :ref:`download page<current_release>`. You will need that and at least the standard *proj-datumgrid* package for a diff --git a/docs/source/resource_files.rst b/docs/source/resource_files.rst index a6fd9f12..40eb9731 100644 --- a/docs/source/resource_files.rst +++ b/docs/source/resource_files.rst @@ -6,11 +6,11 @@ Resource files A number of files containing preconfigured transformations and default parameters for certain projections are bundled with the PROJ distribution. Init files -contains preconfigured proj-strings for various coordinate reference systems -and the defaults file contains default values for parameters of select +contain preconfigured proj-strings for various coordinate reference systems +and the `defaults` file contains default values for parameters of select projections. -In addition to the bundled init-files the PROJ.4 project also distribute a number +In addition to the bundled init-files the PROJ project also distributes a number of packages containing transformation grids and additional init-files not included in the main PROJ package. @@ -23,17 +23,37 @@ A proj installation includes a SQLite database of transformation information that must be accessible for the library to work properly. The library will print an error if the database can't be found. -External resources +Transformation grids +------------------------------------------------------------------------------- + +Grid files are important for shifting and transforming between datums. + +PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections and +the GTX file format for vertical corrections. Details about the formats can be +found in the `GDAL documentation <http://gdal.org/>`_. GDAL reads and writes +all formats. Using GDAL for construction of new grids is recommended. + +.. _datumgrid: + +External resources and packaged grids ------------------------------------------------------------------------------- -For a functioning PROJ installation of the +proj-datumgrid +++++++++++++++ + +For a functioning PROJ, 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 are essential for many of the predefined transformations in PROJ. Which grids are included in the package can be seen on the `proj-datumgrid repository <https://github.com/OSGeo/proj-datumgrid>`_ as well -as descriptions of those grids. +as descriptions of those grids. This is the main grid package and the only one +that is required. It includes various older grids that is mostly needed for +legacy reasons. Without this package, the test suite fails miserably. + +Regional packages ++++++++++++++++++ In addition to the default *proj-datumgrid* package regional packages are also distributed. These include grids and init-files that are valid within the given @@ -47,46 +67,43 @@ At the moment three regional resource file packages are distributed: * `Oceania <https://github.com/OSGeo/proj-datumgrid/tree/master/oceania#proj-datumgrid-oceania>`_ * `North America <https://github.com/OSGeo/proj-datumgrid/tree/master/north-america#proj-datumgrid-north-america>`_ +If someone supplies grids relevant for Africa, South-America, Asia or Antarctica +we will create new regional packages. + Click the links to jump to the relevant README files for each package. Details on the content of the packages maintained there. -Links to the resource packages can be found in the :ref:`download section <download>`. +.. tip:: + To download the various datumgrid packages head to the :ref:`download section <download>`. -.. _transformation_grids: +World package ++++++++++++++ -Transformation grids -------------------------------------------------------------------------------- +The `world package <https://github.com/OSGeo/proj-datumgrid/tree/master/world#proj-datumgrid-world>`_ +includes grids that have global extent, e.g. the global geoid model EGM08. -Grid files are important for shifting and transforming between datums. +-latest packages +++++++++++++++++ -PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections and -the GTX file format for vertical corrections. Details about the formats can be -found in the `GDAL documentation <http://gdal.org/>`_. GDAL reads and writes -all formats. Using GDAL for construction of new grids is recommended. +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 +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). + +.. _transformation_grids: -Below is a given a list of grid resources for various countries which are not +Other transformation grids +------------------------------------------------------------------------------- + +Below is a list of grid resources for various countries which are not included in the grid distributions mentioned above. Free grids +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Below is a list of grids distributed under a free and open license. - -Switzerland -................................................................................ - -Background in ticket `#145 <https://github.com/OSGeo/PROJ/issues/145>`__ - -We basically have two shift grids available. An official here: - -`Swiss CHENyx06 dataset in NTv2 format <https://shop.swisstopo.admin.ch/en/products/geo_software/GIS_info>`__ - -And a derived in a temporary location which is probably going to disappear soon. - -Main problem seems to be there's no mention of distributivity of the grid from -the official website. It just tells: "you can use freely". The "contact" link -is also broken, but maybe someone could make a phone call to ask for rephrasing -that. +The following is a list of grids distributed under a free and open license. Hungary ................................................................................ @@ -134,49 +151,10 @@ Spain `Spanish grids <http://www.ign.es/ign/layoutIn/herramientas.do#DATUM>`__ for ED50. - -HARN -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -With the support of `i-cubed <http://www.i3.com>`__, Frank Warmerdam has -written tools to translate the HPGN grids from NOAA/NGS from ``.los/.las`` format -into NTv2 format for convenient use with PROJ. This project included -implementing a `.los/.las reader <https://github.com/OSGeo/gdal/tree/trunk/gdal/frmts/raw/loslasdataset.cpp>`__ -for GDAL, and an `NTv2 reader/writer <https://github.com/OSGeo/gdal/tree/trunk/gdal/frmts/raw/ntv2dataset.cpp>`__. -Also, a script to do the bulk translation was implemented in -https://github.com/OSGeo/gdal/tree/trunk/gdal/swig/python/samples/loslas2ntv2.py. -The command to do the translation was: - -:: - - loslas2ntv2.py -auto *hpgn.los - -As GDAL uses NAD83/WGS84 as a pivot datum, the sense of the HPGN datum shift offsets were negated to map from HPGN to NAD83 instead of the other way. The files can be used with PROJ like this: - -:: - - cs2cs +proj=latlong +datum=NAD83 - +to +proj=latlong +nadgrids=./azhpgn.gsb +ellps=GRS80 - -:: - - # input: - -112 34 - -:: - - # output: - 111d59'59.996"W 34d0'0.006"N -0.000 - -This was confirmed against the `NGS HPGN calculator -<http://www.ngs.noaa.gov/cgi-bin/nadcon2.prl>`__. - -The grids are available at https://download.osgeo.org/proj/hpgn_ntv2.zip - HTDP +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -This page documents use of the `crs2crs2grid.py` script and the HTDP +This section describes the use of the `crs2crs2grid.py` script and the HTDP (Horizontal Time Dependent Positioning) grid shift modelling program from NGS/NOAA to produce PROJ compatible grid shift files for fine grade conversions between various NAD83 epochs and WGS84. Traditionally PROJ has @@ -212,7 +190,8 @@ Getting crs2crs2grid.py The `crs2crs2grid.py` script can be found at https://github.com/OSGeo/gdal/tree/trunk/gdal/swig/python/samples/crs2crs2grid.py -It depends on having the GDAL Python bindings operational. If they are not +The script depends on having the GDAL Python bindings operational; if they are not you +will get an error such as: :: @@ -311,7 +290,7 @@ Init files Init files are used for preconfiguring proj-strings for often used transformations, such as those found in the EPSG database. Most init files contain transformations from a given coordinate reference system to WGS84. This makes -it easy to transformations between any two coordinate reference systems with +it easy to transform between any two coordinate reference systems with ``cs2cs``. Init files can however contain any proj-string and don't necessarily have to follow the *cs2cs* paradigm where WGS84 is used as a pivot datum. The ITRF init file is a good example of that. @@ -320,7 +299,7 @@ A number of init files come pre-bundled with PROJ but it is also possible to add your own custom init files. PROJ looks for the init files in the directory listed in the ``PROJ_LIB`` environment variable. -The format of init files made up of a identifier in angled brackets and a +The format of init files is an identifier in angled brackets and a proj-string: :: @@ -398,11 +377,3 @@ Below is a list of the init files that are packaged with PROJ. nad27 State plane coordinate systems, North American Datum 1927 nad83 State plane coordinate systems, North American Datum 1983 ======== ================================================================ - - -The defaults file -------------------------------------------------------------------------------- - -Before PROJ 6.0, a ``proj_def.dat`` file could be used to supply default -parameters to PROJ. It has been removed due to the confusion and errors it -caused. |