diff options
| -rw-r--r-- | docs/source/apps/cct.rst | 12 | ||||
| -rw-r--r-- | docs/source/apps/cs2cs.rst | 82 | ||||
| -rw-r--r-- | docs/source/apps/geod.rst | 104 | ||||
| -rw-r--r-- | docs/source/apps/gie.rst | 22 | ||||
| -rw-r--r-- | docs/source/apps/proj.rst | 75 |
5 files changed, 147 insertions, 148 deletions
diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst index 20aec06c..3c3f6668 100644 --- a/docs/source/apps/cct.rst +++ b/docs/source/apps/cct.rst @@ -13,18 +13,18 @@ cct Synopsis ******** - **cct** [ **-cotvz** [ args ] ] *+opts[=arg]* file[s] + **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 +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: +The following control parameters can appear in any order: .. program:: cct @@ -120,14 +120,14 @@ Should give results comparable to the classic proj command .. code-block:: console - cct -c 5,2,1,4 +proj=utm +ellps=GRS80 +zone=32 + 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 + cct -t 0 -z 0 +proj=utm +ellps=GRS80 +zone=32 Background diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index ba77aadf..45d004bf 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -11,17 +11,17 @@ cs2cs Synopsis ******** - **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s] + **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 +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: +The following control parameters can appear in any order: .. program:: cs2cs @@ -33,20 +33,20 @@ The following control parameters can appear in any order: .. 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). + 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 + 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. + printing the converted values. .. option:: -l<[=id]> @@ -89,8 +89,8 @@ The following control parameters can appear in any order: 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 + employed. If a format is specified for inverse projection the output data + will be in decimal degrees. The default format is "%.2f" for forward projection and DMS for inverse. .. option:: -[w|W]<n> @@ -113,38 +113,38 @@ The following control parameters can appear in any order: .. only:: html The *+args* run-line arguments are associated with cartographic - parameters. Usage varies with projection and for a complete description + 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 +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 +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 +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 +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 +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 +places), while projected (cartesian) coordinates will be in linear (meter, feet) units. @@ -155,18 +155,18 @@ 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 + 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. +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 + 1402285.99 5076292.42 0.000 .. only:: man diff --git a/docs/source/apps/geod.rst b/docs/source/apps/geod.rst index 3b60f461..e5251ad2 100644 --- a/docs/source/apps/geod.rst +++ b/docs/source/apps/geod.rst @@ -7,23 +7,23 @@ geod Synopsis ******** - **geod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] + **geod** *+ellps=<ellipse>* [ **-afFIlptwW** [ args ] ] [ *+args* ] file[s] - **invgeod** *+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 +: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 +: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: @@ -40,7 +40,7 @@ The following command-line options can appear in any order: .. option:: -a Latitude and longitudes of the initial and terminal points, forward and - back azimuths and distance are output. + back azimuths and distance are output. .. option:: -ta @@ -54,7 +54,7 @@ The following command-line options can appear in any order: .. option:: -lu - Gives a listing of all the units that may be selected with the *+units=* + Gives a listing of all the units that may be selected with the *+units=* option. .. option:: -f <format> @@ -85,15 +85,15 @@ The following command-line options can appear in any order: 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 *+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 + See :ref:`projections_intro` for full list of these parameters and controls. .. only:: man @@ -101,88 +101,88 @@ the first occurrence assumed to be the desired value. 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, +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, +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 +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 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 +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 +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 +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 +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 +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. +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 + 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 + -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 +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 + 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" + 45d31'0.003"N 123d40'59.985"W 75d39'13.094" .. note:: - Lack of precision in the distance value compromises the + Lack of precision in the distance value compromises the precision of the Portland location. Further reading diff --git a/docs/source/apps/gie.rst b/docs/source/apps/gie.rst index 777c5833..35b0ac38 100644 --- a/docs/source/apps/gie.rst +++ b/docs/source/apps/gie.rst @@ -8,7 +8,7 @@ gie .. only:: html - The Geospatial Integrity Investigation Environment + The Geospatial Integrity Investigation Environment Synopsis ******** @@ -34,13 +34,13 @@ already employed for compiling the library. .. option:: -v, --verbose - Verbose: Provide non-essential informational output. Repeat :option:`-v` for + Verbose: Provide non-essential informational output. Repeat :option:`-v` for more verbosity (e.g. ``-vv``) .. option:: -q, --quiet - Quiet: Opposite of verbose. In quiet mode not even errors are - reported. Only interaction is through the return code (0 on success, + Quiet: Opposite of verbose. In quiet mode not even errors are + reported. Only interaction is through the return code (0 on success, non-zero indicates number of FAILED tests) .. option:: -l, --list @@ -75,7 +75,7 @@ like: </gie> -Parsing of a :program:`gie` file starts at ``<gie>`` and ends when ``</gie>`` +Parsing of a :program:`gie` file starts at ``<gie>`` and ends when ``</gie>`` is reached. Anything before ``<gie>`` and after ``</gie>`` is not considered. Test cases are created by defining an :option:`operation` which :option:`accept` an input coordinate and :option:`expect` an output @@ -143,7 +143,7 @@ gie command language accompanying :option:`expect` is needed. Note that :program:`gie` accepts the underscore ("_") as a thousands - separator. It is not required (in fact, it is entirely ignored by the + separator. It is not required (in fact, it is entirely ignored by the input routine), but it significantly improves the readability of the very long strings of numbers typically required in projected coordinates. @@ -179,7 +179,7 @@ gie command language The :option:`tolerance` command controls how much accepted coordinates can deviate from the expected coordinate. This is handy to test that an operation meets a certain numerical tolerance threshold. Some operations - are expexted to be accurate within milimeters where others might only be + are expexted to be accurate within milimeters where others might only be accurate within a few meters. :option:`tolerance` should .. code-block:: console @@ -251,7 +251,7 @@ gie command language .. code-block:: console - operation proj=hgridshift +grids=nzgd2kgrid0005.gsb ellps=GRS80 + operation proj=hgridshift +grids=nzgd2kgrid0005.gsb ellps=GRS80 tolerance 1 mm ignore pjd_err_failed_to_load_grid accept 172.999892181021551 -45.001620431954613 @@ -307,12 +307,12 @@ Background More importantly than being an acronym for "Geospatial Integrity Investigation Environment", gie were also the initials, user id, and USGS email address of Gerald Ian Evenden (1935--2016), the geospatial visionary, who, already in the -1980s, started what was to become the PROJ of today. +1980s, started what was to become the PROJ of today. Gerald's clear vision was that map projections are *just special functions*. Some of them rather complex, most of them of two variables, but all of them *just special functions*, and not particularly more special than the :c:func:`sin()`, -:c:func:`cos()`, :c:func:`tan()`, and :c:func:`hypot()` already available in the C standard library. +:c:func:`cos()`, :c:func:`tan()`, and :c:func:`hypot()` already available in the C standard library. And hence, according to Gerald, *they should not be particularly much harder to use*, for a programmer, than the :c:func:`sin()`'s, :c:func:`tan()`'s and @@ -322,7 +322,7 @@ Gerald's ingenuity also showed in the implementation of the vision, where he devised a comprehensive, yet simple, system of key-value pairs for parameterising a map projection, and the highly flexible :c:type:`PJ` struct, storing run-time compiled versions of those key-value pairs, hence making a map -projection function call, ``pj_fwd(PJ, point)``, as easy as a traditional function +projection function call, ``pj_fwd(PJ, point)``, as easy as a traditional function call like ``hypot(x,y)``. While today, we may have more formally well defined metadata systems (most diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst index dee4ea89..19a72a66 100644 --- a/docs/source/apps/proj.rst +++ b/docs/source/apps/proj.rst @@ -19,14 +19,14 @@ Synopsis 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:`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 +: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 +The following control parameters can appear in any order .. program:: proj @@ -53,15 +53,15 @@ The following control parameters can appear in any order .. 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 + 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. + 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 @@ -119,21 +119,21 @@ The following control parameters can appear in any order 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 + 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 + 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. + 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 @@ -149,7 +149,7 @@ The following control parameters can appear in any order .. 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 + 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 @@ -160,13 +160,13 @@ The following control parameters can appear in any order 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 +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. ++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 @@ -174,17 +174,17 @@ also used for supporting files like datum shift files. 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 +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 +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 @@ -193,16 +193,15 @@ 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 + 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 +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 |