Merge pull request #577 from OSGeo/docs-release-4.10.0

Docs for the upcoming release

5 files changed, 634 insertions, 0 deletions

diff --git a/docs/source/usage/apps/cct.rst b/docs/source/usage/apps/cct.rst
new file mode 100644
index 00000000..e6f94526
--- /dev/null
+++ b/docs/source/usage/apps/cct.rst
@@ -0,0 +1,138 @@
+.. _cct:
+
+================================================================================
+cct
+================================================================================
+
+
+.. Index:: cct
+
+
+
+
+``cct`` a 4D equivalent to the ``proj`` projection
+program, performs transformation coordinate systems on a set of input points.
+The coordinate system transformation can include  translation  between
+projected  and geographic coordinates as well as the application of datum shifts.
+
+cct is an acromyn meaning *Coordinate Conversion and Transformation*.
+
+The acronym refers to definitions given in the OGC 08-015r2/ISO-19111
+standard "Geographical Information -- Spatial Referencing by Coordinates",
+which defines two different classes of *coordinate operations*:
+
+*Coordinate Conversions*, which are coordinate operations where input
+and output datum are identical (e.g. conversion from geographical to
+cartesian coordinates) and
+
+*Coordinate Transformations*, which are coordinate operations where
+input and output datums differ (e.g. change of reference frame).
+
+``cct``, however, also refers to Carl Christian Tscherning (1942--2014),
+professor of Geodesy at the University of Copenhagen, mentor and advisor
+for a generation of Danish geodesists, colleague and collaborator for
+two generations of global geodesists, Secretary General for the
+International Association of Geodesy, IAG (1995--2007), fellow of the
+Amercan Geophysical Union (1991), recipient of the IAG Levallois Medal
+(2007), the European Geosciences Union Vening Meinesz Medal (2008), and
+of numerous other honours.
+
+cct, or Christian, as he was known to most of us, was recognized for his
+good mood, his sharp wit, his tireless work, and his great commitment to
+the development of geodesy -- both through his scientific contributions,
+comprising more than 250 publications, and by his mentoring and teaching
+of the next generations of geodesists.
+
+As Christian was an avid Fortran programmer, and a keen Unix connoiseur,
+he would have enjoyed to know that his initials would be used to name a
+modest Unix style transformation filter, hinting at the tireless aspect
+of his personality, which was certainly one of the reasons he accomplished
+so much, and meant so much to so many people.
+
+Hence, in honour of cct (the geodesist) this is cct (the program).
+
+
+
+Synopsis
+********
+
+::
+
+       cct [ -cotvz [ args ] ]... +opts[=arg]...  file...
+
+Description
+***********
+The following control parameters can  appear  in any order:
+
+::
+
+       -c x,y,z,t
+       --columns=x,y,z,t
+              Specify input columns for (up to) 4 input parameters. Defaults to 1,2,3,4
+
+       -o <output file name>
+       --output=<output file name>
+              Specify the name of the output file.
+
+       -t <time>
+       --time=<time>
+              Specify a fixed observation time to be used for all input data.
+
+      -z <height>
+      --height=<height>
+              Specify a fixed observation height to be used for all input data.
+
+       -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. For a complete description consult the `projection pages <../projections/index.html>`_
+
+
+Examples
+********
+
+1. The operator specs describe the action to be performed by cct. So the following script
+
+::
+
+     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
+
+::
+
+      echo 12 55 | cct -z0 -t0 +proj=utm +zone=32 +ellps=GRS80
+
+Should give results comparable to the classic proj command
+
+::
+
+      echo 12 55 | proj +proj=utm +zone=32 +ellps=GRS80
+
+2. Convert geographical input to UTM zone 32 on the GRS80 ellipsoid:
+
+::
+
+      cct +proj=utm +ellps=GRS80 +zone=32
+
+3. Roundtrip accuracy check for the case above:
+
+::
+
+      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:
+
+::
+
+      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:
+
+::
+
+      cct -t 0 -z 0  +proj=utm  +ellps=GRS80  +zone=32
diff --git a/docs/source/usage/apps/cs2cs.rst b/docs/source/usage/apps/cs2cs.rst
new file mode 100644
index 00000000..675379ef
--- /dev/null
+++ b/docs/source/usage/apps/cs2cs.rst
@@ -0,0 +1,143 @@
+.. _cs2cs:
+
+================================================================================
+cs2cs
+================================================================================
+
+
+``cs2cs`` performs transformation between the source and destination cartographic  coordinate  system
+on a set of input points.  The coordinate system transformation can include  translation  between
+projected  and geographic coordinates as well as the application of datum shifts.
+
+
+Synopsis
+********
+
+::
+
+       cs2cs [ -eEfIlrstvwW [ args ] ] [ +opts[=arg] ] [ +to [+opts[=arg]] ] file[s]
+
+Description
+***********
+The following control parameters can  appear  in any order:
+
+::
+
+       -I     method to specify inverse translation, convert from +to coordinate system to the
+              primary coordinate system defined.
+
+       -ta    A specifies a character employed as the first character to denote a control  line
+              to  be passed through without processing. This option  applicable  to  ascii  input
+              only. (# is the default value).
+
+       -e string
+              String is an arbitrary string to be output if an error is detected  during  data
+              transformations. The  default value is: *\t*. Note that if the -b, -i or -o
+              options are employed, an error is returned as HUGE_VAL value for both
+              return values.
+
+       -E     causes the input coordinates to be copied to the output line prior to printing  the
+              converted values.
+
+       -l[p|P|=|e|u|d]id
+              List projection identifiers with -l, -lp or -lP (expanded) that can be selected
+              with +proj. -l=id gives expanded description of projection id. List
+              ellipsoid identifiers with -le, that can be selected with +ellps,-lu list  of
+              cartesian to meter conversion factors that can be selected with +units or -ld
+              list of datums that can be selected with +datum.
+
+       -r     This options reverses the order of the expected input from longitude-latitude or
+              x-y to latitude-longitude or y-x.
+
+       -s     This options reverses the order of the output from x-y or longitude-latitude to
+              y-x or latitude-longitude.
+
+       -f format
+              Format is a printf format string to control the form of the output values. For
+              inverse projections, the output will be in degrees when this option is employed.
+              If a format is specified for inverse projection the output data will be in deci-
+              mal  degrees. The default format is "%.2f" for forward projection and DMS for
+              inverse.
+
+       -[w|W]n
+              N is the number of significant fractional digits to employ for seconds output (when
+              the option is not specified, -w3 is assumed). When -W is employed the fields
+              will be constant width and with leading zeroes.
+
+       -v     causes a listing of cartographic control parameters tested for and used by the
+              program to be printed prior to input data.
+
+The ``+args`` run-line arguments are associated with cartographic parameters. Usage varies with
+projection and for a complete description consult the `projection pages <../projections/index.html>`_
+
+The cs2cs program requires two coordinate system
+definitions.  The first (or primary  is  defined
+based on all projection parameters not appearing
+after the +to argument.  All projection  parameters
+appearing  after the ``+to`` argument are considered
+the definition of the second  coordinate
+system.  If there is no second coordinate system
+defined, a geographic coordinate system based on
+the datum and ellipsoid of the source coordinate
+system is assumed.  Note  that  the  source  and
+destination  coordinate  system can both be projections,
+both be geographic, or one of each and
+may have the same or different datums.
+
+Additional  projection control parameters may be
+contained in two auxiliary  control  files:  the
+first   is   optionally   referenced   with  the
+``+init=file:id`` and the second is always processed
+after the name of the projection has been established
+from either the run-line or the  contents
+of  ``+init``   file.   The  environment  parameter
+PROJ_LIB establishes the default directory for a
+file  reference  without an absolute path.  This
+is also used for  supporting  files  like  datum
+shift files.
+
+One  or  more  files (processed in left to right
+order) specify the source of data to  be  transformed.
+A  - will specify the location of processing standard input.
+If no files are  specified,  the  input  is  assumed to be from stdin.
+For input data the two data values  must  be  in
+the  first  two white space separated fields and
+when both input and output are ASCII all  trailing
+portions  of the input line are appended to
+the output line.
+
+Input geographic data (longitude  and  latitude)
+must  be  in  DMS  or decimal degrees format and
+input cartesian data must be in units consistent
+with  the  ellipsoid major axis or sphere radius
+units.  Output geographic coordinates will  normally
+be in DMS format (use ``-f %.12f`` for decimal
+degrees with 12 decimal places), while projected
+(cartesian)   coordinates   will  be  in  linear
+(meter, feet) units.
+
+
+Example
+*******
+The following script
+
+::
+
+     cs2cs +proj=latlong +datum=NAD83
+           +to +proj=utm +zone=10  +datum=NAD27
+     -r <<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
+
+
diff --git a/docs/source/usage/apps/geod.rst b/docs/source/usage/apps/geod.rst
new file mode 100644
index 00000000..e7056121
--- /dev/null
+++ b/docs/source/usage/apps/geod.rst
@@ -0,0 +1,168 @@
+.. _geod:
+
+================================================================================
+geod
+================================================================================
+
+``geod``  (direct)  and  ``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 f is flattening.
+
+
+``invgeod`` may not be available on all  platforms;  in  this  case
+call geod with the -I option.
+
+
+
+Synopsis
+********
+
+::
+
+       geod +ellps=<ellipse> [ -afFIlptwW [ args ] ] [ +args ] file[s]
+
+       invgeod +ellps=<ellipse> [ -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 <proj.html>`_ 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 <<EOF -I +units=us-mi
+     42d15'N 71d07'W 45d31'N 123d41'W
+     EOF
+
+which gives the results:
+
+::
+
+     -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:
+
+::
+
+     geod +ellps=clrk66 <<EOF +units=us-mi
+     42d15'N 71d07'W -66d31'50.141" 2587.504
+     EOF
+
+which gives:
+
+::
+
+     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>`_.
diff --git a/docs/source/usage/apps/index.rst b/docs/source/usage/apps/index.rst
new file mode 100644
index 00000000..5ee58248
--- /dev/null
+++ b/docs/source/usage/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/usage/apps/proj.rst b/docs/source/usage/apps/proj.rst
new file mode 100644
index 00000000..6227047f
--- /dev/null
+++ b/docs/source/usage/apps/proj.rst
@@ -0,0 +1,164 @@
+.. _proj:
+
+================================================================================
+proj
+================================================================================
+
+
+.. Index:: proj
+
+``proj`` and ``invproj`` perform respective forward  and inverse  transformation  of cartographic data to
+or from cartesian data  with  a  wide  range  of selectable projection functions.
+
+
+Synopsis
+********
+::
+
+    proj [ -bcCeEfiIlmorsStTvVwW [ args ] ] [ +args ] file[s]
+    invproj [ -bcCeEfiIlmorsStTwW [ args ] ] [ +args ] file[s]
+
+
+Description
+***********
+The  following  control parameters can appear in any order
+
+::
+
+       -b     Special option for binary coordinate data input and output through standard input
+              and standard output. Data is assumed to be in system type double floating point
+              words. This option is to be used when proj is a son process and allows bypassing
+              formatting operations.
+
+       -i     Selects binary input only (see -b option).
+
+       -C     Check. Invoke all built in self tests and report. Get more verbose report by
+              preceding with the -V option).
+
+       -I     alternate method to specify inverse projection. Redundant when used with invproj.
+
+       -o     Selects binary output only (see -b option).
+
+       -ta    A specifies a character employed as the first character to denote a control line
+              to be passed through without  processing. This  option applicable to ascii input
+              only. (# is the default value).
+
+       -e string
+              String is an arbitrary string to be output if an error is detected during data
+              transformations. The default value is: *\t*. Note that if the -b, -i or -o
+              options are employed, an error is returned as HUGE_VAL value for both return values.
+
+       -E     causes the input coordinates to be copied to the output line prior to printing the
+              converted values.
+
+
+       -l[p|P|=|e|u|d]id
+              List projection identifiers with -l, -lp or -lP (expanded) that can be selected
+              with +proj. -l=id gives expanded description of projection id. List
+              ellipsoid identifiers with -le, that can be selected with +ellps, -lu list of
+              cartesian to meter conversion factors that can be selected with +units or -ld
+              list of datums that can be selected with +datum.
+
+       -r     This options reverses the order of the expected input from longitude-latitude or
+              x-y to latitude-longitude or y-x.
+
+       -s     This options reverses the order of the output from x-y or longitude-latitude to
+              y-x or latitude-longitude.
+
+       -S     Causes estimation of 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.
+
+       -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 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
+
+::
+
+     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