diff options
| -rw-r--r-- | docs/source/apps/index.rst | 27 | ||||
| -rw-r--r-- | docs/source/development/api.rst | 2 | ||||
| -rw-r--r-- | docs/source/glossary.rst | 2 | ||||
| -rw-r--r-- | docs/source/grids.rst | 5 | ||||
| -rw-r--r-- | docs/source/index.rst | 13 | ||||
| -rw-r--r-- | docs/source/parameters.rst | 459 | ||||
| -rw-r--r-- | docs/source/references.rst | 23 | ||||
| -rw-r--r-- | docs/source/usage/apps/cs2cs.rst (renamed from docs/source/apps/cs2cs.rst) | 2 | ||||
| -rw-r--r-- | docs/source/usage/apps/geod.rst (renamed from docs/source/apps/geod.rst) | 5 | ||||
| -rw-r--r-- | docs/source/usage/apps/index.rst | 20 | ||||
| -rw-r--r-- | docs/source/usage/apps/proj.rst (renamed from docs/source/apps/proj.rst) | 4 | ||||
| -rw-r--r-- | docs/source/usage/index.rst | 20 | ||||
| -rw-r--r-- | docs/source/usage/projections.rst | 163 | ||||
| -rw-r--r-- | docs/source/usage/quickstart.rst | 68 | ||||
| -rw-r--r-- | docs/source/usage/resource_files.rst | 34 | ||||
| -rw-r--r-- | docs/source/usage/transformation.rst | 314 |
16 files changed, 645 insertions, 516 deletions
diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst deleted file mode 100644 index 1baaf1c5..00000000 --- a/docs/source/apps/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _apps: - -================================================================================ -Applications -================================================================================ - -The proj program is limited to converting -between geographic and projection coordinates -within one datum. - -The cs2cs program operates similarly, but allows -translation between any pair of definable coor- -dinate systems, including support for datum -translation. - -The geod program provides the ability to compute -geodesic (Great Circle) computations. - - - -.. toctree:: - :maxdepth: 1 - - proj - cs2cs - geod - diff --git a/docs/source/development/api.rst b/docs/source/development/api.rst index 5b915edf..356f32b5 100644 --- a/docs/source/development/api.rst +++ b/docs/source/development/api.rst @@ -143,7 +143,7 @@ definition into a projPJ object suitable for use with other API functions. On failure the function will return NULL and set pj_errno. The definition should be of the general form ``+proj=tmerc +lon_0 +datum=WGS84``. Refer to PROJ.4 documentation and -the :ref:`parameters` notes for additional detail. +the :ref:`transformation` notes for additional detail. Coordinate system objects allocated with ``pj_init_plus()`` should be deallocated with ``pj_free()``. diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index 3495d814..21dd0f34 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -1,4 +1,4 @@ -.. _glossary:: +.. _glossary: ================================================================================ Glossary diff --git a/docs/source/grids.rst b/docs/source/grids.rst index 99bcfdc1..7f362a92 100644 --- a/docs/source/grids.rst +++ b/docs/source/grids.rst @@ -86,6 +86,8 @@ Hungary `Hungarian grid <https://github.com/OSGeoLabBp/eov2etrs/>`__ ETRS89 - HD72/EOV (epsg:23700), both horizontal and elevation grids +.. _nonfreegrids: + Non-Free Grids -------------------------------------------------------------------------------- @@ -166,6 +168,3 @@ Netherlands ................................................................................ `Dutch grid <https://www.kadaster.nl/web/Themas/Registraties/Rijksdriehoeksmeting/Transformatie-van-coordinaten.htm>`__ (Registration required before download) - - - diff --git a/docs/source/index.rst b/docs/source/index.rst index b6f15cae..21d70947 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,13 +1,13 @@ .. _home: ****************************************************************************** -proj.4 +PROJ.4 ****************************************************************************** -proj.4 is a standard UNIX filter function which converts geographic longitude +PROJ.4 is a standard UNIX filter function which converts geographic longitude and latitude coordinates into cartesian coordinates (and vice versa), and it is a C API for software developers to include coordinate transformation in their -own software. proj.4 is maintained on `GitHub <http://github.com/OSGeo/proj.4/>`_. +own software. PROJ.4 is maintained on `GitHub <http://github.com/OSGeo/proj.4/>`_. ============= ================================================================ @@ -34,15 +34,14 @@ Documentation .. toctree:: :maxdepth: 1 - download - faq - apps/index + usage/index projections/index - parameters geodesic grids htpd development/index + faq + download glossary license references diff --git a/docs/source/parameters.rst b/docs/source/parameters.rst deleted file mode 100644 index e4623b9a..00000000 --- a/docs/source/parameters.rst +++ /dev/null @@ -1,459 +0,0 @@ -.. _parameters: - -================================================================================ -Parameters -================================================================================ - -:Date: 01/28/2016 - -.. contents:: Contents - :depth: 3 - :backlinks: none - - -This document attempts to describe a variety of the PROJ.4 parameters which can -be applied to all, or many coordinate system definitions. This document does -not attempt to describe the parameters particular to particular projection -types. Some of these can be found in the GeoTIFF `Projections Transform List -<http://www.remotesensing.org/geotiff/proj_list/>`__. The definitive -documentation for most parameters is Gerald's original documentation available -from the main PROJ.4 page. - -Parameter list --------------------------------------------------------------------------------- - -Common parameters: - -(this PROJ.4 distribution including `cs2cs` and datum support) - -:: - - +a Semimajor radius of the ellipsoid axis - +alpha ? Used with Oblique Mercator and possibly a few others - +axis Axis orientation (new in 4.8.0) - +b Semiminor radius of the ellipsoid axis - +datum Datum name (see `proj -ld`) - +ellps Ellipsoid name (see `proj -le`) - +k Scaling factor (old name) - +k_0 Scaling factor (new name) - +lat_0 Latitude of origin - +lat_1 Latitude of first standard parallel - +lat_2 Latitude of second standard parallel - +lat_ts Latitude of true scale - +lon_0 Central meridian - +lonc ? Longitude used with Oblique Mercator and possibly a few others - +lon_wrap Center longitude to use for wrapping (see below) - +nadgrids Filename of NTv2 grid file to use for datum transforms (see below) - +no_defs Don't use the /usr/share/proj/proj_def.dat defaults file - +over Allow longitude output outside -180 to 180 range, disables wrapping (see below) - +pm Alternate prime meridian (typically a city name, see below) - +proj Projection name (see `proj -l`) - +south Denotes southern hemisphere UTM zone - +to_meter Multiplier to convert map units to 1.0m - +towgs84 3 or 7 term datum transform parameters (see below) - +units meters, US survey feet, etc. - +vto_meter vertical conversion to meters. - +vunits vertical units. - +x_0 False easting - +y_0 False northing - +zone UTM zone - -Extended list provided by Gerald Evenden "grepped out of the RCS directory". - -(libproj4 by G.E.; no datum support) - -:: - - +a Semimajor radius of the ellipsoid axis - +alpha ? Used with Oblique Mercator and possibly a few others - +azi - +b Semiminor radius of the ellipsoid axis - +belgium - +beta - +czech - +e Eccentricity of the ellipsoid = sqrt(1 - b^2/a^2) = sqrt( f*(2-f) ) - +ellps Ellipsoid name (see `proj -le`) - +es Eccentricity of the ellipsoid squared - +f Flattening of the ellipsoid = 1-sqrt(1-e^2) (often presented as an inverse, e.g. 1/298) - +geoc - +guam - +h - +k Scaling factor (old name) - +K - +k_0 Scaling factor (new name) - +lat_0 Latitude of origin - +lat_1 Latitude of first standard parallel - +lat_2 Latitude of second standard parallel - +lat_b - +lat_t - +lat_ts Latitude of true scale - +lon_0 Central meridian - +lon_1 - +lon_2 - +lonc ? Longitude used with Oblique Mercator and possibly a few others - +lsat - +m - +M - +n - +no_cut - +no_off No offset. If present, do not offset origin to center of projection. Only used in Oblique Mercator projection. - +no_uoff Backwards compatible version of +no_off. - +no_rot - +ns - +o_alpha - +o_lat_1 - +o_lat_2 - +o_lat_c - +o_lat_p - +o_lon_1 - +o_lon_2 - +o_lon_c - +o_lon_p - +o_proj - +over - +p - +path - +proj Projection name (see `proj -l`) - +q - +R - +R_a - +R_A Compute radius such that the area of the sphere is the same as the area of the ellipsoid - +rf Reciprocal of the ellipsoid flattening term (e.g. 298) - +R_g - +R_h - +R_lat_a - +R_lat_g - +rot - +R_V - +s - +south Denotes southern hemisphere UTM zone - +sym - +t - +theta - +tilt - +to_meter Multiplier to convert map units to 1.0m - +units meters, US survey feet, etc. - +vopt - +W - +westo - +x_0 False easting - +y_0 False northing - +zone UTM zone - -See GE's `libproj4 -manual <http://members.verizon.net/~gerald.evenden/proj4/manual.pdf>`__ for -further details (`copy in wayback machine <http://web.archive.org/web/20080807155507/http://members.verizon.net/~gerald.evenden/proj4/manual.pdf>`__). - -Further details for projection at http://www.remotesensing.org/geotiff/proj_list/ - -Units --------------------------------------------------------------------------------- - -Horizontal units can be specified using the +units= keyword with a symbolic -name for a unit (ie. us-ft). Alternatively the translation to meters can be -specified with the +to_meter keyword (ie. 0.304800609601219 for US feet). The -``-lu`` argument to cs2cs or proj can be used to list symbolic unit names. -The default unit for projected coordinates is the meter. -A few special projections deviate from this behaviour, most notably the -latlong pseudo-projection that returns degrees. - - -Vertical Units --------------------------------------------------------------------------------- - -Vertical (Z) units can be specified using the ``+vunits=`` keyword with a -symbolic name for a unit (ie. ``us-ft``). Alternatively the translation to -meters can be specified with the ``+vto_meter`` keyword (ie. 0.304800609601219 -for US feet). The ``-lu`` argument to cs2cs or proj can be used to list symbolic -unit names. If no vertical units are specified, the vertical units will -default to be the same as the horizontal coordinates. - -Note that vertical unit transformations are only supported in pj_transform() -and programs built on that such as cs2cs. The low level projections functions -pj_fwd() and pj_inv() and programs using them directly such as proj do not -handle vertical units at all. - -False Easting/Northing --------------------------------------------------------------------------------- - -Virtually all coordinate systems allow for the presence of a false easting -(``+x_0``) and northing (``+y_0``). Note that these values are always expressed in -meters even if the coordinate system is some other units. Some coordinate -systems (such as UTM) have implicit false easting and northing values. - -lon_wrap, over - Longitude Wrapping --------------------------------------------------------------------------------- - -By default PROJ.4 wraps output longitudes in the range -180 to 180. The +over -switch can be used to disable the default wrapping which is done at a low level -- in ``pj_inv()``. This is particularly useful with projections like eqc where -it would desirable for X values past -20000000 (roughly) to continue past --180 instead of wrapping to +180. - -The ``+lon_wrap`` option can be used to provide an alternative means of doing -longitude wrapping within ``pj_transform()``. The argument to this option is a -center longitude. So ``+lon_wrap=180`` means wrap longitudes in the range 0 to -360. Note that ``+over`` does **not** disable ``+lon_wrap``. - -pm - Prime Meridian --------------------------------------------------------------------------------- - -A prime meridian may be declared indicating the offset between the prime -meridian of the declared coordinate system and that of greenwich. A prime -meridian is clared using the "pm" parameter, and may be assigned a symbolic -name, or the longitude of the alternative prime meridian relative to greenwich. - -Currently prime meridian declarations are only utilized by the -``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls. -Consequently the user utility ``cs2cs`` does honour prime meridians but the -proj user utility ignores them. - -The following predeclared prime meridian names are supported. These can be -listed using the cs2cs argument -lm. - -:: - - greenwich 0dE - lisbon 9d07'54.862"W - paris 2d20'14.025"E - bogota 74d04'51.3"E - madrid 3d41'16.48"W - rome 12d27'8.4"E - bern 7d26'22.5"E - jakarta 106d48'27.79"E - ferro 17d40'W - brussels 4d22'4.71"E - stockholm 18d3'29.8"E - athens 23d42'58.815"E - oslo 10d43'22.5"E - -Example of use. The location ``long=0``, ``lat=0`` in the greenwich based lat/long -coordinates is translated to lat/long coordinates with Madrid as the prime -meridian. - -:: - - cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid - 0 0 <i>(input)</i> - 3d41'16.48"E 0dN 0.000 <i>(output)</i> - -towgs84 - Datum transformation to WGS84 --------------------------------------------------------------------------------- - -Datum shifts can be approximated by 3 parameter spatial translations (in -geocentric space), or 7 parameter shifts (translation + rotation + scaling). -The parameters to describe this can be described using the towgs84 parameter. - -In the three parameter case, the three arguments are the translations to the -geocentric location in meters. - -For instance, the following demonstrates converting from the Greek GGRS87 datum -to WGS84. - -:: - - cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62 - +to +proj=latlong +datum=WGS84 - 20 35 - 20d0'5.467"E 35d0'9.575"N 8.570 - -The EPSG database provides this example for transforming from WGS72 to WGS84 -using an approximated 7 parameter transformation. - -:: - - cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \ - +to +proj=latlong +datum=WGS84 - 4 55 - 4d0'0.554"E 55d0'0.09"N 3.223 - -The seven parameter case uses ``delta_x``, ``delta_y``, ``delta_z``, ``Rx - -rotation X``, ``Ry - rotation Y``, ``Rz - rotation Z``, ``M_BF - Scaling``. -The three translation parameters are in meters as in the three parameter case. -The rotational parameters are in seconds of arc. The scaling is apparently the -scale change in parts per million. - -A more complete discussion of the 3 and 7 parameter transformations can be -found in the EPSG database (trf_method's 9603 and 9606). Within PROJ.4 the -following calculations are used to apply the ``towgs84`` transformation (going -to WGS84). The x, y and z coordinates are in geocentric coordinates. - -Three parameter transformation (simple offsets): - -:: - - x[io] = x[io] + defn->datum_params[0]; - y[io] = y[io] + defn->datum_params[1]; - z[io] = z[io] + defn->datum_params[2]; - -Seven parameter transformation (translation, rotation and scaling): - -:: - - #define Dx_BF (defn->datum_params[0]) - #define Dy_BF (defn->datum_params[1]) - #define Dz_BF (defn->datum_params[2]) - #define Rx_BF (defn->datum_params[3]) - #define Ry_BF (defn->datum_params[4]) - #define Rz_BF (defn->datum_params[5]) - #define M_BF (defn->datum_params[6]) - - x_out = M_BF*( x[io] - Rz_BF*y[io] + Ry_BF*z[io]) + Dx_BF; - y_out = M_BF*( Rz_BF*x[io] + y[io] - Rx_BF*z[io]) + Dy_BF; - z_out = M_BF*(-Ry_BF*x[io] + Rx_BF*y[io] + z[io]) + Dz_BF; - -Note that EPSG method 9607 (coordinate frame rotation) coefficients can be -converted to EPSG method 9606 (position vector 7-parameter) supported by PROJ.4 -by reversing the sign of the rotation vectors. The methods are otherwise the -same. - -nadgrids - Grid Based Datum Adjustments --------------------------------------------------------------------------------- - -In many places (notably North America and Austrialia) national geodetic -organizations provide grid shift files for converting between different datums, -such as NAD27 to NAD83. These grid shift files include a shift to be applied -at each grid location. Actually grid shifts are normally computed based on an -interpolation between the containing four grid points. - -PROJ.4 currently supports use of grid shift files for shifting between datums -and WGS84 under some circumstances. The grid shift table formats are ctable -(the binary format produced by the PROJ.4 ``nad2bin`` program), NTv1 (the old -Canadian format), and NTv2 (``.gsb`` - the new Canadian and Australian format). - -Use of grid shifts is specified using the ``nadgrids`` keyword in a coordinate -system definition. For example: - - -:: - - % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 50 - EOF - 111d0'2.952"W 50d0'0.111"N 0.000 - -In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was -loaded, and used to get a grid shift value for the selected point. - -It is possible to list multiple grid shift files, in which case each will be -tried in turn till one is found that contains the point being transformed. - -:: - - cs2cs +proj=latlong +ellps=clrk66 \ - +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 44 - EOF - 111d0'2.788"W 43d59'59.725"N 0.000 - -Skipping Missing Grids -................................................................................ - -The special prefix ``@`` may be prefixed to a grid to make it optional. If it -not found, the search will continue to the next grid. Normally any grid not -found will cause an error. For instance, the following would use the -``ntv2_0.gsb`` file if available (see [[NonFreeGrids]]), otherwise it would -fallback to using the ``ntv1_can.dat`` file. - -:: - - cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 50 - EOF - 111d0'3.006"W 50d0'0.103"N 0.000 - -The null Grid -................................................................................ - -A special ``null`` grid shift file is shift with releases after 4.4.6 (not -inclusive). This file provides a zero shift for the whole world. It may be -listed at the end of a nadgrids file list if you want a zero shift to be -applied to points outside the valid region of all the other grids. Normally if -no grid is found that contains the point to be transformed an error will occur. - -:: - - cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 45 - EOF - 111d0'3.006"W 50d0'0.103"N 0.000 - - cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ - +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF - -111 44 - -111 55 - EOF - 111d0'2.788"W 43d59'59.725"N 0.000 - 111dW 55dN 0.000 - -Downloading and Installing Grids -................................................................................ - -The source distribution of PROJ.4 contains only the ntv1_can.dat file. To get -the set of US grid shift files it is necessary to download an additional -distribution of files from the PROJ.4 site, such as -ftp://ftp.remotesensing.org/pub/proj/proj-nad27-1.1.tar.gz. Overlay it on the -PROJ.4 source distribution, and re-configure, compile and install. The -distributed ASCII .lla files are converted into binary (platform specific) -files that are installed. On windows using the nmake /f makefile.vc nadshift -command in the proj\src directory to build and install these files. - -It appears we can't redistribute the Canadian NTv2 grid shift file freely, -though it is better than the NTv1 file. However, end users can download it for -free from the `NRCan web site -<http://www.geod.nrcan.gc.ca/tools-outils/ntv2_e.php>`__. After downloading -it, just dump it in the data directory with the other installed data files -(usually `/usr/local/share/proj`). See [[NonFreeGrids]] for details. - -Caveats -................................................................................ - -* Where grids overlap (such as conus and ntv1_can.dat for instance) the first - found for a point will be used regardless of whether it is appropriate or - not. So, for instance, ```+nadgrids=ntv1_can.dat```,conus would result in - the Canadian data being used for some areas in the northern United States - even though the conus data is the approved data to use for the area. - Careful selection of files and file order is necessary. In some cases - border spanning datasets may need to be pre-segmented into Canadian and - American points so they can be properly grid shifted -* There are additional grids for shifting between NAD83 and various HPGN - versions of the NAD83 datum. Use of these haven't been tried recently so - you may encounter problems. The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla - are examples of high precision grid shifts. Take care! -* Additional detail on the grid shift being applied can be found by setting - the PROJ_DEBUG environment variable to a value. This will result in output - to stderr on what grid is used to shift points, the bounds of the various - grids loaded and so forth -* PROJ.4 always assumes that grids contain a shift **to** NAD83 (essentially - WGS84). Other types of grids might or might not be usable - -Axis orientation --------------------------------------------------------------------------------- - -Starting in PROJ 4.8.0, the +axis argument can be used to control the axis -orientation of the coordinate system. The default orientation is "easting, -northing, up" but directions can be flipped, or axes flipped using combinations -of the axes in the +axis switch. The values are: - -* "e" - Easting -* "w" - Westing -* "n" - Northing -* "s" - Southing -* "u" - Up -* "d" - Down - -They can be combined in +axis in forms like: - -* ``+axis=enu`` - the default easting, northing, elevation. -* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic - coordinates, or south orientated transverse mercator. -* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems - have "west positive" coordinate systems - -Note that the ``+axis`` argument only applies to coordinate transformations done -through ``pj_transform()`` (so it works with ``cs2cs``, but not with the proj -commandline program). diff --git a/docs/source/references.rst b/docs/source/references.rst index 26c4da08..eaf5b17e 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -4,25 +4,28 @@ References ================================================================================ +.. [AltamimiEtAl2002] Altamimi, Z., P. Sillard, and C. Boucher (2002), ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications, J. Geophys. Res., 107(B10), 2214, `doi:10.1029/2001JB000561 <http://www.agu.org/pubs/crossref/2002/2001JB000561.shtml>`__. + +.. [CalabrettaGreisen2002] M. Calabretta and E. Greisen, 2002, "Representations of celestial coordinates in FITS". Astronomy & Astrophysics 395, 3, 1077–1122. + +.. [ChanONeil1975] F. Chan and E.M.O'Neill, 1975, "Feasibility Study of a Quadrilateralized Spherical Cube Earth Data Base". Tech. Rep. EPRF 2-75 (CSC), Environmental Prediction Research Facility. + +.. [EberHewitt1979] Eber, L.E., and R.P. Hewitt. 1979. `Conversion algorithms for the CALCOFI station grid <http://www.calcofi.org/publications/calcofireports/v20/Vol_20_Eber___Hewitt.pdf>`__. California Cooperative Oceanic Fisheries Investigations Reports 20:135-137. .. [Evenden1995] Evenden, G. I., 1995, `Cartograpic Projection Procedures for the UNIX Environment - A User's Manual <https://github.com/OSGeo/proj.4/blob/master/docs/old/proj_4_3_12.pdf>`_ .. [Evenden2005] Evenden, G. I., 2005, `libproj4: A Comprehensive Library of Cartographic Projection Functions (Preliminary Draft) <https://github.com/OSGeo/proj.4/blob/master/docs/old/libproj.pdf>`_ +.. [EversKnudsen2017] K. Evers and T. Knudsen, 2017, `Transformation pipelines for PROJ.4 <http://www.fig.net/resources/proceedings/fig_proceedings/fig2017/papers/iss6b/ISS6B_evers_knudsen_9156.pdf>`__, FIG Working Week 2017 Proceedings. + +.. [LambersKolb2012] M. Lambers and A. Kolb, 2012, "Ellipsoidal Cube Maps for Accurate Rendering of Planetary-Scale Terrain Data", Proc. Pacfic Graphics (Short Papers). + +.. [ONeilLaubscher1976] E.M. O'Neill and R.E. Laubscher, 1976, "Extended Studies of a Quadrilateralized Spherical Cube Earth Data Base". Tech. Rep. NEPRF 3-76 (CSC), Naval Environmental Prediction Research Facility. + .. [Steers1970] Steers, J.A., 1970, An introduction to the study of map projections (15th ed.): London, Univ. London Press, p. 229 .. [Snyder1987] Snyder. John P. 1987. `Map Projections - A Working Manual <https://github.com/OSGeo/proj.4/blob/master/docs/old/USGS-Snyder-Map-Projections-A-Working-Manual-1987.pdf>`_. US. Geological Survey professional paper; 1395. .. [Snyder1993] Snyder, 1993, Flattening the Earth, Chicago and London, The university of Chicago press -.. [EberHewitt1979] Eber, L.E., and R.P. Hewitt. 1979. `Conversion algorithms for the CALCOFI station grid <http://www.calcofi.org/publications/calcofireports/v20/Vol_20_Eber___Hewitt.pdf>`__. California Cooperative Oceanic Fisheries Investigations Reports 20:135-137. - .. [WeberMoore2013] Weber, E.D., and T.J. Moore. 2013. `Corrected Conversion Algorithms For The Calcofi Station Grid And Their Implementation In Several Computer Languages <http://calcofi.org/publications/calcofireports/v54/Vol_54_Weber.pdf>`__. California Cooperative Oceanic Fisheries Investigations Reports 54. - -.. [CalabrettaGreisen2002] M. Calabretta and E. Greisen, 2002, "Representations of celestial coordinates in FITS". Astronomy & Astrophysics 395, 3, 1077–1122. - -.. [ChanONeil1975] F. Chan and E.M.O'Neill, 1975, "Feasibility Study of a Quadrilateralized Spherical Cube Earth Data Base". Tech. Rep. EPRF 2-75 (CSC), Environmental Prediction Research Facility. - -.. [ONeilLaubscher1976] E.M. O'Neill and R.E. Laubscher, 1976, "Extended Studies of a Quadrilateralized Spherical Cube Earth Data Base". Tech. Rep. NEPRF 3-76 (CSC), Naval Environmental Prediction Research Facility. - -.. [LambersKolb2012] M. Lambers and A. Kolb, 2012, "Ellipsoidal Cube Maps for Accurate Rendering of Planetary-Scale Terrain Data", Proc. Pacfic Graphics (Short Papers). diff --git a/docs/source/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst index ae8016fe..675379ef 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/usage/apps/cs2cs.rst @@ -5,8 +5,6 @@ cs2cs ================================================================================ -.. Index:: cs2cs - ``cs2cs`` performs transformation between the source and destination cartographic coordinate system on a set of input points. The coordinate system transformation can include translation between projected and geographic coordinates as well as the application of datum shifts. diff --git a/docs/source/apps/geod.rst b/docs/source/usage/apps/geod.rst index 4620a6cc..7765f36a 100644 --- a/docs/source/apps/geod.rst +++ b/docs/source/usage/apps/geod.rst @@ -4,9 +4,6 @@ geod ================================================================================ - -.. Index:: geod - ``geod`` (direct) and ``invgeod`` (inverse) perform geodesic ("Great Circle") computations for determining latitude, longitude and back azimuth of a terminus point given a initial point latitude, @@ -157,7 +154,7 @@ which gives: 45d31'0.003"N 123d40'59.985"W 75d39'13.094" .. note:: - lack of precision in the distance value compromises the + Lack of precision in the distance value compromises the precision of the Portland location. Further reading diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst new file mode 100644 index 00000000..73c5c63c --- /dev/null +++ b/docs/source/usage/apps/index.rst @@ -0,0 +1,20 @@ +.. _apps: + +================================================================================ +Applications +================================================================================ + +Bundled with PROJ.4 comes a set of small command line utilities. The +``proj`` program is limited to converting between geographic and projection +coordinates within one datum. The ``cs2cs`` program operates similarly, but +allows translation between any pair of definable coordinate systems, including +support for basic datum translation. The ``geod`` program provides the ability +to do geodesic (great circle) computations. + +.. toctree:: + :maxdepth: 1 + + proj + cs2cs + geod + diff --git a/docs/source/apps/proj.rst b/docs/source/usage/apps/proj.rst index a06df383..424a0fef 100644 --- a/docs/source/apps/proj.rst +++ b/docs/source/usage/apps/proj.rst @@ -1,4 +1,4 @@ -:. _proj: +.. _proj: ================================================================================ proj @@ -7,7 +7,7 @@ proj .. Index:: proj -Proj and invproj perform respective forward and inverse transformation of cartographic data to +``proj`` and ``invproj`` perform respective forward and inverse transformation of cartographic data to or from cartesian data with a wide range of selectable projection functions. diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst new file mode 100644 index 00000000..8c12c026 --- /dev/null +++ b/docs/source/usage/index.rst @@ -0,0 +1,20 @@ +.. _usage: + +================================================================================ +Using PROJ.4 +================================================================================ + +The main purpose of PROJ.4 is to transform coordinates from one coordinate +reference system to another. This can be achieved either with the included +command line applications or the C API that is a part of the software package. + + +.. toctree:: + :maxdepth: 1 + + quickstart + apps/index + projections + transformation + resource_files + diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst new file mode 100644 index 00000000..b0bcce61 --- /dev/null +++ b/docs/source/usage/projections.rst @@ -0,0 +1,163 @@ +.. _projections_intro: + +================================================================================ +Cartographic projection +================================================================================ + +The foundation of PROJ.4 is the large number of +:doc:`projections<../projections/index>` available in the library. This section +is devoted to the generic parameters that can be used on any projection in the +PROJ.4 library. + +Below is a list of PROJ.4 parameters which can be applied to most coordinate +system definitions. This table does not attempt to describe the parameters +particular to particular projection types. These can be found on the pages +documenting the individual :doc:`projections<../projections/index>`. + + ========== ================================================================ + Parameter Description + ========== ================================================================ + +a Semimajor radius of the ellipsoid axis + +axis Axis orientation + +b Semiminor radius of the ellipsoid axis + +ellps Ellipsoid name (see ``proj -le``) + +k Scaling factor (deprecated) + +k_0 Scaling factor + +lat_0 Latitude of origin + +lon_0 Central meridian + +lon_wrap Center longitude to use for wrapping (see below) + +no_defs Don't use the /usr/share/proj/proj_def.dat defaults file + +over Allow longitude output outside -180 to 180 range, disables + wrapping (see below) + +pm Alternate prime meridian (typically a city name, see below) + +proj Projection name (see ``proj -l``) + +units meters, US survey feet, etc. + +vunits vertical units. + +x_0 False easting + +y_0 False northing + ========== ================================================================ + +In the sections below most of the parameters are explained in details. + +Units ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Horizontal units can be specified using the ``+units`` keyword with a symbolic +name for a unit (ie. ``us-ft``). Alternatively the translation to meters can be +specified with the ``+to_meter`` keyword (ie. 0.304800609601219 for US feet). The +``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list symbolic unit names. +The default unit for projected coordinates is the meter. +A few special projections deviate from this behaviour, most notably the +latlong pseudo-projection that returns degrees. + +Vertical (Z) units can be specified using the ``+vunits`` keyword with a +symbolic name for a unit (ie. ``us-ft``). Alternatively the translation to +meters can be specified with the ``+vto_meter`` keyword (ie. 0.304800609601219 +for US feet). The ``-lu`` argument to ``cs2cs`` or ``proj`` can be used to list +symbolic unit names. If no vertical units are specified, the vertical units will +default to be the same as the horizontal coordinates. + +.. note:: + ``proj`` do not handle vertical units at all and hence the ``+vto_meter`` + argument will be ignored. + +Scaling of output units can be done by applying the ``+k_0`` argument. The +returned coordinates are scaled by the value assigned with the ``+k_0`` +parameter. + +False Easting/Northing ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Virtually all coordinate systems allow for the presence of a false easting +(``+x_0``) and northing (``+y_0``). Note that these values are always expressed in +meters even if the coordinate system is some other units. Some coordinate +systems (such as UTM) have implicit false easting and northing values. + +Longitude Wrapping ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +By default PROJ.4 wraps output longitudes in the range -180 to 180. The ``+over`` +switch can be used to disable the default wrapping which is done at a low level +in ``pj_inv()``. This is particularly useful with projections like the +:doc:`equidistant cylindrical<../projections/eqc>` where it would be desirable for +X values past -20000000 (roughly) to continue past -180 instead of wrapping to +180. + +The ``+lon_wrap`` option can be used to provide an alternative means of doing +longitude wrapping within ``pj_transform()``. The argument to this option is a +center longitude. So ``+lon_wrap=180`` means wrap longitudes in the range 0 to +360. Note that ``+over`` does **not** disable ``+lon_wrap``. + +Prime Meridian ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +A prime meridian may be declared indicating the offset between the prime +meridian of the declared coordinate system and that of greenwich. A prime +meridian is clared using the "pm" parameter, and may be assigned a symbolic +name, or the longitude of the alternative prime meridian relative to greenwich. + +Currently prime meridian declarations are only utilized by the +``pj_transform()`` API call, not the ``pj_inv()`` and ``pj_fwd()`` calls. +Consequently the user utility ``cs2cs`` does honour prime meridians but the +``proj`` user utility ignores them. + +The following predeclared prime meridian names are supported. These can be +listed using with ``cs2cs -lm``. + + =========== ================ + Meridian Longitude + =========== ================ + greenwich 0dE + lisbon 9d07'54.862"W + paris 2d20'14.025"E + bogota 74d04'51.3"E + madrid 3d41'16.48"W + rome 12d27'8.4"E + bern 7d26'22.5"E + jakarta 106d48'27.79"E + ferro 17d40'W + brussels 4d22'4.71"E + stockholm 18d3'29.8"E + athens 23d42'58.815"E + oslo 10d43'22.5"E + =========== ================ + +Example of use. The location ``long=0``, ``lat=0`` in the greenwich based lat/long +coordinates is translated to lat/long coordinates with Madrid as the prime +meridian. + +:: + + cs2cs +proj=latlong +datum=WGS84 +to +proj=latlong +datum=WGS84 +pm=madrid + 0 0 <i>(input)</i> + 3d41'16.48"E 0dN 0.000 <i>(output)</i> + + +Axis orientation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Starting in PROJ 4.8.0, the +axis argument can be used to control the axis +orientation of the coordinate system. The default orientation is "easting, +northing, up" but directions can be flipped, or axes flipped using combinations +of the axes in the +axis switch. The values are: + +* "e" - Easting +* "w" - Westing +* "n" - Northing +* "s" - Southing +* "u" - Up +* "d" - Down + +They can be combined in +axis in forms like: + +* ``+axis=enu`` - the default easting, northing, elevation. +* ``+axis=neu`` - northing, easting, up - useful for "lat/long" geographic + coordinates, or south orientated transverse mercator. +* ``+axis=wnu`` - westing, northing, up - some planetary coordinate systems + have "west positive" coordinate systems + +.. note:: + + The ``+axis`` argument does not work with the ``proj`` command line + utility. + + diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst new file mode 100644 index 00000000..d162ace9 --- /dev/null +++ b/docs/source/usage/quickstart.rst @@ -0,0 +1,68 @@ +.. _quickstart: + +================================================================================ +Quick start +================================================================================ + +Coordinate transformations are defined by, what in PROJ.4 terminology is +known as, "proj-strings". A proj-string describes any transformation regardless of +how simple or complicated it might be. The simplest case is projection of geodetic +coordinates. This section focuses on the simpler cases and introduces the basic +anatomy of the proj-string. The complex cases are discussed in +:doc:`transformation`. + +A proj-strings holds the parameters of a given coordinate transformation, e.g. + +:: + + +proj=merc +lat_ts=56.5 +ellps=GRS80 + +I.e. a proj-string consists of a projection specifier, ``+proj``, a number of +parameters that applies to the projection and, if needed, a description of a +datum shift. In the example above geodetic coordinates are transformed to +projected space with the :doc:`Mercator projection<../projections/merc>` with +the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every +projection in PROJ.4 is identified by a shorthand such as ``merc`` in the above +example. + +By using the above projection definition as parameters for the command line +utility ``proj`` we can convert the geodetic coordinates to projected space: + +:: + + $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + +If called as above ``proj`` will be in interactive mode, letting you type the +input data manually and getting a responce presented on screen. ``proj`` +works as any UNIX filter though, which means that you can also pipe data to +the utility, for instance by using the ``echo`` command: + +:: + + $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + 3399483.80 752085.60 + + +PROJ.4 also comes bundled with the ``cs2cs`` utility which is used to transform +from onecoordinate reference system to another. Say we want to convert +the above Mercator coordinates to UTM, we can do that with ``cs2cs``: + +:: + + $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32 + 6103992.36 1924052.47 0.00 + +Notice the ``+to`` parameter that seperates the source and destination +projection definitions. + +If you happen to know the EPSG identifiers for the two cordinates reference +systems you are transforming between you can use those with ``cs2cs``: + +:: + + $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832 + 231950.54 1920310.71 0.00 + +In the above example we transform geodetic coordinates in the WGS84 reference +frame to UTM zone 32N coordinates in the ETRS89 reference frame. +UTM coordinates diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst new file mode 100644 index 00000000..0881cb7c --- /dev/null +++ b/docs/source/usage/resource_files.rst @@ -0,0 +1,34 @@ +.. _resource_files: + +================================================================================ +Resource files +================================================================================ + +Init files +------------------------------------------------------------------------------- + +epsg ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +nad27 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +nad83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +ITRF ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +IGNF ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +GL27 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +esri ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +Defaults file +------------------------------------------------------------------------------- + diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst new file mode 100644 index 00000000..98e607a7 --- /dev/null +++ b/docs/source/usage/transformation.rst @@ -0,0 +1,314 @@ +.. _transformation: + +================================================================================ +Geodetic transformation +================================================================================ + +PROJ.4 can do everything from the most simple projection to very complex +transformations across many reference frames. While originally developed as a +tool for cartographic projections, PROJ.4 has over time evolved into a powerfull +generic coordinate transformation engine that makes it possible to do both +large scale cartographic projections as well as coordinate transformation at a +geodetic high precision level. This chapter delves into the details of how +geodetec transformations of varying complexity can be performed. + +In PROJ.4, two frameworks for geodetic transformations exists, the *cs2cs* +framework and the *transformation pipelines* framework. The first is the original, +and limited, framework for doing geodetic transforms in PROJ.4 The latter is a +newer addition that aims to be a more complete transformation framework. Both are +described in the sections below. Large portions of the text are based on +[EversKnudsen2017]_. + +Before describing the details of the two frameworks, let us first remark that +most cases of geodetic transformations can be expressed as a series of elementary +operations, the output of one operation being the input of the next. E.g. when +going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the +simplest case, go through 5 steps: + +1. Back-project the UTM coordinates to geographic coordinates +2. Convert the geographic coordinates to 3D cartesian geocentric coordinates +3. Apply a Helmert transformation from ED50 to ETRS89 +4. Convert back from cartesian to geographic coordinates +5. Finally project the geographic coordinates to UTM zone 32 planar coordinates. + + +Transformation pipelines ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The homology between the above steps and a Unix shell style pipeline is evident. +It is there the main architectural inspiration behind the transformation pipeline +framework. The pipeline framework is realized by utilizing a special "projection", +that takes as its user supplied arguments, a series of elementary operations, +which it strings together in order to implement the full transformation needed. +Additionally, a number of elementary geodetic operations, including Helmert +transformations, general high order polynomial shifts and the Molodensky +transformation are available as part of the pipeline framework. +In anticipation of upcoming support for full time-varying transformations, we +also introduce a 4D spatiotemporal data type, and a programming interface +(API) for handling this. + +The Molodensky transformation converts directly from geodetic coordinates +in one datum, to geodetic coordinates in another datum, while the (typically more +accurate) Helmert transformation converts from 3D cartesian to 3D cartesian +coordinates. So when using the Helmert transformation one typically needs to do an +initial conversion from geodetic to cartesian coordinates, and a final conversion +the other way round, to arrive at the desired result. Fortunately, this three-step +compound transformation has the attractive characteristic that each step depends +only on the output of the immediately preceding step. Hence, we can build a +geodetic-to-geodetic Helmert transformation by tying together the outputs and inputs +of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style. +The pipeline driver, makes this kind of chained transformations possible. +The implementation is compact, consisting of just one pseudo-projection, called +``pipeline``, which takes as its arguments strings of elementary projections +(note: "projection" is the, slightly misleading, PROJ.4 term used for any kind of +transformation). +The pipeline pseudo projection is supplemented by a number of elementary +transformations, all in all providing a framework for building high accuracy +solutions for a wide spectrum of geodetic tasks. + + +As a first example, let us take a look at the iconic +*geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in +the itroduction). In PROJ.4 it can be implemented as + +:: + + proj=pipeline + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + +The pipeline can be expanded at both ends to accommodate whatever coordinate type +is needed for input and output: In the example below, we transform from the +deprecated Danish System 45, a 2D system with some tension in the original defining +network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial +transformation (the init=./s45b... step, s45b.pol is a file containing the +polynomial coefficients), taking the S45 coordinates to a technical coordinate +system (TC32), defined to represent "UTM zone 32 coordinates, as they would look if +the Helmert transformation between ED50 and ETRS89 was perfect". The TC32 +coordinates are then converted back to geodetic(ED50) coordinates, using an +inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89), +using the relevant Helmert transformation, and back to geodetic(ETRS89), before +finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step +pipeline, implementing a transformation with centimeter level accuracy from a +deprecated system with decimeter level tensions. + +:: + + proj=pipeline + step init=./s45b.pol:s45b_tc32 + step proj=utm inv ellps=intl zone=32 + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + step proj=utm ellps=GRS80 zone=33 + +With the pipeline framework spatiotemporal transformation is possible. This is +possible by leveraging the time dimension in PROJ.4 that enables 4D coordinates +(three spatial components and one temporal component) to be passed through a +transformation pipeline. In the example below a transformation from ITRF93 to +ITRF2000 is defined. The temporal component is given as GPS weeks in the input +data, but the 14-parameter Helmert transform expects temporal units in decimalyears. +Hence the first step in the pipeline is the unitconvert pseudo-projection that makes +sure the correct units are passed along to the Helmert transform. +Most parameters of the Helmert transform are taken from [AltamimiEtAl2002]_, +except the epoch which is the epoch of the transformation. The default setting is to +use “coordinate frame” convention of the Helmert transform, but “position vector” +convention can also be used. The last step in the pipeline is converting the +coordinate timestamps back to GPS weeks. + +:: + + proj=pipeline + step proj=unitconvert t_in=gps_week t_out=decimalyear + step proj=helmert + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + rx=0.00039 ry=-0.00080 rz=0.00114 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + drx=0.00011 dry=0.00019 drz=-0.00007 + epoch=1988.0 + step proj=unitconvert t_in=decimalyear t_out=gps_week + + +cs2cs paradigm ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + ============ ============================================================== + Parameter Description + ============ ============================================================== + +datum Datum name (see ``proj -ld``) + +geoidgrids Filename of GTX grid file to use for vertical datum transforms + +nadgrids Filename of NTv2 grid file to use for datum transforms + +towgs84 3 or 7 term datum transform parameters + +to_meter Multiplier to convert map units to 1.0m + +vto_meter Vertical conversion to meters + ============ ============================================================== + +The *cs2cs* framework delivers a subset of the geodetic transformations available +with the *pipeline* framework. Coordinate transformations done in this framework +are transformed in a two-step process with WGS84 as a pivot datum That is, the +input coordinates are transformed to WGS84 geodetic coordinates and then transformed +from WGS84 coordinates to the specified output coordinate reference system, by +utilizing either the Helmert transform, datum shift grids or a combination of both. +Datum shifts can be described in a proj-string with the parameters ``+towgs84``, +``+nadgrids`` and ``+geoidgrids``. +An inverse transform exists for all three and is applied if +specified in the input proj-string. The most common is ``+towgs84``, which is used to +define a 3- or 7-parameter Helmert shift from the input reference frame to WGS84. +Exactly which realization of WGS84 is not specified, hence a fair amount of +uncertainty is introduced in this step of the transformation. With the +nadgrids +parameter a non-lineaer planar correction derived from interpolation in a +correction grid can be applied. Originally this was implemented as a means to +transform coordinates between the american datums NAD27 and NAD83, but corrections +can be applied for any datum for which a correction grid exists. The inverse +transform for the horizontal grid shift is "dumb", in the sense that the +correction grid is applied verbatim without taking into account that the inverse +operation is non-linear. Similar to the horizontal grid correction, ``+geoidgrids`` +can be used to perform grid corrections in the vertical component. +Both grid correction methods allow inclusion of more than one grid in the same +transformation + +In contrast to the *transformation pipeline* framework, transformations with the +*cs2cs* framework are expressed as two separate proj-strings. One proj-string *to* +WGS84 and one *from* WGS84. Together they form the mapping from the source +coordinate reference system to the destination coordinate reference system. +When used with the ``cs2cs`` the source and destination CRS's are separated by the +special ``+to`` parameter. + +The following example demonstrates converting from the Greek GGRS87 datum +to WGS84 with the ``+towgs84`` parameter. + +:: + + cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62 + +to +proj=latlong +datum=WGS84 + 20 35 + 20d0'5.467"E 35d0'9.575"N 8.570 + +The EPSG database provides this example for transforming from WGS72 to WGS84 +using an approximated 7 parameter transformation. + +:: + + cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \ + +to +proj=latlong +datum=WGS84 + 4 55 + 4d0'0.554"E 55d0'0.09"N 3.223 + + +Grid Based Datum Adjustments ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In many places (notably North America and Austrialia) national geodetic +organizations provide grid shift files for converting between different datums, +such as NAD27 to NAD83. These grid shift files include a shift to be applied +at each grid location. Actually grid shifts are normally computed based on an +interpolation between the containing four grid points. + +PROJ.4 supports use of grid files for shifting between various reference frames. +The grid shift table formats are ctable (the binary format produced by the PROJ.4 +``nad2bin`` program), NTv1 (the old Canadian format), and NTv2 (``.gsb`` - the new +Canadian and Australian format). + +The text in this section is based on the *cs2cs* framework. Gridshifting is off +course also possible with the *pipeline* framework. The major difference between the +two is that the *cs2cs* framework is limited to grid mappings to WGS84, whereas with +*transformation pipelines* it is possible to perform grid shifts between any two +reference frames, as long as a grid exists. + +Use of grid shifts with ``cs2cs`` is specified using the ``+nadgrids`` +keyword in a coordinate system definition. For example: + +:: + + % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'2.952"W 50d0'0.111"N 0.000 + +In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was +loaded, and used to get a grid shift value for the selected point. + +It is possible to list multiple grid shift files, in which case each will be +tried in turn till one is found that contains the point being transformed. + +:: + + cs2cs +proj=latlong +ellps=clrk66 \ + +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + + +Skipping Missing Grids +................................................................................ + +The special prefix ``@`` may be prefixed to a grid to make it optional. If it +not found, the search will continue to the next grid. Normally any grid not +found will cause an error. For instance, the following would use the +``ntv2_0.gsb`` file if available (see :ref:`nonfreegrids`), otherwise it would +fallback to using the ``ntv1_can.dat`` file. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + +The null Grid +................................................................................ + +A special ``null`` grid shift file is shift with releases after 4.4.6 (not +inclusive). This file provides a zero shift for the whole world. It may be +listed at the end of a nadgrids file list if you want a zero shift to be +applied to points outside the valid region of all the other grids. Normally if +no grid is found that contains the point to be transformed an error will occur. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 45 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + -111 55 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + 111dW 55dN 0.000 + +For more information see the chapter on :ref:`Grids`. + +Caveats +................................................................................ + +* Where grids overlap (such as conus and ntv1_can.dat for instance) the first + found for a point will be used regardless of whether it is appropriate or + not. So, for instance, ``+nadgrids=ntv1_can.dat``,conus would result in + the Canadian data being used for some areas in the northern United States + even though the conus data is the approved data to use for the area. + Careful selection of files and file order is necessary. In some cases + border spanning datasets may need to be pre-segmented into Canadian and + American points so they can be properly grid shifted +* There are additional grids for shifting between NAD83 and various HPGN + versions of the NAD83 datum. Use of these haven't been tried recently so + you may encounter problems. The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla + are examples of high precision grid shifts. Take care! +* Additional detail on the grid shift being applied can be found by setting + the PROJ_DEBUG environment variable to a value. This will result in output + to stderr on what grid is used to shift points, the bounds of the various + grids loaded and so forth +* The *cs2cs* framework always assumes that grids contain a shift **to** NAD83 (essentially + WGS84). Other types of grids can be used with the *pipeline* framework. |