diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/apps/cct.rst | 2 | ||||
| -rw-r--r-- | docs/source/apps/cs2cs.rst | 76 | ||||
| -rw-r--r-- | docs/source/apps/index.rst | 9 | ||||
| -rw-r--r-- | docs/source/apps/proj.rst | 2 | ||||
| -rw-r--r-- | docs/source/apps/projinfo.rst | 311 | ||||
| -rw-r--r-- | docs/source/conf.py | 7 | ||||
| -rw-r--r-- | docs/source/development/reference/datatypes.rst | 7 | ||||
| -rw-r--r-- | docs/source/development/reference/functions.rst | 49 |
8 files changed, 431 insertions, 32 deletions
diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst index 25611597..249d523a 100644 --- a/docs/source/apps/cct.rst +++ b/docs/source/apps/cct.rst @@ -179,7 +179,7 @@ Hence, in honour of *cct* (the geodesist) this is :program:`cct` (the program). See also ******** - **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)** + **proj(1)**, **cs2cs(1)**, **geod(1)**, **gie(1)**, **projinfo(1)** Bugs **** diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index 29ea5b42..8df67d72 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -6,19 +6,35 @@ cs2cs .. only:: html - Cartographic coordinate system filter. + Filter for transformations between two coordinate reference systems. Synopsis ******** **cs2cs** [ **-eEfIlrstvwW** [ args ] ] [ *+opts[=arg]* ] [ +to [*+opts[=arg]*] ] file[s] +or + + **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} +to {target_crs} file[s] + + where {source_crs} or {target_crs} is a PROJ string, a WKT string or a AUTHORITY:CODE + (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS + found in the proj.db database), expressing a coordinate reference system. + +.. versionadded:: 6.0.0 + +or + + **cs2cs** [ **-eEfIlrstvwW** [ args ] ] {source_crs} {target_crs} + +.. versionadded:: 6.0.0 + Description *********** :program:`cs2cs` performs transformation between the source and destination -cartographic coordinate system on a set of input points. The coordinate -system transformation can include translation between projected and +cartographic coordinate 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: @@ -125,22 +141,21 @@ The following control parameters can appear in any order: parameters. Usage varies with projection and for a complete description consult the :ref:`projection pages <projections>`. -The :program:`cs2cs` program requires two coordinate system definitions. The first (or +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 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 :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. +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. + +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 @@ -157,8 +172,11 @@ places), while projected (cartesian) coordinates will be in linear (meter, feet) units. -Example -******* +Examples +******** + +Using PROJ strings +------------------ The following script @@ -179,12 +197,30 @@ The x-y output data will appear as three lines of: 1402285.98 5076292.42 -0.00 + +Using EPSG 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 + .. only:: man See also ******** - **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)** + **proj(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)** Bugs **** diff --git a/docs/source/apps/index.rst b/docs/source/apps/index.rst index 91f5c4ff..8c2c8222 100644 --- a/docs/source/apps/index.rst +++ b/docs/source/apps/index.rst @@ -8,15 +8,18 @@ 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 +for datum transformation. The ``geod`` program provides the ability to do geodesic (great circle) computations. ``gie`` is the program used for -regression tests in PROJ. +regression tests in PROJ. ``cct`` a 4D equivalent to the ``proj`` program, +performs transformation coordinate systems on a set of input points. +``projinfo`` performs queries for geodetic objects and coordinate operations. .. toctree:: :maxdepth: 1 - proj cct cs2cs geod gie + proj + projinfo diff --git a/docs/source/apps/proj.rst b/docs/source/apps/proj.rst index 2928193c..7585411f 100644 --- a/docs/source/apps/proj.rst +++ b/docs/source/apps/proj.rst @@ -218,7 +218,7 @@ data will appear as three lines of:: See also ******** - **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)** + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **projinfo(1)** Bugs **** diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst new file mode 100644 index 00000000..cbfd44d4 --- /dev/null +++ b/docs/source/apps/projinfo.rst @@ -0,0 +1,311 @@ +.. _projinfo: + +================================================================================ +projinfo +================================================================================ + +.. Index:: projinfo + +.. only:: html + + .. versionadded:: 6.0.0 + + Geodetic object and coordinate operation queries + +Synopsis +******** + + | **projinfo** + | [-o formats] [-k crs|operation] [--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] [--show-superseded] + | [--pivot-crs none|{auth:code[,auth:code]*}] + | [--boundcrs-to-wgs84] + | [--main-db-path path] [--aux-db-path path]* + | [--identify] + | [--c-ify] [--single-line] + | {object_definition} | (-s {srs_def} -t {srs_def}) + | + + where {object_definition} or {object_definition} is a PROJ string, a + WKT string, an object name or a AUTHORITY:CODE + (where AUTHORITY is the name of a CRS authority and CODE the code of a CRS + found in the proj.db database). + +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). + +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_2018``, ``WKT1_GDAL``, ``WKT1_ESRI``. + + Except ``all`` and ``default``, other formats can be preceded by ``-`` to disable them. + +.. option:: -k crs|operation + + When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object + in case there are CRS or coordinate operations 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, mentionning 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 or WKT + 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 specfied explicitly with :option:`--area` or :option:`--bbox`, + or derivedi implictly from the area of use of the source and target CRS. + By default, 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 + + 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``: 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. + + .. 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:: --pivot-crs none|{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, + projinfo will consider any potential pivot. If using the ``none`` strategy, + only direct transformations between the source and target CRS will be + used. 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:: --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:: --main-db-path path + + Specify the name and path of the database to be used by projinfo. The + default is 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:: --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 WKT strings on a single line, instead of multiple intended lines by + default. + +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_2018 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_2018 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]] + +.. only:: man + + See also + ******** + + **cs2cs(1)**, **cct(1)**, **geod(1)**, **gie(1)**, **proj(1)** + + Bugs + **** + + A list of know bugs can be found at https://github.com/OSGeo/proj.4/issues + where new bug reports can be submitted to. + + Home page + ********* + + https://proj4.org/ diff --git a/docs/source/conf.py b/docs/source/conf.py index 612c7c7e..0fd8d540 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -319,6 +319,13 @@ man_pages = [ ['Thomas Knudsen'], 1 ), + ( + 'apps/projinfo', + 'projinfo', + u'Geodetic object and coordinate operation queries', + ['Even Rouault'], + 1 + ), ] # If true, show URL addresses after external links. diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 25e7ffd2..18bd7efd 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -60,11 +60,12 @@ Transformation objects .. c:type:: PJ_AREA + .. versionadded:: 6.0.0 + Opaque object describing an area in which a transformation is performed. - .. note:: This object is not fully implemented yet. It is to be used with - :c:func:`proj_create_crs_to_crs` to select the best transformation - between the two input coordinate reference systems. + It is used with :c:func:`proj_create_crs_to_crs` to select the best transformation + between the two input coordinate reference systems. 2 dimensional coordinates -------------------------------------------------------------------------------- diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index aa548664..87271117 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -127,10 +127,10 @@ paragraph for more details. The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. :param PJ_CONTEXT* ctx: Threading context. - :param `srid_from`: Source SRID. - :type `srid_from`: const char* - :param `srid_to`: Destination SRID. - :type `srid_to`: const char* + :param `source_crs`: Source CRS. + :type `source_crs`: const char* + :param `target_crs`: Destination SRS. + :type `target_crs`: const char* :param `area`: Descriptor of the desired area for the transformation. :type `area`: PJ_AREA :returns: :c:type:`PJ*` @@ -142,6 +142,45 @@ paragraph for more details. :param PJ* P: :returns: :c:type:`PJ*` +Area of interest +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. versionadded:: 6.0.0 + + +.. c:function:: PJ_AREA* proj_area_create(void) + + Create an area of use. + + Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to + specify the area of use for the choice of relevant coordinate operations. + + :returns: :c:type:`PJ_AREA*` to be deallocated with :c:func:`proj_area_destroy` + + +.. c:function:: void proj_area_set_bbox(PJ_AREA *area, double west_lon_degree, double south_lat_degree, double east_lon_degree, double north_lat_degree) + + Set the bounding box of the area of use + + Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to + specify the area of use for the choice of relevant coordinate operations. + + In the case of an area of use crossing the antimeridian (longitude +/- 180 degrees), + `west_lon_degree` will be greater than `east_lon_degree`. + + :param `area`: Pointer to an object returned by :c:func:`proj_area_create`. + :param `west_lon_degree`: West longitude, in degrees. In [-180,180] range. + :param `south_lat_degree`: South latitude, in degrees. In [-90,90] range. + :param `east_lon_degree`: East longitude, in degrees. In [-180,180] range. + :param `north_lat_degree`: North latitude, in degrees. In [-90,90] range. + +.. c:function:: void proj_area_destroy(PJ_AREA* area) + + Deallocate a :c:type:`PJ_AREA` object. + + :param PJ_AREA* area + + .. _coord_trans_functions: Coordinate transformation @@ -604,6 +643,8 @@ Various C API for ISO-19111 functionality +++++++++++++++++++++++++++++++++ +.. versionadded:: 6.0.0 + The PJ* objects returned by :c:func:`proj_create_from_wkt`, :c:func:`proj_create_from_database` and other functions in that section will have generally minimal interaction with the functions declared in the |