diff options
Diffstat (limited to 'docs/source/usage')
| -rw-r--r-- | docs/source/usage/apps/cct.rst | 165 | ||||
| -rw-r--r-- | docs/source/usage/apps/cs2cs.rst | 187 | ||||
| -rw-r--r-- | docs/source/usage/apps/geod.rst | 214 | ||||
| -rw-r--r-- | docs/source/usage/apps/index.rst | 21 | ||||
| -rw-r--r-- | docs/source/usage/apps/proj.rst | 236 | ||||
| -rw-r--r-- | docs/source/usage/index.rst | 1 |
6 files changed, 0 insertions, 824 deletions
diff --git a/docs/source/usage/apps/cct.rst b/docs/source/usage/apps/cct.rst deleted file mode 100644 index 9153e29b..00000000 --- a/docs/source/usage/apps/cct.rst +++ /dev/null @@ -1,165 +0,0 @@ -.. _cct: - -================================================================================ -cct -================================================================================ - -.. Index:: cct - -.. only:: html - - Coordinate Conversion and Transformation. - -Synopsis -******** - - **cct** [ **-cotvz** [ args ] ] *+opts[=arg]* file[s] - -Description -*********** - -:program:`cct` a 4D equivalent to the :program:`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. - - -The following control parameters can appear in any order: - -.. program:: cct - -.. option:: -c <x,y,z,t> - - Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4. - -.. option:: -o <output file name>, --output=<output file name> - - Specify the name of the output file. - -.. option:: -t <time>, --time=<time> - - Specify a fixed observation time to be used for all input data. - -.. option:: -z <height>, --height=<height> - - Specify a fixed observation height to be used for all input data. - -.. option:: -v, --verbose - - Write non-essential, but potentially useful, information to stderr. - Repeat for additional information (``-vv``, ``-vvv``, etc.) - -The *+args* arguments are associated with coordinate operation parameters. -Usage varies with operation. - -.. only:: html - - For a complete description consult the :ref:`projection pages <projections>`. - - -:program:`cct` is an acronym 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). - -Examples -******** - -1. The operator specs describe the action to be performed by :program:`cct`. So - the following script - -.. code-block:: console - - echo 12 55 0 0 | cct +proj=utm +zone=32 +ellps=GRS80 - -will transform the input geographic coordinates into UTM zone 32 coordinates. -Hence, the command - -.. code-block:: console - - echo 12 55 | cct -z0 -t0 +proj=utm +zone=32 +ellps=GRS80 - -Should give results comparable to the classic proj command - -.. code-block:: console - - echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80 - -2. Convert geographical input to UTM zone 32 on the GRS80 ellipsoid: - -.. code-block:: console - - cct +proj=utm +ellps=GRS80 +zone=32 - -3. Roundtrip accuracy check for the case above: - -.. code-block:: console - - cct +proj=pipeline +proj=utm +ellps=GRS80 +zone=32 +step +step +inv - -4. As (2) but specify input columns for longitude, latitude, height and time: - -.. code-block:: console - - cct -c 5,2,1,4 +proj=utm +ellps=GRS80 +zone=32 - -5. As (2) but specify fixed height and time, hence needing only 2 cols in - input: - -.. code-block:: console - - cct -t 0 -z 0 +proj=utm +ellps=GRS80 +zone=32 - - -Background -********** - -:program:`cct` 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 -American 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 connoisseur, -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 :program:`cct` (the program). - - -.. only:: man - - See also - ******** - - **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)** - - Bugs - **** - - A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues - where new bug reports can be submitted to. - - Home page - ********* - - http://proj4.org/ diff --git a/docs/source/usage/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst deleted file mode 100644 index ba77aadf..00000000 --- a/docs/source/usage/apps/cs2cs.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. _cs2cs: - -================================================================================ -cs2cs -================================================================================ - -.. only:: html - - Cartographic coordinate system filter. - -Synopsis -******** - - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s] - -Description -*********** - -:program:`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. - -The following control parameters can appear in any order: - -.. program:: cs2cs - -.. option:: -I - - method to specify inverse translation, convert from *+to* coordinate system to - the primary coordinate system defined. - -.. option:: -t<a> - - 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). - -.. option:: -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. - -.. option:: -E - - causes the input coordinates to be copied to the output line prior to - printing the converted values. - -.. option:: -l<[=id]> - - List projection identifiers that can be selected with *+proj*. ``cs2cs -l=id`` - gives expanded description of projection id, e.g. ``cs2cs -l=merc``. - -.. option:: -lp - - List of all projection id that can be used with the *+proj* parameter. - Equivalent to ``cs2cs -l``. - -.. option:: -lP - - Expanded description of all projections that can be used with the *+proj* - parameter. - -.. option:: -le - - List of all ellipsoids that can be selected with the *+ellps* parameters. - -.. option:: -lu - - List of all distance units that can be selected with the *+units* parameter. - -.. option:: -ld - - List of datums that can be selected with the *+datum* parameter. - -.. option:: -r - - This options reverses the order of the expected input from - longitude-latitude or x-y to latitude-longitude or y-x. - -.. option:: -s - - This options reverses the order of the output from x-y or longitude-latitude - to y-x or latitude-longitude. - -.. option:: -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. - -.. option:: -[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. - -.. option:: -v - - causes a listing of cartographic control parameters tested for and used by - the program to be printed prior to input data. - - -.. only:: man - - The *+args* run-line arguments are associated with cartographic - parameters. - -.. only:: html - - The *+args* run-line arguments are associated with cartographic - parameters. Usage varies with projection and for a complete description - consult the :ref:`projection pages <projections>`. - -The :program:`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 - <<EOF 45d15'33.1" 111.5W 45d15.551666667N -111d30 +45.25919444444 - 111d30'000w EOF - -will transform the input NAD83 geographic coordinates into NAD27 coordinates in -the UTM projection with zone 10 selected. The geographic values of this -example are equivalent and meant as examples of various forms of DMS input. -The x-y output data will appear as three lines of: - -:: - - 1402285.99 5076292.42 0.000 - -.. only:: man - - See also - ******** - - **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)** - - Bugs - **** - - A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues - where new bug reports can be submitted to. - - Home page - ********* - - http://proj4.org/ diff --git a/docs/source/usage/apps/geod.rst b/docs/source/usage/apps/geod.rst deleted file mode 100644 index 3b60f461..00000000 --- a/docs/source/usage/apps/geod.rst +++ /dev/null @@ -1,214 +0,0 @@ -.. _geod: - -================================================================================ -geod -================================================================================ - -Synopsis -******** - - **geod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] - - **invgeod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] - -Description -*********** - -:program:`geod` (direct) and :program:`invgeod` (inverse) perform geodesic -(Great Circle) computations for determining latitude, longitude and back -azimuth of a terminus point given a initial point latitude, longitude, -azimuth and distance (direct) or the forward and back azimuths and distance -between an initial and terminus point latitudes and longitudes (inverse). -The results are accurate to round off for :math:`|f| < 1/50`, where -:math:`f` is flattening. - - -:program:`invgeod` may not be available on all platforms; in this case -use :option:`geod -I` instead. - -The following command-line options can appear in any order: - - -.. program:: geod - - -.. option:: -I - - Specifies that the inverse geodesic computation is to be performed. May be - used with execution of geod as an alternative to invgeod execution. - -.. option:: -a - - Latitude and longitudes of the initial and terminal points, forward and - back azimuths and distance are output. - -.. option:: -ta - - A specifies a character employed as the first character to denote a control - line to be passed through without processing. - -.. option:: -le - - Gives a listing of all the ellipsoids that may be selected with the - *+ellps=* option. - -.. option:: -lu - - Gives a listing of all the units that may be selected with the *+units=* - option. - -.. option:: -f <format> - - Format is a printf format string to control the output form of the - geographic coordinate values. The default mode is DMS for geographic - coordinates and "%.3f" for distance. - -.. option:: -F <format> - - Format is a printf format string to control the output form of the distance - value (``-F``). The default mode is DMS for geographic coordinates and - "%.3f" for distance. - -.. option:: -w<n> - - N is the number of significant fractional digits to employ for seconds - output (when the option is not specified, ``-w3`` is assumed). - -.. option:: -W<n> - - N is the number of significant fractional digits to employ for seconds - output. When ``-W`` is employed the fields will be constant width - with leading zeroes. - -.. option:: -p - - This option causes the azimuthal values to be output as unsigned DMS - numbers between 0 and 360 degrees. Also note :option:`-f`. - -The *+args* command-line options are associated with geodetic -parameters for specifying the ellipsoidal or sphere to use. -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. - -.. only:: html - - See :ref:`projections_intro` for full - list of these parameters and controls. - -.. only:: man - - See the PROJ documentation for a full list of these parameters and - controls. - -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 :option:`-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 :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: - -.. code-block:: console - - geod +ellps=clrk66 <<EOF -I +units=us-mi - 42d15'N 71d07'W 45d31'N 123d41'W - EOF - -which gives the results: - -.. code-block:: console - - -66d31'50.141" 75d39'13.083" 2587.504 - -where the first two values are the azimuth from Boston to Portland, -the back azimuth from Portland to Boston followed by the distance. - -An example of forward geodesic use is to use the Boston location -and determine Portland's location by azimuth and distance: - -.. code-block:: console - - geod +ellps=clrk66 <<EOF +units=us-mi - 42d15'N 71d07'W -66d31'50.141" 2587.504 - EOF - -which gives: - -.. code-block:: console - - 45d31'0.003"N 123d40'59.985"W 75d39'13.094" - -.. note:: - Lack of precision in the distance value compromises the - precision of the Portland location. - -Further reading -*************** - -#. `GeographicLib <https://geographiclib.sourceforge.io>`_. - -#. C. F. F. Karney, `Algorithms for Geodesics <https://doi.org/10.1007/s00190-012-0578-z>`_, J. Geodesy **87**\ (1), 43–55 (2013); - `addenda <https://geographiclib.sourceforge.io/geod-addenda.html>`_. - -#. `A geodesic bibliography <https://geographiclib.sourceforge.io/geodesic-papers/biblio.html>`_. - -.. only:: man - - See also - ******** - - **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)** - - Bugs - **** - - A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues - where new bug reports can be submitted to. - - Home page - ********* - - http://proj4.org/ diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst deleted file mode 100644 index 5ee58248..00000000 --- a/docs/source/usage/apps/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _apps: - -================================================================================ -Applications -================================================================================ - -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 -support for basic datum translation. The ``geod`` program provides the ability -to do geodesic (great circle) computations. - -.. toctree:: - :maxdepth: 1 - - proj - cct - cs2cs - geod - diff --git a/docs/source/usage/apps/proj.rst b/docs/source/usage/apps/proj.rst deleted file mode 100644 index dee4ea89..00000000 --- a/docs/source/usage/apps/proj.rst +++ /dev/null @@ -1,236 +0,0 @@ -.. _proj: - -================================================================================ -proj -================================================================================ - -.. only:: html - - Cartographic projection filter. - -.. Index:: proj - -Synopsis -******** - **proj** [ **-bceEfiIlmorsStTvVwW** ] [ args ] ] [ *+args* ] file[s] - - **invproj** [ **-bceEfiIlmorsStTwW** ] [ args ] ] [ *+args* ] file[s] - - -Description -*********** -:program:`proj` and :program:`invproj` perform respective forward and inverse -transformation of cartographic data to or from cartesian data with a wide -range of selectable projection functions. - -:program:`invproj` may not be available on all platforms; in this case -use :option:`proj -I` instead. - -The following control parameters can appear in any order - -.. program:: proj - -.. option:: -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. - -.. option:: -i - - Selects binary input only (see :option:`-b`). - -.. option:: -I - - alternate method to specify inverse projection. Redundant when used with - invproj. - -.. option:: -o - - Selects binary output only (see :option:`-b`). - -.. option:: -t<a> - - *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). - -.. option:: -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 - :option:`-b`, :option:`-i` or :option:`-o` options are employed, an error - is returned as HUGE_VAL value for both return values. - -.. option:: -E - - causes the input coordinates to be copied to the output line prior to - printing the converted values. - -.. option:: -l<[=id]> - - List projection identifiers that can be selected with *+proj*. ``proj -l=id`` - gives expanded description of projection id, e.g. ``proj -l=merc``. - -.. option:: -lp - - List of all projection id that can be used with the *+proj* parameter. - Equivalent to ``proj -l``. - -.. option:: -lP - - Expanded description of all projections that can be used with the *+proj* - parameter. - -.. option:: -le - - List of all ellipsoids that can be selected with the *+ellps* parameters. - -.. option:: -lu - - List of all distance units that can be selected with the *+units* parameter. - -.. option:: -ld - - List of datums that can be selected with the *+datum* parameter. - - -.. option:: -r - - This options reverses the order of the expected input from - longitude-latitude or x-y to latitude-longitude or y-x. - -.. option:: -s - - This options reverses the order of the output from x-y or longitude-latitude - to y-x or latitude-longitude. - -.. option:: -S - - Causes estimation of meridional 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 meridional - and parallel scales factors will be equal and angular distortion zero. Equal - area projections will have an area factor of 1. - -.. option:: -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. - -.. option:: -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. - -.. option:: -[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. - -.. option:: -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 - :option:`-T` option. - -.. option:: -V - - This option causes an expanded annotated listing of the characteristics of - the projected point. :option:`-v` is implied with this option. - -.. 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. -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 :envvar:`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. - -.. only:: html - - Usage of *+args* varies with projection and for a complete description - consult the :ref:`projection pages <projections>`. - - -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 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 geographic 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 - -.. code-block:: console - - proj +proj=utm +lon_0=112w +ellps=clrk66 - -r <<EOF - 45d15'33.1" 111.5W - 45d15.551666667N -111d30 - +45.25919444444 111d30'000w - EOF - -will perform UTM forward projection with a standard UTM central meridian -nearest longitude 112W. The geographic values of this example are equivalent -and meant as examples of various forms of DMS input. The x-y output -data will appear as three lines of:: - - 460769.27 5011648.45 - -.. only:: man - - Other programs - ************** - - The :program:`proj` program is limited to converting between geographic and - projected coordinates within one datum. - - The :program:`cs2cs` program operates similarly, but allows translation - between any paor of definable coordinate reference systems, including - support for datum translation. - - See also - ******** - - **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)** - - Bugs - **** - - A list of know bugs can be found at http://github.com/OSGeo/proj.4/issues - where new bug reports can be submitted to. - - Home page - ********* - - http://proj4.org/ diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst index 163aa374..7de0e147 100644 --- a/docs/source/usage/index.rst +++ b/docs/source/usage/index.rst @@ -13,7 +13,6 @@ command line applications or the C API that is a part of the software package. :maxdepth: 1 quickstart - apps/index projections transformation environmentvars |