From 7ea472f54849f3230d5865884ef75c4edcda3fa8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 28 Aug 2017 08:07:48 +0200 Subject: 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/cs2cs.rst | 145 ----------- docs/source/apps/geod.rst | 173 ------------- docs/source/apps/index.rst | 27 --- docs/source/apps/proj.rst | 164 ------------- 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 | 143 +++++++++++ docs/source/usage/apps/geod.rst | 170 +++++++++++++ docs/source/usage/apps/index.rst | 20 ++ docs/source/usage/apps/proj.rst | 164 +++++++++++++ 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 ++++++++++++++++++++++++ 19 files changed, 1119 insertions(+), 990 deletions(-) delete mode 100644 docs/source/apps/cs2cs.rst delete mode 100644 docs/source/apps/geod.rst delete mode 100644 docs/source/apps/index.rst delete mode 100644 docs/source/apps/proj.rst delete mode 100644 docs/source/parameters.rst create mode 100644 docs/source/usage/apps/cs2cs.rst create mode 100644 docs/source/usage/apps/geod.rst create mode 100644 docs/source/usage/apps/index.rst create mode 100644 docs/source/usage/apps/proj.rst 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 (limited to 'docs/source') diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst deleted file mode 100644 index ae8016fe..00000000 --- a/docs/source/apps/cs2cs.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. _cs2cs: - -================================================================================ -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. - - -Synopsis -******** - -:: - - cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s] - -Description -*********** -The following control parameters can appear in any order: - -:: - - -I method to specify inverse translation, convert from +to coordinate system to the - primary coordinate system defined. - - -ta A specifies a character employed as the first character to denote a control line - to be passed through without processing. This option applicable to ascii input - only. (# is the default value). - - -e string - String is an arbitrary string to be output if an error is detected during data - transformations. The default value is: *\t*. Note that if the -b, -i or -o - options are employed, an error is returned as HUGE_VAL value for both - return values. - - -E causes the input coordinates to be copied to the output line prior to printing the - converted values. - - -l[p|P|=|e|u|d]id - List projection identifiers with -l, -lp or -lP (expanded) that can be selected - with +proj. -l=id gives expanded description of projection id. List - ellipsoid identifiers with -le, that can be selected with +ellps,-lu list of - cartesian to meter conversion factors that can be selected with +units or -ld - list of datums that can be selected with +datum. - - -r This options reverses the order of the expected input from longitude-latitude or - x-y to latitude-longitude or y-x. - - -s This options reverses the order of the output from x-y or longitude-latitude to - y-x or latitude-longitude. - - -f format - Format is a printf format string to control the form of the output values. For - inverse projections, the output will be in degrees when this option is employed. - If a format is specified for inverse projection the output data will be in deci- - mal degrees. The default format is "%.2f" for forward projection and DMS for - inverse. - - -[w|W]n - N is the number of significant fractional digits to employ for seconds output (when - the option is not specified, -w3 is assumed). When -W is employed the fields - will be constant width and with leading zeroes. - - -v causes a listing of cartographic control parameters tested for and used by the - program to be printed prior to input data. - -The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with -projection and for a complete description consult the `projection pages <../projections/index.html>`_ - -The cs2cs program requires two coordinate system -definitions. The first (or primary is defined -based on all projection parameters not appearing -after the +to argument. All projection parameters -appearing after the ``+to`` argument are considered -the definition of the second coordinate -system. If there is no second coordinate system -defined, a geographic coordinate system based on -the datum and ellipsoid of the source coordinate -system is assumed. Note that the source and -destination coordinate system can both be projections, -both be geographic, or one of each and -may have the same or different datums. - -Additional projection control parameters may be -contained in two auxiliary control files: the -first is optionally referenced with the -``+init=file:id`` and the second is always processed -after the name of the projection has been established -from either the run-line or the contents -of ``+init`` file. The environment parameter -PROJ_LIB establishes the default directory for a -file reference without an absolute path. This -is also used for supporting files like datum -shift files. - -One or more files (processed in left to right -order) specify the source of data to be transformed. -A - will specify the location of processing standard input. -If no files are specified, the input is assumed to be from stdin. -For input data the two data values must be in -the first two white space separated fields and -when both input and output are ASCII all trailing -portions of the input line are appended to -the output line. - -Input geographic data (longitude and latitude) -must be in DMS or decimal degrees format and -input cartesian data must be in units consistent -with the ellipsoid major axis or sphere radius -units. Output geographic coordinates will normally -be in DMS format (use ``-f %.12f`` for decimal -degrees with 12 decimal places), while projected -(cartesian) coordinates will be in linear -(meter, feet) units. - - -Example -******* -The following script - -:: - - cs2cs +proj=latlong +datum=NAD83 - +to +proj=utm +zone=10 +datum=NAD27 - -r < [ -afFIlptwW [ args ] ] [ +args ] file[s] - - invgeod +ellps= [ -afFIlptwW [ args ] ] [ +args ] file[s] - -Description -*********** -The following command-line options can appear in any order: - -:: - - -I Specifies that the inverse geodesic computation is to be - performed. May be used with execution of geod as an - alternative to invgeod execution. - - -a Latitude and longitudes of the initial and terminal - points, forward and back azimuths and distance are output. - - -ta A specifies a character employed as the first character - to denote a control line to be passed through without - processing. - - -le Gives a listing of all the ellipsoids that may be - selected with the +ellps= option. - - -lu Gives a listing of all the units that may be selected - with the +units= option. - - -[f|F] format - Format is a printf format string to control the output - form of the geographic coordinate values (f) or distance - value (F). The default mode is DMS for geographic - coordinates and "%.3f" for distance. - - -[w|W]n - N is the number of significant fractional digits to - employ for seconds output (when the option is not - specified, -w3 is assumed). When -W is employed the fields - will be constant width with leading zeroes. - - -p This option causes the azimuthal values to be output as - unsigned DMS numbers between 0 and 360 degrees. Also - note -f. - -The ``+args`` command-line options are associated with geodetic -parameters for specifying the ellipsoidal or sphere to use. -See ``proj`` `documentation `_ for full list of these parameters and -controls. The options are processed in left to right order -from the command line. Reentry of an option is ignored with -the first occurrence assumed to be the desired value. - -One or more files (processed in left to right order) specify -the source of data to be transformed. A - will specify the -location of processing standard input. If no files are specified, -the input is assumed to be from stdin. - -For direct determinations input data must be in latitude, longitude, -azimuth and distance order and output will be latitude, -longitude and back azimuth of the terminus point. Latitude, -longitude of the initial and terminus point are input for the -inverse mode and respective forward and back azimuth from the -initial and terminus points are output along with the distance -between the points. - -Input geographic coordinates (latitude and longitude) and -azimuthal data must be in decimal degrees or DMS format and -input distance data must be in units consistent with the ellipsoid -major axis or sphere radius units. The latitude must lie -in the range [-90d,90d]. Output geographic coordinates will be -in DMS (if the -f switch is not employed) to 0.001" with trailing, -zero-valued minute-second fields deleted. Output distance -data will be in the same units as the ellipsoid or sphere -radius. - -The Earth's ellipsoidal figure may be selected in the same manner -as program ``proj`` by using ``+ellps=``, ``+a=``, ``+es=``, etc. - -Geod may also be used to determine intermediate points along -either a geodesic line between two points or along an arc of -specified distance from a geographic point. In both cases an -initial point must be specified with ``+lat_1=lat`` and ``+lon_1=lon`` -parameters and either a terminus point ``+lat_2=lat`` and -``+lon_2=lon`` or a distance and azimuth from the initial point -with ``+S=distance`` and ``+A=azimuth`` must be specified. - -If points along a geodesic are to be determined then either -``+n_S=integer`` specifying the number of intermediate points -and/or ``+del_S=distance`` specifying the incremental distance -between points must be specified. - -To determine points along an arc equidistant from the initial -point both ``+del_A=angle`` and ``+n_A=integer`` must be specified -which determine the respective angular increments and number of -points to be determined. - -Examples -******** - -The following script determines the geodesic azimuths and distance in U.S. -statute miles from Boston, MA, to Portland, OR: - -:: - - geod +ellps=clrk66 <`_ - -#. `C. F. F. Karney, Algorithms for Geodesics, J. Geodesy 87, 43-55 (2013) `_. - `Addendum `_ - -#. `The online geodesic bibliography `_ - - diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst deleted file mode 100644 index 1baaf1c5..00000000 --- a/docs/source/apps/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _apps: - -================================================================================ -Applications -================================================================================ - -The proj program is limited to converting -between geographic and projection coordinates -within one datum. - -The cs2cs program operates similarly, but allows -translation between any pair of definable coor- -dinate systems, including support for datum -translation. - -The geod program provides the ability to compute -geodesic (Great Circle) computations. - - - -.. toctree:: - :maxdepth: 1 - - proj - cs2cs - geod - diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst deleted file mode 100644 index a06df383..00000000 --- a/docs/source/apps/proj.rst +++ /dev/null @@ -1,164 +0,0 @@ -:. _proj: - -================================================================================ -proj -================================================================================ - - -.. Index:: proj - -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. - - -Synopsis -******** -:: - - proj [ -bcCeEfiIlmorsStTvVwW [ args ] ] [ +args ] file[s] - invproj [ -bcCeEfiIlmorsStTwW [ args ] ] [ +args ] file[s] - - -Description -*********** -The following control parameters can appear in any order - -:: - - -b Special option for binary coordinate data input and output through standard input - and standard output. Data is assumed to be in system type double floating point - words. This option is to be used when proj is a son process and allows bypassing - formatting operations. - - -i Selects binary input only (see -b option). - - -C Check. Invoke all built in self tests and report. Get more verbose report by - preceding with the -V option). - - -I alternate method to specify inverse projection. Redundant when used with invproj. - - -o Selects binary output only (see -b option). - - -ta A specifies a character employed as the first character to denote a control line - to be passed through without processing. This option applicable to ascii input - only. (# is the default value). - - -e string - String is an arbitrary string to be output if an error is detected during data - transformations. The default value is: *\t*. Note that if the -b, -i or -o - options are employed, an error is returned as HUGE_VAL value for both return values. - - -E causes the input coordinates to be copied to the output line prior to printing the - converted values. - - - -l[p|P|=|e|u|d]id - List projection identifiers with -l, -lp or -lP (expanded) that can be selected - with +proj. -l=id gives expanded description of projection id. List - ellipsoid identifiers with -le, that can be selected with +ellps, -lu list of - cartesian to meter conversion factors that can be selected with +units or -ld - list of datums that can be selected with +datum. - - -r This options reverses the order of the expected input from longitude-latitude or - x-y to latitude-longitude or y-x. - - -s This options reverses the order of the output from x-y or longitude-latitude to - y-x or latitude-longitude. - - -S Causes estimation of meridinal and parallel scale factors, area scale factor and - angular distortion, and maximum and minimum scale factors to be listed between <> - for each input point. For conformal projections meridinal and parallel scales - factors will be equal and angular distortion zero. Equal area projections will - have an area factor of 1. - - -m mult - The cartesian data may be scaled by the mult parameter. When processing data in - a forward projection mode the cartesian output values are multiplied by mult - otherwise the input cartesian values are divided by mult before inverse projection. - If the first two characters of mult are 1/ or 1: then the reciprocal value of mult - is employed. - - -f format - Format is a printf format string to control the form of the output values. For - inverse projections, the output will be in degrees when this option is employed. - The default format is "%.2f" for forward projection and DMS for inverse. - - -[w|W]n - N is the number of significant fractional digits to employ for seconds output (when - the option is not specified, -w3 is assumed). When -W is employed the fields - will be constant width and with leading zeroes. - - -v causes a listing of cartographic control parameters tested for and used by the - program to be printed prior to input data. Should not be used with the -T - option. - - -V This option causes an expanded annotated listing of the characteristics of the - projected point. -v is implied with this option. - - -T ulow,uhi,vlow,vhi,res[,umax,vmax] - This option creates a set of bivariate Chebyshev polynomial coefficients that - approximate the selected cartographic projection on stdout. The values low and - hi denote the range of the input where the u or v prefixes apply to respective - longitude-x or latitude-y depending upon whether a forward or inverse projection - is selected. Res is an integer number specifying the power of 10 precision of - the approximation. For example, a res of -3 specifies an approximation with an - accuracy better than .001. Umax, and vmax specify maximum degree of the polynomials - (default: 15). - - -The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with -projection and for a complete description consult the `projection pages <../projections/index.html>`_ - -Additional projection control parameters may be -contained in two auxiliary control files: the -first is optionally referenced with the -``+init=file:id`` and the second is always processed -after the name of the projection has been established -from either the run-line or the contents -of +init file. The environment parameter -``PROJ_LIB`` establishes the default directory for a -file reference without an absolute path. This -is also used for supporting files like datum -shift files. - -One or more files (processed in left to right -order) specify the source of data to be trans- -formed. A - will specify the location of pro- -cessing standard input. If no files are speci- -fied, the input is assumed to be from stdin. -For ASCII input data the two data values must be -in the first two white space separated fields -and when both input and output are ASCII all -trailing portions of the input line are appended -to the output line. - -Input geographic data (longitude and latitude) -must be in DMS format and input cartesian data -must be in units consistent with the ellipsoid -major axis or sphere radius units. Output geo- -graphic coordinates will be in DMS (if the -w -switch is not employed) and precise to 0.001" -with trailing, zero-valued minute-second fields -deleted. - -Example -******* -The following script - -:: - - proj +proj=utm +lon_0=112w +ellps=clrk66 - -r <`__ 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 b6f15cae..21d70947 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,13 +1,13 @@ .. _home: ****************************************************************************** -proj.4 +PROJ.4 ****************************************************************************** -proj.4 is a standard UNIX filter function which converts geographic longitude +PROJ.4 is a standard UNIX filter function which converts geographic longitude and latitude coordinates into cartesian coordinates (and vice versa), and it is a C API for software developers to include coordinate transformation in their -own software. proj.4 is maintained on `GitHub `_. +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 e4623b9a..00000000 --- a/docs/source/parameters.rst +++ /dev/null @@ -1,459 +0,0 @@ -.. _parameters: - -================================================================================ -Parameters -================================================================================ - -:Date: 01/28/2016 - -.. contents:: Contents - :depth: 3 - :backlinks: none - - -This document attempts to describe a variety of the PROJ.4 parameters which can -be applied to all, or many coordinate system definitions. This document does -not attempt to describe the parameters particular to particular projection -types. Some of these can be found in the GeoTIFF `Projections Transform List -`__. 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 26c4da08..eaf5b17e 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -4,25 +4,28 @@ References ================================================================================ +.. [AltamimiEtAl2002] Altamimi, Z., P. Sillard, and C. Boucher (2002), ITRF2000: A new release of the International Terrestrial Reference Frame for earth science applications, J. Geophys. Res., 107(B10), 2214, `doi:10.1029/2001JB000561 `__. + +.. [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/usage/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst new file mode 100644 index 00000000..675379ef --- /dev/null +++ b/docs/source/usage/apps/cs2cs.rst @@ -0,0 +1,143 @@ +.. _cs2cs: + +================================================================================ +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. + + +Synopsis +******** + +:: + + cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s] + +Description +*********** +The following control parameters can appear in any order: + +:: + + -I method to specify inverse translation, convert from +to coordinate system to the + primary coordinate system defined. + + -ta A specifies a character employed as the first character to denote a control line + to be passed through without processing. This option applicable to ascii input + only. (# is the default value). + + -e string + String is an arbitrary string to be output if an error is detected during data + transformations. The default value is: *\t*. Note that if the -b, -i or -o + options are employed, an error is returned as HUGE_VAL value for both + return values. + + -E causes the input coordinates to be copied to the output line prior to printing the + converted values. + + -l[p|P|=|e|u|d]id + List projection identifiers with -l, -lp or -lP (expanded) that can be selected + with +proj. -l=id gives expanded description of projection id. List + ellipsoid identifiers with -le, that can be selected with +ellps,-lu list of + cartesian to meter conversion factors that can be selected with +units or -ld + list of datums that can be selected with +datum. + + -r This options reverses the order of the expected input from longitude-latitude or + x-y to latitude-longitude or y-x. + + -s This options reverses the order of the output from x-y or longitude-latitude to + y-x or latitude-longitude. + + -f format + Format is a printf format string to control the form of the output values. For + inverse projections, the output will be in degrees when this option is employed. + If a format is specified for inverse projection the output data will be in deci- + mal degrees. The default format is "%.2f" for forward projection and DMS for + inverse. + + -[w|W]n + N is the number of significant fractional digits to employ for seconds output (when + the option is not specified, -w3 is assumed). When -W is employed the fields + will be constant width and with leading zeroes. + + -v causes a listing of cartographic control parameters tested for and used by the + program to be printed prior to input data. + +The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with +projection and for a complete description consult the `projection pages <../projections/index.html>`_ + +The cs2cs program requires two coordinate system +definitions. The first (or primary is defined +based on all projection parameters not appearing +after the +to argument. All projection parameters +appearing after the ``+to`` argument are considered +the definition of the second coordinate +system. If there is no second coordinate system +defined, a geographic coordinate system based on +the datum and ellipsoid of the source coordinate +system is assumed. Note that the source and +destination coordinate system can both be projections, +both be geographic, or one of each and +may have the same or different datums. + +Additional projection control parameters may be +contained in two auxiliary control files: the +first is optionally referenced with the +``+init=file:id`` and the second is always processed +after the name of the projection has been established +from either the run-line or the contents +of ``+init`` file. The environment parameter +PROJ_LIB establishes the default directory for a +file reference without an absolute path. This +is also used for supporting files like datum +shift files. + +One or more files (processed in left to right +order) specify the source of data to be transformed. +A - will specify the location of processing standard input. +If no files are specified, the input is assumed to be from stdin. +For input data the two data values must be in +the first two white space separated fields and +when both input and output are ASCII all trailing +portions of the input line are appended to +the output line. + +Input geographic data (longitude and latitude) +must be in DMS or decimal degrees format and +input cartesian data must be in units consistent +with the ellipsoid major axis or sphere radius +units. Output geographic coordinates will normally +be in DMS format (use ``-f %.12f`` for decimal +degrees with 12 decimal places), while projected +(cartesian) coordinates will be in linear +(meter, feet) units. + + +Example +******* +The following script + +:: + + cs2cs +proj=latlong +datum=NAD83 + +to +proj=utm +zone=10 +datum=NAD27 + -r < [ -afFIlptwW [ args ] ] [ +args ] file[s] + + invgeod +ellps= [ -afFIlptwW [ args ] ] [ +args ] file[s] + +Description +*********** +The following command-line options can appear in any order: + +:: + + -I Specifies that the inverse geodesic computation is to be + performed. May be used with execution of geod as an + alternative to invgeod execution. + + -a Latitude and longitudes of the initial and terminal + points, forward and back azimuths and distance are output. + + -ta A specifies a character employed as the first character + to denote a control line to be passed through without + processing. + + -le Gives a listing of all the ellipsoids that may be + selected with the +ellps= option. + + -lu Gives a listing of all the units that may be selected + with the +units= option. + + -[f|F] format + Format is a printf format string to control the output + form of the geographic coordinate values (f) or distance + value (F). The default mode is DMS for geographic + coordinates and "%.3f" for distance. + + -[w|W]n + N is the number of significant fractional digits to + employ for seconds output (when the option is not + specified, -w3 is assumed). When -W is employed the fields + will be constant width with leading zeroes. + + -p This option causes the azimuthal values to be output as + unsigned DMS numbers between 0 and 360 degrees. Also + note -f. + +The ``+args`` command-line options are associated with geodetic +parameters for specifying the ellipsoidal or sphere to use. +See ``proj`` `documentation `_ for full list of these parameters and +controls. The options are processed in left to right order +from the command line. Reentry of an option is ignored with +the first occurrence assumed to be the desired value. + +One or more files (processed in left to right order) specify +the source of data to be transformed. A - will specify the +location of processing standard input. If no files are specified, +the input is assumed to be from stdin. + +For direct determinations input data must be in latitude, longitude, +azimuth and distance order and output will be latitude, +longitude and back azimuth of the terminus point. Latitude, +longitude of the initial and terminus point are input for the +inverse mode and respective forward and back azimuth from the +initial and terminus points are output along with the distance +between the points. + +Input geographic coordinates (latitude and longitude) and +azimuthal data must be in decimal degrees or DMS format and +input distance data must be in units consistent with the ellipsoid +major axis or sphere radius units. The latitude must lie +in the range [-90d,90d]. Output geographic coordinates will be +in DMS (if the -f switch is not employed) to 0.001" with trailing, +zero-valued minute-second fields deleted. Output distance +data will be in the same units as the ellipsoid or sphere +radius. + +The Earth's ellipsoidal figure may be selected in the same manner +as program ``proj`` by using ``+ellps=``, ``+a=``, ``+es=``, etc. + +Geod may also be used to determine intermediate points along +either a geodesic line between two points or along an arc of +specified distance from a geographic point. In both cases an +initial point must be specified with ``+lat_1=lat`` and ``+lon_1=lon`` +parameters and either a terminus point ``+lat_2=lat`` and +``+lon_2=lon`` or a distance and azimuth from the initial point +with ``+S=distance`` and ``+A=azimuth`` must be specified. + +If points along a geodesic are to be determined then either +``+n_S=integer`` specifying the number of intermediate points +and/or ``+del_S=distance`` specifying the incremental distance +between points must be specified. + +To determine points along an arc equidistant from the initial +point both ``+del_A=angle`` and ``+n_A=integer`` must be specified +which determine the respective angular increments and number of +points to be determined. + +Examples +******** + +The following script determines the geodesic azimuths and distance in U.S. +statute miles from Boston, MA, to Portland, OR: + +:: + + geod +ellps=clrk66 <`_ + +#. `C. F. F. Karney, Algorithms for Geodesics, J. Geodesy 87, 43-55 (2013) `_. + `Addendum `_ + +#. `The online geodesic bibliography `_ + + diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst new file mode 100644 index 00000000..73c5c63c --- /dev/null +++ b/docs/source/usage/apps/index.rst @@ -0,0 +1,20 @@ +.. _apps: + +================================================================================ +Applications +================================================================================ + +Bundled with PROJ.4 comes a set of small command line utilities. The +``proj`` program is limited to converting between geographic and projection +coordinates within one datum. The ``cs2cs`` program operates similarly, but +allows translation between any pair of definable coordinate systems, including +support for basic datum translation. The ``geod`` program provides the ability +to do geodesic (great circle) computations. + +.. toctree:: + :maxdepth: 1 + + proj + cs2cs + geod + diff --git a/docs/source/usage/apps/proj.rst b/docs/source/usage/apps/proj.rst new file mode 100644 index 00000000..424a0fef --- /dev/null +++ b/docs/source/usage/apps/proj.rst @@ -0,0 +1,164 @@ +.. _proj: + +================================================================================ +proj +================================================================================ + + +.. Index:: proj + +``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. + + +Synopsis +******** +:: + + proj [ -bcCeEfiIlmorsStTvVwW [ args ] ] [ +args ] file[s] + invproj [ -bcCeEfiIlmorsStTwW [ args ] ] [ +args ] file[s] + + +Description +*********** +The following control parameters can appear in any order + +:: + + -b Special option for binary coordinate data input and output through standard input + and standard output. Data is assumed to be in system type double floating point + words. This option is to be used when proj is a son process and allows bypassing + formatting operations. + + -i Selects binary input only (see -b option). + + -C Check. Invoke all built in self tests and report. Get more verbose report by + preceding with the -V option). + + -I alternate method to specify inverse projection. Redundant when used with invproj. + + -o Selects binary output only (see -b option). + + -ta A specifies a character employed as the first character to denote a control line + to be passed through without processing. This option applicable to ascii input + only. (# is the default value). + + -e string + String is an arbitrary string to be output if an error is detected during data + transformations. The default value is: *\t*. Note that if the -b, -i or -o + options are employed, an error is returned as HUGE_VAL value for both return values. + + -E causes the input coordinates to be copied to the output line prior to printing the + converted values. + + + -l[p|P|=|e|u|d]id + List projection identifiers with -l, -lp or -lP (expanded) that can be selected + with +proj. -l=id gives expanded description of projection id. List + ellipsoid identifiers with -le, that can be selected with +ellps, -lu list of + cartesian to meter conversion factors that can be selected with +units or -ld + list of datums that can be selected with +datum. + + -r This options reverses the order of the expected input from longitude-latitude or + x-y to latitude-longitude or y-x. + + -s This options reverses the order of the output from x-y or longitude-latitude to + y-x or latitude-longitude. + + -S Causes estimation of meridinal and parallel scale factors, area scale factor and + angular distortion, and maximum and minimum scale factors to be listed between <> + for each input point. For conformal projections meridinal and parallel scales + factors will be equal and angular distortion zero. Equal area projections will + have an area factor of 1. + + -m mult + The cartesian data may be scaled by the mult parameter. When processing data in + a forward projection mode the cartesian output values are multiplied by mult + otherwise the input cartesian values are divided by mult before inverse projection. + If the first two characters of mult are 1/ or 1: then the reciprocal value of mult + is employed. + + -f format + Format is a printf format string to control the form of the output values. For + inverse projections, the output will be in degrees when this option is employed. + The default format is "%.2f" for forward projection and DMS for inverse. + + -[w|W]n + N is the number of significant fractional digits to employ for seconds output (when + the option is not specified, -w3 is assumed). When -W is employed the fields + will be constant width and with leading zeroes. + + -v causes a listing of cartographic control parameters tested for and used by the + program to be printed prior to input data. Should not be used with the -T + option. + + -V This option causes an expanded annotated listing of the characteristics of the + projected point. -v is implied with this option. + + -T ulow,uhi,vlow,vhi,res[,umax,vmax] + This option creates a set of bivariate Chebyshev polynomial coefficients that + approximate the selected cartographic projection on stdout. The values low and + hi denote the range of the input where the u or v prefixes apply to respective + longitude-x or latitude-y depending upon whether a forward or inverse projection + is selected. Res is an integer number specifying the power of 10 precision of + the approximation. For example, a res of -3 specifies an approximation with an + accuracy better than .001. Umax, and vmax specify maximum degree of the polynomials + (default: 15). + + +The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with +projection and for a complete description consult the `projection pages <../projections/index.html>`_ + +Additional projection control parameters may be +contained in two auxiliary control files: the +first is optionally referenced with the +``+init=file:id`` and the second is always processed +after the name of the projection has been established +from either the run-line or the contents +of +init file. The environment parameter +``PROJ_LIB`` establishes the default directory for a +file reference without an absolute path. This +is also used for supporting files like datum +shift files. + +One or more files (processed in left to right +order) specify the source of data to be trans- +formed. A - will specify the location of pro- +cessing standard input. If no files are speci- +fied, the input is assumed to be from stdin. +For ASCII input data the two data values must be +in the first two white space separated fields +and when both input and output are ASCII all +trailing portions of the input line are appended +to the output line. + +Input geographic data (longitude and latitude) +must be in DMS format and input cartesian data +must be in units consistent with the ellipsoid +major axis or sphere radius units. Output geo- +graphic coordinates will be in DMS (if the -w +switch is not employed) and precise to 0.001" +with trailing, zero-valued minute-second fields +deleted. + +Example +******* +The following script + +:: + + proj +proj=utm +lon_0=112w +ellps=clrk66 + -r <` 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 00000000..d162ace9 --- /dev/null +++ b/docs/source/usage/quickstart.rst @@ -0,0 +1,68 @@ +.. _quickstart: + +================================================================================ +Quick start +================================================================================ + +Coordinate transformations are defined by, what in PROJ.4 terminology is +known as, "proj-strings". A proj-string describes any transformation regardless of +how simple or complicated it might be. The simplest case is projection of geodetic +coordinates. This section focuses on the simpler cases and introduces the basic +anatomy of the proj-string. The complex cases are discussed in +:doc:`transformation`. + +A proj-strings holds the parameters of a given coordinate transformation, e.g. + +:: + + +proj=merc +lat_ts=56.5 +ellps=GRS80 + +I.e. a proj-string consists of a projection specifier, ``+proj``, a number of +parameters that applies to the projection and, if needed, a description of a +datum shift. In the example above geodetic coordinates are transformed to +projected space with the :doc:`Mercator projection<../projections/merc>` with +the latitude of true scale at 56.5 degrees north on the GRS80 ellipsoid. Every +projection in PROJ.4 is identified by a shorthand such as ``merc`` in the above +example. + +By using the above projection definition as parameters for the command line +utility ``proj`` we can convert the geodetic coordinates to projected space: + +:: + + $ proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + +If called as above ``proj`` will be in interactive mode, letting you type the +input data manually and getting a responce presented on screen. ``proj`` +works as any UNIX filter though, which means that you can also pipe data to +the utility, for instance by using the ``echo`` command: + +:: + + $ echo 55.2 12.2 | proj +proj=merc +lat_ts=56.5 +ellps=GRS80 + 3399483.80 752085.60 + + +PROJ.4 also comes bundled with the ``cs2cs`` utility which is used to transform +from onecoordinate reference system to another. Say we want to convert +the above Mercator coordinates to UTM, we can do that with ``cs2cs``: + +:: + + $ echo 3399483.80 752085.60 | cs2cs +proj=merc +lat_ts=56.5 +ellps=GRS80 +to +proj=utm +zone=32 + 6103992.36 1924052.47 0.00 + +Notice the ``+to`` parameter that seperates the source and destination +projection definitions. + +If you happen to know the EPSG identifiers for the two cordinates reference +systems you are transforming between you can use those with ``cs2cs``: + +:: + + $ echo 56 12 | cs2cs +init=epsg:4326 +to +init=epsg:25832 + 231950.54 1920310.71 0.00 + +In the above example we transform geodetic coordinates in the WGS84 reference +frame to UTM zone 32N coordinates in the ETRS89 reference frame. +UTM coordinates diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst new file mode 100644 index 00000000..0881cb7c --- /dev/null +++ b/docs/source/usage/resource_files.rst @@ -0,0 +1,34 @@ +.. _resource_files: + +================================================================================ +Resource files +================================================================================ + +Init files +------------------------------------------------------------------------------- + +epsg ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +nad27 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +nad83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +ITRF ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +IGNF ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +GL27 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +esri ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +Defaults file +------------------------------------------------------------------------------- + diff --git a/docs/source/usage/transformation.rst b/docs/source/usage/transformation.rst new file mode 100644 index 00000000..98e607a7 --- /dev/null +++ b/docs/source/usage/transformation.rst @@ -0,0 +1,314 @@ +.. _transformation: + +================================================================================ +Geodetic transformation +================================================================================ + +PROJ.4 can do everything from the most simple projection to very complex +transformations across many reference frames. While originally developed as a +tool for cartographic projections, PROJ.4 has over time evolved into a powerfull +generic coordinate transformation engine that makes it possible to do both +large scale cartographic projections as well as coordinate transformation at a +geodetic high precision level. This chapter delves into the details of how +geodetec transformations of varying complexity can be performed. + +In PROJ.4, two frameworks for geodetic transformations exists, the *cs2cs* +framework and the *transformation pipelines* framework. The first is the original, +and limited, framework for doing geodetic transforms in PROJ.4 The latter is a +newer addition that aims to be a more complete transformation framework. Both are +described in the sections below. Large portions of the text are based on +[EversKnudsen2017]_. + +Before describing the details of the two frameworks, let us first remark that +most cases of geodetic transformations can be expressed as a series of elementary +operations, the output of one operation being the input of the next. E.g. when +going from UTM zone 32, datum ED50, to UTM zone 32, datum ETRS89, one must, in the +simplest case, go through 5 steps: + +1. Back-project the UTM coordinates to geographic coordinates +2. Convert the geographic coordinates to 3D cartesian geocentric coordinates +3. Apply a Helmert transformation from ED50 to ETRS89 +4. Convert back from cartesian to geographic coordinates +5. Finally project the geographic coordinates to UTM zone 32 planar coordinates. + + +Transformation pipelines ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The homology between the above steps and a Unix shell style pipeline is evident. +It is there the main architectural inspiration behind the transformation pipeline +framework. The pipeline framework is realized by utilizing a special "projection", +that takes as its user supplied arguments, a series of elementary operations, +which it strings together in order to implement the full transformation needed. +Additionally, a number of elementary geodetic operations, including Helmert +transformations, general high order polynomial shifts and the Molodensky +transformation are available as part of the pipeline framework. +In anticipation of upcoming support for full time-varying transformations, we +also introduce a 4D spatiotemporal data type, and a programming interface +(API) for handling this. + +The Molodensky transformation converts directly from geodetic coordinates +in one datum, to geodetic coordinates in another datum, while the (typically more +accurate) Helmert transformation converts from 3D cartesian to 3D cartesian +coordinates. So when using the Helmert transformation one typically needs to do an +initial conversion from geodetic to cartesian coordinates, and a final conversion +the other way round, to arrive at the desired result. Fortunately, this three-step +compound transformation has the attractive characteristic that each step depends +only on the output of the immediately preceding step. Hence, we can build a +geodetic-to-geodetic Helmert transformation by tying together the outputs and inputs +of 3 steps (geodetic-to-cartesian → Helmert → cartesian-to-geodetic), pipeline style. +The pipeline driver, makes this kind of chained transformations possible. +The implementation is compact, consisting of just one pseudo-projection, called +``pipeline``, which takes as its arguments strings of elementary projections +(note: "projection" is the, slightly misleading, PROJ.4 term used for any kind of +transformation). +The pipeline pseudo projection is supplemented by a number of elementary +transformations, all in all providing a framework for building high accuracy +solutions for a wide spectrum of geodetic tasks. + + +As a first example, let us take a look at the iconic +*geodetic → Cartesian → Helmert → geodetic* case (steps 2 to 4 in the example in +the itroduction). In PROJ.4 it can be implemented as + +:: + + proj=pipeline + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + +The pipeline can be expanded at both ends to accommodate whatever coordinate type +is needed for input and output: In the example below, we transform from the +deprecated Danish System 45, a 2D system with some tension in the original defining +network, to UTM zone 33, ETRS89. The tension is reduced using a polynomial +transformation (the init=./s45b... step, s45b.pol is a file containing the +polynomial coefficients), taking the S45 coordinates to a technical coordinate +system (TC32), defined to represent "UTM zone 32 coordinates, as they would look if +the Helmert transformation between ED50 and ETRS89 was perfect". The TC32 +coordinates are then converted back to geodetic(ED50) coordinates, using an +inverse UTM projection, further to cartesian(ED50), then to cartesian(ETRS89), +using the relevant Helmert transformation, and back to geodetic(ETRS89), before +finally being projected onto the UTM zone 33, ETRS89 system. All in all a 6 step +pipeline, implementing a transformation with centimeter level accuracy from a +deprecated system with decimeter level tensions. + +:: + + proj=pipeline + step init=./s45b.pol:s45b_tc32 + step proj=utm inv ellps=intl zone=32 + step proj=cart ellps=intl + step proj=helmert + x=-81.0703 y=-89.3603 z=-115.7526 + rx=-0.48488 ry=-0.02436 rz=-0.41321 s=-0.540645 + step proj=cart inv ellps=GRS80 + step proj=utm ellps=GRS80 zone=33 + +With the pipeline framework spatiotemporal transformation is possible. This is +possible by leveraging the time dimension in PROJ.4 that enables 4D coordinates +(three spatial components and one temporal component) to be passed through a +transformation pipeline. In the example below a transformation from ITRF93 to +ITRF2000 is defined. The temporal component is given as GPS weeks in the input +data, but the 14-parameter Helmert transform expects temporal units in decimalyears. +Hence the first step in the pipeline is the unitconvert pseudo-projection that makes +sure the correct units are passed along to the Helmert transform. +Most parameters of the Helmert transform are taken from [AltamimiEtAl2002]_, +except the epoch which is the epoch of the transformation. The default setting is to +use “coordinate frame” convention of the Helmert transform, but “position vector” +convention can also be used. The last step in the pipeline is converting the +coordinate timestamps back to GPS weeks. + +:: + + proj=pipeline + step proj=unitconvert t_in=gps_week t_out=decimalyear + step proj=helmert + x=0.0127 y=0.0065 z=-0.0209 s=0.00195 + rx=0.00039 ry=-0.00080 rz=0.00114 + dx=-0.0029 dy=-0.0002 dz=-0.0006 ds=0.00001 + drx=0.00011 dry=0.00019 drz=-0.00007 + epoch=1988.0 + step proj=unitconvert t_in=decimalyear t_out=gps_week + + +cs2cs paradigm ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + ============ ============================================================== + Parameter Description + ============ ============================================================== + +datum Datum name (see ``proj -ld``) + +geoidgrids Filename of GTX grid file to use for vertical datum transforms + +nadgrids Filename of NTv2 grid file to use for datum transforms + +towgs84 3 or 7 term datum transform parameters + +to_meter Multiplier to convert map units to 1.0m + +vto_meter Vertical conversion to meters + ============ ============================================================== + +The *cs2cs* framework delivers a subset of the geodetic transformations available +with the *pipeline* framework. Coordinate transformations done in this framework +are transformed in a two-step process with WGS84 as a pivot datum That is, the +input coordinates are transformed to WGS84 geodetic coordinates and then transformed +from WGS84 coordinates to the specified output coordinate reference system, by +utilizing either the Helmert transform, datum shift grids or a combination of both. +Datum shifts can be described in a proj-string with the parameters ``+towgs84``, +``+nadgrids`` and ``+geoidgrids``. +An inverse transform exists for all three and is applied if +specified in the input proj-string. The most common is ``+towgs84``, which is used to +define a 3- or 7-parameter Helmert shift from the input reference frame to WGS84. +Exactly which realization of WGS84 is not specified, hence a fair amount of +uncertainty is introduced in this step of the transformation. With the +nadgrids +parameter a non-lineaer planar correction derived from interpolation in a +correction grid can be applied. Originally this was implemented as a means to +transform coordinates between the american datums NAD27 and NAD83, but corrections +can be applied for any datum for which a correction grid exists. The inverse +transform for the horizontal grid shift is "dumb", in the sense that the +correction grid is applied verbatim without taking into account that the inverse +operation is non-linear. Similar to the horizontal grid correction, ``+geoidgrids`` +can be used to perform grid corrections in the vertical component. +Both grid correction methods allow inclusion of more than one grid in the same +transformation + +In contrast to the *transformation pipeline* framework, transformations with the +*cs2cs* framework are expressed as two separate proj-strings. One proj-string *to* +WGS84 and one *from* WGS84. Together they form the mapping from the source +coordinate reference system to the destination coordinate reference system. +When used with the ``cs2cs`` the source and destination CRS's are separated by the +special ``+to`` parameter. + +The following example demonstrates converting from the Greek GGRS87 datum +to WGS84 with the ``+towgs84`` parameter. + +:: + + cs2cs +proj=latlong +ellps=GRS80 +towgs84=-199.87,74.79,246.62 + +to +proj=latlong +datum=WGS84 + 20 35 + 20d0'5.467"E 35d0'9.575"N 8.570 + +The EPSG database provides this example for transforming from WGS72 to WGS84 +using an approximated 7 parameter transformation. + +:: + + cs2cs +proj=latlong +ellps=WGS72 +towgs84=0,0,4.5,0,0,0.554,0.219 \ + +to +proj=latlong +datum=WGS84 + 4 55 + 4d0'0.554"E 55d0'0.09"N 3.223 + + +Grid Based Datum Adjustments ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In many places (notably North America and Austrialia) national geodetic +organizations provide grid shift files for converting between different datums, +such as NAD27 to NAD83. These grid shift files include a shift to be applied +at each grid location. Actually grid shifts are normally computed based on an +interpolation between the containing four grid points. + +PROJ.4 supports use of grid files for shifting between various reference frames. +The grid shift table formats are ctable (the binary format produced by the PROJ.4 +``nad2bin`` program), NTv1 (the old Canadian format), and NTv2 (``.gsb`` - the new +Canadian and Australian format). + +The text in this section is based on the *cs2cs* framework. Gridshifting is off +course also possible with the *pipeline* framework. The major difference between the +two is that the *cs2cs* framework is limited to grid mappings to WGS84, whereas with +*transformation pipelines* it is possible to perform grid shifts between any two +reference frames, as long as a grid exists. + +Use of grid shifts with ``cs2cs`` is specified using the ``+nadgrids`` +keyword in a coordinate system definition. For example: + +:: + + % cs2cs +proj=latlong +ellps=clrk66 +nadgrids=ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'2.952"W 50d0'0.111"N 0.000 + +In this case the ``/usr/local/share/proj/ntv1_can.dat`` grid shift file was +loaded, and used to get a grid shift value for the selected point. + +It is possible to list multiple grid shift files, in which case each will be +tried in turn till one is found that contains the point being transformed. + +:: + + cs2cs +proj=latlong +ellps=clrk66 \ + +nadgrids=conus,alaska,hawaii,stgeorge,stlrnc,stpaul \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + + +Skipping Missing Grids +................................................................................ + +The special prefix ``@`` may be prefixed to a grid to make it optional. If it +not found, the search will continue to the next grid. Normally any grid not +found will cause an error. For instance, the following would use the +``ntv2_0.gsb`` file if available (see :ref:`nonfreegrids`), otherwise it would +fallback to using the ``ntv1_can.dat`` file. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=@ntv2_0.gsb,ntv1_can.dat \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 50 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + +The null Grid +................................................................................ + +A special ``null`` grid shift file is shift with releases after 4.4.6 (not +inclusive). This file provides a zero shift for the whole world. It may be +listed at the end of a nadgrids file list if you want a zero shift to be +applied to points outside the valid region of all the other grids. Normally if +no grid is found that contains the point to be transformed an error will occur. + +:: + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 45 + EOF + 111d0'3.006"W 50d0'0.103"N 0.000 + + cs2cs +proj=latlong +ellps=clrk66 +nadgrids=conus,null \ + +to +proj=latlong +ellps=GRS80 +datum=NAD83 << EOF + -111 44 + -111 55 + EOF + 111d0'2.788"W 43d59'59.725"N 0.000 + 111dW 55dN 0.000 + +For more information see the chapter on :ref:`Grids`. + +Caveats +................................................................................ + +* Where grids overlap (such as conus and ntv1_can.dat for instance) the first + found for a point will be used regardless of whether it is appropriate or + not. So, for instance, ``+nadgrids=ntv1_can.dat``,conus would result in + the Canadian data being used for some areas in the northern United States + even though the conus data is the approved data to use for the area. + Careful selection of files and file order is necessary. In some cases + border spanning datasets may need to be pre-segmented into Canadian and + American points so they can be properly grid shifted +* There are additional grids for shifting between NAD83 and various HPGN + versions of the NAD83 datum. Use of these haven't been tried recently so + you may encounter problems. The FL.lla, WO.lla, MD.lla, TN.lla and WI.lla + are examples of high precision grid shifts. Take care! +* Additional detail on the grid shift being applied can be found by setting + the PROJ_DEBUG environment variable to a value. This will result in output + to stderr on what grid is used to shift points, the bounds of the various + grids loaded and so forth +* The *cs2cs* framework always assumes that grids contain a shift **to** NAD83 (essentially + WGS84). Other types of grids can be used with the *pipeline* framework. -- cgit v1.2.3 From 1ba5cf61d3daf24103b16915f51582b8dcb3635a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Sep 2017 15:38:27 +0200 Subject: Added documentation of init files and defaults file --- docs/source/usage/resource_files.rst | 115 ++++++++++++++++++++++++++++++----- 1 file changed, 101 insertions(+), 14 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/resource_files.rst b/docs/source/usage/resource_files.rst index 0881cb7c..e99763f1 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. + -- cgit v1.2.3 From c0aaf4c5f489b43ce5a9d0a3cc325e853d04585a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Sep 2017 18:30:02 +0200 Subject: 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(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index cbd02f10..62316eef 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 @@ source_suffix = '.rst' 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 @@ latex_elements = { # (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 @@ latex_documents = [ # 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 @@ man_pages = [ # (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 a1c2a9e0..80babcb2 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 0240df1d..48bcfafd 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 2e309241..56550159 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. -- cgit v1.2.3 From c58d26841a4a4459c1d7dabb04ea504853bd0634 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Sep 2017 21:39:54 +0200 Subject: 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 (limited to 'docs/source') diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 00000000..e7f9101e --- /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 21d70947..c70cdced 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -41,6 +41,7 @@ Documentation htpd development/index faq + contributing download glossary license -- cgit v1.2.3 From 5dc4fb39db01bf06945b063116c10af7661a7999 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 4 Sep 2017 22:32:20 +0200 Subject: 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/api.rst | 270 ----------------------- docs/source/development/errorhandling.rst | 7 + docs/source/development/index.rst | 7 +- docs/source/development/quickstart.rst | 100 +++++++++ docs/source/development/reference/datatypes.rst | 8 + docs/source/development/reference/deprecated.rst | 270 +++++++++++++++++++++++ docs/source/development/reference/functions.rst | 7 + docs/source/development/reference/index.rst | 12 + docs/source/development/threads.rst | 5 - docs/source/development/transformations.rst | 7 + 10 files changed, 416 insertions(+), 277 deletions(-) delete mode 100644 docs/source/development/api.rst 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 create mode 100644 docs/source/development/reference/deprecated.rst 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 (limited to 'docs/source') diff --git a/docs/source/development/api.rst b/docs/source/development/api.rst deleted file mode 100644 index 356f32b5..00000000 --- a/docs/source/development/api.rst +++ /dev/null @@ -1,270 +0,0 @@ -.. _api: - -******************************************************************************** -API -******************************************************************************** - -.. contents:: Contents - :depth: 3 - :backlinks: none - -Introduction ------------- - -Procedure ``pj_init()`` selects and initializes a cartographic -projection with its argument control parameters. ``argc`` is the number -of elements in the array of control strings argv that each contain -individual cartographic control keyword assignments (+ proj arguments). -The list must contain at least the proj=projection and Earth’s radius or -elliptical parameters. If the initialization of the projection is -successful a valid address is returned otherwise a NULL value. - -The ``pj_init_plus()`` function operates similarly to ``pj_init()`` but -takes a single string containing the definition, with each parameter -prefixed with a plus sign. For example -``+proj=utm +zone=11 +ellps=WGS84``. - -Once initialization is performed either forward or inverse projections -can be performed with the returned value of ``pj_init()`` used as the -argument proj. The argument structure projUV values u and v contain -respective longitude and latitude or x and y. Latitude and longitude are -in radians. If a projection operation fails, both elements of projUV are -set to ``HUGE_VAL`` (defined in ``math.h``). - -Note: all projections have a forward mode, but some do not have an -inverse projection. If the projection does not have an inverse the -projPJ structure element inv will be ``NULL``. - -The ``pj_transform`` function may be used to transform points between -the two provided coordinate systems. In addition to converting between -cartographic projection coordinates and geographic coordinates, this -function also takes care of datum shifts if possible between the source -and destination coordinate system. Unlike ``pj_fwd()`` and ``pj_inv()`` -it is also allowable for the coordinate system definitions -``(projPJ *)`` to be geographic coordinate systems (defined as -``+proj=latlong``). -The x, y and z arrays contain the input values of the points, and are replaced with the output values. -The function returns zero on success, or the error number (also in ``pj_errno``) -on failure. - -Memory associated with the projection may be freed with ``pj_free()``. - -Example -------- - -The following program reads latitude and longitude values in decimal -degress, performs Mercator projection with a Clarke 1866 ellipsoid and a -33° latitude of true scale and prints the projected cartesian values in -meters: - -.. code:: - - #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")) ) - exit(1); - if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) - exit(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); - } - exit(0); - } - - -For this program, an input of ``-16 20.25`` would give a result of -``-1495284.21 1920596.79``. - -API Functions -------------- - -pj_transform -============ - -:: - - int pj_transform( projPJ srcdefn, - projPJ dstdefn, - long point_count, - int point_offset, - double *x, - double *y, - double *z ); - - -Transform the x/y/z points from the source coordinate system to the -destination coordinate system. - -``srcdefn``: source (input) coordinate system. - -``dstdefn``: destination (output) coordinate system. - -``point_count``: the number of points to be processed (the size of the -x/y/z arrays). - -``point_offset``: the step size from value to value (measured in -doubles) within the x/y/z arrays - normally 1 for a packed array. May be -used to operate on xyz interleaved point arrays. - -``x``/``y``/``z``: The array of X, Y and Z coordinate values passed as -input, and modified in place for output. The Z may optionally be NULL. - -``return``: The return is zero on success, or a PROJ.4 error code. - -The ``pj_transform()`` function transforms the passed in list of points -from the source coordinate system to the destination coordinate system. -Note that geographic locations need to be passed in radians, not decimal -degrees, and will be returned similarly. The ``z`` array may be passed -as NULL if Z values are not available. - -If there is an overall failure, an error code will be returned from the -function. If individual points fail to transform - for instance due to -being over the horizon - then those x/y/z values will be set to -``HUGE_VAL`` on return. Input values that are ``HUGE_VAL`` will not be -transformed. - - -pj_init_plus -============ - -:: - - projPJ pj_init_plus(const char *definition); - -This function converts a string representation of a coordinate system -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:`transformation` notes for additional detail. - -Coordinate system objects allocated with ``pj_init_plus()`` should be -deallocated with ``pj_free()``. - - -pj_free -======= - -:: - - void pj_free( projPJ pj ); - -Frees all resources associated with pj. - - -pj_is_latlong -============= - -:: - - int pj_is_latlong( projPJ pj ); - -Returns TRUE if the passed coordinate system is geographic -(``proj=latlong``). - - -pj_is_geocent -============= - -:: - - int pj_is_geocent( projPJ pj );`` - -Returns TRUE if the coordinate system is geocentric (``proj=geocent``). - -pj_get_def -========== - -:: - - char *pj_get_def( projPJ pj, int options);`` - -Returns the PROJ.4 initialization string suitable for use with -``pj_init_plus()`` that would produce this coordinate system, but with -the definition expanded as much as possible (for instance ``+init=`` and -``+datum=`` definitions). - -pj_latlong_from_proj -==================== - -:: - - projPJ pj_latlong_from_proj( projPJ pj_in );`` - -Returns a new coordinate system definition which is the geographic -coordinate (lat/long) system underlying ``pj_in``. - -pj_set_finder -============== - -:: - - void pj_set_finder( const char *(*new_finder)(const char *) );`` - -Install a custom function for finding init and grid shift files. - -pj_set_searchpath -================= - -:: - - void pj_set_searchpath ( int count, const char **path );`` - -Set a list of directories to search for init and grid shift files. - - -pj_deallocate_grids -=================== - -:: - - void pj_deallocate_grids( void );`` - -Frees all resources associated with loaded and cached datum shift grids. - - -pj_strerrno -=========== - -:: - - char *pj_strerrno( int );`` - -Returns the error text associated with the passed in error code. - -pj_get_errno_ref -================ - -:: - - int *pj_get_errno_ref( void );`` - -Returns a pointer to the global pj\_errno error variable. - -pj_get_release -============== - -:: - - const char *pj_get_release( void );`` - -Returns an internal string describing the release version. - -Obsolete Functions -~~~~~~~~~~~~~~~~~~ - -``XY pj_fwd( LP lp, PJ *P );`` - -``LP pj_inv( XY xy, PJ *P );`` - -``projPJ pj_init(int argc, char **argv);`` - -.. _more info: pj_transform - diff --git a/docs/source/development/errorhandling.rst b/docs/source/development/errorhandling.rst new file mode 100644 index 00000000..58199e3f --- /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 2e6e5622..9f5c8d89 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 00000000..7137d85a --- /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 00000000..193ec238 --- /dev/null +++ b/docs/source/development/reference/datatypes.rst @@ -0,0 +1,8 @@ +.. _datatypes: + +================================================================================ +Data types +================================================================================ + + + diff --git a/docs/source/development/reference/deprecated.rst b/docs/source/development/reference/deprecated.rst new file mode 100644 index 00000000..c748d461 --- /dev/null +++ b/docs/source/development/reference/deprecated.rst @@ -0,0 +1,270 @@ +.. _api: + +******************************************************************************** +Deprecated API +******************************************************************************** + +.. contents:: Contents + :depth: 3 + :backlinks: none + +Introduction +------------ + +Procedure ``pj_init()`` selects and initializes a cartographic +projection with its argument control parameters. ``argc`` is the number +of elements in the array of control strings argv that each contain +individual cartographic control keyword assignments (+ proj arguments). +The list must contain at least the proj=projection and Earth’s radius or +elliptical parameters. If the initialization of the projection is +successful a valid address is returned otherwise a NULL value. + +The ``pj_init_plus()`` function operates similarly to ``pj_init()`` but +takes a single string containing the definition, with each parameter +prefixed with a plus sign. For example +``+proj=utm +zone=11 +ellps=WGS84``. + +Once initialization is performed either forward or inverse projections +can be performed with the returned value of ``pj_init()`` used as the +argument proj. The argument structure projUV values u and v contain +respective longitude and latitude or x and y. Latitude and longitude are +in radians. If a projection operation fails, both elements of projUV are +set to ``HUGE_VAL`` (defined in ``math.h``). + +Note: all projections have a forward mode, but some do not have an +inverse projection. If the projection does not have an inverse the +projPJ structure element inv will be ``NULL``. + +The ``pj_transform`` function may be used to transform points between +the two provided coordinate systems. In addition to converting between +cartographic projection coordinates and geographic coordinates, this +function also takes care of datum shifts if possible between the source +and destination coordinate system. Unlike ``pj_fwd()`` and ``pj_inv()`` +it is also allowable for the coordinate system definitions +``(projPJ *)`` to be geographic coordinate systems (defined as +``+proj=latlong``). +The x, y and z arrays contain the input values of the points, and are replaced with the output values. +The function returns zero on success, or the error number (also in ``pj_errno``) +on failure. + +Memory associated with the projection may be freed with ``pj_free()``. + +Example +------- + +The following program reads latitude and longitude values in decimal +degress, performs Mercator projection with a Clarke 1866 ellipsoid and a +33° latitude of true scale and prints the projected cartesian values in +meters: + +.. code:: + + #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")) ) + exit(1); + if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) + exit(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); + } + exit(0); + } + + +For this program, an input of ``-16 20.25`` would give a result of +``-1495284.21 1920596.79``. + +API Functions +------------- + +pj_transform +============ + +:: + + int pj_transform( projPJ srcdefn, + projPJ dstdefn, + long point_count, + int point_offset, + double *x, + double *y, + double *z ); + + +Transform the x/y/z points from the source coordinate system to the +destination coordinate system. + +``srcdefn``: source (input) coordinate system. + +``dstdefn``: destination (output) coordinate system. + +``point_count``: the number of points to be processed (the size of the +x/y/z arrays). + +``point_offset``: the step size from value to value (measured in +doubles) within the x/y/z arrays - normally 1 for a packed array. May be +used to operate on xyz interleaved point arrays. + +``x``/``y``/``z``: The array of X, Y and Z coordinate values passed as +input, and modified in place for output. The Z may optionally be NULL. + +``return``: The return is zero on success, or a PROJ.4 error code. + +The ``pj_transform()`` function transforms the passed in list of points +from the source coordinate system to the destination coordinate system. +Note that geographic locations need to be passed in radians, not decimal +degrees, and will be returned similarly. The ``z`` array may be passed +as NULL if Z values are not available. + +If there is an overall failure, an error code will be returned from the +function. If individual points fail to transform - for instance due to +being over the horizon - then those x/y/z values will be set to +``HUGE_VAL`` on return. Input values that are ``HUGE_VAL`` will not be +transformed. + + +pj_init_plus +============ + +:: + + projPJ pj_init_plus(const char *definition); + +This function converts a string representation of a coordinate system +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:`transformation` notes for additional detail. + +Coordinate system objects allocated with ``pj_init_plus()`` should be +deallocated with ``pj_free()``. + + +pj_free +======= + +:: + + void pj_free( projPJ pj ); + +Frees all resources associated with pj. + + +pj_is_latlong +============= + +:: + + int pj_is_latlong( projPJ pj ); + +Returns TRUE if the passed coordinate system is geographic +(``proj=latlong``). + + +pj_is_geocent +============= + +:: + + int pj_is_geocent( projPJ pj );`` + +Returns TRUE if the coordinate system is geocentric (``proj=geocent``). + +pj_get_def +========== + +:: + + char *pj_get_def( projPJ pj, int options);`` + +Returns the PROJ.4 initialization string suitable for use with +``pj_init_plus()`` that would produce this coordinate system, but with +the definition expanded as much as possible (for instance ``+init=`` and +``+datum=`` definitions). + +pj_latlong_from_proj +==================== + +:: + + projPJ pj_latlong_from_proj( projPJ pj_in );`` + +Returns a new coordinate system definition which is the geographic +coordinate (lat/long) system underlying ``pj_in``. + +pj_set_finder +============== + +:: + + void pj_set_finder( const char *(*new_finder)(const char *) );`` + +Install a custom function for finding init and grid shift files. + +pj_set_searchpath +================= + +:: + + void pj_set_searchpath ( int count, const char **path );`` + +Set a list of directories to search for init and grid shift files. + + +pj_deallocate_grids +=================== + +:: + + void pj_deallocate_grids( void );`` + +Frees all resources associated with loaded and cached datum shift grids. + + +pj_strerrno +=========== + +:: + + char *pj_strerrno( int );`` + +Returns the error text associated with the passed in error code. + +pj_get_errno_ref +================ + +:: + + int *pj_get_errno_ref( void );`` + +Returns a pointer to the global pj\_errno error variable. + +pj_get_release +============== + +:: + + const char *pj_get_release( void );`` + +Returns an internal string describing the release version. + +Obsolete Functions +~~~~~~~~~~~~~~~~~~ + +``XY pj_fwd( LP lp, PJ *P );`` + +``LP pj_inv( XY xy, PJ *P );`` + +``projPJ pj_init(int argc, char **argv);`` + +.. _more info: pj_transform + diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst new file mode 100644 index 00000000..3ceffb5b --- /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 00000000..9e92384c --- /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 33072408..a557fa07 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 00000000..b03ce368 --- /dev/null +++ b/docs/source/development/transformations.rst @@ -0,0 +1,7 @@ +.. _dev_transformations: + +================================================================================ +Transformations +================================================================================ + + -- cgit v1.2.3 From 3cb1c28f116283e7ab3cde15ebe119a3bb96564a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 5 Sep 2017 22:21:18 +0200 Subject: Added data types reference section. --- docs/source/development/reference/datatypes.rst | 883 ++++++++++++++++++++++++ docs/source/index.rst | 2 +- 2 files changed, 884 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 193ec238..991fcfc5 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 c70cdced..bfb9aee6 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 ================== -- cgit v1.2.3 From 1f60b8c407ac202916cf4570683935fcca451531 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 12 Sep 2017 16:42:02 +0200 Subject: Added functions API reference --- docs/source/development/reference/functions.rst | 433 ++++++++++++++++++++++++ 1 file changed, 433 insertions(+) (limited to 'docs/source') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 3ceffb5b..fc546f33 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`) -- cgit v1.2.3 From 6d1a1ff4e470bb4d26be46bdf01de3d94e6ab8e9 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 18 Sep 2017 22:21:20 +0200 Subject: 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/projections/aeqd.rst | 10 -- docs/source/projections/airy.rst | 10 -- docs/source/projections/aitoff.rst | 10 -- docs/source/projections/alsk.rst | 10 -- docs/source/projections/apian.rst | 10 -- docs/source/projections/august.rst | 10 -- docs/source/projections/bacon.rst | 10 -- docs/source/projections/bipc.rst | 10 -- docs/source/projections/boggs.rst | 10 -- docs/source/projections/bonne.rst | 10 -- docs/source/projections/calcofi.rst | 95 ---------- docs/source/projections/cass.rst | 145 --------------- docs/source/projections/cc.rst | 10 -- docs/source/projections/cea.rst | 10 -- docs/source/projections/chamb.rst | 10 -- docs/source/projections/collg.rst | 10 -- docs/source/projections/crast.rst | 10 -- docs/source/projections/denoy.rst | 10 -- docs/source/projections/eck1.rst | 18 -- docs/source/projections/eck2.rst | 10 -- docs/source/projections/eck3.rst | 10 -- docs/source/projections/eck4.rst | 19 -- docs/source/projections/eck5.rst | 10 -- docs/source/projections/eck6.rst | 10 -- docs/source/projections/eqc.rst | 110 ------------ docs/source/projections/eqdc.rst | 10 -- docs/source/projections/etmerc.rst | 10 -- docs/source/projections/euler.rst | 10 -- docs/source/projections/fahey.rst | 10 -- docs/source/projections/fouc.rst | 10 -- docs/source/projections/fouc_s.rst | 25 --- docs/source/projections/gall.rst | 84 --------- docs/source/projections/geos.rst | 72 -------- docs/source/projections/gins8.rst | 10 -- docs/source/projections/gn_sinu.rst | 10 -- docs/source/projections/gnom.rst | 10 -- docs/source/projections/goode.rst | 10 -- docs/source/projections/gs48.rst | 10 -- docs/source/projections/gs50.rst | 10 -- docs/source/projections/gstmerc.rst | 10 -- docs/source/projections/hammer.rst | 10 -- docs/source/projections/hatano.rst | 70 -------- docs/source/projections/healpix.rst | 55 ------ docs/source/projections/igh.rst | 10 -- docs/source/projections/images/aea.png | Bin 273668 -> 0 bytes docs/source/projections/images/aeqd.png | Bin 242075 -> 0 bytes docs/source/projections/images/airy.png | Bin 193140 -> 0 bytes docs/source/projections/images/aitoff.png | Bin 281655 -> 0 bytes docs/source/projections/images/alsk.png | Bin 89331 -> 0 bytes docs/source/projections/images/apian.png | Bin 232910 -> 0 bytes docs/source/projections/images/august.png | Bin 264816 -> 0 bytes docs/source/projections/images/bacon.png | Bin 232456 -> 0 bytes docs/source/projections/images/bipc.png | Bin 214330 -> 0 bytes docs/source/projections/images/boggs.png | Bin 243618 -> 0 bytes docs/source/projections/images/bonne.png | Bin 290097 -> 0 bytes docs/source/projections/images/calcofi.png | Bin 316606 -> 0 bytes docs/source/projections/images/cass.png | Bin 207715 -> 0 bytes docs/source/projections/images/cc.png | Bin 100206 -> 0 bytes docs/source/projections/images/cea.png | Bin 96163 -> 0 bytes docs/source/projections/images/chamb.png | Bin 301159 -> 0 bytes docs/source/projections/images/collg.png | Bin 211969 -> 0 bytes docs/source/projections/images/comill.png | Bin 100906 -> 0 bytes docs/source/projections/images/crast.png | Bin 240748 -> 0 bytes docs/source/projections/images/denoy.png | Bin 242689 -> 0 bytes docs/source/projections/images/eck1.png | Bin 226331 -> 0 bytes docs/source/projections/images/eck2.png | Bin 227996 -> 0 bytes docs/source/projections/images/eck3.png | Bin 229072 -> 0 bytes docs/source/projections/images/eck4.png | Bin 228930 -> 0 bytes docs/source/projections/images/eck5.png | Bin 227661 -> 0 bytes docs/source/projections/images/eck6.png | Bin 228739 -> 0 bytes docs/source/projections/images/eqc.png | Bin 99881 -> 0 bytes docs/source/projections/images/eqdc.png | Bin 253069 -> 0 bytes docs/source/projections/images/etmerc.png | Bin 296004 -> 0 bytes docs/source/projections/images/euler.png | Bin 260706 -> 0 bytes docs/source/projections/images/fahey.png | Bin 243833 -> 0 bytes docs/source/projections/images/fouc.png | Bin 226398 -> 0 bytes docs/source/projections/images/fouc_s.png | Bin 96801 -> 0 bytes docs/source/projections/images/gall.png | Bin 99516 -> 0 bytes docs/source/projections/images/geos.png | Bin 155703 -> 0 bytes docs/source/projections/images/gins8.png | Bin 231431 -> 0 bytes docs/source/projections/images/gn_sinu.png | Bin 198410 -> 0 bytes docs/source/projections/images/gnom.png | Bin 183664 -> 0 bytes docs/source/projections/images/goode.png | Bin 245463 -> 0 bytes docs/source/projections/images/gs48.png | Bin 79575 -> 0 bytes docs/source/projections/images/gs50.png | Bin 127915 -> 0 bytes docs/source/projections/images/gstmerc.png | Bin 259585 -> 0 bytes docs/source/projections/images/hammer.png | Bin 282624 -> 0 bytes docs/source/projections/images/hatano.png | Bin 215598 -> 0 bytes docs/source/projections/images/healpix.png | Bin 171513 -> 0 bytes docs/source/projections/images/igh.png | Bin 232327 -> 0 bytes docs/source/projections/images/imw_p.png | Bin 188272 -> 0 bytes docs/source/projections/images/isea.png | Bin 310106 -> 0 bytes docs/source/projections/images/kav5.png | Bin 244578 -> 0 bytes docs/source/projections/images/kav7.png | Bin 229109 -> 0 bytes docs/source/projections/images/krovak.png | Bin 70429 -> 0 bytes docs/source/projections/images/labrd.png | Bin 48609 -> 0 bytes docs/source/projections/images/laea.png | Bin 288272 -> 0 bytes docs/source/projections/images/lagrng.png | Bin 281932 -> 0 bytes docs/source/projections/images/larr.png | Bin 255324 -> 0 bytes docs/source/projections/images/lask.png | Bin 276892 -> 0 bytes docs/source/projections/images/lcc.png | Bin 163094 -> 0 bytes docs/source/projections/images/lcca.png | Bin 235626 -> 0 bytes docs/source/projections/images/leac.png | Bin 306096 -> 0 bytes docs/source/projections/images/lee_os.png | Bin 141797 -> 0 bytes docs/source/projections/images/loxim.png | Bin 241566 -> 0 bytes docs/source/projections/images/lsat.png | Bin 14385 -> 0 bytes docs/source/projections/images/mbt_fps.png | Bin 241457 -> 0 bytes docs/source/projections/images/mbt_s.png | Bin 245067 -> 0 bytes docs/source/projections/images/mbtfpp.png | Bin 236235 -> 0 bytes docs/source/projections/images/mbtfpq.png | Bin 237516 -> 0 bytes docs/source/projections/images/mbtfps.png | Bin 235738 -> 0 bytes docs/source/projections/images/merc.png | Bin 100334 -> 0 bytes docs/source/projections/images/mil_os.png | Bin 136269 -> 0 bytes docs/source/projections/images/mill.png | Bin 97862 -> 0 bytes docs/source/projections/images/misrsom.png | Bin 293190 -> 0 bytes docs/source/projections/images/moll.png | Bin 244671 -> 0 bytes docs/source/projections/images/murd1.png | Bin 234038 -> 0 bytes docs/source/projections/images/murd2.png | Bin 175431 -> 0 bytes docs/source/projections/images/murd3.png | Bin 229304 -> 0 bytes docs/source/projections/images/natearth.png | Bin 228702 -> 0 bytes docs/source/projections/images/natearth2.png | Bin 240763 -> 0 bytes docs/source/projections/images/nell.png | Bin 213589 -> 0 bytes docs/source/projections/images/nell_h.png | Bin 230244 -> 0 bytes docs/source/projections/images/nicol.png | Bin 263585 -> 0 bytes docs/source/projections/images/nsper.png | Bin 133200 -> 0 bytes docs/source/projections/images/nzmg.png | Bin 50472 -> 0 bytes docs/source/projections/images/ob_tran.png | Bin 272387 -> 0 bytes docs/source/projections/images/ocea.png | Bin 93093 -> 0 bytes docs/source/projections/images/oea.png | Bin 351858 -> 0 bytes docs/source/projections/images/omerc.png | Bin 231077 -> 0 bytes docs/source/projections/images/ortel.png | Bin 197532 -> 0 bytes docs/source/projections/images/ortho.png | Bin 156144 -> 0 bytes docs/source/projections/images/patterson.png | Bin 102271 -> 0 bytes docs/source/projections/images/pconic.png | Bin 200664 -> 0 bytes docs/source/projections/images/poly.png | Bin 270344 -> 0 bytes docs/source/projections/images/putp1.png | Bin 243490 -> 0 bytes docs/source/projections/images/putp2.png | Bin 243377 -> 0 bytes docs/source/projections/images/putp3.png | Bin 240811 -> 0 bytes docs/source/projections/images/putp3p.png | Bin 228904 -> 0 bytes docs/source/projections/images/putp4p.png | Bin 230226 -> 0 bytes docs/source/projections/images/putp5.png | Bin 237811 -> 0 bytes docs/source/projections/images/putp5p.png | Bin 228264 -> 0 bytes docs/source/projections/images/putp6.png | Bin 238235 -> 0 bytes docs/source/projections/images/putp6p.png | Bin 229779 -> 0 bytes docs/source/projections/images/qsc.png | Bin 297806 -> 0 bytes docs/source/projections/images/qua_aut.png | Bin 242497 -> 0 bytes docs/source/projections/images/rhealpix.png | Bin 393316 -> 0 bytes docs/source/projections/images/robin.png | Bin 228460 -> 0 bytes docs/source/projections/images/rouss.png | Bin 234337 -> 0 bytes docs/source/projections/images/rpoly.png | Bin 275448 -> 0 bytes docs/source/projections/images/sinu.png | Bin 236312 -> 0 bytes docs/source/projections/images/somerc.png | Bin 87704 -> 0 bytes docs/source/projections/images/stere.png | Bin 176565 -> 0 bytes docs/source/projections/images/sterea.png | Bin 175090 -> 0 bytes docs/source/projections/images/tcc.png | Bin 121474 -> 0 bytes docs/source/projections/images/tcea.png | Bin 331583 -> 0 bytes docs/source/projections/images/tissot.png | Bin 268068 -> 0 bytes docs/source/projections/images/tmerc.png | Bin 186992 -> 0 bytes docs/source/projections/images/tpeqd.png | Bin 297972 -> 0 bytes docs/source/projections/images/tpers.png | Bin 156134 -> 0 bytes docs/source/projections/images/ups.png | Bin 201068 -> 0 bytes docs/source/projections/images/urm5.png | Bin 232637 -> 0 bytes docs/source/projections/images/urmfps.png | Bin 189587 -> 0 bytes docs/source/projections/images/utm.png | Bin 305727 -> 0 bytes docs/source/projections/images/vandg.png | Bin 274126 -> 0 bytes docs/source/projections/images/vandg2.png | Bin 286774 -> 0 bytes docs/source/projections/images/vandg3.png | Bin 239999 -> 0 bytes docs/source/projections/images/vandg4.png | Bin 273833 -> 0 bytes docs/source/projections/images/vitk1.png | Bin 251858 -> 0 bytes docs/source/projections/images/wag1.png | Bin 230113 -> 0 bytes docs/source/projections/images/wag2.png | Bin 229235 -> 0 bytes docs/source/projections/images/wag3.png | Bin 228764 -> 0 bytes docs/source/projections/images/wag4.png | Bin 230059 -> 0 bytes docs/source/projections/images/wag5.png | Bin 231608 -> 0 bytes docs/source/projections/images/wag6.png | Bin 229507 -> 0 bytes docs/source/projections/images/wag7.png | Bin 262121 -> 0 bytes docs/source/projections/images/weren.png | Bin 230046 -> 0 bytes docs/source/projections/images/wink1.png | Bin 228017 -> 0 bytes docs/source/projections/images/wink2.png | Bin 229994 -> 0 bytes docs/source/projections/images/wintri.png | Bin 266146 -> 0 bytes docs/source/projections/imw_p.rst | 10 -- docs/source/projections/index.rst | 142 --------------- docs/source/projections/isea.rst | 10 -- docs/source/projections/kav5.rst | 10 -- docs/source/projections/kav7.rst | 10 -- docs/source/projections/krovak.rst | 10 -- docs/source/projections/labrd.rst | 10 -- docs/source/projections/laea.rst | 10 -- docs/source/projections/lagrng.rst | 10 -- docs/source/projections/larr.rst | 10 -- docs/source/projections/lask.rst | 10 -- docs/source/projections/latlon.rst | 6 - docs/source/projections/lcc.rst | 10 -- docs/source/projections/lcca.rst | 10 -- docs/source/projections/leac.rst | 10 -- docs/source/projections/lee_os.rst | 10 -- docs/source/projections/lonlat.rst | 6 - docs/source/projections/loxim.rst | 10 -- docs/source/projections/lsat.rst | 10 -- docs/source/projections/mbt_fps.rst | 10 -- docs/source/projections/mbt_s.rst | 10 -- docs/source/projections/mbtfpp.rst | 10 -- docs/source/projections/mbtfpq.rst | 10 -- docs/source/projections/mbtfps.rst | 10 -- docs/source/projections/merc.rst | 140 --------------- docs/source/projections/mil_os.rst | 10 -- docs/source/projections/mill.rst | 72 -------- docs/source/projections/moll.rst | 10 -- docs/source/projections/murd1.rst | 10 -- docs/source/projections/murd2.rst | 10 -- docs/source/projections/murd3.rst | 10 -- docs/source/projections/natearth.rst | 47 ----- docs/source/projections/nell.rst | 10 -- docs/source/projections/nell_h.rst | 10 -- docs/source/projections/nicol.rst | 10 -- docs/source/projections/nsper.rst | 10 -- docs/source/projections/nzmg.rst | 10 -- docs/source/projections/ob_tran.rst | 10 -- docs/source/projections/ocea.rst | 10 -- docs/source/projections/oea.rst | 10 -- docs/source/projections/omerc.rst | 10 -- docs/source/projections/ortel.rst | 10 -- docs/source/projections/ortho.rst | 10 -- docs/source/projections/pconic.rst | 10 -- docs/source/projections/poly.rst | 10 -- docs/source/projections/putp1.rst | 10 -- docs/source/projections/putp2.rst | 10 -- docs/source/projections/putp3.rst | 10 -- docs/source/projections/putp3p.rst | 10 -- docs/source/projections/putp4p.rst | 10 -- docs/source/projections/putp5.rst | 10 -- docs/source/projections/putp5p.rst | 10 -- docs/source/projections/putp6.rst | 10 -- docs/source/projections/putp6p.rst | 10 -- docs/source/projections/qsc.rst | 158 ----------------- docs/source/projections/qua_aut.rst | 10 -- docs/source/projections/rhealpix.rst | 51 ------ docs/source/projections/robin.rst | 10 -- docs/source/projections/rouss.rst | 10 -- docs/source/projections/rpoly.rst | 10 -- docs/source/projections/sinu.rst | 24 --- docs/source/projections/somerc.rst | 10 -- docs/source/projections/stere.rst | 10 -- docs/source/projections/sterea.rst | 10 -- docs/source/projections/tcc.rst | 10 -- docs/source/projections/tcea.rst | 10 -- docs/source/projections/tissot.rst | 10 -- docs/source/projections/tmerc.rst | 197 --------------------- docs/source/projections/tpeqd.rst | 10 -- docs/source/projections/tpers.rst | 39 ---- docs/source/projections/ups.rst | 10 -- docs/source/projections/urm5.rst | 10 -- docs/source/projections/urmfps.rst | 10 -- docs/source/projections/utm.rst | 10 -- docs/source/projections/vandg.rst | 10 -- docs/source/projections/vandg2.rst | 10 -- docs/source/projections/vandg3.rst | 10 -- docs/source/projections/vandg4.rst | 10 -- docs/source/projections/vitk1.rst | 10 -- docs/source/projections/wag1.rst | 10 -- docs/source/projections/wag2.rst | 18 -- docs/source/projections/wag3.rst | 16 -- docs/source/projections/wag4.rst | 10 -- docs/source/projections/wag5.rst | 10 -- docs/source/projections/wag6.rst | 10 -- docs/source/projections/wag7.rst | 10 -- docs/source/projections/weren.rst | 10 -- docs/source/projections/wink1.rst | 10 -- docs/source/projections/wink2.rst | 10 -- docs/source/projections/wintri.rst | 10 -- docs/source/usage/index.rst | 1 + docs/source/usage/operations/index.rst | 18 ++ docs/source/usage/operations/projections/aeqd.rst | 10 ++ docs/source/usage/operations/projections/airy.rst | 10 ++ .../source/usage/operations/projections/aitoff.rst | 10 ++ docs/source/usage/operations/projections/alsk.rst | 10 ++ docs/source/usage/operations/projections/apian.rst | 10 ++ .../source/usage/operations/projections/august.rst | 10 ++ docs/source/usage/operations/projections/bacon.rst | 10 ++ docs/source/usage/operations/projections/bipc.rst | 10 ++ docs/source/usage/operations/projections/boggs.rst | 10 ++ docs/source/usage/operations/projections/bonne.rst | 10 ++ .../usage/operations/projections/calcofi.rst | 95 ++++++++++ docs/source/usage/operations/projections/cass.rst | 145 +++++++++++++++ docs/source/usage/operations/projections/cc.rst | 10 ++ docs/source/usage/operations/projections/cea.rst | 10 ++ docs/source/usage/operations/projections/chamb.rst | 10 ++ docs/source/usage/operations/projections/collg.rst | 10 ++ docs/source/usage/operations/projections/crast.rst | 10 ++ docs/source/usage/operations/projections/denoy.rst | 10 ++ docs/source/usage/operations/projections/eck1.rst | 18 ++ docs/source/usage/operations/projections/eck2.rst | 10 ++ docs/source/usage/operations/projections/eck3.rst | 10 ++ docs/source/usage/operations/projections/eck4.rst | 19 ++ docs/source/usage/operations/projections/eck5.rst | 10 ++ docs/source/usage/operations/projections/eck6.rst | 10 ++ docs/source/usage/operations/projections/eqc.rst | 110 ++++++++++++ docs/source/usage/operations/projections/eqdc.rst | 10 ++ .../source/usage/operations/projections/etmerc.rst | 10 ++ docs/source/usage/operations/projections/euler.rst | 10 ++ docs/source/usage/operations/projections/fahey.rst | 10 ++ docs/source/usage/operations/projections/fouc.rst | 10 ++ .../source/usage/operations/projections/fouc_s.rst | 25 +++ docs/source/usage/operations/projections/gall.rst | 84 +++++++++ docs/source/usage/operations/projections/geos.rst | 72 ++++++++ docs/source/usage/operations/projections/gins8.rst | 10 ++ .../usage/operations/projections/gn_sinu.rst | 10 ++ docs/source/usage/operations/projections/gnom.rst | 10 ++ docs/source/usage/operations/projections/goode.rst | 10 ++ docs/source/usage/operations/projections/gs48.rst | 10 ++ docs/source/usage/operations/projections/gs50.rst | 10 ++ .../usage/operations/projections/gstmerc.rst | 10 ++ .../source/usage/operations/projections/hammer.rst | 10 ++ .../source/usage/operations/projections/hatano.rst | 70 ++++++++ .../usage/operations/projections/healpix.rst | 55 ++++++ docs/source/usage/operations/projections/igh.rst | 10 ++ .../usage/operations/projections/images/aea.png | Bin 0 -> 273668 bytes .../usage/operations/projections/images/aeqd.png | Bin 0 -> 242075 bytes .../usage/operations/projections/images/airy.png | Bin 0 -> 193140 bytes .../usage/operations/projections/images/aitoff.png | Bin 0 -> 281655 bytes .../usage/operations/projections/images/alsk.png | Bin 0 -> 89331 bytes .../usage/operations/projections/images/apian.png | Bin 0 -> 232910 bytes .../usage/operations/projections/images/august.png | Bin 0 -> 264816 bytes .../usage/operations/projections/images/bacon.png | Bin 0 -> 232456 bytes .../usage/operations/projections/images/bipc.png | Bin 0 -> 214330 bytes .../usage/operations/projections/images/boggs.png | Bin 0 -> 243618 bytes .../usage/operations/projections/images/bonne.png | Bin 0 -> 290097 bytes .../operations/projections/images/calcofi.png | Bin 0 -> 316606 bytes .../usage/operations/projections/images/cass.png | Bin 0 -> 207715 bytes .../usage/operations/projections/images/cc.png | Bin 0 -> 100206 bytes .../usage/operations/projections/images/cea.png | Bin 0 -> 96163 bytes .../usage/operations/projections/images/chamb.png | Bin 0 -> 301159 bytes .../usage/operations/projections/images/collg.png | Bin 0 -> 211969 bytes .../usage/operations/projections/images/comill.png | Bin 0 -> 100906 bytes .../usage/operations/projections/images/crast.png | Bin 0 -> 240748 bytes .../usage/operations/projections/images/denoy.png | Bin 0 -> 242689 bytes .../usage/operations/projections/images/eck1.png | Bin 0 -> 226331 bytes .../usage/operations/projections/images/eck2.png | Bin 0 -> 227996 bytes .../usage/operations/projections/images/eck3.png | Bin 0 -> 229072 bytes .../usage/operations/projections/images/eck4.png | Bin 0 -> 228930 bytes .../usage/operations/projections/images/eck5.png | Bin 0 -> 227661 bytes .../usage/operations/projections/images/eck6.png | Bin 0 -> 228739 bytes .../usage/operations/projections/images/eqc.png | Bin 0 -> 99881 bytes .../usage/operations/projections/images/eqdc.png | Bin 0 -> 253069 bytes .../usage/operations/projections/images/etmerc.png | Bin 0 -> 296004 bytes .../usage/operations/projections/images/euler.png | Bin 0 -> 260706 bytes .../usage/operations/projections/images/fahey.png | Bin 0 -> 243833 bytes .../usage/operations/projections/images/fouc.png | Bin 0 -> 226398 bytes .../usage/operations/projections/images/fouc_s.png | Bin 0 -> 96801 bytes .../usage/operations/projections/images/gall.png | Bin 0 -> 99516 bytes .../usage/operations/projections/images/geos.png | Bin 0 -> 155703 bytes .../usage/operations/projections/images/gins8.png | Bin 0 -> 231431 bytes .../operations/projections/images/gn_sinu.png | Bin 0 -> 198410 bytes .../usage/operations/projections/images/gnom.png | Bin 0 -> 183664 bytes .../usage/operations/projections/images/goode.png | Bin 0 -> 245463 bytes .../usage/operations/projections/images/gs48.png | Bin 0 -> 79575 bytes .../usage/operations/projections/images/gs50.png | Bin 0 -> 127915 bytes .../operations/projections/images/gstmerc.png | Bin 0 -> 259585 bytes .../usage/operations/projections/images/hammer.png | Bin 0 -> 282624 bytes .../usage/operations/projections/images/hatano.png | Bin 0 -> 215598 bytes .../operations/projections/images/healpix.png | Bin 0 -> 171513 bytes .../usage/operations/projections/images/igh.png | Bin 0 -> 232327 bytes .../usage/operations/projections/images/imw_p.png | Bin 0 -> 188272 bytes .../usage/operations/projections/images/isea.png | Bin 0 -> 310106 bytes .../usage/operations/projections/images/kav5.png | Bin 0 -> 244578 bytes .../usage/operations/projections/images/kav7.png | Bin 0 -> 229109 bytes .../usage/operations/projections/images/krovak.png | Bin 0 -> 70429 bytes .../usage/operations/projections/images/labrd.png | Bin 0 -> 48609 bytes .../usage/operations/projections/images/laea.png | Bin 0 -> 288272 bytes .../usage/operations/projections/images/lagrng.png | Bin 0 -> 281932 bytes .../usage/operations/projections/images/larr.png | Bin 0 -> 255324 bytes .../usage/operations/projections/images/lask.png | Bin 0 -> 276892 bytes .../usage/operations/projections/images/lcc.png | Bin 0 -> 163094 bytes .../usage/operations/projections/images/lcca.png | Bin 0 -> 235626 bytes .../usage/operations/projections/images/leac.png | Bin 0 -> 306096 bytes .../usage/operations/projections/images/lee_os.png | Bin 0 -> 141797 bytes .../usage/operations/projections/images/loxim.png | Bin 0 -> 241566 bytes .../usage/operations/projections/images/lsat.png | Bin 0 -> 14385 bytes .../operations/projections/images/mbt_fps.png | Bin 0 -> 241457 bytes .../usage/operations/projections/images/mbt_s.png | Bin 0 -> 245067 bytes .../usage/operations/projections/images/mbtfpp.png | Bin 0 -> 236235 bytes .../usage/operations/projections/images/mbtfpq.png | Bin 0 -> 237516 bytes .../usage/operations/projections/images/mbtfps.png | Bin 0 -> 235738 bytes .../usage/operations/projections/images/merc.png | Bin 0 -> 100334 bytes .../usage/operations/projections/images/mil_os.png | Bin 0 -> 136269 bytes .../usage/operations/projections/images/mill.png | Bin 0 -> 97862 bytes .../operations/projections/images/misrsom.png | Bin 0 -> 293190 bytes .../usage/operations/projections/images/moll.png | Bin 0 -> 244671 bytes .../usage/operations/projections/images/murd1.png | Bin 0 -> 234038 bytes .../usage/operations/projections/images/murd2.png | Bin 0 -> 175431 bytes .../usage/operations/projections/images/murd3.png | Bin 0 -> 229304 bytes .../operations/projections/images/natearth.png | Bin 0 -> 228702 bytes .../operations/projections/images/natearth2.png | Bin 0 -> 240763 bytes .../usage/operations/projections/images/nell.png | Bin 0 -> 213589 bytes .../usage/operations/projections/images/nell_h.png | Bin 0 -> 230244 bytes .../usage/operations/projections/images/nicol.png | Bin 0 -> 263585 bytes .../usage/operations/projections/images/nsper.png | Bin 0 -> 133200 bytes .../usage/operations/projections/images/nzmg.png | Bin 0 -> 50472 bytes .../operations/projections/images/ob_tran.png | Bin 0 -> 272387 bytes .../usage/operations/projections/images/ocea.png | Bin 0 -> 93093 bytes .../usage/operations/projections/images/oea.png | Bin 0 -> 351858 bytes .../usage/operations/projections/images/omerc.png | Bin 0 -> 231077 bytes .../usage/operations/projections/images/ortel.png | Bin 0 -> 197532 bytes .../usage/operations/projections/images/ortho.png | Bin 0 -> 156144 bytes .../operations/projections/images/patterson.png | Bin 0 -> 102271 bytes .../usage/operations/projections/images/pconic.png | Bin 0 -> 200664 bytes .../usage/operations/projections/images/poly.png | Bin 0 -> 270344 bytes .../usage/operations/projections/images/putp1.png | Bin 0 -> 243490 bytes .../usage/operations/projections/images/putp2.png | Bin 0 -> 243377 bytes .../usage/operations/projections/images/putp3.png | Bin 0 -> 240811 bytes .../usage/operations/projections/images/putp3p.png | Bin 0 -> 228904 bytes .../usage/operations/projections/images/putp4p.png | Bin 0 -> 230226 bytes .../usage/operations/projections/images/putp5.png | Bin 0 -> 237811 bytes .../usage/operations/projections/images/putp5p.png | Bin 0 -> 228264 bytes .../usage/operations/projections/images/putp6.png | Bin 0 -> 238235 bytes .../usage/operations/projections/images/putp6p.png | Bin 0 -> 229779 bytes .../usage/operations/projections/images/qsc.png | Bin 0 -> 297806 bytes .../operations/projections/images/qua_aut.png | Bin 0 -> 242497 bytes .../operations/projections/images/rhealpix.png | Bin 0 -> 393316 bytes .../usage/operations/projections/images/robin.png | Bin 0 -> 228460 bytes .../usage/operations/projections/images/rouss.png | Bin 0 -> 234337 bytes .../usage/operations/projections/images/rpoly.png | Bin 0 -> 275448 bytes .../usage/operations/projections/images/sinu.png | Bin 0 -> 236312 bytes .../usage/operations/projections/images/somerc.png | Bin 0 -> 87704 bytes .../usage/operations/projections/images/stere.png | Bin 0 -> 176565 bytes .../usage/operations/projections/images/sterea.png | Bin 0 -> 175090 bytes .../usage/operations/projections/images/tcc.png | Bin 0 -> 121474 bytes .../usage/operations/projections/images/tcea.png | Bin 0 -> 331583 bytes .../usage/operations/projections/images/tissot.png | Bin 0 -> 268068 bytes .../usage/operations/projections/images/tmerc.png | Bin 0 -> 186992 bytes .../usage/operations/projections/images/tpeqd.png | Bin 0 -> 297972 bytes .../usage/operations/projections/images/tpers.png | Bin 0 -> 156134 bytes .../usage/operations/projections/images/ups.png | Bin 0 -> 201068 bytes .../usage/operations/projections/images/urm5.png | Bin 0 -> 232637 bytes .../usage/operations/projections/images/urmfps.png | Bin 0 -> 189587 bytes .../usage/operations/projections/images/utm.png | Bin 0 -> 305727 bytes .../usage/operations/projections/images/vandg.png | Bin 0 -> 274126 bytes .../usage/operations/projections/images/vandg2.png | Bin 0 -> 286774 bytes .../usage/operations/projections/images/vandg3.png | Bin 0 -> 239999 bytes .../usage/operations/projections/images/vandg4.png | Bin 0 -> 273833 bytes .../usage/operations/projections/images/vitk1.png | Bin 0 -> 251858 bytes .../usage/operations/projections/images/wag1.png | Bin 0 -> 230113 bytes .../usage/operations/projections/images/wag2.png | Bin 0 -> 229235 bytes .../usage/operations/projections/images/wag3.png | Bin 0 -> 228764 bytes .../usage/operations/projections/images/wag4.png | Bin 0 -> 230059 bytes .../usage/operations/projections/images/wag5.png | Bin 0 -> 231608 bytes .../usage/operations/projections/images/wag6.png | Bin 0 -> 229507 bytes .../usage/operations/projections/images/wag7.png | Bin 0 -> 262121 bytes .../usage/operations/projections/images/weren.png | Bin 0 -> 230046 bytes .../usage/operations/projections/images/wink1.png | Bin 0 -> 228017 bytes .../usage/operations/projections/images/wink2.png | Bin 0 -> 229994 bytes .../usage/operations/projections/images/wintri.png | Bin 0 -> 266146 bytes docs/source/usage/operations/projections/imw_p.rst | 10 ++ docs/source/usage/operations/projections/index.rst | 142 +++++++++++++++ docs/source/usage/operations/projections/isea.rst | 10 ++ docs/source/usage/operations/projections/kav5.rst | 10 ++ docs/source/usage/operations/projections/kav7.rst | 10 ++ .../source/usage/operations/projections/krovak.rst | 10 ++ docs/source/usage/operations/projections/labrd.rst | 10 ++ docs/source/usage/operations/projections/laea.rst | 10 ++ .../source/usage/operations/projections/lagrng.rst | 10 ++ docs/source/usage/operations/projections/larr.rst | 10 ++ docs/source/usage/operations/projections/lask.rst | 10 ++ .../source/usage/operations/projections/latlon.rst | 6 + docs/source/usage/operations/projections/lcc.rst | 10 ++ docs/source/usage/operations/projections/lcca.rst | 10 ++ docs/source/usage/operations/projections/leac.rst | 10 ++ .../source/usage/operations/projections/lee_os.rst | 10 ++ .../source/usage/operations/projections/lonlat.rst | 6 + docs/source/usage/operations/projections/loxim.rst | 10 ++ docs/source/usage/operations/projections/lsat.rst | 10 ++ .../usage/operations/projections/mbt_fps.rst | 10 ++ docs/source/usage/operations/projections/mbt_s.rst | 10 ++ .../source/usage/operations/projections/mbtfpp.rst | 10 ++ .../source/usage/operations/projections/mbtfpq.rst | 10 ++ .../source/usage/operations/projections/mbtfps.rst | 10 ++ docs/source/usage/operations/projections/merc.rst | 140 +++++++++++++++ .../source/usage/operations/projections/mil_os.rst | 10 ++ docs/source/usage/operations/projections/mill.rst | 72 ++++++++ docs/source/usage/operations/projections/moll.rst | 10 ++ docs/source/usage/operations/projections/murd1.rst | 10 ++ docs/source/usage/operations/projections/murd2.rst | 10 ++ docs/source/usage/operations/projections/murd3.rst | 10 ++ .../usage/operations/projections/natearth.rst | 47 +++++ docs/source/usage/operations/projections/nell.rst | 10 ++ .../source/usage/operations/projections/nell_h.rst | 10 ++ docs/source/usage/operations/projections/nicol.rst | 10 ++ docs/source/usage/operations/projections/nsper.rst | 10 ++ docs/source/usage/operations/projections/nzmg.rst | 10 ++ .../usage/operations/projections/ob_tran.rst | 10 ++ docs/source/usage/operations/projections/ocea.rst | 10 ++ docs/source/usage/operations/projections/oea.rst | 10 ++ docs/source/usage/operations/projections/omerc.rst | 10 ++ docs/source/usage/operations/projections/ortel.rst | 10 ++ docs/source/usage/operations/projections/ortho.rst | 10 ++ .../source/usage/operations/projections/pconic.rst | 10 ++ docs/source/usage/operations/projections/poly.rst | 10 ++ docs/source/usage/operations/projections/putp1.rst | 10 ++ docs/source/usage/operations/projections/putp2.rst | 10 ++ docs/source/usage/operations/projections/putp3.rst | 10 ++ .../source/usage/operations/projections/putp3p.rst | 10 ++ .../source/usage/operations/projections/putp4p.rst | 10 ++ docs/source/usage/operations/projections/putp5.rst | 10 ++ .../source/usage/operations/projections/putp5p.rst | 10 ++ docs/source/usage/operations/projections/putp6.rst | 10 ++ .../source/usage/operations/projections/putp6p.rst | 10 ++ docs/source/usage/operations/projections/qsc.rst | 158 +++++++++++++++++ .../usage/operations/projections/qua_aut.rst | 10 ++ .../usage/operations/projections/rhealpix.rst | 51 ++++++ docs/source/usage/operations/projections/robin.rst | 10 ++ docs/source/usage/operations/projections/rouss.rst | 10 ++ docs/source/usage/operations/projections/rpoly.rst | 10 ++ docs/source/usage/operations/projections/sinu.rst | 24 +++ .../source/usage/operations/projections/somerc.rst | 10 ++ docs/source/usage/operations/projections/stere.rst | 10 ++ .../source/usage/operations/projections/sterea.rst | 10 ++ docs/source/usage/operations/projections/tcc.rst | 10 ++ docs/source/usage/operations/projections/tcea.rst | 10 ++ .../source/usage/operations/projections/tissot.rst | 10 ++ docs/source/usage/operations/projections/tmerc.rst | 197 +++++++++++++++++++++ docs/source/usage/operations/projections/tpeqd.rst | 10 ++ docs/source/usage/operations/projections/tpers.rst | 39 ++++ docs/source/usage/operations/projections/ups.rst | 10 ++ docs/source/usage/operations/projections/urm5.rst | 10 ++ .../source/usage/operations/projections/urmfps.rst | 10 ++ docs/source/usage/operations/projections/utm.rst | 10 ++ docs/source/usage/operations/projections/vandg.rst | 10 ++ .../source/usage/operations/projections/vandg2.rst | 10 ++ .../source/usage/operations/projections/vandg3.rst | 10 ++ .../source/usage/operations/projections/vandg4.rst | 10 ++ docs/source/usage/operations/projections/vitk1.rst | 10 ++ docs/source/usage/operations/projections/wag1.rst | 10 ++ docs/source/usage/operations/projections/wag2.rst | 18 ++ docs/source/usage/operations/projections/wag3.rst | 16 ++ docs/source/usage/operations/projections/wag4.rst | 10 ++ docs/source/usage/operations/projections/wag5.rst | 10 ++ docs/source/usage/operations/projections/wag6.rst | 10 ++ docs/source/usage/operations/projections/wag7.rst | 10 ++ docs/source/usage/operations/projections/weren.rst | 10 ++ docs/source/usage/operations/projections/wink1.rst | 10 ++ docs/source/usage/operations/projections/wink2.rst | 10 ++ .../source/usage/operations/projections/wintri.rst | 10 ++ .../usage/operations/transformations/cart.rst | 24 +++ .../usage/operations/transformations/helmert.rst | 7 + .../operations/transformations/hgridshift.rst | 32 ++++ .../usage/operations/transformations/index.rst | 15 ++ .../operations/transformations/molodensky.rst | 7 + .../operations/transformations/unitconvert.rst | 7 + .../operations/transformations/vgridshift.rst | 34 ++++ 550 files changed, 2864 insertions(+), 2720 deletions(-) delete mode 100644 docs/source/projections/aeqd.rst delete mode 100644 docs/source/projections/airy.rst delete mode 100644 docs/source/projections/aitoff.rst delete mode 100644 docs/source/projections/alsk.rst delete mode 100644 docs/source/projections/apian.rst delete mode 100644 docs/source/projections/august.rst delete mode 100644 docs/source/projections/bacon.rst delete mode 100644 docs/source/projections/bipc.rst delete mode 100644 docs/source/projections/boggs.rst delete mode 100644 docs/source/projections/bonne.rst delete mode 100644 docs/source/projections/calcofi.rst delete mode 100644 docs/source/projections/cass.rst delete mode 100644 docs/source/projections/cc.rst delete mode 100644 docs/source/projections/cea.rst delete mode 100644 docs/source/projections/chamb.rst delete mode 100644 docs/source/projections/collg.rst delete mode 100644 docs/source/projections/crast.rst delete mode 100644 docs/source/projections/denoy.rst delete mode 100644 docs/source/projections/eck1.rst delete mode 100644 docs/source/projections/eck2.rst delete mode 100644 docs/source/projections/eck3.rst delete mode 100644 docs/source/projections/eck4.rst delete mode 100644 docs/source/projections/eck5.rst delete mode 100644 docs/source/projections/eck6.rst delete mode 100644 docs/source/projections/eqc.rst delete mode 100644 docs/source/projections/eqdc.rst delete mode 100644 docs/source/projections/etmerc.rst delete mode 100644 docs/source/projections/euler.rst delete mode 100644 docs/source/projections/fahey.rst delete mode 100644 docs/source/projections/fouc.rst delete mode 100644 docs/source/projections/fouc_s.rst delete mode 100644 docs/source/projections/gall.rst delete mode 100644 docs/source/projections/geos.rst delete mode 100644 docs/source/projections/gins8.rst delete mode 100644 docs/source/projections/gn_sinu.rst delete mode 100644 docs/source/projections/gnom.rst delete mode 100644 docs/source/projections/goode.rst delete mode 100644 docs/source/projections/gs48.rst delete mode 100644 docs/source/projections/gs50.rst delete mode 100644 docs/source/projections/gstmerc.rst delete mode 100644 docs/source/projections/hammer.rst delete mode 100644 docs/source/projections/hatano.rst delete mode 100644 docs/source/projections/healpix.rst delete mode 100644 docs/source/projections/igh.rst delete mode 100644 docs/source/projections/images/aea.png delete mode 100644 docs/source/projections/images/aeqd.png delete mode 100644 docs/source/projections/images/airy.png delete mode 100644 docs/source/projections/images/aitoff.png delete mode 100644 docs/source/projections/images/alsk.png delete mode 100644 docs/source/projections/images/apian.png delete mode 100644 docs/source/projections/images/august.png delete mode 100644 docs/source/projections/images/bacon.png delete mode 100644 docs/source/projections/images/bipc.png delete mode 100644 docs/source/projections/images/boggs.png delete mode 100644 docs/source/projections/images/bonne.png delete mode 100644 docs/source/projections/images/calcofi.png delete mode 100644 docs/source/projections/images/cass.png delete mode 100644 docs/source/projections/images/cc.png delete mode 100644 docs/source/projections/images/cea.png delete mode 100644 docs/source/projections/images/chamb.png delete mode 100644 docs/source/projections/images/collg.png delete mode 100644 docs/source/projections/images/comill.png delete mode 100644 docs/source/projections/images/crast.png delete mode 100644 docs/source/projections/images/denoy.png delete mode 100644 docs/source/projections/images/eck1.png delete mode 100644 docs/source/projections/images/eck2.png delete mode 100644 docs/source/projections/images/eck3.png delete mode 100644 docs/source/projections/images/eck4.png delete mode 100644 docs/source/projections/images/eck5.png delete mode 100644 docs/source/projections/images/eck6.png delete mode 100644 docs/source/projections/images/eqc.png delete mode 100644 docs/source/projections/images/eqdc.png delete mode 100644 docs/source/projections/images/etmerc.png delete mode 100644 docs/source/projections/images/euler.png delete mode 100644 docs/source/projections/images/fahey.png delete mode 100644 docs/source/projections/images/fouc.png delete mode 100644 docs/source/projections/images/fouc_s.png delete mode 100644 docs/source/projections/images/gall.png delete mode 100644 docs/source/projections/images/geos.png delete mode 100644 docs/source/projections/images/gins8.png delete mode 100644 docs/source/projections/images/gn_sinu.png delete mode 100644 docs/source/projections/images/gnom.png delete mode 100644 docs/source/projections/images/goode.png delete mode 100644 docs/source/projections/images/gs48.png delete mode 100644 docs/source/projections/images/gs50.png delete mode 100644 docs/source/projections/images/gstmerc.png delete mode 100644 docs/source/projections/images/hammer.png delete mode 100644 docs/source/projections/images/hatano.png delete mode 100644 docs/source/projections/images/healpix.png delete mode 100644 docs/source/projections/images/igh.png delete mode 100644 docs/source/projections/images/imw_p.png delete mode 100644 docs/source/projections/images/isea.png delete mode 100644 docs/source/projections/images/kav5.png delete mode 100644 docs/source/projections/images/kav7.png delete mode 100644 docs/source/projections/images/krovak.png delete mode 100644 docs/source/projections/images/labrd.png delete mode 100644 docs/source/projections/images/laea.png delete mode 100644 docs/source/projections/images/lagrng.png delete mode 100644 docs/source/projections/images/larr.png delete mode 100644 docs/source/projections/images/lask.png delete mode 100644 docs/source/projections/images/lcc.png delete mode 100644 docs/source/projections/images/lcca.png delete mode 100644 docs/source/projections/images/leac.png delete mode 100644 docs/source/projections/images/lee_os.png delete mode 100644 docs/source/projections/images/loxim.png delete mode 100644 docs/source/projections/images/lsat.png delete mode 100644 docs/source/projections/images/mbt_fps.png delete mode 100644 docs/source/projections/images/mbt_s.png delete mode 100644 docs/source/projections/images/mbtfpp.png delete mode 100644 docs/source/projections/images/mbtfpq.png delete mode 100644 docs/source/projections/images/mbtfps.png delete mode 100644 docs/source/projections/images/merc.png delete mode 100644 docs/source/projections/images/mil_os.png delete mode 100644 docs/source/projections/images/mill.png delete mode 100644 docs/source/projections/images/misrsom.png delete mode 100644 docs/source/projections/images/moll.png delete mode 100644 docs/source/projections/images/murd1.png delete mode 100644 docs/source/projections/images/murd2.png delete mode 100644 docs/source/projections/images/murd3.png delete mode 100644 docs/source/projections/images/natearth.png delete mode 100644 docs/source/projections/images/natearth2.png delete mode 100644 docs/source/projections/images/nell.png delete mode 100644 docs/source/projections/images/nell_h.png delete mode 100644 docs/source/projections/images/nicol.png delete mode 100644 docs/source/projections/images/nsper.png delete mode 100644 docs/source/projections/images/nzmg.png delete mode 100644 docs/source/projections/images/ob_tran.png delete mode 100644 docs/source/projections/images/ocea.png delete mode 100644 docs/source/projections/images/oea.png delete mode 100644 docs/source/projections/images/omerc.png delete mode 100644 docs/source/projections/images/ortel.png delete mode 100644 docs/source/projections/images/ortho.png delete mode 100644 docs/source/projections/images/patterson.png delete mode 100644 docs/source/projections/images/pconic.png delete mode 100644 docs/source/projections/images/poly.png delete mode 100644 docs/source/projections/images/putp1.png delete mode 100644 docs/source/projections/images/putp2.png delete mode 100644 docs/source/projections/images/putp3.png delete mode 100644 docs/source/projections/images/putp3p.png delete mode 100644 docs/source/projections/images/putp4p.png delete mode 100644 docs/source/projections/images/putp5.png delete mode 100644 docs/source/projections/images/putp5p.png delete mode 100644 docs/source/projections/images/putp6.png delete mode 100644 docs/source/projections/images/putp6p.png delete mode 100644 docs/source/projections/images/qsc.png delete mode 100644 docs/source/projections/images/qua_aut.png delete mode 100644 docs/source/projections/images/rhealpix.png delete mode 100644 docs/source/projections/images/robin.png delete mode 100644 docs/source/projections/images/rouss.png delete mode 100644 docs/source/projections/images/rpoly.png delete mode 100644 docs/source/projections/images/sinu.png delete mode 100644 docs/source/projections/images/somerc.png delete mode 100644 docs/source/projections/images/stere.png delete mode 100644 docs/source/projections/images/sterea.png delete mode 100644 docs/source/projections/images/tcc.png delete mode 100644 docs/source/projections/images/tcea.png delete mode 100644 docs/source/projections/images/tissot.png delete mode 100644 docs/source/projections/images/tmerc.png delete mode 100644 docs/source/projections/images/tpeqd.png delete mode 100644 docs/source/projections/images/tpers.png delete mode 100644 docs/source/projections/images/ups.png delete mode 100644 docs/source/projections/images/urm5.png delete mode 100644 docs/source/projections/images/urmfps.png delete mode 100644 docs/source/projections/images/utm.png delete mode 100644 docs/source/projections/images/vandg.png delete mode 100644 docs/source/projections/images/vandg2.png delete mode 100644 docs/source/projections/images/vandg3.png delete mode 100644 docs/source/projections/images/vandg4.png delete mode 100644 docs/source/projections/images/vitk1.png delete mode 100644 docs/source/projections/images/wag1.png delete mode 100644 docs/source/projections/images/wag2.png delete mode 100644 docs/source/projections/images/wag3.png delete mode 100644 docs/source/projections/images/wag4.png delete mode 100644 docs/source/projections/images/wag5.png delete mode 100644 docs/source/projections/images/wag6.png delete mode 100644 docs/source/projections/images/wag7.png delete mode 100644 docs/source/projections/images/weren.png delete mode 100644 docs/source/projections/images/wink1.png delete mode 100644 docs/source/projections/images/wink2.png delete mode 100644 docs/source/projections/images/wintri.png delete mode 100644 docs/source/projections/imw_p.rst delete mode 100644 docs/source/projections/index.rst delete mode 100644 docs/source/projections/isea.rst delete mode 100644 docs/source/projections/kav5.rst delete mode 100644 docs/source/projections/kav7.rst delete mode 100644 docs/source/projections/krovak.rst delete mode 100644 docs/source/projections/labrd.rst delete mode 100644 docs/source/projections/laea.rst delete mode 100644 docs/source/projections/lagrng.rst delete mode 100644 docs/source/projections/larr.rst delete mode 100644 docs/source/projections/lask.rst delete mode 100644 docs/source/projections/latlon.rst delete mode 100644 docs/source/projections/lcc.rst delete mode 100644 docs/source/projections/lcca.rst delete mode 100644 docs/source/projections/leac.rst delete mode 100644 docs/source/projections/lee_os.rst delete mode 100644 docs/source/projections/lonlat.rst delete mode 100644 docs/source/projections/loxim.rst delete mode 100644 docs/source/projections/lsat.rst delete mode 100644 docs/source/projections/mbt_fps.rst delete mode 100644 docs/source/projections/mbt_s.rst delete mode 100644 docs/source/projections/mbtfpp.rst delete mode 100644 docs/source/projections/mbtfpq.rst delete mode 100644 docs/source/projections/mbtfps.rst delete mode 100644 docs/source/projections/merc.rst delete mode 100644 docs/source/projections/mil_os.rst delete mode 100644 docs/source/projections/mill.rst delete mode 100644 docs/source/projections/moll.rst delete mode 100644 docs/source/projections/murd1.rst delete mode 100644 docs/source/projections/murd2.rst delete mode 100644 docs/source/projections/murd3.rst delete mode 100644 docs/source/projections/natearth.rst delete mode 100644 docs/source/projections/nell.rst delete mode 100644 docs/source/projections/nell_h.rst delete mode 100644 docs/source/projections/nicol.rst delete mode 100644 docs/source/projections/nsper.rst delete mode 100644 docs/source/projections/nzmg.rst delete mode 100644 docs/source/projections/ob_tran.rst delete mode 100644 docs/source/projections/ocea.rst delete mode 100644 docs/source/projections/oea.rst delete mode 100644 docs/source/projections/omerc.rst delete mode 100644 docs/source/projections/ortel.rst delete mode 100644 docs/source/projections/ortho.rst delete mode 100644 docs/source/projections/pconic.rst delete mode 100644 docs/source/projections/poly.rst delete mode 100644 docs/source/projections/putp1.rst delete mode 100644 docs/source/projections/putp2.rst delete mode 100644 docs/source/projections/putp3.rst delete mode 100644 docs/source/projections/putp3p.rst delete mode 100644 docs/source/projections/putp4p.rst delete mode 100644 docs/source/projections/putp5.rst delete mode 100644 docs/source/projections/putp5p.rst delete mode 100644 docs/source/projections/putp6.rst delete mode 100644 docs/source/projections/putp6p.rst delete mode 100644 docs/source/projections/qsc.rst delete mode 100644 docs/source/projections/qua_aut.rst delete mode 100644 docs/source/projections/rhealpix.rst delete mode 100644 docs/source/projections/robin.rst delete mode 100644 docs/source/projections/rouss.rst delete mode 100644 docs/source/projections/rpoly.rst delete mode 100644 docs/source/projections/sinu.rst delete mode 100644 docs/source/projections/somerc.rst delete mode 100644 docs/source/projections/stere.rst delete mode 100644 docs/source/projections/sterea.rst delete mode 100644 docs/source/projections/tcc.rst delete mode 100644 docs/source/projections/tcea.rst delete mode 100644 docs/source/projections/tissot.rst delete mode 100644 docs/source/projections/tmerc.rst delete mode 100644 docs/source/projections/tpeqd.rst delete mode 100644 docs/source/projections/tpers.rst delete mode 100644 docs/source/projections/ups.rst delete mode 100644 docs/source/projections/urm5.rst delete mode 100644 docs/source/projections/urmfps.rst delete mode 100644 docs/source/projections/utm.rst delete mode 100644 docs/source/projections/vandg.rst delete mode 100644 docs/source/projections/vandg2.rst delete mode 100644 docs/source/projections/vandg3.rst delete mode 100644 docs/source/projections/vandg4.rst delete mode 100644 docs/source/projections/vitk1.rst delete mode 100644 docs/source/projections/wag1.rst delete mode 100644 docs/source/projections/wag2.rst delete mode 100644 docs/source/projections/wag3.rst delete mode 100644 docs/source/projections/wag4.rst delete mode 100644 docs/source/projections/wag5.rst delete mode 100644 docs/source/projections/wag6.rst delete mode 100644 docs/source/projections/wag7.rst delete mode 100644 docs/source/projections/weren.rst delete mode 100644 docs/source/projections/wink1.rst delete mode 100644 docs/source/projections/wink2.rst delete mode 100644 docs/source/projections/wintri.rst create mode 100644 docs/source/usage/operations/index.rst create mode 100644 docs/source/usage/operations/projections/aeqd.rst create mode 100644 docs/source/usage/operations/projections/airy.rst create mode 100644 docs/source/usage/operations/projections/aitoff.rst create mode 100644 docs/source/usage/operations/projections/alsk.rst create mode 100644 docs/source/usage/operations/projections/apian.rst create mode 100644 docs/source/usage/operations/projections/august.rst create mode 100644 docs/source/usage/operations/projections/bacon.rst create mode 100644 docs/source/usage/operations/projections/bipc.rst create mode 100644 docs/source/usage/operations/projections/boggs.rst create mode 100644 docs/source/usage/operations/projections/bonne.rst create mode 100644 docs/source/usage/operations/projections/calcofi.rst create mode 100644 docs/source/usage/operations/projections/cass.rst create mode 100644 docs/source/usage/operations/projections/cc.rst create mode 100644 docs/source/usage/operations/projections/cea.rst create mode 100644 docs/source/usage/operations/projections/chamb.rst create mode 100644 docs/source/usage/operations/projections/collg.rst create mode 100644 docs/source/usage/operations/projections/crast.rst create mode 100644 docs/source/usage/operations/projections/denoy.rst create mode 100644 docs/source/usage/operations/projections/eck1.rst create mode 100644 docs/source/usage/operations/projections/eck2.rst create mode 100644 docs/source/usage/operations/projections/eck3.rst create mode 100644 docs/source/usage/operations/projections/eck4.rst create mode 100644 docs/source/usage/operations/projections/eck5.rst create mode 100644 docs/source/usage/operations/projections/eck6.rst create mode 100644 docs/source/usage/operations/projections/eqc.rst create mode 100644 docs/source/usage/operations/projections/eqdc.rst create mode 100644 docs/source/usage/operations/projections/etmerc.rst create mode 100644 docs/source/usage/operations/projections/euler.rst create mode 100644 docs/source/usage/operations/projections/fahey.rst create mode 100644 docs/source/usage/operations/projections/fouc.rst create mode 100644 docs/source/usage/operations/projections/fouc_s.rst create mode 100644 docs/source/usage/operations/projections/gall.rst create mode 100644 docs/source/usage/operations/projections/geos.rst create mode 100644 docs/source/usage/operations/projections/gins8.rst create mode 100644 docs/source/usage/operations/projections/gn_sinu.rst create mode 100644 docs/source/usage/operations/projections/gnom.rst create mode 100644 docs/source/usage/operations/projections/goode.rst create mode 100644 docs/source/usage/operations/projections/gs48.rst create mode 100644 docs/source/usage/operations/projections/gs50.rst create mode 100644 docs/source/usage/operations/projections/gstmerc.rst create mode 100644 docs/source/usage/operations/projections/hammer.rst create mode 100644 docs/source/usage/operations/projections/hatano.rst create mode 100644 docs/source/usage/operations/projections/healpix.rst create mode 100644 docs/source/usage/operations/projections/igh.rst create mode 100644 docs/source/usage/operations/projections/images/aea.png create mode 100644 docs/source/usage/operations/projections/images/aeqd.png create mode 100644 docs/source/usage/operations/projections/images/airy.png create mode 100644 docs/source/usage/operations/projections/images/aitoff.png create mode 100644 docs/source/usage/operations/projections/images/alsk.png create mode 100644 docs/source/usage/operations/projections/images/apian.png create mode 100644 docs/source/usage/operations/projections/images/august.png create mode 100644 docs/source/usage/operations/projections/images/bacon.png create mode 100644 docs/source/usage/operations/projections/images/bipc.png create mode 100644 docs/source/usage/operations/projections/images/boggs.png create mode 100644 docs/source/usage/operations/projections/images/bonne.png create mode 100644 docs/source/usage/operations/projections/images/calcofi.png create mode 100644 docs/source/usage/operations/projections/images/cass.png create mode 100644 docs/source/usage/operations/projections/images/cc.png create mode 100644 docs/source/usage/operations/projections/images/cea.png create mode 100644 docs/source/usage/operations/projections/images/chamb.png create mode 100644 docs/source/usage/operations/projections/images/collg.png create mode 100644 docs/source/usage/operations/projections/images/comill.png create mode 100644 docs/source/usage/operations/projections/images/crast.png create mode 100644 docs/source/usage/operations/projections/images/denoy.png create mode 100644 docs/source/usage/operations/projections/images/eck1.png create mode 100644 docs/source/usage/operations/projections/images/eck2.png create mode 100644 docs/source/usage/operations/projections/images/eck3.png create mode 100644 docs/source/usage/operations/projections/images/eck4.png create mode 100644 docs/source/usage/operations/projections/images/eck5.png create mode 100644 docs/source/usage/operations/projections/images/eck6.png create mode 100644 docs/source/usage/operations/projections/images/eqc.png create mode 100644 docs/source/usage/operations/projections/images/eqdc.png create mode 100644 docs/source/usage/operations/projections/images/etmerc.png create mode 100644 docs/source/usage/operations/projections/images/euler.png create mode 100644 docs/source/usage/operations/projections/images/fahey.png create mode 100644 docs/source/usage/operations/projections/images/fouc.png create mode 100644 docs/source/usage/operations/projections/images/fouc_s.png create mode 100644 docs/source/usage/operations/projections/images/gall.png create mode 100644 docs/source/usage/operations/projections/images/geos.png create mode 100644 docs/source/usage/operations/projections/images/gins8.png create mode 100644 docs/source/usage/operations/projections/images/gn_sinu.png create mode 100644 docs/source/usage/operations/projections/images/gnom.png create mode 100644 docs/source/usage/operations/projections/images/goode.png create mode 100644 docs/source/usage/operations/projections/images/gs48.png create mode 100644 docs/source/usage/operations/projections/images/gs50.png create mode 100644 docs/source/usage/operations/projections/images/gstmerc.png create mode 100644 docs/source/usage/operations/projections/images/hammer.png create mode 100644 docs/source/usage/operations/projections/images/hatano.png create mode 100644 docs/source/usage/operations/projections/images/healpix.png create mode 100644 docs/source/usage/operations/projections/images/igh.png create mode 100644 docs/source/usage/operations/projections/images/imw_p.png create mode 100644 docs/source/usage/operations/projections/images/isea.png create mode 100644 docs/source/usage/operations/projections/images/kav5.png create mode 100644 docs/source/usage/operations/projections/images/kav7.png create mode 100644 docs/source/usage/operations/projections/images/krovak.png create mode 100644 docs/source/usage/operations/projections/images/labrd.png create mode 100644 docs/source/usage/operations/projections/images/laea.png create mode 100644 docs/source/usage/operations/projections/images/lagrng.png create mode 100644 docs/source/usage/operations/projections/images/larr.png create mode 100644 docs/source/usage/operations/projections/images/lask.png create mode 100644 docs/source/usage/operations/projections/images/lcc.png create mode 100644 docs/source/usage/operations/projections/images/lcca.png create mode 100644 docs/source/usage/operations/projections/images/leac.png create mode 100644 docs/source/usage/operations/projections/images/lee_os.png create mode 100644 docs/source/usage/operations/projections/images/loxim.png create mode 100644 docs/source/usage/operations/projections/images/lsat.png create mode 100644 docs/source/usage/operations/projections/images/mbt_fps.png create mode 100644 docs/source/usage/operations/projections/images/mbt_s.png create mode 100644 docs/source/usage/operations/projections/images/mbtfpp.png create mode 100644 docs/source/usage/operations/projections/images/mbtfpq.png create mode 100644 docs/source/usage/operations/projections/images/mbtfps.png create mode 100644 docs/source/usage/operations/projections/images/merc.png create mode 100644 docs/source/usage/operations/projections/images/mil_os.png create mode 100644 docs/source/usage/operations/projections/images/mill.png create mode 100644 docs/source/usage/operations/projections/images/misrsom.png create mode 100644 docs/source/usage/operations/projections/images/moll.png create mode 100644 docs/source/usage/operations/projections/images/murd1.png create mode 100644 docs/source/usage/operations/projections/images/murd2.png create mode 100644 docs/source/usage/operations/projections/images/murd3.png create mode 100644 docs/source/usage/operations/projections/images/natearth.png create mode 100644 docs/source/usage/operations/projections/images/natearth2.png create mode 100644 docs/source/usage/operations/projections/images/nell.png create mode 100644 docs/source/usage/operations/projections/images/nell_h.png create mode 100644 docs/source/usage/operations/projections/images/nicol.png create mode 100644 docs/source/usage/operations/projections/images/nsper.png create mode 100644 docs/source/usage/operations/projections/images/nzmg.png create mode 100644 docs/source/usage/operations/projections/images/ob_tran.png create mode 100644 docs/source/usage/operations/projections/images/ocea.png create mode 100644 docs/source/usage/operations/projections/images/oea.png create mode 100644 docs/source/usage/operations/projections/images/omerc.png create mode 100644 docs/source/usage/operations/projections/images/ortel.png create mode 100644 docs/source/usage/operations/projections/images/ortho.png create mode 100644 docs/source/usage/operations/projections/images/patterson.png create mode 100644 docs/source/usage/operations/projections/images/pconic.png create mode 100644 docs/source/usage/operations/projections/images/poly.png create mode 100644 docs/source/usage/operations/projections/images/putp1.png create mode 100644 docs/source/usage/operations/projections/images/putp2.png create mode 100644 docs/source/usage/operations/projections/images/putp3.png create mode 100644 docs/source/usage/operations/projections/images/putp3p.png create mode 100644 docs/source/usage/operations/projections/images/putp4p.png create mode 100644 docs/source/usage/operations/projections/images/putp5.png create mode 100644 docs/source/usage/operations/projections/images/putp5p.png create mode 100644 docs/source/usage/operations/projections/images/putp6.png create mode 100644 docs/source/usage/operations/projections/images/putp6p.png create mode 100644 docs/source/usage/operations/projections/images/qsc.png create mode 100644 docs/source/usage/operations/projections/images/qua_aut.png create mode 100644 docs/source/usage/operations/projections/images/rhealpix.png create mode 100644 docs/source/usage/operations/projections/images/robin.png create mode 100644 docs/source/usage/operations/projections/images/rouss.png create mode 100644 docs/source/usage/operations/projections/images/rpoly.png create mode 100644 docs/source/usage/operations/projections/images/sinu.png create mode 100644 docs/source/usage/operations/projections/images/somerc.png create mode 100644 docs/source/usage/operations/projections/images/stere.png create mode 100644 docs/source/usage/operations/projections/images/sterea.png create mode 100644 docs/source/usage/operations/projections/images/tcc.png create mode 100644 docs/source/usage/operations/projections/images/tcea.png create mode 100644 docs/source/usage/operations/projections/images/tissot.png create mode 100644 docs/source/usage/operations/projections/images/tmerc.png create mode 100644 docs/source/usage/operations/projections/images/tpeqd.png create mode 100644 docs/source/usage/operations/projections/images/tpers.png create mode 100644 docs/source/usage/operations/projections/images/ups.png create mode 100644 docs/source/usage/operations/projections/images/urm5.png create mode 100644 docs/source/usage/operations/projections/images/urmfps.png create mode 100644 docs/source/usage/operations/projections/images/utm.png create mode 100644 docs/source/usage/operations/projections/images/vandg.png create mode 100644 docs/source/usage/operations/projections/images/vandg2.png create mode 100644 docs/source/usage/operations/projections/images/vandg3.png create mode 100644 docs/source/usage/operations/projections/images/vandg4.png create mode 100644 docs/source/usage/operations/projections/images/vitk1.png create mode 100644 docs/source/usage/operations/projections/images/wag1.png create mode 100644 docs/source/usage/operations/projections/images/wag2.png create mode 100644 docs/source/usage/operations/projections/images/wag3.png create mode 100644 docs/source/usage/operations/projections/images/wag4.png create mode 100644 docs/source/usage/operations/projections/images/wag5.png create mode 100644 docs/source/usage/operations/projections/images/wag6.png create mode 100644 docs/source/usage/operations/projections/images/wag7.png create mode 100644 docs/source/usage/operations/projections/images/weren.png create mode 100644 docs/source/usage/operations/projections/images/wink1.png create mode 100644 docs/source/usage/operations/projections/images/wink2.png create mode 100644 docs/source/usage/operations/projections/images/wintri.png create mode 100644 docs/source/usage/operations/projections/imw_p.rst create mode 100644 docs/source/usage/operations/projections/index.rst create mode 100644 docs/source/usage/operations/projections/isea.rst create mode 100644 docs/source/usage/operations/projections/kav5.rst create mode 100644 docs/source/usage/operations/projections/kav7.rst create mode 100644 docs/source/usage/operations/projections/krovak.rst create mode 100644 docs/source/usage/operations/projections/labrd.rst create mode 100644 docs/source/usage/operations/projections/laea.rst create mode 100644 docs/source/usage/operations/projections/lagrng.rst create mode 100644 docs/source/usage/operations/projections/larr.rst create mode 100644 docs/source/usage/operations/projections/lask.rst create mode 100644 docs/source/usage/operations/projections/latlon.rst create mode 100644 docs/source/usage/operations/projections/lcc.rst create mode 100644 docs/source/usage/operations/projections/lcca.rst create mode 100644 docs/source/usage/operations/projections/leac.rst create mode 100644 docs/source/usage/operations/projections/lee_os.rst create mode 100644 docs/source/usage/operations/projections/lonlat.rst create mode 100644 docs/source/usage/operations/projections/loxim.rst create mode 100644 docs/source/usage/operations/projections/lsat.rst create mode 100644 docs/source/usage/operations/projections/mbt_fps.rst create mode 100644 docs/source/usage/operations/projections/mbt_s.rst create mode 100644 docs/source/usage/operations/projections/mbtfpp.rst create mode 100644 docs/source/usage/operations/projections/mbtfpq.rst create mode 100644 docs/source/usage/operations/projections/mbtfps.rst create mode 100644 docs/source/usage/operations/projections/merc.rst create mode 100644 docs/source/usage/operations/projections/mil_os.rst create mode 100644 docs/source/usage/operations/projections/mill.rst create mode 100644 docs/source/usage/operations/projections/moll.rst create mode 100644 docs/source/usage/operations/projections/murd1.rst create mode 100644 docs/source/usage/operations/projections/murd2.rst create mode 100644 docs/source/usage/operations/projections/murd3.rst create mode 100644 docs/source/usage/operations/projections/natearth.rst create mode 100644 docs/source/usage/operations/projections/nell.rst create mode 100644 docs/source/usage/operations/projections/nell_h.rst create mode 100644 docs/source/usage/operations/projections/nicol.rst create mode 100644 docs/source/usage/operations/projections/nsper.rst create mode 100644 docs/source/usage/operations/projections/nzmg.rst create mode 100644 docs/source/usage/operations/projections/ob_tran.rst create mode 100644 docs/source/usage/operations/projections/ocea.rst create mode 100644 docs/source/usage/operations/projections/oea.rst create mode 100644 docs/source/usage/operations/projections/omerc.rst create mode 100644 docs/source/usage/operations/projections/ortel.rst create mode 100644 docs/source/usage/operations/projections/ortho.rst create mode 100644 docs/source/usage/operations/projections/pconic.rst create mode 100644 docs/source/usage/operations/projections/poly.rst create mode 100644 docs/source/usage/operations/projections/putp1.rst create mode 100644 docs/source/usage/operations/projections/putp2.rst create mode 100644 docs/source/usage/operations/projections/putp3.rst create mode 100644 docs/source/usage/operations/projections/putp3p.rst create mode 100644 docs/source/usage/operations/projections/putp4p.rst create mode 100644 docs/source/usage/operations/projections/putp5.rst create mode 100644 docs/source/usage/operations/projections/putp5p.rst create mode 100644 docs/source/usage/operations/projections/putp6.rst create mode 100644 docs/source/usage/operations/projections/putp6p.rst create mode 100644 docs/source/usage/operations/projections/qsc.rst create mode 100644 docs/source/usage/operations/projections/qua_aut.rst create mode 100644 docs/source/usage/operations/projections/rhealpix.rst create mode 100644 docs/source/usage/operations/projections/robin.rst create mode 100644 docs/source/usage/operations/projections/rouss.rst create mode 100644 docs/source/usage/operations/projections/rpoly.rst create mode 100644 docs/source/usage/operations/projections/sinu.rst create mode 100644 docs/source/usage/operations/projections/somerc.rst create mode 100644 docs/source/usage/operations/projections/stere.rst create mode 100644 docs/source/usage/operations/projections/sterea.rst create mode 100644 docs/source/usage/operations/projections/tcc.rst create mode 100644 docs/source/usage/operations/projections/tcea.rst create mode 100644 docs/source/usage/operations/projections/tissot.rst create mode 100644 docs/source/usage/operations/projections/tmerc.rst create mode 100644 docs/source/usage/operations/projections/tpeqd.rst create mode 100644 docs/source/usage/operations/projections/tpers.rst create mode 100644 docs/source/usage/operations/projections/ups.rst create mode 100644 docs/source/usage/operations/projections/urm5.rst create mode 100644 docs/source/usage/operations/projections/urmfps.rst create mode 100644 docs/source/usage/operations/projections/utm.rst create mode 100644 docs/source/usage/operations/projections/vandg.rst create mode 100644 docs/source/usage/operations/projections/vandg2.rst create mode 100644 docs/source/usage/operations/projections/vandg3.rst create mode 100644 docs/source/usage/operations/projections/vandg4.rst create mode 100644 docs/source/usage/operations/projections/vitk1.rst create mode 100644 docs/source/usage/operations/projections/wag1.rst create mode 100644 docs/source/usage/operations/projections/wag2.rst create mode 100644 docs/source/usage/operations/projections/wag3.rst create mode 100644 docs/source/usage/operations/projections/wag4.rst create mode 100644 docs/source/usage/operations/projections/wag5.rst create mode 100644 docs/source/usage/operations/projections/wag6.rst create mode 100644 docs/source/usage/operations/projections/wag7.rst create mode 100644 docs/source/usage/operations/projections/weren.rst create mode 100644 docs/source/usage/operations/projections/wink1.rst create mode 100644 docs/source/usage/operations/projections/wink2.rst create mode 100644 docs/source/usage/operations/projections/wintri.rst 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 (limited to 'docs/source') diff --git a/docs/source/index.rst b/docs/source/index.rst index bfb9aee6..324d52fc 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/projections/aeqd.rst b/docs/source/projections/aeqd.rst deleted file mode 100644 index 949cd8a0..00000000 --- a/docs/source/projections/aeqd.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _aeqd: - -******************************************************************************** -Azimuthal Equidistant -******************************************************************************** - -.. image:: ./images/aeqd.png - :scale: 50% - :alt: Azimuthal Equidistant - diff --git a/docs/source/projections/airy.rst b/docs/source/projections/airy.rst deleted file mode 100644 index 307af3e3..00000000 --- a/docs/source/projections/airy.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _airy: - -******************************************************************************** -Airy -******************************************************************************** - -.. image:: ./images/airy.png - :scale: 50% - :alt: Airy - diff --git a/docs/source/projections/aitoff.rst b/docs/source/projections/aitoff.rst deleted file mode 100644 index 4d681468..00000000 --- a/docs/source/projections/aitoff.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _aitoff: - -******************************************************************************** -Aitoff -******************************************************************************** - -.. image:: ./images/aitoff.png - :scale: 50% - :alt: Aitoff - diff --git a/docs/source/projections/alsk.rst b/docs/source/projections/alsk.rst deleted file mode 100644 index f7a7a0ef..00000000 --- a/docs/source/projections/alsk.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _alsk: - -******************************************************************************** -Mod. Stererographics of Alaska -******************************************************************************** - -.. image:: ./images/alsk.png - :scale: 50% - :alt: Mod. Stererographics of Alaska - diff --git a/docs/source/projections/apian.rst b/docs/source/projections/apian.rst deleted file mode 100644 index add501ea..00000000 --- a/docs/source/projections/apian.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _apian: - -******************************************************************************** -Apian Globular I -******************************************************************************** - -.. image:: ./images/apian.png - :scale: 50% - :alt: Apian Globular I - diff --git a/docs/source/projections/august.rst b/docs/source/projections/august.rst deleted file mode 100644 index e2ad3516..00000000 --- a/docs/source/projections/august.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _august: - -******************************************************************************** -August Epicycloidal -******************************************************************************** - -.. image:: ./images/august.png - :scale: 50% - :alt: August Epicycloidal - diff --git a/docs/source/projections/bacon.rst b/docs/source/projections/bacon.rst deleted file mode 100644 index a87ea7d8..00000000 --- a/docs/source/projections/bacon.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _bacon: - -******************************************************************************** -Bacon Globular -******************************************************************************** - -.. image:: ./images/bacon.png - :scale: 50% - :alt: Bacon Globular - diff --git a/docs/source/projections/bipc.rst b/docs/source/projections/bipc.rst deleted file mode 100644 index 7045f04a..00000000 --- a/docs/source/projections/bipc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _bipc: - -******************************************************************************** -Bipolar conic of western hemisphere -******************************************************************************** - -.. image:: ./images/bipc.png - :scale: 50% - :alt: Bipolar conic of western hemisphere - diff --git a/docs/source/projections/boggs.rst b/docs/source/projections/boggs.rst deleted file mode 100644 index 1dd7d19f..00000000 --- a/docs/source/projections/boggs.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _boggs: - -******************************************************************************** -Boggs Eumorphic -******************************************************************************** - -.. image:: ./images/boggs.png - :scale: 50% - :alt: Boggs Eumorphic - diff --git a/docs/source/projections/bonne.rst b/docs/source/projections/bonne.rst deleted file mode 100644 index ef87d7c9..00000000 --- a/docs/source/projections/bonne.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _bonne: - -******************************************************************************** -Bonne (Werner lat_1=90) -******************************************************************************** - -.. image:: ./images/bonne.png - :scale: 50% - :alt: Bonne (Werner lat_1=90) - diff --git a/docs/source/projections/calcofi.rst b/docs/source/projections/calcofi.rst deleted file mode 100644 index 3c1e5f7a..00000000 --- a/docs/source/projections/calcofi.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. _calcofi: - -******************************************************************************** -Cal Coop Ocean Fish Invest Lines/Stations -******************************************************************************** - -The CalCOFI pseudo-projection is the line and station coordinate system of the -California Cooperative Oceanic Fisheries Investigations program, known as CalCOFI, for sampling offshore of the west coast of the U.S. and Mexico. - -+---------------------+----------------------------------------------------------+ -| **Classification** | Conformal cylindrical | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical and elliptical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Only valid for the west coast of USA and Mexico | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Frank Warmerdam | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `No special options for this projection` | -+---------------------+----------------------------------------------------------+ - - -.. image:: ../../images/calcofi.png - :scale: 50% - :align: center - :alt: Cal Coop Ocean Fish Invest Lines/Stations - -The coordinate system is based on the Mercator projection with units rotated -30 -degrees from the meridian so that they are oriented with the coastline of the Southern California Bight and Baja California. -Lines increase from Northwest to Southeast. -A unit of line is 12 nautical miles. Stations increase from inshore to offshore. -A unit of station is equal to 4 nautical miles. -The rotation point is located at line 80, station 60, or 34.15 degrees N, -121.15 degrees W, and is depicted by the red dot in the figure. -By convention, the ellipsoid of Clarke 1866 is used to calculate CalCOFI coordinates. - -The CalCOFI program is a joint research effort by the U.S. National Oceanic and -Atmospheric Administration, University of California Scripps Oceanographic Institute, and California Department of Fish and Game. -Surveys have been conducted for the CalCOFI program since 1951, creating one of the oldest and most scientifically valuable joint oceanographic and fisheries data sets in the world. -The CalCOFI line and station coordinate system is now used by several other programs including the Investigaciones Mexicanas de la Corriente de California (IMECOCAL) program offshore of Baja California. -The figure depicts some commonly sampled locations from line 40 to line 156.7 and offshore to station 120. Blue numbers indicate line (bottom) or station (left) numbers along the grid. Note that lines spaced at approximate 3-1/3 intervals are commonly sampled, e.g., lines 43.3 and 46.7. - -Usage -############################################################################### - -A typical forward CalCOFI projection would be from lon/lat coordinates on the -Clark 1866 ellipsoid. -For example:: - - proj +proj=calcofi +ellps=clrk66 -E <`_ -#. `The Investigaciones Mexicanas de la Corriente de California `_ - - - - - - - - - - - - - - diff --git a/docs/source/projections/cass.rst b/docs/source/projections/cass.rst deleted file mode 100644 index 83f8c2ce..00000000 --- a/docs/source/projections/cass.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. _cass: - -******************************************************************************** -Cassini (Cassini-Soldner) -******************************************************************************** - -Although the Cassini projection has been largely replaced by the Transverse Mercator, it is still in limited use outside the United States and was one of the major topographic mapping projections until the early 20th century. - -+---------------------+-------------------------------------------------------------------------+ -| **Classification** | Transverse and oblique cylindrical | -+---------------------+-------------------------------------------------------------------------+ -| **Available forms** | Forward and inverse, Spherical and Elliptical | -+---------------------+-------------------------------------------------------------------------+ -| **Defined area** | Global, but best used near the central meridian with long, narrow areas | -+---------------------+-------------------------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+-------------------------------------------------------------------------+ -| **Options** | -+---------------------+-------------------------------------------------------------------------+ -| `+lat_0` | Latitude of origin (Default to 0) | -+---------------------+-------------------------------------------------------------------------+ - -.. image:: ./images/cass.png - :scale: 50% - :alt: Cassini - -Usage -##### - -There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century [Steers1970]_. -Many of these maps were prepared at a scale of 1:2,500. -The Cassini-Soldner was also used for the detailed mapping of many German states during the same period. - - -Example using EPSG 30200 (Trinidad 1903, units in clarke's links):: - - $ echo 0.17453293 -1.08210414 | proj +proj=cass +lat_0=10.44166666666667 +lon_0=-61.33333333333334 +x_0=86501.46392051999 +y_0=65379.0134283 +a=6378293.645208759 +b=6356617.987679838 +to_meter=0.201166195164 +no_defs - 66644.94 82536.22 - -Example using EPSG 3068 (Soldner Berlin):: - - $ echo 13.5 52.4 | proj +proj=cass +lat_0=52.41864827777778 +lon_0=13.62720366666667 +x_0=40000 +y_0=10000 +ellps=bessel +datum=potsdam +units=m +no_defs - 31343.05 7932.76 - - -Mathematical definition -####################### - -The formulas describing the Cassini projection are taken from Snyder's [Snyder1987]_. - -:math:`\phi_0` is the latitude of origin that match the center of the map (default to 0). It can be set with ``+lat_0``. - - -Spherical form -============== - -Forward projection ------------------- - -.. math:: - - x = \arcsin(\cos(\phi) \sin(\lambda)) - -.. math:: - - y = \arctan2(\tan(\phi), \cos(\lambda)) - \phi_0 - -Inverse projection ------------------- - -.. math:: - - \phi = \arcsin(\sin(y+\phi_0) \cos(x)) - -.. math:: - - \lambda = \arctan2(\tan(x), \cos(y+\phi_0)) - -Elliptical form -=============== - -Forward projection ------------------- - -.. math:: - - N = (1 - e^2 \sin^2(\phi))^{-1/2} - -.. math:: - - T = \tan^2(\phi) - -.. math:: - - A = \lambda \cos(\phi) - -.. math:: - - C = \frac{e^2}{1-e^2} cos^2(\phi) - -.. math:: - - x = N ( A - T \frac{A^3}{6} - (8-T+8C)T\frac{A^5}{120}) - -.. math:: - - y = M(\phi) - M(\phi_0) + N \tan(\phi)(\frac{A^2}{2} + (5-T+6C)\frac{A^4}{24}) - -and M() is the meridionial distance function. - -Inverse projection ------------------- - -.. math:: - - \phi' = M^{-1}(M(\phi_0)+y) - -if :math:`\phi' = \frac{\pi}{2}` then :math:`\phi=\phi'` and :math:`\lambda=0` - -otherwise evaluate T and N above using :math:`\phi'` and - -.. math:: - - R = (1 - e^2)(1 - e^2 sin^2 \phi')^{-3/2} - -.. math:: - - D = x/N - -.. math:: - - \phi = \phi' - \tan \phi' \frac{N}{R}(\frac{D^2}{2}-(1+3T)\frac{D^4}{24}) - -.. math:: - - \lambda = \frac{(D - T\frac{D^3}{3} + (1+3T)T\frac{D^5}{15})}{\cos \phi'} - -.. _further-reading: - -Further reading -############### - -#. `Wikipedia `_ -#. [Snyder1987]_ -#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas `_ diff --git a/docs/source/projections/cc.rst b/docs/source/projections/cc.rst deleted file mode 100644 index 5b30e6c6..00000000 --- a/docs/source/projections/cc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _cc: - -******************************************************************************** -Central Cylindrical -******************************************************************************** - -.. image:: ./images/cc.png - :scale: 50% - :alt: Central Cylindrical - diff --git a/docs/source/projections/cea.rst b/docs/source/projections/cea.rst deleted file mode 100644 index 20ebc285..00000000 --- a/docs/source/projections/cea.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _cea: - -******************************************************************************** -Equal Area Cylindrical -******************************************************************************** - -.. image:: ./images/cea.png - :scale: 50% - :alt: Equal Area Cylindrical - diff --git a/docs/source/projections/chamb.rst b/docs/source/projections/chamb.rst deleted file mode 100644 index 2ec9bffe..00000000 --- a/docs/source/projections/chamb.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _chamb: - -******************************************************************************** -Chamberlin Trimetric -******************************************************************************** - -.. image:: ./images/chamb.png - :scale: 50% - :alt: Chamberlin Trimetric - diff --git a/docs/source/projections/collg.rst b/docs/source/projections/collg.rst deleted file mode 100644 index aa16182a..00000000 --- a/docs/source/projections/collg.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _collg: - -******************************************************************************** -Collignon -******************************************************************************** - -.. image:: ./images/collg.png - :scale: 50% - :alt: Collignon - diff --git a/docs/source/projections/crast.rst b/docs/source/projections/crast.rst deleted file mode 100644 index 9d17f274..00000000 --- a/docs/source/projections/crast.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _crast: - -******************************************************************************** -Craster Parabolic (Putnins P4) -******************************************************************************** - -.. image:: ./images/crast.png - :scale: 50% - :alt: Craster Parabolic (Putnins P4) - diff --git a/docs/source/projections/denoy.rst b/docs/source/projections/denoy.rst deleted file mode 100644 index a885ab0e..00000000 --- a/docs/source/projections/denoy.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _denoy: - -******************************************************************************** -Denoyer Semi-Elliptical -******************************************************************************** - -.. image:: ./images/denoy.png - :scale: 50% - :alt: Denoyer Semi-Elliptical - diff --git a/docs/source/projections/eck1.rst b/docs/source/projections/eck1.rst deleted file mode 100644 index 841533ec..00000000 --- a/docs/source/projections/eck1.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _eck1: - -******************************************************************************** -Eckert I -******************************************************************************** - -.. image:: ./images/eck1.png - :scale: 50% - :alt: Eckert I - - -.. math:: - - x &= 2 \sqrt{2/3\pi} \lambda (1- |\phi|/\pi) - - y &= 2 \sqrt{2/3\pi}\phi - - diff --git a/docs/source/projections/eck2.rst b/docs/source/projections/eck2.rst deleted file mode 100644 index b1bd3179..00000000 --- a/docs/source/projections/eck2.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _eck2: - -******************************************************************************** -Eckert II -******************************************************************************** - -.. image:: ./images/eck2.png - :scale: 50% - :alt: Eckert II - diff --git a/docs/source/projections/eck3.rst b/docs/source/projections/eck3.rst deleted file mode 100644 index ecacc32d..00000000 --- a/docs/source/projections/eck3.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _eck3: - -******************************************************************************** -Eckert III -******************************************************************************** - -.. image:: ./images/eck3.png - :scale: 50% - :alt: Eckert III - diff --git a/docs/source/projections/eck4.rst b/docs/source/projections/eck4.rst deleted file mode 100644 index 3fc6a9fd..00000000 --- a/docs/source/projections/eck4.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _eck4: - -******************************************************************************** -Eckert IV -******************************************************************************** - -.. image:: ./images/eck4.png - :scale: 50% - :alt: Eckert IV - - -.. math:: - - x = \lambda(1+cos\phi) / \sqrt{ 2 + \pi } - -.. math:: - y = 2 \phi / \sqrt { 2 + \pi } - - diff --git a/docs/source/projections/eck5.rst b/docs/source/projections/eck5.rst deleted file mode 100644 index 1442d99d..00000000 --- a/docs/source/projections/eck5.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _eck5: - -******************************************************************************** -Eckert V -******************************************************************************** - -.. image:: ./images/eck5.png - :scale: 50% - :alt: Eckert V - diff --git a/docs/source/projections/eck6.rst b/docs/source/projections/eck6.rst deleted file mode 100644 index caeaefa6..00000000 --- a/docs/source/projections/eck6.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _eck6: - -******************************************************************************** -Eckert VI -******************************************************************************** - -.. image:: ./images/eck6.png - :scale: 50% - :alt: Eckert VI - diff --git a/docs/source/projections/eqc.rst b/docs/source/projections/eqc.rst deleted file mode 100644 index be431977..00000000 --- a/docs/source/projections/eqc.rst +++ /dev/null @@ -1,110 +0,0 @@ -.. _eqc: - -******************************************************************************** -Equidistant Cylindrical (Plate Carrée) -******************************************************************************** - -The simplest of all projections. Standard parallels (0° when omitted) may be specified that determine latitude of true scale (k=h=1). - -+---------------------+----------------------------------------------------------+ -| **Classification** | Conformal cylindrical | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global, but best used near the equator | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `+lat_ts` | Latitude of true scale. Defaults to 0.0 | -+---------------------+----------------------------------------------------------+ -| `+lat_0` | Center of the map : latitude of origin | -+---------------------+----------------------------------------------------------+ - -.. image:: ./images/eqc.png - :scale: 50% - :alt: Equidistant Cylindrical (Plate Carrée) - -Usage -######## - -Because of the distortions introduced by this projection, it has little use in navigation or cadastral mapping and finds its main use in thematic mapping. -In particular, the plate carrée has become a standard for global raster datasets, such as Celestia and NASA World Wind, because of the particularly simple relationship between the position of an image pixel on the map and its corresponding geographic location on Earth. - -The following table gives special cases of the cylindrical equidistant projection. - -+---------------------------------------------------------+--------------------------+ -| Projection Name | (lat ts=) :math:`\phi_0` | -+---------------------------------------------------------+--------------------------+ -| Plain/Plane Chart | 0° | -+---------------------------------------------------------+--------------------------+ -| Simple Cylindrical | 0° | -+---------------------------------------------------------+--------------------------+ -| Plate Carrée | 0° | -+---------------------------------------------------------+--------------------------+ -| Ronald Miller—minimum overall scale distortion | 37°30′ | -+---------------------------------------------------------+--------------------------+ -| E.Grafarend and A.Niermann | 42° | -+---------------------------------------------------------+--------------------------+ -| Ronald Miller—minimum continental scale distortion | 43°30′ | -+---------------------------------------------------------+--------------------------+ -| Gall Isographic | 45° | -+---------------------------------------------------------+--------------------------+ -| Ronald Miller Equirectangular | 50°30′ | -+---------------------------------------------------------+--------------------------+ -| E.Grafarend and A.Niermann minimum linear distortion | 61°7′ | -+---------------------------------------------------------+--------------------------+ - - -Example using EPSG 32662 (WGS84 Plate Carrée):: - - $ echo 2 47 | proj +proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs - 222638.98 5232016.07 - -Example using Plate Carrée projection with true scale at latitude 30° and central meridian 90°W:: - - $ echo -88 30 | proj +proj=eqc +lat_ts=30 +lat_0=90w - -8483684.61 13358338.90 - - -Mathematical definition -####################### - -The formulas describing the Equidistant Cylindrical projection are all taken from Snyder's [Snyder1987]_. - -:math:`\phi_{ts}` is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set with ``+lat_ts``. - -:math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. - - -Forward projection -================== - -.. math:: - - x = \lambda \cos \phi_{ts} - -.. math:: - - y = \phi - \phi_0 - -Inverse projection -================== - -.. math:: - - \lambda = x / cos \phi_{ts} - -.. math:: - - \phi = y + \phi_0 - - -Further reading -############### - -#. `Wikipedia `_ -#. `Wolfram Mathworld `_ - - diff --git a/docs/source/projections/eqdc.rst b/docs/source/projections/eqdc.rst deleted file mode 100644 index 3ee5999d..00000000 --- a/docs/source/projections/eqdc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _eqdc: - -******************************************************************************** -Equidistant Conic -******************************************************************************** - -.. image:: ./images/eqdc.png - :scale: 50% - :alt: Equidistant Conic - diff --git a/docs/source/projections/etmerc.rst b/docs/source/projections/etmerc.rst deleted file mode 100644 index b7f89032..00000000 --- a/docs/source/projections/etmerc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _etmerc: - -******************************************************************************** -Extended Transverse Mercator -******************************************************************************** - -.. image:: ./images/etmerc.png - :scale: 50% - :alt: Extended Transverse Mercator - diff --git a/docs/source/projections/euler.rst b/docs/source/projections/euler.rst deleted file mode 100644 index e495063f..00000000 --- a/docs/source/projections/euler.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _euler: - -******************************************************************************** -Euler -******************************************************************************** - -.. image:: ./images/euler.png - :scale: 50% - :alt: Euler - diff --git a/docs/source/projections/fahey.rst b/docs/source/projections/fahey.rst deleted file mode 100644 index 2e09337f..00000000 --- a/docs/source/projections/fahey.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _fahey: - -******************************************************************************** -Fahey -******************************************************************************** - -.. image:: ./images/fahey.png - :scale: 50% - :alt: Fahey - diff --git a/docs/source/projections/fouc.rst b/docs/source/projections/fouc.rst deleted file mode 100644 index 7467dcb1..00000000 --- a/docs/source/projections/fouc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _fouc: - -******************************************************************************** -Foucaut -******************************************************************************** - -.. image:: ./images/fouc.png - :scale: 50% - :alt: Foucaut - diff --git a/docs/source/projections/fouc_s.rst b/docs/source/projections/fouc_s.rst deleted file mode 100644 index ac353adb..00000000 --- a/docs/source/projections/fouc_s.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _fouc_s: - -******************************************************************************** -Foucaut Sinusoidal -******************************************************************************** - -.. image:: ./images/fouc_s.png - :scale: 50% - :alt: Foucaut Sinusoidal - - -The `y`-axis is based upon a weighted mean of the cylindrical equal-area and -the sinusoidal projections. Parameter :math:`n=n` is the weighting factor where -:math:`0 <= n <= 1`. - -.. math:: - - x &= \lambda \cos \phi / (n + (1 - n) \ cos \phi) - - y &= n \phi + (1 - n) \sin \phi - -For the inverse, the Newton-Raphson method can be used to determine -:math:`\phi` from the equation for :math:`y` above. As :math:`n \rightarrow 0` and -:math:`\phi \rightarrow \pi/2`, convergence is slow but for :math:`n = 0`, :math:`\phi = -\sin^1y` diff --git a/docs/source/projections/gall.rst b/docs/source/projections/gall.rst deleted file mode 100644 index b9120d9f..00000000 --- a/docs/source/projections/gall.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. _gall: - -******************************************************************************** -Gall (Gall Stereographic) -******************************************************************************** - -The Gall stereographic projection, presented by James Gall in 1855, is a cylindrical projection. -It is neither equal-area nor conformal but instead tries to balance the distortion inherent in any projection. - -+---------------------+--------------------------------------------------------------------------------+ -| **Classification** | Transverse and oblique cylindrical | -+---------------------+--------------------------------------------------------------------------------+ -| **Available forms** | Forward and inverse, Spherical | -+---------------------+--------------------------------------------------------------------------------+ -| **Defined area** | Global | -+---------------------+--------------------------------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+--------------------------------------------------------------------------------+ -| **Options** | No special options for this projection | -+---------------------+--------------------------------------------------------------------------------+ - - -.. image:: ./images/gall.png - :scale: 50% - :alt: Gall (Gall Stereographic) - -Usage -##### - -The need for a world map which avoids some of the scale exaggeration of the Mercator projection has led to some commonly used cylindrical modifications, as well as to other modifications which are not cylindrical. -The earliest common cylindrical example was developed by James Gall of Edinburgh about 1855 (Gall, 1885, p. 119-123). -His meridians are equally spaced, but the parallels are spaced at increasing intervals away from the Equator. -The parallels of latitude are actually projected onto a cylinder wrapped about the sphere, but cutting it at lats. 45° N. and S., the point of perspective being a point on the Equator opposite the meridian being projected. -It is used in several British atlases, but seldom in the United States. -The Gall projection is neither conformal nor equal-area, but has a blend of various features. -Unlike the Mercator, the Gall shows the poles as lines running across the top and bottom of the map. - - -Example using Gall Stereographical :: - - $ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs - 708432.90 5193386.36 - -Example using Gall Stereographical (Central meridian 90°W) :: - - $ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs - 7792761.91 5193386.36 - -Mathematical definition -####################### - -The formulas describing the Gall Stereographical are all taken from Snyder's [Snyder1993]_. - -Spherical form -************** - -Forward projection -================== - -.. math:: - - x = \frac{\lambda}{\sqrt{2}} - -.. math:: - - y = (1+\frac{\sqrt{2}}{2}) \tan(\phi/2) - -Inverse projection -================== - -.. math:: - - \phi = 2 \arctan( \frac{y}{1+\frac{\sqrt{2}}{2}} ) - -.. math:: - - \lambda = \sqrt{2} x - - -Further reading -############### - -#. `Wikipedia `_ -#. `Cartographic Projection Procedures for the UNIX Environment-A User's Manual `_ diff --git a/docs/source/projections/geos.rst b/docs/source/projections/geos.rst deleted file mode 100644 index 56550159..00000000 --- a/docs/source/projections/geos.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _geos: - -******************************************************************************** -Geostationary Satellite View -******************************************************************************** -+---------------------+----------------------------------------------------------+ -| **Classification** | Azimuthal | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical and elliptical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden and Martin Raspaud$ | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `+h` | Satellite height above earth. Required. | -+---------------------+----------------------------------------------------------+ -| `+sweep` | Sweep angle axis of the viewing instrument. | -| | Valid options are ``x`` and ``y``. Defaults to ``y``. | -+---------------------+----------------------------------------------------------+ -| `+lon_0` | Subsatellite longitude point. | -+---------------------+----------------------------------------------------------+ - - -.. image:: ./images/geos.png - :scale: 50% - :alt: Geostationary Satellite View - -The geos projection pictures how a geostationary satellite scans the earth at regular -scanning angle intervals. - - -Usage -############################################################################### - -In order to project using the geos projection you can do the following:: - - proj +proj=geos +h=35785831.0 - -The required argument ``h`` is the viewing point (satellite position) height above -the earth. - -The projection coordinate relate to the scanning angle by the following simple -relation:: - - scanning_angle (radians) = projection_coordinate / h - - -Note on sweep angle -------------------------------------------------------------------------------- - -The viewing instrument on-board geostationary satellites described by this -projection have a two-axis gimbal viewing geometry. This means that the different -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 - :scale: 50% - :alt: Gimbal geometry - -In the image above, the outer-gimbal axis, or sweep-angle axis, is the N/S axis (``y``) -while the inner-gimbal axis, or fixed-angle axis, is the E/W axis (``x``). - -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 -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/projections/gins8.rst b/docs/source/projections/gins8.rst deleted file mode 100644 index f6adb092..00000000 --- a/docs/source/projections/gins8.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _gins8: - -******************************************************************************** -Ginsburg VIII (TsNIIGAiK) -******************************************************************************** - -.. image:: ./images/gins8.png - :scale: 50% - :alt: Ginsburg VIII (TsNIIGAiK) - diff --git a/docs/source/projections/gn_sinu.rst b/docs/source/projections/gn_sinu.rst deleted file mode 100644 index c1017c27..00000000 --- a/docs/source/projections/gn_sinu.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _gn_sinu: - -******************************************************************************** -General Sinusoidal Series -******************************************************************************** - -.. image:: ./images/gn_sinu.png - :scale: 50% - :alt: General Sinusoidal Series - diff --git a/docs/source/projections/gnom.rst b/docs/source/projections/gnom.rst deleted file mode 100644 index 08d0db5f..00000000 --- a/docs/source/projections/gnom.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _gnom: - -******************************************************************************** -Gnomonic -******************************************************************************** - -.. image:: ./images/gnom.png - :scale: 50% - :alt: Gnomonic - diff --git a/docs/source/projections/goode.rst b/docs/source/projections/goode.rst deleted file mode 100644 index c4590bf2..00000000 --- a/docs/source/projections/goode.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _goode: - -******************************************************************************** -Goode Homolosine -******************************************************************************** - -.. image:: ./images/goode.png - :scale: 50% - :alt: Goode Homolosine - diff --git a/docs/source/projections/gs48.rst b/docs/source/projections/gs48.rst deleted file mode 100644 index bdaa367c..00000000 --- a/docs/source/projections/gs48.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _gs48: - -******************************************************************************** -Mod. Stererographics of 48 U.S. -******************************************************************************** - -.. image:: ./images/gs48.png - :scale: 50% - :alt: Mod. Stererographics of 48 U.S. - diff --git a/docs/source/projections/gs50.rst b/docs/source/projections/gs50.rst deleted file mode 100644 index 0d4b7e81..00000000 --- a/docs/source/projections/gs50.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _gs50: - -******************************************************************************** -Mod. Stererographics of 50 U.S. -******************************************************************************** - -.. image:: ./images/gs50.png - :scale: 50% - :alt: Mod. Stererographics of 50 U.S. - diff --git a/docs/source/projections/gstmerc.rst b/docs/source/projections/gstmerc.rst deleted file mode 100644 index fc587ab0..00000000 --- a/docs/source/projections/gstmerc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _gstmerc: - -******************************************************************************** -Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) -******************************************************************************** - -.. image:: ./images/gstmerc.png - :scale: 50% - :alt: Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) - diff --git a/docs/source/projections/hammer.rst b/docs/source/projections/hammer.rst deleted file mode 100644 index e795b91b..00000000 --- a/docs/source/projections/hammer.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _hammer: - -******************************************************************************** -Hammer & Eckert-Greifendorff -******************************************************************************** - -.. image:: ./images/hammer.png - :scale: 50% - :alt: Hammer & Eckert-Greifendorff - diff --git a/docs/source/projections/hatano.rst b/docs/source/projections/hatano.rst deleted file mode 100644 index 5d0c63b7..00000000 --- a/docs/source/projections/hatano.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _hatano: - -******************************************************************************** -Hatano Asymmetrical Equal Area -******************************************************************************** - - - - -+---------------------+----------------------------------------------------------+ -| **Classification** | :term:`Pseudocylindrical Projection` | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global, but best between standard parallels | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `+lat_1` | Standard Parallel 1 | -+---------------------+----------------------------------------------------------+ -| `+lat_2` | Standard Parallel 2 | -+---------------------+----------------------------------------------------------+ -| `+sym` | Symmetric form used instead of asymmetric | -+---------------------+----------------------------------------------------------+ - - -.. image:: ./images/hatano.png - :scale: 50% - :alt: Hatano Asymmetrical Equal Area - - - -Mathematical Definition --------------------------------------------------------------------------------- - -Forward -................................................................................ - -.. math:: - - x &= 0.85\lambda \cos \theta - - y &= C_y \sin \theta - - P(\theta) &= 2\theta + \sin 2\theta - C_p \sin \phi - - P'(\theta) &= 2(1 + \cos 2\theta) - - \theta_0 &= 2\phi - - -==================================== ================== =================== -Condition :math:`C_p` :math:`C_p` -==================================== ================== =================== -if ``+sym`` or :math:`\phi > 0` 1.75859 2.67595 -if not ``+sym`` and :math:`\phi < 0` 1.93052 2.43763 -==================================== ================== =================== - -For :math:`\phi = 0`, :math:`y \leftarrow 0`, and :math:`x \leftarrow 0.85\lambda`. - -Further reading --------------------------------------------------------------------------------- - -#. `Compare Map Projections `__ -#. `Mathworks `__ - - - diff --git a/docs/source/projections/healpix.rst b/docs/source/projections/healpix.rst deleted file mode 100644 index 885ea3ea..00000000 --- a/docs/source/projections/healpix.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _healpix: - -******************************************************************************** -HEALPix -******************************************************************************** -+---------------------+----------------------------------------------------------+ -| **Classification** | Mixed | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical and elliptical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Alex Raichev and Michael Speth | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `No special options for this projection` | -+---------------------+----------------------------------------------------------+ - -.. image:: ../../images/healpix.png - :scale: 75% - :alt: HEALPix - -The HEALPix projection is area preserving and can be used with a spherical and -ellipsoidal model. It was initially developed for mapping cosmic background -microwave radiation. The image below is the graphical representation of the -mapping and consists of eight isomorphic triangular interrupted map graticules. -The north and south contains four in which straight meridians converge polewards -to a point and unequally spaced horizontal parallels. HEALPix provides a mapping -in which points of equal latitude and equally spaced longitude are mapped to points -of equal latitude and equally spaced longitude with the module of the polar -interruptions. - - -Usage -############################################################################### - -To run a forward HEALPix projection on a unit sphere model, use the following command:: - - proj +proj=healpix +lon_0=0 +a=1 -E <`_ -#. `Wikipedia `_ - - - - - diff --git a/docs/source/projections/igh.rst b/docs/source/projections/igh.rst deleted file mode 100644 index d74e1362..00000000 --- a/docs/source/projections/igh.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _igh: - -******************************************************************************** -Interrupted Goode Homolosine -******************************************************************************** - -.. image:: ./images/igh.png - :scale: 50% - :alt: Interrupted Goode Homolosine - diff --git a/docs/source/projections/images/aea.png b/docs/source/projections/images/aea.png deleted file mode 100644 index 7fdd4ece..00000000 Binary files a/docs/source/projections/images/aea.png and /dev/null differ diff --git a/docs/source/projections/images/aeqd.png b/docs/source/projections/images/aeqd.png deleted file mode 100644 index 8e45b2c0..00000000 Binary files a/docs/source/projections/images/aeqd.png and /dev/null differ diff --git a/docs/source/projections/images/airy.png b/docs/source/projections/images/airy.png deleted file mode 100644 index a441e317..00000000 Binary files a/docs/source/projections/images/airy.png and /dev/null differ diff --git a/docs/source/projections/images/aitoff.png b/docs/source/projections/images/aitoff.png deleted file mode 100644 index 3449dcd5..00000000 Binary files a/docs/source/projections/images/aitoff.png and /dev/null differ diff --git a/docs/source/projections/images/alsk.png b/docs/source/projections/images/alsk.png deleted file mode 100644 index 6f6e2014..00000000 Binary files a/docs/source/projections/images/alsk.png and /dev/null differ diff --git a/docs/source/projections/images/apian.png b/docs/source/projections/images/apian.png deleted file mode 100644 index 95857ae3..00000000 Binary files a/docs/source/projections/images/apian.png and /dev/null differ diff --git a/docs/source/projections/images/august.png b/docs/source/projections/images/august.png deleted file mode 100644 index 9d9fece6..00000000 Binary files a/docs/source/projections/images/august.png and /dev/null differ diff --git a/docs/source/projections/images/bacon.png b/docs/source/projections/images/bacon.png deleted file mode 100644 index 62deae63..00000000 Binary files a/docs/source/projections/images/bacon.png and /dev/null differ diff --git a/docs/source/projections/images/bipc.png b/docs/source/projections/images/bipc.png deleted file mode 100644 index 7b8ab39c..00000000 Binary files a/docs/source/projections/images/bipc.png and /dev/null differ diff --git a/docs/source/projections/images/boggs.png b/docs/source/projections/images/boggs.png deleted file mode 100644 index 42dd4c13..00000000 Binary files a/docs/source/projections/images/boggs.png and /dev/null differ diff --git a/docs/source/projections/images/bonne.png b/docs/source/projections/images/bonne.png deleted file mode 100644 index 12f93217..00000000 Binary files a/docs/source/projections/images/bonne.png and /dev/null differ diff --git a/docs/source/projections/images/calcofi.png b/docs/source/projections/images/calcofi.png deleted file mode 100644 index 2fd405ac..00000000 Binary files a/docs/source/projections/images/calcofi.png and /dev/null differ diff --git a/docs/source/projections/images/cass.png b/docs/source/projections/images/cass.png deleted file mode 100644 index e44c46af..00000000 Binary files a/docs/source/projections/images/cass.png and /dev/null differ diff --git a/docs/source/projections/images/cc.png b/docs/source/projections/images/cc.png deleted file mode 100644 index 3beaedfd..00000000 Binary files a/docs/source/projections/images/cc.png and /dev/null differ diff --git a/docs/source/projections/images/cea.png b/docs/source/projections/images/cea.png deleted file mode 100644 index eca2319d..00000000 Binary files a/docs/source/projections/images/cea.png and /dev/null differ diff --git a/docs/source/projections/images/chamb.png b/docs/source/projections/images/chamb.png deleted file mode 100644 index a87e6c68..00000000 Binary files a/docs/source/projections/images/chamb.png and /dev/null differ diff --git a/docs/source/projections/images/collg.png b/docs/source/projections/images/collg.png deleted file mode 100644 index 851201da..00000000 Binary files a/docs/source/projections/images/collg.png and /dev/null differ diff --git a/docs/source/projections/images/comill.png b/docs/source/projections/images/comill.png deleted file mode 100644 index 725a0118..00000000 Binary files a/docs/source/projections/images/comill.png and /dev/null differ diff --git a/docs/source/projections/images/crast.png b/docs/source/projections/images/crast.png deleted file mode 100644 index abd4d32a..00000000 Binary files a/docs/source/projections/images/crast.png and /dev/null differ diff --git a/docs/source/projections/images/denoy.png b/docs/source/projections/images/denoy.png deleted file mode 100644 index 2871cf84..00000000 Binary files a/docs/source/projections/images/denoy.png and /dev/null differ diff --git a/docs/source/projections/images/eck1.png b/docs/source/projections/images/eck1.png deleted file mode 100644 index b892d39e..00000000 Binary files a/docs/source/projections/images/eck1.png and /dev/null differ diff --git a/docs/source/projections/images/eck2.png b/docs/source/projections/images/eck2.png deleted file mode 100644 index ff011598..00000000 Binary files a/docs/source/projections/images/eck2.png and /dev/null differ diff --git a/docs/source/projections/images/eck3.png b/docs/source/projections/images/eck3.png deleted file mode 100644 index f828eed0..00000000 Binary files a/docs/source/projections/images/eck3.png and /dev/null differ diff --git a/docs/source/projections/images/eck4.png b/docs/source/projections/images/eck4.png deleted file mode 100644 index d7ff87bb..00000000 Binary files a/docs/source/projections/images/eck4.png and /dev/null differ diff --git a/docs/source/projections/images/eck5.png b/docs/source/projections/images/eck5.png deleted file mode 100644 index 3df303c6..00000000 Binary files a/docs/source/projections/images/eck5.png and /dev/null differ diff --git a/docs/source/projections/images/eck6.png b/docs/source/projections/images/eck6.png deleted file mode 100644 index d22f4956..00000000 Binary files a/docs/source/projections/images/eck6.png and /dev/null differ diff --git a/docs/source/projections/images/eqc.png b/docs/source/projections/images/eqc.png deleted file mode 100644 index b2d8ba23..00000000 Binary files a/docs/source/projections/images/eqc.png and /dev/null differ diff --git a/docs/source/projections/images/eqdc.png b/docs/source/projections/images/eqdc.png deleted file mode 100644 index f2330a8e..00000000 Binary files a/docs/source/projections/images/eqdc.png and /dev/null differ diff --git a/docs/source/projections/images/etmerc.png b/docs/source/projections/images/etmerc.png deleted file mode 100644 index 8e6bb39b..00000000 Binary files a/docs/source/projections/images/etmerc.png and /dev/null differ diff --git a/docs/source/projections/images/euler.png b/docs/source/projections/images/euler.png deleted file mode 100644 index c9c6e4c8..00000000 Binary files a/docs/source/projections/images/euler.png and /dev/null differ diff --git a/docs/source/projections/images/fahey.png b/docs/source/projections/images/fahey.png deleted file mode 100644 index 8b870b8a..00000000 Binary files a/docs/source/projections/images/fahey.png and /dev/null differ diff --git a/docs/source/projections/images/fouc.png b/docs/source/projections/images/fouc.png deleted file mode 100644 index 6d33216b..00000000 Binary files a/docs/source/projections/images/fouc.png and /dev/null differ diff --git a/docs/source/projections/images/fouc_s.png b/docs/source/projections/images/fouc_s.png deleted file mode 100644 index 401f5ee4..00000000 Binary files a/docs/source/projections/images/fouc_s.png and /dev/null differ diff --git a/docs/source/projections/images/gall.png b/docs/source/projections/images/gall.png deleted file mode 100644 index 819b5d12..00000000 Binary files a/docs/source/projections/images/gall.png and /dev/null differ diff --git a/docs/source/projections/images/geos.png b/docs/source/projections/images/geos.png deleted file mode 100644 index e44fa41b..00000000 Binary files a/docs/source/projections/images/geos.png and /dev/null differ diff --git a/docs/source/projections/images/gins8.png b/docs/source/projections/images/gins8.png deleted file mode 100644 index 12fbae93..00000000 Binary files a/docs/source/projections/images/gins8.png and /dev/null differ diff --git a/docs/source/projections/images/gn_sinu.png b/docs/source/projections/images/gn_sinu.png deleted file mode 100644 index f02e119e..00000000 Binary files a/docs/source/projections/images/gn_sinu.png and /dev/null differ diff --git a/docs/source/projections/images/gnom.png b/docs/source/projections/images/gnom.png deleted file mode 100644 index c079d31a..00000000 Binary files a/docs/source/projections/images/gnom.png and /dev/null differ diff --git a/docs/source/projections/images/goode.png b/docs/source/projections/images/goode.png deleted file mode 100644 index 7001e8d2..00000000 Binary files a/docs/source/projections/images/goode.png and /dev/null differ diff --git a/docs/source/projections/images/gs48.png b/docs/source/projections/images/gs48.png deleted file mode 100644 index 574e368f..00000000 Binary files a/docs/source/projections/images/gs48.png and /dev/null differ diff --git a/docs/source/projections/images/gs50.png b/docs/source/projections/images/gs50.png deleted file mode 100644 index 7244b160..00000000 Binary files a/docs/source/projections/images/gs50.png and /dev/null differ diff --git a/docs/source/projections/images/gstmerc.png b/docs/source/projections/images/gstmerc.png deleted file mode 100644 index d553ea60..00000000 Binary files a/docs/source/projections/images/gstmerc.png and /dev/null differ diff --git a/docs/source/projections/images/hammer.png b/docs/source/projections/images/hammer.png deleted file mode 100644 index 83848479..00000000 Binary files a/docs/source/projections/images/hammer.png and /dev/null differ diff --git a/docs/source/projections/images/hatano.png b/docs/source/projections/images/hatano.png deleted file mode 100644 index b3f47377..00000000 Binary files a/docs/source/projections/images/hatano.png and /dev/null differ diff --git a/docs/source/projections/images/healpix.png b/docs/source/projections/images/healpix.png deleted file mode 100644 index c58a155c..00000000 Binary files a/docs/source/projections/images/healpix.png and /dev/null differ diff --git a/docs/source/projections/images/igh.png b/docs/source/projections/images/igh.png deleted file mode 100644 index 36336eec..00000000 Binary files a/docs/source/projections/images/igh.png and /dev/null differ diff --git a/docs/source/projections/images/imw_p.png b/docs/source/projections/images/imw_p.png deleted file mode 100644 index 74cfe81b..00000000 Binary files a/docs/source/projections/images/imw_p.png and /dev/null differ diff --git a/docs/source/projections/images/isea.png b/docs/source/projections/images/isea.png deleted file mode 100644 index 23cfbf74..00000000 Binary files a/docs/source/projections/images/isea.png and /dev/null differ diff --git a/docs/source/projections/images/kav5.png b/docs/source/projections/images/kav5.png deleted file mode 100644 index d5c45400..00000000 Binary files a/docs/source/projections/images/kav5.png and /dev/null differ diff --git a/docs/source/projections/images/kav7.png b/docs/source/projections/images/kav7.png deleted file mode 100644 index 50d7e6e6..00000000 Binary files a/docs/source/projections/images/kav7.png and /dev/null differ diff --git a/docs/source/projections/images/krovak.png b/docs/source/projections/images/krovak.png deleted file mode 100644 index d0d69547..00000000 Binary files a/docs/source/projections/images/krovak.png and /dev/null differ diff --git a/docs/source/projections/images/labrd.png b/docs/source/projections/images/labrd.png deleted file mode 100644 index e4a174c0..00000000 Binary files a/docs/source/projections/images/labrd.png and /dev/null differ diff --git a/docs/source/projections/images/laea.png b/docs/source/projections/images/laea.png deleted file mode 100644 index f52c7c1f..00000000 Binary files a/docs/source/projections/images/laea.png and /dev/null differ diff --git a/docs/source/projections/images/lagrng.png b/docs/source/projections/images/lagrng.png deleted file mode 100644 index e48210bb..00000000 Binary files a/docs/source/projections/images/lagrng.png and /dev/null differ diff --git a/docs/source/projections/images/larr.png b/docs/source/projections/images/larr.png deleted file mode 100644 index 967b91d2..00000000 Binary files a/docs/source/projections/images/larr.png and /dev/null differ diff --git a/docs/source/projections/images/lask.png b/docs/source/projections/images/lask.png deleted file mode 100644 index dff0e8fa..00000000 Binary files a/docs/source/projections/images/lask.png and /dev/null differ diff --git a/docs/source/projections/images/lcc.png b/docs/source/projections/images/lcc.png deleted file mode 100644 index 4714b74e..00000000 Binary files a/docs/source/projections/images/lcc.png and /dev/null differ diff --git a/docs/source/projections/images/lcca.png b/docs/source/projections/images/lcca.png deleted file mode 100644 index 0c404670..00000000 Binary files a/docs/source/projections/images/lcca.png and /dev/null differ diff --git a/docs/source/projections/images/leac.png b/docs/source/projections/images/leac.png deleted file mode 100644 index 1f57d192..00000000 Binary files a/docs/source/projections/images/leac.png and /dev/null differ diff --git a/docs/source/projections/images/lee_os.png b/docs/source/projections/images/lee_os.png deleted file mode 100644 index 3e258393..00000000 Binary files a/docs/source/projections/images/lee_os.png and /dev/null differ diff --git a/docs/source/projections/images/loxim.png b/docs/source/projections/images/loxim.png deleted file mode 100644 index a03ba94e..00000000 Binary files a/docs/source/projections/images/loxim.png and /dev/null differ diff --git a/docs/source/projections/images/lsat.png b/docs/source/projections/images/lsat.png deleted file mode 100644 index ec608544..00000000 Binary files a/docs/source/projections/images/lsat.png and /dev/null differ diff --git a/docs/source/projections/images/mbt_fps.png b/docs/source/projections/images/mbt_fps.png deleted file mode 100644 index e97cd21e..00000000 Binary files a/docs/source/projections/images/mbt_fps.png and /dev/null differ diff --git a/docs/source/projections/images/mbt_s.png b/docs/source/projections/images/mbt_s.png deleted file mode 100644 index 4432e83b..00000000 Binary files a/docs/source/projections/images/mbt_s.png and /dev/null differ diff --git a/docs/source/projections/images/mbtfpp.png b/docs/source/projections/images/mbtfpp.png deleted file mode 100644 index 3d0c4fb5..00000000 Binary files a/docs/source/projections/images/mbtfpp.png and /dev/null differ diff --git a/docs/source/projections/images/mbtfpq.png b/docs/source/projections/images/mbtfpq.png deleted file mode 100644 index b31c52ce..00000000 Binary files a/docs/source/projections/images/mbtfpq.png and /dev/null differ diff --git a/docs/source/projections/images/mbtfps.png b/docs/source/projections/images/mbtfps.png deleted file mode 100644 index 83891be6..00000000 Binary files a/docs/source/projections/images/mbtfps.png and /dev/null differ diff --git a/docs/source/projections/images/merc.png b/docs/source/projections/images/merc.png deleted file mode 100644 index 8202789e..00000000 Binary files a/docs/source/projections/images/merc.png and /dev/null differ diff --git a/docs/source/projections/images/mil_os.png b/docs/source/projections/images/mil_os.png deleted file mode 100644 index 3316d317..00000000 Binary files a/docs/source/projections/images/mil_os.png and /dev/null differ diff --git a/docs/source/projections/images/mill.png b/docs/source/projections/images/mill.png deleted file mode 100644 index f62e517c..00000000 Binary files a/docs/source/projections/images/mill.png and /dev/null differ diff --git a/docs/source/projections/images/misrsom.png b/docs/source/projections/images/misrsom.png deleted file mode 100644 index 493baff3..00000000 Binary files a/docs/source/projections/images/misrsom.png and /dev/null differ diff --git a/docs/source/projections/images/moll.png b/docs/source/projections/images/moll.png deleted file mode 100644 index 5d599579..00000000 Binary files a/docs/source/projections/images/moll.png and /dev/null differ diff --git a/docs/source/projections/images/murd1.png b/docs/source/projections/images/murd1.png deleted file mode 100644 index 34d628c5..00000000 Binary files a/docs/source/projections/images/murd1.png and /dev/null differ diff --git a/docs/source/projections/images/murd2.png b/docs/source/projections/images/murd2.png deleted file mode 100644 index b3fdabdd..00000000 Binary files a/docs/source/projections/images/murd2.png and /dev/null differ diff --git a/docs/source/projections/images/murd3.png b/docs/source/projections/images/murd3.png deleted file mode 100644 index 354b009c..00000000 Binary files a/docs/source/projections/images/murd3.png and /dev/null differ diff --git a/docs/source/projections/images/natearth.png b/docs/source/projections/images/natearth.png deleted file mode 100644 index 0e182a0b..00000000 Binary files a/docs/source/projections/images/natearth.png and /dev/null differ diff --git a/docs/source/projections/images/natearth2.png b/docs/source/projections/images/natearth2.png deleted file mode 100644 index 3757646c..00000000 Binary files a/docs/source/projections/images/natearth2.png and /dev/null differ diff --git a/docs/source/projections/images/nell.png b/docs/source/projections/images/nell.png deleted file mode 100644 index c0dbdcac..00000000 Binary files a/docs/source/projections/images/nell.png and /dev/null differ diff --git a/docs/source/projections/images/nell_h.png b/docs/source/projections/images/nell_h.png deleted file mode 100644 index a5a27076..00000000 Binary files a/docs/source/projections/images/nell_h.png and /dev/null differ diff --git a/docs/source/projections/images/nicol.png b/docs/source/projections/images/nicol.png deleted file mode 100644 index 711db115..00000000 Binary files a/docs/source/projections/images/nicol.png and /dev/null differ diff --git a/docs/source/projections/images/nsper.png b/docs/source/projections/images/nsper.png deleted file mode 100644 index 06f210a1..00000000 Binary files a/docs/source/projections/images/nsper.png and /dev/null differ diff --git a/docs/source/projections/images/nzmg.png b/docs/source/projections/images/nzmg.png deleted file mode 100644 index 3625f331..00000000 Binary files a/docs/source/projections/images/nzmg.png and /dev/null differ diff --git a/docs/source/projections/images/ob_tran.png b/docs/source/projections/images/ob_tran.png deleted file mode 100644 index 9b1e0d44..00000000 Binary files a/docs/source/projections/images/ob_tran.png and /dev/null differ diff --git a/docs/source/projections/images/ocea.png b/docs/source/projections/images/ocea.png deleted file mode 100644 index 41a5a813..00000000 Binary files a/docs/source/projections/images/ocea.png and /dev/null differ diff --git a/docs/source/projections/images/oea.png b/docs/source/projections/images/oea.png deleted file mode 100644 index 601ead55..00000000 Binary files a/docs/source/projections/images/oea.png and /dev/null differ diff --git a/docs/source/projections/images/omerc.png b/docs/source/projections/images/omerc.png deleted file mode 100644 index 50a3d2b7..00000000 Binary files a/docs/source/projections/images/omerc.png and /dev/null differ diff --git a/docs/source/projections/images/ortel.png b/docs/source/projections/images/ortel.png deleted file mode 100644 index c6a5bf4f..00000000 Binary files a/docs/source/projections/images/ortel.png and /dev/null differ diff --git a/docs/source/projections/images/ortho.png b/docs/source/projections/images/ortho.png deleted file mode 100644 index e8b0b9b2..00000000 Binary files a/docs/source/projections/images/ortho.png and /dev/null differ diff --git a/docs/source/projections/images/patterson.png b/docs/source/projections/images/patterson.png deleted file mode 100644 index f8014249..00000000 Binary files a/docs/source/projections/images/patterson.png and /dev/null differ diff --git a/docs/source/projections/images/pconic.png b/docs/source/projections/images/pconic.png deleted file mode 100644 index 7d7f9f92..00000000 Binary files a/docs/source/projections/images/pconic.png and /dev/null differ diff --git a/docs/source/projections/images/poly.png b/docs/source/projections/images/poly.png deleted file mode 100644 index ccf25529..00000000 Binary files a/docs/source/projections/images/poly.png and /dev/null differ diff --git a/docs/source/projections/images/putp1.png b/docs/source/projections/images/putp1.png deleted file mode 100644 index c81f574c..00000000 Binary files a/docs/source/projections/images/putp1.png and /dev/null differ diff --git a/docs/source/projections/images/putp2.png b/docs/source/projections/images/putp2.png deleted file mode 100644 index 377a027c..00000000 Binary files a/docs/source/projections/images/putp2.png and /dev/null differ diff --git a/docs/source/projections/images/putp3.png b/docs/source/projections/images/putp3.png deleted file mode 100644 index 08692ca1..00000000 Binary files a/docs/source/projections/images/putp3.png and /dev/null differ diff --git a/docs/source/projections/images/putp3p.png b/docs/source/projections/images/putp3p.png deleted file mode 100644 index 9e42319c..00000000 Binary files a/docs/source/projections/images/putp3p.png and /dev/null differ diff --git a/docs/source/projections/images/putp4p.png b/docs/source/projections/images/putp4p.png deleted file mode 100644 index 43cb10c6..00000000 Binary files a/docs/source/projections/images/putp4p.png and /dev/null differ diff --git a/docs/source/projections/images/putp5.png b/docs/source/projections/images/putp5.png deleted file mode 100644 index 4e45de6d..00000000 Binary files a/docs/source/projections/images/putp5.png and /dev/null differ diff --git a/docs/source/projections/images/putp5p.png b/docs/source/projections/images/putp5p.png deleted file mode 100644 index 76dcb767..00000000 Binary files a/docs/source/projections/images/putp5p.png and /dev/null differ diff --git a/docs/source/projections/images/putp6.png b/docs/source/projections/images/putp6.png deleted file mode 100644 index c73585ee..00000000 Binary files a/docs/source/projections/images/putp6.png and /dev/null differ diff --git a/docs/source/projections/images/putp6p.png b/docs/source/projections/images/putp6p.png deleted file mode 100644 index d64c2c20..00000000 Binary files a/docs/source/projections/images/putp6p.png and /dev/null differ diff --git a/docs/source/projections/images/qsc.png b/docs/source/projections/images/qsc.png deleted file mode 100644 index 5824cf64..00000000 Binary files a/docs/source/projections/images/qsc.png and /dev/null differ diff --git a/docs/source/projections/images/qua_aut.png b/docs/source/projections/images/qua_aut.png deleted file mode 100644 index 6bc2d811..00000000 Binary files a/docs/source/projections/images/qua_aut.png and /dev/null differ diff --git a/docs/source/projections/images/rhealpix.png b/docs/source/projections/images/rhealpix.png deleted file mode 100644 index dc1c344a..00000000 Binary files a/docs/source/projections/images/rhealpix.png and /dev/null differ diff --git a/docs/source/projections/images/robin.png b/docs/source/projections/images/robin.png deleted file mode 100644 index 42a49da2..00000000 Binary files a/docs/source/projections/images/robin.png and /dev/null differ diff --git a/docs/source/projections/images/rouss.png b/docs/source/projections/images/rouss.png deleted file mode 100644 index 2eca0fed..00000000 Binary files a/docs/source/projections/images/rouss.png and /dev/null differ diff --git a/docs/source/projections/images/rpoly.png b/docs/source/projections/images/rpoly.png deleted file mode 100644 index 343127c1..00000000 Binary files a/docs/source/projections/images/rpoly.png and /dev/null differ diff --git a/docs/source/projections/images/sinu.png b/docs/source/projections/images/sinu.png deleted file mode 100644 index 9bef143a..00000000 Binary files a/docs/source/projections/images/sinu.png and /dev/null differ diff --git a/docs/source/projections/images/somerc.png b/docs/source/projections/images/somerc.png deleted file mode 100644 index 1248e6ea..00000000 Binary files a/docs/source/projections/images/somerc.png and /dev/null differ diff --git a/docs/source/projections/images/stere.png b/docs/source/projections/images/stere.png deleted file mode 100644 index 840050f0..00000000 Binary files a/docs/source/projections/images/stere.png and /dev/null differ diff --git a/docs/source/projections/images/sterea.png b/docs/source/projections/images/sterea.png deleted file mode 100644 index d2aad552..00000000 Binary files a/docs/source/projections/images/sterea.png and /dev/null differ diff --git a/docs/source/projections/images/tcc.png b/docs/source/projections/images/tcc.png deleted file mode 100644 index f968f62d..00000000 Binary files a/docs/source/projections/images/tcc.png and /dev/null differ diff --git a/docs/source/projections/images/tcea.png b/docs/source/projections/images/tcea.png deleted file mode 100644 index 44212bd8..00000000 Binary files a/docs/source/projections/images/tcea.png and /dev/null differ diff --git a/docs/source/projections/images/tissot.png b/docs/source/projections/images/tissot.png deleted file mode 100644 index 2f785477..00000000 Binary files a/docs/source/projections/images/tissot.png and /dev/null differ diff --git a/docs/source/projections/images/tmerc.png b/docs/source/projections/images/tmerc.png deleted file mode 100644 index b206c502..00000000 Binary files a/docs/source/projections/images/tmerc.png and /dev/null differ diff --git a/docs/source/projections/images/tpeqd.png b/docs/source/projections/images/tpeqd.png deleted file mode 100644 index 50291b68..00000000 Binary files a/docs/source/projections/images/tpeqd.png and /dev/null differ diff --git a/docs/source/projections/images/tpers.png b/docs/source/projections/images/tpers.png deleted file mode 100644 index 480f6dce..00000000 Binary files a/docs/source/projections/images/tpers.png and /dev/null differ diff --git a/docs/source/projections/images/ups.png b/docs/source/projections/images/ups.png deleted file mode 100644 index 354b64ac..00000000 Binary files a/docs/source/projections/images/ups.png and /dev/null differ diff --git a/docs/source/projections/images/urm5.png b/docs/source/projections/images/urm5.png deleted file mode 100644 index 088671c9..00000000 Binary files a/docs/source/projections/images/urm5.png and /dev/null differ diff --git a/docs/source/projections/images/urmfps.png b/docs/source/projections/images/urmfps.png deleted file mode 100644 index 86432790..00000000 Binary files a/docs/source/projections/images/urmfps.png and /dev/null differ diff --git a/docs/source/projections/images/utm.png b/docs/source/projections/images/utm.png deleted file mode 100644 index 3dcd5ee0..00000000 Binary files a/docs/source/projections/images/utm.png and /dev/null differ diff --git a/docs/source/projections/images/vandg.png b/docs/source/projections/images/vandg.png deleted file mode 100644 index 46fe2346..00000000 Binary files a/docs/source/projections/images/vandg.png and /dev/null differ diff --git a/docs/source/projections/images/vandg2.png b/docs/source/projections/images/vandg2.png deleted file mode 100644 index 597b5ae1..00000000 Binary files a/docs/source/projections/images/vandg2.png and /dev/null differ diff --git a/docs/source/projections/images/vandg3.png b/docs/source/projections/images/vandg3.png deleted file mode 100644 index 36d1ad04..00000000 Binary files a/docs/source/projections/images/vandg3.png and /dev/null differ diff --git a/docs/source/projections/images/vandg4.png b/docs/source/projections/images/vandg4.png deleted file mode 100644 index 163c1558..00000000 Binary files a/docs/source/projections/images/vandg4.png and /dev/null differ diff --git a/docs/source/projections/images/vitk1.png b/docs/source/projections/images/vitk1.png deleted file mode 100644 index 31034b3a..00000000 Binary files a/docs/source/projections/images/vitk1.png and /dev/null differ diff --git a/docs/source/projections/images/wag1.png b/docs/source/projections/images/wag1.png deleted file mode 100644 index a2bc8adc..00000000 Binary files a/docs/source/projections/images/wag1.png and /dev/null differ diff --git a/docs/source/projections/images/wag2.png b/docs/source/projections/images/wag2.png deleted file mode 100644 index b4abb48c..00000000 Binary files a/docs/source/projections/images/wag2.png and /dev/null differ diff --git a/docs/source/projections/images/wag3.png b/docs/source/projections/images/wag3.png deleted file mode 100644 index a2053815..00000000 Binary files a/docs/source/projections/images/wag3.png and /dev/null differ diff --git a/docs/source/projections/images/wag4.png b/docs/source/projections/images/wag4.png deleted file mode 100644 index 7d1c50b3..00000000 Binary files a/docs/source/projections/images/wag4.png and /dev/null differ diff --git a/docs/source/projections/images/wag5.png b/docs/source/projections/images/wag5.png deleted file mode 100644 index 487f6022..00000000 Binary files a/docs/source/projections/images/wag5.png and /dev/null differ diff --git a/docs/source/projections/images/wag6.png b/docs/source/projections/images/wag6.png deleted file mode 100644 index dd49e8d0..00000000 Binary files a/docs/source/projections/images/wag6.png and /dev/null differ diff --git a/docs/source/projections/images/wag7.png b/docs/source/projections/images/wag7.png deleted file mode 100644 index b9682755..00000000 Binary files a/docs/source/projections/images/wag7.png and /dev/null differ diff --git a/docs/source/projections/images/weren.png b/docs/source/projections/images/weren.png deleted file mode 100644 index 7deb132f..00000000 Binary files a/docs/source/projections/images/weren.png and /dev/null differ diff --git a/docs/source/projections/images/wink1.png b/docs/source/projections/images/wink1.png deleted file mode 100644 index 6cbf48ae..00000000 Binary files a/docs/source/projections/images/wink1.png and /dev/null differ diff --git a/docs/source/projections/images/wink2.png b/docs/source/projections/images/wink2.png deleted file mode 100644 index 21a23634..00000000 Binary files a/docs/source/projections/images/wink2.png and /dev/null differ diff --git a/docs/source/projections/images/wintri.png b/docs/source/projections/images/wintri.png deleted file mode 100644 index 54a0a85a..00000000 Binary files a/docs/source/projections/images/wintri.png and /dev/null differ diff --git a/docs/source/projections/imw_p.rst b/docs/source/projections/imw_p.rst deleted file mode 100644 index 1fd3ded0..00000000 --- a/docs/source/projections/imw_p.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _imw_p: - -******************************************************************************** -International Map of the World Polyconic -******************************************************************************** - -.. image:: ./images/imw_p.png - :scale: 50% - :alt: International Map of the World Polyconic - diff --git a/docs/source/projections/index.rst b/docs/source/projections/index.rst deleted file mode 100644 index ae8ef1ee..00000000 --- a/docs/source/projections/index.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. _projections: - -================================================================================ -Projections -================================================================================ - -.. toctree:: - :maxdepth: 1 - - aeqd - airy - aitoff - alsk - apian - august - bacon - bipc - boggs - bonne - calcofi - cass - cc - cea - chamb - collg - crast - denoy - eck1 - eck2 - eck3 - eck4 - eck5 - eck6 - eqc - eqdc - euler - etmerc - fahey - fouc - fouc_s - gall - geos - gins8 - gn_sinu - gnom - goode - gs48 - gs50 - hammer - hatano - healpix - rhealpix - igh - imw_p - isea - kav5 - kav7 - krovak - labrd - laea - lagrng - larr - lask - lonlat - latlon - lcc - lcca - leac - lee_os - loxim - lsat - mbt_s - mbt_fps - mbtfpp - mbtfpq - mbtfps - merc - mil_os - mill - moll - murd1 - murd2 - murd3 - natearth - nell - nell_h - nicol - nsper - nzmg - ob_tran - ocea - oea - omerc - ortel - ortho - pconic - poly - putp1 - putp2 - putp3 - putp3p - putp4p - putp5 - putp5p - putp6 - putp6p - qua_aut - qsc - robin - rouss - rpoly - sinu - somerc - stere - sterea - gstmerc - tcc - tcea - tissot - tmerc - tpeqd - tpers - ups - urm5 - urmfps - utm - vandg - vandg2 - vandg3 - vandg4 - vitk1 - wag1 - wag2 - wag3 - wag4 - wag5 - wag6 - wag7 - weren - wink1 - wink2 - wintri diff --git a/docs/source/projections/isea.rst b/docs/source/projections/isea.rst deleted file mode 100644 index 1b6457af..00000000 --- a/docs/source/projections/isea.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _isea: - -******************************************************************************** -Icosahedral Snyder Equal Area -******************************************************************************** - -.. image:: ./images/isea.png - :scale: 50% - :alt: Icosahedral Snyder Equal Area - diff --git a/docs/source/projections/kav5.rst b/docs/source/projections/kav5.rst deleted file mode 100644 index 2ec5d1c1..00000000 --- a/docs/source/projections/kav5.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _kav5: - -******************************************************************************** -Kavraisky V -******************************************************************************** - -.. image:: ./images/kav5.png - :scale: 50% - :alt: Kavraisky V - diff --git a/docs/source/projections/kav7.rst b/docs/source/projections/kav7.rst deleted file mode 100644 index 8371e6ea..00000000 --- a/docs/source/projections/kav7.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _kav7: - -******************************************************************************** -Kavraisky VII -******************************************************************************** - -.. image:: ./images/kav7.png - :scale: 50% - :alt: Kavraisky VII - diff --git a/docs/source/projections/krovak.rst b/docs/source/projections/krovak.rst deleted file mode 100644 index 6c774825..00000000 --- a/docs/source/projections/krovak.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _krovak: - -******************************************************************************** -Krovak -******************************************************************************** - -.. image:: ./images/krovak.png - :scale: 50% - :alt: Krovak - diff --git a/docs/source/projections/labrd.rst b/docs/source/projections/labrd.rst deleted file mode 100644 index 5be58db5..00000000 --- a/docs/source/projections/labrd.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _labrd: - -******************************************************************************** -Laborde -******************************************************************************** - -.. image:: ./images/labrd.png - :scale: 50% - :alt: Laborde - diff --git a/docs/source/projections/laea.rst b/docs/source/projections/laea.rst deleted file mode 100644 index 2377f294..00000000 --- a/docs/source/projections/laea.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _laea: - -******************************************************************************** -Lambert Azimuthal Equal Area -******************************************************************************** - -.. image:: ./images/laea.png - :scale: 50% - :alt: Lambert Azimuthal Equal Area - diff --git a/docs/source/projections/lagrng.rst b/docs/source/projections/lagrng.rst deleted file mode 100644 index de9e5640..00000000 --- a/docs/source/projections/lagrng.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _lagrng: - -******************************************************************************** -Lagrange -******************************************************************************** - -.. image:: ./images/lagrng.png - :scale: 50% - :alt: Lagrange - diff --git a/docs/source/projections/larr.rst b/docs/source/projections/larr.rst deleted file mode 100644 index 9529f83f..00000000 --- a/docs/source/projections/larr.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _larr: - -******************************************************************************** -Larrivee -******************************************************************************** - -.. image:: ./images/larr.png - :scale: 50% - :alt: Larrivee - diff --git a/docs/source/projections/lask.rst b/docs/source/projections/lask.rst deleted file mode 100644 index d34dc8a0..00000000 --- a/docs/source/projections/lask.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _lask: - -******************************************************************************** -Laskowski -******************************************************************************** - -.. image:: ./images/lask.png - :scale: 50% - :alt: Laskowski - diff --git a/docs/source/projections/latlon.rst b/docs/source/projections/latlon.rst deleted file mode 100644 index 6712fa7b..00000000 --- a/docs/source/projections/latlon.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _latlon: - -******************************************************************************** -Lat/long (Geodetic alias) -******************************************************************************** - diff --git a/docs/source/projections/lcc.rst b/docs/source/projections/lcc.rst deleted file mode 100644 index a3075e76..00000000 --- a/docs/source/projections/lcc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _lcc: - -******************************************************************************** -Lambert Conformal Conic -******************************************************************************** - -.. image:: ./images/lcc.png - :scale: 50% - :alt: Lambert Conformal Conic - diff --git a/docs/source/projections/lcca.rst b/docs/source/projections/lcca.rst deleted file mode 100644 index ca87e67e..00000000 --- a/docs/source/projections/lcca.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _lcca: - -******************************************************************************** -Lambert Conformal Conic Alternative -******************************************************************************** - -.. image:: ./images/lcca.png - :scale: 50% - :alt: Lambert Conformal Conic Alternative - diff --git a/docs/source/projections/leac.rst b/docs/source/projections/leac.rst deleted file mode 100644 index 2957798e..00000000 --- a/docs/source/projections/leac.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _leac: - -******************************************************************************** -Lambert Equal Area Conic -******************************************************************************** - -.. image:: ./images/leac.png - :scale: 50% - :alt: Lambert Equal Area Conic - diff --git a/docs/source/projections/lee_os.rst b/docs/source/projections/lee_os.rst deleted file mode 100644 index 711dc754..00000000 --- a/docs/source/projections/lee_os.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _lee_os: - -******************************************************************************** -Lee Oblated Stereographic -******************************************************************************** - -.. image:: ./images/lee_os.png - :scale: 50% - :alt: Lee Oblated Stereographic - diff --git a/docs/source/projections/lonlat.rst b/docs/source/projections/lonlat.rst deleted file mode 100644 index 589cc813..00000000 --- a/docs/source/projections/lonlat.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _lonlat: - -******************************************************************************** -Lat/long (Geodetic) -******************************************************************************** - diff --git a/docs/source/projections/loxim.rst b/docs/source/projections/loxim.rst deleted file mode 100644 index e50ba472..00000000 --- a/docs/source/projections/loxim.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _loxim: - -******************************************************************************** -Loximuthal -******************************************************************************** - -.. image:: ./images/loxim.png - :scale: 50% - :alt: Loximuthal - diff --git a/docs/source/projections/lsat.rst b/docs/source/projections/lsat.rst deleted file mode 100644 index fb64bdb2..00000000 --- a/docs/source/projections/lsat.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _lsat: - -******************************************************************************** -Space oblique for LANDSAT -******************************************************************************** - -.. image:: ./images/lsat.png - :scale: 50% - :alt: Space oblique for LANDSAT - diff --git a/docs/source/projections/mbt_fps.rst b/docs/source/projections/mbt_fps.rst deleted file mode 100644 index 55ebcf6c..00000000 --- a/docs/source/projections/mbt_fps.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _mbt_fps: - -******************************************************************************** -McBryde-Thomas Flat-Pole Sine (No. 2) -******************************************************************************** - -.. image:: ./images/mbt_fps.png - :scale: 50% - :alt: McBryde-Thomas Flat-Pole Sine (No. 2) - diff --git a/docs/source/projections/mbt_s.rst b/docs/source/projections/mbt_s.rst deleted file mode 100644 index 9a355ec8..00000000 --- a/docs/source/projections/mbt_s.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _mbt_s: - -******************************************************************************** -McBryde-Thomas Flat-Polar Sine (No. 1) -******************************************************************************** - -.. image:: ./images/mbt_s.png - :scale: 50% - :alt: McBryde-Thomas Flat-Polar Sine (No. 1) - diff --git a/docs/source/projections/mbtfpp.rst b/docs/source/projections/mbtfpp.rst deleted file mode 100644 index 9be309d9..00000000 --- a/docs/source/projections/mbtfpp.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _mbtfpp: - -******************************************************************************** -McBride-Thomas Flat-Polar Parabolic -******************************************************************************** - -.. image:: ./images/mbtfpp.png - :scale: 50% - :alt: McBride-Thomas Flat-Polar Parabolic - diff --git a/docs/source/projections/mbtfpq.rst b/docs/source/projections/mbtfpq.rst deleted file mode 100644 index 295e814d..00000000 --- a/docs/source/projections/mbtfpq.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _mbtfpq: - -******************************************************************************** -McBryde-Thomas Flat-Polar Quartic -******************************************************************************** - -.. image:: ./images/mbtfpq.png - :scale: 50% - :alt: McBryde-Thomas Flat-Polar Quartic - diff --git a/docs/source/projections/mbtfps.rst b/docs/source/projections/mbtfps.rst deleted file mode 100644 index b9365361..00000000 --- a/docs/source/projections/mbtfps.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _mbtfps: - -******************************************************************************** -McBryde-Thomas Flat-Polar Sinusoidal -******************************************************************************** - -.. image:: ./images/mbtfps.png - :scale: 50% - :alt: McBryde-Thomas Flat-Polar Sinusoidal - diff --git a/docs/source/projections/merc.rst b/docs/source/projections/merc.rst deleted file mode 100644 index 64ba98a4..00000000 --- a/docs/source/projections/merc.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. _merc: - -******************************************************************************** -Mercator -******************************************************************************** - -The Mercator projection is a cylindrical map projection that origins from the 15th -century. It is widely recognized as the first regularly used map projection. -The projection is conformal which makes it suitable for navigational purposes. - - -+---------------------+----------------------------------------------------------+ -| **Classification** | Conformal cylindrical | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical and elliptical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global, but best used near the equator | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `+lat_ts` | Latitude of true scale. Defaults to 0.0 | -+---------------------+----------------------------------------------------------+ -| `+k_0` | Scaling factor. Defaults to 1.0 | -+---------------------+----------------------------------------------------------+ - - - -.. image:: ./images/merc.png - :scale: 50% - :alt: Mercator - - -Usage -######## - -Applications should be limited to equatorial regions, but is frequently -used for navigational charts with latitude of true scale (``+lat_ts``) specified within -or near chart's boundaries. -Often inappropriately used for world maps since the regions near the poles -cannot be shown [Evenden1995]_. - - -Example using latitude of true scale:: - - $ echo 56.35 12.32 | proj +proj=merc +lat_ts=56.5 - 3470306.37 759599.90 - -Example using scaling factor:: - - echo 56.35 12.32 | proj +proj=merc +k_0=2 - 12545706.61 2746073.80 - - -Note that ``+lat_ts`` and ``+k_0`` are mutually excusive. -If used together, ``+lat_ts`` takes precedence over ``+k_0``. - -Mathematical definition -####################### - -The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals [Evenden2005]_. - -Spherical form -************** -For the spherical form of the projection we introduce the scaling factor: - -.. math:: - - k_0 = \cos \phi_{ts} - -Forward projection -================== - -.. math:: - - x = k_0 \lambda - -.. math:: - - y = k_0 \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right] - - -Inverse projection -================== - -.. math:: - - \lambda = \frac{x}{k_0} - -.. math:: - - \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y/k_0} \right] - - -Elliptical form -*************** - -For the elliptical form of the projection we introduce the scaling factor: - -.. math:: - - k_0 = m\left( \phi_ts \right) - -where :math:`m\left(\phi\right)` is the parallel radius at latitude :math:`\phi`. - -We also use the Isometric Latitude kernel function :math:`t()`. - -.. note:: - m() and t() should be described properly on a separate page about the theory of projections on the ellipsoid. - -Forward projection -================== -.. math:: - - x = k_0 \lambda - -.. math:: - - y = k_0 \ln t \left( \phi \right) - - -Inverse projection -================== - -.. math:: - - \lambda = \frac{x}{k_0} - -.. math:: - - \phi = t^{-1}\left[ e^{ -y/k_0 } \right] - -Further reading -############### - -#. `Wikipedia `_ -#. `Wolfram Mathworld `_ - - diff --git a/docs/source/projections/mil_os.rst b/docs/source/projections/mil_os.rst deleted file mode 100644 index 5547e43c..00000000 --- a/docs/source/projections/mil_os.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _mil_os: - -******************************************************************************** -Miller Oblated Stereographic -******************************************************************************** - -.. image:: ./images/mil_os.png - :scale: 50% - :alt: Miller Oblated Stereographic - diff --git a/docs/source/projections/mill.rst b/docs/source/projections/mill.rst deleted file mode 100644 index eb9c2092..00000000 --- a/docs/source/projections/mill.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _mill: - -******************************************************************************** -Miller Cylindrical -******************************************************************************** - -The Miller cylindrical projection is a modified Mercator projection, proposed by Osborn Maitland Miller in 1942. -The latitude is scaled by a factor of :math:`\frac{4}{5}`, projected according to Mercator, and then the result is multiplied by :math:`\frac{5}{4}` to retain scale along the equator. - -+---------------------+--------------------------------------------------------------------------------+ -| **Classification** | Neither conformal nor equal area cylindrical | -+---------------------+--------------------------------------------------------------------------------+ -| **Available forms** | Forward and inverse spherical | -+---------------------+--------------------------------------------------------------------------------+ -| **Defined area** | Global, but best used near the equator | -+---------------------+--------------------------------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+--------------------------------------------------------------------------------+ -| **Options** | -+---------------------+--------------------------------------------------------------------------------+ -| `+lat_0` | Latitude of origin (Default to 0) | -+---------------------+--------------------------------------------------------------------------------+ - -.. image:: ./images/mill.png - :scale: 50% - :alt: Miller Cylindrical - -Usage -######## - -The Miller Cylindrical projection is used for world maps and in several atlases, -including the National Atlas of the United States (USGS, 1970, p. 330-331) [Snyder1987]_. - -Example using Central meridian 90°W:: - - $ echo -100 35 | proj +proj=mill +lon_0=90w - -1113194.91 4061217.24 - -Mathematical definition -####################### - -The formulas describing the Miller projection are all taken from Snyder's manuals [Snyder1987]_. - - -Forward projection -================== - -.. math:: - - x = \lambda - -.. math:: - - y = 1.25 * \ln \left[ \tan \left(\frac{\pi}{4} + 0.4 * \phi \right) \right] - - -Inverse projection -================== - -.. math:: - - \lambda = x - -.. math:: - - \phi = 2.5 * ( \arctan \left[ e^{0.8 * y} \right] - \frac{\pi}{4} ) - -Further reading -############### - -#. `Wikipedia `_ - diff --git a/docs/source/projections/moll.rst b/docs/source/projections/moll.rst deleted file mode 100644 index 1bd3d005..00000000 --- a/docs/source/projections/moll.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _moll: - -******************************************************************************** -Mollweide -******************************************************************************** - -.. image:: ./images/moll.png - :scale: 50% - :alt: Mollweide - diff --git a/docs/source/projections/murd1.rst b/docs/source/projections/murd1.rst deleted file mode 100644 index 71cbf155..00000000 --- a/docs/source/projections/murd1.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _murd1: - -******************************************************************************** -Murdoch I -******************************************************************************** - -.. image:: ./images/murd1.png - :scale: 50% - :alt: Murdoch I - diff --git a/docs/source/projections/murd2.rst b/docs/source/projections/murd2.rst deleted file mode 100644 index b55cde35..00000000 --- a/docs/source/projections/murd2.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _murd2: - -******************************************************************************** -Murdoch II -******************************************************************************** - -.. image:: ./images/murd2.png - :scale: 50% - :alt: Murdoch II - diff --git a/docs/source/projections/murd3.rst b/docs/source/projections/murd3.rst deleted file mode 100644 index 70cc9276..00000000 --- a/docs/source/projections/murd3.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _murd3: - -******************************************************************************** -Murdoch III -******************************************************************************** - -.. image:: ./images/murd3.png - :scale: 50% - :alt: Murdoch III - diff --git a/docs/source/projections/natearth.rst b/docs/source/projections/natearth.rst deleted file mode 100644 index 57dd96db..00000000 --- a/docs/source/projections/natearth.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _natearth: - -******************************************************************************** -Natural Earth -******************************************************************************** -+---------------------+--------------------------------------------------------+ -| **Classification** | Pseudo cylindrical | -+---------------------+--------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical projection | -+---------------------+--------------------------------------------------------+ -| **Defined area** | Global | -+---------------------+--------------------------------------------------------+ -| **Implemented by** | Bernhard Jenny | -+---------------------+--------------------------------------------------------+ -| **Options** | -+---------------------+--------------------------------------------------------+ -| `No special options for this projection` | -+---------------------+--------------------------------------------------------+ - -.. image:: ./images/natearth.png - :scale: 50% - :alt: Natural Earth - - -The Natural Earth projection is intended for making world maps. A distinguishing trait -is its slightly rounded corners fashioned to emulate the spherical shape of Earth. -The meridians (except for the central meridian) bend acutely inward as they approach -the pole lines, giving the projection a hint of three-dimensionality. This bending -also suggests that the meridians converge at the poles instead of truncating at the -top and bottom edges. The distortion characteristics of the Natural Earth projection -compare favorably to other world map projections. - - -Usage -############################################################################### - -The Natural Earth projection has no special options so usage is simple. Here is -an example of an inverse projection on a sphere with a radius of 7500 m:: - - $ echo 3500 -8000 | proj -I +proj=natearth +a=7500 - 37d54'6.091"E 61d23'4.582"S - - -Further reading -################################################################################ - -#. `Wikipedia `_ diff --git a/docs/source/projections/nell.rst b/docs/source/projections/nell.rst deleted file mode 100644 index c6a3771c..00000000 --- a/docs/source/projections/nell.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _nell: - -******************************************************************************** -Nell -******************************************************************************** - -.. image:: ./images/nell.png - :scale: 50% - :alt: Nell - diff --git a/docs/source/projections/nell_h.rst b/docs/source/projections/nell_h.rst deleted file mode 100644 index 6a3b26ba..00000000 --- a/docs/source/projections/nell_h.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _nell_h: - -******************************************************************************** -Nell-Hammer -******************************************************************************** - -.. image:: ./images/nell_h.png - :scale: 50% - :alt: Nell-Hammer - diff --git a/docs/source/projections/nicol.rst b/docs/source/projections/nicol.rst deleted file mode 100644 index 995cedb5..00000000 --- a/docs/source/projections/nicol.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _nicol: - -******************************************************************************** -Nicolosi Globular -******************************************************************************** - -.. image:: ./images/nicol.png - :scale: 50% - :alt: Nicolosi Globular - diff --git a/docs/source/projections/nsper.rst b/docs/source/projections/nsper.rst deleted file mode 100644 index 4a8651fc..00000000 --- a/docs/source/projections/nsper.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _nsper: - -******************************************************************************** -Near-sided perspective -******************************************************************************** - -.. image:: ./images/nsper.png - :scale: 50% - :alt: Near-sided perspective - diff --git a/docs/source/projections/nzmg.rst b/docs/source/projections/nzmg.rst deleted file mode 100644 index 926655d8..00000000 --- a/docs/source/projections/nzmg.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _nzmg: - -******************************************************************************** -New Zealand Map Grid -******************************************************************************** - -.. image:: ./images/nzmg.png - :scale: 50% - :alt: New Zealand Map Grid - diff --git a/docs/source/projections/ob_tran.rst b/docs/source/projections/ob_tran.rst deleted file mode 100644 index 3c996336..00000000 --- a/docs/source/projections/ob_tran.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _ob_tran: - -******************************************************************************** -General Oblique Transformation -******************************************************************************** - -.. image:: ./images/ob_tran.png - :scale: 50% - :alt: General Oblique Transformation - diff --git a/docs/source/projections/ocea.rst b/docs/source/projections/ocea.rst deleted file mode 100644 index 40005d9e..00000000 --- a/docs/source/projections/ocea.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _ocea: - -******************************************************************************** -Oblique Cylindrical Equal Area -******************************************************************************** - -.. image:: ./images/ocea.png - :scale: 50% - :alt: Oblique Cylindrical Equal Area - diff --git a/docs/source/projections/oea.rst b/docs/source/projections/oea.rst deleted file mode 100644 index 379dc157..00000000 --- a/docs/source/projections/oea.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _oea: - -******************************************************************************** -Oblated Equal Area -******************************************************************************** - -.. image:: ./images/oea.png - :scale: 50% - :alt: Oblated Equal Area - diff --git a/docs/source/projections/omerc.rst b/docs/source/projections/omerc.rst deleted file mode 100644 index 114b9fa3..00000000 --- a/docs/source/projections/omerc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _omerc: - -******************************************************************************** -Oblique Mercator -******************************************************************************** - -.. image:: ./images/omerc.png - :scale: 50% - :alt: Oblique Mercator - diff --git a/docs/source/projections/ortel.rst b/docs/source/projections/ortel.rst deleted file mode 100644 index 03f132ef..00000000 --- a/docs/source/projections/ortel.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _ortel: - -******************************************************************************** -Ortelius Oval -******************************************************************************** - -.. image:: ./images/ortel.png - :scale: 50% - :alt: Ortelius Oval - diff --git a/docs/source/projections/ortho.rst b/docs/source/projections/ortho.rst deleted file mode 100644 index 131dbfc7..00000000 --- a/docs/source/projections/ortho.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _ortho: - -******************************************************************************** -Orthographic -******************************************************************************** - -.. image:: ./images/ortho.png - :scale: 50% - :alt: Orthographic - diff --git a/docs/source/projections/pconic.rst b/docs/source/projections/pconic.rst deleted file mode 100644 index 6bc0018e..00000000 --- a/docs/source/projections/pconic.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _pconic: - -******************************************************************************** -Perspective Conic -******************************************************************************** - -.. image:: ./images/pconic.png - :scale: 50% - :alt: Perspective Conic - diff --git a/docs/source/projections/poly.rst b/docs/source/projections/poly.rst deleted file mode 100644 index e252feb5..00000000 --- a/docs/source/projections/poly.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _poly: - -******************************************************************************** -Polyconic (American) -******************************************************************************** - -.. image:: ./images/poly.png - :scale: 50% - :alt: Polyconic (American) - diff --git a/docs/source/projections/putp1.rst b/docs/source/projections/putp1.rst deleted file mode 100644 index 68971a46..00000000 --- a/docs/source/projections/putp1.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp1: - -******************************************************************************** -Putnins P1 -******************************************************************************** - -.. image:: ./images/putp1.png - :scale: 50% - :alt: Putnins P1 - diff --git a/docs/source/projections/putp2.rst b/docs/source/projections/putp2.rst deleted file mode 100644 index 01ea8073..00000000 --- a/docs/source/projections/putp2.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp2: - -******************************************************************************** -Putnins P2 -******************************************************************************** - -.. image:: ./images/putp2.png - :scale: 50% - :alt: Putnins P2 - diff --git a/docs/source/projections/putp3.rst b/docs/source/projections/putp3.rst deleted file mode 100644 index 3aa6b9e6..00000000 --- a/docs/source/projections/putp3.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp3: - -******************************************************************************** -Putnins P3 -******************************************************************************** - -.. image:: ./images/putp3.png - :scale: 50% - :alt: Putnins P3 - diff --git a/docs/source/projections/putp3p.rst b/docs/source/projections/putp3p.rst deleted file mode 100644 index 5b87512e..00000000 --- a/docs/source/projections/putp3p.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp3p: - -******************************************************************************** -Putnins P3' -******************************************************************************** - -.. image:: ./images/putp3p.png - :scale: 50% - :alt: Putnins P3' - diff --git a/docs/source/projections/putp4p.rst b/docs/source/projections/putp4p.rst deleted file mode 100644 index b211ad9b..00000000 --- a/docs/source/projections/putp4p.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp4p: - -******************************************************************************** -Putnins P4' -******************************************************************************** - -.. image:: ./images/putp4p.png - :scale: 50% - :alt: Putnins P4' - diff --git a/docs/source/projections/putp5.rst b/docs/source/projections/putp5.rst deleted file mode 100644 index 5b60a961..00000000 --- a/docs/source/projections/putp5.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp5: - -******************************************************************************** -Putnins P5 -******************************************************************************** - -.. image:: ./images/putp5.png - :scale: 50% - :alt: Putnins P5 - diff --git a/docs/source/projections/putp5p.rst b/docs/source/projections/putp5p.rst deleted file mode 100644 index f586b889..00000000 --- a/docs/source/projections/putp5p.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp5p: - -******************************************************************************** -Putnins P5' -******************************************************************************** - -.. image:: ./images/putp5p.png - :scale: 50% - :alt: Putnins P5' - diff --git a/docs/source/projections/putp6.rst b/docs/source/projections/putp6.rst deleted file mode 100644 index 94683ace..00000000 --- a/docs/source/projections/putp6.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp6: - -******************************************************************************** -Putnins P6 -******************************************************************************** - -.. image:: ./images/putp6.png - :scale: 50% - :alt: Putnins P6 - diff --git a/docs/source/projections/putp6p.rst b/docs/source/projections/putp6p.rst deleted file mode 100644 index 8c3add71..00000000 --- a/docs/source/projections/putp6p.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _putp6p: - -******************************************************************************** -Putnins P6' -******************************************************************************** - -.. image:: ./images/putp6p.png - :scale: 50% - :alt: Putnins P6' - diff --git a/docs/source/projections/qsc.rst b/docs/source/projections/qsc.rst deleted file mode 100644 index dedd6ff4..00000000 --- a/docs/source/projections/qsc.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. _qsc: - -******************************************************************************** -Quadrilateralized Spherical Cube -******************************************************************************** - -+---------------------+----------------------------------------------------------+ -| **Classification** | Azimuthal | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, elliptical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Martin Lambers | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `+lat_0` | Latitude (in degrees) of the view position. | -+---------------------+----------------------------------------------------------+ -| `+lon_0` | Longitude (in degrees) of the view position. | -+---------------------+----------------------------------------------------------+ - -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 - :scale: 50% - :align: center - :alt: Quadrilateralized Spherical Cube - -For this purpose, other alternatives can be used, notably :ref:`gnom` or -:ref:`healpix`. However, QSC projection has the following favorable properties: - -It is an equal-area projection, and at the same time introduces only limited angular -distortions. It treats all cube sides equally, i.e. it does not use different -projections for polar areas and equatorial areas. These properties make QSC -projection a good choice for planetary-scale terrain rendering. Map data can be -organized in quadtree structures for each cube side. See [LambersKolb2012]_ for an example. - -The QSC projection was introduced by [ONeilLaubscher1976]_, -building on previous work by [ChanONeil1975]_. For clarity: The -earlier QSC variant described in [ChanONeil1975]_ became known as the COBE QSC since it -was used by the NASA Cosmic Background Explorer (COBE) project; it is an approximately -equal-area projection and is not the same as the QSC projection. - -See also [CalabrettaGreisen2002]_ Sec. 5.6.2 and 5.6.3 for a description of both and -some analysis. - -In this implementation, the QSC projection projects onto one side of a circumscribed -cube. The cube side is selected by choosing one of the following six projection centers: - -+-------------------------+--------------------+ -| ``+lat_0=0 +lon_0=0`` | front cube side | -+-------------------------+--------------------+ -| ``+lat_0=0 +lon_0=90`` | right cube side | -+-------------------------+--------------------+ -| ``+lat_0=0 +lon_0=180`` | back cube side | -+-------------------------+--------------------+ -| ``+lat_0=0 +lon_0=-90`` | left cube side | -+-------------------------+--------------------+ -| ``+lat_0=90`` | top cube side | -+-------------------------+--------------------+ -| ``+lat_0=-90`` | bottom cube side | -+-------------------------+--------------------+ - -Furthermore, this implementation allows the projection to be applied to ellipsoids. -A preceding shift to a sphere is performed automatically; see [LambersKolb2012]_ for details. - - -Usage -############################################################################### - -The following example uses QSC projection via GDAL to create the six cube side -maps from a world map for the WGS84 ellipsoid:: - - gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=0" \ - -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ - worldmap.tiff frontside.tiff - - gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=90" \ - -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ - worldmap.tiff rightside.tiff - - gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=180" \ - -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ - worldmap.tiff backside.tiff - - gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=-90" \ - -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ - worldmap.tiff leftside.tiff - - gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=90 +lon_0=0" \ - -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ - worldmap.tiff topside.tiff - - gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=-90 +lon_0=0" \ - -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ - worldmap.tiff bottomside.tiff - - -Explanation: - -* QSC projection is selected with ``+wktext +proj=qsc``. -* The WGS84 ellipsoid is specified with ``+ellps=WGS84``. -* The cube side is selected with ``+lat_0=... +lon_0=...``. -* The ``-wo`` options are necessary for GDAL to avoid holes in the output maps. -* The ``-te`` option limits the extends of the output map to the major axis diameter - (from -radius to +radius in both x and y direction). These are the dimensions of one side - of the circumscribing cube. - - -The resulting images can be laid out in a grid like below. - - -.. |topside| image:: ../../images/qsc_topside.jpg - :scale: 50% - :align: middle - :alt: Top side - -.. |leftside| image:: ../../images/qsc_leftside.jpg - :scale: 50% - :align: middle - :alt: Left side - -.. |frontside| image:: ../../images/qsc_frontside.jpg - :scale: 50% - :align: middle - :alt: Front side - -.. |rightside| image:: ../../images/qsc_rightside.jpg - :scale: 50% - :align: middle - :alt: Right side - -.. |backside| image:: ../../images/qsc_backside.jpg - :scale: 50% - :align: middle - :alt: Back side - -.. |bottomside| image:: ../../images/qsc_bottomside.jpg - :scale: 50% - :align: middle - :alt: Bottom side - - -+------------+--------------+-------------+------------+ -| | |topside| | | | -+------------+--------------+-------------+------------+ -| |leftside| | |frontside| | |rightside| | |backside| | -+------------+--------------+-------------+------------+ -| | |bottomside| | | | -+------------+--------------+-------------+------------+ - -Further reading -################################################################################ - -#. `Wikipedia `_ -#. `NASA `_ diff --git a/docs/source/projections/qua_aut.rst b/docs/source/projections/qua_aut.rst deleted file mode 100644 index d3a0aece..00000000 --- a/docs/source/projections/qua_aut.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _qua_aut: - -******************************************************************************** -Quartic Authalic -******************************************************************************** - -.. image:: ./images/qua_aut.png - :scale: 50% - :alt: Quartic Authalic - diff --git a/docs/source/projections/rhealpix.rst b/docs/source/projections/rhealpix.rst deleted file mode 100644 index 1701558e..00000000 --- a/docs/source/projections/rhealpix.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _rhealpix: - -******************************************************************************** -rHEALPix -******************************************************************************** -+---------------------+----------------------------------------------------------+ -| **Classification** | Mixed | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical and elliptical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Alex Raichev and Michael Speth | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `+north_square` | Position of the north polar square. | -| | Valid inputs are 0--3. Defaults to 0. | -+---------------------+----------------------------------------------------------+ -| `+south_square` | Position of the south polar square. | -| | Valid inputs are 0--3. Defaults to 0. | -+---------------------+----------------------------------------------------------+ - -.. image:: ../../images/rhealpix.png - :scale: 75% - :alt: rHEALPix - -rHEALPix is a projection based on the HEALPix projection. The implementation of -rHEALPix uses the HEALPix projection. The rHEALPix combines the peaks of the -HEALPix into a square. The square's position can be translated and rotated across -the x-axis which is a noval approach for the rHEALPix projection. The initial -intention of using rHEALPix in the Spatial Computation Engine Science Collaboration -Environment (SCENZGrid). - -Usage -############################################################################### - -To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following -command:: - - proj +proj=rhealpix -f '%.2f' +ellps=WGS84 +south_square=0 +north_square=2 -E << EOF - > 55 12 - > EOF - 55 12 6115727.86 1553840.13 - - -Further reading -################################################################################ - -#. `NASA `_ -#. `Wikipedia `_ diff --git a/docs/source/projections/robin.rst b/docs/source/projections/robin.rst deleted file mode 100644 index 3e58be46..00000000 --- a/docs/source/projections/robin.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _robin: - -******************************************************************************** -Robinson -******************************************************************************** - -.. image:: ./images/robin.png - :scale: 50% - :alt: Robinson - diff --git a/docs/source/projections/rouss.rst b/docs/source/projections/rouss.rst deleted file mode 100644 index e27fb1cf..00000000 --- a/docs/source/projections/rouss.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _rouss: - -******************************************************************************** -Roussilhe Stereographic -******************************************************************************** - -.. image:: ./images/rouss.png - :scale: 50% - :alt: Roussilhe Stereographic - diff --git a/docs/source/projections/rpoly.rst b/docs/source/projections/rpoly.rst deleted file mode 100644 index 80e0d640..00000000 --- a/docs/source/projections/rpoly.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _rpoly: - -******************************************************************************** -Rectangular Polyconic -******************************************************************************** - -.. image:: ./images/rpoly.png - :scale: 50% - :alt: Rectangular Polyconic - diff --git a/docs/source/projections/sinu.rst b/docs/source/projections/sinu.rst deleted file mode 100644 index a7ebd232..00000000 --- a/docs/source/projections/sinu.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _sinu: - -******************************************************************************** -Sinusoidal (Sanson-Flamsteed) -******************************************************************************** - -.. image:: ./images/sinu.png - :scale: 50% - :alt: Sinusoidal (Sanson-Flamsteed) - -MacBryde and Thomas developed generalized formulas for sever of the -pseudocylindricals with sinusoidal meridians: - -.. math:: - - x = C\lambda(m+cos\theta) / ( m + 1) - -.. math:: - y = C\theta - -.. math:: - - C = \sqrt { (m + 1 ) / n } - diff --git a/docs/source/projections/somerc.rst b/docs/source/projections/somerc.rst deleted file mode 100644 index c572622b..00000000 --- a/docs/source/projections/somerc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _somerc: - -******************************************************************************** -Swiss. Obl. Mercator -******************************************************************************** - -.. image:: ./images/somerc.png - :scale: 50% - :alt: Swiss. Obl. Mercator - diff --git a/docs/source/projections/stere.rst b/docs/source/projections/stere.rst deleted file mode 100644 index d4958ec9..00000000 --- a/docs/source/projections/stere.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _stere: - -******************************************************************************** -Stereographic -******************************************************************************** - -.. image:: ./images/stere.png - :scale: 50% - :alt: Stereographic - diff --git a/docs/source/projections/sterea.rst b/docs/source/projections/sterea.rst deleted file mode 100644 index 4f2f8727..00000000 --- a/docs/source/projections/sterea.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _sterea: - -******************************************************************************** -Oblique Stereographic Alternative -******************************************************************************** - -.. image:: ./images/sterea.png - :scale: 50% - :alt: Oblique Stereographic Alternative - diff --git a/docs/source/projections/tcc.rst b/docs/source/projections/tcc.rst deleted file mode 100644 index 586dd3b8..00000000 --- a/docs/source/projections/tcc.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _tcc: - -******************************************************************************** -Transverse Central Cylindrical -******************************************************************************** - -.. image:: ./images/tcc.png - :scale: 50% - :alt: Transverse Central Cylindrical - diff --git a/docs/source/projections/tcea.rst b/docs/source/projections/tcea.rst deleted file mode 100644 index cf5549a3..00000000 --- a/docs/source/projections/tcea.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _tcea: - -******************************************************************************** -Transverse Cylindrical Equal Area -******************************************************************************** - -.. image:: ./images/tcea.png - :scale: 50% - :alt: Transverse Cylindrical Equal Area - diff --git a/docs/source/projections/tissot.rst b/docs/source/projections/tissot.rst deleted file mode 100644 index 7ec1a741..00000000 --- a/docs/source/projections/tissot.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _tissot: - -******************************************************************************** -Tissot -******************************************************************************** - -.. image:: ./images/tissot.png - :scale: 50% - :alt: Tissot - diff --git a/docs/source/projections/tmerc.rst b/docs/source/projections/tmerc.rst deleted file mode 100644 index 03aa2830..00000000 --- a/docs/source/projections/tmerc.rst +++ /dev/null @@ -1,197 +0,0 @@ -.. _tmerc: - -******************************************************************************** -Transverse Mercator -******************************************************************************** - -The transverse Mercator projection in its various forms is the most widely used projected coordinate system for world topographical and offshore mapping. - -+---------------------+--------------------------------------------------------------------------------+ -| **Classification** | Transverse and oblique cylindrical | -+---------------------+--------------------------------------------------------------------------------+ -| **Available forms** | Forward and inverse, Spherical and Elliptical | -+---------------------+--------------------------------------------------------------------------------+ -| **Defined area** | Global, but reasonably accurate only within 15 degrees of the central meridian | -+---------------------+--------------------------------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+--------------------------------------------------------------------------------+ -| **Options** | -+---------------------+--------------------------------------------------------------------------------+ -| `+lat_0` | Latitude of origin (Default to 0) | -+---------------------+--------------------------------------------------------------------------------+ -| `+k0` | Scale factor at natural origin (Default to 1) | -+---------------------+--------------------------------------------------------------------------------+ - - -.. image:: ./images/tmerc.png - :scale: 50% - :alt: Transverse Mercator - -Usage -##### - - -Prior to the development of the Universal Transverse Mercator coordinate system, several European nations demonstrated the utility of grid-based conformal maps by mapping their territory during the interwar period. -Calculating the distance between two points on these maps could be performed more easily in the field (using the Pythagorean theorem) than was possible using the trigonometric formulas required under the graticule-based system of latitude and longitude. -In the post-war years, these concepts were extended into the Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) coordinate system, which is a global (or universal) system of grid-based maps. - -The following table gives special cases of the Transverse Mercator projection. - -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ -| Projection Name | Areas | Central meridian | Zone width | Scale Factor | -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ -| Transverse Mercator | World wide | Various | less than 6° | Various | -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ -| Transverse Mercator south oriented | Southern Africa | 2° intervals E of 11°E | 2° | 1.000 | -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ -| UTM North hemisphere | World wide equator to 84°N | 6° intervals E & W of 3° E & W | Always 6° | 0.9996 | -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ -| UTM South hemisphere | World wide north of 80°S to equator | 6° intervals E & W of 3° E & W | Always 6° | 0.9996 | -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ -| Gauss-Kruger | Former USSR, Yugoslavia, Germany, S. America, China | Various, according to area | Usually less than 6°, often less than 4° | 1.0000 | -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ -| Gauss Boaga | Italy | Various, according to area | 6° | 0.9996 | -+-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ - - - -Example using Gauss-Kruger on Germany area (aka EPSG:31467) :: - - $ echo 9 51 | proj +proj=tmerc +lat_0=0 +lon_0=9 +k=1 +x_0=3500000 +y_0=0 +ellps=bessel +datum=potsdam +units=m +no_defs - 3500000.00 5651505.56 - -Example using Gauss Boaga on Italy area (EPSG:3004) :: - - $ echo 15 42 | proj +proj=tmerc +lat_0=0 +lon_0=15 +k=0.9996 +x_0=2520000 +y_0=0 +ellps=intl +units=m +no_defs - 2520000.00 4649858.60 - -Mathematical definition -####################### - -The formulas describing the Transverse Mercator are all taken from Evenden's [Evenden2005]_. - -:math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. - -:math:`k_0` is the scale factor at the natural origin (on the central meridian). It can be set with ``+k_0``. - -:math:`M(\phi)` is the meridianal distance. - -Spherical form -************** - -Forward projection -================== - -.. math:: - - B = \cos \phi \sin \lambda - -.. math:: - - x = \frac{k_0}{2} \ln(\frac{1+B}{1-B}) - -.. math:: - - y = k_0 ( \arctan(\frac{\tan(\phi)}{\cos \lambda}) - \phi_0) - - -Inverse projection -================== - -.. math:: - - D = \frac{y}{k_0} + \phi_0 - -.. math:: - - x' = \frac{x}{k_0} - -.. math:: - - \phi = \arcsin(\frac{\sin D}{\cosh x'}) - -.. math:: - - \lambda = \arctan(\frac{\sinh x'}{\cos D}) - - -Elliptical form -*************** - -Forward projection -================== - -.. math:: - - N = \frac{k_0}{(1 - e^2 \sin^2\phi)^{1/2}} - -.. math:: - - R = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi)^{3/2}} - -.. math:: - - t = \tan(\phi) - -.. math:: - - \eta = \frac{e^2}{1-e^2}cos^2\phi - -.. math:: - - x &= k_0 \lambda \cos \phi \\ - &+ \frac{k_0 \lambda^3 \cos^3\phi}{3!}(1-t^2+\eta^2) \\ - &+ \frac{k_0 \lambda^5 \cos^5\phi}{5!}(5-18t^2+t^4+14\eta^2-58t^2\eta^2) \\ - &+\frac{k_0 \lambda^7 \cos^7\phi}{7!}(61-479t^2+179t^4-t^6) - -.. math:: - - y &= M(\phi) \\ - &+ \frac{k_0 \lambda^2 \sin(\phi) \cos \phi}{2!} \\ - &+ \frac{k_0 \lambda^4 \sin(\phi) \cos^3\phi}{4!}(5-t^2+9\eta^2+4\eta^4) \\ - &+ \frac{k_0 \lambda^6 \sin(\phi) \cos^5\phi}{6!}(61-58t^2+t^4+270\eta^2-330t^2\eta^2) \\ - &+ \frac{k_0 \lambda^8 \sin(\phi) \cos^7\phi}{8!}(1385-3111t^2+543t^4-t^6) - -Inverse projection -================== - -.. math:: - - \phi_1 = M^-1(y) - -.. math:: - - N_1 = \frac{k_0}{1 - e^2 \sin^2\phi_1)^{1/2}} - -.. math:: - - R_1 = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi_1)^{3/2}} - -.. math:: - - t_1 = \tan(\phi_1) - -.. math:: - - \eta_1 = \frac{e^2}{1-e^2}cos^2\phi_1 - -.. math:: - - \phi &= \phi_1 \\ - &- \frac{t_1 x^2}{2! R_1 N_1} \\ - &+ \frac{t_1 x^4}{4! R_1 N_1^3}(5+3t_1^2+\eta_1^2-4\eta_1^4-9\eta_1^2t_1^2) \\ - &- \frac{t_1 x^6}{6! R_1 N_1^5}(61+90t_1^2+46\eta_1^2+45t_1^4-252t_1^2\eta_1^2) \\ - &+ \frac{t_1 x^8}{8! R_1 N_1^7}(1385+3633t_1^2+4095t_1^4+1575t_1^6) - -.. math:: - - \lambda &= \frac{x}{\cos \phi N_1} \\ - &- \frac{x^3}{3! \cos \phi N_1^3}(1+2t_1^2+\eta_1^2) \\ - &+ \frac{x^5}{5! \cos \phi N_1^5}(5+6\eta_1^2+28t_1^2-3\eta_1^2+8t_1^2\eta_1^2) \\ - &- \frac{x^7}{7! \cos \phi N_1^7}(61+662t_1^2+1320t_1^4+720t_1^6) - -Further reading -############### - -#. `Wikipedia `_ -#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas `_ diff --git a/docs/source/projections/tpeqd.rst b/docs/source/projections/tpeqd.rst deleted file mode 100644 index e6d7ef29..00000000 --- a/docs/source/projections/tpeqd.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _tpeqd: - -******************************************************************************** -Two Point Equidistant -******************************************************************************** - -.. image:: ./images/tpeqd.png - :scale: 50% - :alt: Two Point Equidistant - diff --git a/docs/source/projections/tpers.rst b/docs/source/projections/tpers.rst deleted file mode 100644 index 345a5faa..00000000 --- a/docs/source/projections/tpers.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _tpers: - -******************************************************************************** -Tilted perspective -******************************************************************************** -+---------------------+----------------------------------------------------------+ -| **Classification** | Azimuthal | -+---------------------+----------------------------------------------------------+ -| **Available forms** | Forward and inverse, spherical projection | -+---------------------+----------------------------------------------------------+ -| **Defined area** | Global | -+---------------------+----------------------------------------------------------+ -| **Implemented by** | Gerald I. Evenden | -+---------------------+----------------------------------------------------------+ -| **Options** | -+---------------------+----------------------------------------------------------+ -| `+h` | Height (in meters) above the surface. Required. | -+---------------------+----------------------------------------------------------+ -| `+azi` | Bearing (in degrees) from due north. | -+---------------------+----------------------------------------------------------+ -| `+tilt` | Angle (in degrees) away from nadir. | -+---------------------+----------------------------------------------------------+ -| `+lat_0` | Latitude (in degrees) of the view position. | -+---------------------+----------------------------------------------------------+ -| `+lon_0` | Longitude (in degrees) of the view position. | -+---------------------+----------------------------------------------------------+ - - -.. image:: ./images/tpers.png - :scale: 50% - :alt: Tilted perspective - - -Tilted Perspective is similar to :ref:`nsper` (``nsper``) in that it simulates a -perspective view from a hight. Where ``nsper`` projects onto a plane tangent to -the surface, Tilted Perspective orients the plane towards the direction of the -view. Thus, extra parameters azi and tilt are required beyond `nsper``'s ``h``. -As with ``nsper``, ``lat_0`` & ``lon_0`` are also required -for satellite position. diff --git a/docs/source/projections/ups.rst b/docs/source/projections/ups.rst deleted file mode 100644 index 7a9ab50b..00000000 --- a/docs/source/projections/ups.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _ups: - -******************************************************************************** -Universal Polar Stereographic -******************************************************************************** - -.. image:: ./images/ups.png - :scale: 50% - :alt: Universal Polar Stereographic - diff --git a/docs/source/projections/urm5.rst b/docs/source/projections/urm5.rst deleted file mode 100644 index 91d06308..00000000 --- a/docs/source/projections/urm5.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _urm5: - -******************************************************************************** -Urmaev V -******************************************************************************** - -.. image:: ./images/urm5.png - :scale: 50% - :alt: Urmaev V - diff --git a/docs/source/projections/urmfps.rst b/docs/source/projections/urmfps.rst deleted file mode 100644 index 515ced84..00000000 --- a/docs/source/projections/urmfps.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _urmfps: - -******************************************************************************** -Urmaev Flat-Polar Sinusoidal -******************************************************************************** - -.. image:: ./images/urmfps.png - :scale: 50% - :alt: Urmaev Flat-Polar Sinusoidal - diff --git a/docs/source/projections/utm.rst b/docs/source/projections/utm.rst deleted file mode 100644 index 7fb66cb8..00000000 --- a/docs/source/projections/utm.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _utm: - -******************************************************************************** -Universal Transverse Mercator (UTM) -******************************************************************************** - -.. image:: ./images/utm.png - :scale: 50% - :alt: Universal Transverse Mercator (UTM) - diff --git a/docs/source/projections/vandg.rst b/docs/source/projections/vandg.rst deleted file mode 100644 index cdc772bb..00000000 --- a/docs/source/projections/vandg.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _vandg: - -******************************************************************************** -van der Grinten (I) -******************************************************************************** - -.. image:: ./images/vandg.png - :scale: 50% - :alt: van der Grinten (I) - diff --git a/docs/source/projections/vandg2.rst b/docs/source/projections/vandg2.rst deleted file mode 100644 index 556929e2..00000000 --- a/docs/source/projections/vandg2.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _vandg2: - -******************************************************************************** -van der Grinten II -******************************************************************************** - -.. image:: ./images/vandg2.png - :scale: 50% - :alt: van der Grinten II - diff --git a/docs/source/projections/vandg3.rst b/docs/source/projections/vandg3.rst deleted file mode 100644 index d767c4d5..00000000 --- a/docs/source/projections/vandg3.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _vandg3: - -******************************************************************************** -van der Grinten III -******************************************************************************** - -.. image:: ./images/vandg3.png - :scale: 50% - :alt: van der Grinten III - diff --git a/docs/source/projections/vandg4.rst b/docs/source/projections/vandg4.rst deleted file mode 100644 index 097ba1d8..00000000 --- a/docs/source/projections/vandg4.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _vandg4: - -******************************************************************************** -van der Grinten IV -******************************************************************************** - -.. image:: ./images/vandg4.png - :scale: 50% - :alt: van der Grinten IV - diff --git a/docs/source/projections/vitk1.rst b/docs/source/projections/vitk1.rst deleted file mode 100644 index b9081547..00000000 --- a/docs/source/projections/vitk1.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _vitk1: - -******************************************************************************** -Vitkovsky I -******************************************************************************** - -.. image:: ./images/vitk1.png - :scale: 50% - :alt: Vitkovsky I - diff --git a/docs/source/projections/wag1.rst b/docs/source/projections/wag1.rst deleted file mode 100644 index dd1ed39e..00000000 --- a/docs/source/projections/wag1.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wag1: - -******************************************************************************** -Wagner I (Kavraisky VI) -******************************************************************************** - -.. image:: ./images/wag1.png - :scale: 50% - :alt: Wagner I (Kavraisky VI) - diff --git a/docs/source/projections/wag2.rst b/docs/source/projections/wag2.rst deleted file mode 100644 index 9c7b0edc..00000000 --- a/docs/source/projections/wag2.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _wag2: - -******************************************************************************** -Wagner II -******************************************************************************** - -.. image:: ./images/wag2.png - :scale: 50% - :alt: Wagner II - - -.. math:: - - x &= 0.92483 \lambda \cos \theta - - y &= 1.38725\theta - - \sin \theta &= 0.88022 \sin(0.8855\phi) diff --git a/docs/source/projections/wag3.rst b/docs/source/projections/wag3.rst deleted file mode 100644 index fb70a0a6..00000000 --- a/docs/source/projections/wag3.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _wag3: - -******************************************************************************** -Wagner III -******************************************************************************** - -.. image:: ./images/wag3.png - :scale: 50% - :alt: Wagner III - - -.. math:: - - x &= [\cos\phi_{ts} / \cos ( 2\phi_{ts} / 3)] \lambda \cos (2\phi /3) - - y = \phi diff --git a/docs/source/projections/wag4.rst b/docs/source/projections/wag4.rst deleted file mode 100644 index 7b8dac96..00000000 --- a/docs/source/projections/wag4.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wag4: - -******************************************************************************** -Wagner IV -******************************************************************************** - -.. image:: ./images/wag4.png - :scale: 50% - :alt: Wagner IV - diff --git a/docs/source/projections/wag5.rst b/docs/source/projections/wag5.rst deleted file mode 100644 index f880290b..00000000 --- a/docs/source/projections/wag5.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wag5: - -******************************************************************************** -Wagner V -******************************************************************************** - -.. image:: ./images/wag5.png - :scale: 50% - :alt: Wagner V - diff --git a/docs/source/projections/wag6.rst b/docs/source/projections/wag6.rst deleted file mode 100644 index f74749a5..00000000 --- a/docs/source/projections/wag6.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wag6: - -******************************************************************************** -Wagner VI -******************************************************************************** - -.. image:: ./images/wag6.png - :scale: 50% - :alt: Wagner VI - diff --git a/docs/source/projections/wag7.rst b/docs/source/projections/wag7.rst deleted file mode 100644 index be1401b8..00000000 --- a/docs/source/projections/wag7.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wag7: - -******************************************************************************** -Wagner VII -******************************************************************************** - -.. image:: ./images/wag7.png - :scale: 50% - :alt: Wagner VII - diff --git a/docs/source/projections/weren.rst b/docs/source/projections/weren.rst deleted file mode 100644 index de7c5abf..00000000 --- a/docs/source/projections/weren.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _weren: - -******************************************************************************** -Werenskiold I -******************************************************************************** - -.. image:: ./images/weren.png - :scale: 50% - :alt: Werenskiold I - diff --git a/docs/source/projections/wink1.rst b/docs/source/projections/wink1.rst deleted file mode 100644 index 00346765..00000000 --- a/docs/source/projections/wink1.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wink1: - -******************************************************************************** -Winkel I -******************************************************************************** - -.. image:: ./images/wink1.png - :scale: 50% - :alt: Winkel I - diff --git a/docs/source/projections/wink2.rst b/docs/source/projections/wink2.rst deleted file mode 100644 index 7e9b48a7..00000000 --- a/docs/source/projections/wink2.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wink2: - -******************************************************************************** -Winkel II -******************************************************************************** - -.. image:: ./images/wink2.png - :scale: 50% - :alt: Winkel II - diff --git a/docs/source/projections/wintri.rst b/docs/source/projections/wintri.rst deleted file mode 100644 index bfd5032f..00000000 --- a/docs/source/projections/wintri.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _wintri: - -******************************************************************************** -Winkel Tripel -******************************************************************************** - -.. image:: ./images/wintri.png - :scale: 50% - :alt: Winkel Tripel - diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst index 8c12c026..5979426a 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 00000000..21200c93 --- /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/usage/operations/projections/aeqd.rst b/docs/source/usage/operations/projections/aeqd.rst new file mode 100644 index 00000000..949cd8a0 --- /dev/null +++ b/docs/source/usage/operations/projections/aeqd.rst @@ -0,0 +1,10 @@ +.. _aeqd: + +******************************************************************************** +Azimuthal Equidistant +******************************************************************************** + +.. image:: ./images/aeqd.png + :scale: 50% + :alt: Azimuthal Equidistant + diff --git a/docs/source/usage/operations/projections/airy.rst b/docs/source/usage/operations/projections/airy.rst new file mode 100644 index 00000000..307af3e3 --- /dev/null +++ b/docs/source/usage/operations/projections/airy.rst @@ -0,0 +1,10 @@ +.. _airy: + +******************************************************************************** +Airy +******************************************************************************** + +.. image:: ./images/airy.png + :scale: 50% + :alt: Airy + diff --git a/docs/source/usage/operations/projections/aitoff.rst b/docs/source/usage/operations/projections/aitoff.rst new file mode 100644 index 00000000..4d681468 --- /dev/null +++ b/docs/source/usage/operations/projections/aitoff.rst @@ -0,0 +1,10 @@ +.. _aitoff: + +******************************************************************************** +Aitoff +******************************************************************************** + +.. image:: ./images/aitoff.png + :scale: 50% + :alt: Aitoff + diff --git a/docs/source/usage/operations/projections/alsk.rst b/docs/source/usage/operations/projections/alsk.rst new file mode 100644 index 00000000..f7a7a0ef --- /dev/null +++ b/docs/source/usage/operations/projections/alsk.rst @@ -0,0 +1,10 @@ +.. _alsk: + +******************************************************************************** +Mod. Stererographics of Alaska +******************************************************************************** + +.. image:: ./images/alsk.png + :scale: 50% + :alt: Mod. Stererographics of Alaska + diff --git a/docs/source/usage/operations/projections/apian.rst b/docs/source/usage/operations/projections/apian.rst new file mode 100644 index 00000000..add501ea --- /dev/null +++ b/docs/source/usage/operations/projections/apian.rst @@ -0,0 +1,10 @@ +.. _apian: + +******************************************************************************** +Apian Globular I +******************************************************************************** + +.. image:: ./images/apian.png + :scale: 50% + :alt: Apian Globular I + diff --git a/docs/source/usage/operations/projections/august.rst b/docs/source/usage/operations/projections/august.rst new file mode 100644 index 00000000..e2ad3516 --- /dev/null +++ b/docs/source/usage/operations/projections/august.rst @@ -0,0 +1,10 @@ +.. _august: + +******************************************************************************** +August Epicycloidal +******************************************************************************** + +.. image:: ./images/august.png + :scale: 50% + :alt: August Epicycloidal + diff --git a/docs/source/usage/operations/projections/bacon.rst b/docs/source/usage/operations/projections/bacon.rst new file mode 100644 index 00000000..a87ea7d8 --- /dev/null +++ b/docs/source/usage/operations/projections/bacon.rst @@ -0,0 +1,10 @@ +.. _bacon: + +******************************************************************************** +Bacon Globular +******************************************************************************** + +.. image:: ./images/bacon.png + :scale: 50% + :alt: Bacon Globular + diff --git a/docs/source/usage/operations/projections/bipc.rst b/docs/source/usage/operations/projections/bipc.rst new file mode 100644 index 00000000..7045f04a --- /dev/null +++ b/docs/source/usage/operations/projections/bipc.rst @@ -0,0 +1,10 @@ +.. _bipc: + +******************************************************************************** +Bipolar conic of western hemisphere +******************************************************************************** + +.. image:: ./images/bipc.png + :scale: 50% + :alt: Bipolar conic of western hemisphere + diff --git a/docs/source/usage/operations/projections/boggs.rst b/docs/source/usage/operations/projections/boggs.rst new file mode 100644 index 00000000..1dd7d19f --- /dev/null +++ b/docs/source/usage/operations/projections/boggs.rst @@ -0,0 +1,10 @@ +.. _boggs: + +******************************************************************************** +Boggs Eumorphic +******************************************************************************** + +.. image:: ./images/boggs.png + :scale: 50% + :alt: Boggs Eumorphic + diff --git a/docs/source/usage/operations/projections/bonne.rst b/docs/source/usage/operations/projections/bonne.rst new file mode 100644 index 00000000..ef87d7c9 --- /dev/null +++ b/docs/source/usage/operations/projections/bonne.rst @@ -0,0 +1,10 @@ +.. _bonne: + +******************************************************************************** +Bonne (Werner lat_1=90) +******************************************************************************** + +.. image:: ./images/bonne.png + :scale: 50% + :alt: Bonne (Werner lat_1=90) + diff --git a/docs/source/usage/operations/projections/calcofi.rst b/docs/source/usage/operations/projections/calcofi.rst new file mode 100644 index 00000000..650416c1 --- /dev/null +++ b/docs/source/usage/operations/projections/calcofi.rst @@ -0,0 +1,95 @@ +.. _calcofi: + +******************************************************************************** +Cal Coop Ocean Fish Invest Lines/Stations +******************************************************************************** + +The CalCOFI pseudo-projection is the line and station coordinate system of the +California Cooperative Oceanic Fisheries Investigations program, known as CalCOFI, for sampling offshore of the west coast of the U.S. and Mexico. + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Only valid for the west coast of USA and Mexico | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Frank Warmerdam | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `No special options for this projection` | ++---------------------+----------------------------------------------------------+ + + +.. image:: ../../../../images/calcofi.png + :scale: 50% + :align: center + :alt: Cal Coop Ocean Fish Invest Lines/Stations + +The coordinate system is based on the Mercator projection with units rotated -30 +degrees from the meridian so that they are oriented with the coastline of the Southern California Bight and Baja California. +Lines increase from Northwest to Southeast. +A unit of line is 12 nautical miles. Stations increase from inshore to offshore. +A unit of station is equal to 4 nautical miles. +The rotation point is located at line 80, station 60, or 34.15 degrees N, -121.15 degrees W, and is depicted by the red dot in the figure. +By convention, the ellipsoid of Clarke 1866 is used to calculate CalCOFI coordinates. + +The CalCOFI program is a joint research effort by the U.S. National Oceanic and +Atmospheric Administration, University of California Scripps Oceanographic Institute, and California Department of Fish and Game. +Surveys have been conducted for the CalCOFI program since 1951, creating one of the oldest and most scientifically valuable joint oceanographic and fisheries data sets in the world. +The CalCOFI line and station coordinate system is now used by several other programs including the Investigaciones Mexicanas de la Corriente de California (IMECOCAL) program offshore of Baja California. +The figure depicts some commonly sampled locations from line 40 to line 156.7 and offshore to station 120. Blue numbers indicate line (bottom) or station (left) numbers along the grid. Note that lines spaced at approximate 3-1/3 intervals are commonly sampled, e.g., lines 43.3 and 46.7. + +Usage +############################################################################### + +A typical forward CalCOFI projection would be from lon/lat coordinates on the +Clark 1866 ellipsoid. +For example:: + + proj +proj=calcofi +ellps=clrk66 -E <`_ +#. `The Investigaciones Mexicanas de la Corriente de California `_ + + + + + + + + + + + + + + diff --git a/docs/source/usage/operations/projections/cass.rst b/docs/source/usage/operations/projections/cass.rst new file mode 100644 index 00000000..83f8c2ce --- /dev/null +++ b/docs/source/usage/operations/projections/cass.rst @@ -0,0 +1,145 @@ +.. _cass: + +******************************************************************************** +Cassini (Cassini-Soldner) +******************************************************************************** + +Although the Cassini projection has been largely replaced by the Transverse Mercator, it is still in limited use outside the United States and was one of the major topographic mapping projections until the early 20th century. + ++---------------------+-------------------------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+-------------------------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical and Elliptical | ++---------------------+-------------------------------------------------------------------------+ +| **Defined area** | Global, but best used near the central meridian with long, narrow areas | ++---------------------+-------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+-------------------------------------------------------------------------+ +| **Options** | ++---------------------+-------------------------------------------------------------------------+ +| `+lat_0` | Latitude of origin (Default to 0) | ++---------------------+-------------------------------------------------------------------------+ + +.. image:: ./images/cass.png + :scale: 50% + :alt: Cassini + +Usage +##### + +There has been little usage of the spherical version of the Cassini, but the ellipsoidal Cassini-Soldner version was adopted by the Ordnance Survey for the official survey of Great Britain during the second half of the 19th century [Steers1970]_. +Many of these maps were prepared at a scale of 1:2,500. +The Cassini-Soldner was also used for the detailed mapping of many German states during the same period. + + +Example using EPSG 30200 (Trinidad 1903, units in clarke's links):: + + $ echo 0.17453293 -1.08210414 | proj +proj=cass +lat_0=10.44166666666667 +lon_0=-61.33333333333334 +x_0=86501.46392051999 +y_0=65379.0134283 +a=6378293.645208759 +b=6356617.987679838 +to_meter=0.201166195164 +no_defs + 66644.94 82536.22 + +Example using EPSG 3068 (Soldner Berlin):: + + $ echo 13.5 52.4 | proj +proj=cass +lat_0=52.41864827777778 +lon_0=13.62720366666667 +x_0=40000 +y_0=10000 +ellps=bessel +datum=potsdam +units=m +no_defs + 31343.05 7932.76 + + +Mathematical definition +####################### + +The formulas describing the Cassini projection are taken from Snyder's [Snyder1987]_. + +:math:`\phi_0` is the latitude of origin that match the center of the map (default to 0). It can be set with ``+lat_0``. + + +Spherical form +============== + +Forward projection +------------------ + +.. math:: + + x = \arcsin(\cos(\phi) \sin(\lambda)) + +.. math:: + + y = \arctan2(\tan(\phi), \cos(\lambda)) - \phi_0 + +Inverse projection +------------------ + +.. math:: + + \phi = \arcsin(\sin(y+\phi_0) \cos(x)) + +.. math:: + + \lambda = \arctan2(\tan(x), \cos(y+\phi_0)) + +Elliptical form +=============== + +Forward projection +------------------ + +.. math:: + + N = (1 - e^2 \sin^2(\phi))^{-1/2} + +.. math:: + + T = \tan^2(\phi) + +.. math:: + + A = \lambda \cos(\phi) + +.. math:: + + C = \frac{e^2}{1-e^2} cos^2(\phi) + +.. math:: + + x = N ( A - T \frac{A^3}{6} - (8-T+8C)T\frac{A^5}{120}) + +.. math:: + + y = M(\phi) - M(\phi_0) + N \tan(\phi)(\frac{A^2}{2} + (5-T+6C)\frac{A^4}{24}) + +and M() is the meridionial distance function. + +Inverse projection +------------------ + +.. math:: + + \phi' = M^{-1}(M(\phi_0)+y) + +if :math:`\phi' = \frac{\pi}{2}` then :math:`\phi=\phi'` and :math:`\lambda=0` + +otherwise evaluate T and N above using :math:`\phi'` and + +.. math:: + + R = (1 - e^2)(1 - e^2 sin^2 \phi')^{-3/2} + +.. math:: + + D = x/N + +.. math:: + + \phi = \phi' - \tan \phi' \frac{N}{R}(\frac{D^2}{2}-(1+3T)\frac{D^4}{24}) + +.. math:: + + \lambda = \frac{(D - T\frac{D^3}{3} + (1+3T)T\frac{D^5}{15})}{\cos \phi'} + +.. _further-reading: + +Further reading +############### + +#. `Wikipedia `_ +#. [Snyder1987]_ +#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas `_ diff --git a/docs/source/usage/operations/projections/cc.rst b/docs/source/usage/operations/projections/cc.rst new file mode 100644 index 00000000..5b30e6c6 --- /dev/null +++ b/docs/source/usage/operations/projections/cc.rst @@ -0,0 +1,10 @@ +.. _cc: + +******************************************************************************** +Central Cylindrical +******************************************************************************** + +.. image:: ./images/cc.png + :scale: 50% + :alt: Central Cylindrical + diff --git a/docs/source/usage/operations/projections/cea.rst b/docs/source/usage/operations/projections/cea.rst new file mode 100644 index 00000000..20ebc285 --- /dev/null +++ b/docs/source/usage/operations/projections/cea.rst @@ -0,0 +1,10 @@ +.. _cea: + +******************************************************************************** +Equal Area Cylindrical +******************************************************************************** + +.. image:: ./images/cea.png + :scale: 50% + :alt: Equal Area Cylindrical + diff --git a/docs/source/usage/operations/projections/chamb.rst b/docs/source/usage/operations/projections/chamb.rst new file mode 100644 index 00000000..2ec9bffe --- /dev/null +++ b/docs/source/usage/operations/projections/chamb.rst @@ -0,0 +1,10 @@ +.. _chamb: + +******************************************************************************** +Chamberlin Trimetric +******************************************************************************** + +.. image:: ./images/chamb.png + :scale: 50% + :alt: Chamberlin Trimetric + diff --git a/docs/source/usage/operations/projections/collg.rst b/docs/source/usage/operations/projections/collg.rst new file mode 100644 index 00000000..aa16182a --- /dev/null +++ b/docs/source/usage/operations/projections/collg.rst @@ -0,0 +1,10 @@ +.. _collg: + +******************************************************************************** +Collignon +******************************************************************************** + +.. image:: ./images/collg.png + :scale: 50% + :alt: Collignon + diff --git a/docs/source/usage/operations/projections/crast.rst b/docs/source/usage/operations/projections/crast.rst new file mode 100644 index 00000000..9d17f274 --- /dev/null +++ b/docs/source/usage/operations/projections/crast.rst @@ -0,0 +1,10 @@ +.. _crast: + +******************************************************************************** +Craster Parabolic (Putnins P4) +******************************************************************************** + +.. image:: ./images/crast.png + :scale: 50% + :alt: Craster Parabolic (Putnins P4) + diff --git a/docs/source/usage/operations/projections/denoy.rst b/docs/source/usage/operations/projections/denoy.rst new file mode 100644 index 00000000..a885ab0e --- /dev/null +++ b/docs/source/usage/operations/projections/denoy.rst @@ -0,0 +1,10 @@ +.. _denoy: + +******************************************************************************** +Denoyer Semi-Elliptical +******************************************************************************** + +.. image:: ./images/denoy.png + :scale: 50% + :alt: Denoyer Semi-Elliptical + diff --git a/docs/source/usage/operations/projections/eck1.rst b/docs/source/usage/operations/projections/eck1.rst new file mode 100644 index 00000000..841533ec --- /dev/null +++ b/docs/source/usage/operations/projections/eck1.rst @@ -0,0 +1,18 @@ +.. _eck1: + +******************************************************************************** +Eckert I +******************************************************************************** + +.. image:: ./images/eck1.png + :scale: 50% + :alt: Eckert I + + +.. math:: + + x &= 2 \sqrt{2/3\pi} \lambda (1- |\phi|/\pi) + + y &= 2 \sqrt{2/3\pi}\phi + + diff --git a/docs/source/usage/operations/projections/eck2.rst b/docs/source/usage/operations/projections/eck2.rst new file mode 100644 index 00000000..b1bd3179 --- /dev/null +++ b/docs/source/usage/operations/projections/eck2.rst @@ -0,0 +1,10 @@ +.. _eck2: + +******************************************************************************** +Eckert II +******************************************************************************** + +.. image:: ./images/eck2.png + :scale: 50% + :alt: Eckert II + diff --git a/docs/source/usage/operations/projections/eck3.rst b/docs/source/usage/operations/projections/eck3.rst new file mode 100644 index 00000000..ecacc32d --- /dev/null +++ b/docs/source/usage/operations/projections/eck3.rst @@ -0,0 +1,10 @@ +.. _eck3: + +******************************************************************************** +Eckert III +******************************************************************************** + +.. image:: ./images/eck3.png + :scale: 50% + :alt: Eckert III + diff --git a/docs/source/usage/operations/projections/eck4.rst b/docs/source/usage/operations/projections/eck4.rst new file mode 100644 index 00000000..3fc6a9fd --- /dev/null +++ b/docs/source/usage/operations/projections/eck4.rst @@ -0,0 +1,19 @@ +.. _eck4: + +******************************************************************************** +Eckert IV +******************************************************************************** + +.. image:: ./images/eck4.png + :scale: 50% + :alt: Eckert IV + + +.. math:: + + x = \lambda(1+cos\phi) / \sqrt{ 2 + \pi } + +.. math:: + y = 2 \phi / \sqrt { 2 + \pi } + + diff --git a/docs/source/usage/operations/projections/eck5.rst b/docs/source/usage/operations/projections/eck5.rst new file mode 100644 index 00000000..1442d99d --- /dev/null +++ b/docs/source/usage/operations/projections/eck5.rst @@ -0,0 +1,10 @@ +.. _eck5: + +******************************************************************************** +Eckert V +******************************************************************************** + +.. image:: ./images/eck5.png + :scale: 50% + :alt: Eckert V + diff --git a/docs/source/usage/operations/projections/eck6.rst b/docs/source/usage/operations/projections/eck6.rst new file mode 100644 index 00000000..caeaefa6 --- /dev/null +++ b/docs/source/usage/operations/projections/eck6.rst @@ -0,0 +1,10 @@ +.. _eck6: + +******************************************************************************** +Eckert VI +******************************************************************************** + +.. image:: ./images/eck6.png + :scale: 50% + :alt: Eckert VI + diff --git a/docs/source/usage/operations/projections/eqc.rst b/docs/source/usage/operations/projections/eqc.rst new file mode 100644 index 00000000..be431977 --- /dev/null +++ b/docs/source/usage/operations/projections/eqc.rst @@ -0,0 +1,110 @@ +.. _eqc: + +******************************************************************************** +Equidistant Cylindrical (Plate Carrée) +******************************************************************************** + +The simplest of all projections. Standard parallels (0° when omitted) may be specified that determine latitude of true scale (k=h=1). + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_ts` | Latitude of true scale. Defaults to 0.0 | ++---------------------+----------------------------------------------------------+ +| `+lat_0` | Center of the map : latitude of origin | ++---------------------+----------------------------------------------------------+ + +.. image:: ./images/eqc.png + :scale: 50% + :alt: Equidistant Cylindrical (Plate Carrée) + +Usage +######## + +Because of the distortions introduced by this projection, it has little use in navigation or cadastral mapping and finds its main use in thematic mapping. +In particular, the plate carrée has become a standard for global raster datasets, such as Celestia and NASA World Wind, because of the particularly simple relationship between the position of an image pixel on the map and its corresponding geographic location on Earth. + +The following table gives special cases of the cylindrical equidistant projection. + ++---------------------------------------------------------+--------------------------+ +| Projection Name | (lat ts=) :math:`\phi_0` | ++---------------------------------------------------------+--------------------------+ +| Plain/Plane Chart | 0° | ++---------------------------------------------------------+--------------------------+ +| Simple Cylindrical | 0° | ++---------------------------------------------------------+--------------------------+ +| Plate Carrée | 0° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller—minimum overall scale distortion | 37°30′ | ++---------------------------------------------------------+--------------------------+ +| E.Grafarend and A.Niermann | 42° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller—minimum continental scale distortion | 43°30′ | ++---------------------------------------------------------+--------------------------+ +| Gall Isographic | 45° | ++---------------------------------------------------------+--------------------------+ +| Ronald Miller Equirectangular | 50°30′ | ++---------------------------------------------------------+--------------------------+ +| E.Grafarend and A.Niermann minimum linear distortion | 61°7′ | ++---------------------------------------------------------+--------------------------+ + + +Example using EPSG 32662 (WGS84 Plate Carrée):: + + $ echo 2 47 | proj +proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs + 222638.98 5232016.07 + +Example using Plate Carrée projection with true scale at latitude 30° and central meridian 90°W:: + + $ echo -88 30 | proj +proj=eqc +lat_ts=30 +lat_0=90w + -8483684.61 13358338.90 + + +Mathematical definition +####################### + +The formulas describing the Equidistant Cylindrical projection are all taken from Snyder's [Snyder1987]_. + +:math:`\phi_{ts}` is the latitude of true scale, that mean the standard parallels where the scale of the projection is true. It can be set with ``+lat_ts``. + +:math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. + + +Forward projection +================== + +.. math:: + + x = \lambda \cos \phi_{ts} + +.. math:: + + y = \phi - \phi_0 + +Inverse projection +================== + +.. math:: + + \lambda = x / cos \phi_{ts} + +.. math:: + + \phi = y + \phi_0 + + +Further reading +############### + +#. `Wikipedia `_ +#. `Wolfram Mathworld `_ + + diff --git a/docs/source/usage/operations/projections/eqdc.rst b/docs/source/usage/operations/projections/eqdc.rst new file mode 100644 index 00000000..3ee5999d --- /dev/null +++ b/docs/source/usage/operations/projections/eqdc.rst @@ -0,0 +1,10 @@ +.. _eqdc: + +******************************************************************************** +Equidistant Conic +******************************************************************************** + +.. image:: ./images/eqdc.png + :scale: 50% + :alt: Equidistant Conic + diff --git a/docs/source/usage/operations/projections/etmerc.rst b/docs/source/usage/operations/projections/etmerc.rst new file mode 100644 index 00000000..b7f89032 --- /dev/null +++ b/docs/source/usage/operations/projections/etmerc.rst @@ -0,0 +1,10 @@ +.. _etmerc: + +******************************************************************************** +Extended Transverse Mercator +******************************************************************************** + +.. image:: ./images/etmerc.png + :scale: 50% + :alt: Extended Transverse Mercator + diff --git a/docs/source/usage/operations/projections/euler.rst b/docs/source/usage/operations/projections/euler.rst new file mode 100644 index 00000000..e495063f --- /dev/null +++ b/docs/source/usage/operations/projections/euler.rst @@ -0,0 +1,10 @@ +.. _euler: + +******************************************************************************** +Euler +******************************************************************************** + +.. image:: ./images/euler.png + :scale: 50% + :alt: Euler + diff --git a/docs/source/usage/operations/projections/fahey.rst b/docs/source/usage/operations/projections/fahey.rst new file mode 100644 index 00000000..2e09337f --- /dev/null +++ b/docs/source/usage/operations/projections/fahey.rst @@ -0,0 +1,10 @@ +.. _fahey: + +******************************************************************************** +Fahey +******************************************************************************** + +.. image:: ./images/fahey.png + :scale: 50% + :alt: Fahey + diff --git a/docs/source/usage/operations/projections/fouc.rst b/docs/source/usage/operations/projections/fouc.rst new file mode 100644 index 00000000..7467dcb1 --- /dev/null +++ b/docs/source/usage/operations/projections/fouc.rst @@ -0,0 +1,10 @@ +.. _fouc: + +******************************************************************************** +Foucaut +******************************************************************************** + +.. image:: ./images/fouc.png + :scale: 50% + :alt: Foucaut + diff --git a/docs/source/usage/operations/projections/fouc_s.rst b/docs/source/usage/operations/projections/fouc_s.rst new file mode 100644 index 00000000..ac353adb --- /dev/null +++ b/docs/source/usage/operations/projections/fouc_s.rst @@ -0,0 +1,25 @@ +.. _fouc_s: + +******************************************************************************** +Foucaut Sinusoidal +******************************************************************************** + +.. image:: ./images/fouc_s.png + :scale: 50% + :alt: Foucaut Sinusoidal + + +The `y`-axis is based upon a weighted mean of the cylindrical equal-area and +the sinusoidal projections. Parameter :math:`n=n` is the weighting factor where +:math:`0 <= n <= 1`. + +.. math:: + + x &= \lambda \cos \phi / (n + (1 - n) \ cos \phi) + + y &= n \phi + (1 - n) \sin \phi + +For the inverse, the Newton-Raphson method can be used to determine +:math:`\phi` from the equation for :math:`y` above. As :math:`n \rightarrow 0` and +:math:`\phi \rightarrow \pi/2`, convergence is slow but for :math:`n = 0`, :math:`\phi = +\sin^1y` diff --git a/docs/source/usage/operations/projections/gall.rst b/docs/source/usage/operations/projections/gall.rst new file mode 100644 index 00000000..b9120d9f --- /dev/null +++ b/docs/source/usage/operations/projections/gall.rst @@ -0,0 +1,84 @@ +.. _gall: + +******************************************************************************** +Gall (Gall Stereographic) +******************************************************************************** + +The Gall stereographic projection, presented by James Gall in 1855, is a cylindrical projection. +It is neither equal-area nor conformal but instead tries to balance the distortion inherent in any projection. + ++---------------------+--------------------------------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+--------------------------------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical | ++---------------------+--------------------------------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+--------------------------------------------------------------------------------+ +| **Options** | No special options for this projection | ++---------------------+--------------------------------------------------------------------------------+ + + +.. image:: ./images/gall.png + :scale: 50% + :alt: Gall (Gall Stereographic) + +Usage +##### + +The need for a world map which avoids some of the scale exaggeration of the Mercator projection has led to some commonly used cylindrical modifications, as well as to other modifications which are not cylindrical. +The earliest common cylindrical example was developed by James Gall of Edinburgh about 1855 (Gall, 1885, p. 119-123). +His meridians are equally spaced, but the parallels are spaced at increasing intervals away from the Equator. +The parallels of latitude are actually projected onto a cylinder wrapped about the sphere, but cutting it at lats. 45° N. and S., the point of perspective being a point on the Equator opposite the meridian being projected. +It is used in several British atlases, but seldom in the United States. +The Gall projection is neither conformal nor equal-area, but has a blend of various features. +Unlike the Mercator, the Gall shows the poles as lines running across the top and bottom of the map. + + +Example using Gall Stereographical :: + + $ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs + 708432.90 5193386.36 + +Example using Gall Stereographical (Central meridian 90°W) :: + + $ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs + 7792761.91 5193386.36 + +Mathematical definition +####################### + +The formulas describing the Gall Stereographical are all taken from Snyder's [Snyder1993]_. + +Spherical form +************** + +Forward projection +================== + +.. math:: + + x = \frac{\lambda}{\sqrt{2}} + +.. math:: + + y = (1+\frac{\sqrt{2}}{2}) \tan(\phi/2) + +Inverse projection +================== + +.. math:: + + \phi = 2 \arctan( \frac{y}{1+\frac{\sqrt{2}}{2}} ) + +.. math:: + + \lambda = \sqrt{2} x + + +Further reading +############### + +#. `Wikipedia `_ +#. `Cartographic Projection Procedures for the UNIX Environment-A User's Manual `_ diff --git a/docs/source/usage/operations/projections/geos.rst b/docs/source/usage/operations/projections/geos.rst new file mode 100644 index 00000000..3b24e1f7 --- /dev/null +++ b/docs/source/usage/operations/projections/geos.rst @@ -0,0 +1,72 @@ +.. _geos: + +******************************************************************************** +Geostationary Satellite View +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden and Martin Raspaud$ | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+h` | Satellite height above earth. Required. | ++---------------------+----------------------------------------------------------+ +| `+sweep` | Sweep angle axis of the viewing instrument. | +| | Valid options are ``x`` and ``y``. Defaults to ``y``. | ++---------------------+----------------------------------------------------------+ +| `+lon_0` | Subsatellite longitude point. | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/geos.png + :scale: 50% + :alt: Geostationary Satellite View + +The geos projection pictures how a geostationary satellite scans the earth at regular +scanning angle intervals. + + +Usage +############################################################################### + +In order to project using the geos projection you can do the following:: + + proj +proj=geos +h=35785831.0 + +The required argument ``h`` is the viewing point (satellite position) height above +the earth. + +The projection coordinate relate to the scanning angle by the following simple +relation:: + + scanning_angle (radians) = projection_coordinate / h + + +Note on sweep angle +------------------------------------------------------------------------------- + +The viewing instrument on-board geostationary satellites described by this +projection have a two-axis gimbal viewing geometry. This means that the different +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 + :scale: 50% + :alt: Gimbal geometry + +In the image above, the outer-gimbal axis, or sweep-angle axis, is the N/S axis (``y``) +while the inner-gimbal axis, or fixed-angle axis, is the E/W axis (``x``). + +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 +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/gins8.rst b/docs/source/usage/operations/projections/gins8.rst new file mode 100644 index 00000000..f6adb092 --- /dev/null +++ b/docs/source/usage/operations/projections/gins8.rst @@ -0,0 +1,10 @@ +.. _gins8: + +******************************************************************************** +Ginsburg VIII (TsNIIGAiK) +******************************************************************************** + +.. image:: ./images/gins8.png + :scale: 50% + :alt: Ginsburg VIII (TsNIIGAiK) + diff --git a/docs/source/usage/operations/projections/gn_sinu.rst b/docs/source/usage/operations/projections/gn_sinu.rst new file mode 100644 index 00000000..c1017c27 --- /dev/null +++ b/docs/source/usage/operations/projections/gn_sinu.rst @@ -0,0 +1,10 @@ +.. _gn_sinu: + +******************************************************************************** +General Sinusoidal Series +******************************************************************************** + +.. image:: ./images/gn_sinu.png + :scale: 50% + :alt: General Sinusoidal Series + diff --git a/docs/source/usage/operations/projections/gnom.rst b/docs/source/usage/operations/projections/gnom.rst new file mode 100644 index 00000000..08d0db5f --- /dev/null +++ b/docs/source/usage/operations/projections/gnom.rst @@ -0,0 +1,10 @@ +.. _gnom: + +******************************************************************************** +Gnomonic +******************************************************************************** + +.. image:: ./images/gnom.png + :scale: 50% + :alt: Gnomonic + diff --git a/docs/source/usage/operations/projections/goode.rst b/docs/source/usage/operations/projections/goode.rst new file mode 100644 index 00000000..c4590bf2 --- /dev/null +++ b/docs/source/usage/operations/projections/goode.rst @@ -0,0 +1,10 @@ +.. _goode: + +******************************************************************************** +Goode Homolosine +******************************************************************************** + +.. image:: ./images/goode.png + :scale: 50% + :alt: Goode Homolosine + diff --git a/docs/source/usage/operations/projections/gs48.rst b/docs/source/usage/operations/projections/gs48.rst new file mode 100644 index 00000000..bdaa367c --- /dev/null +++ b/docs/source/usage/operations/projections/gs48.rst @@ -0,0 +1,10 @@ +.. _gs48: + +******************************************************************************** +Mod. Stererographics of 48 U.S. +******************************************************************************** + +.. image:: ./images/gs48.png + :scale: 50% + :alt: Mod. Stererographics of 48 U.S. + diff --git a/docs/source/usage/operations/projections/gs50.rst b/docs/source/usage/operations/projections/gs50.rst new file mode 100644 index 00000000..0d4b7e81 --- /dev/null +++ b/docs/source/usage/operations/projections/gs50.rst @@ -0,0 +1,10 @@ +.. _gs50: + +******************************************************************************** +Mod. Stererographics of 50 U.S. +******************************************************************************** + +.. image:: ./images/gs50.png + :scale: 50% + :alt: Mod. Stererographics of 50 U.S. + diff --git a/docs/source/usage/operations/projections/gstmerc.rst b/docs/source/usage/operations/projections/gstmerc.rst new file mode 100644 index 00000000..fc587ab0 --- /dev/null +++ b/docs/source/usage/operations/projections/gstmerc.rst @@ -0,0 +1,10 @@ +.. _gstmerc: + +******************************************************************************** +Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) +******************************************************************************** + +.. image:: ./images/gstmerc.png + :scale: 50% + :alt: Gauss-Schreiber Transverse Mercator (aka Gauss-Laborde Reunion) + diff --git a/docs/source/usage/operations/projections/hammer.rst b/docs/source/usage/operations/projections/hammer.rst new file mode 100644 index 00000000..e795b91b --- /dev/null +++ b/docs/source/usage/operations/projections/hammer.rst @@ -0,0 +1,10 @@ +.. _hammer: + +******************************************************************************** +Hammer & Eckert-Greifendorff +******************************************************************************** + +.. image:: ./images/hammer.png + :scale: 50% + :alt: Hammer & Eckert-Greifendorff + diff --git a/docs/source/usage/operations/projections/hatano.rst b/docs/source/usage/operations/projections/hatano.rst new file mode 100644 index 00000000..5d0c63b7 --- /dev/null +++ b/docs/source/usage/operations/projections/hatano.rst @@ -0,0 +1,70 @@ +.. _hatano: + +******************************************************************************** +Hatano Asymmetrical Equal Area +******************************************************************************** + + + + ++---------------------+----------------------------------------------------------+ +| **Classification** | :term:`Pseudocylindrical Projection` | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best between standard parallels | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_1` | Standard Parallel 1 | ++---------------------+----------------------------------------------------------+ +| `+lat_2` | Standard Parallel 2 | ++---------------------+----------------------------------------------------------+ +| `+sym` | Symmetric form used instead of asymmetric | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/hatano.png + :scale: 50% + :alt: Hatano Asymmetrical Equal Area + + + +Mathematical Definition +-------------------------------------------------------------------------------- + +Forward +................................................................................ + +.. math:: + + x &= 0.85\lambda \cos \theta + + y &= C_y \sin \theta + + P(\theta) &= 2\theta + \sin 2\theta - C_p \sin \phi + + P'(\theta) &= 2(1 + \cos 2\theta) + + \theta_0 &= 2\phi + + +==================================== ================== =================== +Condition :math:`C_p` :math:`C_p` +==================================== ================== =================== +if ``+sym`` or :math:`\phi > 0` 1.75859 2.67595 +if not ``+sym`` and :math:`\phi < 0` 1.93052 2.43763 +==================================== ================== =================== + +For :math:`\phi = 0`, :math:`y \leftarrow 0`, and :math:`x \leftarrow 0.85\lambda`. + +Further reading +-------------------------------------------------------------------------------- + +#. `Compare Map Projections `__ +#. `Mathworks `__ + + + diff --git a/docs/source/usage/operations/projections/healpix.rst b/docs/source/usage/operations/projections/healpix.rst new file mode 100644 index 00000000..20815d76 --- /dev/null +++ b/docs/source/usage/operations/projections/healpix.rst @@ -0,0 +1,55 @@ +.. _healpix: + +******************************************************************************** +HEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Mixed | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Alex Raichev and Michael Speth | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `No special options for this projection` | ++---------------------+----------------------------------------------------------+ + +.. image:: ../../../../images/healpix.png + :scale: 75% + :alt: HEALPix + +The HEALPix projection is area preserving and can be used with a spherical and +ellipsoidal model. It was initially developed for mapping cosmic background +microwave radiation. The image below is the graphical representation of the +mapping and consists of eight isomorphic triangular interrupted map graticules. +The north and south contains four in which straight meridians converge polewards +to a point and unequally spaced horizontal parallels. HEALPix provides a mapping +in which points of equal latitude and equally spaced longitude are mapped to points +of equal latitude and equally spaced longitude with the module of the polar +interruptions. + + +Usage +############################################################################### + +To run a forward HEALPix projection on a unit sphere model, use the following command:: + + proj +proj=healpix +lon_0=0 +a=1 -E <`_ +#. `Wikipedia `_ + + + + + diff --git a/docs/source/usage/operations/projections/igh.rst b/docs/source/usage/operations/projections/igh.rst new file mode 100644 index 00000000..d74e1362 --- /dev/null +++ b/docs/source/usage/operations/projections/igh.rst @@ -0,0 +1,10 @@ +.. _igh: + +******************************************************************************** +Interrupted Goode Homolosine +******************************************************************************** + +.. image:: ./images/igh.png + :scale: 50% + :alt: Interrupted Goode Homolosine + diff --git a/docs/source/usage/operations/projections/images/aea.png b/docs/source/usage/operations/projections/images/aea.png new file mode 100644 index 00000000..7fdd4ece Binary files /dev/null and b/docs/source/usage/operations/projections/images/aea.png differ diff --git a/docs/source/usage/operations/projections/images/aeqd.png b/docs/source/usage/operations/projections/images/aeqd.png new file mode 100644 index 00000000..8e45b2c0 Binary files /dev/null and b/docs/source/usage/operations/projections/images/aeqd.png differ diff --git a/docs/source/usage/operations/projections/images/airy.png b/docs/source/usage/operations/projections/images/airy.png new file mode 100644 index 00000000..a441e317 Binary files /dev/null and b/docs/source/usage/operations/projections/images/airy.png differ diff --git a/docs/source/usage/operations/projections/images/aitoff.png b/docs/source/usage/operations/projections/images/aitoff.png new file mode 100644 index 00000000..3449dcd5 Binary files /dev/null and b/docs/source/usage/operations/projections/images/aitoff.png differ diff --git a/docs/source/usage/operations/projections/images/alsk.png b/docs/source/usage/operations/projections/images/alsk.png new file mode 100644 index 00000000..6f6e2014 Binary files /dev/null and b/docs/source/usage/operations/projections/images/alsk.png differ diff --git a/docs/source/usage/operations/projections/images/apian.png b/docs/source/usage/operations/projections/images/apian.png new file mode 100644 index 00000000..95857ae3 Binary files /dev/null and b/docs/source/usage/operations/projections/images/apian.png differ diff --git a/docs/source/usage/operations/projections/images/august.png b/docs/source/usage/operations/projections/images/august.png new file mode 100644 index 00000000..9d9fece6 Binary files /dev/null and b/docs/source/usage/operations/projections/images/august.png differ diff --git a/docs/source/usage/operations/projections/images/bacon.png b/docs/source/usage/operations/projections/images/bacon.png new file mode 100644 index 00000000..62deae63 Binary files /dev/null and b/docs/source/usage/operations/projections/images/bacon.png differ diff --git a/docs/source/usage/operations/projections/images/bipc.png b/docs/source/usage/operations/projections/images/bipc.png new file mode 100644 index 00000000..7b8ab39c Binary files /dev/null and b/docs/source/usage/operations/projections/images/bipc.png differ diff --git a/docs/source/usage/operations/projections/images/boggs.png b/docs/source/usage/operations/projections/images/boggs.png new file mode 100644 index 00000000..42dd4c13 Binary files /dev/null and b/docs/source/usage/operations/projections/images/boggs.png differ diff --git a/docs/source/usage/operations/projections/images/bonne.png b/docs/source/usage/operations/projections/images/bonne.png new file mode 100644 index 00000000..12f93217 Binary files /dev/null and b/docs/source/usage/operations/projections/images/bonne.png differ diff --git a/docs/source/usage/operations/projections/images/calcofi.png b/docs/source/usage/operations/projections/images/calcofi.png new file mode 100644 index 00000000..2fd405ac Binary files /dev/null and b/docs/source/usage/operations/projections/images/calcofi.png differ diff --git a/docs/source/usage/operations/projections/images/cass.png b/docs/source/usage/operations/projections/images/cass.png new file mode 100644 index 00000000..e44c46af Binary files /dev/null and b/docs/source/usage/operations/projections/images/cass.png differ diff --git a/docs/source/usage/operations/projections/images/cc.png b/docs/source/usage/operations/projections/images/cc.png new file mode 100644 index 00000000..3beaedfd Binary files /dev/null and b/docs/source/usage/operations/projections/images/cc.png differ diff --git a/docs/source/usage/operations/projections/images/cea.png b/docs/source/usage/operations/projections/images/cea.png new file mode 100644 index 00000000..eca2319d Binary files /dev/null and b/docs/source/usage/operations/projections/images/cea.png differ diff --git a/docs/source/usage/operations/projections/images/chamb.png b/docs/source/usage/operations/projections/images/chamb.png new file mode 100644 index 00000000..a87e6c68 Binary files /dev/null and b/docs/source/usage/operations/projections/images/chamb.png differ diff --git a/docs/source/usage/operations/projections/images/collg.png b/docs/source/usage/operations/projections/images/collg.png new file mode 100644 index 00000000..851201da Binary files /dev/null and b/docs/source/usage/operations/projections/images/collg.png differ diff --git a/docs/source/usage/operations/projections/images/comill.png b/docs/source/usage/operations/projections/images/comill.png new file mode 100644 index 00000000..725a0118 Binary files /dev/null and b/docs/source/usage/operations/projections/images/comill.png differ diff --git a/docs/source/usage/operations/projections/images/crast.png b/docs/source/usage/operations/projections/images/crast.png new file mode 100644 index 00000000..abd4d32a Binary files /dev/null and b/docs/source/usage/operations/projections/images/crast.png differ diff --git a/docs/source/usage/operations/projections/images/denoy.png b/docs/source/usage/operations/projections/images/denoy.png new file mode 100644 index 00000000..2871cf84 Binary files /dev/null and b/docs/source/usage/operations/projections/images/denoy.png differ diff --git a/docs/source/usage/operations/projections/images/eck1.png b/docs/source/usage/operations/projections/images/eck1.png new file mode 100644 index 00000000..b892d39e Binary files /dev/null and b/docs/source/usage/operations/projections/images/eck1.png differ diff --git a/docs/source/usage/operations/projections/images/eck2.png b/docs/source/usage/operations/projections/images/eck2.png new file mode 100644 index 00000000..ff011598 Binary files /dev/null and b/docs/source/usage/operations/projections/images/eck2.png differ diff --git a/docs/source/usage/operations/projections/images/eck3.png b/docs/source/usage/operations/projections/images/eck3.png new file mode 100644 index 00000000..f828eed0 Binary files /dev/null and b/docs/source/usage/operations/projections/images/eck3.png differ diff --git a/docs/source/usage/operations/projections/images/eck4.png b/docs/source/usage/operations/projections/images/eck4.png new file mode 100644 index 00000000..d7ff87bb Binary files /dev/null and b/docs/source/usage/operations/projections/images/eck4.png differ diff --git a/docs/source/usage/operations/projections/images/eck5.png b/docs/source/usage/operations/projections/images/eck5.png new file mode 100644 index 00000000..3df303c6 Binary files /dev/null and b/docs/source/usage/operations/projections/images/eck5.png differ diff --git a/docs/source/usage/operations/projections/images/eck6.png b/docs/source/usage/operations/projections/images/eck6.png new file mode 100644 index 00000000..d22f4956 Binary files /dev/null and b/docs/source/usage/operations/projections/images/eck6.png differ diff --git a/docs/source/usage/operations/projections/images/eqc.png b/docs/source/usage/operations/projections/images/eqc.png new file mode 100644 index 00000000..b2d8ba23 Binary files /dev/null and b/docs/source/usage/operations/projections/images/eqc.png differ diff --git a/docs/source/usage/operations/projections/images/eqdc.png b/docs/source/usage/operations/projections/images/eqdc.png new file mode 100644 index 00000000..f2330a8e Binary files /dev/null and b/docs/source/usage/operations/projections/images/eqdc.png differ diff --git a/docs/source/usage/operations/projections/images/etmerc.png b/docs/source/usage/operations/projections/images/etmerc.png new file mode 100644 index 00000000..8e6bb39b Binary files /dev/null and b/docs/source/usage/operations/projections/images/etmerc.png differ diff --git a/docs/source/usage/operations/projections/images/euler.png b/docs/source/usage/operations/projections/images/euler.png new file mode 100644 index 00000000..c9c6e4c8 Binary files /dev/null and b/docs/source/usage/operations/projections/images/euler.png differ diff --git a/docs/source/usage/operations/projections/images/fahey.png b/docs/source/usage/operations/projections/images/fahey.png new file mode 100644 index 00000000..8b870b8a Binary files /dev/null and b/docs/source/usage/operations/projections/images/fahey.png differ diff --git a/docs/source/usage/operations/projections/images/fouc.png b/docs/source/usage/operations/projections/images/fouc.png new file mode 100644 index 00000000..6d33216b Binary files /dev/null and b/docs/source/usage/operations/projections/images/fouc.png differ diff --git a/docs/source/usage/operations/projections/images/fouc_s.png b/docs/source/usage/operations/projections/images/fouc_s.png new file mode 100644 index 00000000..401f5ee4 Binary files /dev/null and b/docs/source/usage/operations/projections/images/fouc_s.png differ diff --git a/docs/source/usage/operations/projections/images/gall.png b/docs/source/usage/operations/projections/images/gall.png new file mode 100644 index 00000000..819b5d12 Binary files /dev/null and b/docs/source/usage/operations/projections/images/gall.png differ diff --git a/docs/source/usage/operations/projections/images/geos.png b/docs/source/usage/operations/projections/images/geos.png new file mode 100644 index 00000000..e44fa41b Binary files /dev/null and b/docs/source/usage/operations/projections/images/geos.png differ diff --git a/docs/source/usage/operations/projections/images/gins8.png b/docs/source/usage/operations/projections/images/gins8.png new file mode 100644 index 00000000..12fbae93 Binary files /dev/null and b/docs/source/usage/operations/projections/images/gins8.png differ diff --git a/docs/source/usage/operations/projections/images/gn_sinu.png b/docs/source/usage/operations/projections/images/gn_sinu.png new file mode 100644 index 00000000..f02e119e Binary files /dev/null and b/docs/source/usage/operations/projections/images/gn_sinu.png differ diff --git a/docs/source/usage/operations/projections/images/gnom.png b/docs/source/usage/operations/projections/images/gnom.png new file mode 100644 index 00000000..c079d31a Binary files /dev/null and b/docs/source/usage/operations/projections/images/gnom.png differ diff --git a/docs/source/usage/operations/projections/images/goode.png b/docs/source/usage/operations/projections/images/goode.png new file mode 100644 index 00000000..7001e8d2 Binary files /dev/null and b/docs/source/usage/operations/projections/images/goode.png differ diff --git a/docs/source/usage/operations/projections/images/gs48.png b/docs/source/usage/operations/projections/images/gs48.png new file mode 100644 index 00000000..574e368f Binary files /dev/null and b/docs/source/usage/operations/projections/images/gs48.png differ diff --git a/docs/source/usage/operations/projections/images/gs50.png b/docs/source/usage/operations/projections/images/gs50.png new file mode 100644 index 00000000..7244b160 Binary files /dev/null and b/docs/source/usage/operations/projections/images/gs50.png differ diff --git a/docs/source/usage/operations/projections/images/gstmerc.png b/docs/source/usage/operations/projections/images/gstmerc.png new file mode 100644 index 00000000..d553ea60 Binary files /dev/null and b/docs/source/usage/operations/projections/images/gstmerc.png differ diff --git a/docs/source/usage/operations/projections/images/hammer.png b/docs/source/usage/operations/projections/images/hammer.png new file mode 100644 index 00000000..83848479 Binary files /dev/null and b/docs/source/usage/operations/projections/images/hammer.png differ diff --git a/docs/source/usage/operations/projections/images/hatano.png b/docs/source/usage/operations/projections/images/hatano.png new file mode 100644 index 00000000..b3f47377 Binary files /dev/null and b/docs/source/usage/operations/projections/images/hatano.png differ diff --git a/docs/source/usage/operations/projections/images/healpix.png b/docs/source/usage/operations/projections/images/healpix.png new file mode 100644 index 00000000..c58a155c Binary files /dev/null and b/docs/source/usage/operations/projections/images/healpix.png differ diff --git a/docs/source/usage/operations/projections/images/igh.png b/docs/source/usage/operations/projections/images/igh.png new file mode 100644 index 00000000..36336eec Binary files /dev/null and b/docs/source/usage/operations/projections/images/igh.png differ diff --git a/docs/source/usage/operations/projections/images/imw_p.png b/docs/source/usage/operations/projections/images/imw_p.png new file mode 100644 index 00000000..74cfe81b Binary files /dev/null and b/docs/source/usage/operations/projections/images/imw_p.png differ diff --git a/docs/source/usage/operations/projections/images/isea.png b/docs/source/usage/operations/projections/images/isea.png new file mode 100644 index 00000000..23cfbf74 Binary files /dev/null and b/docs/source/usage/operations/projections/images/isea.png differ diff --git a/docs/source/usage/operations/projections/images/kav5.png b/docs/source/usage/operations/projections/images/kav5.png new file mode 100644 index 00000000..d5c45400 Binary files /dev/null and b/docs/source/usage/operations/projections/images/kav5.png differ diff --git a/docs/source/usage/operations/projections/images/kav7.png b/docs/source/usage/operations/projections/images/kav7.png new file mode 100644 index 00000000..50d7e6e6 Binary files /dev/null and b/docs/source/usage/operations/projections/images/kav7.png differ diff --git a/docs/source/usage/operations/projections/images/krovak.png b/docs/source/usage/operations/projections/images/krovak.png new file mode 100644 index 00000000..d0d69547 Binary files /dev/null and b/docs/source/usage/operations/projections/images/krovak.png differ diff --git a/docs/source/usage/operations/projections/images/labrd.png b/docs/source/usage/operations/projections/images/labrd.png new file mode 100644 index 00000000..e4a174c0 Binary files /dev/null and b/docs/source/usage/operations/projections/images/labrd.png differ diff --git a/docs/source/usage/operations/projections/images/laea.png b/docs/source/usage/operations/projections/images/laea.png new file mode 100644 index 00000000..f52c7c1f Binary files /dev/null and b/docs/source/usage/operations/projections/images/laea.png differ diff --git a/docs/source/usage/operations/projections/images/lagrng.png b/docs/source/usage/operations/projections/images/lagrng.png new file mode 100644 index 00000000..e48210bb Binary files /dev/null and b/docs/source/usage/operations/projections/images/lagrng.png differ diff --git a/docs/source/usage/operations/projections/images/larr.png b/docs/source/usage/operations/projections/images/larr.png new file mode 100644 index 00000000..967b91d2 Binary files /dev/null and b/docs/source/usage/operations/projections/images/larr.png differ diff --git a/docs/source/usage/operations/projections/images/lask.png b/docs/source/usage/operations/projections/images/lask.png new file mode 100644 index 00000000..dff0e8fa Binary files /dev/null and b/docs/source/usage/operations/projections/images/lask.png differ diff --git a/docs/source/usage/operations/projections/images/lcc.png b/docs/source/usage/operations/projections/images/lcc.png new file mode 100644 index 00000000..4714b74e Binary files /dev/null and b/docs/source/usage/operations/projections/images/lcc.png differ diff --git a/docs/source/usage/operations/projections/images/lcca.png b/docs/source/usage/operations/projections/images/lcca.png new file mode 100644 index 00000000..0c404670 Binary files /dev/null and b/docs/source/usage/operations/projections/images/lcca.png differ diff --git a/docs/source/usage/operations/projections/images/leac.png b/docs/source/usage/operations/projections/images/leac.png new file mode 100644 index 00000000..1f57d192 Binary files /dev/null and b/docs/source/usage/operations/projections/images/leac.png differ diff --git a/docs/source/usage/operations/projections/images/lee_os.png b/docs/source/usage/operations/projections/images/lee_os.png new file mode 100644 index 00000000..3e258393 Binary files /dev/null and b/docs/source/usage/operations/projections/images/lee_os.png differ diff --git a/docs/source/usage/operations/projections/images/loxim.png b/docs/source/usage/operations/projections/images/loxim.png new file mode 100644 index 00000000..a03ba94e Binary files /dev/null and b/docs/source/usage/operations/projections/images/loxim.png differ diff --git a/docs/source/usage/operations/projections/images/lsat.png b/docs/source/usage/operations/projections/images/lsat.png new file mode 100644 index 00000000..ec608544 Binary files /dev/null and b/docs/source/usage/operations/projections/images/lsat.png differ diff --git a/docs/source/usage/operations/projections/images/mbt_fps.png b/docs/source/usage/operations/projections/images/mbt_fps.png new file mode 100644 index 00000000..e97cd21e Binary files /dev/null and b/docs/source/usage/operations/projections/images/mbt_fps.png differ diff --git a/docs/source/usage/operations/projections/images/mbt_s.png b/docs/source/usage/operations/projections/images/mbt_s.png new file mode 100644 index 00000000..4432e83b Binary files /dev/null and b/docs/source/usage/operations/projections/images/mbt_s.png differ diff --git a/docs/source/usage/operations/projections/images/mbtfpp.png b/docs/source/usage/operations/projections/images/mbtfpp.png new file mode 100644 index 00000000..3d0c4fb5 Binary files /dev/null and b/docs/source/usage/operations/projections/images/mbtfpp.png differ diff --git a/docs/source/usage/operations/projections/images/mbtfpq.png b/docs/source/usage/operations/projections/images/mbtfpq.png new file mode 100644 index 00000000..b31c52ce Binary files /dev/null and b/docs/source/usage/operations/projections/images/mbtfpq.png differ diff --git a/docs/source/usage/operations/projections/images/mbtfps.png b/docs/source/usage/operations/projections/images/mbtfps.png new file mode 100644 index 00000000..83891be6 Binary files /dev/null and b/docs/source/usage/operations/projections/images/mbtfps.png differ diff --git a/docs/source/usage/operations/projections/images/merc.png b/docs/source/usage/operations/projections/images/merc.png new file mode 100644 index 00000000..8202789e Binary files /dev/null and b/docs/source/usage/operations/projections/images/merc.png differ diff --git a/docs/source/usage/operations/projections/images/mil_os.png b/docs/source/usage/operations/projections/images/mil_os.png new file mode 100644 index 00000000..3316d317 Binary files /dev/null and b/docs/source/usage/operations/projections/images/mil_os.png differ diff --git a/docs/source/usage/operations/projections/images/mill.png b/docs/source/usage/operations/projections/images/mill.png new file mode 100644 index 00000000..f62e517c Binary files /dev/null and b/docs/source/usage/operations/projections/images/mill.png differ diff --git a/docs/source/usage/operations/projections/images/misrsom.png b/docs/source/usage/operations/projections/images/misrsom.png new file mode 100644 index 00000000..493baff3 Binary files /dev/null and b/docs/source/usage/operations/projections/images/misrsom.png differ diff --git a/docs/source/usage/operations/projections/images/moll.png b/docs/source/usage/operations/projections/images/moll.png new file mode 100644 index 00000000..5d599579 Binary files /dev/null and b/docs/source/usage/operations/projections/images/moll.png differ diff --git a/docs/source/usage/operations/projections/images/murd1.png b/docs/source/usage/operations/projections/images/murd1.png new file mode 100644 index 00000000..34d628c5 Binary files /dev/null and b/docs/source/usage/operations/projections/images/murd1.png differ diff --git a/docs/source/usage/operations/projections/images/murd2.png b/docs/source/usage/operations/projections/images/murd2.png new file mode 100644 index 00000000..b3fdabdd Binary files /dev/null and b/docs/source/usage/operations/projections/images/murd2.png differ diff --git a/docs/source/usage/operations/projections/images/murd3.png b/docs/source/usage/operations/projections/images/murd3.png new file mode 100644 index 00000000..354b009c Binary files /dev/null and b/docs/source/usage/operations/projections/images/murd3.png differ diff --git a/docs/source/usage/operations/projections/images/natearth.png b/docs/source/usage/operations/projections/images/natearth.png new file mode 100644 index 00000000..0e182a0b Binary files /dev/null and b/docs/source/usage/operations/projections/images/natearth.png differ diff --git a/docs/source/usage/operations/projections/images/natearth2.png b/docs/source/usage/operations/projections/images/natearth2.png new file mode 100644 index 00000000..3757646c Binary files /dev/null and b/docs/source/usage/operations/projections/images/natearth2.png differ diff --git a/docs/source/usage/operations/projections/images/nell.png b/docs/source/usage/operations/projections/images/nell.png new file mode 100644 index 00000000..c0dbdcac Binary files /dev/null and b/docs/source/usage/operations/projections/images/nell.png differ diff --git a/docs/source/usage/operations/projections/images/nell_h.png b/docs/source/usage/operations/projections/images/nell_h.png new file mode 100644 index 00000000..a5a27076 Binary files /dev/null and b/docs/source/usage/operations/projections/images/nell_h.png differ diff --git a/docs/source/usage/operations/projections/images/nicol.png b/docs/source/usage/operations/projections/images/nicol.png new file mode 100644 index 00000000..711db115 Binary files /dev/null and b/docs/source/usage/operations/projections/images/nicol.png differ diff --git a/docs/source/usage/operations/projections/images/nsper.png b/docs/source/usage/operations/projections/images/nsper.png new file mode 100644 index 00000000..06f210a1 Binary files /dev/null and b/docs/source/usage/operations/projections/images/nsper.png differ diff --git a/docs/source/usage/operations/projections/images/nzmg.png b/docs/source/usage/operations/projections/images/nzmg.png new file mode 100644 index 00000000..3625f331 Binary files /dev/null and b/docs/source/usage/operations/projections/images/nzmg.png differ diff --git a/docs/source/usage/operations/projections/images/ob_tran.png b/docs/source/usage/operations/projections/images/ob_tran.png new file mode 100644 index 00000000..9b1e0d44 Binary files /dev/null and b/docs/source/usage/operations/projections/images/ob_tran.png differ diff --git a/docs/source/usage/operations/projections/images/ocea.png b/docs/source/usage/operations/projections/images/ocea.png new file mode 100644 index 00000000..41a5a813 Binary files /dev/null and b/docs/source/usage/operations/projections/images/ocea.png differ diff --git a/docs/source/usage/operations/projections/images/oea.png b/docs/source/usage/operations/projections/images/oea.png new file mode 100644 index 00000000..601ead55 Binary files /dev/null and b/docs/source/usage/operations/projections/images/oea.png differ diff --git a/docs/source/usage/operations/projections/images/omerc.png b/docs/source/usage/operations/projections/images/omerc.png new file mode 100644 index 00000000..50a3d2b7 Binary files /dev/null and b/docs/source/usage/operations/projections/images/omerc.png differ diff --git a/docs/source/usage/operations/projections/images/ortel.png b/docs/source/usage/operations/projections/images/ortel.png new file mode 100644 index 00000000..c6a5bf4f Binary files /dev/null and b/docs/source/usage/operations/projections/images/ortel.png differ diff --git a/docs/source/usage/operations/projections/images/ortho.png b/docs/source/usage/operations/projections/images/ortho.png new file mode 100644 index 00000000..e8b0b9b2 Binary files /dev/null and b/docs/source/usage/operations/projections/images/ortho.png differ diff --git a/docs/source/usage/operations/projections/images/patterson.png b/docs/source/usage/operations/projections/images/patterson.png new file mode 100644 index 00000000..f8014249 Binary files /dev/null and b/docs/source/usage/operations/projections/images/patterson.png differ diff --git a/docs/source/usage/operations/projections/images/pconic.png b/docs/source/usage/operations/projections/images/pconic.png new file mode 100644 index 00000000..7d7f9f92 Binary files /dev/null and b/docs/source/usage/operations/projections/images/pconic.png differ diff --git a/docs/source/usage/operations/projections/images/poly.png b/docs/source/usage/operations/projections/images/poly.png new file mode 100644 index 00000000..ccf25529 Binary files /dev/null and b/docs/source/usage/operations/projections/images/poly.png differ diff --git a/docs/source/usage/operations/projections/images/putp1.png b/docs/source/usage/operations/projections/images/putp1.png new file mode 100644 index 00000000..c81f574c Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp1.png differ diff --git a/docs/source/usage/operations/projections/images/putp2.png b/docs/source/usage/operations/projections/images/putp2.png new file mode 100644 index 00000000..377a027c Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp2.png differ diff --git a/docs/source/usage/operations/projections/images/putp3.png b/docs/source/usage/operations/projections/images/putp3.png new file mode 100644 index 00000000..08692ca1 Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp3.png differ diff --git a/docs/source/usage/operations/projections/images/putp3p.png b/docs/source/usage/operations/projections/images/putp3p.png new file mode 100644 index 00000000..9e42319c Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp3p.png differ diff --git a/docs/source/usage/operations/projections/images/putp4p.png b/docs/source/usage/operations/projections/images/putp4p.png new file mode 100644 index 00000000..43cb10c6 Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp4p.png differ diff --git a/docs/source/usage/operations/projections/images/putp5.png b/docs/source/usage/operations/projections/images/putp5.png new file mode 100644 index 00000000..4e45de6d Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp5.png differ diff --git a/docs/source/usage/operations/projections/images/putp5p.png b/docs/source/usage/operations/projections/images/putp5p.png new file mode 100644 index 00000000..76dcb767 Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp5p.png differ diff --git a/docs/source/usage/operations/projections/images/putp6.png b/docs/source/usage/operations/projections/images/putp6.png new file mode 100644 index 00000000..c73585ee Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp6.png differ diff --git a/docs/source/usage/operations/projections/images/putp6p.png b/docs/source/usage/operations/projections/images/putp6p.png new file mode 100644 index 00000000..d64c2c20 Binary files /dev/null and b/docs/source/usage/operations/projections/images/putp6p.png differ diff --git a/docs/source/usage/operations/projections/images/qsc.png b/docs/source/usage/operations/projections/images/qsc.png new file mode 100644 index 00000000..5824cf64 Binary files /dev/null and b/docs/source/usage/operations/projections/images/qsc.png differ diff --git a/docs/source/usage/operations/projections/images/qua_aut.png b/docs/source/usage/operations/projections/images/qua_aut.png new file mode 100644 index 00000000..6bc2d811 Binary files /dev/null and b/docs/source/usage/operations/projections/images/qua_aut.png differ diff --git a/docs/source/usage/operations/projections/images/rhealpix.png b/docs/source/usage/operations/projections/images/rhealpix.png new file mode 100644 index 00000000..dc1c344a Binary files /dev/null and b/docs/source/usage/operations/projections/images/rhealpix.png differ diff --git a/docs/source/usage/operations/projections/images/robin.png b/docs/source/usage/operations/projections/images/robin.png new file mode 100644 index 00000000..42a49da2 Binary files /dev/null and b/docs/source/usage/operations/projections/images/robin.png differ diff --git a/docs/source/usage/operations/projections/images/rouss.png b/docs/source/usage/operations/projections/images/rouss.png new file mode 100644 index 00000000..2eca0fed Binary files /dev/null and b/docs/source/usage/operations/projections/images/rouss.png differ diff --git a/docs/source/usage/operations/projections/images/rpoly.png b/docs/source/usage/operations/projections/images/rpoly.png new file mode 100644 index 00000000..343127c1 Binary files /dev/null and b/docs/source/usage/operations/projections/images/rpoly.png differ diff --git a/docs/source/usage/operations/projections/images/sinu.png b/docs/source/usage/operations/projections/images/sinu.png new file mode 100644 index 00000000..9bef143a Binary files /dev/null and b/docs/source/usage/operations/projections/images/sinu.png differ diff --git a/docs/source/usage/operations/projections/images/somerc.png b/docs/source/usage/operations/projections/images/somerc.png new file mode 100644 index 00000000..1248e6ea Binary files /dev/null and b/docs/source/usage/operations/projections/images/somerc.png differ diff --git a/docs/source/usage/operations/projections/images/stere.png b/docs/source/usage/operations/projections/images/stere.png new file mode 100644 index 00000000..840050f0 Binary files /dev/null and b/docs/source/usage/operations/projections/images/stere.png differ diff --git a/docs/source/usage/operations/projections/images/sterea.png b/docs/source/usage/operations/projections/images/sterea.png new file mode 100644 index 00000000..d2aad552 Binary files /dev/null and b/docs/source/usage/operations/projections/images/sterea.png differ diff --git a/docs/source/usage/operations/projections/images/tcc.png b/docs/source/usage/operations/projections/images/tcc.png new file mode 100644 index 00000000..f968f62d Binary files /dev/null and b/docs/source/usage/operations/projections/images/tcc.png differ diff --git a/docs/source/usage/operations/projections/images/tcea.png b/docs/source/usage/operations/projections/images/tcea.png new file mode 100644 index 00000000..44212bd8 Binary files /dev/null and b/docs/source/usage/operations/projections/images/tcea.png differ diff --git a/docs/source/usage/operations/projections/images/tissot.png b/docs/source/usage/operations/projections/images/tissot.png new file mode 100644 index 00000000..2f785477 Binary files /dev/null and b/docs/source/usage/operations/projections/images/tissot.png differ diff --git a/docs/source/usage/operations/projections/images/tmerc.png b/docs/source/usage/operations/projections/images/tmerc.png new file mode 100644 index 00000000..b206c502 Binary files /dev/null and b/docs/source/usage/operations/projections/images/tmerc.png differ diff --git a/docs/source/usage/operations/projections/images/tpeqd.png b/docs/source/usage/operations/projections/images/tpeqd.png new file mode 100644 index 00000000..50291b68 Binary files /dev/null and b/docs/source/usage/operations/projections/images/tpeqd.png differ diff --git a/docs/source/usage/operations/projections/images/tpers.png b/docs/source/usage/operations/projections/images/tpers.png new file mode 100644 index 00000000..480f6dce Binary files /dev/null and b/docs/source/usage/operations/projections/images/tpers.png differ diff --git a/docs/source/usage/operations/projections/images/ups.png b/docs/source/usage/operations/projections/images/ups.png new file mode 100644 index 00000000..354b64ac Binary files /dev/null and b/docs/source/usage/operations/projections/images/ups.png differ diff --git a/docs/source/usage/operations/projections/images/urm5.png b/docs/source/usage/operations/projections/images/urm5.png new file mode 100644 index 00000000..088671c9 Binary files /dev/null and b/docs/source/usage/operations/projections/images/urm5.png differ diff --git a/docs/source/usage/operations/projections/images/urmfps.png b/docs/source/usage/operations/projections/images/urmfps.png new file mode 100644 index 00000000..86432790 Binary files /dev/null and b/docs/source/usage/operations/projections/images/urmfps.png differ diff --git a/docs/source/usage/operations/projections/images/utm.png b/docs/source/usage/operations/projections/images/utm.png new file mode 100644 index 00000000..3dcd5ee0 Binary files /dev/null and b/docs/source/usage/operations/projections/images/utm.png differ diff --git a/docs/source/usage/operations/projections/images/vandg.png b/docs/source/usage/operations/projections/images/vandg.png new file mode 100644 index 00000000..46fe2346 Binary files /dev/null and b/docs/source/usage/operations/projections/images/vandg.png differ diff --git a/docs/source/usage/operations/projections/images/vandg2.png b/docs/source/usage/operations/projections/images/vandg2.png new file mode 100644 index 00000000..597b5ae1 Binary files /dev/null and b/docs/source/usage/operations/projections/images/vandg2.png differ diff --git a/docs/source/usage/operations/projections/images/vandg3.png b/docs/source/usage/operations/projections/images/vandg3.png new file mode 100644 index 00000000..36d1ad04 Binary files /dev/null and b/docs/source/usage/operations/projections/images/vandg3.png differ diff --git a/docs/source/usage/operations/projections/images/vandg4.png b/docs/source/usage/operations/projections/images/vandg4.png new file mode 100644 index 00000000..163c1558 Binary files /dev/null and b/docs/source/usage/operations/projections/images/vandg4.png differ diff --git a/docs/source/usage/operations/projections/images/vitk1.png b/docs/source/usage/operations/projections/images/vitk1.png new file mode 100644 index 00000000..31034b3a Binary files /dev/null and b/docs/source/usage/operations/projections/images/vitk1.png differ diff --git a/docs/source/usage/operations/projections/images/wag1.png b/docs/source/usage/operations/projections/images/wag1.png new file mode 100644 index 00000000..a2bc8adc Binary files /dev/null and b/docs/source/usage/operations/projections/images/wag1.png differ diff --git a/docs/source/usage/operations/projections/images/wag2.png b/docs/source/usage/operations/projections/images/wag2.png new file mode 100644 index 00000000..b4abb48c Binary files /dev/null and b/docs/source/usage/operations/projections/images/wag2.png differ diff --git a/docs/source/usage/operations/projections/images/wag3.png b/docs/source/usage/operations/projections/images/wag3.png new file mode 100644 index 00000000..a2053815 Binary files /dev/null and b/docs/source/usage/operations/projections/images/wag3.png differ diff --git a/docs/source/usage/operations/projections/images/wag4.png b/docs/source/usage/operations/projections/images/wag4.png new file mode 100644 index 00000000..7d1c50b3 Binary files /dev/null and b/docs/source/usage/operations/projections/images/wag4.png differ diff --git a/docs/source/usage/operations/projections/images/wag5.png b/docs/source/usage/operations/projections/images/wag5.png new file mode 100644 index 00000000..487f6022 Binary files /dev/null and b/docs/source/usage/operations/projections/images/wag5.png differ diff --git a/docs/source/usage/operations/projections/images/wag6.png b/docs/source/usage/operations/projections/images/wag6.png new file mode 100644 index 00000000..dd49e8d0 Binary files /dev/null and b/docs/source/usage/operations/projections/images/wag6.png differ diff --git a/docs/source/usage/operations/projections/images/wag7.png b/docs/source/usage/operations/projections/images/wag7.png new file mode 100644 index 00000000..b9682755 Binary files /dev/null and b/docs/source/usage/operations/projections/images/wag7.png differ diff --git a/docs/source/usage/operations/projections/images/weren.png b/docs/source/usage/operations/projections/images/weren.png new file mode 100644 index 00000000..7deb132f Binary files /dev/null and b/docs/source/usage/operations/projections/images/weren.png differ diff --git a/docs/source/usage/operations/projections/images/wink1.png b/docs/source/usage/operations/projections/images/wink1.png new file mode 100644 index 00000000..6cbf48ae Binary files /dev/null and b/docs/source/usage/operations/projections/images/wink1.png differ diff --git a/docs/source/usage/operations/projections/images/wink2.png b/docs/source/usage/operations/projections/images/wink2.png new file mode 100644 index 00000000..21a23634 Binary files /dev/null and b/docs/source/usage/operations/projections/images/wink2.png differ diff --git a/docs/source/usage/operations/projections/images/wintri.png b/docs/source/usage/operations/projections/images/wintri.png new file mode 100644 index 00000000..54a0a85a Binary files /dev/null and b/docs/source/usage/operations/projections/images/wintri.png differ diff --git a/docs/source/usage/operations/projections/imw_p.rst b/docs/source/usage/operations/projections/imw_p.rst new file mode 100644 index 00000000..1fd3ded0 --- /dev/null +++ b/docs/source/usage/operations/projections/imw_p.rst @@ -0,0 +1,10 @@ +.. _imw_p: + +******************************************************************************** +International Map of the World Polyconic +******************************************************************************** + +.. image:: ./images/imw_p.png + :scale: 50% + :alt: International Map of the World Polyconic + diff --git a/docs/source/usage/operations/projections/index.rst b/docs/source/usage/operations/projections/index.rst new file mode 100644 index 00000000..ae8ef1ee --- /dev/null +++ b/docs/source/usage/operations/projections/index.rst @@ -0,0 +1,142 @@ +.. _projections: + +================================================================================ +Projections +================================================================================ + +.. toctree:: + :maxdepth: 1 + + aeqd + airy + aitoff + alsk + apian + august + bacon + bipc + boggs + bonne + calcofi + cass + cc + cea + chamb + collg + crast + denoy + eck1 + eck2 + eck3 + eck4 + eck5 + eck6 + eqc + eqdc + euler + etmerc + fahey + fouc + fouc_s + gall + geos + gins8 + gn_sinu + gnom + goode + gs48 + gs50 + hammer + hatano + healpix + rhealpix + igh + imw_p + isea + kav5 + kav7 + krovak + labrd + laea + lagrng + larr + lask + lonlat + latlon + lcc + lcca + leac + lee_os + loxim + lsat + mbt_s + mbt_fps + mbtfpp + mbtfpq + mbtfps + merc + mil_os + mill + moll + murd1 + murd2 + murd3 + natearth + nell + nell_h + nicol + nsper + nzmg + ob_tran + ocea + oea + omerc + ortel + ortho + pconic + poly + putp1 + putp2 + putp3 + putp3p + putp4p + putp5 + putp5p + putp6 + putp6p + qua_aut + qsc + robin + rouss + rpoly + sinu + somerc + stere + sterea + gstmerc + tcc + tcea + tissot + tmerc + tpeqd + tpers + ups + urm5 + urmfps + utm + vandg + vandg2 + vandg3 + vandg4 + vitk1 + wag1 + wag2 + wag3 + wag4 + wag5 + wag6 + wag7 + weren + wink1 + wink2 + wintri diff --git a/docs/source/usage/operations/projections/isea.rst b/docs/source/usage/operations/projections/isea.rst new file mode 100644 index 00000000..1b6457af --- /dev/null +++ b/docs/source/usage/operations/projections/isea.rst @@ -0,0 +1,10 @@ +.. _isea: + +******************************************************************************** +Icosahedral Snyder Equal Area +******************************************************************************** + +.. image:: ./images/isea.png + :scale: 50% + :alt: Icosahedral Snyder Equal Area + diff --git a/docs/source/usage/operations/projections/kav5.rst b/docs/source/usage/operations/projections/kav5.rst new file mode 100644 index 00000000..2ec5d1c1 --- /dev/null +++ b/docs/source/usage/operations/projections/kav5.rst @@ -0,0 +1,10 @@ +.. _kav5: + +******************************************************************************** +Kavraisky V +******************************************************************************** + +.. image:: ./images/kav5.png + :scale: 50% + :alt: Kavraisky V + diff --git a/docs/source/usage/operations/projections/kav7.rst b/docs/source/usage/operations/projections/kav7.rst new file mode 100644 index 00000000..8371e6ea --- /dev/null +++ b/docs/source/usage/operations/projections/kav7.rst @@ -0,0 +1,10 @@ +.. _kav7: + +******************************************************************************** +Kavraisky VII +******************************************************************************** + +.. image:: ./images/kav7.png + :scale: 50% + :alt: Kavraisky VII + diff --git a/docs/source/usage/operations/projections/krovak.rst b/docs/source/usage/operations/projections/krovak.rst new file mode 100644 index 00000000..6c774825 --- /dev/null +++ b/docs/source/usage/operations/projections/krovak.rst @@ -0,0 +1,10 @@ +.. _krovak: + +******************************************************************************** +Krovak +******************************************************************************** + +.. image:: ./images/krovak.png + :scale: 50% + :alt: Krovak + diff --git a/docs/source/usage/operations/projections/labrd.rst b/docs/source/usage/operations/projections/labrd.rst new file mode 100644 index 00000000..5be58db5 --- /dev/null +++ b/docs/source/usage/operations/projections/labrd.rst @@ -0,0 +1,10 @@ +.. _labrd: + +******************************************************************************** +Laborde +******************************************************************************** + +.. image:: ./images/labrd.png + :scale: 50% + :alt: Laborde + diff --git a/docs/source/usage/operations/projections/laea.rst b/docs/source/usage/operations/projections/laea.rst new file mode 100644 index 00000000..2377f294 --- /dev/null +++ b/docs/source/usage/operations/projections/laea.rst @@ -0,0 +1,10 @@ +.. _laea: + +******************************************************************************** +Lambert Azimuthal Equal Area +******************************************************************************** + +.. image:: ./images/laea.png + :scale: 50% + :alt: Lambert Azimuthal Equal Area + diff --git a/docs/source/usage/operations/projections/lagrng.rst b/docs/source/usage/operations/projections/lagrng.rst new file mode 100644 index 00000000..de9e5640 --- /dev/null +++ b/docs/source/usage/operations/projections/lagrng.rst @@ -0,0 +1,10 @@ +.. _lagrng: + +******************************************************************************** +Lagrange +******************************************************************************** + +.. image:: ./images/lagrng.png + :scale: 50% + :alt: Lagrange + diff --git a/docs/source/usage/operations/projections/larr.rst b/docs/source/usage/operations/projections/larr.rst new file mode 100644 index 00000000..9529f83f --- /dev/null +++ b/docs/source/usage/operations/projections/larr.rst @@ -0,0 +1,10 @@ +.. _larr: + +******************************************************************************** +Larrivee +******************************************************************************** + +.. image:: ./images/larr.png + :scale: 50% + :alt: Larrivee + diff --git a/docs/source/usage/operations/projections/lask.rst b/docs/source/usage/operations/projections/lask.rst new file mode 100644 index 00000000..d34dc8a0 --- /dev/null +++ b/docs/source/usage/operations/projections/lask.rst @@ -0,0 +1,10 @@ +.. _lask: + +******************************************************************************** +Laskowski +******************************************************************************** + +.. image:: ./images/lask.png + :scale: 50% + :alt: Laskowski + diff --git a/docs/source/usage/operations/projections/latlon.rst b/docs/source/usage/operations/projections/latlon.rst new file mode 100644 index 00000000..6712fa7b --- /dev/null +++ b/docs/source/usage/operations/projections/latlon.rst @@ -0,0 +1,6 @@ +.. _latlon: + +******************************************************************************** +Lat/long (Geodetic alias) +******************************************************************************** + diff --git a/docs/source/usage/operations/projections/lcc.rst b/docs/source/usage/operations/projections/lcc.rst new file mode 100644 index 00000000..a3075e76 --- /dev/null +++ b/docs/source/usage/operations/projections/lcc.rst @@ -0,0 +1,10 @@ +.. _lcc: + +******************************************************************************** +Lambert Conformal Conic +******************************************************************************** + +.. image:: ./images/lcc.png + :scale: 50% + :alt: Lambert Conformal Conic + diff --git a/docs/source/usage/operations/projections/lcca.rst b/docs/source/usage/operations/projections/lcca.rst new file mode 100644 index 00000000..ca87e67e --- /dev/null +++ b/docs/source/usage/operations/projections/lcca.rst @@ -0,0 +1,10 @@ +.. _lcca: + +******************************************************************************** +Lambert Conformal Conic Alternative +******************************************************************************** + +.. image:: ./images/lcca.png + :scale: 50% + :alt: Lambert Conformal Conic Alternative + diff --git a/docs/source/usage/operations/projections/leac.rst b/docs/source/usage/operations/projections/leac.rst new file mode 100644 index 00000000..2957798e --- /dev/null +++ b/docs/source/usage/operations/projections/leac.rst @@ -0,0 +1,10 @@ +.. _leac: + +******************************************************************************** +Lambert Equal Area Conic +******************************************************************************** + +.. image:: ./images/leac.png + :scale: 50% + :alt: Lambert Equal Area Conic + diff --git a/docs/source/usage/operations/projections/lee_os.rst b/docs/source/usage/operations/projections/lee_os.rst new file mode 100644 index 00000000..711dc754 --- /dev/null +++ b/docs/source/usage/operations/projections/lee_os.rst @@ -0,0 +1,10 @@ +.. _lee_os: + +******************************************************************************** +Lee Oblated Stereographic +******************************************************************************** + +.. image:: ./images/lee_os.png + :scale: 50% + :alt: Lee Oblated Stereographic + diff --git a/docs/source/usage/operations/projections/lonlat.rst b/docs/source/usage/operations/projections/lonlat.rst new file mode 100644 index 00000000..589cc813 --- /dev/null +++ b/docs/source/usage/operations/projections/lonlat.rst @@ -0,0 +1,6 @@ +.. _lonlat: + +******************************************************************************** +Lat/long (Geodetic) +******************************************************************************** + diff --git a/docs/source/usage/operations/projections/loxim.rst b/docs/source/usage/operations/projections/loxim.rst new file mode 100644 index 00000000..e50ba472 --- /dev/null +++ b/docs/source/usage/operations/projections/loxim.rst @@ -0,0 +1,10 @@ +.. _loxim: + +******************************************************************************** +Loximuthal +******************************************************************************** + +.. image:: ./images/loxim.png + :scale: 50% + :alt: Loximuthal + diff --git a/docs/source/usage/operations/projections/lsat.rst b/docs/source/usage/operations/projections/lsat.rst new file mode 100644 index 00000000..fb64bdb2 --- /dev/null +++ b/docs/source/usage/operations/projections/lsat.rst @@ -0,0 +1,10 @@ +.. _lsat: + +******************************************************************************** +Space oblique for LANDSAT +******************************************************************************** + +.. image:: ./images/lsat.png + :scale: 50% + :alt: Space oblique for LANDSAT + diff --git a/docs/source/usage/operations/projections/mbt_fps.rst b/docs/source/usage/operations/projections/mbt_fps.rst new file mode 100644 index 00000000..55ebcf6c --- /dev/null +++ b/docs/source/usage/operations/projections/mbt_fps.rst @@ -0,0 +1,10 @@ +.. _mbt_fps: + +******************************************************************************** +McBryde-Thomas Flat-Pole Sine (No. 2) +******************************************************************************** + +.. image:: ./images/mbt_fps.png + :scale: 50% + :alt: McBryde-Thomas Flat-Pole Sine (No. 2) + diff --git a/docs/source/usage/operations/projections/mbt_s.rst b/docs/source/usage/operations/projections/mbt_s.rst new file mode 100644 index 00000000..9a355ec8 --- /dev/null +++ b/docs/source/usage/operations/projections/mbt_s.rst @@ -0,0 +1,10 @@ +.. _mbt_s: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sine (No. 1) +******************************************************************************** + +.. image:: ./images/mbt_s.png + :scale: 50% + :alt: McBryde-Thomas Flat-Polar Sine (No. 1) + diff --git a/docs/source/usage/operations/projections/mbtfpp.rst b/docs/source/usage/operations/projections/mbtfpp.rst new file mode 100644 index 00000000..9be309d9 --- /dev/null +++ b/docs/source/usage/operations/projections/mbtfpp.rst @@ -0,0 +1,10 @@ +.. _mbtfpp: + +******************************************************************************** +McBride-Thomas Flat-Polar Parabolic +******************************************************************************** + +.. image:: ./images/mbtfpp.png + :scale: 50% + :alt: McBride-Thomas Flat-Polar Parabolic + diff --git a/docs/source/usage/operations/projections/mbtfpq.rst b/docs/source/usage/operations/projections/mbtfpq.rst new file mode 100644 index 00000000..295e814d --- /dev/null +++ b/docs/source/usage/operations/projections/mbtfpq.rst @@ -0,0 +1,10 @@ +.. _mbtfpq: + +******************************************************************************** +McBryde-Thomas Flat-Polar Quartic +******************************************************************************** + +.. image:: ./images/mbtfpq.png + :scale: 50% + :alt: McBryde-Thomas Flat-Polar Quartic + diff --git a/docs/source/usage/operations/projections/mbtfps.rst b/docs/source/usage/operations/projections/mbtfps.rst new file mode 100644 index 00000000..b9365361 --- /dev/null +++ b/docs/source/usage/operations/projections/mbtfps.rst @@ -0,0 +1,10 @@ +.. _mbtfps: + +******************************************************************************** +McBryde-Thomas Flat-Polar Sinusoidal +******************************************************************************** + +.. image:: ./images/mbtfps.png + :scale: 50% + :alt: McBryde-Thomas Flat-Polar Sinusoidal + diff --git a/docs/source/usage/operations/projections/merc.rst b/docs/source/usage/operations/projections/merc.rst new file mode 100644 index 00000000..64ba98a4 --- /dev/null +++ b/docs/source/usage/operations/projections/merc.rst @@ -0,0 +1,140 @@ +.. _merc: + +******************************************************************************** +Mercator +******************************************************************************** + +The Mercator projection is a cylindrical map projection that origins from the 15th +century. It is widely recognized as the first regularly used map projection. +The projection is conformal which makes it suitable for navigational purposes. + + ++---------------------+----------------------------------------------------------+ +| **Classification** | Conformal cylindrical | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_ts` | Latitude of true scale. Defaults to 0.0 | ++---------------------+----------------------------------------------------------+ +| `+k_0` | Scaling factor. Defaults to 1.0 | ++---------------------+----------------------------------------------------------+ + + + +.. image:: ./images/merc.png + :scale: 50% + :alt: Mercator + + +Usage +######## + +Applications should be limited to equatorial regions, but is frequently +used for navigational charts with latitude of true scale (``+lat_ts``) specified within +or near chart's boundaries. +Often inappropriately used for world maps since the regions near the poles +cannot be shown [Evenden1995]_. + + +Example using latitude of true scale:: + + $ echo 56.35 12.32 | proj +proj=merc +lat_ts=56.5 + 3470306.37 759599.90 + +Example using scaling factor:: + + echo 56.35 12.32 | proj +proj=merc +k_0=2 + 12545706.61 2746073.80 + + +Note that ``+lat_ts`` and ``+k_0`` are mutually excusive. +If used together, ``+lat_ts`` takes precedence over ``+k_0``. + +Mathematical definition +####################### + +The formulas describing the Mercator projection are all taken from G. Evenden's libproj manuals [Evenden2005]_. + +Spherical form +************** +For the spherical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = \cos \phi_{ts} + +Forward projection +================== + +.. math:: + + x = k_0 \lambda + +.. math:: + + y = k_0 \ln \left[ \tan \left(\frac{\pi}{4} + \frac{\phi}{2} \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0} + +.. math:: + + \phi = \frac{\pi}{2} - 2 \arctan \left[ e^{-y/k_0} \right] + + +Elliptical form +*************** + +For the elliptical form of the projection we introduce the scaling factor: + +.. math:: + + k_0 = m\left( \phi_ts \right) + +where :math:`m\left(\phi\right)` is the parallel radius at latitude :math:`\phi`. + +We also use the Isometric Latitude kernel function :math:`t()`. + +.. note:: + m() and t() should be described properly on a separate page about the theory of projections on the ellipsoid. + +Forward projection +================== +.. math:: + + x = k_0 \lambda + +.. math:: + + y = k_0 \ln t \left( \phi \right) + + +Inverse projection +================== + +.. math:: + + \lambda = \frac{x}{k_0} + +.. math:: + + \phi = t^{-1}\left[ e^{ -y/k_0 } \right] + +Further reading +############### + +#. `Wikipedia `_ +#. `Wolfram Mathworld `_ + + diff --git a/docs/source/usage/operations/projections/mil_os.rst b/docs/source/usage/operations/projections/mil_os.rst new file mode 100644 index 00000000..5547e43c --- /dev/null +++ b/docs/source/usage/operations/projections/mil_os.rst @@ -0,0 +1,10 @@ +.. _mil_os: + +******************************************************************************** +Miller Oblated Stereographic +******************************************************************************** + +.. image:: ./images/mil_os.png + :scale: 50% + :alt: Miller Oblated Stereographic + diff --git a/docs/source/usage/operations/projections/mill.rst b/docs/source/usage/operations/projections/mill.rst new file mode 100644 index 00000000..eb9c2092 --- /dev/null +++ b/docs/source/usage/operations/projections/mill.rst @@ -0,0 +1,72 @@ +.. _mill: + +******************************************************************************** +Miller Cylindrical +******************************************************************************** + +The Miller cylindrical projection is a modified Mercator projection, proposed by Osborn Maitland Miller in 1942. +The latitude is scaled by a factor of :math:`\frac{4}{5}`, projected according to Mercator, and then the result is multiplied by :math:`\frac{5}{4}` to retain scale along the equator. + ++---------------------+--------------------------------------------------------------------------------+ +| **Classification** | Neither conformal nor equal area cylindrical | ++---------------------+--------------------------------------------------------------------------------+ +| **Available forms** | Forward and inverse spherical | ++---------------------+--------------------------------------------------------------------------------+ +| **Defined area** | Global, but best used near the equator | ++---------------------+--------------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+--------------------------------------------------------------------------------+ +| **Options** | ++---------------------+--------------------------------------------------------------------------------+ +| `+lat_0` | Latitude of origin (Default to 0) | ++---------------------+--------------------------------------------------------------------------------+ + +.. image:: ./images/mill.png + :scale: 50% + :alt: Miller Cylindrical + +Usage +######## + +The Miller Cylindrical projection is used for world maps and in several atlases, +including the National Atlas of the United States (USGS, 1970, p. 330-331) [Snyder1987]_. + +Example using Central meridian 90°W:: + + $ echo -100 35 | proj +proj=mill +lon_0=90w + -1113194.91 4061217.24 + +Mathematical definition +####################### + +The formulas describing the Miller projection are all taken from Snyder's manuals [Snyder1987]_. + + +Forward projection +================== + +.. math:: + + x = \lambda + +.. math:: + + y = 1.25 * \ln \left[ \tan \left(\frac{\pi}{4} + 0.4 * \phi \right) \right] + + +Inverse projection +================== + +.. math:: + + \lambda = x + +.. math:: + + \phi = 2.5 * ( \arctan \left[ e^{0.8 * y} \right] - \frac{\pi}{4} ) + +Further reading +############### + +#. `Wikipedia `_ + diff --git a/docs/source/usage/operations/projections/moll.rst b/docs/source/usage/operations/projections/moll.rst new file mode 100644 index 00000000..1bd3d005 --- /dev/null +++ b/docs/source/usage/operations/projections/moll.rst @@ -0,0 +1,10 @@ +.. _moll: + +******************************************************************************** +Mollweide +******************************************************************************** + +.. image:: ./images/moll.png + :scale: 50% + :alt: Mollweide + diff --git a/docs/source/usage/operations/projections/murd1.rst b/docs/source/usage/operations/projections/murd1.rst new file mode 100644 index 00000000..71cbf155 --- /dev/null +++ b/docs/source/usage/operations/projections/murd1.rst @@ -0,0 +1,10 @@ +.. _murd1: + +******************************************************************************** +Murdoch I +******************************************************************************** + +.. image:: ./images/murd1.png + :scale: 50% + :alt: Murdoch I + diff --git a/docs/source/usage/operations/projections/murd2.rst b/docs/source/usage/operations/projections/murd2.rst new file mode 100644 index 00000000..b55cde35 --- /dev/null +++ b/docs/source/usage/operations/projections/murd2.rst @@ -0,0 +1,10 @@ +.. _murd2: + +******************************************************************************** +Murdoch II +******************************************************************************** + +.. image:: ./images/murd2.png + :scale: 50% + :alt: Murdoch II + diff --git a/docs/source/usage/operations/projections/murd3.rst b/docs/source/usage/operations/projections/murd3.rst new file mode 100644 index 00000000..70cc9276 --- /dev/null +++ b/docs/source/usage/operations/projections/murd3.rst @@ -0,0 +1,10 @@ +.. _murd3: + +******************************************************************************** +Murdoch III +******************************************************************************** + +.. image:: ./images/murd3.png + :scale: 50% + :alt: Murdoch III + diff --git a/docs/source/usage/operations/projections/natearth.rst b/docs/source/usage/operations/projections/natearth.rst new file mode 100644 index 00000000..57dd96db --- /dev/null +++ b/docs/source/usage/operations/projections/natearth.rst @@ -0,0 +1,47 @@ +.. _natearth: + +******************************************************************************** +Natural Earth +******************************************************************************** ++---------------------+--------------------------------------------------------+ +| **Classification** | Pseudo cylindrical | ++---------------------+--------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+--------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+--------------------------------------------------------+ +| **Implemented by** | Bernhard Jenny | ++---------------------+--------------------------------------------------------+ +| **Options** | ++---------------------+--------------------------------------------------------+ +| `No special options for this projection` | ++---------------------+--------------------------------------------------------+ + +.. image:: ./images/natearth.png + :scale: 50% + :alt: Natural Earth + + +The Natural Earth projection is intended for making world maps. A distinguishing trait +is its slightly rounded corners fashioned to emulate the spherical shape of Earth. +The meridians (except for the central meridian) bend acutely inward as they approach +the pole lines, giving the projection a hint of three-dimensionality. This bending +also suggests that the meridians converge at the poles instead of truncating at the +top and bottom edges. The distortion characteristics of the Natural Earth projection +compare favorably to other world map projections. + + +Usage +############################################################################### + +The Natural Earth projection has no special options so usage is simple. Here is +an example of an inverse projection on a sphere with a radius of 7500 m:: + + $ echo 3500 -8000 | proj -I +proj=natearth +a=7500 + 37d54'6.091"E 61d23'4.582"S + + +Further reading +################################################################################ + +#. `Wikipedia `_ diff --git a/docs/source/usage/operations/projections/nell.rst b/docs/source/usage/operations/projections/nell.rst new file mode 100644 index 00000000..c6a3771c --- /dev/null +++ b/docs/source/usage/operations/projections/nell.rst @@ -0,0 +1,10 @@ +.. _nell: + +******************************************************************************** +Nell +******************************************************************************** + +.. image:: ./images/nell.png + :scale: 50% + :alt: Nell + diff --git a/docs/source/usage/operations/projections/nell_h.rst b/docs/source/usage/operations/projections/nell_h.rst new file mode 100644 index 00000000..6a3b26ba --- /dev/null +++ b/docs/source/usage/operations/projections/nell_h.rst @@ -0,0 +1,10 @@ +.. _nell_h: + +******************************************************************************** +Nell-Hammer +******************************************************************************** + +.. image:: ./images/nell_h.png + :scale: 50% + :alt: Nell-Hammer + diff --git a/docs/source/usage/operations/projections/nicol.rst b/docs/source/usage/operations/projections/nicol.rst new file mode 100644 index 00000000..995cedb5 --- /dev/null +++ b/docs/source/usage/operations/projections/nicol.rst @@ -0,0 +1,10 @@ +.. _nicol: + +******************************************************************************** +Nicolosi Globular +******************************************************************************** + +.. image:: ./images/nicol.png + :scale: 50% + :alt: Nicolosi Globular + diff --git a/docs/source/usage/operations/projections/nsper.rst b/docs/source/usage/operations/projections/nsper.rst new file mode 100644 index 00000000..4a8651fc --- /dev/null +++ b/docs/source/usage/operations/projections/nsper.rst @@ -0,0 +1,10 @@ +.. _nsper: + +******************************************************************************** +Near-sided perspective +******************************************************************************** + +.. image:: ./images/nsper.png + :scale: 50% + :alt: Near-sided perspective + diff --git a/docs/source/usage/operations/projections/nzmg.rst b/docs/source/usage/operations/projections/nzmg.rst new file mode 100644 index 00000000..926655d8 --- /dev/null +++ b/docs/source/usage/operations/projections/nzmg.rst @@ -0,0 +1,10 @@ +.. _nzmg: + +******************************************************************************** +New Zealand Map Grid +******************************************************************************** + +.. image:: ./images/nzmg.png + :scale: 50% + :alt: New Zealand Map Grid + diff --git a/docs/source/usage/operations/projections/ob_tran.rst b/docs/source/usage/operations/projections/ob_tran.rst new file mode 100644 index 00000000..3c996336 --- /dev/null +++ b/docs/source/usage/operations/projections/ob_tran.rst @@ -0,0 +1,10 @@ +.. _ob_tran: + +******************************************************************************** +General Oblique Transformation +******************************************************************************** + +.. image:: ./images/ob_tran.png + :scale: 50% + :alt: General Oblique Transformation + diff --git a/docs/source/usage/operations/projections/ocea.rst b/docs/source/usage/operations/projections/ocea.rst new file mode 100644 index 00000000..40005d9e --- /dev/null +++ b/docs/source/usage/operations/projections/ocea.rst @@ -0,0 +1,10 @@ +.. _ocea: + +******************************************************************************** +Oblique Cylindrical Equal Area +******************************************************************************** + +.. image:: ./images/ocea.png + :scale: 50% + :alt: Oblique Cylindrical Equal Area + diff --git a/docs/source/usage/operations/projections/oea.rst b/docs/source/usage/operations/projections/oea.rst new file mode 100644 index 00000000..379dc157 --- /dev/null +++ b/docs/source/usage/operations/projections/oea.rst @@ -0,0 +1,10 @@ +.. _oea: + +******************************************************************************** +Oblated Equal Area +******************************************************************************** + +.. image:: ./images/oea.png + :scale: 50% + :alt: Oblated Equal Area + diff --git a/docs/source/usage/operations/projections/omerc.rst b/docs/source/usage/operations/projections/omerc.rst new file mode 100644 index 00000000..114b9fa3 --- /dev/null +++ b/docs/source/usage/operations/projections/omerc.rst @@ -0,0 +1,10 @@ +.. _omerc: + +******************************************************************************** +Oblique Mercator +******************************************************************************** + +.. image:: ./images/omerc.png + :scale: 50% + :alt: Oblique Mercator + diff --git a/docs/source/usage/operations/projections/ortel.rst b/docs/source/usage/operations/projections/ortel.rst new file mode 100644 index 00000000..03f132ef --- /dev/null +++ b/docs/source/usage/operations/projections/ortel.rst @@ -0,0 +1,10 @@ +.. _ortel: + +******************************************************************************** +Ortelius Oval +******************************************************************************** + +.. image:: ./images/ortel.png + :scale: 50% + :alt: Ortelius Oval + diff --git a/docs/source/usage/operations/projections/ortho.rst b/docs/source/usage/operations/projections/ortho.rst new file mode 100644 index 00000000..131dbfc7 --- /dev/null +++ b/docs/source/usage/operations/projections/ortho.rst @@ -0,0 +1,10 @@ +.. _ortho: + +******************************************************************************** +Orthographic +******************************************************************************** + +.. image:: ./images/ortho.png + :scale: 50% + :alt: Orthographic + diff --git a/docs/source/usage/operations/projections/pconic.rst b/docs/source/usage/operations/projections/pconic.rst new file mode 100644 index 00000000..6bc0018e --- /dev/null +++ b/docs/source/usage/operations/projections/pconic.rst @@ -0,0 +1,10 @@ +.. _pconic: + +******************************************************************************** +Perspective Conic +******************************************************************************** + +.. image:: ./images/pconic.png + :scale: 50% + :alt: Perspective Conic + diff --git a/docs/source/usage/operations/projections/poly.rst b/docs/source/usage/operations/projections/poly.rst new file mode 100644 index 00000000..e252feb5 --- /dev/null +++ b/docs/source/usage/operations/projections/poly.rst @@ -0,0 +1,10 @@ +.. _poly: + +******************************************************************************** +Polyconic (American) +******************************************************************************** + +.. image:: ./images/poly.png + :scale: 50% + :alt: Polyconic (American) + diff --git a/docs/source/usage/operations/projections/putp1.rst b/docs/source/usage/operations/projections/putp1.rst new file mode 100644 index 00000000..68971a46 --- /dev/null +++ b/docs/source/usage/operations/projections/putp1.rst @@ -0,0 +1,10 @@ +.. _putp1: + +******************************************************************************** +Putnins P1 +******************************************************************************** + +.. image:: ./images/putp1.png + :scale: 50% + :alt: Putnins P1 + diff --git a/docs/source/usage/operations/projections/putp2.rst b/docs/source/usage/operations/projections/putp2.rst new file mode 100644 index 00000000..01ea8073 --- /dev/null +++ b/docs/source/usage/operations/projections/putp2.rst @@ -0,0 +1,10 @@ +.. _putp2: + +******************************************************************************** +Putnins P2 +******************************************************************************** + +.. image:: ./images/putp2.png + :scale: 50% + :alt: Putnins P2 + diff --git a/docs/source/usage/operations/projections/putp3.rst b/docs/source/usage/operations/projections/putp3.rst new file mode 100644 index 00000000..3aa6b9e6 --- /dev/null +++ b/docs/source/usage/operations/projections/putp3.rst @@ -0,0 +1,10 @@ +.. _putp3: + +******************************************************************************** +Putnins P3 +******************************************************************************** + +.. image:: ./images/putp3.png + :scale: 50% + :alt: Putnins P3 + diff --git a/docs/source/usage/operations/projections/putp3p.rst b/docs/source/usage/operations/projections/putp3p.rst new file mode 100644 index 00000000..5b87512e --- /dev/null +++ b/docs/source/usage/operations/projections/putp3p.rst @@ -0,0 +1,10 @@ +.. _putp3p: + +******************************************************************************** +Putnins P3' +******************************************************************************** + +.. image:: ./images/putp3p.png + :scale: 50% + :alt: Putnins P3' + diff --git a/docs/source/usage/operations/projections/putp4p.rst b/docs/source/usage/operations/projections/putp4p.rst new file mode 100644 index 00000000..b211ad9b --- /dev/null +++ b/docs/source/usage/operations/projections/putp4p.rst @@ -0,0 +1,10 @@ +.. _putp4p: + +******************************************************************************** +Putnins P4' +******************************************************************************** + +.. image:: ./images/putp4p.png + :scale: 50% + :alt: Putnins P4' + diff --git a/docs/source/usage/operations/projections/putp5.rst b/docs/source/usage/operations/projections/putp5.rst new file mode 100644 index 00000000..5b60a961 --- /dev/null +++ b/docs/source/usage/operations/projections/putp5.rst @@ -0,0 +1,10 @@ +.. _putp5: + +******************************************************************************** +Putnins P5 +******************************************************************************** + +.. image:: ./images/putp5.png + :scale: 50% + :alt: Putnins P5 + diff --git a/docs/source/usage/operations/projections/putp5p.rst b/docs/source/usage/operations/projections/putp5p.rst new file mode 100644 index 00000000..f586b889 --- /dev/null +++ b/docs/source/usage/operations/projections/putp5p.rst @@ -0,0 +1,10 @@ +.. _putp5p: + +******************************************************************************** +Putnins P5' +******************************************************************************** + +.. image:: ./images/putp5p.png + :scale: 50% + :alt: Putnins P5' + diff --git a/docs/source/usage/operations/projections/putp6.rst b/docs/source/usage/operations/projections/putp6.rst new file mode 100644 index 00000000..94683ace --- /dev/null +++ b/docs/source/usage/operations/projections/putp6.rst @@ -0,0 +1,10 @@ +.. _putp6: + +******************************************************************************** +Putnins P6 +******************************************************************************** + +.. image:: ./images/putp6.png + :scale: 50% + :alt: Putnins P6 + diff --git a/docs/source/usage/operations/projections/putp6p.rst b/docs/source/usage/operations/projections/putp6p.rst new file mode 100644 index 00000000..8c3add71 --- /dev/null +++ b/docs/source/usage/operations/projections/putp6p.rst @@ -0,0 +1,10 @@ +.. _putp6p: + +******************************************************************************** +Putnins P6' +******************************************************************************** + +.. image:: ./images/putp6p.png + :scale: 50% + :alt: Putnins P6' + diff --git a/docs/source/usage/operations/projections/qsc.rst b/docs/source/usage/operations/projections/qsc.rst new file mode 100644 index 00000000..e3af2cee --- /dev/null +++ b/docs/source/usage/operations/projections/qsc.rst @@ -0,0 +1,158 @@ +.. _qsc: + +******************************************************************************** +Quadrilateralized Spherical Cube +******************************************************************************** + ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Martin Lambers | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+lat_0` | Latitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ +| `+lon_0` | Longitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ + +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 + :scale: 50% + :align: center + :alt: Quadrilateralized Spherical Cube + +For this purpose, other alternatives can be used, notably :ref:`gnom` or +:ref:`healpix`. However, QSC projection has the following favorable properties: + +It is an equal-area projection, and at the same time introduces only limited angular +distortions. It treats all cube sides equally, i.e. it does not use different +projections for polar areas and equatorial areas. These properties make QSC +projection a good choice for planetary-scale terrain rendering. Map data can be +organized in quadtree structures for each cube side. See [LambersKolb2012]_ for an example. + +The QSC projection was introduced by [ONeilLaubscher1976]_, +building on previous work by [ChanONeil1975]_. For clarity: The +earlier QSC variant described in [ChanONeil1975]_ became known as the COBE QSC since it +was used by the NASA Cosmic Background Explorer (COBE) project; it is an approximately +equal-area projection and is not the same as the QSC projection. + +See also [CalabrettaGreisen2002]_ Sec. 5.6.2 and 5.6.3 for a description of both and +some analysis. + +In this implementation, the QSC projection projects onto one side of a circumscribed +cube. The cube side is selected by choosing one of the following six projection centers: + ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=0`` | front cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=90`` | right cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=180`` | back cube side | ++-------------------------+--------------------+ +| ``+lat_0=0 +lon_0=-90`` | left cube side | ++-------------------------+--------------------+ +| ``+lat_0=90`` | top cube side | ++-------------------------+--------------------+ +| ``+lat_0=-90`` | bottom cube side | ++-------------------------+--------------------+ + +Furthermore, this implementation allows the projection to be applied to ellipsoids. +A preceding shift to a sphere is performed automatically; see [LambersKolb2012]_ for details. + + +Usage +############################################################################### + +The following example uses QSC projection via GDAL to create the six cube side +maps from a world map for the WGS84 ellipsoid:: + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff frontside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=90" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff rightside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=180" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff backside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=-90" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff leftside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=90 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff topside.tiff + + gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=-90 +lon_0=0" \ + -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137 \ + worldmap.tiff bottomside.tiff + + +Explanation: + +* QSC projection is selected with ``+wktext +proj=qsc``. +* The WGS84 ellipsoid is specified with ``+ellps=WGS84``. +* The cube side is selected with ``+lat_0=... +lon_0=...``. +* The ``-wo`` options are necessary for GDAL to avoid holes in the output maps. +* The ``-te`` option limits the extends of the output map to the major axis diameter + (from -radius to +radius in both x and y direction). These are the dimensions of one side + of the circumscribing cube. + + +The resulting images can be laid out in a grid like below. + + +.. |topside| image:: ../../../../images/qsc_topside.jpg + :scale: 50% + :align: middle + :alt: Top side + +.. |leftside| image:: ../../../../images/qsc_leftside.jpg + :scale: 50% + :align: middle + :alt: Left side + +.. |frontside| image:: ../../../../images/qsc_frontside.jpg + :scale: 50% + :align: middle + :alt: Front side + +.. |rightside| image:: ../../../../images/qsc_rightside.jpg + :scale: 50% + :align: middle + :alt: Right side + +.. |backside| image:: ../../../../images/qsc_backside.jpg + :scale: 50% + :align: middle + :alt: Back side + +.. |bottomside| image:: ../../../../images/qsc_bottomside.jpg + :scale: 50% + :align: middle + :alt: Bottom side + + ++------------+--------------+-------------+------------+ +| | |topside| | | | ++------------+--------------+-------------+------------+ +| |leftside| | |frontside| | |rightside| | |backside| | ++------------+--------------+-------------+------------+ +| | |bottomside| | | | ++------------+--------------+-------------+------------+ + +Further reading +################################################################################ + +#. `Wikipedia `_ +#. `NASA `_ diff --git a/docs/source/usage/operations/projections/qua_aut.rst b/docs/source/usage/operations/projections/qua_aut.rst new file mode 100644 index 00000000..d3a0aece --- /dev/null +++ b/docs/source/usage/operations/projections/qua_aut.rst @@ -0,0 +1,10 @@ +.. _qua_aut: + +******************************************************************************** +Quartic Authalic +******************************************************************************** + +.. image:: ./images/qua_aut.png + :scale: 50% + :alt: Quartic Authalic + diff --git a/docs/source/usage/operations/projections/rhealpix.rst b/docs/source/usage/operations/projections/rhealpix.rst new file mode 100644 index 00000000..5808cfaa --- /dev/null +++ b/docs/source/usage/operations/projections/rhealpix.rst @@ -0,0 +1,51 @@ +.. _rhealpix: + +******************************************************************************** +rHEALPix +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Mixed | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical and elliptical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Alex Raichev and Michael Speth | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+north_square` | Position of the north polar square. | +| | Valid inputs are 0--3. Defaults to 0. | ++---------------------+----------------------------------------------------------+ +| `+south_square` | Position of the south polar square. | +| | Valid inputs are 0--3. Defaults to 0. | ++---------------------+----------------------------------------------------------+ + +.. image:: ../../../../images/rhealpix.png + :scale: 75% + :alt: rHEALPix + +rHEALPix is a projection based on the HEALPix projection. The implementation of +rHEALPix uses the HEALPix projection. The rHEALPix combines the peaks of the +HEALPix into a square. The square's position can be translated and rotated across +the x-axis which is a noval approach for the rHEALPix projection. The initial +intention of using rHEALPix in the Spatial Computation Engine Science Collaboration +Environment (SCENZGrid). + +Usage +############################################################################### + +To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following +command:: + + proj +proj=rhealpix -f '%.2f' +ellps=WGS84 +south_square=0 +north_square=2 -E << EOF + > 55 12 + > EOF + 55 12 6115727.86 1553840.13 + + +Further reading +################################################################################ + +#. `NASA `_ +#. `Wikipedia `_ diff --git a/docs/source/usage/operations/projections/robin.rst b/docs/source/usage/operations/projections/robin.rst new file mode 100644 index 00000000..3e58be46 --- /dev/null +++ b/docs/source/usage/operations/projections/robin.rst @@ -0,0 +1,10 @@ +.. _robin: + +******************************************************************************** +Robinson +******************************************************************************** + +.. image:: ./images/robin.png + :scale: 50% + :alt: Robinson + diff --git a/docs/source/usage/operations/projections/rouss.rst b/docs/source/usage/operations/projections/rouss.rst new file mode 100644 index 00000000..e27fb1cf --- /dev/null +++ b/docs/source/usage/operations/projections/rouss.rst @@ -0,0 +1,10 @@ +.. _rouss: + +******************************************************************************** +Roussilhe Stereographic +******************************************************************************** + +.. image:: ./images/rouss.png + :scale: 50% + :alt: Roussilhe Stereographic + diff --git a/docs/source/usage/operations/projections/rpoly.rst b/docs/source/usage/operations/projections/rpoly.rst new file mode 100644 index 00000000..80e0d640 --- /dev/null +++ b/docs/source/usage/operations/projections/rpoly.rst @@ -0,0 +1,10 @@ +.. _rpoly: + +******************************************************************************** +Rectangular Polyconic +******************************************************************************** + +.. image:: ./images/rpoly.png + :scale: 50% + :alt: Rectangular Polyconic + diff --git a/docs/source/usage/operations/projections/sinu.rst b/docs/source/usage/operations/projections/sinu.rst new file mode 100644 index 00000000..a7ebd232 --- /dev/null +++ b/docs/source/usage/operations/projections/sinu.rst @@ -0,0 +1,24 @@ +.. _sinu: + +******************************************************************************** +Sinusoidal (Sanson-Flamsteed) +******************************************************************************** + +.. image:: ./images/sinu.png + :scale: 50% + :alt: Sinusoidal (Sanson-Flamsteed) + +MacBryde and Thomas developed generalized formulas for sever of the +pseudocylindricals with sinusoidal meridians: + +.. math:: + + x = C\lambda(m+cos\theta) / ( m + 1) + +.. math:: + y = C\theta + +.. math:: + + C = \sqrt { (m + 1 ) / n } + diff --git a/docs/source/usage/operations/projections/somerc.rst b/docs/source/usage/operations/projections/somerc.rst new file mode 100644 index 00000000..c572622b --- /dev/null +++ b/docs/source/usage/operations/projections/somerc.rst @@ -0,0 +1,10 @@ +.. _somerc: + +******************************************************************************** +Swiss. Obl. Mercator +******************************************************************************** + +.. image:: ./images/somerc.png + :scale: 50% + :alt: Swiss. Obl. Mercator + diff --git a/docs/source/usage/operations/projections/stere.rst b/docs/source/usage/operations/projections/stere.rst new file mode 100644 index 00000000..d4958ec9 --- /dev/null +++ b/docs/source/usage/operations/projections/stere.rst @@ -0,0 +1,10 @@ +.. _stere: + +******************************************************************************** +Stereographic +******************************************************************************** + +.. image:: ./images/stere.png + :scale: 50% + :alt: Stereographic + diff --git a/docs/source/usage/operations/projections/sterea.rst b/docs/source/usage/operations/projections/sterea.rst new file mode 100644 index 00000000..4f2f8727 --- /dev/null +++ b/docs/source/usage/operations/projections/sterea.rst @@ -0,0 +1,10 @@ +.. _sterea: + +******************************************************************************** +Oblique Stereographic Alternative +******************************************************************************** + +.. image:: ./images/sterea.png + :scale: 50% + :alt: Oblique Stereographic Alternative + diff --git a/docs/source/usage/operations/projections/tcc.rst b/docs/source/usage/operations/projections/tcc.rst new file mode 100644 index 00000000..586dd3b8 --- /dev/null +++ b/docs/source/usage/operations/projections/tcc.rst @@ -0,0 +1,10 @@ +.. _tcc: + +******************************************************************************** +Transverse Central Cylindrical +******************************************************************************** + +.. image:: ./images/tcc.png + :scale: 50% + :alt: Transverse Central Cylindrical + diff --git a/docs/source/usage/operations/projections/tcea.rst b/docs/source/usage/operations/projections/tcea.rst new file mode 100644 index 00000000..cf5549a3 --- /dev/null +++ b/docs/source/usage/operations/projections/tcea.rst @@ -0,0 +1,10 @@ +.. _tcea: + +******************************************************************************** +Transverse Cylindrical Equal Area +******************************************************************************** + +.. image:: ./images/tcea.png + :scale: 50% + :alt: Transverse Cylindrical Equal Area + diff --git a/docs/source/usage/operations/projections/tissot.rst b/docs/source/usage/operations/projections/tissot.rst new file mode 100644 index 00000000..7ec1a741 --- /dev/null +++ b/docs/source/usage/operations/projections/tissot.rst @@ -0,0 +1,10 @@ +.. _tissot: + +******************************************************************************** +Tissot +******************************************************************************** + +.. image:: ./images/tissot.png + :scale: 50% + :alt: Tissot + diff --git a/docs/source/usage/operations/projections/tmerc.rst b/docs/source/usage/operations/projections/tmerc.rst new file mode 100644 index 00000000..03aa2830 --- /dev/null +++ b/docs/source/usage/operations/projections/tmerc.rst @@ -0,0 +1,197 @@ +.. _tmerc: + +******************************************************************************** +Transverse Mercator +******************************************************************************** + +The transverse Mercator projection in its various forms is the most widely used projected coordinate system for world topographical and offshore mapping. + ++---------------------+--------------------------------------------------------------------------------+ +| **Classification** | Transverse and oblique cylindrical | ++---------------------+--------------------------------------------------------------------------------+ +| **Available forms** | Forward and inverse, Spherical and Elliptical | ++---------------------+--------------------------------------------------------------------------------+ +| **Defined area** | Global, but reasonably accurate only within 15 degrees of the central meridian | ++---------------------+--------------------------------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+--------------------------------------------------------------------------------+ +| **Options** | ++---------------------+--------------------------------------------------------------------------------+ +| `+lat_0` | Latitude of origin (Default to 0) | ++---------------------+--------------------------------------------------------------------------------+ +| `+k0` | Scale factor at natural origin (Default to 1) | ++---------------------+--------------------------------------------------------------------------------+ + + +.. image:: ./images/tmerc.png + :scale: 50% + :alt: Transverse Mercator + +Usage +##### + + +Prior to the development of the Universal Transverse Mercator coordinate system, several European nations demonstrated the utility of grid-based conformal maps by mapping their territory during the interwar period. +Calculating the distance between two points on these maps could be performed more easily in the field (using the Pythagorean theorem) than was possible using the trigonometric formulas required under the graticule-based system of latitude and longitude. +In the post-war years, these concepts were extended into the Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) coordinate system, which is a global (or universal) system of grid-based maps. + +The following table gives special cases of the Transverse Mercator projection. + ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ +| Projection Name | Areas | Central meridian | Zone width | Scale Factor | ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ +| Transverse Mercator | World wide | Various | less than 6° | Various | ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ +| Transverse Mercator south oriented | Southern Africa | 2° intervals E of 11°E | 2° | 1.000 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ +| UTM North hemisphere | World wide equator to 84°N | 6° intervals E & W of 3° E & W | Always 6° | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ +| UTM South hemisphere | World wide north of 80°S to equator | 6° intervals E & W of 3° E & W | Always 6° | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ +| Gauss-Kruger | Former USSR, Yugoslavia, Germany, S. America, China | Various, according to area | Usually less than 6°, often less than 4° | 1.0000 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ +| Gauss Boaga | Italy | Various, according to area | 6° | 0.9996 | ++-------------------------------------+-----------------------------------------------------+--------------------------------+------------------------------------------+--------------+ + + + +Example using Gauss-Kruger on Germany area (aka EPSG:31467) :: + + $ echo 9 51 | proj +proj=tmerc +lat_0=0 +lon_0=9 +k=1 +x_0=3500000 +y_0=0 +ellps=bessel +datum=potsdam +units=m +no_defs + 3500000.00 5651505.56 + +Example using Gauss Boaga on Italy area (EPSG:3004) :: + + $ echo 15 42 | proj +proj=tmerc +lat_0=0 +lon_0=15 +k=0.9996 +x_0=2520000 +y_0=0 +ellps=intl +units=m +no_defs + 2520000.00 4649858.60 + +Mathematical definition +####################### + +The formulas describing the Transverse Mercator are all taken from Evenden's [Evenden2005]_. + +:math:`\phi_0` is the latitude of origin that match the center of the map. It can be set with ``+lat_0``. + +:math:`k_0` is the scale factor at the natural origin (on the central meridian). It can be set with ``+k_0``. + +:math:`M(\phi)` is the meridianal distance. + +Spherical form +************** + +Forward projection +================== + +.. math:: + + B = \cos \phi \sin \lambda + +.. math:: + + x = \frac{k_0}{2} \ln(\frac{1+B}{1-B}) + +.. math:: + + y = k_0 ( \arctan(\frac{\tan(\phi)}{\cos \lambda}) - \phi_0) + + +Inverse projection +================== + +.. math:: + + D = \frac{y}{k_0} + \phi_0 + +.. math:: + + x' = \frac{x}{k_0} + +.. math:: + + \phi = \arcsin(\frac{\sin D}{\cosh x'}) + +.. math:: + + \lambda = \arctan(\frac{\sinh x'}{\cos D}) + + +Elliptical form +*************** + +Forward projection +================== + +.. math:: + + N = \frac{k_0}{(1 - e^2 \sin^2\phi)^{1/2}} + +.. math:: + + R = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi)^{3/2}} + +.. math:: + + t = \tan(\phi) + +.. math:: + + \eta = \frac{e^2}{1-e^2}cos^2\phi + +.. math:: + + x &= k_0 \lambda \cos \phi \\ + &+ \frac{k_0 \lambda^3 \cos^3\phi}{3!}(1-t^2+\eta^2) \\ + &+ \frac{k_0 \lambda^5 \cos^5\phi}{5!}(5-18t^2+t^4+14\eta^2-58t^2\eta^2) \\ + &+\frac{k_0 \lambda^7 \cos^7\phi}{7!}(61-479t^2+179t^4-t^6) + +.. math:: + + y &= M(\phi) \\ + &+ \frac{k_0 \lambda^2 \sin(\phi) \cos \phi}{2!} \\ + &+ \frac{k_0 \lambda^4 \sin(\phi) \cos^3\phi}{4!}(5-t^2+9\eta^2+4\eta^4) \\ + &+ \frac{k_0 \lambda^6 \sin(\phi) \cos^5\phi}{6!}(61-58t^2+t^4+270\eta^2-330t^2\eta^2) \\ + &+ \frac{k_0 \lambda^8 \sin(\phi) \cos^7\phi}{8!}(1385-3111t^2+543t^4-t^6) + +Inverse projection +================== + +.. math:: + + \phi_1 = M^-1(y) + +.. math:: + + N_1 = \frac{k_0}{1 - e^2 \sin^2\phi_1)^{1/2}} + +.. math:: + + R_1 = \frac{k_0(1-e^2)}{(1-e^2 \sin^2\phi_1)^{3/2}} + +.. math:: + + t_1 = \tan(\phi_1) + +.. math:: + + \eta_1 = \frac{e^2}{1-e^2}cos^2\phi_1 + +.. math:: + + \phi &= \phi_1 \\ + &- \frac{t_1 x^2}{2! R_1 N_1} \\ + &+ \frac{t_1 x^4}{4! R_1 N_1^3}(5+3t_1^2+\eta_1^2-4\eta_1^4-9\eta_1^2t_1^2) \\ + &- \frac{t_1 x^6}{6! R_1 N_1^5}(61+90t_1^2+46\eta_1^2+45t_1^4-252t_1^2\eta_1^2) \\ + &+ \frac{t_1 x^8}{8! R_1 N_1^7}(1385+3633t_1^2+4095t_1^4+1575t_1^6) + +.. math:: + + \lambda &= \frac{x}{\cos \phi N_1} \\ + &- \frac{x^3}{3! \cos \phi N_1^3}(1+2t_1^2+\eta_1^2) \\ + &+ \frac{x^5}{5! \cos \phi N_1^5}(5+6\eta_1^2+28t_1^2-3\eta_1^2+8t_1^2\eta_1^2) \\ + &- \frac{x^7}{7! \cos \phi N_1^7}(61+662t_1^2+1320t_1^4+720t_1^6) + +Further reading +############### + +#. `Wikipedia `_ +#. `EPSG, POSC literature pertaining to Coordinate Conversions and Transformations including Formulas `_ diff --git a/docs/source/usage/operations/projections/tpeqd.rst b/docs/source/usage/operations/projections/tpeqd.rst new file mode 100644 index 00000000..e6d7ef29 --- /dev/null +++ b/docs/source/usage/operations/projections/tpeqd.rst @@ -0,0 +1,10 @@ +.. _tpeqd: + +******************************************************************************** +Two Point Equidistant +******************************************************************************** + +.. image:: ./images/tpeqd.png + :scale: 50% + :alt: Two Point Equidistant + diff --git a/docs/source/usage/operations/projections/tpers.rst b/docs/source/usage/operations/projections/tpers.rst new file mode 100644 index 00000000..345a5faa --- /dev/null +++ b/docs/source/usage/operations/projections/tpers.rst @@ -0,0 +1,39 @@ +.. _tpers: + +******************************************************************************** +Tilted perspective +******************************************************************************** ++---------------------+----------------------------------------------------------+ +| **Classification** | Azimuthal | ++---------------------+----------------------------------------------------------+ +| **Available forms** | Forward and inverse, spherical projection | ++---------------------+----------------------------------------------------------+ +| **Defined area** | Global | ++---------------------+----------------------------------------------------------+ +| **Implemented by** | Gerald I. Evenden | ++---------------------+----------------------------------------------------------+ +| **Options** | ++---------------------+----------------------------------------------------------+ +| `+h` | Height (in meters) above the surface. Required. | ++---------------------+----------------------------------------------------------+ +| `+azi` | Bearing (in degrees) from due north. | ++---------------------+----------------------------------------------------------+ +| `+tilt` | Angle (in degrees) away from nadir. | ++---------------------+----------------------------------------------------------+ +| `+lat_0` | Latitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ +| `+lon_0` | Longitude (in degrees) of the view position. | ++---------------------+----------------------------------------------------------+ + + +.. image:: ./images/tpers.png + :scale: 50% + :alt: Tilted perspective + + +Tilted Perspective is similar to :ref:`nsper` (``nsper``) in that it simulates a +perspective view from a hight. Where ``nsper`` projects onto a plane tangent to +the surface, Tilted Perspective orients the plane towards the direction of the +view. Thus, extra parameters azi and tilt are required beyond `nsper``'s ``h``. +As with ``nsper``, ``lat_0`` & ``lon_0`` are also required +for satellite position. diff --git a/docs/source/usage/operations/projections/ups.rst b/docs/source/usage/operations/projections/ups.rst new file mode 100644 index 00000000..7a9ab50b --- /dev/null +++ b/docs/source/usage/operations/projections/ups.rst @@ -0,0 +1,10 @@ +.. _ups: + +******************************************************************************** +Universal Polar Stereographic +******************************************************************************** + +.. image:: ./images/ups.png + :scale: 50% + :alt: Universal Polar Stereographic + diff --git a/docs/source/usage/operations/projections/urm5.rst b/docs/source/usage/operations/projections/urm5.rst new file mode 100644 index 00000000..91d06308 --- /dev/null +++ b/docs/source/usage/operations/projections/urm5.rst @@ -0,0 +1,10 @@ +.. _urm5: + +******************************************************************************** +Urmaev V +******************************************************************************** + +.. image:: ./images/urm5.png + :scale: 50% + :alt: Urmaev V + diff --git a/docs/source/usage/operations/projections/urmfps.rst b/docs/source/usage/operations/projections/urmfps.rst new file mode 100644 index 00000000..515ced84 --- /dev/null +++ b/docs/source/usage/operations/projections/urmfps.rst @@ -0,0 +1,10 @@ +.. _urmfps: + +******************************************************************************** +Urmaev Flat-Polar Sinusoidal +******************************************************************************** + +.. image:: ./images/urmfps.png + :scale: 50% + :alt: Urmaev Flat-Polar Sinusoidal + diff --git a/docs/source/usage/operations/projections/utm.rst b/docs/source/usage/operations/projections/utm.rst new file mode 100644 index 00000000..7fb66cb8 --- /dev/null +++ b/docs/source/usage/operations/projections/utm.rst @@ -0,0 +1,10 @@ +.. _utm: + +******************************************************************************** +Universal Transverse Mercator (UTM) +******************************************************************************** + +.. image:: ./images/utm.png + :scale: 50% + :alt: Universal Transverse Mercator (UTM) + diff --git a/docs/source/usage/operations/projections/vandg.rst b/docs/source/usage/operations/projections/vandg.rst new file mode 100644 index 00000000..cdc772bb --- /dev/null +++ b/docs/source/usage/operations/projections/vandg.rst @@ -0,0 +1,10 @@ +.. _vandg: + +******************************************************************************** +van der Grinten (I) +******************************************************************************** + +.. image:: ./images/vandg.png + :scale: 50% + :alt: van der Grinten (I) + diff --git a/docs/source/usage/operations/projections/vandg2.rst b/docs/source/usage/operations/projections/vandg2.rst new file mode 100644 index 00000000..556929e2 --- /dev/null +++ b/docs/source/usage/operations/projections/vandg2.rst @@ -0,0 +1,10 @@ +.. _vandg2: + +******************************************************************************** +van der Grinten II +******************************************************************************** + +.. image:: ./images/vandg2.png + :scale: 50% + :alt: van der Grinten II + diff --git a/docs/source/usage/operations/projections/vandg3.rst b/docs/source/usage/operations/projections/vandg3.rst new file mode 100644 index 00000000..d767c4d5 --- /dev/null +++ b/docs/source/usage/operations/projections/vandg3.rst @@ -0,0 +1,10 @@ +.. _vandg3: + +******************************************************************************** +van der Grinten III +******************************************************************************** + +.. image:: ./images/vandg3.png + :scale: 50% + :alt: van der Grinten III + diff --git a/docs/source/usage/operations/projections/vandg4.rst b/docs/source/usage/operations/projections/vandg4.rst new file mode 100644 index 00000000..097ba1d8 --- /dev/null +++ b/docs/source/usage/operations/projections/vandg4.rst @@ -0,0 +1,10 @@ +.. _vandg4: + +******************************************************************************** +van der Grinten IV +******************************************************************************** + +.. image:: ./images/vandg4.png + :scale: 50% + :alt: van der Grinten IV + diff --git a/docs/source/usage/operations/projections/vitk1.rst b/docs/source/usage/operations/projections/vitk1.rst new file mode 100644 index 00000000..b9081547 --- /dev/null +++ b/docs/source/usage/operations/projections/vitk1.rst @@ -0,0 +1,10 @@ +.. _vitk1: + +******************************************************************************** +Vitkovsky I +******************************************************************************** + +.. image:: ./images/vitk1.png + :scale: 50% + :alt: Vitkovsky I + diff --git a/docs/source/usage/operations/projections/wag1.rst b/docs/source/usage/operations/projections/wag1.rst new file mode 100644 index 00000000..dd1ed39e --- /dev/null +++ b/docs/source/usage/operations/projections/wag1.rst @@ -0,0 +1,10 @@ +.. _wag1: + +******************************************************************************** +Wagner I (Kavraisky VI) +******************************************************************************** + +.. image:: ./images/wag1.png + :scale: 50% + :alt: Wagner I (Kavraisky VI) + diff --git a/docs/source/usage/operations/projections/wag2.rst b/docs/source/usage/operations/projections/wag2.rst new file mode 100644 index 00000000..9c7b0edc --- /dev/null +++ b/docs/source/usage/operations/projections/wag2.rst @@ -0,0 +1,18 @@ +.. _wag2: + +******************************************************************************** +Wagner II +******************************************************************************** + +.. image:: ./images/wag2.png + :scale: 50% + :alt: Wagner II + + +.. math:: + + x &= 0.92483 \lambda \cos \theta + + y &= 1.38725\theta + + \sin \theta &= 0.88022 \sin(0.8855\phi) diff --git a/docs/source/usage/operations/projections/wag3.rst b/docs/source/usage/operations/projections/wag3.rst new file mode 100644 index 00000000..fb70a0a6 --- /dev/null +++ b/docs/source/usage/operations/projections/wag3.rst @@ -0,0 +1,16 @@ +.. _wag3: + +******************************************************************************** +Wagner III +******************************************************************************** + +.. image:: ./images/wag3.png + :scale: 50% + :alt: Wagner III + + +.. math:: + + x &= [\cos\phi_{ts} / \cos ( 2\phi_{ts} / 3)] \lambda \cos (2\phi /3) + + y = \phi diff --git a/docs/source/usage/operations/projections/wag4.rst b/docs/source/usage/operations/projections/wag4.rst new file mode 100644 index 00000000..7b8dac96 --- /dev/null +++ b/docs/source/usage/operations/projections/wag4.rst @@ -0,0 +1,10 @@ +.. _wag4: + +******************************************************************************** +Wagner IV +******************************************************************************** + +.. image:: ./images/wag4.png + :scale: 50% + :alt: Wagner IV + diff --git a/docs/source/usage/operations/projections/wag5.rst b/docs/source/usage/operations/projections/wag5.rst new file mode 100644 index 00000000..f880290b --- /dev/null +++ b/docs/source/usage/operations/projections/wag5.rst @@ -0,0 +1,10 @@ +.. _wag5: + +******************************************************************************** +Wagner V +******************************************************************************** + +.. image:: ./images/wag5.png + :scale: 50% + :alt: Wagner V + diff --git a/docs/source/usage/operations/projections/wag6.rst b/docs/source/usage/operations/projections/wag6.rst new file mode 100644 index 00000000..f74749a5 --- /dev/null +++ b/docs/source/usage/operations/projections/wag6.rst @@ -0,0 +1,10 @@ +.. _wag6: + +******************************************************************************** +Wagner VI +******************************************************************************** + +.. image:: ./images/wag6.png + :scale: 50% + :alt: Wagner VI + diff --git a/docs/source/usage/operations/projections/wag7.rst b/docs/source/usage/operations/projections/wag7.rst new file mode 100644 index 00000000..be1401b8 --- /dev/null +++ b/docs/source/usage/operations/projections/wag7.rst @@ -0,0 +1,10 @@ +.. _wag7: + +******************************************************************************** +Wagner VII +******************************************************************************** + +.. image:: ./images/wag7.png + :scale: 50% + :alt: Wagner VII + diff --git a/docs/source/usage/operations/projections/weren.rst b/docs/source/usage/operations/projections/weren.rst new file mode 100644 index 00000000..de7c5abf --- /dev/null +++ b/docs/source/usage/operations/projections/weren.rst @@ -0,0 +1,10 @@ +.. _weren: + +******************************************************************************** +Werenskiold I +******************************************************************************** + +.. image:: ./images/weren.png + :scale: 50% + :alt: Werenskiold I + diff --git a/docs/source/usage/operations/projections/wink1.rst b/docs/source/usage/operations/projections/wink1.rst new file mode 100644 index 00000000..00346765 --- /dev/null +++ b/docs/source/usage/operations/projections/wink1.rst @@ -0,0 +1,10 @@ +.. _wink1: + +******************************************************************************** +Winkel I +******************************************************************************** + +.. image:: ./images/wink1.png + :scale: 50% + :alt: Winkel I + diff --git a/docs/source/usage/operations/projections/wink2.rst b/docs/source/usage/operations/projections/wink2.rst new file mode 100644 index 00000000..7e9b48a7 --- /dev/null +++ b/docs/source/usage/operations/projections/wink2.rst @@ -0,0 +1,10 @@ +.. _wink2: + +******************************************************************************** +Winkel II +******************************************************************************** + +.. image:: ./images/wink2.png + :scale: 50% + :alt: Winkel II + diff --git a/docs/source/usage/operations/projections/wintri.rst b/docs/source/usage/operations/projections/wintri.rst new file mode 100644 index 00000000..bfd5032f --- /dev/null +++ b/docs/source/usage/operations/projections/wintri.rst @@ -0,0 +1,10 @@ +.. _wintri: + +******************************************************************************** +Winkel Tripel +******************************************************************************** + +.. image:: ./images/wintri.png + :scale: 50% + :alt: Winkel Tripel + diff --git a/docs/source/usage/operations/transformations/cart.rst b/docs/source/usage/operations/transformations/cart.rst new file mode 100644 index 00000000..0c3c7c23 --- /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 00000000..46073b63 --- /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 00000000..78e46aa9 --- /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 00000000..8bf2a890 --- /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 00000000..3fa8f9a8 --- /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 00000000..458d0c15 --- /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 00000000..f48d40c8 --- /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. + -- cgit v1.2.3 From 1f546602f1da800199ad298968154f2c71de6daf Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 27 Sep 2017 22:06:29 +0200 Subject: add proj_errno_* functions to API reference --- docs/source/development/reference/functions.rst | 63 +++++++++++++++++++++++++ 1 file changed, 63 insertions(+) (limited to 'docs/source') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index fc546f33..3b6d4489 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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -- cgit v1.2.3 From c9376a4700ca71605c27fa84e0ad49d043846158 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 27 Sep 2017 23:13:16 +0200 Subject: 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 (limited to 'docs/source') diff --git a/docs/source/usage/environmentvars.rst b/docs/source/usage/environmentvars.rst new file mode 100644 index 00000000..38cb46de --- /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 5979426a..81ea4b6b 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 -- cgit v1.2.3 From f8d26297de7f6092e78bcd33876510c7082c3f35 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 9 Oct 2017 21:48:24 +0200 Subject: Add PJ_DIRECTION to API referece [skip ci] --- docs/source/development/reference/datatypes.rst | 29 +++++++++++++++++++++++++ docs/source/development/reference/functions.rst | 27 +++++++++++++---------- 2 files changed, 44 insertions(+), 12 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 991fcfc5..7e314dce 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 3b6d4489..daefce4b 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 \ -- cgit v1.2.3 From f73ec9d887d9cddf014d33a53bf6f87390004a63 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 9 Oct 2017 22:48:44 +0200 Subject: Add documentation for datatypes and functions related to internal lists in PROJ.4. [skip ci] --- docs/source/development/reference/datatypes.rst | 104 ++++++++++++++++++++++++ docs/source/development/reference/functions.rst | 43 ++++++++++ 2 files changed, 147 insertions(+) (limited to 'docs/source') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 7e314dce..85cedea6 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 daefce4b..10af19d4 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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -- cgit v1.2.3 From 0c83891614bc158c56f8132f09b0db95d5dd72f1 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 7 Nov 2017 16:43:01 +0100 Subject: Wrote docs for unitconvert operation [skip-ci] --- .../operations/transformations/unitconvert.rst | 105 +++++++++++++++++++++ 1 file changed, 105 insertions(+) (limited to 'docs/source') diff --git a/docs/source/usage/operations/transformations/unitconvert.rst b/docs/source/usage/operations/transformations/unitconvert.rst index 458d0c15..ad848207 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 | ++--------------+-----------------------------+ + -- cgit v1.2.3 From 91b641e627a028786e56276d18501dd518d6b112 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sat, 11 Nov 2017 19:08:45 +0100 Subject: add axisswap documentation --- .../usage/operations/transformations/axisswap.rst | 39 ++++++++++++++++++++++ .../usage/operations/transformations/index.rst | 1 + 2 files changed, 40 insertions(+) create mode 100644 docs/source/usage/operations/transformations/axisswap.rst (limited to 'docs/source') diff --git a/docs/source/usage/operations/transformations/axisswap.rst b/docs/source/usage/operations/transformations/axisswap.rst new file mode 100644 index 00000000..ddaad075 --- /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 8bf2a890..2966ed0d 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 -- cgit v1.2.3 From 1f096c9f9cf1ef4c152c53605bf6f6347209b4b5 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 15 Nov 2017 21:31:51 +0100 Subject: 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 (limited to 'docs/source') diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 9f5c8d89..318e3778 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 00000000..d9014a36 --- /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 | ++---------------------------------------+---------------------------------------+ -- cgit v1.2.3 From 082f5aed6ea6a746e73c17e39f8aabb85d840272 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 15 Nov 2017 21:52:25 +0100 Subject: 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(-) (limited to 'docs/source') diff --git a/docs/source/usage/projections.rst b/docs/source/usage/projections.rst index b0bcce61..8f0b3586 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 d162ace9..96bfbba1 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 e99763f1..9a202879 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. -- cgit v1.2.3 From 25b011042fdff451ca2826afe82251c06d883fb8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 16:33:42 +0100 Subject: Update API reference to reflect recent changes to the API --- docs/source/development/reference/datatypes.rst | 389 +++--------------------- docs/source/development/reference/functions.rst | 109 ++++--- 2 files changed, 104 insertions(+), 394 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 85cedea6..1253b1a2 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 10af19d4..ea128954 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 + -- cgit v1.2.3 From 83fa46d89a1998323c095abaa911b8455c7b62d6 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 20:37:10 +0100 Subject: Added info table to ccon doc page --- docs/source/usage/operations/projections/ccon.rst | 35 ++++++++++++++--------- 1 file changed, 22 insertions(+), 13 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/operations/projections/ccon.rst b/docs/source/usage/operations/projections/ccon.rst index 6197f061..8a858e38 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 - - - - - - -- cgit v1.2.3 From 410ad2d07515a734d04bf4c44c694fd5b548f1a2 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 22:31:55 +0100 Subject: Restructure coordinate operations docs --- .../usage/operations/conversions/axisswap.rst | 39 +++++++ docs/source/usage/operations/conversions/cart.rst | 24 +++++ docs/source/usage/operations/conversions/index.rst | 18 ++++ .../source/usage/operations/conversions/latlon.rst | 6 ++ .../source/usage/operations/conversions/lonlat.rst | 6 ++ .../usage/operations/conversions/unitconvert.rst | 112 +++++++++++++++++++++ docs/source/usage/operations/index.rst | 13 ++- docs/source/usage/operations/projections/index.rst | 7 +- .../source/usage/operations/projections/latlon.rst | 6 -- .../source/usage/operations/projections/lonlat.rst | 6 -- .../usage/operations/transformations/axisswap.rst | 39 ------- .../usage/operations/transformations/cart.rst | 24 ----- .../usage/operations/transformations/index.rst | 6 +- .../operations/transformations/unitconvert.rst | 112 --------------------- 14 files changed, 221 insertions(+), 197 deletions(-) create mode 100644 docs/source/usage/operations/conversions/axisswap.rst create mode 100644 docs/source/usage/operations/conversions/cart.rst create mode 100644 docs/source/usage/operations/conversions/index.rst create mode 100644 docs/source/usage/operations/conversions/latlon.rst create mode 100644 docs/source/usage/operations/conversions/lonlat.rst create mode 100644 docs/source/usage/operations/conversions/unitconvert.rst delete mode 100644 docs/source/usage/operations/projections/latlon.rst delete mode 100644 docs/source/usage/operations/projections/lonlat.rst delete mode 100644 docs/source/usage/operations/transformations/axisswap.rst delete mode 100644 docs/source/usage/operations/transformations/cart.rst delete mode 100644 docs/source/usage/operations/transformations/unitconvert.rst (limited to 'docs/source') diff --git a/docs/source/usage/operations/conversions/axisswap.rst b/docs/source/usage/operations/conversions/axisswap.rst new file mode 100644 index 00000000..ddaad075 --- /dev/null +++ b/docs/source/usage/operations/conversions/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/conversions/cart.rst b/docs/source/usage/operations/conversions/cart.rst new file mode 100644 index 00000000..0c3c7c23 --- /dev/null +++ b/docs/source/usage/operations/conversions/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/conversions/index.rst b/docs/source/usage/operations/conversions/index.rst new file mode 100644 index 00000000..54324ec4 --- /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/conversions/latlon.rst b/docs/source/usage/operations/conversions/latlon.rst new file mode 100644 index 00000000..6712fa7b --- /dev/null +++ b/docs/source/usage/operations/conversions/latlon.rst @@ -0,0 +1,6 @@ +.. _latlon: + +******************************************************************************** +Lat/long (Geodetic alias) +******************************************************************************** + diff --git a/docs/source/usage/operations/conversions/lonlat.rst b/docs/source/usage/operations/conversions/lonlat.rst new file mode 100644 index 00000000..589cc813 --- /dev/null +++ b/docs/source/usage/operations/conversions/lonlat.rst @@ -0,0 +1,6 @@ +.. _lonlat: + +******************************************************************************** +Lat/long (Geodetic) +******************************************************************************** + diff --git a/docs/source/usage/operations/conversions/unitconvert.rst b/docs/source/usage/operations/conversions/unitconvert.rst new file mode 100644 index 00000000..ad848207 --- /dev/null +++ b/docs/source/usage/operations/conversions/unitconvert.rst @@ -0,0 +1,112 @@ +.. _unitconvert: + +================================================================================ +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 | ++--------------+-----------------------------+ + diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst index 21200c93..baae0e0a 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 5ccf0045..f7eb0c67 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/projections/latlon.rst b/docs/source/usage/operations/projections/latlon.rst deleted file mode 100644 index 6712fa7b..00000000 --- a/docs/source/usage/operations/projections/latlon.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _latlon: - -******************************************************************************** -Lat/long (Geodetic alias) -******************************************************************************** - diff --git a/docs/source/usage/operations/projections/lonlat.rst b/docs/source/usage/operations/projections/lonlat.rst deleted file mode 100644 index 589cc813..00000000 --- a/docs/source/usage/operations/projections/lonlat.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _lonlat: - -******************************************************************************** -Lat/long (Geodetic) -******************************************************************************** - diff --git a/docs/source/usage/operations/transformations/axisswap.rst b/docs/source/usage/operations/transformations/axisswap.rst deleted file mode 100644 index ddaad075..00000000 --- a/docs/source/usage/operations/transformations/axisswap.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _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/cart.rst b/docs/source/usage/operations/transformations/cart.rst deleted file mode 100644 index 0c3c7c23..00000000 --- a/docs/source/usage/operations/transformations/cart.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _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/index.rst b/docs/source/usage/operations/transformations/index.rst index 2966ed0d..112d9220 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 diff --git a/docs/source/usage/operations/transformations/unitconvert.rst b/docs/source/usage/operations/transformations/unitconvert.rst deleted file mode 100644 index ad848207..00000000 --- a/docs/source/usage/operations/transformations/unitconvert.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _unitconvert: - -================================================================================ -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 | -+--------------+-----------------------------+ - -- cgit v1.2.3 From 28ead8822488f0cd382f8966a18000f17ef1e958 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 23:26:23 +0100 Subject: Added projections parameters to aeqd and airy doc pages --- docs/source/usage/operations/projections/aeqd.rst | 14 +++++++++++++- docs/source/usage/operations/projections/airy.rst | 18 +++++++++++++++++- 2 files changed, 30 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/operations/projections/aeqd.rst b/docs/source/usage/operations/projections/aeqd.rst index 949cd8a0..32165e49 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 307af3e3..d2730592 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 -- cgit v1.2.3 From 7b0e97df22d32608355d1f235ee22ffedcc9f06e Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 29 Nov 2017 21:58:15 +0100 Subject: Fill out Molodensky docs [skip ci] --- docs/source/references.rst | 2 + .../operations/transformations/molodensky.rst | 69 +++++++++++++++++++++- 2 files changed, 70 insertions(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/references.rst b/docs/source/references.rst index 7d1d2216..e2dece5c 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 3fa8f9a8..d4ff3e79 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 + -- cgit v1.2.3 From 597a208400377ca6285fbd204c44817e21f31907 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 29 Nov 2017 22:08:39 +0100 Subject: 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 (limited to 'docs/source') diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css new file mode 100644 index 00000000..63ee6cc7 --- /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 62316eef..12ee0a57 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -140,7 +140,13 @@ html_theme_options = {} # 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 -- cgit v1.2.3 From ee59e88d090a9a3b6ecd9651b4f439ab9b6651e4 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Dec 2017 13:41:46 +0100 Subject: Update config with version number and correct copyright dates [skip ci] --- docs/source/conf.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/source') diff --git a/docs/source/conf.py b/docs/source/conf.py index 12ee0a57..af9d24da 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 @@ master_doc = 'index' # 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 @@ author = u'Gerald Evenden, Frank Warmerdam, and others' # 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. -- cgit v1.2.3 From 053ffa05ca8cf36cd02830d746ebde5506efa475 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Dec 2017 14:03:27 +0100 Subject: Add input/output types to gridshift docs [skip ci] --- .../source/usage/operations/transformations/hgridshift.rst | 14 +++++++++----- .../source/usage/operations/transformations/vgridshift.rst | 14 +++++++++----- 2 files changed, 18 insertions(+), 10 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/operations/transformations/hgridshift.rst b/docs/source/usage/operations/transformations/hgridshift.rst index 78e46aa9..bd147c2f 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 f48d40c8..272b24ab 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 -- cgit v1.2.3 From 16bc13c878cfa5e2d5dbeef7de5b9546d0df02eb Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 6 Dec 2017 14:06:32 +0100 Subject: Helmer update [wip] --- docs/source/usage/operations/transformations/helmert.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/source') diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst index 46073b63..88a3facd 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` | ++-----------------+--------------------------------------------------------------------+ + -- cgit v1.2.3 From f8d8315fd87a2ff9d210c229985bac8330962a53 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 7 Dec 2017 17:30:05 +0100 Subject: Document the helmert transform --- .../usage/operations/transformations/helmert.rst | 377 ++++++++++++++++++++- 1 file changed, 366 insertions(+), 11 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst index 88a3facd..001d2db1 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} -- cgit v1.2.3 From b59c43e146b9cf040e6e1f000b3ee520a9eecfd7 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 7 Dec 2017 17:31:25 +0100 Subject: Override RTD css and make sure that equation numbers are right-aligned --- docs/source/_static/theme_overrides.css | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) (limited to 'docs/source') diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css index 63ee6cc7..b82d2881 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; +} -- cgit v1.2.3 From 586db5409d203dfc941b88a6e7632dac407d8a7f Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Fri, 8 Dec 2017 11:05:59 +0100 Subject: A few updates to Helmert doc page --- .../usage/operations/transformations/helmert.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/usage/operations/transformations/helmert.rst b/docs/source/usage/operations/transformations/helmert.rst index 001d2db1..03e5db15 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: -- cgit v1.2.3 From 4134d0a47f2ac94807750c82d3a19064d03b8b73 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 21 Dec 2017 16:50:49 +0100 Subject: Deformation operation documented --- docs/source/references.rst | 5 +++++ docs/source/usage/operations/transformations/index.rst | 1 + 2 files changed, 6 insertions(+) (limited to 'docs/source') diff --git a/docs/source/references.rst b/docs/source/references.rst index ad5f16bf..320e401b 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 112d9220..5112ffa2 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 -- cgit v1.2.3 From 9e3547af382998b3e2c50c9000b77fc1ede8211c Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 22 Jan 2018 14:20:36 +0100 Subject: Add deformation docs-page (missing from previous commit) [skip ci] --- .../operations/transformations/deformation.rst | 148 +++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/source/usage/operations/transformations/deformation.rst (limited to 'docs/source') diff --git a/docs/source/usage/operations/transformations/deformation.rst b/docs/source/usage/operations/transformations/deformation.rst new file mode 100644 index 00000000..2489f18e --- /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. -- cgit v1.2.3 From 0e51328d89563c2968a33e816bfd4424d2437a7e Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 22 Jan 2018 14:21:25 +0100 Subject: 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(+) (limited to 'docs/source') diff --git a/docs/source/grids.rst b/docs/source/grids.rst index 7f362a92..4c0bc577 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 bd147c2f..a9690260 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 272b24ab..31b3e56e 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. -- cgit v1.2.3 From 46f56fb01e272730a007e5c6cecb40158c096c0a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 22 Jan 2018 15:37:47 +0100 Subject: 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 (limited to 'docs/source') diff --git a/docs/source/usage/operations/index.rst b/docs/source/usage/operations/index.rst index baae0e0a..d78f8947 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 00000000..18637712 --- /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 + + -- cgit v1.2.3 From 28f7894d9aee8eecc691fd691a0e27ff0914ce08 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 1 Feb 2018 16:46:06 +0100 Subject: Update datatype and function reference to reflect recent code changes [skip ci] --- docs/source/development/reference/datatypes.rst | 26 +++++++++++++++++++++++++ docs/source/development/reference/functions.rst | 4 ++-- 2 files changed, 28 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 1253b1a2..80e9ae4c 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 ea128954..14c0b52a 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* -- cgit v1.2.3 From a9e08ad008b1ff16d6139aab5e813058c922eef8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 22:37:10 +0100 Subject: API reference updates to reflect recent changes across the code-base [skip ci]. --- docs/source/development/reference/datatypes.rst | 106 ++++++++-------- docs/source/development/reference/functions.rst | 156 +++++++++--------------- 2 files changed, 110 insertions(+), 152 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 1253b1a2..89a9306e 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 ea128954..8770f99b 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. -- cgit v1.2.3 From 631145da4d23db670cb378fdae14dc6f3555513b Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 23:09:40 +0100 Subject: 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 +- docs/source/usage/operations/conversions/index.rst | 2 +- .../usage/operations/conversions/unitconvert.rst | 4 +- docs/source/usage/operations/index.rst | 4 +- docs/source/usage/operations/projections/geos.rst | 2 +- docs/source/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(-) (limited to 'docs/source') diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index e7f9101e..5e198ae7 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 80babcb2..3fac1869 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 1429ae88..5a8ce624 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 743224a6..3f8a7bf6 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 7137d85a..960cddbf 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 a557fa07..674f4bd1 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 4b9cbb92..9afad945 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 8afdb35d..c508a167 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 4c0bc577..b3a551d7 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 2209c865..4007bef6 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 324d52fc..88bac738 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 73c5c63c..0d818682 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 38cb46de..0d5d06a8 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 81ea4b6b..d59296d0 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 54324ec4..af27e2fd 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 ad848207..73e517bd 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 d78f8947..87bfdc40 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 3b24e1f7..28b96736 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 f7eb0c67..904dc9e6 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 a9690260..7f3c9895 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 31b3e56e..e9f78310 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 8f0b3586..645c1eb1 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 96bfbba1..2cf66122 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 9a202879..7a1dea8b 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 98e607a7..2f5ee880 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). -- cgit v1.2.3 From c7398bd44d47ac824bb7f81bfdfe60fff3b9b675 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 23:54:30 +0100 Subject: 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(-) (limited to 'docs/source') diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst index d9014a36..eb509bcf 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 ############################################################################### -- cgit v1.2.3 From 0ddbb3612928bf88eac686360a58ca5a9ac14b51 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 23 Feb 2018 12:13:01 +0100 Subject: datatypes.rst: linuistics + INFO datatypes Some minor linguistic corrections + general update to make the documentation reflect the updates in PR #775 --- docs/source/development/reference/datatypes.rst | 79 +++++++++++++------------ 1 file changed, 40 insertions(+), 39 deletions(-) (limited to 'docs/source') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index f2f1d9c9..7f2c4b41 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*". -- cgit v1.2.3 From 79abf9e27f12b1253832ac19cce957e2e3680bca Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Tue, 27 Feb 2018 09:30:10 +0100 Subject: Wrong URL for i-cubed --- docs/source/grids.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source') diff --git a/docs/source/grids.rst b/docs/source/grids.rst index b3a551d7..612183a4 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 `__ -- cgit v1.2.3 From fbf8415e832790127c878aedefd796a75193b6a8 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Tue, 27 Feb 2018 15:12:31 +0100 Subject: 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 (limited to 'docs/source') diff --git a/docs/source/usage/apps/cct.rst b/docs/source/usage/apps/cct.rst new file mode 100644 index 00000000..e6f94526 --- /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