From 1df9429b3ef8fd5af34c9e59d1978fbca0ae3bcb Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 15 Sep 2016 22:11:38 +0200 Subject: Added 'Applications' section to docs --- docs/source/apps/cs2cs.rst | 137 ++++++++++++++++++++++++++++++++++- docs/source/apps/geod.rst | 173 +++++++++++++++++++++++++++++++++++++++++++++ docs/source/apps/index.rst | 17 ++++- docs/source/apps/proj.rst | 164 ++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 7 +- 5 files changed, 493 insertions(+), 5 deletions(-) create mode 100644 docs/source/apps/geod.rst create mode 100644 docs/source/apps/proj.rst (limited to 'docs/source') diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index eb299b77..ae8016fe 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -7,4 +7,139 @@ cs2cs .. Index:: cs2cs -This document describes the ``cs2cs`` application +``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 index cf99cd55..1baaf1c5 100644 --- a/docs/source/apps/index.rst +++ b/docs/source/apps/index.rst @@ -4,9 +4,24 @@ 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 new file mode 100644 index 00000000..a06df383 --- /dev/null +++ b/docs/source/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 <