From 7ea472f54849f3230d5865884ef75c4edcda3fa8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 28 Aug 2017 08:07:48 +0200 Subject: [PATCH 01/43] Major restructure and rewrite of docs. A section on "Using PROJ.4" has been introduced giving a introduction on how to use PROJ.4. The Parameters section has been removed and the content reworked into other sections. Additionally the order of chapters has been changed to provide a more complete and readable experience for users of the documentation. --- docs/source/apps/index.rst | 27 -- docs/source/development/api.rst | 2 +- docs/source/glossary.rst | 2 +- docs/source/grids.rst | 5 +- docs/source/index.rst | 13 +- docs/source/parameters.rst | 459 ------------------------- docs/source/references.rst | 23 +- docs/source/{ => usage}/apps/cs2cs.rst | 2 - docs/source/{ => usage}/apps/geod.rst | 5 +- docs/source/usage/apps/index.rst | 20 ++ docs/source/{ => usage}/apps/proj.rst | 4 +- docs/source/usage/index.rst | 20 ++ docs/source/usage/projections.rst | 163 +++++++++ docs/source/usage/quickstart.rst | 68 ++++ docs/source/usage/resource_files.rst | 34 ++ docs/source/usage/transformation.rst | 314 +++++++++++++++++ 16 files changed, 645 insertions(+), 516 deletions(-) delete mode 100644 docs/source/apps/index.rst delete mode 100644 docs/source/parameters.rst rename docs/source/{ => usage}/apps/cs2cs.rst (99%) rename docs/source/{ => usage}/apps/geod.rst (98%) create mode 100644 docs/source/usage/apps/index.rst rename docs/source/{ => usage}/apps/proj.rst (98%) create mode 100644 docs/source/usage/index.rst create mode 100644 docs/source/usage/projections.rst create mode 100644 docs/source/usage/quickstart.rst create mode 100644 docs/source/usage/resource_files.rst create mode 100644 docs/source/usage/transformation.rst diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst deleted file mode 100644 index 1baaf1c592..0000000000 --- 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 5b915edf30..356f32b581 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 3495d8148a..21dd0f3475 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 99bcfdc106..7f362a9245 100644 --- a/docs/source/grids.rst +++ b/docs/source/grids.rst @@ -86,6 +86,8 @@ Hungary `Hungarian grid `__ ETRS89 - HD72/EOV (epsg:23700), both horizontal and elevation grids +.. _nonfreegrids: + Non-Free Grids -------------------------------------------------------------------------------- @@ -166,6 +168,3 @@ Netherlands ................................................................................ `Dutch grid `__ (Registration required before download) - - - diff --git a/docs/source/index.rst b/docs/source/index.rst index b6f15cae2f..21d709473d 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 `_. +own software. PROJ.4 is maintained on `GitHub `_. ============= ================================================================ @@ -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 e4623b9a27..0000000000 --- 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 -`__. 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 `__ for -further details (`copy in wayback machine `__). - -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 (input) - 3d41'16.48"E 0dN 0.000 (output) - -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 -`__. 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 26c4da0868..eaf5b17ecb 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 `__. + +.. [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 `__. 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 `_ .. [Evenden2005] Evenden, G. I., 2005, `libproj4: A Comprehensive Library of Cartographic Projection Functions (Preliminary Draft) `_ +.. [EversKnudsen2017] K. Evers and T. Knudsen, 2017, `Transformation pipelines for PROJ.4 `__, 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 `_. 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 `__. 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 `__. 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 similarity index 99% rename from docs/source/apps/cs2cs.rst rename to docs/source/usage/apps/cs2cs.rst index ae8016fe8e..675379ef96 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 similarity index 98% rename from docs/source/apps/geod.rst rename to docs/source/usage/apps/geod.rst index 4620a6cc46..7765f36a21 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 0000000000..73c5c63c5b --- /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 similarity index 98% rename from docs/source/apps/proj.rst rename to docs/source/usage/apps/proj.rst index a06df383c3..424a0fef3f 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 0000000000..8c12c026f8 --- /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 0000000000..b0bcce6181 --- /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 (input) + 3d41'16.48"E 0dN 0.000 (output) + + +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 0000000000..d162ace9b2 --- /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 0000000000..0881cb7cc3 --- /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 0000000000..98e607a78d --- /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. From 1ba5cf61d3daf24103b16915f51582b8dcb3635a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Sep 2017 15:38:27 +0200 Subject: [PATCH 02/43] Added documentation of init files and defaults file --- docs/source/usage/resource_files.rst | 115 +++++++++++++++++++++++---- 1 file changed, 101 insertions(+), 14 deletions(-) diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst index 0881cb7cc3..e99763f128 100644 --- a/docs/source/usage/resource_files.rst +++ b/docs/source/usage/resource_files.rst @@ -4,31 +4,118 @@ Resource files ================================================================================ +A number of files containing preconfigured transformations and default parameters +for certain projections are bundled with the PROJ.4 distribution. Init files +contains preconfigured proj-strings for various coordinate reference systems +and the defaults file contains default values for parameters of select +projections. + Init files ------------------------------------------------------------------------------- -epsg -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +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 +``cs2cs``. Init files can however contain any proj-string and don't necesarily +have to follow the *cs2cs* paradigm where WGS84 is used as a pivot datum. The +ITRF init file is a good example of that. + +A number of init files come pre-bundled with PROJ.4 but it is also possible to +add your own custom init files. PROJ.4 looks for the init files in the directoty +listed in the ``PROJ_LIB`` environment variable. + +The format of init files made up of a identifier in angled brackets and a +proj-string: + +:: + + <3819> +proj=longlat +ellps=bessel + +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs <> + +The above example is the first entry from the ``epsg`` init file. So, this is the +coordinate reference system with ID 3819 in the EPSG database. Comments can be +inserted by prefixing them with a "#". With version 4.10.0 a new special metadata +entry is now accepted in init files. It can be parsed with a function from the public +API. The metadata entry in the epsg init file looks like this at the time of writing: + +:: + + +version=9.0.0 +origin=EPSG +lastupdate=2017-01-10 + +Pre-configured proj-strings from init files are used in the following way: -nad27 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +:: -nad83 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + $ cs2cs -v +proj=latlong +to +init=epsg:3819 + # ---- From Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +proj=latlong +ellps=WGS84 + # ---- To Coordinate System ---- + #Lat/long (Geodetic alias) + # + # +init=epsg:3819 +proj=longlat +ellps=bessel + # +towgs84=595.48,121.69,515.35,4.115,-2.9383,0.853,-3.408 +no_defs -ITRF -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +It is possible to override parameters when using ``+init``. Just add the parameter +to the proj-string alongside the ``+init`` parameter. For instance by overriding +the ellipsoid as in the following example -IGNF -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +:: -GL27 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +init=epsg:25832 +ellps=intl -esri -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +where the Hayford ellipsoid is used instead of the predefined GRS80 ellipsoid. +It is also possible to add additional parameters not specified in the init file, +for instance by adding an obervation epoch when transforming from ITRF2000 to +ITRF2005: + +:: + + +init=ITRF2000:ITRF2005 +tobs=2010.5 + +which then expands to + +:: + + +proj=helmert +x=-0.0001 +y=0.0008 +z=0.0058 +s=-0.0004 + +dx=0.0002 +dy=-0.0001 +dz=0.0018 +ds=-0.000008 + +epoch=2000.0 +transpose + +tobs=2010.5 + +Below is a list of the init files that are packaged with PROJ.4. + + ======== ================================================================ + Name Description + ======== ================================================================ + esri Auto-generated mapping from Esri projection index. Not + maintained any more + epsg EPSG database + GL27 Great Lakes Grids + IGNF French coordinate systems supplied by the IGNF + ITRF2000 Full set of transformation parameters between ITRF2000 and other + ITRF's + ITRF2008 Full set of transformation parameters between ITRF2008 and other + ITRF's + ITRF2014 Full set of transformation parameters between ITRF2014 and other + ITRF's + nad27 State plane coordinate systems, North American Datum 1927 + nad83 State plane coordinate systems, North American Datum 1983 + ======== ================================================================ Defaults file ------------------------------------------------------------------------------- +The ``proj_def.dat`` file supplies default parameters for PROJ.4. It uses the same +syntax as the init files described above. The identifiers in the defaults file +describe to what the parameters should apply. If the ```` identifier is +used, then all parameters in that section applies for all proj-strings. Otherwise +the identifier is connected to a specific projection. With the defaults file +supplied with PROJ.4 the default ellipsoid is set to WGS84 (for all proj-strings). +Apart from that only the Albers Equal Area, +:doc:`Lambert Conic Conformal<../projections/lcc>` and the +:doc:`Lagrange<../projections/lagrng>` projections have default parameters. +Defaults can be ignored by adding the ``+no_def`` parameter to a proj-string. + From c0aaf4c5f489b43ce5a9d0a3cc325e853d04585a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Sep 2017 18:30:02 +0200 Subject: [PATCH 03/43] Use same spelling of PROJ.4 across all doc pages. --- docs/source/conf.py | 10 +++++----- docs/source/development/bindings.rst | 12 ++++++------ docs/source/faq.rst | 6 +++--- docs/source/projections/geos.rst | 2 +- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index cbd02f100e..62316eeffa 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# proj.4 documentation build configuration file, created by +# PROJ.4 documentation build configuration file, created by # sphinx-quickstart on Wed Feb 24 10:47:15 2016. # # This file is execfile()d with the current directory set to its @@ -47,7 +47,7 @@ master_doc = 'index' # General information about the project. -project = u'proj.4' +project = u'PROJ.4' copyright = u'1986?-2016' author = u'Gerald Evenden, Frank Warmerdam, and others' @@ -230,7 +230,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'proj4.tex', u'proj.4 Documentation', + (master_doc, 'proj4.tex', u'PROJ.4 Documentation', u'Gerald Evenden', 'manual'), ] @@ -260,7 +260,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'proj4', u'proj.4 Documentation', + (master_doc, 'proj4', u'PROJ.4 Documentation', [author], 1) ] @@ -274,7 +274,7 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'proj4', u'proj.4 Documentation', + (master_doc, 'proj4', u'PROJ.4 Documentation', author, 'proj4', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/source/development/bindings.rst b/docs/source/development/bindings.rst index a1c2a9e0fb..80babcb20d 100644 --- a/docs/source/development/bindings.rst +++ b/docs/source/development/bindings.rst @@ -4,37 +4,37 @@ Language bindings ******************************************************************************** -Proj.4 bindings are available for a number of different development platforms. +PROJ.4 bindings are available for a number of different development platforms. Python ====== `pyproj `_: -Python interface (wrapper for proj.4) +Python interface (wrapper for PROJ.4) Ruby ======= `proj4rb `_: -Bindings for proj.4 in ruby +Bindings for PROJ.4 in ruby TCL ======== `proj4tcl `_: -Bindings for proj.4 in tcl (critcl source) +Bindings for PROJ.4 in tcl (critcl source) MySQL ===== `fProj4 `_: -Bindings for proj.4 in MySQL +Bindings for PROJ.4 in MySQL Excel ======== `proj.xll `_: -Excel add-in for proj.4 map projections +Excel add-in for PROJ.4 map projections Visual Basic ================== diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 0240df1d91..48bcfafd23 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -212,7 +212,7 @@ Similar issues apply with many other datasets distributed with projections based on a spherical earth model - such as many NASA datasets. This coordinate system is now known by the EPSG code 3857 and has in the past been known as EPSG:3785 and EPSG:900913. When using this coordinate system with GDAL/OGR it -is helpful to include the +wktext so the exact proj.4 string will be preserved +is helpful to include the +wktext so the exact PROJ.4 string will be preserved in the WKT representation (otherwise key parameters like `+nadgrids=@null` will be dropped): @@ -302,7 +302,7 @@ Output of above command: 0 0.7853981633974483 0.00 41.94 -What options does proj.4 allow for the shape of the Earth (geodesy)? +What options does PROJ.4 allow for the shape of the Earth (geodesy)? -------------------------------------------------------------------------------- See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c @@ -315,7 +315,7 @@ What if I want a spherical Earth? Use ``+ellps=sphere``. See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c for the radius used in this case. -How do I change the radius of the Earth? How do I use proj.4 for work on Mars? +How do I change the radius of the Earth? How do I use PROJ.4 for work on Mars? -------------------------------------------------------------------------------- You can supply explicit values for the semi minor and semi major axes instead diff --git a/docs/source/projections/geos.rst b/docs/source/projections/geos.rst index 2e30924157..5655015900 100644 --- a/docs/source/projections/geos.rst +++ b/docs/source/projections/geos.rst @@ -66,7 +66,7 @@ This example represents the scanning geometry of the Meteosat series satellite. However, the GOES satellite series use the opposite scanning geometry, with the E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle axis. -The sweep argument is used to tell proj.4 which on which axis the outer-gimbal +The sweep argument is used to tell PROJ.4 which on which axis the outer-gimbal is rotating. The possible values are x or y, y being the default. Thus, the scanning geometry of the Meteosat series satellite should take sweep as x, and GOES should take sweep as y. From c58d26841a4a4459c1d7dabb04ea504853bd0634 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Sep 2017 21:39:54 +0200 Subject: [PATCH 04/43] Added Contributing chapter to docs. CONTRIBUTING.md translated to rst with pandoc. --- docs/source/contributing.rst | 242 +++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 243 insertions(+) create mode 100644 docs/source/contributing.rst diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 0000000000..e7f9101e0c --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,242 @@ +.. _contributing: + +=========================== +Contributing +=========================== + +PROJ.4 has a wide and varied user base. Some are highly skilled +geodesists with a deep knowledge of map projections and reference +systems, some are GIS software developers and others are GIS users. All +users, regardless of the profession or skill level, has the ability to +contribute to PROJ.4. Here's a few suggestion on how: + +- Help PROJ.4-users that is less experienced than yourself. +- Write a bug report +- Request a new feature +- Write documentation for your favorite map projection +- Fix a bug +- Implement a new feature + +In the following sections you can find some guidelines on how to +contribute. As PROJ.4 is managed on GitHub most contributions require +that you have a GitHub account. Familiarity with +`issues `__ and the `GitHub +Flow `__ is an advantage. + +Help a fellow PROJ.4 user +------------------------- + +The main forum for support for PROJ.4 is the mailing list. You can +subscribe to the mailing list +`here `__ and read the +archive `here `__. + +If you have questions about the usage of PROJ.4 the mailing list is also +the place to go. Please *do not* use the GitHub issue tracker as a +support forum. Your question is much more likely to be answered on the +mailing list, as many more people follow that than the issue tracker. + +Adding bug reports +------------------ + +Bug reports are handled in the `issue +tracker `__ on PROJ.4's home on +GitHub. Writing a good bug report is not easy. But fixing a poorly +documented bug is not easy either, so please put in the effort it takes +to create a thorough bug report. + +A good bug report includes at least: + +- A title that quickly explains the problem +- A description of the problem and how it can be reproduced +- Version of PROJ.4 being used +- Version numbers of any other relevant software being used, e.g. + operating system +- A description of what already has been done to solve the problem + +The more information that is given up front, the more likely it is that +a developer will find interest in solving the problem. You will probably +get follow-up questions after submitting a bug report. Please answer +them in a timely manner if you have an interest in getting the issue +solved. + +Finally, please only submit bug reports that are actually related to +PROJ.4. If the issue materializes in software that uses PROJ.4 it is +likely a problem with that particular software. Make sure that it +actually is a PROJ.4 problem before you submit an issue. If you can +reproduce the problem only by using tools from PROJ.4 it is definitely a +problem with PROJ.4. + +Feature requests +---------------- + +Got an idea for a new feature in PROJ.4? Submit a thorough description +of the new feature in the `issue +tracker `__. Please include any +technical documents that can help the developer make the new feature a +reality. An example of this could be a publicly available academic paper +that describes a new projection. Also, including a numerical test case +will make it much easier to verify that an implementation of your +requested feature actually works as you expect. + +Note that not all feature requests are accepted. + +Write documentation +------------------- + +PROJ.4 is in dire need of better documentation. Any contributiions of +documentation are greatly appreaciated. The PROJ.4 documentation is +available on `proj4.org `__. The website is generated +with `Sphinx `__. Contributions to +the documentation should be made as `Pull +Requests `__ on GitHub. + +If you intend to document one of PROJ.4's supported projections please +use the `Mercator projection `__ +as a template. + +Code contributions +------------------ + +Code contributions can be either bug fixes or new features. The process +is the same for both, so they will be discussed together in this +section. + +Making Changes +~~~~~~~~~~~~~~ + +- Create a topic branch from where you want to base your work. +- You usually should base your topic branch off of the master branch. +- To quickly create a topic branch: ``git checkout -b my-topic-branch`` +- Make commits of logical units. +- Check for unnecessary whitespace with ``git diff --check`` before + committing. +- Make sure your commit messages are in the `proper + format `__. +- Make sure you have added the necessary tests for your changes. +- Make sure that all tests pass + +Submitting Changes +~~~~~~~~~~~~~~~~~~ + +- Push your changes to a topic branch in your fork of the repository. +- Submit a pull request to the PROJ.4 repository in the OSGeo + organization. +- If your pull request fixes/references an issue, include that issue + number in the pull request. For example: + +:: + + Wiz the bang + + Fixes #123. + +- PROJ.4 developers will look at your patch and take an appropriate + action. + +Coding conventions +~~~~~~~~~~~~~~~~~~ + +Programming language +^^^^^^^^^^^^^^^^^^^^ + +PROJ.4 is developed strictly in ANSI C 89. + +Coding style +^^^^^^^^^^^^ + +We don't enforce any particular coding style, but please try to keep it +as simple as possible. If improving existing code, please try to conform +with the style of the locally surrounding code. + +Whitespace +^^^^^^^^^^ + +Throughout the PROJ.4 code base you will see differing whitespace use. +The general rule is to keep whitespace in whatever form it is in the +file you are currently editing. If the file has a mix of tabs and space +please convert the tabs to space in a separate commit before making any +other changes. This makes it a lot easier to see the changes in diffs +when evaulating the changed code. New files should use spaces as +whitespace. + +File names +^^^^^^^^^^ + +Files in which projections are implemented are prefixed with an +upper-case ``PJ_`` and most other files are prefixed with lower-case +``pj_``. Some file deviate from this pattern, most of them dates back to +the very early releases of PROJ.4. New contributions should follow the +pj-prefix pattern. Unless there are obvious reasons not to. + +Legalese +~~~~~~~~ + +Commiters are the front line gatekeepers to keep the code base clear of +improperly contributed code. It is important to the PROJ.4 users, +developers and the OSGeo foundation to avoid contributing any code to +the project without it being clearly licensed under the project license. + +Generally speaking the key issues are that those providing code to be +included in the repository understand that the code will be released +under the MIT/X license, and that the person providing the code has the +right to contribute the code. For the commiter themselves understanding +about the license is hopefully clear. For other contributors, the +commiter should verify the understanding unless the commiter is very +comfortable that the contributor understands the license (for instance +frequent contributors). + +If the contribution was developed on behalf of an employer (on work +time, as part of a work project, etc) then it is important that an +appropriate representative of the employer understand that the code will +be contributed under the MIT/X license. The arrangement should be +cleared with an authorized supervisor/manager, etc. + +The code should be developed by the contributor, or the code should be +from a source which can be rightfully contributed such as from the +public domain, or from an open source project under a compatible +license. + +All unusual situations need to be discussed and/or documented. + +Commiters should adhere to the following guidelines, and may be +personally legally liable for improperly contributing code to the source +repository: + +- Make sure the contributor (and possibly employer) is aware of the + contribution terms. +- Code coming from a source other than the contributor (such as adapted + from another project) should be clearly marked as to the original + source, copyright holders, license terms and so forth. This + information can be in the file headers, but should also be added to + the project licensing file if not exactly matching normal project + licensing (COPYING). +- Existing copyright headers and license text should never be stripped + from a file. If a copyright holder wishes to give up copyright they + must do so in writing to the foundation before copyright messages are + removed. If license terms are changed it has to be by agreement + (written in email is ok) of the copyright holders. +- Code with licenses requiring credit, or disclosure to users should be + added to COPYING. +- When substantial contributions are added to a file (such as + substantial patches) the author/contributor should be added to the + list of copyright holders for the file. +- If there is uncertainty about whether a change is proper to + contribute to the code base, please seek more information from the + project steering committee, or the foundation legal counsel. + +Additional Resources +-------------------- + +- `General GitHub documentation `__ +- `GitHub pull request + documentation `__ + +Acknowledgements +---------------- + +The *code contribution* section of this CONTRIBUTING file is inspired by +`PDAL's `__ +and the *legalese* section is modified from `GDAL contributer +guidelines `__ + diff --git a/docs/source/index.rst b/docs/source/index.rst index 21d709473d..c70cdced2d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -41,6 +41,7 @@ Documentation htpd development/index faq + contributing download glossary license From 5dc4fb39db01bf06945b063116c10af7661a7999 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 4 Sep 2017 22:32:20 +0200 Subject: [PATCH 05/43] Added more pages to 'development' chapter. Moved old API description to section named 'deprecated'. Created a quickstart page for the development chapter. Scaffolding in place for the rest of the chapter. --- docs/source/development/errorhandling.rst | 7 ++ docs/source/development/index.rst | 7 +- docs/source/development/quickstart.rst | 100 ++++++++++++++++++ .../development/reference/datatypes.rst | 8 ++ .../{api.rst => reference/deprecated.rst} | 2 +- .../development/reference/functions.rst | 7 ++ docs/source/development/reference/index.rst | 12 +++ docs/source/development/threads.rst | 5 - docs/source/development/transformations.rst | 7 ++ examples/pj_obs_api_mini_demo.c | 4 +- 10 files changed, 150 insertions(+), 9 deletions(-) create mode 100644 docs/source/development/errorhandling.rst create mode 100644 docs/source/development/quickstart.rst create mode 100644 docs/source/development/reference/datatypes.rst rename docs/source/development/{api.rst => reference/deprecated.rst} (99%) create mode 100644 docs/source/development/reference/functions.rst create mode 100644 docs/source/development/reference/index.rst create mode 100644 docs/source/development/transformations.rst diff --git a/docs/source/development/errorhandling.rst b/docs/source/development/errorhandling.rst new file mode 100644 index 0000000000..58199e3f87 --- /dev/null +++ b/docs/source/development/errorhandling.rst @@ -0,0 +1,7 @@ +.. _errorhandling: + +================================================================================ +Error handling +================================================================================ + + diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 2e6e5622c2..9f5c8d89b0 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -5,13 +5,16 @@ Development ================================================================================ These pages are primarily focused towards developers either contributing to the -proj.4 project or using the library in their own software. +PROJ.4 project or using the library in their own software. .. toctree:: :maxdepth: 1 - api + quickstart + transformations + errorhandling threads + reference/index bindings diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst new file mode 100644 index 0000000000..7137d85a59 --- /dev/null +++ b/docs/source/development/quickstart.rst @@ -0,0 +1,100 @@ +.. _dev_quickstart: + +================================================================================ +Quick start +================================================================================ + +This is a short introduction to the PROJ.4 API. In the following section we +create a simple program that transforms a geodetic coordinate to UTM and back +again. The program is explained a few lines at a time. The complete program can +be seen at the end of the section. + +See the following sections for more in-depth descriptions of different parts of +the PROJ.4 API or consult the :doc:`API reference ` for specifics. + +Before the PROJ.4 API can be used it is necessary to include the ``proj.h`` header +file. Here ``stdio.h`` is also included so we can print some text to the screen: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 39-40 + +Let's declare a few variables that'll be used later in the program. Each variable +will be discussed below. +See the :doc:`reference for more info on data types `. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 43-45 + :dedent: 4 + +For use in multi-threaded programs the ``PJ_CONTEXT`` threading-context is used. +In this particular example it is not needed, but for the sake of completeness +it created here. The section on :doc:`threads ` discusses +this in detail. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 48 + :dedent: 4 + +Next we create the ``PJ`` transformation object ``P`` with the function +``proj_create``. ``proj_create`` takes the threading context ``C`` created above, +and a proj-string that defines the desired transformation. Here we transform +from geodetic coordinate to UTM zone 32N. +It is recommended to create one threading-context per thread used by the program. +This ensures that all ``PJ`` objects created in the same context will be sharing +resources such as error-numbers and loaded grids. +In case the creation of the ``PJ`` object fails an error message is displayed and +the program returns. See :doc:`errorhandling` for further +details. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 50-52 + :dedent: 4 + +PROJ.4 uses it's own data structures for handling coordinates. Here we use a +``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note +that the input values are converted to radians with ``proj_torad``. This is +necessary since PROJ.4 is using radians internally. See :doc:`transformations` +for further details. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 56 + :dedent: 4 + +The coordinate defined above is transformed with ``proj_trans_coord``. For this +a ``PJ`` object, a transformation direction (either forward or inverse) and the +coordinate is needed. The transformed coordinate is returned in ``b``. +Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 59-60 + :dedent: 4 + +The inverse transformation (UTM to geodetic) is done similar to above, +this time using ``PJ_INV`` as the direction. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 61-62 + :dedent: 4 + +Before ending the program the allocated memory needs to be released again: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 65-66 + :dedent: 4 + + +A complete compilable version of the above can be seen here: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :linenos: + :lines: 39- + diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst new file mode 100644 index 0000000000..193ec2382a --- /dev/null +++ b/docs/source/development/reference/datatypes.rst @@ -0,0 +1,8 @@ +.. _datatypes: + +================================================================================ +Data types +================================================================================ + + + diff --git a/docs/source/development/api.rst b/docs/source/development/reference/deprecated.rst similarity index 99% rename from docs/source/development/api.rst rename to docs/source/development/reference/deprecated.rst index 356f32b581..c748d461f6 100644 --- a/docs/source/development/api.rst +++ b/docs/source/development/reference/deprecated.rst @@ -1,7 +1,7 @@ .. _api: ******************************************************************************** -API +Deprecated API ******************************************************************************** .. contents:: Contents diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst new file mode 100644 index 0000000000..3ceffb5b3b --- /dev/null +++ b/docs/source/development/reference/functions.rst @@ -0,0 +1,7 @@ +.. _functions: + +================================================================================ +Functions +================================================================================ + + diff --git a/docs/source/development/reference/index.rst b/docs/source/development/reference/index.rst new file mode 100644 index 0000000000..9e92384cfe --- /dev/null +++ b/docs/source/development/reference/index.rst @@ -0,0 +1,12 @@ +.. _reference: + +================================================================================ +Reference +================================================================================ + +.. toctree:: + :maxdepth: 1 + + datatypes + functions + deprecated diff --git a/docs/source/development/threads.rst b/docs/source/development/threads.rst index 3307240808..a557fa07f6 100644 --- a/docs/source/development/threads.rst +++ b/docs/source/development/threads.rst @@ -4,11 +4,6 @@ Threads ================================================================================ -.. contents:: Contents - :depth: 3 - :backlinks: none - - This page is about efforts to make PROJ.4 thread safe. Key Thread Safety Issues diff --git a/docs/source/development/transformations.rst b/docs/source/development/transformations.rst new file mode 100644 index 0000000000..b03ce36876 --- /dev/null +++ b/docs/source/development/transformations.rst @@ -0,0 +1,7 @@ +.. _dev_transformations: + +================================================================================ +Transformations +================================================================================ + + diff --git a/examples/pj_obs_api_mini_demo.c b/examples/pj_obs_api_mini_demo.c index 855c37f803..340214886a 100644 --- a/examples/pj_obs_api_mini_demo.c +++ b/examples/pj_obs_api_mini_demo.c @@ -31,6 +31,9 @@ and destructor may be left out, and the default context selected by passing a null-pointer to pj_create. + Note: This file is in-lined in the documentation. Any changes must be + reflected in docs/source/development/quickstart.rst + Thomas Knudsen, 2016-10-30/2017-07-06 *******************************************************************************/ #include @@ -53,7 +56,6 @@ int main (void) { a = proj_coord (proj_torad(12), proj_torad(55), 0, 0); /* transform to UTM zone 32, then back to geographical */ - /* note the use of union selectors to indicate what kind of coordinates are expected */ b = proj_trans_coord (P, PJ_FWD, a); printf ("easting: %g, northing: %g\n", b.en.e, b.en.n); b = proj_trans_coord (P, PJ_INV, b); From 3cb1c28f116283e7ab3cde15ebe119a3bb96564a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 5 Sep 2017 22:21:18 +0200 Subject: [PATCH 06/43] Added data types reference section. --- .../development/reference/datatypes.rst | 883 ++++++++++++++++++ docs/source/index.rst | 2 +- 2 files changed, 884 insertions(+), 1 deletion(-) diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 193ec2382a..991fcfc5c0 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -4,5 +4,888 @@ Data types ================================================================================ +This section describe the multiplude of data types in use in PROJ.4. As a rule +of thumb PROJ.4 data types are prefixed with ``PJ_``, or in one particular case, +is simply called :c:type:`PJ`. A few notable exceptions can be traced +back to the very early days of PROJ.4 when the ``PJ_`` prefix was not +consistenly used. +Transformation objects +-------------------------------------------------------------------------------- +.. c:type:: PJ + + Object containing everything related to a given projection or transformation. + As a user of the PROJ.4 library your are only exposed to pointers to this + object and the contents are hidden in the public API. :c:type:`PJ` objects + are created with :c:func:`proj_create` and destroyed with + :c:func:`proj_destroy`. + +.. c:type:: PJ_CONTEXT + + Context objects enables safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` + object is connected to a context (if not specified, the default context is + used). All operations within a context should be performed in the same thread. + :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` + and destroyed with :c:func:`proj_context_destroy`. + +2 dimensional coordinates +-------------------------------------------------------------------------------- + +Various 2-dimensional coordinate data types. + +.. c:type:: LP + + Geodetic coordinate, latitude and longitude. Usually in radians. + + .. code-block:: C + + typedef struct { double lam, phi; } LP; + + .. c:member:: double LP.lam + + Longitude. Lambda. + + .. c:member:: double LP.phi + + Latitude. Phi. + + +.. c:type:: XY + + 2-dimensional cartesian coordinate. + + .. code-block:: C + + typedef struct { double x, y; } XY; + + + .. c:member:: double XY.lam + + Easting. + + .. c:member:: double XY.phi + + Northing. + + +.. c:type:: UV + + 2-dimensional generic coordinate. Usually used when contents can be either + a :c:type:`XY` or :c:type:`UV`. + + .. code-block:: C + + typedef struct {double u, v; } UV; + + + .. c:member:: double UV.u + + Longitude or easting, depending on use. + + .. c:member:: double UV.v + + Latitude or northing, depending on use. + + +.. c:type:: PJ_EN + + Generic easting/northing coordinate. + + .. code-block:: C + + typedef struct { double e, n; } PJ_EN; + + .. c:member:: double PJ_EN.e + + Easting + + .. c:member:: double PJ_EN.n + + Northing + +3 dimensional coordinates +-------------------------------------------------------------------------------- + +The following data types are the 3-dimensional equivalents to the data +types above. + +.. c:type:: LPZ + + 3-dimensional version of :c:type:`LP`. Holds longitude, latitude and + vertical component. + + .. code-block:: C + + typedef struct { double lam, phi, z; } LPZ; + + .. c:member:: double LPZ.lam + + Longitude. Lambda. + + .. c:member:: double LPZ.phi + + Latitude. Phi. + + .. c:member:: double LPZ.z + + Vertical component. + + +.. c:type:: XYZ + + Cartesian coordinate in 3 dimensions. Extension of :c:type:`XY`. + + .. code-block:: C + + typedef struct { double x, y, z; } XYZ; + + .. c:member:: double XYZ.x + + Easting. + + .. c:member:: double XYZ.y + + Northing. + + .. c:member:: double XYZ.z + + Vertical component. + + +.. c:type:: UVW + + 3-dimensional extension of :c:type:`UV`. + + .. code-block:: C + + typedef struct {double u, v, w; } UVW; + + .. c:member:: double UVW.u + + Longitude or easting, depending on use. + + .. c:member:: double UVW.v + + Latitude or northing, depending on use. + + .. c:member:: double UVW.w + + Vertical component. + + +.. c:type:: PJ_ENH + + Easting, northing and height. + + .. code-block:: C + + typedef struct {double e, n, h; } PJ_ENH; + + .. c:member:: double PJ_ENH.e + + Easting + + .. c:member:: double PJ_ENH.n + + Northing + + .. c:member:: double PJ_ENH.h + + Height + + +Spatiotemporal coordinate types +-------------------------------------------------------------------------------- + +The following data types are extensions of the triplets above into the time +domain. + + +.. c:type:: PJ_LPZT + + Spatiotemporal version of :c:type:`LPZ`. + + .. code-block:: C + + typedef struct { + double lam; + double phi; + double z; + double t; + } PJ_LPZT; + + + .. c:member:: double PJ_LPZT.lam + + Longitude. + + .. c:member:: double PJ_LPZT.phi + + Latitude + + .. c:member:: double PJ_LPZT.z + + Vertical component. + + .. c:member:: double PJ_LPZT.t + + Time component. + +.. c:type:: PJ_XYZT + + Generic spatiotemporal coordinate. Usefull for e.g. cartesian coordinates with + an attached time-stamp. + + .. code-block:: C + + typedef struct { + double x; + double y; + double z; + double t; + } PJ_XYZT; + + + .. c:member:: double PJ_XYZT.x + + Easting. + + .. c:member:: double PJ_XYZT.y + + Northing. + + .. c:member:: double PJ_XYZT.z + + Vertical component. + + .. c:member:: double PJ_XYZT.t + + Time component. + + +.. c:type:: PJ_UVWT + + Spatiotemporal version of :c:type:`PJ_UVW`. + + .. code-block:: C + + typedef struct { double u, v, w, t; } PJ_UVWT; + + .. c:member:: double PJ_UVWT.e + + First horizontal component. + + .. c:member:: double PJ_UVWT.n + + Second horizontal component. + + .. c:member:: double PJ_UVWT.w + + Vertical component. + + .. c:member:: double PJ_UVWT.t + + Temporal component. + + + +.. c:type:: PJ_ENHT + + Spatiotemporal version of :c:type:`PJ_ENH`. + + .. code-block:: C + + typedef struct {double e, n, h, t; } PJ_ENHT; + + .. c:member:: double PJ_ENHT.e + + Easting + + .. c:member:: double PJ_ENHT.n + + Northing + + .. c:member:: double PJ_ENHT.h + + Height + + .. c:member:: double PJ_ENHT.t + +Ancillary types for geodetic computations +-------------------------------------------------------------------------------- + + +.. c:type:: PJ_OPK + + Rotations, for instance three euler angles. + + .. code-block:: C + + typedef struct { double o, p, k; } PJ_OPK; + + .. c:member:: double PJ_OPK.o + + First rotation angle, omega. + + .. c:member:: double PJ_OPK.p + + Second rotation angle, phi. + + .. c:member:: double PJ_OPK.k + + Third rotation angle, kappa. + + +.. c:type:: PJ_DMS + + Describe a longitude or latitude by degrees, minutes and seconds. + + .. code-block:: C + + typedef struct { double d, m, s; } PJ_DMS; + + .. c:member:: double PJ_DMS.d + + Degrees. + + .. c:member:: double PJ_DMS.m + + Minutes + + .. c:member:: double PJ_DMS.s + + Seconds. + + +.. c:type:: PJ_EZN + + Geoid undulation and deflections of the vertical. + + .. code-block:: C + + typedef struct { double e, z, N; } PJ_EZN; + + .. c:member:: double PJ_EZN.e + + Deflection of the vertical, eta. + + .. c:member:: double PJ_EZN.z + + Deflection of the vertical, zeta + + .. c:member:: double PJ_EZN.N + + Geoid undulation. + + +.. c:type:: PJ_AF + + Ellipsoidal parameters. + + .. code-block:: C + + typedef struct {double a, f; } PJ_AF; + + .. c:member:: double PJ_AF.a + + Major axis of ellipsoid. + + .. c:member:: double PJ_AF.f + + Flattening of ellipsoid. + + +Complex coordinate types +-------------------------------------------------------------------------------- + +.. c:type:: PJ_PAIR + + .. code-block:: C + + typedef union { + XY xy; + LP lp; + UV uv; + PJ_AF af; + PJ_EN en; + double v[2]; + } PJ_PAIR; + + .. c:member:: XY PJ_PAIR.xy + + Coordinate in projected space. + + .. c:member:: LP PJ_PAIR.lp + + Coordinate in lat/long space. + + .. c:member:: UV PJ_PAIR.uv + + Coordinate either in lat/lon or projected space. + + .. c:member:: PJ_AF PJ_PAIR.af; + + Ellipsoidal parameters. + + .. c:member:: PJ_EN PJ_PAIR.en + + Easting/Northing pair. + + .. c:member:: double PJ_PAIR.v[2] + + Generic 2D-vector. + +.. c:type:: PJ_TRIPLET + + Union type that groups all coordinate data types of two and tree dimensions. + + .. code-block:: C + + typedef union { + PJ_OPK opk; + PJ_ENH enh; + PJ_EZN ezn; + PJ_DMS dms; + double v[3]; + XYZ xyz; + LPZ lpz; + UVW uvw; + XY xy; + LP lp; + UV uv; + PJ_AF af; + } PJ_TRIPLET; + + .. c:member:: PJ_OPK PJ_TRIPLET.opk + + Rotations. + + .. c:member:: PJ_ENH PJ_TRIPLET.enh + + Easting, northing and height. + + .. c:member:: PJ_EZN PJ_TRIPLET.ezn + + Geoid undulation and deflections of the vertical. + + .. c:member:: PJ_DMS PJ_TRIPLET.dsm + + Degrees, minutes and seconds. + + .. c:member:: double PJ_TRIPLET.v[3] + + Generic 3-dimensional vector. + + .. c:member:: XYZ PJ_TRIPLET.xyz + + Coordinates in projected space. + + .. c:member:: LPZ PJ_TRIPLET.lpz + + Geodetic coordinates, including height. + + .. c:member:: UVW PJ_TRIPLET.uvw + + Either geodetic or projected coordinates. + + .. c:member:: XY PJ_TRIPLET.xy + + Horizontal coordinates in projected space. + + .. c:member:: LP PJ_TRIPLET.lp + + Geodetic coordinates. + + .. c:member:: UV PJ_TRIPLET.uv + + Geodetic or projected coordinate. + + .. c:member:: PJ_AF PJ_TRIPLET.af + + Ellipsoidal paramaters. + +.. c:type:: PJ_COORD + + General purpose coordinate union type usefull in two, three and four dimensions. + + .. code-block:: C + + typedef union { + PJ_XYZT xyzt; + PJ_UVWT uvwt; + PJ_ENHT enht; + PJ_LPZT lpzt; + PJ_ENH enh; + PJ_EN en; + double v[4]; + XYZ xyz; + UVW uvw; + LPZ lpz; + XY xy; + UV uv; + LP lp; + } PJ_COORD ; + + .. c:member:: PJ_XYZT PJ_COORD.xyzt + + Spatiotemporal cartesian coordinate. + + .. c:member:: PJ_UVWT PJ_COORD.uvwt + + Spatiotemporal generic coordinate. + + .. c:member:: PJ_ENHT PJ_COORD.enht + + Easting, northing, height and time. + + .. c:member:: PJ_LPZT PJ_COORD.lpzt + + Longitude, latitude, vertical and time components. + + .. c:member:: PJ_ENH PJ_COORD.enh + + Easting, northing and height + + .. c:member:: PJ_EN PJCOORD.en + + Easting and northing. + + .. c:member:: double v[4] + + Generic four-dimensional vector. + + .. c:member:: XYZ PJ_COORD.xyz + + 3-dimensional cartesian coordinate. + + .. c:member:: UVW PJ_COORD.uvw + + 3-dimensional generic coordinate. + + .. c:member:: LPZ PJ_COORD.lpz + + Longitude, latitude and vertical component. + + .. c:member:: XY PJ_COORD.xy + + 2-dimensional cartesian coordinate. + + .. c:member:: UV PJ_COORD.uv + + 2-dimensional generic coordinate. + + .. c:member:: LP PJ_COORD.lp + + Longitude and latitude. + + +.. c:type:: PJ_OBS + + Geodetic observation data type. + + .. code-block:: C + + typedef struct { + PJ_COORD coo; + PJ_TRIPLET anc; + int id; + unsigned int flags; + } PJ_OBS; + + .. c:member:: PJ_COORD PJ_OBS.coo + + Coordinate data + + .. c:member:: PJ_TRIPLET PJ_OBS.anc + + Ancillary data + + .. c:member:: int PJ_OBS.id + + Integer ancillary data, e.g. observation number, EPSG code, etc. + + .. c:member:: unsigned int PJ_OBS.flags + + Additional data intended for flags. + + +Projection derivatives +------------------------------------------------------------------------------- + +.. c:type:: PJ_DERIVS + + Partial derivatives of geodetic coordinate :math:`\left(\lambda,\phi\right)`. + Calculated with :c:func:`proj_derivatives`. + + .. code-block:: C + + typedef struct { + double x_l, x_p; + double y_l, y_p; + } PJ_DERIVS; + + .. c:member:: double PJ_DERIVS.x_l + + :math:`\frac{\partial x}{\partial \lambda}` + + .. c:member:: double PJ_DERIVS.x_p + + :math:`\frac{\partial x}{\partial \phi}` + + .. c:member:: double PJ_DERIVS.y_l + + :math:`\frac{\partial y}{\partial \lambda}` + + .. c:member:: double PJ_DERIVS.y_p + + :math:`\frac{\partial y}{\partial \phi}` + + +.. c:type:: PJ_FACTORS + + Various cartographic properties, such as scale factors, angular distortion + and meridian convergence. Calculated with :c:func:`proj_factors`. Depending + on the underlying projection, values can be calculated either numerically + or analytically. + + .. code-block:: C + + typedef struct { + struct PJ_DERIVS der; + double h, k; + double omega, thetap; + double conv; + double s; + double a, b; + int code; + } PJ_FACTORS; + + .. c:member:: PJ_DERIVS PJ_FACTORS.der + + Partial derivatives of coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.h + + Meridian scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.k + + Parallel scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.omega + + Angular distortion at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.thetap + + Meridian/parallel angle, :math:`\theta^\prime`, at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.conv + + Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. + Sometimes also described as *grid declination*. + + .. c:member:: double PJ_FACTORS.s + + Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.a + + Maximum scale error. + + .. c:member:: double PJ_FACTORS.b + + Minimum scale error. + + .. c:member:: int code + + Bitmask determing if calculation of various factors was done numerically + or analytically. If a bit flags is set the calculation was done analytically. + The following bit flags exists: + + .. c:macro:: PJ_IS_ANAL_XL_YL + + Longitude derivatives are calculated analytically + + .. c:macro:: PJ_IS_ANAL_XP_YP + + Latitude derivatives are calculated analyticall. + + .. c:macro:: PJ_IS_ANAL_HK + + Meridinal and parallel scale factors are calculated analytically. + + .. c:macro:: PJ_IS_ANAL_CONV + + Meridian convergence calculated analytically. + + +Info structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_INFO + + Struct holding information about the current instance of PROJ.4. Struct is + populated by :c:func:`proj_info`. + + .. code-block:: C + + typedef struct { + char release[64]; + char version[64]; + int major; + int minor; + int patch; + char searchpath[512]; + } PJ_INFO; + + .. c:member:: char PJ_INFO.release[64] + + Release info. Version number and release date, + e.g. "Rel. 4.9.3, 15 August 2016". + + .. c:member:: char PJ_INFO.version[64] + + Text representation of the full version number, + e.g. "4.9.3". + + .. c:member:: int PJ_INFO.major + + Major version number. + + .. c:member:: int PJ_INFO.minor + + Minor version number. + + .. c:member:: int PJ_INFO.patch + + Patch level of release. + + .. c:member:: char PJ_INFO.searchpath[512] + + Search path for PROJ.4. List of directories separated by + semicolons, e.g. "C:\Users\doctorwho;C:\OSGeo4W64\\share\proj". + Grids and init files are looked for in directories in the search path. + +.. c:type:: PJ_PROJ_INFO + + Struct holding information about a :c:type:`PJ` object. Populated by + :c:func:`proj_pj_info`. + + .. code-block:: C + + typedef struct { + char id[16]; + char description[128]; + char definition[512]; + int has_inverse; + } PJ_PROJ_INFO; + + .. c:member:: char PJ_PROJ_INFO.id[16] + + Short ID of the operation the :c:type:`PJ` object is based on, that is, + what comes afther the ``+proj=`` in a proj-string, e.g. "*merc*". + + .. c:member:: char PJ_PROJ_INFO.description[128] + + Long describes of the operation the :c:type:`PJ` object is based on, + e.g. "*Mercator Cyl, Sph&Ell lat_ts=*". + + .. c:member:: char PJ_PROJ_INFO.definition[512] + + The proj-string that was used to create the :c:type:`PJ` object with, + e.g. "*+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84*". + + .. c:member:: int PJ_PROJ_INFO.has_inverse + + 1 if an inverse mapping of the defined operation exists, otherwise 0. + +.. c:type:: PJ_GRID_INFO + + Struct holding information about a specific grid in the search path of + PROJ.4. Populated with the function :c:func:`proj_grid_info`. + + .. code-block:: C + + typedef struct { + char gridname[32]; + char filename[260]; + char format[8]; + LP lowerleft; + LP upperright; + int n_lon, n_lat; + double cs_lon, cs_lat; + } PJ_GRID_INFO; + + .. c:member:: char PJ_GRID_INFO.gridname[32] + + Name of grid, e.g. "*BETA2007.gsb*". + + .. c:member:: char PJ_GRID_INFO + + Full path of grid file, e.g. "*C:\OSGeo4W64\\share\proj\BETA2007.gsb*" + + .. c:member:: char PJ_GRID_INFO.format[8] + + File format of grid file, e.g. "*ntv2*" + + .. c:member:: LP PJ_GRID_INFO.lowerleft + + Geodetic coordinate of lower left corner of grid. + + .. c:member:: LP PJ_GRID_INFO.upperright + + Geodetic coordinate of upper right corner of grid. + + .. c:member:: int PJ_GRID_INFO.n_lon + + Number of grid cells in the longitudinal direction. + + .. c:member:: int PJ_GRID_INFO.n_lat + + Number of grid cells in the latitudianl direction. + + .. c:member:: double PJ_GRID_INFO.cs_lon + + Cell size in the longitudinal direction. In radians. + + .. c:member:: double PJ_GRID_INFO.cs_lat + + Cell size in the latitudinal direction. In radians. + + +.. c:type:: PJ_INIT_INFO + + Struct holding information about a specific init file in the search path of + PROJ.4. Populated with the function :c:func:`proj_init_info`. + + .. code-block:: C + + typedef struct { + char name[32]; + char filename[260]; + char version[32]; + char origin[32]; + char lastupdate[16]; + } PJ_INIT_INFO; + + .. c:member:: char PJ_INIT_INFO.name[32] + + Name of init file, e.g. "*epsg*". + + .. c:member:: char PJ_INIT_INFO.filename[260] + + Full path of init file, e.g. "*C:\OSGeo4W64\share\proj\epsg*" + + .. c:member:: char PJ_INIT_INFO.version[32] + + Version number of init-file, e.g. "*9.0.0*" + + .. c:member:: char PJ_INIT_INFO.origin[32] + + Originating entity of the init file, e.g. "*EPSG*" + + .. c:member:: char PJ_INIT_INFO.lastupdate + + Date of last update of the init-file. diff --git a/docs/source/index.rst b/docs/source/index.rst index c70cdced2d..bfb9aee6cf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -50,7 +50,7 @@ Documentation Mailing List ================================================================================ -The Proj.4 mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj +The PROJ.4 mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj Indices and tables ================== From 1f60b8c407ac202916cf4570683935fcca451531 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 12 Sep 2017 16:42:02 +0200 Subject: [PATCH 07/43] Added functions API reference --- .../development/reference/functions.rst | 433 ++++++++++++++++++ 1 file changed, 433 insertions(+) diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 3ceffb5b3b..fc546f3340 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -4,4 +4,437 @@ Functions ================================================================================ +Threading contexts +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. c:function:: PJ_CONTEXT* proj_context_create(void) + + Create a new threading-context. + + :returns: :c:type:`PJ_CONTEXT*` + +.. c:function:: void proj_context_destroy(PJ_CONTEXT *ctx) + + Deallacote a threading-context. + + :param PJ_CONTEXT* ctx: Threading context. + +Transformation setup +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition) + + Create a transformation object from a proj-string. + + Example call: + + .. code-block:: C + + PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel"); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context. + :param `definition`: Proj-string of the desired transformation. + :type `definition`: const char* + + +.. c:function:: PJ* proj_create_argv(PJ_CONTEXT *ctx, int argc, char **argv) + + Create transformation object with argc/argv-style initialization. For this + application each parameter in the defining proj-string is an entry in :c:data:`argv`. + + Example call: + + .. code-block:: C + + char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"}; + PJ* P = proj_create_argv(0, 3, args); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context + :param int argc: Count of arguments in :c:data:`argv` + :param char** argv: Vector of strings with proj-string parameters, e.g. ``+proj=merc`` + :returns: :c:type:`PJ*` + +.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to) + + Create a transformation object that is a pipeline between two known + coordinate reference systems. + + :c:data:`srid_from` and :c:data:`srid_to` should be the value part of a ``+init=...`` parameter + set, i.e. "epsg:25833" or "IGNF:AMST63". Any projection definition that + can be found in a init-file in :envvar:`PROJ_LIB` is a valid input to this function. + + For now the function mimics the cs2cs app: An input and an output CRS is + given and coordinates are transformed via a hub datum (WGS84). This + transformation strategy is referred to as "early-binding" by the EPSG. The + function can be extended to support "late-binding" transformations in the + future without affecting users of the function. + + Example call: + + .. code-block:: C + + PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833"); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context. + :param `srid_from`: Source SRID. + :type `srid_from`: const char* + :param `srid_to`: Destination SRID. + :type `srid_to`: const char* + :returns: :c:type:`PJ*` + +.. c:function:: PJ* proj_destroy(PJ *P) + + Deallocate a :c:type:`PJ` transformation object. + + :param PJ* P: + :returns: :c:type:`PJ*` + +Coordinate transformation +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_COORD proj_trans_coord(PJ *P, enum proj_direction direction, PJ_COORD coord) + + Transform a single :c:type:`PJ_COORD` coordinate. + + :param PJ* P: + :param `direction`: Transformation direction. + :type `direction`: enum proj_direction + :param PJ_COORD coord: Coordinate that will be transformed. + :returns: :c:type:`PJ_COORD` + + +.. c:function:: PJ_OBS proj_trans_obs(PJ *P, enum proj_direction direction, PJ_OBS obs) + + Transform a single :c:type:`PJ_OBS` observation. + + :param PJ* P: + :param `direction`: Transformation direction. + :type `direction`: enum proj_direction + :param PJ_OBS obs: Observation data to transform. + :returns: :c:type:`PJ_OBS` + + + +.. c:function:: size_t proj_transform(PJ *P, enum proj_direction direction, \ + double *x, size_t sx, size_t nx, double *y, \ + size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ + double *t, size_t st, size_t nt) + + Transform a series of coordinates, where the individual coordinate dimension + may be represented by an array that is either + + 1. fully populated + 2. a null pointer and/or a length of zero, which will be treated as a + fully populated array of zeroes + 3. of length one, i.e. a constant, which will be treated as a fully + populated array of that constant value + + The strides, :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, + represent the step length, in bytes, between + consecutive elements of the corresponding array. This makes it possible for + :c:func:`proj_transform` to handle transformation of a large class of application + specific data structures, without necessarily understanding the data structure + format, as in: + + .. code-block:: C + + typedef struct { + double x, y; + int quality_level; + char surveyor_name[134]; + } XYQS; + + XYQS survey[345]; + double height = 23.45; + size_t stride = sizeof (XYQS); + + ... + + proj_transform ( + P, PJ_INV, sizeof(XYQS), + &(survey[0].x), stride, 345, /* We have 345 eastings */ + &(survey[0].y), stride, 345, /* ...and 345 northings. */ + &height, 1, /* The height is the constant 23.45 m */ + 0, 0 /* and the time is the constant 0.00 s */ + ); + + This is similar to the inner workings of the deprecated pj_transform function, but the + stride functionality has been generalized to work for any size of basic unit, + not just a fixed number of doubles. + + In most cases, the stride will be identical for x, y, z, and t, since they will + typically be either individual arrays (stride = sizeof(double)), or strided + views into an array of application specific data structures (stride = sizeof (...)). + + But in order to support cases where :c:data:`x`, :c:data:`y`, :c:data:`z`, + and :c:data:`t` come from heterogeneous sources, individual strides, + :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, are used. + + .. note:: Since :c:func:`proj_transform` does its work *in place*, this means that even the + supposedly constants (i.e. length 1 arrays) will return from the call in altered + state. Hence, remember to reinitialize between repeated calls. + + :param PJ* P: Transformation object + :param `direction`: Transformation direction + :type `enum proj_direction`: + :param double* x: Array of x-coordinates + :param double* y: Array of y-coordinates + :param double* z: Array of z-coordinates + :param double* t: Array of t-coordinates + :param size_t sx: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nx: Number of elements in the corresponding array + :param size_t sy: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nv: Number of elements in the corresponding array + :param size_t sz: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nz: Number of elements in the corresponding array + :param size_t st: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nt: Number of elements in the corresponding array + :returns: Number of transformations succesfully completed + + + +.. c:function:: size_t proj_transform_coord(PJ *P, enum proj_direction direction, size_t n, PJ_COORD *coord) + + Batch transform an array of :c:type:`PJ_COORD`. + + :param PJ* P: + :param `direction`: Transformation direction + :type `direction`: enum proj_direction + :param size_t n: Number of cordinates in :c:data:`coord` + :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number + +.. c:function:: size_t proj_transform_obs(PJ *P, enum proj_direction direction, size_t n, PJ_OBS *obs) + + Batch transform an array of :c:type:`PJ_OBS`. + + :param PJ* P: + :param `direction`: Transformation direction + :type `direction`: enum proj_direction + :param size_t n: Number of observations in :c:data:`obs` + :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number + + +Initializers +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) + + Initializer for the :c:type:`PJ_COORD` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; + + or + + .. code-block:: C + + PJ_COORD c; + // Assign using the PJ_XYZT struct in the union + c.xyzt.x = 10.0; + c.xyzt.y = 20.0; + c.xyzt.z = 30.0; + c.xyzt.t = 40.0; + + Since :c:type:`PJ_COORD` is a union of structs, the above assignment can + also be expressed in terms of the other types in the union, e.g. + :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. + + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :returns: :c:type:`PJ_COORD` + +.. c:function:: PJ_OBS proj_obs(double x, double y, double z, double t,\ + double o, double p, double k,\ + int id, unsigned int flags) + + Initializer for the :c:type:`PJ_OBS` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_OBS c = {{{1.0, 2.0, 3.0, 4.0}}, {{5.0, 6.0, 7.0}}, 8, 9}; + + or + + .. code-block:: C + + PJ_OBS c; + // Assign using the PJ_COORD part of the struct in the union + o.coo.v[0] = 1.0; + o.coo.v[1] = 2.0; + o.coo.v[2] = 3.0; + o.coo.v[3] = 4.0; + o.anc.v[0] = 5.0; + o.anc.v[1] = 6.0; + o.anc.v[2] = 7.0; + o.id = 8; + o.flags = 9; + + which is a bit too verbose in most practical applications. + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :param double o: 1st component in a :c:type:`PJ_TRIPLET` + :param double p: 2nd component in a :c:type:`PJ_TRIPLET` + :param double k: 3rd component in a :c:type:`PJ_TRIPLET` + :param int id: Ancillary data, e.g. an ID + :param `flags`: Flags + :type `flags`: unsigned int + :returns: :c:type:`PJ_OBS` + +Info functions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_INFO proj_info(void) + + Get information about the current instance of the PROJ.4 library. + + :returns: :c:type:`PJ_INFO` + +.. c:function:: PJ_PROJ_INFO proj_pj_info(const PJ *P) + + Get information about a specific transformation object, :c:data:`P`. + + :param `P`: Transformation object + :type `P`: const PJ* + :returns: :c:type:`PJ_PROJ_INFO` + +.. c:function:: PJ_GRID_INFO proj_grid_info(const char *gridname) + + Get information about a specific grid. + + :param `gridname`: Gridname in the PROJ.4 searchpath + :type `gridname`: const char* + :returns: :c:type:`PJ_GRID_INFO` + +.. c:function:: PJ_INIT_INFO proj_init_info(const char *initname) + + Get information about a specific init file. + + :param `initname`: Init file in the PROJ.4 searchpath + :type `initname`: const char* + :returns: :c:type:`PJ_INIT_INFO` + + +Distances +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_lp_dist(PJ *P, LP a, LP b) + + Calculate geodesic distance between two points in geodetic coordinates. + + :param PJ* P: Transformation object + :param LP a: Coordinate of first point + :param LP b: Coordinate of second point + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xy_dist(XY a, XY, b) + + Calculate 2-dimensional euclidean between two projected coordinates. + + :param XY a: First coordinate + :param XY b: Second coordinate + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xyz_dist(XYZ a, XYZ b) + + Calculate 3-dimensional euclidean between two projected coordinates. + + :param XYZ a: First coordinate + :param XYZ b: Second coordinate + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + + +Various +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_roundtrip(PJ *P, enum proj_direction direction, int n, PJ_OBS obs) + + Measure internal consistency of a given transformation. The function + performs :c:data:`n` round trip transformations starting in either + the forward or reverse :c:data:`direction`. Returns the euclidean + distance of the starting point :c:data:`obs` and the resulting + coordinate after :c:data:`n` iterations back and forth. + + :param PJ* P: + :param `direction`: Starting direction of transformation + :type `direction`: enum proj_direction + :param int n: Number of roundtrip transformations + :param PJ_OBS obs: Input coordinate + :returns: :c:type:`double` Distance between original coordinate and the \ + resulting coordinate after :c:data:`n` transformation iterations. + +.. c:function:: PJ_DERIVS proj_derivatives(const PJ *P, const LP lp) + + Calculate partial derivatives of geodetic coordinates. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `lp`: Geodetic coordinate + :type `lp`: const LP + :returns: :c:type:`PJ_DERIVS` + +.. c:function:: PJ_FACTORS proj_factors(const PJ *P, const LP lp) + + Calculate various cartographic properties, such as scale factors, angular + distortion and meridian convergence. Depending on the underlying projection + values will be calculated either numerically (default) or analytically. + + The function also calculates the partial derivatives of the given + coordinate. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `lp`: Geodetic coordinate + :type `lp`: const LP + :returns: :c:type:`PJ_FACTORS` + +.. c:function:: double proj_torad(double angle_in_degrees) + + Convert degrees to radians. + + :param double angle_in_degrees: Degrees + :returns: :c:type:`double` Radians + +.. c:function:: double proj_todeg(double angle_in_radians) + + Convert radians to degrees + + :param double angle_in_radians: Radians + :returns: :c:type:`double` Degrees + +.. c:function:: double proj_dmstor(const char *is, char **rs) + + Convert string of degrees, minutes and seconds to radians. + Works similarly to the C standard library function :c:func:`strtod`. + + :param `is`: Value to be converted to radians + :type `is`: const char* + :param `rs`: Reference to an already allocated char*, whose value is \ + set by the function to the next character in :c:data:`is` \ + after the numerical value. + +.. c:function:: char *proj_rtodms(char *s, double r, int pos, int neg) + + Convert radians to string representation of degrees, minutes and seconds. + + :param char* s: Buffer that holds the output string + :param double r: Value to convert to dms-representation + :param int pos: Character denoting positive direction, typically `'N'` or `'E'`. + :param int neg: Character denoting negative direction, typically `'S'` or `'W'`. + :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) From 6d1a1ff4e470bb4d26be46bdf01de3d94e6ab8e9 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 18 Sep 2017 22:21:20 +0200 Subject: [PATCH 08/43] Moved projection list to using chapter and created a list of transformations. Both are grouped in a section called operations. --- docs/source/index.rst | 1 - docs/source/usage/index.rst | 1 + docs/source/usage/operations/index.rst | 18 ++++++++++ .../operations}/projections/aeqd.rst | 0 .../operations}/projections/airy.rst | 0 .../operations}/projections/aitoff.rst | 0 .../operations}/projections/alsk.rst | 0 .../operations}/projections/apian.rst | 0 .../operations}/projections/august.rst | 0 .../operations}/projections/bacon.rst | 0 .../operations}/projections/bipc.rst | 0 .../operations}/projections/boggs.rst | 0 .../operations}/projections/bonne.rst | 0 .../operations}/projections/calcofi.rst | 2 +- .../operations}/projections/cass.rst | 0 .../{ => usage/operations}/projections/cc.rst | 0 .../operations}/projections/cea.rst | 0 .../operations}/projections/chamb.rst | 0 .../operations}/projections/collg.rst | 0 .../operations}/projections/crast.rst | 0 .../operations}/projections/denoy.rst | 0 .../operations}/projections/eck1.rst | 0 .../operations}/projections/eck2.rst | 0 .../operations}/projections/eck3.rst | 0 .../operations}/projections/eck4.rst | 0 .../operations}/projections/eck5.rst | 0 .../operations}/projections/eck6.rst | 0 .../operations}/projections/eqc.rst | 0 .../operations}/projections/eqdc.rst | 0 .../operations}/projections/etmerc.rst | 0 .../operations}/projections/euler.rst | 0 .../operations}/projections/fahey.rst | 0 .../operations}/projections/fouc.rst | 0 .../operations}/projections/fouc_s.rst | 0 .../operations}/projections/gall.rst | 0 .../operations}/projections/geos.rst | 2 +- .../operations}/projections/gins8.rst | 0 .../operations}/projections/gn_sinu.rst | 0 .../operations}/projections/gnom.rst | 0 .../operations}/projections/goode.rst | 0 .../operations}/projections/gs48.rst | 0 .../operations}/projections/gs50.rst | 0 .../operations}/projections/gstmerc.rst | 0 .../operations}/projections/hammer.rst | 0 .../operations}/projections/hatano.rst | 0 .../operations}/projections/healpix.rst | 2 +- .../operations}/projections/igh.rst | 0 .../operations}/projections/images/aea.png | Bin .../operations}/projections/images/aeqd.png | Bin .../operations}/projections/images/airy.png | Bin .../operations}/projections/images/aitoff.png | Bin .../operations}/projections/images/alsk.png | Bin .../operations}/projections/images/apian.png | Bin .../operations}/projections/images/august.png | Bin .../operations}/projections/images/bacon.png | Bin .../operations}/projections/images/bipc.png | Bin .../operations}/projections/images/boggs.png | Bin .../operations}/projections/images/bonne.png | Bin .../projections/images/calcofi.png | Bin .../operations}/projections/images/cass.png | Bin .../operations}/projections/images/cc.png | Bin .../operations}/projections/images/cea.png | Bin .../operations}/projections/images/chamb.png | Bin .../operations}/projections/images/collg.png | Bin .../operations}/projections/images/comill.png | Bin .../operations}/projections/images/crast.png | Bin .../operations}/projections/images/denoy.png | Bin .../operations}/projections/images/eck1.png | Bin .../operations}/projections/images/eck2.png | Bin .../operations}/projections/images/eck3.png | Bin .../operations}/projections/images/eck4.png | Bin .../operations}/projections/images/eck5.png | Bin .../operations}/projections/images/eck6.png | Bin .../operations}/projections/images/eqc.png | Bin .../operations}/projections/images/eqdc.png | Bin .../operations}/projections/images/etmerc.png | Bin .../operations}/projections/images/euler.png | Bin .../operations}/projections/images/fahey.png | Bin .../operations}/projections/images/fouc.png | Bin .../operations}/projections/images/fouc_s.png | Bin .../operations}/projections/images/gall.png | Bin .../operations}/projections/images/geos.png | Bin .../operations}/projections/images/gins8.png | Bin .../projections/images/gn_sinu.png | Bin .../operations}/projections/images/gnom.png | Bin .../operations}/projections/images/goode.png | Bin .../operations}/projections/images/gs48.png | Bin .../operations}/projections/images/gs50.png | Bin .../projections/images/gstmerc.png | Bin .../operations}/projections/images/hammer.png | Bin .../operations}/projections/images/hatano.png | Bin .../projections/images/healpix.png | Bin .../operations}/projections/images/igh.png | Bin .../operations}/projections/images/imw_p.png | Bin .../operations}/projections/images/isea.png | Bin .../operations}/projections/images/kav5.png | Bin .../operations}/projections/images/kav7.png | Bin .../operations}/projections/images/krovak.png | Bin .../operations}/projections/images/labrd.png | Bin .../operations}/projections/images/laea.png | Bin .../operations}/projections/images/lagrng.png | Bin .../operations}/projections/images/larr.png | Bin .../operations}/projections/images/lask.png | Bin .../operations}/projections/images/lcc.png | Bin .../operations}/projections/images/lcca.png | Bin .../operations}/projections/images/leac.png | Bin .../operations}/projections/images/lee_os.png | Bin .../operations}/projections/images/loxim.png | Bin .../operations}/projections/images/lsat.png | Bin .../projections/images/mbt_fps.png | Bin .../operations}/projections/images/mbt_s.png | Bin .../operations}/projections/images/mbtfpp.png | Bin .../operations}/projections/images/mbtfpq.png | Bin .../operations}/projections/images/mbtfps.png | Bin .../operations}/projections/images/merc.png | Bin .../operations}/projections/images/mil_os.png | Bin .../operations}/projections/images/mill.png | Bin .../projections/images/misrsom.png | Bin .../operations}/projections/images/moll.png | Bin .../operations}/projections/images/murd1.png | Bin .../operations}/projections/images/murd2.png | Bin .../operations}/projections/images/murd3.png | Bin .../projections/images/natearth.png | Bin .../projections/images/natearth2.png | Bin .../operations}/projections/images/nell.png | Bin .../operations}/projections/images/nell_h.png | Bin .../operations}/projections/images/nicol.png | Bin .../operations}/projections/images/nsper.png | Bin .../operations}/projections/images/nzmg.png | Bin .../projections/images/ob_tran.png | Bin .../operations}/projections/images/ocea.png | Bin .../operations}/projections/images/oea.png | Bin .../operations}/projections/images/omerc.png | Bin .../operations}/projections/images/ortel.png | Bin .../operations}/projections/images/ortho.png | Bin .../projections/images/patterson.png | Bin .../operations}/projections/images/pconic.png | Bin .../operations}/projections/images/poly.png | Bin .../operations}/projections/images/putp1.png | Bin .../operations}/projections/images/putp2.png | Bin .../operations}/projections/images/putp3.png | Bin .../operations}/projections/images/putp3p.png | Bin .../operations}/projections/images/putp4p.png | Bin .../operations}/projections/images/putp5.png | Bin .../operations}/projections/images/putp5p.png | Bin .../operations}/projections/images/putp6.png | Bin .../operations}/projections/images/putp6p.png | Bin .../operations}/projections/images/qsc.png | Bin .../projections/images/qua_aut.png | Bin .../projections/images/rhealpix.png | Bin .../operations}/projections/images/robin.png | Bin .../operations}/projections/images/rouss.png | Bin .../operations}/projections/images/rpoly.png | Bin .../operations}/projections/images/sinu.png | Bin .../operations}/projections/images/somerc.png | Bin .../operations}/projections/images/stere.png | Bin .../operations}/projections/images/sterea.png | Bin .../operations}/projections/images/tcc.png | Bin .../operations}/projections/images/tcea.png | Bin .../operations}/projections/images/tissot.png | Bin .../operations}/projections/images/tmerc.png | Bin .../operations}/projections/images/tpeqd.png | Bin .../operations}/projections/images/tpers.png | Bin .../operations}/projections/images/ups.png | Bin .../operations}/projections/images/urm5.png | Bin .../operations}/projections/images/urmfps.png | Bin .../operations}/projections/images/utm.png | Bin .../operations}/projections/images/vandg.png | Bin .../operations}/projections/images/vandg2.png | Bin .../operations}/projections/images/vandg3.png | Bin .../operations}/projections/images/vandg4.png | Bin .../operations}/projections/images/vitk1.png | Bin .../operations}/projections/images/wag1.png | Bin .../operations}/projections/images/wag2.png | Bin .../operations}/projections/images/wag3.png | Bin .../operations}/projections/images/wag4.png | Bin .../operations}/projections/images/wag5.png | Bin .../operations}/projections/images/wag6.png | Bin .../operations}/projections/images/wag7.png | Bin .../operations}/projections/images/weren.png | Bin .../operations}/projections/images/wink1.png | Bin .../operations}/projections/images/wink2.png | Bin .../operations}/projections/images/wintri.png | Bin .../operations}/projections/imw_p.rst | 0 .../operations}/projections/index.rst | 0 .../operations}/projections/isea.rst | 0 .../operations}/projections/kav5.rst | 0 .../operations}/projections/kav7.rst | 0 .../operations}/projections/krovak.rst | 0 .../operations}/projections/labrd.rst | 0 .../operations}/projections/laea.rst | 0 .../operations}/projections/lagrng.rst | 0 .../operations}/projections/larr.rst | 0 .../operations}/projections/lask.rst | 0 .../operations}/projections/latlon.rst | 0 .../operations}/projections/lcc.rst | 0 .../operations}/projections/lcca.rst | 0 .../operations}/projections/leac.rst | 0 .../operations}/projections/lee_os.rst | 0 .../operations}/projections/lonlat.rst | 0 .../operations}/projections/loxim.rst | 0 .../operations}/projections/lsat.rst | 0 .../operations}/projections/mbt_fps.rst | 0 .../operations}/projections/mbt_s.rst | 0 .../operations}/projections/mbtfpp.rst | 0 .../operations}/projections/mbtfpq.rst | 0 .../operations}/projections/mbtfps.rst | 0 .../operations}/projections/merc.rst | 0 .../operations}/projections/mil_os.rst | 0 .../operations}/projections/mill.rst | 0 .../operations}/projections/moll.rst | 0 .../operations}/projections/murd1.rst | 0 .../operations}/projections/murd2.rst | 0 .../operations}/projections/murd3.rst | 0 .../operations}/projections/natearth.rst | 0 .../operations}/projections/nell.rst | 0 .../operations}/projections/nell_h.rst | 0 .../operations}/projections/nicol.rst | 0 .../operations}/projections/nsper.rst | 0 .../operations}/projections/nzmg.rst | 0 .../operations}/projections/ob_tran.rst | 0 .../operations}/projections/ocea.rst | 0 .../operations}/projections/oea.rst | 0 .../operations}/projections/omerc.rst | 0 .../operations}/projections/ortel.rst | 0 .../operations}/projections/ortho.rst | 0 .../operations}/projections/pconic.rst | 0 .../operations}/projections/poly.rst | 0 .../operations}/projections/putp1.rst | 0 .../operations}/projections/putp2.rst | 0 .../operations}/projections/putp3.rst | 0 .../operations}/projections/putp3p.rst | 0 .../operations}/projections/putp4p.rst | 0 .../operations}/projections/putp5.rst | 0 .../operations}/projections/putp5p.rst | 0 .../operations}/projections/putp6.rst | 0 .../operations}/projections/putp6p.rst | 0 .../operations}/projections/qsc.rst | 14 ++++---- .../operations}/projections/qua_aut.rst | 0 .../operations}/projections/rhealpix.rst | 2 +- .../operations}/projections/robin.rst | 0 .../operations}/projections/rouss.rst | 0 .../operations}/projections/rpoly.rst | 0 .../operations}/projections/sinu.rst | 0 .../operations}/projections/somerc.rst | 0 .../operations}/projections/stere.rst | 0 .../operations}/projections/sterea.rst | 0 .../operations}/projections/tcc.rst | 0 .../operations}/projections/tcea.rst | 0 .../operations}/projections/tissot.rst | 0 .../operations}/projections/tmerc.rst | 0 .../operations}/projections/tpeqd.rst | 0 .../operations}/projections/tpers.rst | 0 .../operations}/projections/ups.rst | 0 .../operations}/projections/urm5.rst | 0 .../operations}/projections/urmfps.rst | 0 .../operations}/projections/utm.rst | 0 .../operations}/projections/vandg.rst | 0 .../operations}/projections/vandg2.rst | 0 .../operations}/projections/vandg3.rst | 0 .../operations}/projections/vandg4.rst | 0 .../operations}/projections/vitk1.rst | 0 .../operations}/projections/wag1.rst | 0 .../operations}/projections/wag2.rst | 0 .../operations}/projections/wag3.rst | 0 .../operations}/projections/wag4.rst | 0 .../operations}/projections/wag5.rst | 0 .../operations}/projections/wag6.rst | 0 .../operations}/projections/wag7.rst | 0 .../operations}/projections/weren.rst | 0 .../operations}/projections/wink1.rst | 0 .../operations}/projections/wink2.rst | 0 .../operations}/projections/wintri.rst | 0 .../usage/operations/transformations/cart.rst | 24 +++++++++++++ .../operations/transformations/helmert.rst | 7 ++++ .../operations/transformations/hgridshift.rst | 32 +++++++++++++++++ .../operations/transformations/index.rst | 15 ++++++++ .../operations/transformations/molodensky.rst | 7 ++++ .../transformations/unitconvert.rst | 7 ++++ .../operations/transformations/vgridshift.rst | 34 ++++++++++++++++++ 280 files changed, 156 insertions(+), 12 deletions(-) create mode 100644 docs/source/usage/operations/index.rst rename docs/source/{ => usage/operations}/projections/aeqd.rst (100%) rename docs/source/{ => usage/operations}/projections/airy.rst (100%) rename docs/source/{ => usage/operations}/projections/aitoff.rst (100%) rename docs/source/{ => usage/operations}/projections/alsk.rst (100%) rename docs/source/{ => usage/operations}/projections/apian.rst (100%) rename docs/source/{ => usage/operations}/projections/august.rst (100%) rename docs/source/{ => usage/operations}/projections/bacon.rst (100%) rename docs/source/{ => usage/operations}/projections/bipc.rst (100%) rename docs/source/{ => usage/operations}/projections/boggs.rst (100%) rename docs/source/{ => usage/operations}/projections/bonne.rst (100%) rename docs/source/{ => usage/operations}/projections/calcofi.rst (99%) rename docs/source/{ => usage/operations}/projections/cass.rst (100%) rename docs/source/{ => usage/operations}/projections/cc.rst (100%) rename docs/source/{ => usage/operations}/projections/cea.rst (100%) rename docs/source/{ => usage/operations}/projections/chamb.rst (100%) rename docs/source/{ => usage/operations}/projections/collg.rst (100%) rename docs/source/{ => usage/operations}/projections/crast.rst (100%) rename docs/source/{ => usage/operations}/projections/denoy.rst (100%) rename docs/source/{ => usage/operations}/projections/eck1.rst (100%) rename docs/source/{ => usage/operations}/projections/eck2.rst (100%) rename docs/source/{ => usage/operations}/projections/eck3.rst (100%) rename docs/source/{ => usage/operations}/projections/eck4.rst (100%) rename docs/source/{ => usage/operations}/projections/eck5.rst (100%) rename docs/source/{ => usage/operations}/projections/eck6.rst (100%) rename docs/source/{ => usage/operations}/projections/eqc.rst (100%) rename docs/source/{ => usage/operations}/projections/eqdc.rst (100%) rename docs/source/{ => usage/operations}/projections/etmerc.rst (100%) rename docs/source/{ => usage/operations}/projections/euler.rst (100%) rename docs/source/{ => usage/operations}/projections/fahey.rst (100%) rename docs/source/{ => usage/operations}/projections/fouc.rst (100%) rename docs/source/{ => usage/operations}/projections/fouc_s.rst (100%) rename docs/source/{ => usage/operations}/projections/gall.rst (100%) rename docs/source/{ => usage/operations}/projections/geos.rst (98%) rename docs/source/{ => usage/operations}/projections/gins8.rst (100%) rename docs/source/{ => usage/operations}/projections/gn_sinu.rst (100%) rename docs/source/{ => usage/operations}/projections/gnom.rst (100%) rename docs/source/{ => usage/operations}/projections/goode.rst (100%) rename docs/source/{ => usage/operations}/projections/gs48.rst (100%) rename docs/source/{ => usage/operations}/projections/gs50.rst (100%) rename docs/source/{ => usage/operations}/projections/gstmerc.rst (100%) rename docs/source/{ => usage/operations}/projections/hammer.rst (100%) rename docs/source/{ => usage/operations}/projections/hatano.rst (100%) rename docs/source/{ => usage/operations}/projections/healpix.rst (98%) rename docs/source/{ => usage/operations}/projections/igh.rst (100%) rename docs/source/{ => usage/operations}/projections/images/aea.png (100%) rename docs/source/{ => usage/operations}/projections/images/aeqd.png (100%) rename docs/source/{ => usage/operations}/projections/images/airy.png (100%) rename docs/source/{ => usage/operations}/projections/images/aitoff.png (100%) rename docs/source/{ => usage/operations}/projections/images/alsk.png (100%) rename docs/source/{ => usage/operations}/projections/images/apian.png (100%) rename docs/source/{ => usage/operations}/projections/images/august.png (100%) rename docs/source/{ => usage/operations}/projections/images/bacon.png (100%) rename docs/source/{ => usage/operations}/projections/images/bipc.png (100%) rename docs/source/{ => usage/operations}/projections/images/boggs.png (100%) rename docs/source/{ => usage/operations}/projections/images/bonne.png (100%) rename docs/source/{ => usage/operations}/projections/images/calcofi.png (100%) rename docs/source/{ => usage/operations}/projections/images/cass.png (100%) rename docs/source/{ => usage/operations}/projections/images/cc.png (100%) rename docs/source/{ => usage/operations}/projections/images/cea.png (100%) rename docs/source/{ => usage/operations}/projections/images/chamb.png (100%) rename docs/source/{ => usage/operations}/projections/images/collg.png (100%) rename docs/source/{ => usage/operations}/projections/images/comill.png (100%) rename docs/source/{ => usage/operations}/projections/images/crast.png (100%) rename docs/source/{ => usage/operations}/projections/images/denoy.png (100%) rename docs/source/{ => usage/operations}/projections/images/eck1.png (100%) rename docs/source/{ => usage/operations}/projections/images/eck2.png (100%) rename docs/source/{ => usage/operations}/projections/images/eck3.png (100%) rename docs/source/{ => usage/operations}/projections/images/eck4.png (100%) rename docs/source/{ => usage/operations}/projections/images/eck5.png (100%) rename docs/source/{ => usage/operations}/projections/images/eck6.png (100%) rename docs/source/{ => usage/operations}/projections/images/eqc.png (100%) rename docs/source/{ => usage/operations}/projections/images/eqdc.png (100%) rename docs/source/{ => usage/operations}/projections/images/etmerc.png (100%) rename docs/source/{ => usage/operations}/projections/images/euler.png (100%) rename docs/source/{ => usage/operations}/projections/images/fahey.png (100%) rename docs/source/{ => usage/operations}/projections/images/fouc.png (100%) rename docs/source/{ => usage/operations}/projections/images/fouc_s.png (100%) rename docs/source/{ => usage/operations}/projections/images/gall.png (100%) rename docs/source/{ => usage/operations}/projections/images/geos.png (100%) rename docs/source/{ => usage/operations}/projections/images/gins8.png (100%) rename docs/source/{ => usage/operations}/projections/images/gn_sinu.png (100%) rename docs/source/{ => usage/operations}/projections/images/gnom.png (100%) rename docs/source/{ => usage/operations}/projections/images/goode.png (100%) rename docs/source/{ => usage/operations}/projections/images/gs48.png (100%) rename docs/source/{ => usage/operations}/projections/images/gs50.png (100%) rename docs/source/{ => usage/operations}/projections/images/gstmerc.png (100%) rename docs/source/{ => usage/operations}/projections/images/hammer.png (100%) rename docs/source/{ => usage/operations}/projections/images/hatano.png (100%) rename docs/source/{ => usage/operations}/projections/images/healpix.png (100%) rename docs/source/{ => usage/operations}/projections/images/igh.png (100%) rename docs/source/{ => usage/operations}/projections/images/imw_p.png (100%) rename docs/source/{ => usage/operations}/projections/images/isea.png (100%) rename docs/source/{ => usage/operations}/projections/images/kav5.png (100%) rename docs/source/{ => usage/operations}/projections/images/kav7.png (100%) rename docs/source/{ => usage/operations}/projections/images/krovak.png (100%) rename docs/source/{ => usage/operations}/projections/images/labrd.png (100%) rename docs/source/{ => usage/operations}/projections/images/laea.png (100%) rename docs/source/{ => usage/operations}/projections/images/lagrng.png (100%) rename docs/source/{ => usage/operations}/projections/images/larr.png (100%) rename docs/source/{ => usage/operations}/projections/images/lask.png (100%) rename docs/source/{ => usage/operations}/projections/images/lcc.png (100%) rename docs/source/{ => usage/operations}/projections/images/lcca.png (100%) rename docs/source/{ => usage/operations}/projections/images/leac.png (100%) rename docs/source/{ => usage/operations}/projections/images/lee_os.png (100%) rename docs/source/{ => usage/operations}/projections/images/loxim.png (100%) rename docs/source/{ => usage/operations}/projections/images/lsat.png (100%) rename docs/source/{ => usage/operations}/projections/images/mbt_fps.png (100%) rename docs/source/{ => usage/operations}/projections/images/mbt_s.png (100%) rename docs/source/{ => usage/operations}/projections/images/mbtfpp.png (100%) rename docs/source/{ => usage/operations}/projections/images/mbtfpq.png (100%) rename docs/source/{ => usage/operations}/projections/images/mbtfps.png (100%) rename docs/source/{ => usage/operations}/projections/images/merc.png (100%) rename docs/source/{ => usage/operations}/projections/images/mil_os.png (100%) rename docs/source/{ => usage/operations}/projections/images/mill.png (100%) rename docs/source/{ => usage/operations}/projections/images/misrsom.png (100%) rename docs/source/{ => usage/operations}/projections/images/moll.png (100%) rename docs/source/{ => usage/operations}/projections/images/murd1.png (100%) rename docs/source/{ => usage/operations}/projections/images/murd2.png (100%) rename docs/source/{ => usage/operations}/projections/images/murd3.png (100%) rename docs/source/{ => usage/operations}/projections/images/natearth.png (100%) rename docs/source/{ => usage/operations}/projections/images/natearth2.png (100%) rename docs/source/{ => usage/operations}/projections/images/nell.png (100%) rename docs/source/{ => usage/operations}/projections/images/nell_h.png (100%) rename docs/source/{ => usage/operations}/projections/images/nicol.png (100%) rename docs/source/{ => usage/operations}/projections/images/nsper.png (100%) rename docs/source/{ => usage/operations}/projections/images/nzmg.png (100%) rename docs/source/{ => usage/operations}/projections/images/ob_tran.png (100%) rename docs/source/{ => usage/operations}/projections/images/ocea.png (100%) rename docs/source/{ => usage/operations}/projections/images/oea.png (100%) rename docs/source/{ => usage/operations}/projections/images/omerc.png (100%) rename docs/source/{ => usage/operations}/projections/images/ortel.png (100%) rename docs/source/{ => usage/operations}/projections/images/ortho.png (100%) rename docs/source/{ => usage/operations}/projections/images/patterson.png (100%) rename docs/source/{ => usage/operations}/projections/images/pconic.png (100%) rename docs/source/{ => usage/operations}/projections/images/poly.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp1.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp2.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp3.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp3p.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp4p.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp5.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp5p.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp6.png (100%) rename docs/source/{ => usage/operations}/projections/images/putp6p.png (100%) rename docs/source/{ => usage/operations}/projections/images/qsc.png (100%) rename docs/source/{ => usage/operations}/projections/images/qua_aut.png (100%) rename docs/source/{ => usage/operations}/projections/images/rhealpix.png (100%) rename docs/source/{ => usage/operations}/projections/images/robin.png (100%) rename docs/source/{ => usage/operations}/projections/images/rouss.png (100%) rename docs/source/{ => usage/operations}/projections/images/rpoly.png (100%) rename docs/source/{ => usage/operations}/projections/images/sinu.png (100%) rename docs/source/{ => usage/operations}/projections/images/somerc.png (100%) rename docs/source/{ => usage/operations}/projections/images/stere.png (100%) rename docs/source/{ => usage/operations}/projections/images/sterea.png (100%) rename docs/source/{ => usage/operations}/projections/images/tcc.png (100%) rename docs/source/{ => usage/operations}/projections/images/tcea.png (100%) rename docs/source/{ => usage/operations}/projections/images/tissot.png (100%) rename docs/source/{ => usage/operations}/projections/images/tmerc.png (100%) rename docs/source/{ => usage/operations}/projections/images/tpeqd.png (100%) rename docs/source/{ => usage/operations}/projections/images/tpers.png (100%) rename docs/source/{ => usage/operations}/projections/images/ups.png (100%) rename docs/source/{ => usage/operations}/projections/images/urm5.png (100%) rename docs/source/{ => usage/operations}/projections/images/urmfps.png (100%) rename docs/source/{ => usage/operations}/projections/images/utm.png (100%) rename docs/source/{ => usage/operations}/projections/images/vandg.png (100%) rename docs/source/{ => usage/operations}/projections/images/vandg2.png (100%) rename docs/source/{ => usage/operations}/projections/images/vandg3.png (100%) rename docs/source/{ => usage/operations}/projections/images/vandg4.png (100%) rename docs/source/{ => usage/operations}/projections/images/vitk1.png (100%) rename docs/source/{ => usage/operations}/projections/images/wag1.png (100%) rename docs/source/{ => usage/operations}/projections/images/wag2.png (100%) rename docs/source/{ => usage/operations}/projections/images/wag3.png (100%) rename docs/source/{ => usage/operations}/projections/images/wag4.png (100%) rename docs/source/{ => usage/operations}/projections/images/wag5.png (100%) rename docs/source/{ => usage/operations}/projections/images/wag6.png (100%) rename docs/source/{ => usage/operations}/projections/images/wag7.png (100%) rename docs/source/{ => usage/operations}/projections/images/weren.png (100%) rename docs/source/{ => usage/operations}/projections/images/wink1.png (100%) rename docs/source/{ => usage/operations}/projections/images/wink2.png (100%) rename docs/source/{ => usage/operations}/projections/images/wintri.png (100%) rename docs/source/{ => usage/operations}/projections/imw_p.rst (100%) rename docs/source/{ => usage/operations}/projections/index.rst (100%) rename docs/source/{ => usage/operations}/projections/isea.rst (100%) rename docs/source/{ => usage/operations}/projections/kav5.rst (100%) rename docs/source/{ => usage/operations}/projections/kav7.rst (100%) rename docs/source/{ => usage/operations}/projections/krovak.rst (100%) rename docs/source/{ => usage/operations}/projections/labrd.rst (100%) rename docs/source/{ => usage/operations}/projections/laea.rst (100%) rename docs/source/{ => usage/operations}/projections/lagrng.rst (100%) rename docs/source/{ => usage/operations}/projections/larr.rst (100%) rename docs/source/{ => usage/operations}/projections/lask.rst (100%) rename docs/source/{ => usage/operations}/projections/latlon.rst (100%) rename docs/source/{ => usage/operations}/projections/lcc.rst (100%) rename docs/source/{ => usage/operations}/projections/lcca.rst (100%) rename docs/source/{ => usage/operations}/projections/leac.rst (100%) rename docs/source/{ => usage/operations}/projections/lee_os.rst (100%) rename docs/source/{ => usage/operations}/projections/lonlat.rst (100%) rename docs/source/{ => usage/operations}/projections/loxim.rst (100%) rename docs/source/{ => usage/operations}/projections/lsat.rst (100%) rename docs/source/{ => usage/operations}/projections/mbt_fps.rst (100%) rename docs/source/{ => usage/operations}/projections/mbt_s.rst (100%) rename docs/source/{ => usage/operations}/projections/mbtfpp.rst (100%) rename docs/source/{ => usage/operations}/projections/mbtfpq.rst (100%) rename docs/source/{ => usage/operations}/projections/mbtfps.rst (100%) rename docs/source/{ => usage/operations}/projections/merc.rst (100%) rename docs/source/{ => usage/operations}/projections/mil_os.rst (100%) rename docs/source/{ => usage/operations}/projections/mill.rst (100%) rename docs/source/{ => usage/operations}/projections/moll.rst (100%) rename docs/source/{ => usage/operations}/projections/murd1.rst (100%) rename docs/source/{ => usage/operations}/projections/murd2.rst (100%) rename docs/source/{ => usage/operations}/projections/murd3.rst (100%) rename docs/source/{ => usage/operations}/projections/natearth.rst (100%) rename docs/source/{ => usage/operations}/projections/nell.rst (100%) rename docs/source/{ => usage/operations}/projections/nell_h.rst (100%) rename docs/source/{ => usage/operations}/projections/nicol.rst (100%) rename docs/source/{ => usage/operations}/projections/nsper.rst (100%) rename docs/source/{ => usage/operations}/projections/nzmg.rst (100%) rename docs/source/{ => usage/operations}/projections/ob_tran.rst (100%) rename docs/source/{ => usage/operations}/projections/ocea.rst (100%) rename docs/source/{ => usage/operations}/projections/oea.rst (100%) rename docs/source/{ => usage/operations}/projections/omerc.rst (100%) rename docs/source/{ => usage/operations}/projections/ortel.rst (100%) rename docs/source/{ => usage/operations}/projections/ortho.rst (100%) rename docs/source/{ => usage/operations}/projections/pconic.rst (100%) rename docs/source/{ => usage/operations}/projections/poly.rst (100%) rename docs/source/{ => usage/operations}/projections/putp1.rst (100%) rename docs/source/{ => usage/operations}/projections/putp2.rst (100%) rename docs/source/{ => usage/operations}/projections/putp3.rst (100%) rename docs/source/{ => usage/operations}/projections/putp3p.rst (100%) rename docs/source/{ => usage/operations}/projections/putp4p.rst (100%) rename docs/source/{ => usage/operations}/projections/putp5.rst (100%) rename docs/source/{ => usage/operations}/projections/putp5p.rst (100%) rename docs/source/{ => usage/operations}/projections/putp6.rst (100%) rename docs/source/{ => usage/operations}/projections/putp6p.rst (100%) rename docs/source/{ => usage/operations}/projections/qsc.rst (94%) rename docs/source/{ => usage/operations}/projections/qua_aut.rst (100%) rename docs/source/{ => usage/operations}/projections/rhealpix.rst (98%) rename docs/source/{ => usage/operations}/projections/robin.rst (100%) rename docs/source/{ => usage/operations}/projections/rouss.rst (100%) rename docs/source/{ => usage/operations}/projections/rpoly.rst (100%) rename docs/source/{ => usage/operations}/projections/sinu.rst (100%) rename docs/source/{ => usage/operations}/projections/somerc.rst (100%) rename docs/source/{ => usage/operations}/projections/stere.rst (100%) rename docs/source/{ => usage/operations}/projections/sterea.rst (100%) rename docs/source/{ => usage/operations}/projections/tcc.rst (100%) rename docs/source/{ => usage/operations}/projections/tcea.rst (100%) rename docs/source/{ => usage/operations}/projections/tissot.rst (100%) rename docs/source/{ => usage/operations}/projections/tmerc.rst (100%) rename docs/source/{ => usage/operations}/projections/tpeqd.rst (100%) rename docs/source/{ => usage/operations}/projections/tpers.rst (100%) rename docs/source/{ => usage/operations}/projections/ups.rst (100%) rename docs/source/{ => usage/operations}/projections/urm5.rst (100%) rename docs/source/{ => usage/operations}/projections/urmfps.rst (100%) rename docs/source/{ => usage/operations}/projections/utm.rst (100%) rename docs/source/{ => usage/operations}/projections/vandg.rst (100%) rename docs/source/{ => usage/operations}/projections/vandg2.rst (100%) rename docs/source/{ => usage/operations}/projections/vandg3.rst (100%) rename docs/source/{ => usage/operations}/projections/vandg4.rst (100%) rename docs/source/{ => usage/operations}/projections/vitk1.rst (100%) rename docs/source/{ => usage/operations}/projections/wag1.rst (100%) rename docs/source/{ => usage/operations}/projections/wag2.rst (100%) rename docs/source/{ => usage/operations}/projections/wag3.rst (100%) rename docs/source/{ => usage/operations}/projections/wag4.rst (100%) rename docs/source/{ => usage/operations}/projections/wag5.rst (100%) rename docs/source/{ => usage/operations}/projections/wag6.rst (100%) rename docs/source/{ => usage/operations}/projections/wag7.rst (100%) rename docs/source/{ => usage/operations}/projections/weren.rst (100%) rename docs/source/{ => usage/operations}/projections/wink1.rst (100%) rename docs/source/{ => usage/operations}/projections/wink2.rst (100%) rename docs/source/{ => usage/operations}/projections/wintri.rst (100%) create mode 100644 docs/source/usage/operations/transformations/cart.rst create mode 100644 docs/source/usage/operations/transformations/helmert.rst create mode 100644 docs/source/usage/operations/transformations/hgridshift.rst create mode 100644 docs/source/usage/operations/transformations/index.rst create mode 100644 docs/source/usage/operations/transformations/molodensky.rst create mode 100644 docs/source/usage/operations/transformations/unitconvert.rst create mode 100644 docs/source/usage/operations/transformations/vgridshift.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index bfb9aee6cf..324d52fc2a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -35,7 +35,6 @@ Documentation :maxdepth: 1 usage/index - projections/index geodesic grids htpd diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst index 8c12c026f8..5979426a8e 100644 --- a/docs/source/usage/index.rst +++ b/docs/source/usage/index.rst @@ -17,4 +17,5 @@ command line applications or the C API that is a part of the software package. projections transformation resource_files + operations/index diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst new file mode 100644 index 0000000000..21200c939c --- /dev/null +++ b/docs/source/usage/operations/index.rst @@ -0,0 +1,18 @@ +.. _operations: + +================================================================================ +Coordinate operations +================================================================================ + +Coordinate operations in PROJ.4 are divided into two groups: +Projections and transformations. +Projections are purely cartographic mappings of the sphere onto the plane whereas +transformations are mostly geodetic operations concerned with changes in +reference frames. + +.. toctree:: + :maxdepth: 1 + + projections/index + transformations/index + diff --git a/docs/source/projections/aeqd.rst b/docs/source/usage/operations/projections/aeqd.rst similarity index 100% rename from docs/source/projections/aeqd.rst rename to docs/source/usage/operations/projections/aeqd.rst diff --git a/docs/source/projections/airy.rst b/docs/source/usage/operations/projections/airy.rst similarity index 100% rename from docs/source/projections/airy.rst rename to docs/source/usage/operations/projections/airy.rst diff --git a/docs/source/projections/aitoff.rst b/docs/source/usage/operations/projections/aitoff.rst similarity index 100% rename from docs/source/projections/aitoff.rst rename to docs/source/usage/operations/projections/aitoff.rst diff --git a/docs/source/projections/alsk.rst b/docs/source/usage/operations/projections/alsk.rst similarity index 100% rename from docs/source/projections/alsk.rst rename to docs/source/usage/operations/projections/alsk.rst diff --git a/docs/source/projections/apian.rst b/docs/source/usage/operations/projections/apian.rst similarity index 100% rename from docs/source/projections/apian.rst rename to docs/source/usage/operations/projections/apian.rst diff --git a/docs/source/projections/august.rst b/docs/source/usage/operations/projections/august.rst similarity index 100% rename from docs/source/projections/august.rst rename to docs/source/usage/operations/projections/august.rst diff --git a/docs/source/projections/bacon.rst b/docs/source/usage/operations/projections/bacon.rst similarity index 100% rename from docs/source/projections/bacon.rst rename to docs/source/usage/operations/projections/bacon.rst diff --git a/docs/source/projections/bipc.rst b/docs/source/usage/operations/projections/bipc.rst similarity index 100% rename from docs/source/projections/bipc.rst rename to docs/source/usage/operations/projections/bipc.rst diff --git a/docs/source/projections/boggs.rst b/docs/source/usage/operations/projections/boggs.rst similarity index 100% rename from docs/source/projections/boggs.rst rename to docs/source/usage/operations/projections/boggs.rst diff --git a/docs/source/projections/bonne.rst b/docs/source/usage/operations/projections/bonne.rst similarity index 100% rename from docs/source/projections/bonne.rst rename to docs/source/usage/operations/projections/bonne.rst diff --git a/docs/source/projections/calcofi.rst b/docs/source/usage/operations/projections/calcofi.rst similarity index 99% rename from docs/source/projections/calcofi.rst rename to docs/source/usage/operations/projections/calcofi.rst index 3c1e5f7a8d..650416c1df 100644 --- a/docs/source/projections/calcofi.rst +++ b/docs/source/usage/operations/projections/calcofi.rst @@ -22,7 +22,7 @@ California Cooperative Oceanic Fisheries Investigations program, known as CalCOF +---------------------+----------------------------------------------------------+ -.. image:: ../../images/calcofi.png +.. image:: ../../../../images/calcofi.png :scale: 50% :align: center :alt: Cal Coop Ocean Fish Invest Lines/Stations diff --git a/docs/source/projections/cass.rst b/docs/source/usage/operations/projections/cass.rst similarity index 100% rename from docs/source/projections/cass.rst rename to docs/source/usage/operations/projections/cass.rst diff --git a/docs/source/projections/cc.rst b/docs/source/usage/operations/projections/cc.rst similarity index 100% rename from docs/source/projections/cc.rst rename to docs/source/usage/operations/projections/cc.rst diff --git a/docs/source/projections/cea.rst b/docs/source/usage/operations/projections/cea.rst similarity index 100% rename from docs/source/projections/cea.rst rename to docs/source/usage/operations/projections/cea.rst diff --git a/docs/source/projections/chamb.rst b/docs/source/usage/operations/projections/chamb.rst similarity index 100% rename from docs/source/projections/chamb.rst rename to docs/source/usage/operations/projections/chamb.rst diff --git a/docs/source/projections/collg.rst b/docs/source/usage/operations/projections/collg.rst similarity index 100% rename from docs/source/projections/collg.rst rename to docs/source/usage/operations/projections/collg.rst diff --git a/docs/source/projections/crast.rst b/docs/source/usage/operations/projections/crast.rst similarity index 100% rename from docs/source/projections/crast.rst rename to docs/source/usage/operations/projections/crast.rst diff --git a/docs/source/projections/denoy.rst b/docs/source/usage/operations/projections/denoy.rst similarity index 100% rename from docs/source/projections/denoy.rst rename to docs/source/usage/operations/projections/denoy.rst diff --git a/docs/source/projections/eck1.rst b/docs/source/usage/operations/projections/eck1.rst similarity index 100% rename from docs/source/projections/eck1.rst rename to docs/source/usage/operations/projections/eck1.rst diff --git a/docs/source/projections/eck2.rst b/docs/source/usage/operations/projections/eck2.rst similarity index 100% rename from docs/source/projections/eck2.rst rename to docs/source/usage/operations/projections/eck2.rst diff --git a/docs/source/projections/eck3.rst b/docs/source/usage/operations/projections/eck3.rst similarity index 100% rename from docs/source/projections/eck3.rst rename to docs/source/usage/operations/projections/eck3.rst diff --git a/docs/source/projections/eck4.rst b/docs/source/usage/operations/projections/eck4.rst similarity index 100% rename from docs/source/projections/eck4.rst rename to docs/source/usage/operations/projections/eck4.rst diff --git a/docs/source/projections/eck5.rst b/docs/source/usage/operations/projections/eck5.rst similarity index 100% rename from docs/source/projections/eck5.rst rename to docs/source/usage/operations/projections/eck5.rst diff --git a/docs/source/projections/eck6.rst b/docs/source/usage/operations/projections/eck6.rst similarity index 100% rename from docs/source/projections/eck6.rst rename to docs/source/usage/operations/projections/eck6.rst diff --git a/docs/source/projections/eqc.rst b/docs/source/usage/operations/projections/eqc.rst similarity index 100% rename from docs/source/projections/eqc.rst rename to docs/source/usage/operations/projections/eqc.rst diff --git a/docs/source/projections/eqdc.rst b/docs/source/usage/operations/projections/eqdc.rst similarity index 100% rename from docs/source/projections/eqdc.rst rename to docs/source/usage/operations/projections/eqdc.rst diff --git a/docs/source/projections/etmerc.rst b/docs/source/usage/operations/projections/etmerc.rst similarity index 100% rename from docs/source/projections/etmerc.rst rename to docs/source/usage/operations/projections/etmerc.rst diff --git a/docs/source/projections/euler.rst b/docs/source/usage/operations/projections/euler.rst similarity index 100% rename from docs/source/projections/euler.rst rename to docs/source/usage/operations/projections/euler.rst diff --git a/docs/source/projections/fahey.rst b/docs/source/usage/operations/projections/fahey.rst similarity index 100% rename from docs/source/projections/fahey.rst rename to docs/source/usage/operations/projections/fahey.rst diff --git a/docs/source/projections/fouc.rst b/docs/source/usage/operations/projections/fouc.rst similarity index 100% rename from docs/source/projections/fouc.rst rename to docs/source/usage/operations/projections/fouc.rst diff --git a/docs/source/projections/fouc_s.rst b/docs/source/usage/operations/projections/fouc_s.rst similarity index 100% rename from docs/source/projections/fouc_s.rst rename to docs/source/usage/operations/projections/fouc_s.rst diff --git a/docs/source/projections/gall.rst b/docs/source/usage/operations/projections/gall.rst similarity index 100% rename from docs/source/projections/gall.rst rename to docs/source/usage/operations/projections/gall.rst diff --git a/docs/source/projections/geos.rst b/docs/source/usage/operations/projections/geos.rst similarity index 98% rename from docs/source/projections/geos.rst rename to docs/source/usage/operations/projections/geos.rst index 5655015900..3b24e1f7d6 100644 --- a/docs/source/projections/geos.rst +++ b/docs/source/usage/operations/projections/geos.rst @@ -55,7 +55,7 @@ projection have a two-axis gimbal viewing geometry. This means that the differen scanning positions are obtained by rotating the gimbal along a N/S axis (or ``y``) and a E/W axis (or ``x``). -.. image:: ../../images/geos_sweep.png +.. image:: ../../../../images/geos_sweep.png :scale: 50% :alt: Gimbal geometry diff --git a/docs/source/projections/gins8.rst b/docs/source/usage/operations/projections/gins8.rst similarity index 100% rename from docs/source/projections/gins8.rst rename to docs/source/usage/operations/projections/gins8.rst diff --git a/docs/source/projections/gn_sinu.rst b/docs/source/usage/operations/projections/gn_sinu.rst similarity index 100% rename from docs/source/projections/gn_sinu.rst rename to docs/source/usage/operations/projections/gn_sinu.rst diff --git a/docs/source/projections/gnom.rst b/docs/source/usage/operations/projections/gnom.rst similarity index 100% rename from docs/source/projections/gnom.rst rename to docs/source/usage/operations/projections/gnom.rst diff --git a/docs/source/projections/goode.rst b/docs/source/usage/operations/projections/goode.rst similarity index 100% rename from docs/source/projections/goode.rst rename to docs/source/usage/operations/projections/goode.rst diff --git a/docs/source/projections/gs48.rst b/docs/source/usage/operations/projections/gs48.rst similarity index 100% rename from docs/source/projections/gs48.rst rename to docs/source/usage/operations/projections/gs48.rst diff --git a/docs/source/projections/gs50.rst b/docs/source/usage/operations/projections/gs50.rst similarity index 100% rename from docs/source/projections/gs50.rst rename to docs/source/usage/operations/projections/gs50.rst diff --git a/docs/source/projections/gstmerc.rst b/docs/source/usage/operations/projections/gstmerc.rst similarity index 100% rename from docs/source/projections/gstmerc.rst rename to docs/source/usage/operations/projections/gstmerc.rst diff --git a/docs/source/projections/hammer.rst b/docs/source/usage/operations/projections/hammer.rst similarity index 100% rename from docs/source/projections/hammer.rst rename to docs/source/usage/operations/projections/hammer.rst diff --git a/docs/source/projections/hatano.rst b/docs/source/usage/operations/projections/hatano.rst similarity index 100% rename from docs/source/projections/hatano.rst rename to docs/source/usage/operations/projections/hatano.rst diff --git a/docs/source/projections/healpix.rst b/docs/source/usage/operations/projections/healpix.rst similarity index 98% rename from docs/source/projections/healpix.rst rename to docs/source/usage/operations/projections/healpix.rst index 885ea3ea03..20815d7654 100644 --- a/docs/source/projections/healpix.rst +++ b/docs/source/usage/operations/projections/healpix.rst @@ -17,7 +17,7 @@ HEALPix | `No special options for this projection` | +---------------------+----------------------------------------------------------+ -.. image:: ../../images/healpix.png +.. image:: ../../../../images/healpix.png :scale: 75% :alt: HEALPix diff --git a/docs/source/projections/igh.rst b/docs/source/usage/operations/projections/igh.rst similarity index 100% rename from docs/source/projections/igh.rst rename to docs/source/usage/operations/projections/igh.rst diff --git a/docs/source/projections/images/aea.png b/docs/source/usage/operations/projections/images/aea.png similarity index 100% rename from docs/source/projections/images/aea.png rename to docs/source/usage/operations/projections/images/aea.png diff --git a/docs/source/projections/images/aeqd.png b/docs/source/usage/operations/projections/images/aeqd.png similarity index 100% rename from docs/source/projections/images/aeqd.png rename to docs/source/usage/operations/projections/images/aeqd.png diff --git a/docs/source/projections/images/airy.png b/docs/source/usage/operations/projections/images/airy.png similarity index 100% rename from docs/source/projections/images/airy.png rename to docs/source/usage/operations/projections/images/airy.png diff --git a/docs/source/projections/images/aitoff.png b/docs/source/usage/operations/projections/images/aitoff.png similarity index 100% rename from docs/source/projections/images/aitoff.png rename to docs/source/usage/operations/projections/images/aitoff.png diff --git a/docs/source/projections/images/alsk.png b/docs/source/usage/operations/projections/images/alsk.png similarity index 100% rename from docs/source/projections/images/alsk.png rename to docs/source/usage/operations/projections/images/alsk.png diff --git a/docs/source/projections/images/apian.png b/docs/source/usage/operations/projections/images/apian.png similarity index 100% rename from docs/source/projections/images/apian.png rename to docs/source/usage/operations/projections/images/apian.png diff --git a/docs/source/projections/images/august.png b/docs/source/usage/operations/projections/images/august.png similarity index 100% rename from docs/source/projections/images/august.png rename to docs/source/usage/operations/projections/images/august.png diff --git a/docs/source/projections/images/bacon.png b/docs/source/usage/operations/projections/images/bacon.png similarity index 100% rename from docs/source/projections/images/bacon.png rename to docs/source/usage/operations/projections/images/bacon.png diff --git a/docs/source/projections/images/bipc.png b/docs/source/usage/operations/projections/images/bipc.png similarity index 100% rename from docs/source/projections/images/bipc.png rename to docs/source/usage/operations/projections/images/bipc.png diff --git a/docs/source/projections/images/boggs.png b/docs/source/usage/operations/projections/images/boggs.png similarity index 100% rename from docs/source/projections/images/boggs.png rename to docs/source/usage/operations/projections/images/boggs.png diff --git a/docs/source/projections/images/bonne.png b/docs/source/usage/operations/projections/images/bonne.png similarity index 100% rename from docs/source/projections/images/bonne.png rename to docs/source/usage/operations/projections/images/bonne.png diff --git a/docs/source/projections/images/calcofi.png b/docs/source/usage/operations/projections/images/calcofi.png similarity index 100% rename from docs/source/projections/images/calcofi.png rename to docs/source/usage/operations/projections/images/calcofi.png diff --git a/docs/source/projections/images/cass.png b/docs/source/usage/operations/projections/images/cass.png similarity index 100% rename from docs/source/projections/images/cass.png rename to docs/source/usage/operations/projections/images/cass.png diff --git a/docs/source/projections/images/cc.png b/docs/source/usage/operations/projections/images/cc.png similarity index 100% rename from docs/source/projections/images/cc.png rename to docs/source/usage/operations/projections/images/cc.png diff --git a/docs/source/projections/images/cea.png b/docs/source/usage/operations/projections/images/cea.png similarity index 100% rename from docs/source/projections/images/cea.png rename to docs/source/usage/operations/projections/images/cea.png diff --git a/docs/source/projections/images/chamb.png b/docs/source/usage/operations/projections/images/chamb.png similarity index 100% rename from docs/source/projections/images/chamb.png rename to docs/source/usage/operations/projections/images/chamb.png diff --git a/docs/source/projections/images/collg.png b/docs/source/usage/operations/projections/images/collg.png similarity index 100% rename from docs/source/projections/images/collg.png rename to docs/source/usage/operations/projections/images/collg.png diff --git a/docs/source/projections/images/comill.png b/docs/source/usage/operations/projections/images/comill.png similarity index 100% rename from docs/source/projections/images/comill.png rename to docs/source/usage/operations/projections/images/comill.png diff --git a/docs/source/projections/images/crast.png b/docs/source/usage/operations/projections/images/crast.png similarity index 100% rename from docs/source/projections/images/crast.png rename to docs/source/usage/operations/projections/images/crast.png diff --git a/docs/source/projections/images/denoy.png b/docs/source/usage/operations/projections/images/denoy.png similarity index 100% rename from docs/source/projections/images/denoy.png rename to docs/source/usage/operations/projections/images/denoy.png diff --git a/docs/source/projections/images/eck1.png b/docs/source/usage/operations/projections/images/eck1.png similarity index 100% rename from docs/source/projections/images/eck1.png rename to docs/source/usage/operations/projections/images/eck1.png diff --git a/docs/source/projections/images/eck2.png b/docs/source/usage/operations/projections/images/eck2.png similarity index 100% rename from docs/source/projections/images/eck2.png rename to docs/source/usage/operations/projections/images/eck2.png diff --git a/docs/source/projections/images/eck3.png b/docs/source/usage/operations/projections/images/eck3.png similarity index 100% rename from docs/source/projections/images/eck3.png rename to docs/source/usage/operations/projections/images/eck3.png diff --git a/docs/source/projections/images/eck4.png b/docs/source/usage/operations/projections/images/eck4.png similarity index 100% rename from docs/source/projections/images/eck4.png rename to docs/source/usage/operations/projections/images/eck4.png diff --git a/docs/source/projections/images/eck5.png b/docs/source/usage/operations/projections/images/eck5.png similarity index 100% rename from docs/source/projections/images/eck5.png rename to docs/source/usage/operations/projections/images/eck5.png diff --git a/docs/source/projections/images/eck6.png b/docs/source/usage/operations/projections/images/eck6.png similarity index 100% rename from docs/source/projections/images/eck6.png rename to docs/source/usage/operations/projections/images/eck6.png diff --git a/docs/source/projections/images/eqc.png b/docs/source/usage/operations/projections/images/eqc.png similarity index 100% rename from docs/source/projections/images/eqc.png rename to docs/source/usage/operations/projections/images/eqc.png diff --git a/docs/source/projections/images/eqdc.png b/docs/source/usage/operations/projections/images/eqdc.png similarity index 100% rename from docs/source/projections/images/eqdc.png rename to docs/source/usage/operations/projections/images/eqdc.png diff --git a/docs/source/projections/images/etmerc.png b/docs/source/usage/operations/projections/images/etmerc.png similarity index 100% rename from docs/source/projections/images/etmerc.png rename to docs/source/usage/operations/projections/images/etmerc.png diff --git a/docs/source/projections/images/euler.png b/docs/source/usage/operations/projections/images/euler.png similarity index 100% rename from docs/source/projections/images/euler.png rename to docs/source/usage/operations/projections/images/euler.png diff --git a/docs/source/projections/images/fahey.png b/docs/source/usage/operations/projections/images/fahey.png similarity index 100% rename from docs/source/projections/images/fahey.png rename to docs/source/usage/operations/projections/images/fahey.png diff --git a/docs/source/projections/images/fouc.png b/docs/source/usage/operations/projections/images/fouc.png similarity index 100% rename from docs/source/projections/images/fouc.png rename to docs/source/usage/operations/projections/images/fouc.png diff --git a/docs/source/projections/images/fouc_s.png b/docs/source/usage/operations/projections/images/fouc_s.png similarity index 100% rename from docs/source/projections/images/fouc_s.png rename to docs/source/usage/operations/projections/images/fouc_s.png diff --git a/docs/source/projections/images/gall.png b/docs/source/usage/operations/projections/images/gall.png similarity index 100% rename from docs/source/projections/images/gall.png rename to docs/source/usage/operations/projections/images/gall.png diff --git a/docs/source/projections/images/geos.png b/docs/source/usage/operations/projections/images/geos.png similarity index 100% rename from docs/source/projections/images/geos.png rename to docs/source/usage/operations/projections/images/geos.png diff --git a/docs/source/projections/images/gins8.png b/docs/source/usage/operations/projections/images/gins8.png similarity index 100% rename from docs/source/projections/images/gins8.png rename to docs/source/usage/operations/projections/images/gins8.png diff --git a/docs/source/projections/images/gn_sinu.png b/docs/source/usage/operations/projections/images/gn_sinu.png similarity index 100% rename from docs/source/projections/images/gn_sinu.png rename to docs/source/usage/operations/projections/images/gn_sinu.png diff --git a/docs/source/projections/images/gnom.png b/docs/source/usage/operations/projections/images/gnom.png similarity index 100% rename from docs/source/projections/images/gnom.png rename to docs/source/usage/operations/projections/images/gnom.png diff --git a/docs/source/projections/images/goode.png b/docs/source/usage/operations/projections/images/goode.png similarity index 100% rename from docs/source/projections/images/goode.png rename to docs/source/usage/operations/projections/images/goode.png diff --git a/docs/source/projections/images/gs48.png b/docs/source/usage/operations/projections/images/gs48.png similarity index 100% rename from docs/source/projections/images/gs48.png rename to docs/source/usage/operations/projections/images/gs48.png diff --git a/docs/source/projections/images/gs50.png b/docs/source/usage/operations/projections/images/gs50.png similarity index 100% rename from docs/source/projections/images/gs50.png rename to docs/source/usage/operations/projections/images/gs50.png diff --git a/docs/source/projections/images/gstmerc.png b/docs/source/usage/operations/projections/images/gstmerc.png similarity index 100% rename from docs/source/projections/images/gstmerc.png rename to docs/source/usage/operations/projections/images/gstmerc.png diff --git a/docs/source/projections/images/hammer.png b/docs/source/usage/operations/projections/images/hammer.png similarity index 100% rename from docs/source/projections/images/hammer.png rename to docs/source/usage/operations/projections/images/hammer.png diff --git a/docs/source/projections/images/hatano.png b/docs/source/usage/operations/projections/images/hatano.png similarity index 100% rename from docs/source/projections/images/hatano.png rename to docs/source/usage/operations/projections/images/hatano.png diff --git a/docs/source/projections/images/healpix.png b/docs/source/usage/operations/projections/images/healpix.png similarity index 100% rename from docs/source/projections/images/healpix.png rename to docs/source/usage/operations/projections/images/healpix.png diff --git a/docs/source/projections/images/igh.png b/docs/source/usage/operations/projections/images/igh.png similarity index 100% rename from docs/source/projections/images/igh.png rename to docs/source/usage/operations/projections/images/igh.png diff --git a/docs/source/projections/images/imw_p.png b/docs/source/usage/operations/projections/images/imw_p.png similarity index 100% rename from docs/source/projections/images/imw_p.png rename to docs/source/usage/operations/projections/images/imw_p.png diff --git a/docs/source/projections/images/isea.png b/docs/source/usage/operations/projections/images/isea.png similarity index 100% rename from docs/source/projections/images/isea.png rename to docs/source/usage/operations/projections/images/isea.png diff --git a/docs/source/projections/images/kav5.png b/docs/source/usage/operations/projections/images/kav5.png similarity index 100% rename from docs/source/projections/images/kav5.png rename to docs/source/usage/operations/projections/images/kav5.png diff --git a/docs/source/projections/images/kav7.png b/docs/source/usage/operations/projections/images/kav7.png similarity index 100% rename from docs/source/projections/images/kav7.png rename to docs/source/usage/operations/projections/images/kav7.png diff --git a/docs/source/projections/images/krovak.png b/docs/source/usage/operations/projections/images/krovak.png similarity index 100% rename from docs/source/projections/images/krovak.png rename to docs/source/usage/operations/projections/images/krovak.png diff --git a/docs/source/projections/images/labrd.png b/docs/source/usage/operations/projections/images/labrd.png similarity index 100% rename from docs/source/projections/images/labrd.png rename to docs/source/usage/operations/projections/images/labrd.png diff --git a/docs/source/projections/images/laea.png b/docs/source/usage/operations/projections/images/laea.png similarity index 100% rename from docs/source/projections/images/laea.png rename to docs/source/usage/operations/projections/images/laea.png diff --git a/docs/source/projections/images/lagrng.png b/docs/source/usage/operations/projections/images/lagrng.png similarity index 100% rename from docs/source/projections/images/lagrng.png rename to docs/source/usage/operations/projections/images/lagrng.png diff --git a/docs/source/projections/images/larr.png b/docs/source/usage/operations/projections/images/larr.png similarity index 100% rename from docs/source/projections/images/larr.png rename to docs/source/usage/operations/projections/images/larr.png diff --git a/docs/source/projections/images/lask.png b/docs/source/usage/operations/projections/images/lask.png similarity index 100% rename from docs/source/projections/images/lask.png rename to docs/source/usage/operations/projections/images/lask.png diff --git a/docs/source/projections/images/lcc.png b/docs/source/usage/operations/projections/images/lcc.png similarity index 100% rename from docs/source/projections/images/lcc.png rename to docs/source/usage/operations/projections/images/lcc.png diff --git a/docs/source/projections/images/lcca.png b/docs/source/usage/operations/projections/images/lcca.png similarity index 100% rename from docs/source/projections/images/lcca.png rename to docs/source/usage/operations/projections/images/lcca.png diff --git a/docs/source/projections/images/leac.png b/docs/source/usage/operations/projections/images/leac.png similarity index 100% rename from docs/source/projections/images/leac.png rename to docs/source/usage/operations/projections/images/leac.png diff --git a/docs/source/projections/images/lee_os.png b/docs/source/usage/operations/projections/images/lee_os.png similarity index 100% rename from docs/source/projections/images/lee_os.png rename to docs/source/usage/operations/projections/images/lee_os.png diff --git a/docs/source/projections/images/loxim.png b/docs/source/usage/operations/projections/images/loxim.png similarity index 100% rename from docs/source/projections/images/loxim.png rename to docs/source/usage/operations/projections/images/loxim.png diff --git a/docs/source/projections/images/lsat.png b/docs/source/usage/operations/projections/images/lsat.png similarity index 100% rename from docs/source/projections/images/lsat.png rename to docs/source/usage/operations/projections/images/lsat.png diff --git a/docs/source/projections/images/mbt_fps.png b/docs/source/usage/operations/projections/images/mbt_fps.png similarity index 100% rename from docs/source/projections/images/mbt_fps.png rename to docs/source/usage/operations/projections/images/mbt_fps.png diff --git a/docs/source/projections/images/mbt_s.png b/docs/source/usage/operations/projections/images/mbt_s.png similarity index 100% rename from docs/source/projections/images/mbt_s.png rename to docs/source/usage/operations/projections/images/mbt_s.png diff --git a/docs/source/projections/images/mbtfpp.png b/docs/source/usage/operations/projections/images/mbtfpp.png similarity index 100% rename from docs/source/projections/images/mbtfpp.png rename to docs/source/usage/operations/projections/images/mbtfpp.png diff --git a/docs/source/projections/images/mbtfpq.png b/docs/source/usage/operations/projections/images/mbtfpq.png similarity index 100% rename from docs/source/projections/images/mbtfpq.png rename to docs/source/usage/operations/projections/images/mbtfpq.png diff --git a/docs/source/projections/images/mbtfps.png b/docs/source/usage/operations/projections/images/mbtfps.png similarity index 100% rename from docs/source/projections/images/mbtfps.png rename to docs/source/usage/operations/projections/images/mbtfps.png diff --git a/docs/source/projections/images/merc.png b/docs/source/usage/operations/projections/images/merc.png similarity index 100% rename from docs/source/projections/images/merc.png rename to docs/source/usage/operations/projections/images/merc.png diff --git a/docs/source/projections/images/mil_os.png b/docs/source/usage/operations/projections/images/mil_os.png similarity index 100% rename from docs/source/projections/images/mil_os.png rename to docs/source/usage/operations/projections/images/mil_os.png diff --git a/docs/source/projections/images/mill.png b/docs/source/usage/operations/projections/images/mill.png similarity index 100% rename from docs/source/projections/images/mill.png rename to docs/source/usage/operations/projections/images/mill.png diff --git a/docs/source/projections/images/misrsom.png b/docs/source/usage/operations/projections/images/misrsom.png similarity index 100% rename from docs/source/projections/images/misrsom.png rename to docs/source/usage/operations/projections/images/misrsom.png diff --git a/docs/source/projections/images/moll.png b/docs/source/usage/operations/projections/images/moll.png similarity index 100% rename from docs/source/projections/images/moll.png rename to docs/source/usage/operations/projections/images/moll.png diff --git a/docs/source/projections/images/murd1.png b/docs/source/usage/operations/projections/images/murd1.png similarity index 100% rename from docs/source/projections/images/murd1.png rename to docs/source/usage/operations/projections/images/murd1.png diff --git a/docs/source/projections/images/murd2.png b/docs/source/usage/operations/projections/images/murd2.png similarity index 100% rename from docs/source/projections/images/murd2.png rename to docs/source/usage/operations/projections/images/murd2.png diff --git a/docs/source/projections/images/murd3.png b/docs/source/usage/operations/projections/images/murd3.png similarity index 100% rename from docs/source/projections/images/murd3.png rename to docs/source/usage/operations/projections/images/murd3.png diff --git a/docs/source/projections/images/natearth.png b/docs/source/usage/operations/projections/images/natearth.png similarity index 100% rename from docs/source/projections/images/natearth.png rename to docs/source/usage/operations/projections/images/natearth.png diff --git a/docs/source/projections/images/natearth2.png b/docs/source/usage/operations/projections/images/natearth2.png similarity index 100% rename from docs/source/projections/images/natearth2.png rename to docs/source/usage/operations/projections/images/natearth2.png diff --git a/docs/source/projections/images/nell.png b/docs/source/usage/operations/projections/images/nell.png similarity index 100% rename from docs/source/projections/images/nell.png rename to docs/source/usage/operations/projections/images/nell.png diff --git a/docs/source/projections/images/nell_h.png b/docs/source/usage/operations/projections/images/nell_h.png similarity index 100% rename from docs/source/projections/images/nell_h.png rename to docs/source/usage/operations/projections/images/nell_h.png diff --git a/docs/source/projections/images/nicol.png b/docs/source/usage/operations/projections/images/nicol.png similarity index 100% rename from docs/source/projections/images/nicol.png rename to docs/source/usage/operations/projections/images/nicol.png diff --git a/docs/source/projections/images/nsper.png b/docs/source/usage/operations/projections/images/nsper.png similarity index 100% rename from docs/source/projections/images/nsper.png rename to docs/source/usage/operations/projections/images/nsper.png diff --git a/docs/source/projections/images/nzmg.png b/docs/source/usage/operations/projections/images/nzmg.png similarity index 100% rename from docs/source/projections/images/nzmg.png rename to docs/source/usage/operations/projections/images/nzmg.png diff --git a/docs/source/projections/images/ob_tran.png b/docs/source/usage/operations/projections/images/ob_tran.png similarity index 100% rename from docs/source/projections/images/ob_tran.png rename to docs/source/usage/operations/projections/images/ob_tran.png diff --git a/docs/source/projections/images/ocea.png b/docs/source/usage/operations/projections/images/ocea.png similarity index 100% rename from docs/source/projections/images/ocea.png rename to docs/source/usage/operations/projections/images/ocea.png diff --git a/docs/source/projections/images/oea.png b/docs/source/usage/operations/projections/images/oea.png similarity index 100% rename from docs/source/projections/images/oea.png rename to docs/source/usage/operations/projections/images/oea.png diff --git a/docs/source/projections/images/omerc.png b/docs/source/usage/operations/projections/images/omerc.png similarity index 100% rename from docs/source/projections/images/omerc.png rename to docs/source/usage/operations/projections/images/omerc.png diff --git a/docs/source/projections/images/ortel.png b/docs/source/usage/operations/projections/images/ortel.png similarity index 100% rename from docs/source/projections/images/ortel.png rename to docs/source/usage/operations/projections/images/ortel.png diff --git a/docs/source/projections/images/ortho.png b/docs/source/usage/operations/projections/images/ortho.png similarity index 100% rename from docs/source/projections/images/ortho.png rename to docs/source/usage/operations/projections/images/ortho.png diff --git a/docs/source/projections/images/patterson.png b/docs/source/usage/operations/projections/images/patterson.png similarity index 100% rename from docs/source/projections/images/patterson.png rename to docs/source/usage/operations/projections/images/patterson.png diff --git a/docs/source/projections/images/pconic.png b/docs/source/usage/operations/projections/images/pconic.png similarity index 100% rename from docs/source/projections/images/pconic.png rename to docs/source/usage/operations/projections/images/pconic.png diff --git a/docs/source/projections/images/poly.png b/docs/source/usage/operations/projections/images/poly.png similarity index 100% rename from docs/source/projections/images/poly.png rename to docs/source/usage/operations/projections/images/poly.png diff --git a/docs/source/projections/images/putp1.png b/docs/source/usage/operations/projections/images/putp1.png similarity index 100% rename from docs/source/projections/images/putp1.png rename to docs/source/usage/operations/projections/images/putp1.png diff --git a/docs/source/projections/images/putp2.png b/docs/source/usage/operations/projections/images/putp2.png similarity index 100% rename from docs/source/projections/images/putp2.png rename to docs/source/usage/operations/projections/images/putp2.png diff --git a/docs/source/projections/images/putp3.png b/docs/source/usage/operations/projections/images/putp3.png similarity index 100% rename from docs/source/projections/images/putp3.png rename to docs/source/usage/operations/projections/images/putp3.png diff --git a/docs/source/projections/images/putp3p.png b/docs/source/usage/operations/projections/images/putp3p.png similarity index 100% rename from docs/source/projections/images/putp3p.png rename to docs/source/usage/operations/projections/images/putp3p.png diff --git a/docs/source/projections/images/putp4p.png b/docs/source/usage/operations/projections/images/putp4p.png similarity index 100% rename from docs/source/projections/images/putp4p.png rename to docs/source/usage/operations/projections/images/putp4p.png diff --git a/docs/source/projections/images/putp5.png b/docs/source/usage/operations/projections/images/putp5.png similarity index 100% rename from docs/source/projections/images/putp5.png rename to docs/source/usage/operations/projections/images/putp5.png diff --git a/docs/source/projections/images/putp5p.png b/docs/source/usage/operations/projections/images/putp5p.png similarity index 100% rename from docs/source/projections/images/putp5p.png rename to docs/source/usage/operations/projections/images/putp5p.png diff --git a/docs/source/projections/images/putp6.png b/docs/source/usage/operations/projections/images/putp6.png similarity index 100% rename from docs/source/projections/images/putp6.png rename to docs/source/usage/operations/projections/images/putp6.png diff --git a/docs/source/projections/images/putp6p.png b/docs/source/usage/operations/projections/images/putp6p.png similarity index 100% rename from docs/source/projections/images/putp6p.png rename to docs/source/usage/operations/projections/images/putp6p.png diff --git a/docs/source/projections/images/qsc.png b/docs/source/usage/operations/projections/images/qsc.png similarity index 100% rename from docs/source/projections/images/qsc.png rename to docs/source/usage/operations/projections/images/qsc.png diff --git a/docs/source/projections/images/qua_aut.png b/docs/source/usage/operations/projections/images/qua_aut.png similarity index 100% rename from docs/source/projections/images/qua_aut.png rename to docs/source/usage/operations/projections/images/qua_aut.png diff --git a/docs/source/projections/images/rhealpix.png b/docs/source/usage/operations/projections/images/rhealpix.png similarity index 100% rename from docs/source/projections/images/rhealpix.png rename to docs/source/usage/operations/projections/images/rhealpix.png diff --git a/docs/source/projections/images/robin.png b/docs/source/usage/operations/projections/images/robin.png similarity index 100% rename from docs/source/projections/images/robin.png rename to docs/source/usage/operations/projections/images/robin.png diff --git a/docs/source/projections/images/rouss.png b/docs/source/usage/operations/projections/images/rouss.png similarity index 100% rename from docs/source/projections/images/rouss.png rename to docs/source/usage/operations/projections/images/rouss.png diff --git a/docs/source/projections/images/rpoly.png b/docs/source/usage/operations/projections/images/rpoly.png similarity index 100% rename from docs/source/projections/images/rpoly.png rename to docs/source/usage/operations/projections/images/rpoly.png diff --git a/docs/source/projections/images/sinu.png b/docs/source/usage/operations/projections/images/sinu.png similarity index 100% rename from docs/source/projections/images/sinu.png rename to docs/source/usage/operations/projections/images/sinu.png diff --git a/docs/source/projections/images/somerc.png b/docs/source/usage/operations/projections/images/somerc.png similarity index 100% rename from docs/source/projections/images/somerc.png rename to docs/source/usage/operations/projections/images/somerc.png diff --git a/docs/source/projections/images/stere.png b/docs/source/usage/operations/projections/images/stere.png similarity index 100% rename from docs/source/projections/images/stere.png rename to docs/source/usage/operations/projections/images/stere.png diff --git a/docs/source/projections/images/sterea.png b/docs/source/usage/operations/projections/images/sterea.png similarity index 100% rename from docs/source/projections/images/sterea.png rename to docs/source/usage/operations/projections/images/sterea.png diff --git a/docs/source/projections/images/tcc.png b/docs/source/usage/operations/projections/images/tcc.png similarity index 100% rename from docs/source/projections/images/tcc.png rename to docs/source/usage/operations/projections/images/tcc.png diff --git a/docs/source/projections/images/tcea.png b/docs/source/usage/operations/projections/images/tcea.png similarity index 100% rename from docs/source/projections/images/tcea.png rename to docs/source/usage/operations/projections/images/tcea.png diff --git a/docs/source/projections/images/tissot.png b/docs/source/usage/operations/projections/images/tissot.png similarity index 100% rename from docs/source/projections/images/tissot.png rename to docs/source/usage/operations/projections/images/tissot.png diff --git a/docs/source/projections/images/tmerc.png b/docs/source/usage/operations/projections/images/tmerc.png similarity index 100% rename from docs/source/projections/images/tmerc.png rename to docs/source/usage/operations/projections/images/tmerc.png diff --git a/docs/source/projections/images/tpeqd.png b/docs/source/usage/operations/projections/images/tpeqd.png similarity index 100% rename from docs/source/projections/images/tpeqd.png rename to docs/source/usage/operations/projections/images/tpeqd.png diff --git a/docs/source/projections/images/tpers.png b/docs/source/usage/operations/projections/images/tpers.png similarity index 100% rename from docs/source/projections/images/tpers.png rename to docs/source/usage/operations/projections/images/tpers.png diff --git a/docs/source/projections/images/ups.png b/docs/source/usage/operations/projections/images/ups.png similarity index 100% rename from docs/source/projections/images/ups.png rename to docs/source/usage/operations/projections/images/ups.png diff --git a/docs/source/projections/images/urm5.png b/docs/source/usage/operations/projections/images/urm5.png similarity index 100% rename from docs/source/projections/images/urm5.png rename to docs/source/usage/operations/projections/images/urm5.png diff --git a/docs/source/projections/images/urmfps.png b/docs/source/usage/operations/projections/images/urmfps.png similarity index 100% rename from docs/source/projections/images/urmfps.png rename to docs/source/usage/operations/projections/images/urmfps.png diff --git a/docs/source/projections/images/utm.png b/docs/source/usage/operations/projections/images/utm.png similarity index 100% rename from docs/source/projections/images/utm.png rename to docs/source/usage/operations/projections/images/utm.png diff --git a/docs/source/projections/images/vandg.png b/docs/source/usage/operations/projections/images/vandg.png similarity index 100% rename from docs/source/projections/images/vandg.png rename to docs/source/usage/operations/projections/images/vandg.png diff --git a/docs/source/projections/images/vandg2.png b/docs/source/usage/operations/projections/images/vandg2.png similarity index 100% rename from docs/source/projections/images/vandg2.png rename to docs/source/usage/operations/projections/images/vandg2.png diff --git a/docs/source/projections/images/vandg3.png b/docs/source/usage/operations/projections/images/vandg3.png similarity index 100% rename from docs/source/projections/images/vandg3.png rename to docs/source/usage/operations/projections/images/vandg3.png diff --git a/docs/source/projections/images/vandg4.png b/docs/source/usage/operations/projections/images/vandg4.png similarity index 100% rename from docs/source/projections/images/vandg4.png rename to docs/source/usage/operations/projections/images/vandg4.png diff --git a/docs/source/projections/images/vitk1.png b/docs/source/usage/operations/projections/images/vitk1.png similarity index 100% rename from docs/source/projections/images/vitk1.png rename to docs/source/usage/operations/projections/images/vitk1.png diff --git a/docs/source/projections/images/wag1.png b/docs/source/usage/operations/projections/images/wag1.png similarity index 100% rename from docs/source/projections/images/wag1.png rename to docs/source/usage/operations/projections/images/wag1.png diff --git a/docs/source/projections/images/wag2.png b/docs/source/usage/operations/projections/images/wag2.png similarity index 100% rename from docs/source/projections/images/wag2.png rename to docs/source/usage/operations/projections/images/wag2.png diff --git a/docs/source/projections/images/wag3.png b/docs/source/usage/operations/projections/images/wag3.png similarity index 100% rename from docs/source/projections/images/wag3.png rename to docs/source/usage/operations/projections/images/wag3.png diff --git a/docs/source/projections/images/wag4.png b/docs/source/usage/operations/projections/images/wag4.png similarity index 100% rename from docs/source/projections/images/wag4.png rename to docs/source/usage/operations/projections/images/wag4.png diff --git a/docs/source/projections/images/wag5.png b/docs/source/usage/operations/projections/images/wag5.png similarity index 100% rename from docs/source/projections/images/wag5.png rename to docs/source/usage/operations/projections/images/wag5.png diff --git a/docs/source/projections/images/wag6.png b/docs/source/usage/operations/projections/images/wag6.png similarity index 100% rename from docs/source/projections/images/wag6.png rename to docs/source/usage/operations/projections/images/wag6.png diff --git a/docs/source/projections/images/wag7.png b/docs/source/usage/operations/projections/images/wag7.png similarity index 100% rename from docs/source/projections/images/wag7.png rename to docs/source/usage/operations/projections/images/wag7.png diff --git a/docs/source/projections/images/weren.png b/docs/source/usage/operations/projections/images/weren.png similarity index 100% rename from docs/source/projections/images/weren.png rename to docs/source/usage/operations/projections/images/weren.png diff --git a/docs/source/projections/images/wink1.png b/docs/source/usage/operations/projections/images/wink1.png similarity index 100% rename from docs/source/projections/images/wink1.png rename to docs/source/usage/operations/projections/images/wink1.png diff --git a/docs/source/projections/images/wink2.png b/docs/source/usage/operations/projections/images/wink2.png similarity index 100% rename from docs/source/projections/images/wink2.png rename to docs/source/usage/operations/projections/images/wink2.png diff --git a/docs/source/projections/images/wintri.png b/docs/source/usage/operations/projections/images/wintri.png similarity index 100% rename from docs/source/projections/images/wintri.png rename to docs/source/usage/operations/projections/images/wintri.png diff --git a/docs/source/projections/imw_p.rst b/docs/source/usage/operations/projections/imw_p.rst similarity index 100% rename from docs/source/projections/imw_p.rst rename to docs/source/usage/operations/projections/imw_p.rst diff --git a/docs/source/projections/index.rst b/docs/source/usage/operations/projections/index.rst similarity index 100% rename from docs/source/projections/index.rst rename to docs/source/usage/operations/projections/index.rst diff --git a/docs/source/projections/isea.rst b/docs/source/usage/operations/projections/isea.rst similarity index 100% rename from docs/source/projections/isea.rst rename to docs/source/usage/operations/projections/isea.rst diff --git a/docs/source/projections/kav5.rst b/docs/source/usage/operations/projections/kav5.rst similarity index 100% rename from docs/source/projections/kav5.rst rename to docs/source/usage/operations/projections/kav5.rst diff --git a/docs/source/projections/kav7.rst b/docs/source/usage/operations/projections/kav7.rst similarity index 100% rename from docs/source/projections/kav7.rst rename to docs/source/usage/operations/projections/kav7.rst diff --git a/docs/source/projections/krovak.rst b/docs/source/usage/operations/projections/krovak.rst similarity index 100% rename from docs/source/projections/krovak.rst rename to docs/source/usage/operations/projections/krovak.rst diff --git a/docs/source/projections/labrd.rst b/docs/source/usage/operations/projections/labrd.rst similarity index 100% rename from docs/source/projections/labrd.rst rename to docs/source/usage/operations/projections/labrd.rst diff --git a/docs/source/projections/laea.rst b/docs/source/usage/operations/projections/laea.rst similarity index 100% rename from docs/source/projections/laea.rst rename to docs/source/usage/operations/projections/laea.rst diff --git a/docs/source/projections/lagrng.rst b/docs/source/usage/operations/projections/lagrng.rst similarity index 100% rename from docs/source/projections/lagrng.rst rename to docs/source/usage/operations/projections/lagrng.rst diff --git a/docs/source/projections/larr.rst b/docs/source/usage/operations/projections/larr.rst similarity index 100% rename from docs/source/projections/larr.rst rename to docs/source/usage/operations/projections/larr.rst diff --git a/docs/source/projections/lask.rst b/docs/source/usage/operations/projections/lask.rst similarity index 100% rename from docs/source/projections/lask.rst rename to docs/source/usage/operations/projections/lask.rst diff --git a/docs/source/projections/latlon.rst b/docs/source/usage/operations/projections/latlon.rst similarity index 100% rename from docs/source/projections/latlon.rst rename to docs/source/usage/operations/projections/latlon.rst diff --git a/docs/source/projections/lcc.rst b/docs/source/usage/operations/projections/lcc.rst similarity index 100% rename from docs/source/projections/lcc.rst rename to docs/source/usage/operations/projections/lcc.rst diff --git a/docs/source/projections/lcca.rst b/docs/source/usage/operations/projections/lcca.rst similarity index 100% rename from docs/source/projections/lcca.rst rename to docs/source/usage/operations/projections/lcca.rst diff --git a/docs/source/projections/leac.rst b/docs/source/usage/operations/projections/leac.rst similarity index 100% rename from docs/source/projections/leac.rst rename to docs/source/usage/operations/projections/leac.rst diff --git a/docs/source/projections/lee_os.rst b/docs/source/usage/operations/projections/lee_os.rst similarity index 100% rename from docs/source/projections/lee_os.rst rename to docs/source/usage/operations/projections/lee_os.rst diff --git a/docs/source/projections/lonlat.rst b/docs/source/usage/operations/projections/lonlat.rst similarity index 100% rename from docs/source/projections/lonlat.rst rename to docs/source/usage/operations/projections/lonlat.rst diff --git a/docs/source/projections/loxim.rst b/docs/source/usage/operations/projections/loxim.rst similarity index 100% rename from docs/source/projections/loxim.rst rename to docs/source/usage/operations/projections/loxim.rst diff --git a/docs/source/projections/lsat.rst b/docs/source/usage/operations/projections/lsat.rst similarity index 100% rename from docs/source/projections/lsat.rst rename to docs/source/usage/operations/projections/lsat.rst diff --git a/docs/source/projections/mbt_fps.rst b/docs/source/usage/operations/projections/mbt_fps.rst similarity index 100% rename from docs/source/projections/mbt_fps.rst rename to docs/source/usage/operations/projections/mbt_fps.rst diff --git a/docs/source/projections/mbt_s.rst b/docs/source/usage/operations/projections/mbt_s.rst similarity index 100% rename from docs/source/projections/mbt_s.rst rename to docs/source/usage/operations/projections/mbt_s.rst diff --git a/docs/source/projections/mbtfpp.rst b/docs/source/usage/operations/projections/mbtfpp.rst similarity index 100% rename from docs/source/projections/mbtfpp.rst rename to docs/source/usage/operations/projections/mbtfpp.rst diff --git a/docs/source/projections/mbtfpq.rst b/docs/source/usage/operations/projections/mbtfpq.rst similarity index 100% rename from docs/source/projections/mbtfpq.rst rename to docs/source/usage/operations/projections/mbtfpq.rst diff --git a/docs/source/projections/mbtfps.rst b/docs/source/usage/operations/projections/mbtfps.rst similarity index 100% rename from docs/source/projections/mbtfps.rst rename to docs/source/usage/operations/projections/mbtfps.rst diff --git a/docs/source/projections/merc.rst b/docs/source/usage/operations/projections/merc.rst similarity index 100% rename from docs/source/projections/merc.rst rename to docs/source/usage/operations/projections/merc.rst diff --git a/docs/source/projections/mil_os.rst b/docs/source/usage/operations/projections/mil_os.rst similarity index 100% rename from docs/source/projections/mil_os.rst rename to docs/source/usage/operations/projections/mil_os.rst diff --git a/docs/source/projections/mill.rst b/docs/source/usage/operations/projections/mill.rst similarity index 100% rename from docs/source/projections/mill.rst rename to docs/source/usage/operations/projections/mill.rst diff --git a/docs/source/projections/moll.rst b/docs/source/usage/operations/projections/moll.rst similarity index 100% rename from docs/source/projections/moll.rst rename to docs/source/usage/operations/projections/moll.rst diff --git a/docs/source/projections/murd1.rst b/docs/source/usage/operations/projections/murd1.rst similarity index 100% rename from docs/source/projections/murd1.rst rename to docs/source/usage/operations/projections/murd1.rst diff --git a/docs/source/projections/murd2.rst b/docs/source/usage/operations/projections/murd2.rst similarity index 100% rename from docs/source/projections/murd2.rst rename to docs/source/usage/operations/projections/murd2.rst diff --git a/docs/source/projections/murd3.rst b/docs/source/usage/operations/projections/murd3.rst similarity index 100% rename from docs/source/projections/murd3.rst rename to docs/source/usage/operations/projections/murd3.rst diff --git a/docs/source/projections/natearth.rst b/docs/source/usage/operations/projections/natearth.rst similarity index 100% rename from docs/source/projections/natearth.rst rename to docs/source/usage/operations/projections/natearth.rst diff --git a/docs/source/projections/nell.rst b/docs/source/usage/operations/projections/nell.rst similarity index 100% rename from docs/source/projections/nell.rst rename to docs/source/usage/operations/projections/nell.rst diff --git a/docs/source/projections/nell_h.rst b/docs/source/usage/operations/projections/nell_h.rst similarity index 100% rename from docs/source/projections/nell_h.rst rename to docs/source/usage/operations/projections/nell_h.rst diff --git a/docs/source/projections/nicol.rst b/docs/source/usage/operations/projections/nicol.rst similarity index 100% rename from docs/source/projections/nicol.rst rename to docs/source/usage/operations/projections/nicol.rst diff --git a/docs/source/projections/nsper.rst b/docs/source/usage/operations/projections/nsper.rst similarity index 100% rename from docs/source/projections/nsper.rst rename to docs/source/usage/operations/projections/nsper.rst diff --git a/docs/source/projections/nzmg.rst b/docs/source/usage/operations/projections/nzmg.rst similarity index 100% rename from docs/source/projections/nzmg.rst rename to docs/source/usage/operations/projections/nzmg.rst diff --git a/docs/source/projections/ob_tran.rst b/docs/source/usage/operations/projections/ob_tran.rst similarity index 100% rename from docs/source/projections/ob_tran.rst rename to docs/source/usage/operations/projections/ob_tran.rst diff --git a/docs/source/projections/ocea.rst b/docs/source/usage/operations/projections/ocea.rst similarity index 100% rename from docs/source/projections/ocea.rst rename to docs/source/usage/operations/projections/ocea.rst diff --git a/docs/source/projections/oea.rst b/docs/source/usage/operations/projections/oea.rst similarity index 100% rename from docs/source/projections/oea.rst rename to docs/source/usage/operations/projections/oea.rst diff --git a/docs/source/projections/omerc.rst b/docs/source/usage/operations/projections/omerc.rst similarity index 100% rename from docs/source/projections/omerc.rst rename to docs/source/usage/operations/projections/omerc.rst diff --git a/docs/source/projections/ortel.rst b/docs/source/usage/operations/projections/ortel.rst similarity index 100% rename from docs/source/projections/ortel.rst rename to docs/source/usage/operations/projections/ortel.rst diff --git a/docs/source/projections/ortho.rst b/docs/source/usage/operations/projections/ortho.rst similarity index 100% rename from docs/source/projections/ortho.rst rename to docs/source/usage/operations/projections/ortho.rst diff --git a/docs/source/projections/pconic.rst b/docs/source/usage/operations/projections/pconic.rst similarity index 100% rename from docs/source/projections/pconic.rst rename to docs/source/usage/operations/projections/pconic.rst diff --git a/docs/source/projections/poly.rst b/docs/source/usage/operations/projections/poly.rst similarity index 100% rename from docs/source/projections/poly.rst rename to docs/source/usage/operations/projections/poly.rst diff --git a/docs/source/projections/putp1.rst b/docs/source/usage/operations/projections/putp1.rst similarity index 100% rename from docs/source/projections/putp1.rst rename to docs/source/usage/operations/projections/putp1.rst diff --git a/docs/source/projections/putp2.rst b/docs/source/usage/operations/projections/putp2.rst similarity index 100% rename from docs/source/projections/putp2.rst rename to docs/source/usage/operations/projections/putp2.rst diff --git a/docs/source/projections/putp3.rst b/docs/source/usage/operations/projections/putp3.rst similarity index 100% rename from docs/source/projections/putp3.rst rename to docs/source/usage/operations/projections/putp3.rst diff --git a/docs/source/projections/putp3p.rst b/docs/source/usage/operations/projections/putp3p.rst similarity index 100% rename from docs/source/projections/putp3p.rst rename to docs/source/usage/operations/projections/putp3p.rst diff --git a/docs/source/projections/putp4p.rst b/docs/source/usage/operations/projections/putp4p.rst similarity index 100% rename from docs/source/projections/putp4p.rst rename to docs/source/usage/operations/projections/putp4p.rst diff --git a/docs/source/projections/putp5.rst b/docs/source/usage/operations/projections/putp5.rst similarity index 100% rename from docs/source/projections/putp5.rst rename to docs/source/usage/operations/projections/putp5.rst diff --git a/docs/source/projections/putp5p.rst b/docs/source/usage/operations/projections/putp5p.rst similarity index 100% rename from docs/source/projections/putp5p.rst rename to docs/source/usage/operations/projections/putp5p.rst diff --git a/docs/source/projections/putp6.rst b/docs/source/usage/operations/projections/putp6.rst similarity index 100% rename from docs/source/projections/putp6.rst rename to docs/source/usage/operations/projections/putp6.rst diff --git a/docs/source/projections/putp6p.rst b/docs/source/usage/operations/projections/putp6p.rst similarity index 100% rename from docs/source/projections/putp6p.rst rename to docs/source/usage/operations/projections/putp6p.rst diff --git a/docs/source/projections/qsc.rst b/docs/source/usage/operations/projections/qsc.rst similarity index 94% rename from docs/source/projections/qsc.rst rename to docs/source/usage/operations/projections/qsc.rst index dedd6ff4de..e3af2cee05 100644 --- a/docs/source/projections/qsc.rst +++ b/docs/source/usage/operations/projections/qsc.rst @@ -23,7 +23,7 @@ Quadrilateralized Spherical Cube The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project a sphere surface onto the six sides of a cube: -.. image:: ../../images/qsc_concept.jpg +.. image:: ../../../../images/qsc_concept.jpg :scale: 50% :align: center :alt: Quadrilateralized Spherical Cube @@ -112,32 +112,32 @@ Explanation: The resulting images can be laid out in a grid like below. -.. |topside| image:: ../../images/qsc_topside.jpg +.. |topside| image:: ../../../../images/qsc_topside.jpg :scale: 50% :align: middle :alt: Top side -.. |leftside| image:: ../../images/qsc_leftside.jpg +.. |leftside| image:: ../../../../images/qsc_leftside.jpg :scale: 50% :align: middle :alt: Left side -.. |frontside| image:: ../../images/qsc_frontside.jpg +.. |frontside| image:: ../../../../images/qsc_frontside.jpg :scale: 50% :align: middle :alt: Front side -.. |rightside| image:: ../../images/qsc_rightside.jpg +.. |rightside| image:: ../../../../images/qsc_rightside.jpg :scale: 50% :align: middle :alt: Right side -.. |backside| image:: ../../images/qsc_backside.jpg +.. |backside| image:: ../../../../images/qsc_backside.jpg :scale: 50% :align: middle :alt: Back side -.. |bottomside| image:: ../../images/qsc_bottomside.jpg +.. |bottomside| image:: ../../../../images/qsc_bottomside.jpg :scale: 50% :align: middle :alt: Bottom side diff --git a/docs/source/projections/qua_aut.rst b/docs/source/usage/operations/projections/qua_aut.rst similarity index 100% rename from docs/source/projections/qua_aut.rst rename to docs/source/usage/operations/projections/qua_aut.rst diff --git a/docs/source/projections/rhealpix.rst b/docs/source/usage/operations/projections/rhealpix.rst similarity index 98% rename from docs/source/projections/rhealpix.rst rename to docs/source/usage/operations/projections/rhealpix.rst index 1701558e05..5808cfaaad 100644 --- a/docs/source/projections/rhealpix.rst +++ b/docs/source/usage/operations/projections/rhealpix.rst @@ -21,7 +21,7 @@ rHEALPix | | Valid inputs are 0--3. Defaults to 0. | +---------------------+----------------------------------------------------------+ -.. image:: ../../images/rhealpix.png +.. image:: ../../../../images/rhealpix.png :scale: 75% :alt: rHEALPix diff --git a/docs/source/projections/robin.rst b/docs/source/usage/operations/projections/robin.rst similarity index 100% rename from docs/source/projections/robin.rst rename to docs/source/usage/operations/projections/robin.rst diff --git a/docs/source/projections/rouss.rst b/docs/source/usage/operations/projections/rouss.rst similarity index 100% rename from docs/source/projections/rouss.rst rename to docs/source/usage/operations/projections/rouss.rst diff --git a/docs/source/projections/rpoly.rst b/docs/source/usage/operations/projections/rpoly.rst similarity index 100% rename from docs/source/projections/rpoly.rst rename to docs/source/usage/operations/projections/rpoly.rst diff --git a/docs/source/projections/sinu.rst b/docs/source/usage/operations/projections/sinu.rst similarity index 100% rename from docs/source/projections/sinu.rst rename to docs/source/usage/operations/projections/sinu.rst diff --git a/docs/source/projections/somerc.rst b/docs/source/usage/operations/projections/somerc.rst similarity index 100% rename from docs/source/projections/somerc.rst rename to docs/source/usage/operations/projections/somerc.rst diff --git a/docs/source/projections/stere.rst b/docs/source/usage/operations/projections/stere.rst similarity index 100% rename from docs/source/projections/stere.rst rename to docs/source/usage/operations/projections/stere.rst diff --git a/docs/source/projections/sterea.rst b/docs/source/usage/operations/projections/sterea.rst similarity index 100% rename from docs/source/projections/sterea.rst rename to docs/source/usage/operations/projections/sterea.rst diff --git a/docs/source/projections/tcc.rst b/docs/source/usage/operations/projections/tcc.rst similarity index 100% rename from docs/source/projections/tcc.rst rename to docs/source/usage/operations/projections/tcc.rst diff --git a/docs/source/projections/tcea.rst b/docs/source/usage/operations/projections/tcea.rst similarity index 100% rename from docs/source/projections/tcea.rst rename to docs/source/usage/operations/projections/tcea.rst diff --git a/docs/source/projections/tissot.rst b/docs/source/usage/operations/projections/tissot.rst similarity index 100% rename from docs/source/projections/tissot.rst rename to docs/source/usage/operations/projections/tissot.rst diff --git a/docs/source/projections/tmerc.rst b/docs/source/usage/operations/projections/tmerc.rst similarity index 100% rename from docs/source/projections/tmerc.rst rename to docs/source/usage/operations/projections/tmerc.rst diff --git a/docs/source/projections/tpeqd.rst b/docs/source/usage/operations/projections/tpeqd.rst similarity index 100% rename from docs/source/projections/tpeqd.rst rename to docs/source/usage/operations/projections/tpeqd.rst diff --git a/docs/source/projections/tpers.rst b/docs/source/usage/operations/projections/tpers.rst similarity index 100% rename from docs/source/projections/tpers.rst rename to docs/source/usage/operations/projections/tpers.rst diff --git a/docs/source/projections/ups.rst b/docs/source/usage/operations/projections/ups.rst similarity index 100% rename from docs/source/projections/ups.rst rename to docs/source/usage/operations/projections/ups.rst diff --git a/docs/source/projections/urm5.rst b/docs/source/usage/operations/projections/urm5.rst similarity index 100% rename from docs/source/projections/urm5.rst rename to docs/source/usage/operations/projections/urm5.rst diff --git a/docs/source/projections/urmfps.rst b/docs/source/usage/operations/projections/urmfps.rst similarity index 100% rename from docs/source/projections/urmfps.rst rename to docs/source/usage/operations/projections/urmfps.rst diff --git a/docs/source/projections/utm.rst b/docs/source/usage/operations/projections/utm.rst similarity index 100% rename from docs/source/projections/utm.rst rename to docs/source/usage/operations/projections/utm.rst diff --git a/docs/source/projections/vandg.rst b/docs/source/usage/operations/projections/vandg.rst similarity index 100% rename from docs/source/projections/vandg.rst rename to docs/source/usage/operations/projections/vandg.rst diff --git a/docs/source/projections/vandg2.rst b/docs/source/usage/operations/projections/vandg2.rst similarity index 100% rename from docs/source/projections/vandg2.rst rename to docs/source/usage/operations/projections/vandg2.rst diff --git a/docs/source/projections/vandg3.rst b/docs/source/usage/operations/projections/vandg3.rst similarity index 100% rename from docs/source/projections/vandg3.rst rename to docs/source/usage/operations/projections/vandg3.rst diff --git a/docs/source/projections/vandg4.rst b/docs/source/usage/operations/projections/vandg4.rst similarity index 100% rename from docs/source/projections/vandg4.rst rename to docs/source/usage/operations/projections/vandg4.rst diff --git a/docs/source/projections/vitk1.rst b/docs/source/usage/operations/projections/vitk1.rst similarity index 100% rename from docs/source/projections/vitk1.rst rename to docs/source/usage/operations/projections/vitk1.rst diff --git a/docs/source/projections/wag1.rst b/docs/source/usage/operations/projections/wag1.rst similarity index 100% rename from docs/source/projections/wag1.rst rename to docs/source/usage/operations/projections/wag1.rst diff --git a/docs/source/projections/wag2.rst b/docs/source/usage/operations/projections/wag2.rst similarity index 100% rename from docs/source/projections/wag2.rst rename to docs/source/usage/operations/projections/wag2.rst diff --git a/docs/source/projections/wag3.rst b/docs/source/usage/operations/projections/wag3.rst similarity index 100% rename from docs/source/projections/wag3.rst rename to docs/source/usage/operations/projections/wag3.rst diff --git a/docs/source/projections/wag4.rst b/docs/source/usage/operations/projections/wag4.rst similarity index 100% rename from docs/source/projections/wag4.rst rename to docs/source/usage/operations/projections/wag4.rst diff --git a/docs/source/projections/wag5.rst b/docs/source/usage/operations/projections/wag5.rst similarity index 100% rename from docs/source/projections/wag5.rst rename to docs/source/usage/operations/projections/wag5.rst diff --git a/docs/source/projections/wag6.rst b/docs/source/usage/operations/projections/wag6.rst similarity index 100% rename from docs/source/projections/wag6.rst rename to docs/source/usage/operations/projections/wag6.rst diff --git a/docs/source/projections/wag7.rst b/docs/source/usage/operations/projections/wag7.rst similarity index 100% rename from docs/source/projections/wag7.rst rename to docs/source/usage/operations/projections/wag7.rst diff --git a/docs/source/projections/weren.rst b/docs/source/usage/operations/projections/weren.rst similarity index 100% rename from docs/source/projections/weren.rst rename to docs/source/usage/operations/projections/weren.rst diff --git a/docs/source/projections/wink1.rst b/docs/source/usage/operations/projections/wink1.rst similarity index 100% rename from docs/source/projections/wink1.rst rename to docs/source/usage/operations/projections/wink1.rst diff --git a/docs/source/projections/wink2.rst b/docs/source/usage/operations/projections/wink2.rst similarity index 100% rename from docs/source/projections/wink2.rst rename to docs/source/usage/operations/projections/wink2.rst diff --git a/docs/source/projections/wintri.rst b/docs/source/usage/operations/projections/wintri.rst similarity index 100% rename from docs/source/projections/wintri.rst rename to docs/source/usage/operations/projections/wintri.rst diff --git a/docs/source/usage/operations/transformations/cart.rst b/docs/source/usage/operations/transformations/cart.rst new file mode 100644 index 0000000000..0c3c7c239b --- /dev/null +++ b/docs/source/usage/operations/transformations/cart.rst @@ -0,0 +1,24 @@ +.. _cart: + +================================================================================ +Cartesian to geodetic conversion +================================================================================ + +Convert geodetic coordinates to cartesian coordinates. + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+ellps` | Ellipsoid of the input coordinates. If used together with the | +| |  ellipsoid parameters below, ``+ellps`` is overwritten. | ++--------------+--------------------------------------------------------------------+ +| `+a` | Semi-major radius of ellipsoid axis. | ++--------------+--------------------------------------------------------------------+ +| `+b` | Semi-minor radius of ellipsoid axis. | ++--------------+--------------------------------------------------------------------+ +| `+es` | Eccentricity of ellipsoid. | ++--------------+--------------------------------------------------------------------+ +| `+f` | Flattening of ellipsoid. | ++--------------+--------------------------------------------------------------------+ + + diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst new file mode 100644 index 0000000000..46073b633b --- /dev/null +++ b/docs/source/usage/operations/transformations/helmert.rst @@ -0,0 +1,7 @@ +.. _helmert: + +================================================================================ +Helmert transform +================================================================================ + +Change reference frame by Helmert shift. diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst new file mode 100644 index 0000000000..78e46aa917 --- /dev/null +++ b/docs/source/usage/operations/transformations/hgridshift.rst @@ -0,0 +1,32 @@ +.. _hgridshift: + +================================================================================ +Horizontal grid shift +================================================================================ + +Change of horizontal datum by grid shift. + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++--------------+--------------------------------------------------------------------+ + +The horizontal grid shift is done by offsetting the planar input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid:: + + +hgridshift +grids=nzgr2kgrid0005.gsb + + +More than one grid can be loaded at the same time, for instance in case the +dataset needs to be transformed spans several countries. In this example grids +of the continental US, Alaska and Canada is loaded at the same time:: + + +hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ.4 search path. The list of grids is prioritized so that +grids in the start of the list takes presedence over the grids in the back of the +list. + diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst new file mode 100644 index 0000000000..8bf2a89031 --- /dev/null +++ b/docs/source/usage/operations/transformations/index.rst @@ -0,0 +1,15 @@ +.. _transformation_list: + +================================================================================ +Transformations +================================================================================ + +.. toctree:: + :maxdepth: 1 + + cart + helmert + molodensky + hgridshift + vgridshift + unitconvert diff --git a/docs/source/usage/operations/transformations/molodensky.rst b/docs/source/usage/operations/transformations/molodensky.rst new file mode 100644 index 0000000000..3fa8f9a887 --- /dev/null +++ b/docs/source/usage/operations/transformations/molodensky.rst @@ -0,0 +1,7 @@ +.. _molodensky: + +================================================================================ +Molodensky transform +================================================================================ + +Perform a datum shift in geodetic coordinate space. diff --git a/docs/source/usage/operations/transformations/unitconvert.rst b/docs/source/usage/operations/transformations/unitconvert.rst new file mode 100644 index 0000000000..458d0c1536 --- /dev/null +++ b/docs/source/usage/operations/transformations/unitconvert.rst @@ -0,0 +1,7 @@ +.. _unitconvert: + +================================================================================ +Unit conversion +================================================================================ + +Convert between various distance and time units. diff --git a/docs/source/usage/operations/transformations/vgridshift.rst b/docs/source/usage/operations/transformations/vgridshift.rst new file mode 100644 index 0000000000..f48d40c8fd --- /dev/null +++ b/docs/source/usage/operations/transformations/vgridshift.rst @@ -0,0 +1,34 @@ +.. _vgridshift: + +================================================================================ +Vertical grid shift +================================================================================ + +Change Vertical datum change by grid shift + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++--------------+--------------------------------------------------------------------+ + +The vertical grid shift is done by offsetting the vertical input coordinates by +a specific amount determined by the loaded grids. The simplest use case of the +horizontal grid shift is applying a single grid. Here we change the vertical +reference from the ellipsoid to the global geoid model, EGM96:: + + +vgridshift +grids=egm96_16.gtx + + +More than one grid can be loaded at the same time, for instance in the case where +a better geoid model than the global is available for a certain area. Here the +gridshift is set up so that the local DVR90 geoid model takes presedence over +the global model:: + + +vgridshift +grids=@dvr90.gtx,egm96_16.gtx + +The ``@`` in the above example states that the grid is optional, in case the grid +is not found in the PROJ.4 search path. The list of grids is prioritized so that +grids in the start of the list takes presedence over the grids in the back of the +list. + From 1f546602f1da800199ad298968154f2c71de6daf Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 27 Sep 2017 22:06:29 +0200 Subject: [PATCH 09/43] add proj_errno_* functions to API reference --- .../development/reference/functions.rst | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index fc546f3340..3b6d448908 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -297,6 +297,69 @@ Initializers :type `flags`: unsigned int :returns: :c:type:`PJ_OBS` +Error reporting +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: int proj_errno(PJ *P) + + Get a reading of the current error-state of :c:data:`P`. An non-zero error + codes indicates an error either with the transformation setup or during a + transformation. + + :param: PJ* P: Transformation object. + + :returns: :c:type:`int` + +.. c:function:: void proj_errno_set(PJ *P, int err) + +Change the error-state of :c:data:`P` to `err`. + + :param PJ* P: Transformation object. + :param int err: Error number. + +.. c:function:: int proj_errno_reset(PJ *P) + + Clears the error number in :c:data:`P`, and bubbles it up to the context. + + Example: + + .. code-block:: C + + void foo (PJ *P) { + int last_errno = proj_errno_reset (P); + + do_something_with_P (P); + + /* failure - keep latest error status */ + if (proj_errno(P)) + return; + /* success - restore previous error status */ + proj_errno_restore (P, last_errno); + return; + } + + :param: PJ* P: Transformation object. + + :returns: :c:type:`int` Returns the previous value of the errno, for convenient reset/restore operations. + +.. c:function:: void proj_errno_restore(PJ *P, int err) + + Reduce some mental impedance in the canonical reset/restore use case: + Basically, :c:func:`proj_errno_restore()` is a synonym for + :c:func:`proj_errno_set()`, but the use cases are very different: + *set* indicate an error to higher level user code, *restore* passes previously + set error indicators in case of no errors at this level. + + Hence, although the inner working is identical, we provide both options, + to avoid some rather confusing real world code. + + See usage example under :c:func:`proj_errno_reset` + + :param PJ* P: Transformation object. + :param int err: Error code. + + + Info functions ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ From c9376a4700ca71605c27fa84e0ad49d043846158 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 27 Sep 2017 23:13:16 +0200 Subject: [PATCH 10/43] Add section PROJ.4 environment variables. --- docs/source/usage/environmentvars.rst | 43 +++++++++++++++++++++++++++ docs/source/usage/index.rst | 1 + 2 files changed, 44 insertions(+) create mode 100644 docs/source/usage/environmentvars.rst diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst new file mode 100644 index 0000000000..38cb46de8a --- /dev/null +++ b/docs/source/usage/environmentvars.rst @@ -0,0 +1,43 @@ +.. _environmentvars: + +================================================================================ +Environment variables +================================================================================ + +PROJ.4 can be crontrolled by setting environment variables. Most users will +have a use for the :envvar:`PROJ_LIB`. + +On UNIX systems environment variables can be set for a shell-session with:: + + $ export VAR="some variable" + +or it can be set for just one command line call:: + + $ VAR="some variable" ./cmd + +Environment variables on UNIX are usually removed with the ``unset`` command:: + + $ unset VAR + +On windows systems environment variables can be set in the command line with:: + + > set VAR="some variable" + +```VAR`` will be available for the entire session, unless it is unset. This is +done by setting the variable with no content:: + + > set VAR= + +.. envvar:: PROJ_LIB + + The location of PROJ.4 :doc:`resource files`. + It is only possible to specify a single library in :envvar:`PROJ_LIB`; e.g. it + does not behave like PATH. PROJ.4 is hardcoded to look for resource files + in other locations as well, amongst those are the users home directory, + ``/usr/share/proj`` and the current folder. + +.. envvar:: PROJ_DEBUG + + Set the debug level of PROJ.4. The default debug level is zero, which results + in no debug output when using PROJ.4. A number from 1-3, whit 3 being the most + verbose setting. diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst index 5979426a8e..81ea4b6b8b 100644 --- a/docs/source/usage/index.rst +++ b/docs/source/usage/index.rst @@ -17,5 +17,6 @@ command line applications or the C API that is a part of the software package. projections transformation resource_files + environmentvars operations/index From f8d26297de7f6092e78bcd33876510c7082c3f35 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 9 Oct 2017 21:48:24 +0200 Subject: [PATCH 11/43] Add PJ_DIRECTION to API referece [skip ci] --- .../development/reference/datatypes.rst | 29 +++++++++++++++++++ .../development/reference/functions.rst | 27 +++++++++-------- 2 files changed, 44 insertions(+), 12 deletions(-) diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 991fcfc5c0..7e314dced3 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -21,6 +21,34 @@ Transformation objects are created with :c:func:`proj_create` and destroyed with :c:func:`proj_destroy`. +.. c:type:: PJ_DIRECTION + + Enumeration that is used to convey in which direction a given transformation + should be performed. Used in transformation function call as described in + the section on :ref:`transformation functions `. + + Forward transformations are defined with the :c: + + .. code-block:: C + + typedef enum proj_direction { + PJ_FWD = 1, /* Forward */ + PJ_IDENT = 0, /* Do nothing */ + PJ_INV = -1 /* Inverse */ + } PJ_DIRECTION; + + .. c:member:: PJ_FWD + + Perform transformation in the forward direction. + + .. c:member:: PJ_IDENT + + Identity. Do nothing. + + .. c:member:: PJ_INV + + Perform transformation in the inverse direction. + .. c:type:: PJ_CONTEXT Context objects enables safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` @@ -29,6 +57,7 @@ Transformation objects :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` and destroyed with :c:func:`proj_context_destroy`. + 2 dimensional coordinates -------------------------------------------------------------------------------- diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 3b6d448908..daefce4bf6 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -95,33 +95,36 @@ Transformation setup :param PJ* P: :returns: :c:type:`PJ*` +.. _coord_trans_functions: + Coordinate transformation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: PJ_COORD proj_trans_coord(PJ *P, enum proj_direction direction, PJ_COORD coord) + +.. c:function:: PJ_COORD proj_trans_coord(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) Transform a single :c:type:`PJ_COORD` coordinate. :param PJ* P: :param `direction`: Transformation direction. - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param PJ_COORD coord: Coordinate that will be transformed. :returns: :c:type:`PJ_COORD` -.. c:function:: PJ_OBS proj_trans_obs(PJ *P, enum proj_direction direction, PJ_OBS obs) +.. c:function:: PJ_OBS proj_trans_obs(PJ *P, PJ_DIRECTION direction, PJ_OBS obs) Transform a single :c:type:`PJ_OBS` observation. :param PJ* P: :param `direction`: Transformation direction. - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param PJ_OBS obs: Observation data to transform. :returns: :c:type:`PJ_OBS` -.. c:function:: size_t proj_transform(PJ *P, enum proj_direction direction, \ +.. c:function:: size_t proj_transform(PJ *P, PJ_DIRECTION direction, \ double *x, size_t sx, size_t nx, double *y, \ size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ double *t, size_t st, size_t nt) @@ -182,7 +185,7 @@ Coordinate transformation :param PJ* P: Transformation object :param `direction`: Transformation direction - :type `enum proj_direction`: + :type `PJ_DIRECTION`: :param double* x: Array of x-coordinates :param double* y: Array of y-coordinates :param double* z: Array of z-coordinates @@ -199,23 +202,23 @@ Coordinate transformation -.. c:function:: size_t proj_transform_coord(PJ *P, enum proj_direction direction, size_t n, PJ_COORD *coord) +.. c:function:: size_t proj_transform_coord(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) Batch transform an array of :c:type:`PJ_COORD`. :param PJ* P: :param `direction`: Transformation direction - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param size_t n: Number of cordinates in :c:data:`coord` :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number -.. c:function:: size_t proj_transform_obs(PJ *P, enum proj_direction direction, size_t n, PJ_OBS *obs) +.. c:function:: size_t proj_transform_obs(PJ *P, PJ_DIRECTION direction, size_t n, PJ_OBS *obs) Batch transform an array of :c:type:`PJ_OBS`. :param PJ* P: :param `direction`: Transformation direction - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param size_t n: Number of observations in :c:data:`obs` :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number @@ -426,7 +429,7 @@ Distances Various ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_roundtrip(PJ *P, enum proj_direction direction, int n, PJ_OBS obs) +.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_OBS obs) Measure internal consistency of a given transformation. The function performs :c:data:`n` round trip transformations starting in either @@ -436,7 +439,7 @@ Various :param PJ* P: :param `direction`: Starting direction of transformation - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param int n: Number of roundtrip transformations :param PJ_OBS obs: Input coordinate :returns: :c:type:`double` Distance between original coordinate and the \ From f73ec9d887d9cddf014d33a53bf6f87390004a63 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 9 Oct 2017 22:48:44 +0200 Subject: [PATCH 12/43] Add documentation for datatypes and functions related to internal lists in PROJ.4. [skip ci] --- .../development/reference/datatypes.rst | 104 ++++++++++++++++++ .../development/reference/functions.rst | 43 ++++++++ 2 files changed, 147 insertions(+) diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 7e314dced3..85cedea683 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -749,6 +749,110 @@ Projection derivatives Meridian convergence calculated analytically. +List structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_OPERATIONS + + Description a PROJ.4 operation + + .. code-block:: C + + struct PJ_OPERATIONS { + char *id; /* operation keyword */ + PJ *(*proj)(PJ *); /* operation entry point */ + char * const *descr; /* description text */ + }; + + .. c:member:: char *id + + Operation keyword. + + .. c:member:: PJ *(*op)(PJ *) + + Operation entry point. + + .. c:member:: char * const * + + Description of operation. + + +.. c:type:: PJ_ELLPS + + Description of ellipsoids defined in PROJ.4 + + .. code-block:: C + + struct PJ_ELLPS { + char *id; + char *major; + char *ell; + char *name; + }; + + .. c:member:: char *id + + Keyword name of the ellipsoid. + + .. c:member:: char *major + + Semi-major axis of the ellipsoid, or radius in case of a sphere. + + .. c:member:: char *ell + + Elliptical parameter, e.g. `rf=298.257` or `b=6356772.2`. + + .. c:member:: char *name + + Name of the ellipsoid + +.. c:type:: PJ_UNITS + + Distance units defined in PROJ.4. + + .. code-block:: C + + struct PJ_UNITS { + char *id; /* units keyword */ + char *to_meter; /* multiply by value to get meters */ + char *name; /* comments */ + double factor; /* to_meter factor in actual numbers */ + }; + + .. c:member:: char *id + + Keyword for the unit. + + .. c:member:: char *to_meter + + Text representation of the factor that converts a given unit to meters + + .. c:member:: char *name + + Name of the unit. + + .. c:member:: double factor + + Conversion factor that converts the unit to meters. + +.. c:type:: PJ_PRIME_MERIDIANS + + Prime meridians defined in PROJ.4. + + .. code-block:: C + + struct PJ_PRIME_MERIDIANS { + char *id; + char *defn; + }; + + .. c:member:: char *id + + Keyword for the prime meridian + + .. c:member:: char *def + + Offset from Greenwich in DMS format. Info structures ------------------------------------------------------------------------------- diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index daefce4bf6..10af19d409 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -396,6 +396,49 @@ Info functions :type `initname`: const char* :returns: :c:type:`PJ_INIT_INFO` +Lists +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: const PJ_OPERATIONS* proj_list_operations(void) + + Get a pointer to an array of all operations in PROJ.4. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + Print a list of all operations in PROJ.4: + + .. code-block:: C + + PJ_OPERATIONS *ops; + for (ops = proj_list_operations(); ops->id; ++ops) + printf("%s\n", ops->id); + + + :returns: :c:type:`PJ_OPERATIONS*` + +.. c:function:: const PJ_ELLPS* proj_list_ellps(void) + + Get a pointer to an array of ellipsoids defined in PROJ.4. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + :returns: :c:type:`PJ_ELLPS*` + +.. c:function:: const PJ_UNITS* proj_list_units(void) + + Get a pointer to an array of distance units defined in PROJ.4. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + :returns: :c:type:`PJ_UNITS*` + +.. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void) + + Get a pointer to an array of prime meridians defined in PROJ.4. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + :returns: :c:type:`PJ_PRIME_MERIDIANS*` Distances ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ From 0c83891614bc158c56f8132f09b0db95d5dd72f1 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 7 Nov 2017 16:43:01 +0100 Subject: [PATCH 13/43] Wrote docs for unitconvert operation [skip-ci] --- .../transformations/unitconvert.rst | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/docs/source/usage/operations/transformations/unitconvert.rst b/docs/source/usage/operations/transformations/unitconvert.rst index 458d0c1536..ad8482071b 100644 --- a/docs/source/usage/operations/transformations/unitconvert.rst +++ b/docs/source/usage/operations/transformations/unitconvert.rst @@ -5,3 +5,108 @@ Unit conversion ================================================================================ Convert between various distance and time units. + ++--------------+--------------------------------------------------------------------+ +| **Options** | ++--------------+--------------------------------------------------------------------+ +| `+xy_in` | Input unit of the horizontal components. | ++--------------+--------------------------------------------------------------------+ +| `+xy_out` | Output unit of the horizontal components. | ++--------------+--------------------------------------------------------------------+ +| `+z_in` | Input unit of the vertical component. | ++--------------+--------------------------------------------------------------------+ +| `+z_out` | Output unit of the vertical component. | ++--------------+--------------------------------------------------------------------+ +| `+t_in` | Input unit of the time component. | ++--------------+--------------------------------------------------------------------+ +| `+t_out` | Output unit of the time component. | ++--------------+--------------------------------------------------------------------+ + +There are many examples of coordinate reference systems that are expressed in +other units than the meter. There are also many cases where temporal data +has to be translated to different units. The `unitconvert` operation takes care +of that. + +Many North American systems are defined with coordinates in feet. For example +in Vermont:: + + +proj=pipeline + +step +proj=tmerc +lat_0=42.5 +lon_0=-72.5 +k=0.999964286 +x_0=500000.00001016 +y_0=0 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Often when working with GNNS data the timestamps are presented in GPS-weeks, +but when the data transformed with the `helmert` operation timestamps are +expected to be in units of decimalyears. This can be fixed with `unitconvert`:: + + +proj=pipeline + +step +proj=unitconvert +t_in=gpsweek +t_out=decimalyear + +step +proj=helmert +epoch=2000.0 +t_obs=2017.5 ... + + +Distance units +############################################################################### + +In the table below all distance units supported by PROJ.4 is listed. +The same list can also be produced on the command line with `proj` or `cs2cs`, +by adding the `-lu` flag when calling the utility. + ++----------+---------------------------------+ +| Label | Name | ++----------+---------------------------------+ +| km | Kilometer | ++----------+---------------------------------+ +| m | Meter | ++----------+---------------------------------+ +| dm | Decimeter | ++----------+---------------------------------+ +| cm | Centimeter | ++----------+---------------------------------+ +| mm | Millimeter | ++----------+---------------------------------+ +| kmi | International Nautical Mile | ++----------+---------------------------------+ +| in | International Inch | ++----------+---------------------------------+ +| ft | International Foot | ++----------+---------------------------------+ +| yd | International Yard | ++----------+---------------------------------+ +| mi | International Statute Mile | ++----------+---------------------------------+ +| fath | International Fathom | ++----------+---------------------------------+ +| ch | International Chain | ++----------+---------------------------------+ +| link | International Link | ++----------+---------------------------------+ +| us-in | U.S. Surveyor's Inch | ++----------+---------------------------------+ +| us-ft | U.S. Surveyor's Foot | ++----------+---------------------------------+ +| us-yd | U.S. Surveyor's Yard | ++----------+---------------------------------+ +| us-ch | U.S. Surveyor's Chain | ++----------+---------------------------------+ +| us-mi | U.S. Surveyor's Statute Mile | ++----------+---------------------------------+ +| ind-yd | Indian Yard | ++----------+---------------------------------+ +| ind-ft | Indian Foot | ++----------+---------------------------------+ +| ind-ch | Indian Chain | ++----------+---------------------------------+ + + +Time units +############################################################################### + +In the table below all time units supported by PROJ.4 is listed. + ++--------------+-----------------------------+ +| mjd | Modfied Julian date | ++--------------+-----------------------------+ +| decimalyear | Decimal year | ++--------------+-----------------------------+ +| gps_week | GPS Week | ++--------------+-----------------------------+ + From 91b641e627a028786e56276d18501dd518d6b112 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sat, 11 Nov 2017 19:08:45 +0100 Subject: [PATCH 14/43] add axisswap documentation --- .../operations/transformations/axisswap.rst | 39 +++++++++++++++++++ .../operations/transformations/index.rst | 1 + 2 files changed, 40 insertions(+) create mode 100644 docs/source/usage/operations/transformations/axisswap.rst diff --git a/docs/source/usage/operations/transformations/axisswap.rst b/docs/source/usage/operations/transformations/axisswap.rst new file mode 100644 index 0000000000..ddaad0751a --- /dev/null +++ b/docs/source/usage/operations/transformations/axisswap.rst @@ -0,0 +1,39 @@ +.. _axisswap: + +================================================================================ +Axis swap +================================================================================ + +Change the order and sign of 2,3 or 4 axes. + ++--------------+---------------------------------------------------------------+ +| **Options** | ++--------------+---------------------------------------------------------------+ +| `+order` | Ordered comma-separated list of axis, e.g. `+order=2,1,3,4` | ++--------------+---------------------------------------------------------------+ + + +Each of the possible four axes are numbered with 1-4, such that the first input axis +is 1, the second is 2 and so on. The output ordering is controlled by a list of the +input axes re-ordered to the new mapping. + +Examples +################################################################################ + +Reversing the order of the axes:: + + +proj=axisswap +order=4,3,2,1 + +Swapping the first two axes (x and y):: + + +proj=axisswap +order=2,1,3,4 + +The direction, or sign, of an axis can be changed by adding a minus in +front of the axis-number:: + + +proj=axisswap +order=1,-2,3,4 + +It is only necessary to specify the axes that are affected by the swap +operation:: + + +proj=axisswap +order=2,1 diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst index 8bf2a89031..2966ed0de8 100644 --- a/docs/source/usage/operations/transformations/index.rst +++ b/docs/source/usage/operations/transformations/index.rst @@ -7,6 +7,7 @@ Transformations .. toctree:: :maxdepth: 1 + axisswap cart helmert molodensky From 1f096c9f9cf1ef4c152c53605bf6f6347209b4b5 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 15 Nov 2017 21:31:51 +0100 Subject: [PATCH 15/43] Added a transition guide to aid migration from old to new API --- docs/source/development/index.rst | 1 + docs/source/development/migration.rst | 137 ++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 docs/source/development/migration.rst diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 9f5c8d89b0..318e3778b3 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -17,4 +17,5 @@ PROJ.4 project or using the library in their own software. threads reference/index bindings + migration diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst new file mode 100644 index 0000000000..d9014a366d --- /dev/null +++ b/docs/source/development/migration.rst @@ -0,0 +1,137 @@ +.. _API_migration: + +================================================================================ +Version 4 to 5 API Migration +================================================================================ + +This is a transition guide for developers wanting to migrate their code to use +PROJ version 5. + +The difference between the old and new API is best shown with examples. Below +we implement the same program with the two different API's. The program reads +input latitude and longitude from the command line and convert them to +projected coordinates with the Mercator projection. + +We start by writing the progran for PROJ v. 4: + +.. code-block:: C + + #include + + main(int argc, char **argv) { + projPJ pj_merc, pj_latlong; + double x, y; + + if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) + return 1; + if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) + return 1; + + while (scanf("%lf %lf", &x, &y) == 2) { + x *= DEG_TO_RAD; + y *= DEG_TO_RAD; + p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL ); + printf("%.2f\t%.2f\n", x, y); + } + + return 0; + } + +The same program implemented using PROJ v. 5: + +.. code-block:: C + + #include + + main(int argc, char **argv) { + PJ *P; + PJ_COORD c; + + P = proj_create(PJ_DEFAULT_CTX, "+proj=merc +ellps=clrk66 +lat_ts=33"); + if (P==0) + return 1; + + while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) { + c.lp.lam = proj_todeg(c.lp.lam); + c.lp.phi = proj_todeg(c.lp.phi); + c = proj_trans(P, PJ_FWD, c); + printf("%.2f\t%.2f\n", c.xy.x, c.xy.y); + } + + } + +Looking at the two different programs, there's a few immediate +differences that catches the eye. First off, the included header file describing +the API has changed from ``proj_api.h`` to simply ``proj.h``. All functions in ``proj.h`` +belongs to the ``proj_`` namespace. + +With the new API also comes new datatypes. E.g. the transformation object ``projPJ`` +which has been changed to a pointer of type ``PJ``. This is done to highlight the +actual nature of the object, instead of hiding it away behind a typedef. New data +types for handling coordinates have also been introduced. In the above example we +use the ``PJ_COORD``, which is a union of various types. The benefit of this is that +it is possible to use the various structs in the union to communicate what state +the data is in at different points in the program. For instance as in the above +example where the coordinate is read from STDIN as a geodetic coordinate, +communicated to the reader of the code by using the ``c.lp`` struct. +After it has been projected we print it to STDOUT by accessing the individual +elements in ``c.xy`` to illustrate that the coordinate is now in projected space. +Data types are prefixed with `PJ_`. + +The final, and perhaps biggest, change is that the fundamental concept of +transformations in PROJ are now handled in a single transformation object (``PJ``) +and not by stating the source and destination systems as previously. It is of +course still possible to do just that, but the transformation object now +captures the whole transformation from source to destination in one. In the +example with the old API the source system is described as +``+proj=latlon +ellps=clrk66`` and the destination system is described as +``+proj=merc +ellps=clrk66 +lat_ts=33``. Since the Mercator projection accepts +geodetic coordinates as its input, the description of the source in this case +is superflous. We use that to our advantage in the new API and simply state +the destination. This is simple at a glance, but is actually a big conceptual +change. We are now focused on the path between two systems instead of what the +source and destination systems are. + + +Function mapping from old to new API +############################################################################### + ++---------------------------------------+---------------------------------------+ +| **Old API functions** | **New API functions** | ++---------------------------------------+---------------------------------------+ +| pj_fwd | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_inv | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_fwd3 | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_inv3 | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_transform | proj_trans_array or proj_trans_generic| ++---------------------------------------+---------------------------------------+ +| pj_init | proj_create | ++---------------------------------------+---------------------------------------+ +| pj_init_plus | proj_create | ++---------------------------------------+---------------------------------------+ +| pj_free | proj_destroy | ++---------------------------------------+---------------------------------------+ +| pj_is_latlong | proj_angular_output | ++---------------------------------------+---------------------------------------+ +| pj_is_geocent | proj_angular_outout | ++---------------------------------------+---------------------------------------+ +| pj_get_def | proj_pj_info | ++---------------------------------------+---------------------------------------+ +| pj_latlong_from_proj | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_set_finder | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_set_searchpath | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_deallocate_grids | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_strerrno | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_get_errno_ref | proj_errno | ++---------------------------------------+---------------------------------------+ +| pj_get_release | proj_info | ++---------------------------------------+---------------------------------------+ From 082f5aed6ea6a746e73c17e39f8aabb85d840272 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 15 Nov 2017 21:52:25 +0100 Subject: [PATCH 16/43] Fix a few bad links [skip ci] --- docs/source/usage/projections.rst | 9 +++++---- docs/source/usage/quickstart.rst | 2 +- docs/source/usage/resource_files.rst | 4 ++-- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst index b0bcce6181..8f0b358698 100644 --- a/docs/source/usage/projections.rst +++ b/docs/source/usage/projections.rst @@ -5,14 +5,14 @@ Cartographic projection ================================================================================ The foundation of PROJ.4 is the large number of -:doc:`projections<../projections/index>` available in the library. This section +:doc:`projections` 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>`. +documenting the individual :doc:`projections`. ========== ================================================================ Parameter Description @@ -79,8 +79,9 @@ 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. +:doc:`equidistant cylindrical` +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 diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst index d162ace9b2..96bfbba1fe 100644 --- a/docs/source/usage/quickstart.rst +++ b/docs/source/usage/quickstart.rst @@ -20,7 +20,7 @@ A proj-strings holds the parameters of a given coordinate transformation, e.g. 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 +projected space with the :doc:`Mercator projection` 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. diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst index e99763f128..9a2028792b 100644 --- a/docs/source/usage/resource_files.rst +++ b/docs/source/usage/resource_files.rst @@ -115,7 +115,7 @@ used, then all parameters in that section applies for all proj-strings. Otherwis the identifier is connected to a specific projection. With the defaults file supplied with PROJ.4 the default ellipsoid is set to WGS84 (for all proj-strings). Apart from that only the Albers Equal Area, -:doc:`Lambert Conic Conformal<../projections/lcc>` and the -:doc:`Lagrange<../projections/lagrng>` projections have default parameters. +:doc:`Lambert Conic Conformal` and the +:doc:`Lagrange` projections have default parameters. Defaults can be ignored by adding the ``+no_def`` parameter to a proj-string. From 25b011042fdff451ca2826afe82251c06d883fb8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 16:33:42 +0100 Subject: [PATCH 17/43] Update API reference to reflect recent changes to the API --- .../development/reference/datatypes.rst | 389 ++---------------- .../development/reference/functions.rst | 109 ++--- 2 files changed, 104 insertions(+), 394 deletions(-) diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 85cedea683..1253b1a203 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -58,6 +58,14 @@ Transformation objects and destroyed with :c:func:`proj_context_destroy`. +.. c:type:: PJ_AREA + + Opaque object describing an area in which a transformation is performed. + + .. note:: This object is not fully implemented yet. It is used with + :c:func:`proj_create_crs_to_crs` to select the best transformation + between the two input coordinate reference systems. + 2 dimensional coordinates -------------------------------------------------------------------------------- @@ -117,22 +125,6 @@ Various 2-dimensional coordinate data types. Latitude or northing, depending on use. -.. c:type:: PJ_EN - - Generic easting/northing coordinate. - - .. code-block:: C - - typedef struct { double e, n; } PJ_EN; - - .. c:member:: double PJ_EN.e - - Easting - - .. c:member:: double PJ_EN.n - - Northing - 3 dimensional coordinates -------------------------------------------------------------------------------- @@ -203,27 +195,6 @@ types above. Vertical component. -.. c:type:: PJ_ENH - - Easting, northing and height. - - .. code-block:: C - - typedef struct {double e, n, h; } PJ_ENH; - - .. c:member:: double PJ_ENH.e - - Easting - - .. c:member:: double PJ_ENH.n - - Northing - - .. c:member:: double PJ_ENH.h - - Height - - Spatiotemporal coordinate types -------------------------------------------------------------------------------- @@ -318,29 +289,6 @@ domain. Temporal component. - -.. c:type:: PJ_ENHT - - Spatiotemporal version of :c:type:`PJ_ENH`. - - .. code-block:: C - - typedef struct {double e, n, h, t; } PJ_ENHT; - - .. c:member:: double PJ_ENHT.e - - Easting - - .. c:member:: double PJ_ENHT.n - - Northing - - .. c:member:: double PJ_ENHT.h - - Height - - .. c:member:: double PJ_ENHT.t - Ancillary types for geodetic computations -------------------------------------------------------------------------------- @@ -366,173 +314,9 @@ Ancillary types for geodetic computations Third rotation angle, kappa. -.. c:type:: PJ_DMS - - Describe a longitude or latitude by degrees, minutes and seconds. - - .. code-block:: C - - typedef struct { double d, m, s; } PJ_DMS; - - .. c:member:: double PJ_DMS.d - - Degrees. - - .. c:member:: double PJ_DMS.m - - Minutes - - .. c:member:: double PJ_DMS.s - - Seconds. - - -.. c:type:: PJ_EZN - - Geoid undulation and deflections of the vertical. - - .. code-block:: C - - typedef struct { double e, z, N; } PJ_EZN; - - .. c:member:: double PJ_EZN.e - - Deflection of the vertical, eta. - - .. c:member:: double PJ_EZN.z - - Deflection of the vertical, zeta - - .. c:member:: double PJ_EZN.N - - Geoid undulation. - - -.. c:type:: PJ_AF - - Ellipsoidal parameters. - - .. code-block:: C - - typedef struct {double a, f; } PJ_AF; - - .. c:member:: double PJ_AF.a - - Major axis of ellipsoid. - - .. c:member:: double PJ_AF.f - - Flattening of ellipsoid. - - Complex coordinate types -------------------------------------------------------------------------------- -.. c:type:: PJ_PAIR - - .. code-block:: C - - typedef union { - XY xy; - LP lp; - UV uv; - PJ_AF af; - PJ_EN en; - double v[2]; - } PJ_PAIR; - - .. c:member:: XY PJ_PAIR.xy - - Coordinate in projected space. - - .. c:member:: LP PJ_PAIR.lp - - Coordinate in lat/long space. - - .. c:member:: UV PJ_PAIR.uv - - Coordinate either in lat/lon or projected space. - - .. c:member:: PJ_AF PJ_PAIR.af; - - Ellipsoidal parameters. - - .. c:member:: PJ_EN PJ_PAIR.en - - Easting/Northing pair. - - .. c:member:: double PJ_PAIR.v[2] - - Generic 2D-vector. - -.. c:type:: PJ_TRIPLET - - Union type that groups all coordinate data types of two and tree dimensions. - - .. code-block:: C - - typedef union { - PJ_OPK opk; - PJ_ENH enh; - PJ_EZN ezn; - PJ_DMS dms; - double v[3]; - XYZ xyz; - LPZ lpz; - UVW uvw; - XY xy; - LP lp; - UV uv; - PJ_AF af; - } PJ_TRIPLET; - - .. c:member:: PJ_OPK PJ_TRIPLET.opk - - Rotations. - - .. c:member:: PJ_ENH PJ_TRIPLET.enh - - Easting, northing and height. - - .. c:member:: PJ_EZN PJ_TRIPLET.ezn - - Geoid undulation and deflections of the vertical. - - .. c:member:: PJ_DMS PJ_TRIPLET.dsm - - Degrees, minutes and seconds. - - .. c:member:: double PJ_TRIPLET.v[3] - - Generic 3-dimensional vector. - - .. c:member:: XYZ PJ_TRIPLET.xyz - - Coordinates in projected space. - - .. c:member:: LPZ PJ_TRIPLET.lpz - - Geodetic coordinates, including height. - - .. c:member:: UVW PJ_TRIPLET.uvw - - Either geodetic or projected coordinates. - - .. c:member:: XY PJ_TRIPLET.xy - - Horizontal coordinates in projected space. - - .. c:member:: LP PJ_TRIPLET.lp - - Geodetic coordinates. - - .. c:member:: UV PJ_TRIPLET.uv - - Geodetic or projected coordinate. - - .. c:member:: PJ_AF PJ_TRIPLET.af - - Ellipsoidal paramaters. .. c:type:: PJ_COORD @@ -541,13 +325,10 @@ Complex coordinate types .. code-block:: C typedef union { + double v[4]; PJ_XYZT xyzt; PJ_UVWT uvwt; - PJ_ENHT enht; PJ_LPZT lpzt; - PJ_ENH enh; - PJ_EN en; - double v[4]; XYZ xyz; UVW uvw; LPZ lpz; @@ -556,6 +337,10 @@ Complex coordinate types LP lp; } PJ_COORD ; + .. c:member:: double v[4] + + Generic four-dimensional vector. + .. c:member:: PJ_XYZT PJ_COORD.xyzt Spatiotemporal cartesian coordinate. @@ -564,26 +349,10 @@ Complex coordinate types Spatiotemporal generic coordinate. - .. c:member:: PJ_ENHT PJ_COORD.enht - - Easting, northing, height and time. - .. c:member:: PJ_LPZT PJ_COORD.lpzt Longitude, latitude, vertical and time components. - .. c:member:: PJ_ENH PJ_COORD.enh - - Easting, northing and height - - .. c:member:: PJ_EN PJCOORD.en - - Easting and northing. - - .. c:member:: double v[4] - - Generic four-dimensional vector. - .. c:member:: XYZ PJ_COORD.xyz 3-dimensional cartesian coordinate. @@ -609,68 +378,9 @@ Complex coordinate types Longitude and latitude. -.. c:type:: PJ_OBS - - Geodetic observation data type. - - .. code-block:: C - - typedef struct { - PJ_COORD coo; - PJ_TRIPLET anc; - int id; - unsigned int flags; - } PJ_OBS; - - .. c:member:: PJ_COORD PJ_OBS.coo - - Coordinate data - - .. c:member:: PJ_TRIPLET PJ_OBS.anc - - Ancillary data - - .. c:member:: int PJ_OBS.id - - Integer ancillary data, e.g. observation number, EPSG code, etc. - - .. c:member:: unsigned int PJ_OBS.flags - - Additional data intended for flags. - - Projection derivatives ------------------------------------------------------------------------------- -.. c:type:: PJ_DERIVS - - Partial derivatives of geodetic coordinate :math:`\left(\lambda,\phi\right)`. - Calculated with :c:func:`proj_derivatives`. - - .. code-block:: C - - typedef struct { - double x_l, x_p; - double y_l, y_p; - } PJ_DERIVS; - - .. c:member:: double PJ_DERIVS.x_l - - :math:`\frac{\partial x}{\partial \lambda}` - - .. c:member:: double PJ_DERIVS.x_p - - :math:`\frac{\partial x}{\partial \phi}` - - .. c:member:: double PJ_DERIVS.y_l - - :math:`\frac{\partial y}{\partial \lambda}` - - .. c:member:: double PJ_DERIVS.y_p - - :math:`\frac{\partial y}{\partial \phi}` - - .. c:type:: PJ_FACTORS Various cartographic properties, such as scale factors, angular distortion @@ -681,73 +391,51 @@ Projection derivatives .. code-block:: C typedef struct { - struct PJ_DERIVS der; - double h, k; - double omega, thetap; - double conv; - double s; - double a, b; - int code; - } PJ_FACTORS; + double meridional_scale; + double parallel_scale; + double areal_scale; - .. c:member:: PJ_DERIVS PJ_FACTORS.der + double angular_distortion; + double meridian_parallel_angle; + double meridian_convergence; - Partial derivatives of coordinate :math:`\left(\lambda,\phi\right)`. + double tissot_semimajor; + double tissot_semiminor; + } PJ_FACTORS; - .. c:member:: double PJ_FACTORS.h + .. c:member:: double PJ_FACTORS.meridional_scale - Meridian scale at coordinate :math:`\left(\lambda,\phi\right)`. + Meridional scale at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.k + .. c:member:: double PJ_FACTORS.parallel_scale Parallel scale at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.omega + .. c:member:: double PJ_FACTORS.areal_scale + + Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.angular_distortion Angular distortion at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.thetap + .. c:member:: double PJ_FACTORS.meridian_parallel_angle Meridian/parallel angle, :math:`\theta^\prime`, at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.conv + .. c:member:: double PJ_FACTORS.meridian_convergence Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. Sometimes also described as *grid declination*. - .. c:member:: double PJ_FACTORS.s - - Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. - - .. c:member:: double PJ_FACTORS.a + .. c:member:: double PJ_FACTORS.tissot_semimajor Maximum scale error. - .. c:member:: double PJ_FACTORS.b + .. c:member:: double PJ_FACTORS.tissot_semiminor Minimum scale error. - .. c:member:: int code - - Bitmask determing if calculation of various factors was done numerically - or analytically. If a bit flags is set the calculation was done analytically. - The following bit flags exists: - - .. c:macro:: PJ_IS_ANAL_XL_YL - - Longitude derivatives are calculated analytically - - .. c:macro:: PJ_IS_ANAL_XP_YP - - Latitude derivatives are calculated analyticall. - - .. c:macro:: PJ_IS_ANAL_HK - - Meridinal and parallel scale factors are calculated analytically. - - .. c:macro:: PJ_IS_ANAL_CONV - - Meridian convergence calculated analytically. List structures ------------------------------------------------------------------------------- @@ -913,6 +601,7 @@ Info structures char description[128]; char definition[512]; int has_inverse; + double accuracy; } PJ_PROJ_INFO; .. c:member:: char PJ_PROJ_INFO.id[16] @@ -934,6 +623,10 @@ Info structures 1 if an inverse mapping of the defined operation exists, otherwise 0. + .. c:member:: double PJ_PROJ_INFO.accuracy + + Expected accuracy of the transformation. -1 if unknown. + .. c:type:: PJ_GRID_INFO Struct holding information about a specific grid in the search path of @@ -957,7 +650,7 @@ Info structures .. c:member:: char PJ_GRID_INFO - Full path of grid file, e.g. "*C:\OSGeo4W64\\share\proj\BETA2007.gsb*" + Full path of grid file, e.g. *"C:\\OSGeo4W64\\share\\proj\\BETA2007.gsb"* .. c:member:: char PJ_GRID_INFO.format[8] @@ -1009,7 +702,7 @@ Info structures .. c:member:: char PJ_INIT_INFO.filename[260] - Full path of init file, e.g. "*C:\OSGeo4W64\share\proj\epsg*" + Full path of init file, e.g. "*C:\\OSGeo4W64\\share\\proj\\epsg*" .. c:member:: char PJ_INIT_INFO.version[32] diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 10af19d409..ea1289541c 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -58,7 +58,7 @@ Transformation setup :param char** argv: Vector of strings with proj-string parameters, e.g. ``+proj=merc`` :returns: :c:type:`PJ*` -.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to) +.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to, PJ_AREA *area) Create a transformation object that is a pipeline between two known coordinate reference systems. @@ -71,13 +71,15 @@ Transformation setup given and coordinates are transformed via a hub datum (WGS84). This transformation strategy is referred to as "early-binding" by the EPSG. The function can be extended to support "late-binding" transformations in the - future without affecting users of the function. + future without affecting users of the function. When the function is extended + to the late-binding approach the :c:data:`area` argument will be used. For + now it is just a place-holder for a future improved implementation. Example call: .. code-block:: C - PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833"); + PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0); The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. @@ -86,6 +88,8 @@ Transformation setup :type `srid_from`: const char* :param `srid_to`: Destination SRID. :type `srid_to`: const char* + :param `area`: Descriptor of the desired area for the transformation. + :type `area`: PJ_AREA :returns: :c:type:`PJ*` .. c:function:: PJ* proj_destroy(PJ *P) @@ -101,7 +105,7 @@ Coordinate transformation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: PJ_COORD proj_trans_coord(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) +.. c:function:: PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) Transform a single :c:type:`PJ_COORD` coordinate. @@ -112,22 +116,10 @@ Coordinate transformation :returns: :c:type:`PJ_COORD` -.. c:function:: PJ_OBS proj_trans_obs(PJ *P, PJ_DIRECTION direction, PJ_OBS obs) - - Transform a single :c:type:`PJ_OBS` observation. - - :param PJ* P: - :param `direction`: Transformation direction. - :type `direction`: PJ_DIRECTION - :param PJ_OBS obs: Observation data to transform. - :returns: :c:type:`PJ_OBS` - - - -.. c:function:: size_t proj_transform(PJ *P, PJ_DIRECTION direction, \ - double *x, size_t sx, size_t nx, double *y, \ - size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ - double *t, size_t st, size_t nt) +.. c:function:: size_t proj_trans_generic(PJ *P, PJ_DIRECTION direction, \ + double *x, size_t sx, size_t nx, double *y, \ + size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ + double *t, size_t st, size_t nt) Transform a series of coordinates, where the individual coordinate dimension may be represented by an array that is either @@ -159,7 +151,7 @@ Coordinate transformation ... - proj_transform ( + proj_trans_generic ( P, PJ_INV, sizeof(XYQS), &(survey[0].x), stride, 345, /* We have 345 eastings */ &(survey[0].y), stride, 345, /* ...and 345 northings. */ @@ -202,7 +194,7 @@ Coordinate transformation -.. c:function:: size_t proj_transform_coord(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) +.. c:function:: size_t proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) Batch transform an array of :c:type:`PJ_COORD`. @@ -212,16 +204,6 @@ Coordinate transformation :param size_t n: Number of cordinates in :c:data:`coord` :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number -.. c:function:: size_t proj_transform_obs(PJ *P, PJ_DIRECTION direction, size_t n, PJ_OBS *obs) - - Batch transform an array of :c:type:`PJ_OBS`. - - :param PJ* P: - :param `direction`: Transformation direction - :type `direction`: PJ_DIRECTION - :param size_t n: Number of observations in :c:data:`obs` - :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number - Initializers ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -443,7 +425,7 @@ Lists Distances ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_lp_dist(PJ *P, LP a, LP b) +.. c:function:: double proj_lp_dist(const PJ *P, LP a, LP b) Calculate geodesic distance between two points in geodetic coordinates. @@ -452,6 +434,15 @@ Distances :param LP b: Coordinate of second point :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. +.. c:function:: double proj_lp_dist(const PJ *P, LPZ a, LPZ b) + + Calculate geodesic distance between two points in geodetic coordinates. + + :param PJ* P: Transformation object + :param LPZ a: Coordinate of first point + :param LPZ b: Coordinate of second point + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + .. c:function:: double proj_xy_dist(XY a, XY, b) Calculate 2-dimensional euclidean between two projected coordinates. @@ -472,15 +463,16 @@ Distances Various ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_OBS obs) +.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coo) Measure internal consistency of a given transformation. The function performs :c:data:`n` round trip transformations starting in either the forward or reverse :c:data:`direction`. Returns the euclidean - distance of the starting point :c:data:`obs` and the resulting + distance of the starting point :c:data:`coo` and the resulting coordinate after :c:data:`n` iterations back and forth. :param PJ* P: + :type `P`: const PJ* :param `direction`: Starting direction of transformation :type `direction`: PJ_DIRECTION :param int n: Number of roundtrip transformations @@ -488,17 +480,7 @@ Various :returns: :c:type:`double` Distance between original coordinate and the \ resulting coordinate after :c:data:`n` transformation iterations. -.. c:function:: PJ_DERIVS proj_derivatives(const PJ *P, const LP lp) - - Calculate partial derivatives of geodetic coordinates. - - :param `P`: Transformation object - :type `P`: const PJ* - :param `lp`: Geodetic coordinate - :type `lp`: const LP - :returns: :c:type:`PJ_DERIVS` - -.. c:function:: PJ_FACTORS proj_factors(const PJ *P, const LP lp) +.. c:function:: PJ_FACTORS proj_factors(PJ *P, LP lp) Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence. Depending on the underlying projection @@ -547,3 +529,38 @@ Various :param int pos: Character denoting positive direction, typically `'N'` or `'E'`. :param int neg: Character denoting negative direction, typically `'S'` or `'W'`. :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) + + +.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) + + Convert geographical to geocentric latitude. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :param `coo`: Coordinate + :type `coo`: PJ_COORD + :returns: :c:type:`PJ_COORD` Converted coordinate + + +.. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir) + + Check if a operation expects angular input. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: :c:type:`int` 1 if angular input is expected, otherwise 0 + +.. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir) + + Check if an operation returns angular output. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: :c:type:`int` 1 if angular output is returned, otherwise 0 + From 83fa46d89a1998323c095abaa911b8455c7b62d6 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 20:37:10 +0100 Subject: [PATCH 18/43] Added info table to ccon doc page --- .../usage/operations/projections/ccon.rst | 35 ++++++++++++------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/source/usage/operations/projections/ccon.rst b/docs/source/usage/operations/projections/ccon.rst index 6197f06193..8a858e385b 100644 --- a/docs/source/usage/operations/projections/ccon.rst +++ b/docs/source/usage/operations/projections/ccon.rst @@ -4,22 +4,37 @@ Central Conic ******************************************************************************** +This is central (centrographic) projection on cone tangent at ``lat_0`` latitude, +identical with ``conic()`` projection from ``mapproj`` R package. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conic | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the standard parallel | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Lukasz Komsta | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_1` | Latitude of standard parallel. | ++---------------------+----------------------------------------------------------+ + .. image:: ./images/ccon.png :scale: 50% - :alt: Central Conic + :alt: Central Conic -This is central (centrographic) projection on cone tangent at ``lat_0`` latitude, -identical with ``conic()`` projection from ``mapproj`` R package. Usage ######## This simple projection is rarely used, as it is not equidistant, equal-area, nor -conformal. +conformal. An example of usage (and the main reason to implement this projection in proj4) -is the ATPOL geobotanical grid of Poland, developed in Institute of Botany, -Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]_. The grid was +is the ATPOL geobotanical grid of Poland, developed in Institute of Botany, +Jagiellonian University, Krakow, Poland in 1970s [Zajac1978]_. The grid was originally handwritten on paper maps and further copied by hand. The projection (together with strange Earth radius) was chosen by its creators as the compromise fit to existing maps during first software development in DOS era. Many years later @@ -47,7 +62,7 @@ Forward projection .. math:: - y = \cot \phi_0 - r \cos (\lambda\sin\phi_0) + y = \cot \phi_0 - r \cos (\lambda\sin\phi_0) Inverse projection @@ -110,9 +125,3 @@ and it should give the following results: 3.707419E+04 6.768262E+05 0.000000E+00 6.960534E+05 6.722946E+05 0.000000E+00 3.300000E+05 3.500000E+05 0.000000E+00 - - - - - - From 410ad2d07515a734d04bf4c44c694fd5b548f1a2 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 22:31:55 +0100 Subject: [PATCH 19/43] Restructure coordinate operations docs --- .../axisswap.rst | 0 .../{transformations => conversions}/cart.rst | 0 .../usage/operations/conversions/index.rst | 18 ++++++++++++++++++ .../{projections => conversions}/latlon.rst | 0 .../{projections => conversions}/lonlat.rst | 0 .../unitconvert.rst | 0 docs/source/usage/operations/index.rst | 13 ++++++++----- .../usage/operations/projections/index.rst | 7 +++++-- .../usage/operations/transformations/index.rst | 6 +++--- 9 files changed, 34 insertions(+), 10 deletions(-) rename docs/source/usage/operations/{transformations => conversions}/axisswap.rst (100%) rename docs/source/usage/operations/{transformations => conversions}/cart.rst (100%) create mode 100644 docs/source/usage/operations/conversions/index.rst rename docs/source/usage/operations/{projections => conversions}/latlon.rst (100%) rename docs/source/usage/operations/{projections => conversions}/lonlat.rst (100%) rename docs/source/usage/operations/{transformations => conversions}/unitconvert.rst (100%) diff --git a/docs/source/usage/operations/transformations/axisswap.rst b/docs/source/usage/operations/conversions/axisswap.rst similarity index 100% rename from docs/source/usage/operations/transformations/axisswap.rst rename to docs/source/usage/operations/conversions/axisswap.rst diff --git a/docs/source/usage/operations/transformations/cart.rst b/docs/source/usage/operations/conversions/cart.rst similarity index 100% rename from docs/source/usage/operations/transformations/cart.rst rename to docs/source/usage/operations/conversions/cart.rst diff --git a/docs/source/usage/operations/conversions/index.rst b/docs/source/usage/operations/conversions/index.rst new file mode 100644 index 0000000000..54324ec435 --- /dev/null +++ b/docs/source/usage/operations/conversions/index.rst @@ -0,0 +1,18 @@ +.. _conversions_list: + +================================================================================ +Conversions +================================================================================ + +Conversions are coordinate operations in which both coordinate reference systems +are based on the same datum. In PROJ.4 projections are differentiated from +conversions. + +.. toctree:: + :maxdepth: 1 + + axisswap + cart + lonlat + latlon + unitconvert diff --git a/docs/source/usage/operations/projections/latlon.rst b/docs/source/usage/operations/conversions/latlon.rst similarity index 100% rename from docs/source/usage/operations/projections/latlon.rst rename to docs/source/usage/operations/conversions/latlon.rst diff --git a/docs/source/usage/operations/projections/lonlat.rst b/docs/source/usage/operations/conversions/lonlat.rst similarity index 100% rename from docs/source/usage/operations/projections/lonlat.rst rename to docs/source/usage/operations/conversions/lonlat.rst diff --git a/docs/source/usage/operations/transformations/unitconvert.rst b/docs/source/usage/operations/conversions/unitconvert.rst similarity index 100% rename from docs/source/usage/operations/transformations/unitconvert.rst rename to docs/source/usage/operations/conversions/unitconvert.rst diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst index 21200c939c..baae0e0ae0 100644 --- a/docs/source/usage/operations/index.rst +++ b/docs/source/usage/operations/index.rst @@ -4,15 +4,18 @@ Coordinate operations ================================================================================ -Coordinate operations in PROJ.4 are divided into two groups: -Projections and transformations. -Projections are purely cartographic mappings of the sphere onto the plane whereas -transformations are mostly geodetic operations concerned with changes in -reference frames. +Coordinate operations in PROJ.4 are divided into three groups: +Projections, conversions and transformations. +Projections are purely cartographic mappings of the sphere onto the plane. +Technically projections are conversions (according to ISO standards), though in +PROJ.4 projections are distinguished from conversions. Conversions are coordinate +operations that do not exert a change in reference frame. Operations that do +exert a change in reference frame are called transformations. .. toctree:: :maxdepth: 1 projections/index + conversions/index transformations/index diff --git a/docs/source/usage/operations/projections/index.rst b/docs/source/usage/operations/projections/index.rst index 5ccf00459f..f7eb0c67e1 100644 --- a/docs/source/usage/operations/projections/index.rst +++ b/docs/source/usage/operations/projections/index.rst @@ -4,6 +4,11 @@ Projections ================================================================================ +Projections are coordinate operations that are technically conversions but since +projections are so fundamental to PROJ.4 we differentiate them from conversions. + +Projections map the spherical 3D space to a flat 2D space. + .. toctree:: :maxdepth: 1 @@ -62,8 +67,6 @@ Projections lagrng larr lask - lonlat - latlon lcc lcca leac diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst index 2966ed0de8..112d9220fb 100644 --- a/docs/source/usage/operations/transformations/index.rst +++ b/docs/source/usage/operations/transformations/index.rst @@ -4,13 +4,13 @@ Transformations ================================================================================ +Transformations coordinate operation in which the two coordinate reference +systems are based on different datums. + .. toctree:: :maxdepth: 1 - axisswap - cart helmert molodensky hgridshift vgridshift - unitconvert From 28ead8822488f0cd382f8966a18000f17ef1e958 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 23:26:23 +0100 Subject: [PATCH 20/43] Added projections parameters to aeqd and airy doc pages --- .../usage/operations/projections/aeqd.rst | 14 +++++++++++++- .../usage/operations/projections/airy.rst | 18 +++++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/source/usage/operations/projections/aeqd.rst b/docs/source/usage/operations/projections/aeqd.rst index 949cd8a0c7..32165e49db 100644 --- a/docs/source/usage/operations/projections/aeqd.rst +++ b/docs/source/usage/operations/projections/aeqd.rst @@ -3,8 +3,20 @@ ******************************************************************************** Azimuthal Equidistant ******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+guam` | Use Guam elliptical formulas. Defaults to false. | ++---------------------+----------------------------------------------------------+ + .. image:: ./images/aeqd.png :scale: 50% - :alt: Azimuthal Equidistant + :alt: Azimuthal Equidistant diff --git a/docs/source/usage/operations/projections/airy.rst b/docs/source/usage/operations/projections/airy.rst index 307af3e340..d273059297 100644 --- a/docs/source/usage/operations/projections/airy.rst +++ b/docs/source/usage/operations/projections/airy.rst @@ -3,8 +3,24 @@ ******************************************************************************** Airy ******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_b` | | ++---------------------+----------------------------------------------------------+ +| `+no_cut` | Do not cut at hemisphere limit | ++---------------------+----------------------------------------------------------+ + .. image:: ./images/airy.png :scale: 50% - :alt: Airy + :alt: Airy From 7b0e97df22d32608355d1f235ee22ffedcc9f06e Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 29 Nov 2017 21:58:15 +0100 Subject: [PATCH 21/43] Fill out Molodensky docs [skip ci] --- docs/source/references.rst | 2 + .../operations/transformations/molodensky.rst | 69 ++++++++++++++++++- 2 files changed, 70 insertions(+), 1 deletion(-) diff --git a/docs/source/references.rst b/docs/source/references.rst index 7d1d221674..e2dece5cbf 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -10,6 +10,8 @@ References .. [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. +.. [Deakin2004] R.E. Deakin, 2004, `The Standard and Abridged Molodensky Coordinate Transformation Formulae `__. + .. [EberHewitt1979] Eber, L.E., and R.P. Hewitt. 1979. `Conversion algorithms for the CALCOFI station grid `__. 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 `_ diff --git a/docs/source/usage/operations/transformations/molodensky.rst b/docs/source/usage/operations/transformations/molodensky.rst index 3fa8f9a887..d4ff3e7923 100644 --- a/docs/source/usage/operations/transformations/molodensky.rst +++ b/docs/source/usage/operations/transformations/molodensky.rst @@ -4,4 +4,71 @@ Molodensky transform ================================================================================ -Perform a datum shift in geodetic coordinate space. +The Molodensky transformation resembles a :ref:`Helmert` with zero +rotations and a scale of unity, but converts directly from geodetic coordinates to +geodetic coordinates, without the intermediate shifts to and from cartesian +geocentric coordinates, associated with the Helmert transformation. +The Molodensky transformation is simple to implement and to parameterize, requiring +only the 3 shifts between the input and output frame, and the corresponding +differences between the semimajor axes and flattening parameters of the reference +ellipsoids. Due to its algorithmic simplicity, it was popular prior to the +ubiquity of digital computers. Today, it is mostly interesting for historical +reasons, but nevertheless indispensable due to the large amount of data that has +already been transformed that way [EversKnudsen2017]_. + ++---------------------+----------------------------------------------------------+ +| **Input type** | Geodetic coordinates. | ++---------------------+----------------------------------------------------------+ +| **Output type** | Geodetic coordinates. | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+da` | Difference in semimajor axis of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+df` | Difference in flattening of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dx` | Offset of the X-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dy` | Offset of the Y-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+dz` | Offset of the Z-axes of the defining ellipsoids. | ++---------------------+----------------------------------------------------------+ +| `+ellps` | Ellipsoid definition of source coordinates. | +| | Any specification can be used (e.g. `+a`, `+rf`, etc). | +|   | If not specified, default ellipsoid is used. | ++---------------------+----------------------------------------------------------+ +| `+abridged` | Use the abridged version of the Molodensky transform. | +| | Optional. | ++---------------------+----------------------------------------------------------+ + +The Molodensky transform can be used to perform a datum shift from coordinate +:math:`(\phi_1, \lambda_1, h_1)` to :math:`(\phi_2, \lambda_2, h_2)` where the two +coordinates are referenced to different ellipsoids. This is based on three +assumptions: + + 1. The cartesian axes, :math:`X, Y, Z`, of the two ellipsoids are parallel. + 2. The offset, :math:`\delta X, \delta Y, \delta Z`, between the two ellipsoid + are known. + 3. The characteristics of the two ellipsoids, expressed as the difference in + semimajor axis (:math:`\delta a`) and flattening (:math:`\delta f`), are known. + +The Molodensky transform is mostly used for transforming between old systems +dating back to the time before computers. The advantage of the Molodensky transform +is that it is fairly simple to compute by hand. The ease of computation come at the +cost of limited accuracy. + +A derivation of the mathematical formulas for the Molodensky transform can be found +in [Deakin2004]_. + + +Examples +############################################################################### + +The abridged Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 abridged + +The same transformation using the standard Molodensky:: + + proj=molodensky a=6378160 rf=298.25 da=-23 df=-8.120449e-8 dx=-134 dy=-48 dz=149 + From 597a208400377ca6285fbd204c44817e21f31907 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 29 Nov 2017 22:08:39 +0100 Subject: [PATCH 22/43] CSS override of the RTD theme so that lines are wrapped in tables. [skip ci] --- docs/source/_static/theme_overrides.css | 13 +++++++++++++ docs/source/conf.py | 8 +++++++- 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 docs/source/_static/theme_overrides.css diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css new file mode 100644 index 0000000000..63ee6cc74c --- /dev/null +++ b/docs/source/_static/theme_overrides.css @@ -0,0 +1,13 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} diff --git a/docs/source/conf.py b/docs/source/conf.py index 62316eeffa..12ee0a5759 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -140,7 +140,13 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] +html_static_path = ['_static'] + +html_context = { + 'css_files': [ + '_static/theme_overrides.css', # override wide tables in RTD theme + ], +} # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied From ee59e88d090a9a3b6ecd9651b4f439ab9b6651e4 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Dec 2017 13:41:46 +0100 Subject: [PATCH 23/43] Update config with version number and correct copyright dates [skip ci] --- docs/source/conf.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 12ee0a5759..af9d24dab7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,6 +14,7 @@ import sys import os +import datetime # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -48,7 +49,8 @@ # General information about the project. project = u'PROJ.4' -copyright = u'1986?-2016' +now = datetime.datetime.now() +copyright = u'1983-{0}'.format(now.year) author = u'Gerald Evenden, Frank Warmerdam, and others' # The version info for the project you're documenting, acts as replacement for @@ -56,9 +58,9 @@ # built documents. # # The short X.Y version. -version = u'4.9.3' +version = u'5.0.0' # The full version, including alpha/beta/rc tags. -release = u'4.9.3' +release = u'5.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 053ffa05ca8cf36cd02830d746ebde5506efa475 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Dec 2017 14:03:27 +0100 Subject: [PATCH 24/43] Add input/output types to gridshift docs [skip ci] --- .../operations/transformations/hgridshift.rst | 14 +++++++++----- .../operations/transformations/vgridshift.rst | 14 +++++++++----- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst index 78e46aa917..bd147c2f73 100644 --- a/docs/source/usage/operations/transformations/hgridshift.rst +++ b/docs/source/usage/operations/transformations/hgridshift.rst @@ -6,11 +6,15 @@ Horizontal grid shift Change of horizontal datum by grid shift. -+--------------+--------------------------------------------------------------------+ -| **Options** | -+--------------+--------------------------------------------------------------------+ -| `+grids` | Comma-separated list of grids to load. | -+--------------+--------------------------------------------------------------------+ ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ The horizontal grid shift is done by offsetting the planar input coordinates by a specific amount determined by the loaded grids. The simplest use case of the diff --git a/docs/source/usage/operations/transformations/vgridshift.rst b/docs/source/usage/operations/transformations/vgridshift.rst index f48d40c8fd..272b24abab 100644 --- a/docs/source/usage/operations/transformations/vgridshift.rst +++ b/docs/source/usage/operations/transformations/vgridshift.rst @@ -6,11 +6,15 @@ Vertical grid shift Change Vertical datum change by grid shift -+--------------+--------------------------------------------------------------------+ -| **Options** | -+--------------+--------------------------------------------------------------------+ -| `+grids` | Comma-separated list of grids to load. | -+--------------+--------------------------------------------------------------------+ ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Geodetic coordinates (horizontal), meters (vertical). | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Geodetic coordinates (horizontal), meters (vertical). | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `+grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ The vertical grid shift is done by offsetting the vertical input coordinates by a specific amount determined by the loaded grids. The simplest use case of the From 16bc13c878cfa5e2d5dbeef7de5b9546d0df02eb Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Dec 2017 14:06:32 +0100 Subject: [PATCH 25/43] Helmer update [wip] --- .../usage/operations/transformations/helmert.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst index 46073b633b..88a3facdb8 100644 --- a/docs/source/usage/operations/transformations/helmert.rst +++ b/docs/source/usage/operations/transformations/helmert.rst @@ -5,3 +5,14 @@ Helmert transform ================================================================================ Change reference frame by Helmert shift. + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `+x` | ++-----------------+--------------------------------------------------------------------+ + From f8d8315fd87a2ff9d210c229985bac8330962a53 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 7 Dec 2017 17:30:05 +0100 Subject: [PATCH 26/43] Document the helmert transform --- .../operations/transformations/helmert.rst | 377 +++++++++++++++++- 1 file changed, 366 insertions(+), 11 deletions(-) diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst index 88a3facdb8..001d2db172 100644 --- a/docs/source/usage/operations/transformations/helmert.rst +++ b/docs/source/usage/operations/transformations/helmert.rst @@ -4,15 +4,370 @@ Helmert transform ================================================================================ -Change reference frame by Helmert shift. - -+-----------------+--------------------------------------------------------------------+ -| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | -+-----------------+--------------------------------------------------------------------+ -| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | -+-----------------+--------------------------------------------------------------------+ -| **Options** | -+-----------------+--------------------------------------------------------------------+ -| `+x` | -+-----------------+--------------------------------------------------------------------+ +The Helmert transformation changes coordinates from one reference frame to +anoether by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and +14-parameter kinematic counterparts. ++-----------------+-------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates (spatial), decimalyears (temporal). | ++-----------------+-------------------------------------------------------------------+ +| **Options** | ++----------------+--------------------------------------------------------------------+ +| `x` | Translation of the x-axis [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `y` | Translation of the y-axis [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `z` | Translation of the z-axis. [m]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `s` | Scale factor [ppm]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `rx` | X-axis rotation in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `ry` | Y-axis rotatoin in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `rz` | Z-axis rotation in the 3D Helmert [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `theta` | Rotation angle in the 2D Helmert. [arc seconds]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dx` | Translation rate of the x-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dy` | Translation rate of the y-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dz` | Translation rate of the z-axis. [m/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `ds` | Scale rate factor [ppm/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `drx` | Rotation rate of the x-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `dry` | Rotation rate of the y-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `drz` | Rotation rate of the y-axis [arc seconds/year]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `t_epoch` | Central epoch of transformation. [decimalyear]. Only used in | +| | spatiotemporal transformations. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `t_obs` | Observation time of coordinate(s). Mostly useful in 2D and 3D | +| | transformations. [decimalyear]. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `exact` | Use exact transformation equations. *Optional*. | ++----------------+--------------------------------------------------------------------+ +| `transpose` | Transpose rotation matrix. *Optional*. | ++----------------+--------------------------------------------------------------------+ + +The Helmert transform, in all it's various incarnations, is used to perform reference +frame shifts. The transformation operates in cartesian space. It can be used to transform +planar coordinates from one datum to another (:ref:`2D Helmert`), transform 3D cartesian +coordinates from one static reference frame to another or it can be used to do fully +kinematic transformations from global reference frame to local static frames. + +All of the parameters described in the table above are marked as optional. This is true +as long as at least one parameter is defined in the setup of the transformation. +The behaviour of the transformation depends on which parameters are used in the setup. +For instance, if a rate of change paramater is specified a kinematic version of the +transformation is used. + +Examples ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Transforming coordinates from NAD72 to NAD83 using the 4 parameter 2D Helmert: + +:: + + proj=helmert ellps=GRS80 x=-9597.3572 y=.6112 + s=0.304794780637 theta=-1.244048 + +Simplified transformations from ITRF2008/IGS08 to ETRS89 using 7 parameters: + +:: + + proj=helmert ellps=GRS80 x=0.67678 y=0.65495 z=-0.52827 + rx=-0.022742 ry=0.012667 rz=0.022704 s=-0.01070 + +Transformation from `ITRF2000@2017.0` to `ITRF93@2017.0` using 15 parameters: + +:: + + proj=helmert ellps=GRS80 + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + rx=-0.00039 ry=0.00080 rz=-0.00114 + drx=-0.00011 dry=-0.00019 drz=0.00007 + epoch=1988.0 tobs=2017.0 transpose + +Mathematical description ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In the notation used below, :math:`\hat{P}` is the rate of change of a given transformation +parameter :math:`P`. :math:`\dot{P}` is the kinematically adjusted version of :math:`P`, +described by + +.. math:: + :label: propagation + + \dot{P}= P + \hat{P}\left(t - t_{central}\right) + +where :math:`t` is the observation time of the coordinate and :math:`t_{central}` is +the central epoch of the transformation. Equation :eq:`propagation` can be used to +propagate all transformation parameters in time. + +Superscripts of vectors denote the reference frame the coordinates in the vector belong to. + + +2D Helmert +------------------------------------------------------------------------------- + +The simplest version of the Helmert transform is the 2D case. In the 2-dimensional +case only the horizontal coordinates are changed. The coordinates can be +translated, rotated and scale. Translation is controlled with the `x` and `y` +parameters. The rotation is determined by `theta` and the scale is controlled with +the `s` paramaters. + +.. note:: + + The scaling parameter `s` is unitless for the 2D Helmert, as opposed to the + 3D version where the scaling parameter is given in units of ppm. + +Mathematically the 2D Helmert is described as: + +.. math:: + :label: 4param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + \end{bmatrix} + + s + \begin{bmatrix} + \hphantom{-}\cos \theta & \sin \theta \\ + -\sin \theta & \cos \theta \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + + +:eq:`4param` can be extended to a time-varying kinematic version by +adjusting the parameters with :eq:`propagation` to :eq:`4param`, which yields +the kinematic 2D Helmert transform: + +.. math:: + :label: 8param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \end{bmatrix} + + s(t) + \begin{bmatrix} + \hphantom{-}\cos \dot{\theta} & \sin \dot{\theta} \\ + -\sin\ \dot{\theta} & \cos \dot{\theta} \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + \end{bmatrix}^A + \end{align} + +All parameters in :eq:`8param` are determined by the use of :eq:`propagation`, +which applies the rate of change to each individual parameter for a given +timespan between :math:`t` and :math:`t_{central}`. + + +3D Helmert +------------------------------------------------------------------------------- + +The general form of the 3D Helmert is + +.. math:: + :label: general-helmert + + + \begin{align} + V^B = T + \left(1 + s \times 10^{-6}\right) \mathbf{R} V^A + \end{align} + +Where :math:`T` is a vector consisting of the three translation parameters, :math:`s` +is the scaling factor and :math:`\mathbf{R}` is a rotation matrix. :math:`V^A` and +:math:`V^B` are coordinate vectors, with :math:`V^A` being the input coordinate and +:math:`V^B` is the output coordinate. + +The rotation matrix is composed of three rotation matrices, one for each axis: + +.. math:: + + \begin{align} + \mathbf{R}_X &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos\phi & -\sin\phi\\ 0 & \sin\phi & \cos\phi \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Y &= \begin{bmatrix} \cos\theta & 0 & \sin\theta\\ 0 & 1 & 0\\ -\sin\theta & 0 & \cos\theta \end{bmatrix} + \end{align} + +.. math:: + + \begin{align} + \mathbf{R}_Z &= \begin{bmatrix} \cos\psi & -\sin\psi & 0\\ \sin\psi & \cos\psi & 0\\ 0 & 0 & 1 \end{bmatrix} + \end{align} + +The three rotation matrices can be combined in one: + +.. math:: + + \begin{align} + \mathbf{R} = \mathbf{R_X} \mathbf{R_Y} \mathbf{R_Y} + \end{align} + +For :math:`\mathbf{R}`, this yields: + +.. math:: + :label: rot_exact + + \begin{bmatrix} + \cos\theta \cos\psi & -\cos\phi \sin\psi + \sin\phi \sin\theta \cos\psi & \sin\phi \sin\psi + \cos\phi \sin\theta \cos\psi \\ + \cos\theta\sin\psi & \cos\phi \cos\psi + \sin\phi \sin\theta \sin\psi & - \sin\phi \cos\psi + \cos\phi \sin\theta \sin\psi \\ + -\sin\theta & \sin\phi \cos\theta & \cos\phi \cos\theta \\ + \end{bmatrix} + + +Using the small angle approxition the rotation matrix can be simplified to + +.. math:: + :label: rot_approx + + \begin{align} \mathbf{R} = + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \end{align} + +Which allow us to express the most common version of the Helmert transform, +using the approximated rotation matrix: + + +.. math:: + :label: 7param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \left(1 + s \times 10^{-6}\right) + \begin{bmatrix} + 1 & -R_z & R_y \\ + Rz & 1 & -R_x \\ + -Ry & R_x & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +Applying :eq:`propagation` we get the kinematic version of the approximated +3D Helmert: + +.. math:: + :label: 14param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \left(1 + \dot{s} \times 10^{-6}\right) + \begin{bmatrix} + 1 & -\dot{R_z} & \dot{R_y} \\ + \dot{R_z} & 1 & -\dot{R_x} \\ + -\dot{R_y} & \dot{R_x} & 1 \\ + \end{bmatrix} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + + + + +The Helmert transformation can be applied without using the rotation parameters, +in which case it becomes a simlpe translation of the origin of the coordinate +system. When using the Helmert in this version equation :eq:`general-helmert` +simplies to: + +.. math:: + :label: 3param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + T_x \\ + T_y \\ + T_z \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} + +That after application of :eq:`propagation` has the following kinematic +countpart: + +.. math:: + :label: 6param + + \begin{align} + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^B = + \begin{bmatrix} + \dot{T_x} \\ + \dot{T_y} \\ + \dot{T_z} \\ + \end{bmatrix} + + \begin{bmatrix} + X \\ + Y \\ + Z \\ + \end{bmatrix}^A + \end{align} From b59c43e146b9cf040e6e1f000b3ee520a9eecfd7 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 7 Dec 2017 17:31:25 +0100 Subject: [PATCH 27/43] Override RTD css and make sure that equation numbers are right-aligned --- docs/source/_static/theme_overrides.css | 44 +++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css index 63ee6cc74c..b82d2881be 100644 --- a/docs/source/_static/theme_overrides.css +++ b/docs/source/_static/theme_overrides.css @@ -11,3 +11,47 @@ overflow: visible !important; } } + +/* Align equation numbers to the right of the equation, not above */ +div.math { + position: relative; + padding-right: 2.5em; +} +.eqno { + height: 100%; + position: absolute; + right: 0; + padding-left: 5px; + padding-bottom: 5px; +} +.eqno:before { + /* Force vertical alignment of number */ + display: inline-block; + height: 100%; + vertical-align: middle; + content: ""; +} +.eqno .headerlink { + display: none; + visibility: hidden; + font-size: 14px; + padding-left: .3em; +} +.eqno:hover .headerlink { + display: inline-block; + visibility: hidden; + margin-right: -1.05em; +} +.eqno .headerlink:after { + visibility: visible; + content: "\f0c1"; + font-family: FontAwesome; + display: inline-block; + margin-left: -.9em; +} +/* Make responsive */ +.MathJax_Display { + max-width: 100%; + overflow-x: auto; + overflow-y: hidden; +} From 586db5409d203dfc941b88a6e7632dac407d8a7f Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Fri, 8 Dec 2017 11:05:59 +0100 Subject: [PATCH 28/43] A few updates to Helmert doc page --- .../operations/transformations/helmert.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst index 001d2db172..03e5db15ba 100644 --- a/docs/source/usage/operations/transformations/helmert.rst +++ b/docs/source/usage/operations/transformations/helmert.rst @@ -58,9 +58,9 @@ anoether by means of 3-, 4-and 7-parameter shifts, or one of their 6-, 8- and The Helmert transform, in all it's various incarnations, is used to perform reference frame shifts. The transformation operates in cartesian space. It can be used to transform -planar coordinates from one datum to another (:ref:`2D Helmert`), transform 3D cartesian +planar coordinates from one datum to another, transform 3D cartesian coordinates from one static reference frame to another or it can be used to do fully -kinematic transformations from global reference frame to local static frames. +kinematic transformations from global reference frames to local static frames. All of the parameters described in the table above are marked as optional. This is true as long as at least one parameter is defined in the setup of the transformation. @@ -68,6 +68,15 @@ The behaviour of the transformation depends on which parameters are used in the For instance, if a rate of change paramater is specified a kinematic version of the transformation is used. +The kinematic transformations require an observation time of the coordinate, as well +as a central epoch for the transformation. The latter is usually documented +alongside the rest of the transformation parameters for a given transformation. +The central eopch is controlled with the parameter `t_epoch`. The observation +time can either by stated as part of the coordinate when using PROJ's +4D-functionality or it can be controlled in the transformation setup by the +parameter `t_obs`. When `t_obs` is specified, all transformed coordinates are +treated as if they have the same observation time. + Examples +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -289,6 +298,12 @@ using the approximated rotation matrix: \end{bmatrix}^A \end{align} +If the rotation matrix is transposed the transformation is effectively reversed. +This is cause for some confusion since there is no correct way of defining the +rotation matrix. Two conventions exists and they seem to be equally popular. +In PROJ the rotation matrix can be transposed by adding the `transpose` flag in +the transformation setup. + Applying :eq:`propagation` we get the kinematic version of the approximated 3D Helmert: From 4134d0a47f2ac94807750c82d3a19064d03b8b73 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 21 Dec 2017 16:50:49 +0100 Subject: [PATCH 29/43] Deformation operation documented --- docs/source/references.rst | 5 +++++ docs/source/usage/operations/transformations/index.rst | 1 + 2 files changed, 6 insertions(+) diff --git a/docs/source/references.rst b/docs/source/references.rst index ad5f16bf50..320e401b10 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -60,6 +60,11 @@ References `Geodesics on an ellipsoid `_. +.. [Häkli2016] P. Häkli, M. Lidberg, L. Jivall, et al, 2016, + `The NKG2008 GPS Campaign - final transformation results and a new common Nordic reference frame + `_, + Journal of Geodetic Science, 6(1). + .. [Helmert1880] F. R. Helmert, 1880, `Mathematical and Physical Theories of Higher Geodesy, Vol 1 `_, diff --git a/docs/source/usage/operations/transformations/index.rst b/docs/source/usage/operations/transformations/index.rst index 112d9220fb..5112ffa25c 100644 --- a/docs/source/usage/operations/transformations/index.rst +++ b/docs/source/usage/operations/transformations/index.rst @@ -10,6 +10,7 @@ systems are based on different datums. .. toctree:: :maxdepth: 1 + deformation helmert molodensky hgridshift From 9e3547af382998b3e2c50c9000b77fc1ede8211c Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 22 Jan 2018 14:20:36 +0100 Subject: [PATCH 30/43] Add deformation docs-page (missing from previous commit) [skip ci] --- .../transformations/deformation.rst | 148 ++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/source/usage/operations/transformations/deformation.rst diff --git a/docs/source/usage/operations/transformations/deformation.rst b/docs/source/usage/operations/transformations/deformation.rst new file mode 100644 index 0000000000..2489f18e7e --- /dev/null +++ b/docs/source/usage/operations/transformations/deformation.rst @@ -0,0 +1,148 @@ +.. _deformation: + +================================================================================ +Kinematic datum shifting utilizing a deformation model +================================================================================ + +Perform datum shifts means of a deformation/velocity model. + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Cartesian coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Cartesian coordinates. | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `xy_grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ +| `z_grids` | Comma-separated list of grids to load. | ++-----------------+--------------------------------------------------------------------+ +| `t_epoch` | Central epoch of transformation. [decimalyear]. Only used in | +| | spatiotemporal transformations. | ++-----------------+--------------------------------------------------------------------+ +| `t_obs` | Observation time of coordinate(s). Mostly useful in 2D and 3D | +| | transformations. [decimalyear]. *Optional*. | ++-----------------+--------------------------------------------------------------------+ + +The deformation operation is used to adjust coordinates for intraplate deformations. +Usually the transformation parameters for regional plate-fixed reference frames such as +the ETRS89 does not take intraplate deformation into account. It is assumed that +tectonic plate of the region is rigid. Often times this is true, but near the plate +boundary and in areas with post-glacial uplift the assumption breaks. Tntraplate +deformations can be modelled and then applied to the coordinates so that +they represent the physical world better. In PROJ this is done with the deformation +operation. + +The horizontal grid is stored in CTable2 format and the vertical grid is stored in the +GTX format. Both grids are expected to contain grid-values in units of mm/year. +Details about the formats can be found in the GDAL documentation. GDAL both reads and +writes both file formats. Using GDAL for construction of new grids is recommended. + +Example +------------------------------------------------------------------------------- + +In [Häkli2016]_ coordinate transformation including a deformation model is described. +The paper describes how coordinates from the global ITRFxx frames are transformed to the +local Nordic realisations of ERTS89. Scandinavia is an area with significant post-glacial +rebound. The deformations from the post-glacial uplift is not accounted for in the +offcial ETRS89 transformations so in order to get accurate transformations in the Nordic +countries it is necesarry to apply the deformation model. The transformation from ITRF2008 +to the Danish realisation of ETRS89 is in PROJ described as:: + + proj = pipeline ellps = GRS80 + # ITRF2008@t_obs -> ITRF2000@t_obs + step init = ITRF2008:ITRF2000 + # ITRF2000@t_obs -> ETRF2000@t_obs + step proj=helmert t_epoch = 2000.0 transpose + x = 0.054 rx = 0.000891 drx = 8.1e-05 + y = 0.051 ry = 0.00539 dry = 0.00049 + z = -0.048 rz = -0.008712 drz = -0.000792 + # ETRF2000@t_obs -> NKG_ETRF00@2000.0 + step proj = deformation t_epoch = 2000.0 + xy_grids = ./nkgrf03vel_realigned_xy.ct2 + z_grids = ./nkgrf03vel_realigned_z.gtx + # NKG_ETRF@2000.0 -> ETRF92@2000.0 + step proj=helmert transpose s = -0.009420e + x = 0.03863 rx = 0.00617753 + y = 0.147 ry = 5.064e-05 + z = 0.02776 rz = 4.729e-05 + # ETRF92@2000.0 -> ETRF92@1994.704 + step proj = deformation t_epoch = 1994.704 t_obs = 2000.0 + xy_grids = ./nkgrf03vel_realigned_xy.ct2 + z_grids = ./nkgrf03vel_realigned_z.gtx + +From this we can see that the transformation from ITRF2008 to the Danish realisation of +ETRS89 is a combination of Helmert transformations and adjustments with a deformation +model. The first use of the deformation operation is:: + + proj = deformation t_epoch = 2000.0 + xy_grids = ./nkgrf03vel_realigned_xy.ct2 + z_grids = ./nkgrf03vel_realigned_z.gtx + +Here we set the central epoch of the transformation, 2000.0. The observation epoch +is expected as part of the input coordinate tuple. The deformation model is +described by two grids, specified with *xy_grids* and *z_grids*. The first is +the horizontal part of the model and the second is the vertical component. + +Mathematical description +------------------------------------------------------------------------------- + +Mathematically speaking, application of a deformation model is simple. The deformation model is +represented as a grid of velocities in three dimensions. Coordinate corrections are +applied in cartesian space. For a given coordinate, :math:`(X, Y, Z)`, velocities +:math:`(V_X, V_Y, V_Z)` can be interpolated from the gridded model. The time span +between :math:`t_c` and :math:`t_{obs}` determine the magnitude of the coordinate +correcton as seen in eq. :eq:`apply_velocity` below. + +.. math:: + :label: apply_velocity + + \begin{align} + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix}_B = + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix}_A + + (t_c - t_{obs}) + \begin{pmatrix} + V_X \\ + V_Y \\ + V_Z \\ + \end{pmatrix} + \end{align} + +Corrections are done in cartesian space. + +Coordinates of the gridded model are in ENU (east, north, up) space because it would +otherwise require an enormous 3 dimensional grid to handle the corrections in cartesian +space. Keeping the correction in lat/long space reduces the complexity of the grid +significantly. Consequentyly though, the input coordinates needs to be converted to +lat/long space when searching for corrections in the grid. This is done with *cart* +operation. The converted grid corrections can then be applied to the input coordinates +in cartesian space. The conversion from ENU space to cartesian space is done in the +following way: + +.. math:: + :label: enu2xyz + + \begin{align} + \begin{pmatrix} + X \\ + Y \\ + Z \\ + \end{pmatrix} = + \begin{pmatrix} + -\sin\phi \cos\lambda N - \sin\lambda E + \cos\phi \cos\lambda U \\ + -\sin\phi \sin\lambda N + \sin\lambda E + \cos\phi \sin\lambda U \\ + \cos\phi N + \sin\phi U \\ + \end{pmatrix} + \end{align} + +where :math:`\phi` and :math:`\lambda` are the latitude and longitude of the coordinate +that is searched for in the grid. :math:`(E, N, U)` are the grid values in ENU-space and +:math:`(X, Y, Z)` are the corrections converted to cartesian space. From 0e51328d89563c2968a33e816bfd4424d2437a7e Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 22 Jan 2018 14:21:25 +0100 Subject: [PATCH 31/43] Add details about grid file formats in relevant sections of the documentation [skip ci] --- docs/source/grids.rst | 5 +++++ docs/source/usage/operations/transformations/hgridshift.rst | 3 +++ docs/source/usage/operations/transformations/vgridshift.rst | 3 +++ 3 files changed, 11 insertions(+) diff --git a/docs/source/grids.rst b/docs/source/grids.rst index 7f362a9245..4c0bc5773e 100644 --- a/docs/source/grids.rst +++ b/docs/source/grids.rst @@ -11,6 +11,11 @@ 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. GDAL reads and writes all formats. Using GDAL +for construction of new grids is recommended. + US, Canadian, French and New Zealand -------------------------------------------------------------------------------- diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst index bd147c2f73..a9690260f5 100644 --- a/docs/source/usage/operations/transformations/hgridshift.rst +++ b/docs/source/usage/operations/transformations/hgridshift.rst @@ -34,3 +34,6 @@ is not found in the PROJ.4 search path. The list of grids is prioritized so that grids in the start of the list takes presedence over the grids in the back of the list. +PROJ supports CTable2, NTv1 and NTv2 files for horizontal grid corrections. Details +about all three formats can be found in the GDAL documentation. GDAL reads and +writes all three formats. Using GDAL for construction of new grids is recommended. diff --git a/docs/source/usage/operations/transformations/vgridshift.rst b/docs/source/usage/operations/transformations/vgridshift.rst index 272b24abab..31b3e56e87 100644 --- a/docs/source/usage/operations/transformations/vgridshift.rst +++ b/docs/source/usage/operations/transformations/vgridshift.rst @@ -36,3 +36,6 @@ is not found in the PROJ.4 search path. The list of grids is prioritized so that grids in the start of the list takes presedence over the grids in the back of the list. +PROJ supports the GTX file format for vertical grid corrections. Details +about all the format can be found in the GDAL documentation. GDAL both reads and +writes the format. Using GDAL for construction of new grids is recommended. From 46f56fb01e272730a007e5c6cecb40158c096c0a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 22 Jan 2018 15:37:47 +0100 Subject: [PATCH 32/43] Adding rudimentary docs for the pipeline operation [skip ci]. --- docs/source/usage/operations/index.rst | 1 + docs/source/usage/operations/pipeline.rst | 98 +++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 docs/source/usage/operations/pipeline.rst diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst index baae0e0ae0..d78f8947d6 100644 --- a/docs/source/usage/operations/index.rst +++ b/docs/source/usage/operations/index.rst @@ -18,4 +18,5 @@ exert a change in reference frame are called transformations. projections/index conversions/index transformations/index + pipeline diff --git a/docs/source/usage/operations/pipeline.rst b/docs/source/usage/operations/pipeline.rst new file mode 100644 index 0000000000..186377129d --- /dev/null +++ b/docs/source/usage/operations/pipeline.rst @@ -0,0 +1,98 @@ +.. _pipeline: + +================================================================================ +The pipeline operator +================================================================================ + +Construct complex operations by daisy-chaining operations in a sequential pipeline. + ++-----------------+--------------------------------------------------------------------+ +| **Input type** | Any. | ++-----------------+--------------------------------------------------------------------+ +| **Output type** | Any. | ++-----------------+--------------------------------------------------------------------+ +| **Options** | ++-----------------+--------------------------------------------------------------------+ +| `step` | Separate each step in a pipeline. | ++-----------------+--------------------------------------------------------------------+ +| `inv` | Invert a step in a pipeline. | ++-----------------+--------------------------------------------------------------------+ + +.. note:: See the section on :ref:`transformation` for a more thorough introduction + to the concept of transformation pipelines in PROJ. + + +With the pipeline operation it is possible to perform several operations after each +other on the same input data. This feature makes it possible to create transformations +that are made up of more than one operation, e.g. performing a datum shift and then +applying a suitable map projection. Theoretically any transformation between two +coordinate reference systems is possible to perform using the pipeline operation, +provided that the necessary coordinate operations in each step is available in PROJ. + +A pipeline is made up of a number of steps, with each step being a coordinate operation +in itself. By connecting these individual steps sequentially we end up with a concatenated +coordinate operation. An example of this is a transformation from geodetic coordinates +on the GRS80 ellipsoid to a projected system where the east-west and north-east axes has +been swapped: + +:: + + +proj=pipeline +ellps=GRS80 +step +proj=merc +step +proj=axisswap +order=2,1 + +Here the first step is applying the :ref:`merc` projection and the second step is +applying the :ref:`axisswap` conversion. Note that the `+ellps=GRS80` is specified +before the first occurence of `+step`. This means that the GRS80 ellipsoid is used +in both steps, since any parameter stated before the first occurence of `+step` is +treated as a global parameter and is transferred to each individual steps. + + +Rules for pipelines +------------------------------------------------------------------------------- + +**1. Pipelines must consist of at least one step.** + +:: + + +proj=pipeline + +Will result in an error. + +**2. Pipelines can only be nested if the nested pipeline is defined in an init-file.** + +:: + + +proj=pipeline + +step +proj=pipeline +step +proj=merc +step +proj=axisswap +order=2,1 + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +Results in an error, while + +:: + + +proj=pipeline + +step +init=predefined_pipelines:projectandswap + +step +proj=unitconvert +xy_in=m +xy_out=us-ft + +does not. + +**3. Pipelines without a forward path can't be constructed.** + +:: + + +proj=pipeline +step +inv +proj=urm5 + +Will result in an error since :ref:`urm5` does not have an inverse operation defined. + +**4. Parameters added before the first `+step` are global and will be applied to all steps.** + +In the following the GRS80 ellipsoid will be applied to all steps. + +:: + + +proj=pipeline +ellps=GRS80 + +step +proj=cart + +step +proj=helmert +x=10 +y=3 +z=1 + +step +proj=cart +inv + +step +proj=merc + + From 28f7894d9aee8eecc691fd691a0e27ff0914ce08 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 1 Feb 2018 16:46:06 +0100 Subject: [PATCH 33/43] Update datatype and function reference to reflect recent code changes [skip ci] --- .../development/reference/datatypes.rst | 26 +++++++++++++++++++ .../development/reference/functions.rst | 4 +-- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 1253b1a203..80e9ae4c38 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -401,6 +401,11 @@ Projection derivatives double tissot_semimajor; double tissot_semiminor; + + double dx_dlam; + double dx_dphi; + double dy_dlam; + double dy_dphi; } PJ_FACTORS; .. c:member:: double PJ_FACTORS.meridional_scale @@ -436,6 +441,27 @@ Projection derivatives Minimum scale error. + .. c:member:: double PJ_FACTORS.dx_dlam + + Partial derivative :math:`\frac{\partial x}{\partial \lambda}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dy_dlam + + + Partial derivative :math:`\frac{\partial y}{\partial \lambda}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dx_dphi + + Partial derivative :math:`\frac{\partial x}{\partial \phi}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dy_dphi + + + Partial derivative :math:`\frac{\partial y}{\partial \phi}` of coordinate + :math:`\left(\lambda,\phi\right)`. List structures ------------------------------------------------------------------------------- diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index ea1289541c..14c0b52a97 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -531,9 +531,9 @@ Various :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) -.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) +.. c:function:: PJ_COORD proj_geocentric_latitude(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) - Convert geographical to geocentric latitude. + Convert from geographical latitude to geocentric latitude. :param `P`: Transformation object :type `P`: const PJ* From a9e08ad008b1ff16d6139aab5e813058c922eef8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 22:37:10 +0100 Subject: [PATCH 34/43] API reference updates to reflect recent changes across the code-base [skip ci]. --- .../development/reference/datatypes.rst | 106 ++++++------ .../development/reference/functions.rst | 156 +++++++----------- 2 files changed, 110 insertions(+), 152 deletions(-) diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 1253b1a203..89a9306e93 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -62,7 +62,7 @@ Transformation objects Opaque object describing an area in which a transformation is performed. - .. note:: This object is not fully implemented yet. It is used with + .. note:: This object is not fully implemented yet. It is to be used with :c:func:`proj_create_crs_to_crs` to select the best transformation between the two input coordinate reference systems. @@ -71,56 +71,56 @@ Transformation objects Various 2-dimensional coordinate data types. -.. c:type:: LP +.. c:type:: PJ_LP Geodetic coordinate, latitude and longitude. Usually in radians. .. code-block:: C - typedef struct { double lam, phi; } LP; + typedef struct { double lam, phi; } PJ_LP; - .. c:member:: double LP.lam + .. c:member:: double PJ_LP.lam Longitude. Lambda. - .. c:member:: double LP.phi + .. c:member:: double PJ_LP.phi Latitude. Phi. -.. c:type:: XY +.. c:type:: PJ_XY 2-dimensional cartesian coordinate. .. code-block:: C - typedef struct { double x, y; } XY; + typedef struct { double x, y; } PJ_XY; - .. c:member:: double XY.lam + .. c:member:: double PJ_XY.lam Easting. - .. c:member:: double XY.phi + .. c:member:: double PJ_XY.phi Northing. -.. c:type:: UV +.. c:type:: PJ_UV 2-dimensional generic coordinate. Usually used when contents can be either - a :c:type:`XY` or :c:type:`UV`. + a :c:type:`PJ_XY` or :c:type:`PJ_LP`. .. code-block:: C - typedef struct {double u, v; } UV; + typedef struct {double u, v; } PJ_UV; - .. c:member:: double UV.u + .. c:member:: double PJ_UV.u Longitude or easting, depending on use. - .. c:member:: double UV.v + .. c:member:: double PJ_UV.v Latitude or northing, depending on use. @@ -131,66 +131,66 @@ Various 2-dimensional coordinate data types. The following data types are the 3-dimensional equivalents to the data types above. -.. c:type:: LPZ +.. c:type:: PJ_LPZ - 3-dimensional version of :c:type:`LP`. Holds longitude, latitude and + 3-dimensional version of :c:type:`PJ_LP`. Holds longitude, latitude and vertical component. .. code-block:: C - typedef struct { double lam, phi, z; } LPZ; + typedef struct { double lam, phi, z; } PJ_LPZ; - .. c:member:: double LPZ.lam + .. c:member:: double PJ_LPZ.lam Longitude. Lambda. - .. c:member:: double LPZ.phi + .. c:member:: double PJ_LPZ.phi Latitude. Phi. - .. c:member:: double LPZ.z + .. c:member:: double PJ_LPZ.z Vertical component. -.. c:type:: XYZ +.. c:type:: PJ_XYZ - Cartesian coordinate in 3 dimensions. Extension of :c:type:`XY`. + Cartesian coordinate in 3 dimensions. Extension of :c:type:`PJ_XY`. .. code-block:: C - typedef struct { double x, y, z; } XYZ; + typedef struct { double x, y, z; } PJ_XYZ; - .. c:member:: double XYZ.x + .. c:member:: double PJ_XYZ.x Easting. - .. c:member:: double XYZ.y + .. c:member:: double PJ_XYZ.y Northing. - .. c:member:: double XYZ.z + .. c:member:: double PJ_XYZ.z Vertical component. -.. c:type:: UVW +.. c:type:: PJ_UVW - 3-dimensional extension of :c:type:`UV`. + 3-dimensional extension of :c:type:`PJ_UV`. .. code-block:: C - typedef struct {double u, v, w; } UVW; + typedef struct {double u, v, w; } PJ_UVW; - .. c:member:: double UVW.u + .. c:member:: double PJ_UVW.u Longitude or easting, depending on use. - .. c:member:: double UVW.v + .. c:member:: double PJ_UVW.v Latitude or northing, depending on use. - .. c:member:: double UVW.w + .. c:member:: double PJ_UVW.w Vertical component. @@ -204,7 +204,7 @@ domain. .. c:type:: PJ_LPZT - Spatiotemporal version of :c:type:`LPZ`. + Spatiotemporal version of :c:type:`PJ_LPZ`. .. code-block:: C @@ -321,6 +321,7 @@ Complex coordinate types .. c:type:: PJ_COORD General purpose coordinate union type usefull in two, three and four dimensions. + This is the default coordinate datatype used in PROJ. .. code-block:: C @@ -329,12 +330,12 @@ Complex coordinate types PJ_XYZT xyzt; PJ_UVWT uvwt; PJ_LPZT lpzt; - XYZ xyz; - UVW uvw; - LPZ lpz; - XY xy; - UV uv; - LP lp; + PJ_XYZ xyz; + PJ_UVW uvw; + PJ_LPZ lpz; + PJ_XY xy; + PJ_UV uv; + PJ_LP lp; } PJ_COORD ; .. c:member:: double v[4] @@ -353,27 +354,27 @@ Complex coordinate types Longitude, latitude, vertical and time components. - .. c:member:: XYZ PJ_COORD.xyz + .. c:member:: PJ_XYZ PJ_COORD.xyz 3-dimensional cartesian coordinate. - .. c:member:: UVW PJ_COORD.uvw + .. c:member:: PJ_UVW PJ_COORD.uvw 3-dimensional generic coordinate. - .. c:member:: LPZ PJ_COORD.lpz + .. c:member:: PJ_LPZ PJ_COORD.lpz Longitude, latitude and vertical component. - .. c:member:: XY PJ_COORD.xy + .. c:member:: PJ_XY PJ_COORD.xy 2-dimensional cartesian coordinate. - .. c:member:: UV PJ_COORD.uv + .. c:member:: PJ_UV PJ_COORD.uv 2-dimensional generic coordinate. - .. c:member:: LP PJ_COORD.lp + .. c:member:: PJ_LP PJ_COORD.lp Longitude and latitude. @@ -496,7 +497,7 @@ List structures .. c:type:: PJ_UNITS - Distance units defined in PROJ.4. + Distance units defined in PROJ. .. code-block:: C @@ -525,7 +526,7 @@ List structures .. c:type:: PJ_PRIME_MERIDIANS - Prime meridians defined in PROJ.4. + Prime meridians defined in PROJ. .. code-block:: C @@ -547,7 +548,7 @@ Info structures .. c:type:: PJ_INFO - Struct holding information about the current instance of PROJ.4. Struct is + Struct holding information about the current instance of PROJ. Struct is populated by :c:func:`proj_info`. .. code-block:: C @@ -585,8 +586,9 @@ Info structures .. c:member:: char PJ_INFO.searchpath[512] - Search path for PROJ.4. List of directories separated by - semicolons, e.g. "C:\Users\doctorwho;C:\OSGeo4W64\\share\proj". + Search path for PROJ. List of directories separated by + semicolons (Windows) or colons (non-Windows), e.g. + "C:\\Users\\doctorwho;C:\\OSGeo4W64\\share\\proj". Grids and init files are looked for in directories in the search path. .. c:type:: PJ_PROJ_INFO @@ -630,7 +632,7 @@ Info structures .. c:type:: PJ_GRID_INFO Struct holding information about a specific grid in the search path of - PROJ.4. Populated with the function :c:func:`proj_grid_info`. + PROJ. Populated with the function :c:func:`proj_grid_info`. .. code-block:: C @@ -684,7 +686,7 @@ Info structures .. c:type:: PJ_INIT_INFO Struct holding information about a specific init file in the search path of - PROJ.4. Populated with the function :c:func:`proj_init_info`. + PROJ. Populated with the function :c:func:`proj_init_info`. .. code-block:: C diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index ea1289541c..8770f99b1d 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -205,83 +205,6 @@ Coordinate transformation :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number -Initializers -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) - - Initializer for the :c:type:`PJ_COORD` union. The function is - shorthand for the otherwise convoluted assignment. - Equivalent to - - .. code-block:: C - - PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; - - or - - .. code-block:: C - - PJ_COORD c; - // Assign using the PJ_XYZT struct in the union - c.xyzt.x = 10.0; - c.xyzt.y = 20.0; - c.xyzt.z = 30.0; - c.xyzt.t = 40.0; - - Since :c:type:`PJ_COORD` is a union of structs, the above assignment can - also be expressed in terms of the other types in the union, e.g. - :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. - - - :param double x: 1st component in a :c:type:`PJ_COORD` - :param double y: 2nd component in a :c:type:`PJ_COORD` - :param double z: 3rd component in a :c:type:`PJ_COORD` - :param double t: 4th component in a :c:type:`PJ_COORD` - :returns: :c:type:`PJ_COORD` - -.. c:function:: PJ_OBS proj_obs(double x, double y, double z, double t,\ - double o, double p, double k,\ - int id, unsigned int flags) - - Initializer for the :c:type:`PJ_OBS` union. The function is - shorthand for the otherwise convoluted assignment. - Equivalent to - - .. code-block:: C - - PJ_OBS c = {{{1.0, 2.0, 3.0, 4.0}}, {{5.0, 6.0, 7.0}}, 8, 9}; - - or - - .. code-block:: C - - PJ_OBS c; - // Assign using the PJ_COORD part of the struct in the union - o.coo.v[0] = 1.0; - o.coo.v[1] = 2.0; - o.coo.v[2] = 3.0; - o.coo.v[3] = 4.0; - o.anc.v[0] = 5.0; - o.anc.v[1] = 6.0; - o.anc.v[2] = 7.0; - o.id = 8; - o.flags = 9; - - which is a bit too verbose in most practical applications. - - :param double x: 1st component in a :c:type:`PJ_COORD` - :param double y: 2nd component in a :c:type:`PJ_COORD` - :param double z: 3rd component in a :c:type:`PJ_COORD` - :param double t: 4th component in a :c:type:`PJ_COORD` - :param double o: 1st component in a :c:type:`PJ_TRIPLET` - :param double p: 2nd component in a :c:type:`PJ_TRIPLET` - :param double k: 3rd component in a :c:type:`PJ_TRIPLET` - :param int id: Ancillary data, e.g. an ID - :param `flags`: Flags - :type `flags`: unsigned int - :returns: :c:type:`PJ_OBS` - Error reporting ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -350,7 +273,7 @@ Info functions .. c:function:: PJ_INFO proj_info(void) - Get information about the current instance of the PROJ.4 library. + Get information about the current instance of the PROJ library. :returns: :c:type:`PJ_INFO` @@ -366,7 +289,7 @@ Info functions Get information about a specific grid. - :param `gridname`: Gridname in the PROJ.4 searchpath + :param `gridname`: Gridname in the PROJ searchpath :type `gridname`: const char* :returns: :c:type:`PJ_GRID_INFO` @@ -374,7 +297,7 @@ Info functions Get information about a specific init file. - :param `initname`: Init file in the PROJ.4 searchpath + :param `initname`: Init file in the PROJ searchpath :type `initname`: const char* :returns: :c:type:`PJ_INIT_INFO` @@ -383,11 +306,11 @@ Lists .. c:function:: const PJ_OPERATIONS* proj_list_operations(void) - Get a pointer to an array of all operations in PROJ.4. The last entry + Get a pointer to an array of all operations in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. - Print a list of all operations in PROJ.4: + Print a list of all operations in PROJ: .. code-block:: C @@ -400,7 +323,7 @@ Lists .. c:function:: const PJ_ELLPS* proj_list_ellps(void) - Get a pointer to an array of ellipsoids defined in PROJ.4. The last entry + Get a pointer to an array of ellipsoids defined in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. @@ -408,7 +331,7 @@ Lists .. c:function:: const PJ_UNITS* proj_list_units(void) - Get a pointer to an array of distance units defined in PROJ.4. The last + Get a pointer to an array of distance units defined in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. @@ -416,7 +339,7 @@ Lists .. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void) - Get a pointer to an array of prime meridians defined in PROJ.4. The last + Get a pointer to an array of prime meridians defined in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. @@ -425,44 +348,77 @@ Lists Distances ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_lp_dist(const PJ *P, LP a, LP b) +.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b) Calculate geodesic distance between two points in geodetic coordinates. :param PJ* P: Transformation object - :param LP a: Coordinate of first point - :param LP b: Coordinate of second point + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. -.. c:function:: double proj_lp_dist(const PJ *P, LPZ a, LPZ b) +.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b) Calculate geodesic distance between two points in geodetic coordinates. :param PJ* P: Transformation object - :param LPZ a: Coordinate of first point - :param LPZ b: Coordinate of second point + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. -.. c:function:: double proj_xy_dist(XY a, XY, b) +.. c:function:: double proj_xy_dist(PJ_COORD a, PJ_COORD b) Calculate 2-dimensional euclidean between two projected coordinates. - :param XY a: First coordinate - :param XY b: Second coordinate + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. -.. c:function:: double proj_xyz_dist(XYZ a, XYZ b) +.. c:function:: double proj_xyz_dist(PJ_COORD a, PJ_COORD b) Calculate 3-dimensional euclidean between two projected coordinates. - :param XYZ a: First coordinate - :param XYZ b: Second coordinate + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. Various ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) + + Initializer for the :c:type:`PJ_COORD` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; + + or + + .. code-block:: C + + PJ_COORD c; + // Assign using the PJ_XYZT struct in the union + c.xyzt.x = 10.0; + c.xyzt.y = 20.0; + c.xyzt.z = 30.0; + c.xyzt.t = 40.0; + + Since :c:type:`PJ_COORD` is a union of structs, the above assignment can + also be expressed in terms of the other types in the union, e.g. + :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. + + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :returns: :c:type:`PJ_COORD` + + .. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coo) Measure internal consistency of a given transformation. The function @@ -480,7 +436,7 @@ Various :returns: :c:type:`double` Distance between original coordinate and the \ resulting coordinate after :c:data:`n` transformation iterations. -.. c:function:: PJ_FACTORS proj_factors(PJ *P, LP lp) +.. c:function:: PJ_FACTORS proj_factors(PJ *P, PJ_COORD lp) Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence. Depending on the underlying projection @@ -492,7 +448,7 @@ Various :param `P`: Transformation object :type `P`: const PJ* :param `lp`: Geodetic coordinate - :type `lp`: const LP + :type `lp`: const PJ_COORD :returns: :c:type:`PJ_FACTORS` .. c:function:: double proj_torad(double angle_in_degrees) @@ -531,7 +487,7 @@ Various :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) -.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) +.. c:function:: PJ_COORD proj_geocentric_latitude(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) Convert geographical to geocentric latitude. From 631145da4d23db670cb378fdae14dc6f3555513b Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 23:09:40 +0100 Subject: [PATCH 35/43] Change most occurences of PROJ.4 to PROJ [skip ci] --- docs/source/contributing.rst | 46 +++++++++---------- docs/source/development/bindings.rst | 14 +++--- docs/source/development/cmake.rst | 4 +- docs/source/development/index.rst | 2 +- docs/source/development/quickstart.rst | 10 ++-- docs/source/development/threads.rst | 8 ++-- docs/source/download.rst | 2 +- docs/source/faq.rst | 38 +++++++-------- docs/source/grids.rst | 6 +-- docs/source/htpd.rst | 6 +-- docs/source/index.rst | 8 ++-- docs/source/usage/apps/index.rst | 2 +- docs/source/usage/environmentvars.rst | 10 ++-- docs/source/usage/index.rst | 4 +- .../usage/operations/conversions/index.rst | 2 +- .../operations/conversions/unitconvert.rst | 4 +- docs/source/usage/operations/index.rst | 4 +- .../usage/operations/projections/geos.rst | 2 +- .../usage/operations/projections/index.rst | 2 +- .../operations/transformations/hgridshift.rst | 2 +- .../operations/transformations/vgridshift.rst | 2 +- docs/source/usage/projections.rst | 8 ++-- docs/source/usage/quickstart.rst | 6 +-- docs/source/usage/resource_files.rst | 12 ++--- docs/source/usage/transformation.rst | 18 ++++---- 25 files changed, 111 insertions(+), 111 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index e7f9101e0c..5e198ae79c 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -4,13 +4,13 @@ Contributing =========================== -PROJ.4 has a wide and varied user base. Some are highly skilled +PROJ has a wide and varied user base. Some are highly skilled geodesists with a deep knowledge of map projections and reference systems, some are GIS software developers and others are GIS users. All users, regardless of the profession or skill level, has the ability to -contribute to PROJ.4. Here's a few suggestion on how: +contribute to PROJ. Here's a few suggestion on how: -- Help PROJ.4-users that is less experienced than yourself. +- Help PROJ-users that is less experienced than yourself. - Write a bug report - Request a new feature - Write documentation for your favorite map projection @@ -18,20 +18,20 @@ contribute to PROJ.4. Here's a few suggestion on how: - Implement a new feature In the following sections you can find some guidelines on how to -contribute. As PROJ.4 is managed on GitHub most contributions require +contribute. As PROJ is managed on GitHub most contributions require that you have a GitHub account. Familiarity with `issues `__ and the `GitHub Flow `__ is an advantage. -Help a fellow PROJ.4 user +Help a fellow PROJ user ------------------------- -The main forum for support for PROJ.4 is the mailing list. You can +The main forum for support for PROJ is the mailing list. You can subscribe to the mailing list `here `__ and read the archive `here `__. -If you have questions about the usage of PROJ.4 the mailing list is also +If you have questions about the usage of PROJ the mailing list is also the place to go. Please *do not* use the GitHub issue tracker as a support forum. Your question is much more likely to be answered on the mailing list, as many more people follow that than the issue tracker. @@ -40,7 +40,7 @@ Adding bug reports ------------------ Bug reports are handled in the `issue -tracker `__ on PROJ.4's home on +tracker `__ on PROJ's home on GitHub. Writing a good bug report is not easy. But fixing a poorly documented bug is not easy either, so please put in the effort it takes to create a thorough bug report. @@ -49,7 +49,7 @@ A good bug report includes at least: - A title that quickly explains the problem - A description of the problem and how it can be reproduced -- Version of PROJ.4 being used +- Version of PROJ being used - Version numbers of any other relevant software being used, e.g. operating system - A description of what already has been done to solve the problem @@ -61,16 +61,16 @@ them in a timely manner if you have an interest in getting the issue solved. Finally, please only submit bug reports that are actually related to -PROJ.4. If the issue materializes in software that uses PROJ.4 it is +PROJ. If the issue materializes in software that uses PROJ it is likely a problem with that particular software. Make sure that it -actually is a PROJ.4 problem before you submit an issue. If you can -reproduce the problem only by using tools from PROJ.4 it is definitely a -problem with PROJ.4. +actually is a PROJ problem before you submit an issue. If you can +reproduce the problem only by using tools from PROJ it is definitely a +problem with PROJ. Feature requests ---------------- -Got an idea for a new feature in PROJ.4? Submit a thorough description +Got an idea for a new feature in PROJ? Submit a thorough description of the new feature in the `issue tracker `__. Please include any technical documents that can help the developer make the new feature a @@ -84,14 +84,14 @@ Note that not all feature requests are accepted. Write documentation ------------------- -PROJ.4 is in dire need of better documentation. Any contributiions of -documentation are greatly appreaciated. The PROJ.4 documentation is +PROJ is in dire need of better documentation. Any contributiions of +documentation are greatly appreaciated. The PROJ documentation is available on `proj4.org `__. The website is generated with `Sphinx `__. Contributions to the documentation should be made as `Pull Requests `__ on GitHub. -If you intend to document one of PROJ.4's supported projections please +If you intend to document one of PROJ's supported projections please use the `Mercator projection `__ as a template. @@ -120,7 +120,7 @@ Submitting Changes ~~~~~~~~~~~~~~~~~~ - Push your changes to a topic branch in your fork of the repository. -- Submit a pull request to the PROJ.4 repository in the OSGeo +- Submit a pull request to the PROJ repository in the OSGeo organization. - If your pull request fixes/references an issue, include that issue number in the pull request. For example: @@ -131,7 +131,7 @@ Submitting Changes Fixes #123. -- PROJ.4 developers will look at your patch and take an appropriate +- PROJ developers will look at your patch and take an appropriate action. Coding conventions @@ -140,7 +140,7 @@ Coding conventions Programming language ^^^^^^^^^^^^^^^^^^^^ -PROJ.4 is developed strictly in ANSI C 89. +PROJ is developed strictly in ANSI C 89. Coding style ^^^^^^^^^^^^ @@ -152,7 +152,7 @@ with the style of the locally surrounding code. Whitespace ^^^^^^^^^^ -Throughout the PROJ.4 code base you will see differing whitespace use. +Throughout the PROJ code base you will see differing whitespace use. The general rule is to keep whitespace in whatever form it is in the file you are currently editing. If the file has a mix of tabs and space please convert the tabs to space in a separate commit before making any @@ -166,14 +166,14 @@ File names Files in which projections are implemented are prefixed with an upper-case ``PJ_`` and most other files are prefixed with lower-case ``pj_``. Some file deviate from this pattern, most of them dates back to -the very early releases of PROJ.4. New contributions should follow the +the very early releases of PROJ. New contributions should follow the pj-prefix pattern. Unless there are obvious reasons not to. Legalese ~~~~~~~~ Commiters are the front line gatekeepers to keep the code base clear of -improperly contributed code. It is important to the PROJ.4 users, +improperly contributed code. It is important to the PROJ users, developers and the OSGeo foundation to avoid contributing any code to the project without it being clearly licensed under the project license. diff --git a/docs/source/development/bindings.rst b/docs/source/development/bindings.rst index 80babcb20d..3fac186907 100644 --- a/docs/source/development/bindings.rst +++ b/docs/source/development/bindings.rst @@ -4,40 +4,40 @@ Language bindings ******************************************************************************** -PROJ.4 bindings are available for a number of different development platforms. +PROJ bindings are available for a number of different development platforms. Python ====== `pyproj `_: -Python interface (wrapper for PROJ.4) +Python interface (wrapper for PROJ) Ruby ======= `proj4rb `_: -Bindings for PROJ.4 in ruby +Bindings for PROJ in ruby TCL ======== `proj4tcl `_: -Bindings for PROJ.4 in tcl (critcl source) +Bindings for PROJ in tcl (critcl source) MySQL ===== `fProj4 `_: -Bindings for PROJ.4 in MySQL +Bindings for PROJ in MySQL Excel ======== `proj.xll `_: -Excel add-in for PROJ.4 map projections +Excel add-in for PROJ map projections Visual Basic ================== -`PROJ.4 VB Wrappers `_: +`PROJ VB Wrappers `_: By Eric G. Miller. diff --git a/docs/source/development/cmake.rst b/docs/source/development/cmake.rst index 1429ae8871..5a8ce62409 100644 --- a/docs/source/development/cmake.rst +++ b/docs/source/development/cmake.rst @@ -1,10 +1,10 @@ .. _cmake: ******************************************************************************** -Using Proj.4 in CMake projects +Using PROJ in CMake projects ******************************************************************************** -The recommended way to use the Proj.4 library in a CMake project is to +The recommended way to use the PROJ library in a CMake project is to link to the imported library target ``${PROJ4_LIBRARIES}`` provided by the CMake configuration which comes with the library. Typical usage is: diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 743224a633..3f8a7bf66a 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -5,7 +5,7 @@ Development ================================================================================ These pages are primarily focused towards developers either contributing to the -PROJ.4 project or using the library in their own software. +PROJ project or using the library in their own software. .. toctree:: diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index 7137d85a59..960cddbfc9 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -4,15 +4,15 @@ Quick start ================================================================================ -This is a short introduction to the PROJ.4 API. In the following section we +This is a short introduction to the PROJ API. In the following section we create a simple program that transforms a geodetic coordinate to UTM and back again. The program is explained a few lines at a time. The complete program can be seen at the end of the section. See the following sections for more in-depth descriptions of different parts of -the PROJ.4 API or consult the :doc:`API reference ` for specifics. +the PROJ API or consult the :doc:`API reference ` for specifics. -Before the PROJ.4 API can be used it is necessary to include the ``proj.h`` header +Before the PROJ API can be used it is necessary to include the ``proj.h`` header file. Here ``stdio.h`` is also included so we can print some text to the screen: .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c @@ -54,10 +54,10 @@ details. :lines: 50-52 :dedent: 4 -PROJ.4 uses it's own data structures for handling coordinates. Here we use a +PROJ uses it's own data structures for handling coordinates. Here we use a ``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note that the input values are converted to radians with ``proj_torad``. This is -necessary since PROJ.4 is using radians internally. See :doc:`transformations` +necessary since PROJ is using radians internally. See :doc:`transformations` for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c diff --git a/docs/source/development/threads.rst b/docs/source/development/threads.rst index a557fa07f6..674f4bd118 100644 --- a/docs/source/development/threads.rst +++ b/docs/source/development/threads.rst @@ -4,7 +4,7 @@ Threads ================================================================================ -This page is about efforts to make PROJ.4 thread safe. +This page is about efforts to make PROJ thread safe. Key Thread Safety Issues -------------------------------------------------------------------------------- @@ -14,14 +14,14 @@ Key Thread Safety Issues introduction of the projCtx execution context. * the datum shift using grid files uses globally shared lists of loaded grid information. Access to this has been made safe in 4.7.0 with the introduction - of a proj.4 mutex used to protect access to these memory structures (see + of a PROJ mutex used to protect access to these memory structures (see pj_mutex.c). projCtx -------------------------------------------------------------------------------- Primarily in order to avoid having pj_errno as a global variable, a "thread -context" structure has been introduced into a variation of the PROJ.4 API for +context" structure has been introduced into a variation of the PROJ API for the 4.8.0 release. The pj_init() and pj_init_plus() functions now have context variations called pj_init_ctx() and pj_init_plus_ctx() which take a projections context. @@ -68,7 +68,7 @@ src/multistresstest.c -------------------------------------------------------------------------------- A small multi-threaded test program has been written (src/multistresstest.c) -for testing multithreaded use of PROJ.4. It performs a series of reprojections +for testing multithreaded use of PROJ. It performs a series of reprojections to setup a table expected results, and then it does them many times in several threads to confirm that the results are consistent. At this time this program is not part of the builds but it can be built on linux like: diff --git a/docs/source/download.rst b/docs/source/download.rst index 4b9cbb9278..9afad945e8 100644 --- a/docs/source/download.rst +++ b/docs/source/download.rst @@ -45,7 +45,7 @@ Linux Docker ................................................................................ -A `Docker`_ image with just PROJ.4 binaries and a full compliment of grid shift +A `Docker`_ image with just PROJ binaries and a full compliment of grid shift files is available on `DockerHub`_: .. _`Docker`: https://docker.org diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 8afdb35d88..c508a167d9 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -15,7 +15,7 @@ Where can I find the list of projections and their arguments? There is no simple single location to find all the required information. The !PostScript/PDF documents listed on the [http://trac.osgeo.org/proj/wiki main] -PROJ.4 page under documentation are the authoritative source but projections +PROJ page under documentation are the authoritative source but projections and options are spread over several documents in a form more related to their order of implementation than anything else. @@ -25,7 +25,7 @@ units with the '''-lu''' option, and the list of built-in datums with the '''-ld''' option. The [http://www.remotesensing.org/geotiff/proj_list/ GeoTIFF Projections Pages] -include most of the common PROJ.4 projections, and a definition of the +include most of the common PROJ projections, and a definition of the projection specific options for each. * How do I do datum shifts between NAD27 and NAD83? @@ -50,10 +50,10 @@ In order for datum shifting to work properly the various grid shift files must be available. See below. More details are available in the [wiki:GenParms#nadgrids-GridBasedDatumAdjustments General Parameters] document. -How do I build/configure PROJ.4 to support datum shifting? +How do I build/configure PROJ to support datum shifting? -------------------------------------------------------------------------------- -After downloading and unpacking the PROJ.4 source, also download and unpack the +After downloading and unpacking the PROJ source, also download and unpack the set of datum shift files. See :ref:`download` for instructions how to fetch and install these files @@ -61,10 +61,10 @@ On Windows the extra nadshift target must be used. For instance ``nmake /f makefile.vc nadshift`` in the ``proj/src`` directory. A default build and install on Unix will normally build knowledge of the -directory where the grid shift files are installed into the PROJ.4 library +directory where the grid shift files are installed into the PROJ library (usually /usr/local/share/proj). On Windows the library is normally built thinking that C:\PROJ\NAD is the installed directory for the grid shift files. -If the built in concept of the PROJ.4 data directory is incorrect, the ``PROJ_LIB`` +If the built in concept of the PROJ data directory is incorrect, the ``PROJ_LIB`` environment can be defined with the correct directory. How do I debug problems with NAD27/NAD83 datum shifting? @@ -88,7 +88,7 @@ How do I debug problems with NAD27/NAD83 datum shifting? are not identified as having a datum, the datum shifting (and ellipsoid change) step is just quietly skipped! 4. The ``PROJ_DEBUG`` environment can be defined (any value) to force extra output - from the PROJ.4 library to stderr (the text console normally) with + from the PROJ library to stderr (the text console normally) with information on what data files are being opened and in some cases why a transformation fails. @@ -99,17 +99,17 @@ How do I debug problems with NAD27/NAD83 datum shifting? .. note:: - ``PROJ_DEBUG`` support is not yet very mature in the PROJ.4 library. + ``PROJ_DEBUG`` support is not yet very mature in the PROJ library. 5. The ``-v`` flag to cs2cs can be useful in establishing more detail on what parameters being used internally for a coordinate system. This will include expanding the definition of +datum clause. -How do I use EPSG coordinate system codes with PROJ.4? +How do I use EPSG coordinate system codes with PROJ? -------------------------------------------------------------------------------- There is somewhat imperfect translation between 2d geographic and projected -coordinate system codes and PROJ.4 descriptions of the coordinate system +coordinate system codes and PROJ descriptions of the coordinate system available in the epsg definition file that normally lives in the proj/nad directory. If installed (it is installed by default on Unix), it is possible to use EPSG numbers like this: @@ -144,12 +144,12 @@ use is more fully described in the [wiki:GenParms#towgs84-DatumtransformationtoWGS84 towgs84] parameter discussion. -Does PROJ.4 work in different international numeric locales? +Does PROJ work in different international numeric locales? -------------------------------------------------------------------------------- -No. PROJ.4 makes extensive use of sprintf() and atof() internally to translate +No. PROJ makes extensive use of sprintf() and atof() internally to translate numeric values. If a locale is in effect that modifies formatting of numbers, -altering the role of commas and periods in numbers, then PROJ.4 will not work. +altering the role of commas and periods in numbers, then PROJ will not work. This problem is common in some European locales. On unix-like platforms, this problem can be avoided by forcing the use of the @@ -194,7 +194,7 @@ the WGS84 datum which has a quite differently shaped ellipsoid. In this case, and many other cases using spherical projections, the desired approach is to actually treat the lat/long locations on the sphere as if they were on WGS84 without any adjustments when using them for converting to other -coordinate systems. The solution is to "trick" PROJ.4 into applying no change +coordinate systems. The solution is to "trick" PROJ into applying no change to the lat/long values when going to (and through) WGS84. This can be accomplished by asking PROJ to use a null grid shift file for switching from your spherical lat/long coordinates to WGS84. @@ -212,7 +212,7 @@ Similar issues apply with many other datasets distributed with projections based on a spherical earth model - such as many NASA datasets. This coordinate system is now known by the EPSG code 3857 and has in the past been known as EPSG:3785 and EPSG:900913. When using this coordinate system with GDAL/OGR it -is helpful to include the +wktext so the exact PROJ.4 string will be preserved +is helpful to include the +wktext so the exact PROJ string will be preserved in the WKT representation (otherwise key parameters like `+nadgrids=@null` will be dropped): @@ -224,11 +224,11 @@ be dropped): Why do I get different results with 4.5.0 and 4.6.0? -------------------------------------------------------------------------------- -The default datum application behavior changed with the 4.6.0 release. PROJ.4 +The default datum application behavior changed with the 4.6.0 release. PROJ will now only apply a datum shift if both the source and destination coordinate system have valid datum shift information. -From the PROJ.4 4.6.0 Release Notes (in NEWS): +From the PROJ 4.6.0 Release Notes (in NEWS): * MAJOR: Rework pj_transform() to avoid applying ellipsoid to ellipsoid transformations as a datum shift when no datum info is available. @@ -302,7 +302,7 @@ Output of above command: 0 0.7853981633974483 0.00 41.94 -What options does PROJ.4 allow for the shape of the Earth (geodesy)? +What options does PROJ allow for the shape of the Earth (geodesy)? -------------------------------------------------------------------------------- See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c @@ -315,7 +315,7 @@ What if I want a spherical Earth? Use ``+ellps=sphere``. See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c for the radius used in this case. -How do I change the radius of the Earth? How do I use PROJ.4 for work on Mars? +How do I change the radius of the Earth? How do I use PROJ for work on Mars? -------------------------------------------------------------------------------- You can supply explicit values for the semi minor and semi major axes instead diff --git a/docs/source/grids.rst b/docs/source/grids.rst index 4c0bc5773e..b3a551d748 100644 --- a/docs/source/grids.rst +++ b/docs/source/grids.rst @@ -44,7 +44,7 @@ HARN With the support of `i-cubed `__, 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.4. This project included +into NTv2 format for convenient use with PROJ. This project included implementing a `.los/.las reader `__ for GDAL, and an `NTv2 reader/writer `__. Also, a script to do the bulk translation was implemented in @@ -55,7 +55,7 @@ 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.4 like this: +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: :: @@ -101,7 +101,7 @@ distributed, but can be obtained by users through free and legal methods. Canada NTv2.0 ................................................................................ -Although NTv1 grid shifts are provided freely with PROJ.4, the higher-quality +Although NTv1 grid shifts are provided freely with PROJ, the higher-quality NTv2.0 file needs to be downloaded from Natural Resources Canada. More info: http://www.geod.nrcan.gc.ca/tools-outils/ntv2_e.php. diff --git a/docs/source/htpd.rst b/docs/source/htpd.rst index 2209c8650d..4007bef603 100644 --- a/docs/source/htpd.rst +++ b/docs/source/htpd.rst @@ -10,8 +10,8 @@ HTPD This page documents use of the `crs2crs2grid.py` script and the HTDP (Horizontal Time Dependent Positioning) grid shift modelling program from -NGS/NOAA to produce PROJ.4 compatible grid shift files for fine grade -conversions between various NAD83 epochs and WGS84. Traditionally PROJ.4 has +NGS/NOAA to produce PROJ compatible grid shift files for fine grade +conversions between various NAD83 epochs and WGS84. Traditionally PROJ has treated NAD83 and WGS84 as equivalent and failed to distinguish between different epochs or realizations of those datums. At the scales of much mapping this is adequate but as interest grows in high resolution imagery and @@ -121,7 +121,7 @@ source and destination date (epoch). For example: crs2crs2grid.py 29 2002.0 8 2002.0 -o nad83_2002.ct2 -The output is a CTable2 format grid shift file suitable for use with PROJ.4 +The output is a CTable2 format grid shift file suitable for use with PROJ (4.8.0 or newer). It might be utilized something like: diff --git a/docs/source/index.rst b/docs/source/index.rst index 324d52fc2a..88bac7388c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,13 +1,13 @@ .. _home: ****************************************************************************** -PROJ.4 +PROJ ****************************************************************************** -PROJ.4 is a standard UNIX filter function which converts geographic longitude +PROJ 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 `_. +own software. PROJ is maintained on `GitHub `_. ============= ================================================================ @@ -49,7 +49,7 @@ Documentation Mailing List ================================================================================ -The PROJ.4 mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj +The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj Indices and tables ================== diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst index 73c5c63c5b..0d81868231 100644 --- a/docs/source/usage/apps/index.rst +++ b/docs/source/usage/apps/index.rst @@ -4,7 +4,7 @@ Applications ================================================================================ -Bundled with PROJ.4 comes a set of small command line utilities. The +Bundled with PROJ 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 diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst index 38cb46de8a..0d5d06a8be 100644 --- a/docs/source/usage/environmentvars.rst +++ b/docs/source/usage/environmentvars.rst @@ -4,7 +4,7 @@ Environment variables ================================================================================ -PROJ.4 can be crontrolled by setting environment variables. Most users will +PROJ can be crontrolled by setting environment variables. Most users will have a use for the :envvar:`PROJ_LIB`. On UNIX systems environment variables can be set for a shell-session with:: @@ -30,14 +30,14 @@ done by setting the variable with no content:: .. envvar:: PROJ_LIB - The location of PROJ.4 :doc:`resource files`. + The location of PROJ :doc:`resource files`. It is only possible to specify a single library in :envvar:`PROJ_LIB`; e.g. it - does not behave like PATH. PROJ.4 is hardcoded to look for resource files + does not behave like PATH. PROJ is hardcoded to look for resource files in other locations as well, amongst those are the users home directory, ``/usr/share/proj`` and the current folder. .. envvar:: PROJ_DEBUG - Set the debug level of PROJ.4. The default debug level is zero, which results - in no debug output when using PROJ.4. A number from 1-3, whit 3 being the most + Set the debug level of PROJ. The default debug level is zero, which results + in no debug output when using PROJ. A number from 1-3, whit 3 being the most verbose setting. diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst index 81ea4b6b8b..d59296d062 100644 --- a/docs/source/usage/index.rst +++ b/docs/source/usage/index.rst @@ -1,10 +1,10 @@ .. _usage: ================================================================================ -Using PROJ.4 +Using PROJ ================================================================================ -The main purpose of PROJ.4 is to transform coordinates from one coordinate +The main purpose of PROJ 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. diff --git a/docs/source/usage/operations/conversions/index.rst b/docs/source/usage/operations/conversions/index.rst index 54324ec435..af27e2fd2a 100644 --- a/docs/source/usage/operations/conversions/index.rst +++ b/docs/source/usage/operations/conversions/index.rst @@ -5,7 +5,7 @@ Conversions ================================================================================ Conversions are coordinate operations in which both coordinate reference systems -are based on the same datum. In PROJ.4 projections are differentiated from +are based on the same datum. In PROJ projections are differentiated from conversions. .. toctree:: diff --git a/docs/source/usage/operations/conversions/unitconvert.rst b/docs/source/usage/operations/conversions/unitconvert.rst index ad8482071b..73e517bd01 100644 --- a/docs/source/usage/operations/conversions/unitconvert.rst +++ b/docs/source/usage/operations/conversions/unitconvert.rst @@ -46,7 +46,7 @@ expected to be in units of decimalyears. This can be fixed with `unitconvert`:: Distance units ############################################################################### -In the table below all distance units supported by PROJ.4 is listed. +In the table below all distance units supported by PROJ is listed. The same list can also be produced on the command line with `proj` or `cs2cs`, by adding the `-lu` flag when calling the utility. @@ -100,7 +100,7 @@ by adding the `-lu` flag when calling the utility. Time units ############################################################################### -In the table below all time units supported by PROJ.4 is listed. +In the table below all time units supported by PROJ is listed. +--------------+-----------------------------+ | mjd | Modfied Julian date | diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst index d78f8947d6..87bfdc4033 100644 --- a/docs/source/usage/operations/index.rst +++ b/docs/source/usage/operations/index.rst @@ -4,11 +4,11 @@ Coordinate operations ================================================================================ -Coordinate operations in PROJ.4 are divided into three groups: +Coordinate operations in PROJ are divided into three groups: Projections, conversions and transformations. Projections are purely cartographic mappings of the sphere onto the plane. Technically projections are conversions (according to ISO standards), though in -PROJ.4 projections are distinguished from conversions. Conversions are coordinate +PROJ projections are distinguished from conversions. Conversions are coordinate operations that do not exert a change in reference frame. Operations that do exert a change in reference frame are called transformations. diff --git a/docs/source/usage/operations/projections/geos.rst b/docs/source/usage/operations/projections/geos.rst index 3b24e1f7d6..28b967362d 100644 --- a/docs/source/usage/operations/projections/geos.rst +++ b/docs/source/usage/operations/projections/geos.rst @@ -66,7 +66,7 @@ This example represents the scanning geometry of the Meteosat series satellite. However, the GOES satellite series use the opposite scanning geometry, with the E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle axis. -The sweep argument is used to tell PROJ.4 which on which axis the outer-gimbal +The sweep argument is used to tell PROJ which on which axis the outer-gimbal is rotating. The possible values are x or y, y being the default. Thus, the scanning geometry of the Meteosat series satellite should take sweep as x, and GOES should take sweep as y. diff --git a/docs/source/usage/operations/projections/index.rst b/docs/source/usage/operations/projections/index.rst index f7eb0c67e1..904dc9e6da 100644 --- a/docs/source/usage/operations/projections/index.rst +++ b/docs/source/usage/operations/projections/index.rst @@ -5,7 +5,7 @@ Projections ================================================================================ Projections are coordinate operations that are technically conversions but since -projections are so fundamental to PROJ.4 we differentiate them from conversions. +projections are so fundamental to PROJ we differentiate them from conversions. Projections map the spherical 3D space to a flat 2D space. diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst index a9690260f5..7f3c9895b1 100644 --- a/docs/source/usage/operations/transformations/hgridshift.rst +++ b/docs/source/usage/operations/transformations/hgridshift.rst @@ -30,7 +30,7 @@ of the continental US, Alaska and Canada is loaded at the same time:: +hgridshift +grids=@conus,@alaska,@ntv2_0.gsb,@ntv_can.dat The ``@`` in the above example states that the grid is optional, in case the grid -is not found in the PROJ.4 search path. The list of grids is prioritized so that +is not found in the PROJ search path. The list of grids is prioritized so that grids in the start of the list takes presedence over the grids in the back of the list. diff --git a/docs/source/usage/operations/transformations/vgridshift.rst b/docs/source/usage/operations/transformations/vgridshift.rst index 31b3e56e87..e9f7831056 100644 --- a/docs/source/usage/operations/transformations/vgridshift.rst +++ b/docs/source/usage/operations/transformations/vgridshift.rst @@ -32,7 +32,7 @@ the global model:: +vgridshift +grids=@dvr90.gtx,egm96_16.gtx The ``@`` in the above example states that the grid is optional, in case the grid -is not found in the PROJ.4 search path. The list of grids is prioritized so that +is not found in the PROJ search path. The list of grids is prioritized so that grids in the start of the list takes presedence over the grids in the back of the list. diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst index 8f0b358698..645c1eb138 100644 --- a/docs/source/usage/projections.rst +++ b/docs/source/usage/projections.rst @@ -4,12 +4,12 @@ Cartographic projection ================================================================================ -The foundation of PROJ.4 is the large number of +The foundation of PROJ is the large number of :doc:`projections` available in the library. This section is devoted to the generic parameters that can be used on any projection in the -PROJ.4 library. +PROJ library. -Below is a list of PROJ.4 parameters which can be applied to most coordinate +Below is a list of PROJ 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`. @@ -76,7 +76,7 @@ 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`` +By default PROJ 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` diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst index 96bfbba1fe..2cf66122f8 100644 --- a/docs/source/usage/quickstart.rst +++ b/docs/source/usage/quickstart.rst @@ -4,7 +4,7 @@ Quick start ================================================================================ -Coordinate transformations are defined by, what in PROJ.4 terminology is +Coordinate transformations are defined by, what in PROJ 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 @@ -22,7 +22,7 @@ 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` 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 +projection in PROJ is identified by a shorthand such as ``merc`` in the above example. By using the above projection definition as parameters for the command line @@ -43,7 +43,7 @@ the utility, for instance by using the ``echo`` command: 3399483.80 752085.60 -PROJ.4 also comes bundled with the ``cs2cs`` utility which is used to transform +PROJ 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``: diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst index 9a2028792b..7a1dea8be6 100644 --- a/docs/source/usage/resource_files.rst +++ b/docs/source/usage/resource_files.rst @@ -5,7 +5,7 @@ Resource files ================================================================================ A number of files containing preconfigured transformations and default parameters -for certain projections are bundled with the PROJ.4 distribution. Init files +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 projections. @@ -21,8 +21,8 @@ it easy to transformations between any two coordinate reference systems with have to follow the *cs2cs* paradigm where WGS84 is used as a pivot datum. The ITRF init file is a good example of that. -A number of init files come pre-bundled with PROJ.4 but it is also possible to -add your own custom init files. PROJ.4 looks for the init files in the directoty +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 directoty listed in the ``PROJ_LIB`` environment variable. The format of init files made up of a identifier in angled brackets and a @@ -84,7 +84,7 @@ which then expands to +epoch=2000.0 +transpose +tobs=2010.5 -Below is a list of the init files that are packaged with PROJ.4. +Below is a list of the init files that are packaged with PROJ. ======== ================================================================ Name Description @@ -108,12 +108,12 @@ Below is a list of the init files that are packaged with PROJ.4. Defaults file ------------------------------------------------------------------------------- -The ``proj_def.dat`` file supplies default parameters for PROJ.4. It uses the same +The ``proj_def.dat`` file supplies default parameters for PROJ. It uses the same syntax as the init files described above. The identifiers in the defaults file describe to what the parameters should apply. If the ```` identifier is used, then all parameters in that section applies for all proj-strings. Otherwise the identifier is connected to a specific projection. With the defaults file -supplied with PROJ.4 the default ellipsoid is set to WGS84 (for all proj-strings). +supplied with PROJ the default ellipsoid is set to WGS84 (for all proj-strings). Apart from that only the Albers Equal Area, :doc:`Lambert Conic Conformal` and the :doc:`Lagrange` projections have default parameters. diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst index 98e607a78d..2f5ee88085 100644 --- a/docs/source/usage/transformation.rst +++ b/docs/source/usage/transformation.rst @@ -4,17 +4,17 @@ Geodetic transformation ================================================================================ -PROJ.4 can do everything from the most simple projection to very complex +PROJ 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 +tool for cartographic projections, PROJ 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* +In PROJ, 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 +and limited, framework for doing geodetic transforms in PROJ 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]_. @@ -60,7 +60,7 @@ of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeli 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 +(note: "projection" is the, slightly misleading, PROJ 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 @@ -69,7 +69,7 @@ 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 +the itroduction). In PROJ it can be implemented as :: @@ -108,7 +108,7 @@ deprecated system with decimeter level tensions. 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 +possible by leveraging the time dimension in PROJ 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 @@ -209,8 +209,8 @@ 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 +PROJ 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 ``nad2bin`` program), NTv1 (the old Canadian format), and NTv2 (``.gsb`` - the new Canadian and Australian format). From c7398bd44d47ac824bb7f81bfdfe60fff3b9b675 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 23:54:30 +0100 Subject: [PATCH 36/43] Added background info to API migration guide [skip ci]. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brazenly stolen from mailing list post by Thomas Knudsen [0] and modified slightly to fit the context. [0] http://lists.maptools.org/pipermail/proj/2018-February/007995.html --- docs/source/development/migration.rst | 62 +++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 3 deletions(-) diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst index d9014a366d..eb509bcfd1 100644 --- a/docs/source/development/migration.rst +++ b/docs/source/development/migration.rst @@ -7,12 +7,69 @@ Version 4 to 5 API Migration This is a transition guide for developers wanting to migrate their code to use PROJ version 5. -The difference between the old and new API is best shown with examples. Below + +Background +############################################################################### + +Before we go on, a bit of background is needed. The new API takes a different +view of the world than the old because it is needed in order to obtain high +accuracy transformations. The old API is constructed in such a way that any transformation +between two coordinate reference systems *must* pass through the ill-defined +WGS84 reference frame, using it as a hub. The new API does away with this limitation to +transformations in PROJ. It is still possible to do that type of transformations +but in many cases there will be a better alternative. + +The world view represented by the old API is always sufficient if all you care about is +meter level accuracy - and in many cases it will provide much higher accuracy +than that. But the view that “WGS84 is the *true* foundation of the world, and +everything else can be transformed natively to and from WGS84” is inherently flawed. + +First and foremost because any time WGS84 is mentioned, you should ask yourself +“Which of the six WGS84 realizations are we talking about here?”. + +Second, because for many (especially legacy) systems, it may not be straightforward +to transform to WGS84 (or actually ITRF-something, ETRS-something or NAD-something +which appear to be the practical meaning of the term WGS84 in everyday PROJ related +work), while centimeter-level accurate transformations may exist between pairs of +older systems. + +The concept of a hub reference frame (“datum”) is not inherently bad, but in many +cases you need to handle and select that datum with more care than the old API allows. +The primary aim of the new API is to allow just that. And to do that, you must realize +that the world is inherently 4 dimensional. You may in many cases assume one or more of +the coordinates to be constant, but basically, to obtain geodetic accuracy transformations, +you need to work in 4 dimensions. + +Now, having described the background for introducing the new API, let's try to show +how to use it. First note that in order to go from system A to system B, the old API +starts by doing an **inverse** transformation from system A to WGS84, then does a +**forward** transformation from WGS84 to system B. + +With ``cs2cs`` being the command line interface to the old API, and ``cct`` being the same +for the new, this example of doing the same thing in both world views will should give +an idea of the differences: + +:: + + $ echo 300000 6100000 | cs2cs +proj=utm +zone=33 +ellps=GRS80 +to +proj=utm +zone=32 +ellps=GRS80 + 683687.87 6099299.66 0.00 + + + $ echo 300000 6100000 0 0 | cct +proj=pipeline +step +inv +proj=utm +zone=33 +ellps=GRS80 +step +proj=utm +zone=32 +ellps=GRS80 + 683687.8667 6099299.6624 0.0000 0.0000 + +Lookout for the ``+inv`` in the first ``+step``, indicating an inverse transform. + + +Code example +############################################################################### + +The difference between the old and new API is shown here with a few examples. Below we implement the same program with the two different API's. The program reads input latitude and longitude from the command line and convert them to projected coordinates with the Mercator projection. -We start by writing the progran for PROJ v. 4: +We start by writing the program for PROJ v. 4: .. code-block:: C @@ -92,7 +149,6 @@ the destination. This is simple at a glance, but is actually a big conceptual change. We are now focused on the path between two systems instead of what the source and destination systems are. - Function mapping from old to new API ############################################################################### From 0ddbb3612928bf88eac686360a58ca5a9ac14b51 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 23 Feb 2018 12:13:01 +0100 Subject: [PATCH 37/43] datatypes.rst: linuistics + INFO datatypes Some minor linguistic corrections + general update to make the documentation reflect the updates in PR #775 --- .../development/reference/datatypes.rst | 79 ++++++++++--------- 1 file changed, 40 insertions(+), 39 deletions(-) diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index f2f1d9c9f5..7f2c4b417c 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -4,7 +4,7 @@ Data types ================================================================================ -This section describe the multiplude of data types in use in PROJ.4. As a rule +This section describes the numerous data types in use in PROJ.4. As a rule of thumb PROJ.4 data types are prefixed with ``PJ_``, or in one particular case, is simply called :c:type:`PJ`. A few notable exceptions can be traced back to the very early days of PROJ.4 when the ``PJ_`` prefix was not @@ -16,8 +16,8 @@ Transformation objects .. c:type:: PJ Object containing everything related to a given projection or transformation. - As a user of the PROJ.4 library your are only exposed to pointers to this - object and the contents are hidden in the public API. :c:type:`PJ` objects + As a user of the PROJ.4 library you are only exposed to pointers to this + object and the contents is hidden behind the public API. :c:type:`PJ` objects are created with :c:func:`proj_create` and destroyed with :c:func:`proj_destroy`. @@ -51,7 +51,7 @@ Transformation objects .. c:type:: PJ_CONTEXT - Context objects enables safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` + Context objects enable safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` object is connected to a context (if not specified, the default context is used). All operations within a context should be performed in the same thread. :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` @@ -97,11 +97,11 @@ Various 2-dimensional coordinate data types. typedef struct { double x, y; } PJ_XY; - .. c:member:: double PJ_XY.lam + .. c:member:: double PJ_XY.x Easting. - .. c:member:: double PJ_XY.phi + .. c:member:: double PJ_XY.y Northing. @@ -134,7 +134,7 @@ types above. .. c:type:: PJ_LPZ 3-dimensional version of :c:type:`PJ_LP`. Holds longitude, latitude and - vertical component. + a vertical component. .. code-block:: C @@ -163,15 +163,15 @@ types above. .. c:member:: double PJ_XYZ.x - Easting. + Easting or the X component of a 3D cartesian system. .. c:member:: double PJ_XYZ.y - Northing. + Northing or the Y component of a 3D cartesian system. .. c:member:: double PJ_XYZ.z - Vertical component. + Vertical component or the Z component of a 3D cartesian system. .. c:type:: PJ_UVW @@ -249,15 +249,15 @@ domain. .. c:member:: double PJ_XYZT.x - Easting. + Easting or the X component of a 3D cartesian system. .. c:member:: double PJ_XYZT.y - Northing. + Northing or the Y component of a 3D cartesian system. .. c:member:: double PJ_XYZT.z - Vertical component. + Vertical or the Z component of a 3D cartesian system. .. c:member:: double PJ_XYZT.t @@ -320,7 +320,7 @@ Complex coordinate types .. c:type:: PJ_COORD - General purpose coordinate union type usefull in two, three and four dimensions. + General purpose coordinate union type, applicable in two, three and four dimensions. This is the default coordinate datatype used in PROJ. .. code-block:: C @@ -385,9 +385,7 @@ Projection derivatives .. c:type:: PJ_FACTORS Various cartographic properties, such as scale factors, angular distortion - and meridian convergence. Calculated with :c:func:`proj_factors`. Depending - on the underlying projection, values can be calculated either numerically - or analytically. + and meridian convergence. Calculated with :c:func:`proj_factors`. .. code-block:: C @@ -434,13 +432,15 @@ Projection derivatives Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. Sometimes also described as *grid declination*. + .. c:member:: double PJ_FACTORS.tissot_semimajor - Maximum scale error. + Maximum scale factor. .. c:member:: double PJ_FACTORS.tissot_semiminor - Minimum scale error. + Minimum scale factor. + .. c:member:: double PJ_FACTORS.dx_dlam @@ -449,7 +449,6 @@ Projection derivatives .. c:member:: double PJ_FACTORS.dy_dlam - Partial derivative :math:`\frac{\partial y}{\partial \lambda}` of coordinate :math:`\left(\lambda,\phi\right)`. @@ -460,7 +459,6 @@ Projection derivatives .. c:member:: double PJ_FACTORS.dy_dphi - Partial derivative :math:`\frac{\partial y}{\partial \phi}` of coordinate :math:`\left(\lambda,\phi\right)`. @@ -580,20 +578,20 @@ Info structures .. code-block:: C typedef struct { - char release[64]; - char version[64]; - int major; - int minor; - int patch; - char searchpath[512]; + int major; + int minor; + int patch; + const char *release; + const char *version; + const char *searchpath; } PJ_INFO; - .. c:member:: char PJ_INFO.release[64] + .. c:member:: const char *PJ_INFO.release Release info. Version number and release date, e.g. "Rel. 4.9.3, 15 August 2016". - .. c:member:: char PJ_INFO.version[64] + .. c:member:: const char *PJ_INFO.version Text representation of the full version number, e.g. "4.9.3". @@ -610,7 +608,7 @@ Info structures Patch level of release. - .. c:member:: char PJ_INFO.searchpath[512] + .. c:member:: const char PJ_INFO.searchpath Search path for PROJ. List of directories separated by semicolons (Windows) or colons (non-Windows), e.g. @@ -620,29 +618,32 @@ Info structures .. c:type:: PJ_PROJ_INFO Struct holding information about a :c:type:`PJ` object. Populated by - :c:func:`proj_pj_info`. + :c:func:`proj_pj_info`. The :c:type:`PJ_PROJ_INFO` object provides a + view into the internals of a :c:type:`PJ`, so once the :c:type:`PJ` + is destroyed or otherwise becomes invalid, so does the + :c:type:`PJ_PROJ_INFO` .. code-block:: C typedef struct { - char id[16]; - char description[128]; - char definition[512]; - int has_inverse; - double accuracy; + const char *id; + const char *description; + const char *definition; + int has_inverse; + double accuracy; } PJ_PROJ_INFO; - .. c:member:: char PJ_PROJ_INFO.id[16] + .. c:member:: const char *PJ_PROJ_INFO.id Short ID of the operation the :c:type:`PJ` object is based on, that is, what comes afther the ``+proj=`` in a proj-string, e.g. "*merc*". - .. c:member:: char PJ_PROJ_INFO.description[128] + .. c:member:: const char *PJ_PROJ_INFO.description Long describes of the operation the :c:type:`PJ` object is based on, e.g. "*Mercator Cyl, Sph&Ell lat_ts=*". - .. c:member:: char PJ_PROJ_INFO.definition[512] + .. c:member:: const char *PJ_PROJ_INFO.definition The proj-string that was used to create the :c:type:`PJ` object with, e.g. "*+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84*". From 79abf9e27f12b1253832ac19cce957e2e3680bca Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Tue, 27 Feb 2018 09:30:10 +0100 Subject: [PATCH 38/43] Wrong URL for i-cubed --- docs/source/grids.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/grids.rst b/docs/source/grids.rst index b3a551d748..612183a49d 100644 --- a/docs/source/grids.rst +++ b/docs/source/grids.rst @@ -42,7 +42,7 @@ that. HARN -------------------------------------------------------------------------------- -With the support of `i-cubed `__, Frank Warmerdam has +With the support of `i-cubed `__, 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 `__ From fbf8415e832790127c878aedefd796a75193b6a8 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Tue, 27 Feb 2018 15:12:31 +0100 Subject: [PATCH 39/43] Add usage description for the cct program --- docs/source/usage/apps/cct.rst | 138 +++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/source/usage/apps/cct.rst diff --git a/docs/source/usage/apps/cct.rst b/docs/source/usage/apps/cct.rst new file mode 100644 index 0000000000..e6f9452687 --- /dev/null +++ b/docs/source/usage/apps/cct.rst @@ -0,0 +1,138 @@ +.. _cct: + +================================================================================ +cct +================================================================================ + + +.. Index:: cct + + + + +``cct`` a 4D equivalent to the ``proj`` projection +program, performs transformation coordinate systems 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. + +cct is an acromyn meaning *Coordinate Conversion and Transformation*. + +The acronym refers to definitions given in the OGC 08-015r2/ISO-19111 +standard "Geographical Information -- Spatial Referencing by Coordinates", +which defines two different classes of *coordinate operations*: + +*Coordinate Conversions*, which are coordinate operations where input +and output datum are identical (e.g. conversion from geographical to +cartesian coordinates) and + +*Coordinate Transformations*, which are coordinate operations where +input and output datums differ (e.g. change of reference frame). + +``cct``, however, also refers to Carl Christian Tscherning (1942--2014), +professor of Geodesy at the University of Copenhagen, mentor and advisor +for a generation of Danish geodesists, colleague and collaborator for +two generations of global geodesists, Secretary General for the +International Association of Geodesy, IAG (1995--2007), fellow of the +Amercan Geophysical Union (1991), recipient of the IAG Levallois Medal +(2007), the European Geosciences Union Vening Meinesz Medal (2008), and +of numerous other honours. + +cct, or Christian, as he was known to most of us, was recognized for his +good mood, his sharp wit, his tireless work, and his great commitment to +the development of geodesy -- both through his scientific contributions, +comprising more than 250 publications, and by his mentoring and teaching +of the next generations of geodesists. + +As Christian was an avid Fortran programmer, and a keen Unix connoiseur, +he would have enjoyed to know that his initials would be used to name a +modest Unix style transformation filter, hinting at the tireless aspect +of his personality, which was certainly one of the reasons he accomplished +so much, and meant so much to so many people. + +Hence, in honour of cct (the geodesist) this is cct (the program). + + + +Synopsis +******** + +:: + + cct [ -cotvz [ args ] ]... +opts[=arg]... file... + +Description +*********** +The following control parameters can appear in any order: + +:: + + -c x,y,z,t + --columns=x,y,z,t + Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4 + + -o + --output= + Specify the name of the output file. + + -t