diff options
Diffstat (limited to 'docs/source/apps')
| -rw-r--r-- | docs/source/apps/cct.rst | 165 | ||||
| -rw-r--r-- | docs/source/apps/cs2cs.rst | 187 | ||||
| -rw-r--r-- | docs/source/apps/geod.rst | 214 | ||||
| -rw-r--r-- | docs/source/apps/index.rst | 21 | ||||
| -rw-r--r-- | docs/source/apps/proj.rst | 236 |
5 files changed, 823 insertions, 0 deletions
diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst new file mode 100644 index 00000000..9153e29b --- /dev/null +++ b/docs/source/apps/cct.rst @@ -0,0 +1,165 @@ +.. _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/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst new file mode 100644 index 00000000..ba77aadf --- /dev/null +++ b/docs/source/apps/cs2cs.rst @@ -0,0 +1,187 @@ +.. _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/apps/geod.rst b/docs/source/apps/geod.rst new file mode 100644 index 00000000..3b60f461 --- /dev/null +++ b/docs/source/apps/geod.rst @@ -0,0 +1,214 @@ +.. _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/apps/index.rst b/docs/source/apps/index.rst new file mode 100644 index 00000000..5ee58248 --- /dev/null +++ b/docs/source/apps/index.rst @@ -0,0 +1,21 @@ +.. _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/apps/proj.rst b/docs/source/apps/proj.rst new file mode 100644 index 00000000..dee4ea89 --- /dev/null +++ b/docs/source/apps/proj.rst @@ -0,0 +1,236 @@ +.. _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/ |