diff options
Diffstat (limited to '_sources/apps')
| -rw-r--r-- | _sources/apps/cct.rst.txt | 245 | ||||
| -rw-r--r-- | _sources/apps/common_man.rst.txt | 12 | ||||
| -rw-r--r-- | _sources/apps/cs2cs.rst.txt | 320 | ||||
| -rw-r--r-- | _sources/apps/geod.rst.txt | 203 | ||||
| -rw-r--r-- | _sources/apps/gie.rst.txt | 398 | ||||
| -rw-r--r-- | _sources/apps/index.rst.txt | 28 | ||||
| -rw-r--r-- | _sources/apps/proj.rst.txt | 219 | ||||
| -rw-r--r-- | _sources/apps/projinfo.rst.txt | 606 | ||||
| -rw-r--r-- | _sources/apps/projsync.rst.txt | 177 |
9 files changed, 2208 insertions, 0 deletions
diff --git a/_sources/apps/cct.rst.txt b/_sources/apps/cct.rst.txt new file mode 100644 index 00000000..08bdd004 --- /dev/null +++ b/_sources/apps/cct.rst.txt @@ -0,0 +1,245 @@ +.. _cct: + +================================================================================ +cct +================================================================================ + +.. Index:: cct + +.. only:: html + + Coordinate Conversion and Transformation. + +Synopsis +******** + + **cct** [**-cIostvz** [args]] *+opt[=arg]* ... file ... + +or + + **cct** [**-cIostvz** [args]] {object_definition} file ... + +Where {object_definition} is one of the possibilities accepted +by :c:func:`proj_create`, provided it expresses a coordinate operation + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:1671" "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an object name. e.g. "ITRF2014 to ETRF2014 (1)". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json + + .. versionadded:: 8.0.0 + + .. note:: + + Before version 8.0.0 only proj-strings could be used to instantiate + operations in :program:`cct`. + + +or + + **cct** [**-cIostvz** [args]] {object_reference} file ... + +where {object_reference} is a filename preceded by the '@' character. The +file referenced by the {object_reference} must contain a valid +{object_definition}. + + .. versionadded:: 8.0.0 + + + +Description +*********** + +:program:`cct` is 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:: -d <n> + + .. versionadded:: 5.2.0 + + Specify the number of decimals in the output. + +.. option:: -I + + Do the inverse transformation. + +.. 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:: -s <n>, --skip-lines=<n> + + .. versionadded:: 5.1.0 + + Skip the first *n* lines of input. This applies to any kind of input, whether + it comes from ``STDIN``, a file or interactive user input. + +.. option:: -v, --verbose + + Write non-essential, but potentially useful, information to stderr. + Repeat for additional information (``-vv``, ``-vvv``, etc.) + +.. option:: --version + + Print version number. + +The *+opt* 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). + +Use of remote grids +******************* + +.. versionadded:: 7.0.0 + +If the :envvar:`PROJ_NETWORK` environment variable is set to ``ON``, +:program:`cct` will attempt to use remote grids stored on CDN (Content +Delivery Network) storage, when they are not available locally. + +More details are available in the :ref:`network` section. + +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 :program:`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 + +6. Auxiliary data following the coordinate input is forward to the output + stream: + +.. code-block:: console + + $ echo 12 56 100 2018.0 auxiliary data | cct +proj=merc + 1335833.8895 7522963.2411 100.0000 2018.0000 auxiliary data + +7. Coordinate operation referenced through its code + +.. code-block:: console + + $ echo 3541657.3778 948984.2343 5201383.5231 2020.5 | cct EPSG:8366 + 3541657.9112 948983.7503 5201383.2482 2020.5000 + +8. Coordinate operation referenced through its name + +.. code-block:: console + + $ echo 3541657.3778 948984.2343 5201383.5231 2020.5 | cct "ITRF2014 to ETRF2014 (1)" + 3541657.9112 948983.7503 5201383.2482 2020.5000 + +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)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/common_man.rst.txt b/_sources/apps/common_man.rst.txt new file mode 100644 index 00000000..28a39ba9 --- /dev/null +++ b/_sources/apps/common_man.rst.txt @@ -0,0 +1,12 @@ +.. only:: man + + Bugs + **** + + A list of known bugs can be found at https://github.com/OSGeo/PROJ/issues + where new bug reports can be submitted to. + + Home page + ********* + + https://proj.org/ diff --git a/_sources/apps/cs2cs.rst.txt b/_sources/apps/cs2cs.rst.txt new file mode 100644 index 00000000..841ce092 --- /dev/null +++ b/_sources/apps/cs2cs.rst.txt @@ -0,0 +1,320 @@ +.. _cs2cs: + +================================================================================ +cs2cs +================================================================================ + +.. only:: html + + Filter for transformations between two coordinate reference systems. + +Synopsis +******** + + | **cs2cs** [**-eEfIlrstvwW** [args]] + | [[--area <name_or_code>] | [--bbox <west_long,south_lat,east_long,north_lat>]] + | [--authority <name>] [--no-ballpark] [--accuracy <accuracy>] + | ([*+opt[=arg]* ...] [+to *+opt[=arg]* ...] | {source_crs} {target_crs}) + | file ... + + where {source_crs} or {target_crs} is one of the possibilities accepted + by :c:func:`proj_create`, provided it expresses a CRS + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for references for projected or derived CRSs + e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)": + "urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031" + (*added in 6.2*) + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json (*added in 6.2*) + - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*) + + .. versionadded:: 6.0.0 + + .. note:: before 7.0.1, it was needed to add +to between {source_crs} and {target_crs} + when adding a filename + +Description +*********** + +:program:`cs2cs` performs transformation between the source and destination +cartographic coordinate reference system on a set of input points. The coordinate +reference 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> + + Where *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:: -d <n> + + .. versionadded:: 5.2.0 + + Specify the number of decimals in the output. + +.. option:: -e <string> + + Where *string* is an arbitrary string to be output if an error is detected during + data transformations. The default value is a three character string: ``*\t*``. + +.. 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:: -r + + This options reverses the order of the first two expected + inputs from that specified by the CRS to the opposite + order. The third coordinate, typically height, remains + third. + +.. option:: -s + + This options reverses the order of the first two expected + outputs from that specified by the CRS to the opposite + order. The third coordinate, typically height, remains + third. + + +.. option:: -f <format> + + Where *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 decimal degrees. The default format is ``"%.2f"`` for forward + projection and DMS for inverse. + +.. option:: -w<n> + + Where *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> + + Where *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:: -v + + Causes a listing of cartographic control parameters tested for and used by + the program to be printed prior to input data. + +.. option:: --area <name_or_code> + + .. versionadded:: 8.0.0 + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest can be specified either + as a name (e.g "Denmark - onshore") or a AUTHORITY:CODE (EPSG:3237) + + This option is mutually exclusive with :option:`--bbox`. + +.. option:: --bbox <west_long,south_lat,east_long,north_lat> + + .. versionadded:: 8.0.0 + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest is specified as a + bounding box with geographic coordinates, expressed in degrees in a + unspecified geographic CRS. + `west_long` and `east_long` should be in the [-180,180] range, and + `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than + `east_long`, except in the case where the area of interest crosses the antimeridian. + +.. option:: --no-ballpark + + .. versionadded:: 8.0.0 + + Disallow any coordinate operation that is, or contains, a + :term:`Ballpark transformation` + +.. option:: --accuracy <accuracy> + + .. versionadded:: 8.0.0 + + Sets the minimum desired accuracy for candidate coordinate operations. + +.. option:: --authority <name> + + .. versionadded:: 8.0.0 + + This option can be used to restrict the authority of coordinate operations + looked up in the database. When not specified, coordinate + operations from any authority will be searched, with the restrictions set + in the ``authority_to_authority_preference`` database table related to the authority + of the source/target CRS themselves. + If authority is set to ``any``, then coordinate operations from any authority will be searched + If authority is a non-empty string different of ``any``, then coordinate operations + will be searched only in that authority namespace (e.g ``EPSG``). + + This option is mutually exclusive with :option:`--bbox`. + +.. only:: man + + The *+opt* run-line arguments are associated with cartographic + parameters. + +.. only:: html + + The *+opt* 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 reference system (CRS) 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 CRS. If there is no +second CRS defined, a geographic CRS based on the +datum and ellipsoid of the source CRS is assumed. Note that the +source and destination CRS can both of same or different nature (geographic, +projected, compound CRS), or one of each and may have the same or different datums. + +When using a WKT definition or a AUTHORITY:CODE, the axis order of the CRS will +be enforced. So for example if using EPSG:4326, the first value expected (or +returned) will be a latitude. + +Internally, :program:`cs2cs` uses the :c:func:`proj_create_crs_to_crs` function +to compute the appropriate coordinate operation, so implementation details of +this function directly impact the results returned by the program. + +The environment parameter :envvar:`PROJ_LIB` establishes the +directory for resource files (database, datum shift grids, etc.) + +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. + +Use of remote grids +------------------- + +.. versionadded:: 7.0.0 + +If the :envvar:`PROJ_NETWORK` environment variable is set to ``ON``, +:program:`cs2cs` will attempt to use remote grids stored on CDN (Content +Delivery Network) storage, when they are not available locally. + +More details are available in the :ref:`network` section. + +Examples +******** + +Using PROJ strings +------------------ + +The following script + +:: + + cs2cs +proj=latlong +datum=NAD83 +to +proj=utm +zone=10 +datum=NAD27 -r <<EOF + 45°15'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: + +:: + + 1402293.44 5076292.68 0.00 + + +Using EPSG CRS codes +-------------------- + +Transforming from WGS 84 latitude/longitude (in that order) to UTM Zone 31N/WGS 84 + +:: + + cs2cs EPSG:4326 EPSG:32631 <<EOF + 45N 2E + EOF + +outputs + +:: + + 421184.70 4983436.77 0.00 + +Using EPSG CRS names +-------------------- + +Transforming from WGS 84 latitude/longitude (in that order) with EGM96 height to +UTM Zone 31N/WGS 84 with WGS84 ellipsoidal height + +:: + + echo 45 2 0 | cs2cs "WGS 84 + EGM96 height" "WGS 84 / UTM zone 31N" + +outputs + +:: + + 421184.70 4983436.77 50.69 + + +.. only:: man + + See also + ******** + + **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/geod.rst.txt b/_sources/apps/geod.rst.txt new file mode 100644 index 00000000..7b8f921f --- /dev/null +++ b/_sources/apps/geod.rst.txt @@ -0,0 +1,203 @@ +.. _geod: + +================================================================================ +geod +================================================================================ + +Synopsis +******** + + **geod** *+ellps=<ellipse>* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... + + **invgeod** *+ellps=<ellipse>* [**-afFIlptwW** [args]] [*+opt[=arg]* ...] file ... + +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 :program:`geod` as an alternative to :program:`invgeod` execution. + +.. option:: -a + + Latitude and longitudes of the initial and terminal points, forward and + back azimuths and distance are output. + +.. option:: -t<a> + + Where *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. (Default units are meters.) + +.. option:: -f <format> + + Where *format* is a printf format string to control the output form of the + geographic coordinate values. The default mode is DMS. + +.. option:: -F <format> + + Where *format* is a printf format string to control the output form of the distance + value. The default mode is ``"%.3f"``. + +.. option:: -w<n> + + Where *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> + + Where *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 *+opt* 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. + +:program:`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)**, **gie(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/gie.rst.txt b/_sources/apps/gie.rst.txt new file mode 100644 index 00000000..73d29e04 --- /dev/null +++ b/_sources/apps/gie.rst.txt @@ -0,0 +1,398 @@ +.. _gie: + +================================================================================ +gie +================================================================================ + +.. Index:: gie + +.. only:: html + + The Geospatial Integrity Investigation Environment + +Synopsis +******** + + **gie** [ **-hovql** [ args ] ] file[s] + +Description +*********** + +:program:`gie`, the Geospatial Integrity Investigation Environment, is a +regression testing environment for the PROJ transformation library. Its primary +design goal is to be able to perform regression testing of code that are a part +of PROJ, while not requiring any other kind of tooling than the same C compiler +already employed for compiling the library. + +.. option:: -h, --help + + Print usage information + +.. option:: -o <file>, --output <file> + + Specify output file name + +.. option:: -v, --verbose + + 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, + non-zero indicates number of FAILED tests) + +.. option:: -l, --list + + List the PROJ internal system error codes + +.. option:: --version + + Print version number + +Tests for :program:`gie` are defined in simple text files. Usually having the +extension ``.gie``. Test for :program:`gie` are written in the purpose-build command language for gie. +The basic functionality of the gie command language is implemented through just +3 command verbs: ``operation``, which defines the PROJ operation to test, +``accept``, which defines the input coordinate to read, and ``expect``, which +defines the result to expect. + +A sample test file for :program:`gie` that uses the three above basic commands looks +like: + +.. code-block:: console + + <gie> + + -------------------------------------------- + Test output of the UTM projection + -------------------------------------------- + operation +proj=utm +zone=32 +ellps=GRS80 + -------------------------------------------- + accept 12 55 + expect 691_875.632_14 6_098_907.825_05 + + </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 +coordinate. + +Because :program:`gie` tests are wrapped in the ``<gie>``/``</gie>`` tags it is +also possible to add test cases to custom made :ref:`init files <init_files>`. +The tests will be ignore by PROJ when reading the init file with *+init* and +:program:`gie` ignores anything not wrapped in ``<gie>``/``</gie>``. + +:program:`gie` tests are defined by a set of commands like :option:`operation`, +:option:`accept` and :option:`expect` in the example above. Together the +commands make out the :program:`gie` command language. Any line in a +:program:`gie` file that does not start with a command is ignored. In the +example above it is seen how this can be used to add comments and styling to +:program:`gie` test files in order to make them more readable as well as +documenting what the purpose of the various tests are. + +Below the :ref:`gie_commands` is explained in details. + +Examples +********* + +1. Run all tests in a file with all debug information turned on + +.. code-block:: console + + gie -vvvv corner-cases.gie + +2. Run all tests in several files + +.. code-block:: console + + gie foo bar + +.. _gie_commands: + +gie command language +******************** + + +.. option:: operation <+args> + + Define a PROJ operation to test. Example: + + .. code-block:: console + + operation proj=utm zone=32 ellps=GRS80 + # test 4D function + accept 12 55 0 0 + expect 691875.63214 6098907.82501 0 0 + + # test 2D function + accept 12 56 + expect 687071.4391 6210141.3267 + +.. option:: accept <x y [z [t]]> + + Define the input coordinate to read. Takes test coordinate. The coordinate + can be defined by either 2, 3 or 4 values, where the first two values are + the x- and y-components, the 3rd is the z-component and the 4th is the time + component. The number of components in the coordinate determines which + version of the operation is tested (2D, 3D or 4D). Many coordinates can be + accepted for one :option:`operation`. For each :option:`accept` an + 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 + input routine), but it significantly improves the readability of the very + long strings of numbers typically required in projected coordinates. + + + See :option:`operation` for an example. + +.. option:: expect <x y [z [t]]> | <error code> + + Define the expected coordinate that will be returned from accepted + coordinate passed though an operation. The expected coordinate can be + defined by either 2, 3 or 4 components, similarly to :option:`accept`. + Many coordinates can be expected for one :option:`operation`. For each + :option:`expect` an accompanying :option:`accept` is needed. + + See :option:`operation` for an example. + + In addition to expecting a coordinate it is also possible to expect a + PROJ error code in case an operation can't be created. This is useful when + testing that errors are caught and handled correctly. Below is an example of + that tests that the pipeline operator fails correctly when a non-invertible + pipeline is constructed. + + .. code-block:: console + + operation proj=pipeline step + proj=urm5 n=0.5 inv + expect failure pjd_err_malformed_pipeline + + See :option:`gie --list<--list>` for a list of error codes that can be expected. + +.. option:: tolerance <tolerance> + + 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 expected to be accurate within millimeters where others might only be + accurate within a few meters. :option:`tolerance` should + + .. code-block:: console + + operation proj=merc + # test coordinate as returned by ```echo 12 55 | proj +proj=merc`` + tolerance 1 cm + accept 12 55 + expect 1335833.89 7326837.72 + + # test that the same coordinate with a 50 m false easting as determined + # by ``echo 12 55 |proj +proj=merc +x_0=50`` is still within a 100 m + # tolerance of the unaltered coordinate from proj=merc + tolerance 100 m + accept 12 55 + expect 1335883.89 7326837.72 + + The default tolerance is 0.5 mm. See :option:`proj -lu` for a list of possible + units. + +.. option:: roundtrip <n> <tolerance> + + Do a roundtrip test of an operation. :option:`roundtrip` needs a + :option:`operation` and a :option:`accept` command + to function. The accepted coordinate is passed to the operation first in + it's forward mode, then the output from the forward operation is passed + back to the inverse operation. This procedure is done ``n`` times. If the + resulting coordinate is within the set tolerance of the initial coordinate, + the test is passed. + + Example with the default 100 iterations and the default tolerance: + + .. code-block:: console + + operation proj=merc + accept 12 55 + roundtrip + + Example with count and default tolerance: + + .. code-block:: console + + operation proj=merc + accept 12 55 + roundtrip 10000 + + Example with count and tolerance: + + .. code-block:: console + + operation proj=merc + accept 12 55 + roundtrip 10000 5 mm + +.. option:: direction <direction> + + The :option:`direction` command specifies in which direction an operation + is performed. This can either be ``forward`` or ``inverse``. An example of + this is seen below where it is tested that a symmetrical transformation + pipeline returns the same results in both directions. + + .. code-block:: console + + operation proj=pipeline zone=32 step + proj=utm ellps=GRS80 step + proj=utm ellps=GRS80 inv + tolerance 0.1 mm + + accept 12 55 0 0 + expect 12 55 0 0 + + # Now the inverse direction (still same result: the pipeline is symmetrical) + + direction inverse + expect 12 55 0 0 + + The default direction is "forward". + +.. option:: ignore <error code> + + This is especially + useful in test cases that rely on a grid that is not guaranteed to be + available. Below is an example of that situation. + + .. code-block:: console + + operation proj=hgridshift +grids=nzgd2kgrid0005.gsb ellps=GRS80 + tolerance 1 mm + ignore pjd_err_failed_to_load_grid + accept 172.999892181021551 -45.001620431954613 + expect 173 -45 + + + See :option:`gie --list<--list>` for a list of error codes that can be ignored. + +.. option:: require_grid <grid_name> + + Checks the availability of the grid <grid_name>. If it is not found, then + all :option:`accept`/:option:`expect` pairs until the next + :option:`operation` will be skipped. + :option:`require_grid` can be repeated several times to specify several grids whose + presence is required. + +.. option:: echo <text> + + Add user defined text to the output stream. See the example below. + + .. code-block:: console + + <gie> + echo ** Mercator projection tests ** + operation +proj=merc + accept 0 0 + expect 0 0 + </gie> + + which returns + + .. code-block:: console + + ------------------------------------------------------------------------------- + Reading file 'test.gie' + ** Mercator projection test ** + ------------------------------------------------------------------------------- + total: 1 tests succeeded, 0 tests skipped, 0 tests failed. + ------------------------------------------------------------------------------- + +.. option:: skip + + Skip any test after the first occurrence of :option:`skip`. In the example below only + the first test will be performed. The second test is skipped. This feature is mostly + relevant for debugging when writing new test cases. + + .. code-block:: console + + <gie> + operation proj=merc + accept 0 0 + expect 0 0 + skip + accept 0 1 + expect 0 110579.9 + </gie> + + +Strict mode +*********** + +.. versionadded:: 7.1 + +A stricter variant of normal gie syntax can be used by wrapping gie commands +between ``<gie-strict>`` and ``</gie-strict>``. In strict mode, comment lines +must start with a sharp character. Unknown commands will be considered as an error. +A command can still be split on several lines, but intermediate lines must +end with the space character followed by backslash to mark the continuation. + + .. code-block:: console + + <gie-strict> + # This is a comment. The following line with multiple repeated characters too + ------------------------------------------------- + # A command on several lines must use " \" continuation + operation proj=hgridshift +grids=nzgd2kgrid0005.gsb \ + ellps=GRS80 + tolerance 1 mm + ignore pjd_err_failed_to_load_grid + accept 172.999892181021551 -45.001620431954613 + expect 173 -45 + </gie-strict> + + +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. + +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. + +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 +:c:func:`hypot()`'s so readily available. + +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 +call like ``hypot(x,y)``. + +While today, we may have more formally well defined metadata systems (most +prominent the OGC WKT2 representation), nothing comes close being as easily +readable ("human compatible") as Gerald's key-value system. This system in +particular, and the PROJ system in general, was Gerald's great gift to anyone +using and/or communicating about geodata. + +It is only reasonable to name a program, keeping an eye on the +integrity of the PROJ system, in honour of Gerald. + +So in honour, and hopefully also in the spirit, of Gerald Ian Evenden +(1935--2016), this is the Geospatial Integrity Investigation Environment. + + +.. only:: man + + See also + ******** + + **proj(1)**, **cs2cs(1)**, **cct(1)**, **geod(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/index.rst.txt b/_sources/apps/index.rst.txt new file mode 100644 index 00000000..61448e49 --- /dev/null +++ b/_sources/apps/index.rst.txt @@ -0,0 +1,28 @@ +.. _apps: + +================================================================================ +Applications +================================================================================ + +Bundled with PROJ comes a set of small command line utilities. The :program:`proj` +program is limited to converting between geographic and projection coordinates +within one datum. The :program:`cs2cs` program operates similarly, but allows +translation between any pair of definable coordinate systems, including support +for datum transformation. The :program:`geod` program provides the ability to do +geodesic (great circle) computations. :program:`gie` is the program used for +regression tests in PROJ. :program:`cct`, a 4D equivalent to the :program:`proj` +program, performs transformation coordinate systems on a set of input points. +:program:`projinfo` performs queries for geodetic objects and coordinate +operations. :program:`projsync` is a tool for synchronizing PROJ datum and +transformation support data. + +.. toctree:: + :maxdepth: 1 + + cct + cs2cs + geod + gie + proj + projinfo + projsync diff --git a/_sources/apps/proj.rst.txt b/_sources/apps/proj.rst.txt new file mode 100644 index 00000000..0c62ec7e --- /dev/null +++ b/_sources/apps/proj.rst.txt @@ -0,0 +1,219 @@ +.. _proj: + +================================================================================ +proj +================================================================================ + +.. only:: html + + Cartographic projection filter. + +.. Index:: proj + +Synopsis +******** + **proj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... + + **invproj** [**-beEfiIlmorsStTvVwW**] [args]] [*+opt[=arg]* ...] file ... + + +Description +*********** +:program:`proj` and :program:`invproj` perform respective forward and inverse +conversion 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 :program:`proj` is a child process + and allows bypassing formatting operations. + +.. option:: -d <n> + +.. versionadded:: 5.2.0 + + Specify the number of decimals in the output. + +.. option:: -i + + Selects binary input only (see :option:`-b`). + +.. option:: -I + + Alternate method to specify inverse projection. Redundant when used with + :program:`invproj`. + +.. option:: -o + + Selects binary output only (see :option:`-b`). + +.. option:: -t<a> + + Where *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> + + Where *string* is an arbitrary string to be output if an error is detected during + data transformations. The default value is a three character string: ``*\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:: -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> + + Where *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<n> + + Where *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> + + Where *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:: -v + + Causes a listing of cartographic control parameters tested for and used by + the program to be printed prior to input data. + +.. option:: -V + + This option causes an expanded annotated listing of the characteristics of + the projected point. :option:`-v` is implied with this option. + + +The *+opt* 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 *+opt* 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 converted. 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 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 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 pair of definable coordinate reference systems, including + support for datum translation. + + See also + ******** + + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/projinfo.rst.txt b/_sources/apps/projinfo.rst.txt new file mode 100644 index 00000000..04ee7578 --- /dev/null +++ b/_sources/apps/projinfo.rst.txt @@ -0,0 +1,606 @@ +.. _projinfo: + +================================================================================ +projinfo +================================================================================ + +.. Index:: projinfo + +.. only:: html + + .. versionadded:: 6.0.0 + + Geodetic object and coordinate operation queries + +Synopsis +******** + + | **projinfo** + | [-o formats] [-k crs|operation|datum|ensemble|ellipsoid] [--summary] [-q] + | [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] + | [--spatial-test contains|intersects] + | [--crs-extent-use none|both|intersection|smallest] + | [--grid-check none|discard_missing|sort|known_available] + | [--pivot-crs always|if_no_direct_transformation|never|{auth:code[,auth:code]*}] + | [--show-superseded] [--hide-ballpark] [--accuracy {accuracy}] + | [--allow-ellipsoidal-height-as-vertical-crs] + | [--boundcrs-to-wgs84] + | [--authority name] + | [--main-db-path path] [--aux-db-path path]* + | [--dump-db-structure] + | [--identify] [--3d] + | [--output-id AUTH:CODE] + | [--c-ify] [--single-line] + | --searchpaths | --remote-data | + | --list-crs [list-crs-filter] | + | --dump-db-structure [{object_definition} | {object_reference}] | + | {object_definition} | {object_reference} | (-s {srs_def} -t {srs_def}) + | + + where {object_definition} or {srs_def} is one of the possibilities accepted + by :c:func:`proj_create` + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for references for projected or derived CRSs + e.g. for Projected 3D CRS "UTM zone 31N / WGS 84 (3D)": + "urn:ogc:def:crs,crs:EPSG::4979,cs:PROJ::ENh,coordinateOperation:EPSG::16031" + (*added in 6.2*) + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json (*added in 6.2*) + - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*) + + {object_reference} is a filename preceded by the '@' character. The + file referenced by the {object_reference} must contain a valid + {object_definition}. + +Description +*********** + +:program:`projinfo` is a program that can query information on a geodetic object, +coordinate reference system (CRS) or coordinate operation, when the ``-s`` and ``-t`` +options are specified, and display it under different formats (PROJ string, WKT string +or PROJJSON string). + +It can also be used to query coordinate operations available between two CRS. + +The program is named with some reference to the GDAL :program:`gdalsrsinfo` that offers +partly similar services. + + +The following control parameters can appear in any order: + +.. program:: projinfo + +.. option:: -o formats + + formats is a comma separated combination of: + ``all``, ``default``, ``PROJ``, ``WKT_ALL``, ``WKT2:2015``, ``WKT2:2019``, ``WKT1:GDAL``, ``WKT1:ESRI``, ``PROJJSON``, ``SQL``. + + Except ``all`` and ``default``, other formats can be preceded by ``-`` to disable them. + + .. note:: WKT2_2019 was previously called WKT2_2018. + + .. note:: Before PROJ 6.3.0, WKT1:GDAL was implicitly calling --boundcrs-to-wgs84. + This is no longer the case. + + .. note:: When SQL is specified, :option:`--output-id` must be specified. + +.. option:: -k crs|operation|datum|ensemble|ellipsoid + + When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object + in case there are CRS, coordinate operations or ellipsoids with the same CODE. + The default is crs. + +.. option:: --summary + + When listing coordinate operations available between 2 CRS, return the + result in a summary format, mentioning only the name of the coordinate + operation, its accuracy and its area of use. + + .. note:: only used for coordinate operation computation + +.. option:: -q + + Turn on quiet mode. Quiet mode is only available for queries on single objects, + and only one output format is selected. In that mode, only the PROJ, WKT or PROJJSON + string is displayed, without other introduction output. The output is then + potentially compatible of being piped in other utilities. + +.. option:: --area name_or_code + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest can be specified either + as a name (e.g "Denmark - onshore") or a AUTHORITY:CODE (EPSG:3237) + This option is exclusive of :option:`--bbox`. + + .. note:: only used for coordinate operation computation + +.. option:: --bbox west_long,south_lat,east_long,north_lat + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest is specified as a + bounding box with geographic coordinates, expressed in degrees in a + unspecified geographic CRS. + `west_long` and `east_long` should be in the [-180,180] range, and + `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than + `east_long`, except in the case where the area of interest crosses the antimeridian. + + .. note:: only used for coordinate operation computation + +.. option:: --spatial-test contains|intersects + + Specify how the area of use of coordinate operations found in the database + are compared to the area of use specified explicitly with :option:`--area` or :option:`--bbox`, + or derived implicitly from the area of use of the source and target CRS. + By default, :program:`projinfo` will only keep coordinate operations whose are of use + is strictly within the area of interest (``contains`` strategy). + If using the ``intersects`` strategy, the spatial test is relaxed, and any + coordinate operation whose area of use at least partly intersects the + area of interest is listed. + + .. note:: only used for coordinate operation computation + +.. option:: --crs-extent-use none|both|intersection|smallest + + Specify which area of interest to consider when no explicit one is specified + with :option:`--area` or :option:`--bbox` options. + By default (``smallest`` strategy), the area of + use of the source or target CRS will be looked, and the one that is the + smallest one in terms of area will be used as the area of interest. + If using ``none``, no area of interest is used. + If using ``both``, only coordinate operations that relate (contain or intersect + depending of the :option:`--spatial-test` strategy) to the area of use of both CRS + are selected. + If using ``intersection``, the area of interest is the intersection of the + bounding box of the area of use of the source and target CRS + + .. note:: only used for coordinate operation computation + +.. option:: --grid-check none|discard_missing|sort|known_available + + Specify how the presence or absence of a horizontal or vertical shift grid + required for a coordinate operation affects the results returned when + researching coordinate operations between 2 CRS. + The default strategy is ``sort`` (if :envvar:`PROJ_NETWORK` is not defined). + In that case, all candidate + operations are returned, but the actual availability of the grids is used + to determine the sorting order. That is, if a coordinate operation involves + using a grid that is not available in the PROJ resource directories + (determined by the :envvar:`PROJ_LIB` environment variable, it will be listed in + the bottom of the results. + The ``none`` strategy completely disables the checks of presence of grids and + this returns the results as if all the grids where available. + The ``discard_missing`` strategy discards results that involve grids not + present in the PROJ resource directories. + The ``known_available`` strategy discards results that involve grids not + present in the PROJ resource directories and that are not known of the CDN. + This is the default strategy is :envvar:`PROJ_NETWORK` is set to ``ON``. + + .. note:: only used for coordinate operation computation + +.. option:: --pivot-crs always|if_no_direct_transformation|never|{auth:code[,auth:code]*} + + Determine if intermediate (pivot) CRS can be used when researching coordinate + operation between 2 CRS. A typical example is the WGS84 pivot. By default, + :program:`projinfo` will consider any potential pivot if there is no direct transformation + ( ``if_no_direct_transformation``). If using the ``never`` strategy, + only direct transformations between the source and target CRS will be + used. If using the ``always`` strategy, intermediate CRS will be considered + even if there are direct transformations. + It is also possible to restrict the pivot CRS to consider by specifying + one or several CRS by their AUTHORITY:CODE. + + .. note:: only used for coordinate operation computation + +.. option:: --show-superseded + + When enabled, coordinate operations that are superseded by others will be + listed. Note that supersession is not equivalent to deprecation: superseded + operations are still considered valid although they have a better equivalent, + whereas deprecated operations have been determined to be erroneous and are + not considered at all. + + .. note:: only used for coordinate operation computation + +.. option:: --hide-ballpark + + .. versionadded:: 7.1 + + Hides any coordinate operation that is, or contains, a + :term:`Ballpark transformation` + + .. note:: only used for coordinate operation computation + +.. option:: --accuracy {accuracy} + + .. versionadded:: 8.0 + + Sets the minimum desired accuracy for returned coordinate operations. + + .. note:: only used for coordinate operation computation + +.. option:: --allow-ellipsoidal-height-as-vertical-crs + + .. versionadded:: 8.0 + + Allows exporting a geographic or projected 3D CRS as a compound CRS whose + vertical CRS represents the ellipsoidal height. + + .. note:: only used for CRS, and with WKT1:GDAL output format + +.. option:: --boundcrs-to-wgs84 + + When specified, this option researches a coordinate operation from the + base geographic CRS of the single CRS, source or target CRS to the WGS84 + geographic CRS, and if found, wraps those CRS into a BoundCRS object. + This is mostly to be used for early-binding approaches. + +.. option:: --authority name + + Specify the name of the authority into which to restrict looks up for + objects, when specifying an object by name or when coordinate operations are + computed. The default is to allow all authorities. + + When used with SQL output, this restricts the authorities to which intermediate + objects can belong to (the default is EPSG and PROJ). Note that the authority + of the :option:`--output-id` option will also be implicitly added. + +.. option:: --main-db-path path + + Specify the name and path of the database to be used by :program:`projinfo`. + The default is :file:`proj.db` in the PROJ resource directories. + +.. option:: --aux-db-path path + + Specify the name and path of auxiliary databases, that are to be combined + with the main database. Those auxiliary databases must have a table + structure that is identical to the main database, but can be partly filled + and their entries can refer to entries of the main database. + The option may be repeated to specify several auxiliary databases. + +.. option:: --identify + + When used with an object definition, this queries the PROJ database to find + known objects, typically CRS, that are close or identical to the object. + Each candidate object is associated with an approximate likelihood percentage. + This is useful when used with a WKT string that lacks a EPSG identifier, + such as ESRI WKT1. This might also be used with PROJ strings. + For example, `+proj=utm +zone=31 +datum=WGS84 +type=crs` will be identified + with a likelihood of 70% to EPSG:32631 + +.. option:: --dump-db-structure + + .. versionadded:: 8.1 + + Outputs the sequence of SQL statements to create a new empty valid auxiliary + database. This option can be specified as the only switch of the utility. + If also specifying a CRS object and the :option:`--output-id` option, the + definition of the object as SQL statements will be appended. + +.. option:: --list-crs [list-crs-filter] + + .. versionadded:: 8.1 + + Outputs a list (authority name:code and CRS name) of the filtered CRSs from the database. + If no filter is provided all authority names and types of non deprecated CRSs are dumped. + list-crs-filter is a comma separated combination of: allow_deprecated,geodetic,geocentric, + geographic,geographic_2d,geographic_3d,vertical,projected,compound. + Affected by options :option:`--authority`, :option:`--area`, :option:`--bbox` and :option:`--spatial-test` + +.. option:: --3d + + .. versionadded:: 6.3 + + "Promote" the CRS(s) to their 3D version. In the context of researching + available coordinate transformations, explicitly specifying this option is + not necessary, because when one of the source or target CRS has a vertical + component but not the other one, the one that has no vertical component is + automatically promoted to a 3D version, where its vertical axis is the + ellipsoidal height in metres, using the ellipsoid of the base geodetic CRS. + +.. option:: --output-id=AUTH:NAME + + .. versionadded:: 8.1 + + Identifier to assign to the object (for SQL output). + + It is strongly recommended that new objects should not be added in common + registries, such as ``EPSG``, ``ESRI``, ``IAU``, etc. + Users should use a custom authority name instead. If a new object should be + added to the official EPSG registry, users are invited to follow the + procedure explained at https://epsg.org/dataset-change-requests.html. + + Combined with :option:`--dump-db-structure`, users can create + auxiliary databases, instead of directly modifying the main :file:`proj.db` database. + See the :ref:`example how to export to an auxiliary database <projinfo_aux_db_example>`. + + Those auxiliary databases can be specified through + :cpp:func:`proj_context_set_database_path` or the :envvar:`PROJ_AUX_DB` + environment variable. + +.. option:: --c-ify + + For developers only. Modify the string output of the utility so that it + is easy to put those strings in C/C++ code + +.. option:: --single-line + + Output PROJ, WKT or PROJJSON strings on a single line, instead of multiple + indented lines by default. + +.. option:: --searchpaths + + .. versionadded:: 7.0 + + Output the directories into which PROJ resources will be looked for + (if not using C API such as :cpp:func:`proj_context_set_search_paths` + that will override them. + +.. option:: --remote-data + + .. versionadded:: 7.0 + + Display information regarding if :ref:`network` is enabled, and the + related URL. + +Examples +******** + +1. Query the CRS object corresponding to EPSG:4326 + +.. code-block:: console + + projinfo EPSG:4326 + +Output: + +:: + + PROJ.4 string: + +proj=longlat +datum=WGS84 +no_defs +type=crs + + WKT2:2019 string: + GEOGCRS["WGS 84", + DATUM["World Geodetic System 1984", + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["geodetic latitude (Lat)",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["geodetic longitude (Lon)",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]], + USAGE[ + SCOPE["unknown"], + AREA["World"], + BBOX[-90,-180,90,180]], + ID["EPSG",4326]] + + +2. List the coordinate operations between NAD27 (designed with its CRS name) + and NAD83 (designed with its EPSG code 4269) within an area of interest + +.. code-block:: console + + projinfo -s NAD27 -t EPSG:4269 --area "USA - Missouri" + +Output: + +:: + + DERIVED_FROM(EPSG):1241, NAD27 to NAD83 (1), 0.15 m, USA - CONUS including EEZ + + PROJ string: + +proj=pipeline +step +proj=axisswap +order=2,1 +step +proj=unitconvert \ + +xy_in=deg +xy_out=rad +step +proj=hgridshift +grids=conus \ + +step +proj=unitconvert +xy_in=rad +xy_out=deg +step +proj=axisswap +order=2,1 + + WKT2:2019 string: + COORDINATEOPERATION["NAD27 to NAD83 (1)", + SOURCECRS[ + GEOGCRS["NAD27", + DATUM["North American Datum 1927", + ELLIPSOID["Clarke 1866",6378206.4,294.978698213898, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["geodetic latitude (Lat)",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["geodetic longitude (Lon)",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]]]], + TARGETCRS[ + GEOGCRS["NAD83", + DATUM["North American Datum 1983", + ELLIPSOID["GRS 1980",6378137,298.257222101, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["geodetic latitude (Lat)",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["geodetic longitude (Lon)",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]]]], + METHOD["CTABLE2"], + PARAMETERFILE["Latitude and longitude difference file","conus"], + OPERATIONACCURACY[0.15], + USAGE[ + SCOPE["unknown"], + AREA["USA - CONUS including EEZ"], + BBOX[23.81,-129.17,49.38,-65.69]], + ID["DERIVED_FROM(EPSG)",1241]] + +3. Export an object as a PROJJSON string + +.. code-block:: console + + projinfo GDA94 -o PROJJSON -q + +Output: + +.. code-block:: json + + { + "type": "GeographicCRS", + "name": "GDA94", + "datum": { + "type": "GeodeticReferenceFrame", + "name": "Geocentric Datum of Australia 1994", + "ellipsoid": { + "name": "GRS 1980", + "semi_major_axis": 6378137, + "inverse_flattening": 298.257222101 + } + }, + "coordinate_system": { + "subtype": "ellipsoidal", + "axis": [ + { + "name": "Geodetic latitude", + "abbreviation": "Lat", + "direction": "north", + "unit": "degree" + }, + { + "name": "Geodetic longitude", + "abbreviation": "Lon", + "direction": "east", + "unit": "degree" + } + ] + }, + "area": "Australia - GDA", + "bbox": { + "south_latitude": -60.56, + "west_longitude": 93.41, + "north_latitude": -8.47, + "east_longitude": 173.35 + }, + "id": { + "authority": "EPSG", + "code": 4283 + } + } + +.. _projinfo_aux_db_example: + +4. Exporting the SQL statements to insert a new CRS in an auxiliary database. + +.. code-block:: console + + # Get the SQL statements for a custom CRS + projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs +title=my_crs" --output-id HOBU:MY_CRS -o SQL -q > my_crs.sql + cat my_crs.sql + + # Initialize an auxiliary database with the schema of the reference database + echo ".schema" | sqlite3 /path/to/proj.db | sqlite3 aux.db + + # Append the content of the definition of HOBU:MY_CRS + sqlite3 aux.db < my_crs.db + + # Check that everything works OK + projinfo --aux-db-path aux.db HOBU:MY_CRS + +or more simply: + +.. code-block:: console + + # Create an auxiliary database with the definition of a custom CRS. + projinfo "+proj=merc +lat_ts=5 +datum=WGS84 +type=crs +title=my_crs" --output-id HOBU:MY_CRS --dump-db-structure | sqlite3 aux.db + + # Check that everything works OK + projinfo --aux-db-path aux.db HOBU:MY_CRS + +Output: + +.. code-block:: sql + + INSERT INTO geodetic_crs VALUES('HOBU','GEODETIC_CRS_MY_CRS','unknown','','geographic 2D','EPSG','6424','EPSG','6326',NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_GEODETIC_CRS_MY_CRS','geodetic_crs','HOBU','GEODETIC_CRS_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + INSERT INTO conversion VALUES('HOBU','CONVERSION_MY_CRS','unknown','','EPSG','9805','Mercator (variant B)','EPSG','8823','Latitude of 1st standard parallel',5,'EPSG','9122','EPSG','8802','Longitude of natural origin',0,'EPSG','9122','EPSG','8806','False easting',0,'EPSG','9001','EPSG','8807','False northing',0,'EPSG','9001',NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_CONVERSION_MY_CRS','conversion','HOBU','CONVERSION_MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + INSERT INTO projected_crs VALUES('HOBU','MY_CRS','my_crs','','EPSG','4400','HOBU','GEODETIC_CRS_MY_CRS','HOBU','CONVERSION_MY_CRS',NULL,0); + INSERT INTO usage VALUES('HOBU','USAGE_PROJECTED_CRS_MY_CRS','projected_crs','HOBU','MY_CRS','PROJ','EXTENT_UNKNOWN','PROJ','SCOPE_UNKNOWN'); + +:: + + PROJ.4 string: + +proj=merc +lat_ts=5 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs +type=crs + + WKT2:2019 string: + PROJCRS["my_crs", + BASEGEOGCRS["unknown", + ENSEMBLE["World Geodetic System 1984 ensemble", + MEMBER["World Geodetic System 1984 (Transit)"], + MEMBER["World Geodetic System 1984 (G730)"], + MEMBER["World Geodetic System 1984 (G873)"], + MEMBER["World Geodetic System 1984 (G1150)"], + MEMBER["World Geodetic System 1984 (G1674)"], + MEMBER["World Geodetic System 1984 (G1762)"], + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]], + ENSEMBLEACCURACY[2.0]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + ID["HOBU","GEODETIC_CRS_MY_CRS"]], + CONVERSION["unknown", + METHOD["Mercator (variant B)", + ID["EPSG",9805]], + PARAMETER["Latitude of 1st standard parallel",5, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8823]], + PARAMETER["Longitude of natural origin",0, + ANGLEUNIT["degree",0.0174532925199433], + ID["EPSG",8802]], + PARAMETER["False easting",0, + LENGTHUNIT["metre",1], + ID["EPSG",8806]], + PARAMETER["False northing",0, + LENGTHUNIT["metre",1], + ID["EPSG",8807]]], + CS[Cartesian,2], + AXIS["(E)",east, + ORDER[1], + LENGTHUNIT["metre",1]], + AXIS["(N)",north, + ORDER[2], + LENGTHUNIT["metre",1]], + ID["HOBU","MY_CRS"]] + +5. Get the WKT representation of EPSG:25832 in the WKT1:GDAL output format and on a single line + +.. code-block:: console + + projinfo -o WKT1:GDAL --single-line EPSG:25832 + +Output: + +:: + + WKT1:GDAL string: + PROJCS["ETRS89 / UTM zone 32N",GEOGCS["ETRS89",DATUM["European_Terrestrial_Reference_System_1989",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],AUTHORITY["EPSG","6258"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4258"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",9],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","25832"]] + +.. only:: man + + See also + ******** + + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**, **projsync(1)** + + .. include:: common_man.rst diff --git a/_sources/apps/projsync.rst.txt b/_sources/apps/projsync.rst.txt new file mode 100644 index 00000000..7722e52e --- /dev/null +++ b/_sources/apps/projsync.rst.txt @@ -0,0 +1,177 @@ +.. _projsync: + +================================================================================ +projsync +================================================================================ + +.. Index:: projsync + +.. only:: html + + .. versionadded:: 7.0.0 + + Tool for synchronizing PROJ datum and transformation support data. + +Synopsis +******** + + | **projsync** + | [--endpoint URL] + | [--local-geojson-file FILENAME] + | ([--user-writable-directory] | [--system-directory] | [--target-dir DIRNAME]) + | [--bbox west_long,south_lat,east_long,north_lat] + | [--spatial-test contains|intersects] + | [--source-id ID] [--area-of-use NAME] + | [--file NAME] + | [--all] [--exclude-world-coverage] + | [--quiet | --verbose] [--dry-run] [--list-files] + | [--no-version-filtering] + +Description +*********** + +:program:`projsync` is a program that downloads remote resource files +into a local directory. This is an alternative to downloading a proj-data-X.Y.Z +archive file, or using the on-demand :ref:`networking capabilities <network>` of PROJ. + +The following control parameters can appear in any order: + +.. program:: projsync + +.. option:: --endpoint URL + + Defines the URL where to download the master :file:`files.geojson` file and then + the resource files. Defaults to the value set in :ref:`proj-ini` + +.. option:: --local-geojson-file FILENAME + + Defines the filename for the master GeoJSON files that references resources. + Defaults to ``${endpoint}/files.geojson`` + +.. option:: --user-writable-directory + + Specifies that resource files must be downloaded in the + :ref:`user writable directory <user_writable_directory>`. This is the default. + +.. option:: --system-directory + + Specifies that resource files must be downloaded in the + ${installation_prefix}/share/proj directory. The user launching projsync + should make sure it has writing rights in that directory. + +.. option:: --target-dir DIRNAME + + Directory into which resource files must be downloaded. + +.. option:: --bbox west_long,south_lat,east_long,north_lat + + Specify an area of interest to restrict the resources to download. + The area of interest is specified as a + bounding box with geographic coordinates, expressed in degrees in a + unspecified geographic CRS. + `west_long` and `east_long` should be in the [-180,180] range, and + `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than + `east_long`, except in the case where the area of interest crosses the antimeridian. + +.. option:: --spatial-test contains|intersects + + Specify how the extent of the resource files + are compared to the area of use specified explicitly with :option:`--bbox`. + By default, any resource files whose extent intersects the value specified + by :option:`--bbox` will be selected. + If using the ``contains`` strategy, only resource files whose extent is + contained in the value specified by :option:`--bbox` will be selected. + +.. option:: --source-id ID + + Restrict resource files to be downloaded to those whose source_id property + contains the ID value. Specifying ``?`` as ID will list all possible values. + +.. option:: --area-of-use NAME + + Restrict resource files to be downloaded to those whose area_of_use property + contains the NAME value. Specifying ``?`` as NAME will list all possible values. + +.. option:: --file NAME + + Restrict resource files to be downloaded to those whose name property + contains the NAME value. Specifying ``?`` as NAME will list all possible values. + +.. option:: --all + + Ask to download all files. + +.. option:: --exclude-world-coverage + + Exclude files which have world coverage. + +.. option:: -q / --quiet + + Quiet mode + +.. option:: --verbose + + .. versionadded:: 8.1 + + Verbose mode (more than default) + +.. option:: --dry-run + + Simulate the behavior of the tool without downloading resource files. + +.. option:: --list-files + + List file names, with the source_id and area_of_use properties. + +.. option:: --no-version-filtering + + .. versionadded:: 8.1 + + By default, projsync only downloads files that are compatible of + the PROJ_DATA.VERSION metadata of :file:`proj.db`, taking into account the + ``version_added`` and ``version_removed`` properties of entries in :file:`files.geojson`. + When specifying this switch, all files referenced in :file:`files.geojson` + will be candidate (combined with other filters). + + +At least one of :option:`--list-files`, :option:`--file`, :option:`--source-id`, +:option:`--area-of-use`, :option:`--bbox` or :option:`--all` must be specified. + +Options :option:`--file`, :option:`--source-id`, :option:`--area-of-use` and +:option:`--bbox` are combined with a AND logic. + +Examples +******** + +1. Download all resource files + +.. code-block:: console + + projsync --all + +2. Download resource files covering specified point and attributing to an agency + +.. code-block:: console + + projsync --source-id fr_ign --bbox 2,49,2,49 + + +.. only:: man + + See also + ******** + + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)**, **projinfo(1)** + + Bugs + **** + + A list of known bugs can be found at https://github.com/OSGeo/PROJ/issues + where new bug reports can be submitted to. + Bugs specific to resource files should be submitted to + https://github.com/OSGeo/PROJ-data/issues + + Home page + ********* + + https://proj.org/ |