diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/apps/cs2cs.rst | 29 | ||||
| -rw-r--r-- | docs/source/apps/projinfo.rst | 10 | ||||
| -rw-r--r-- | docs/source/development/index.rst | 5 | ||||
| -rw-r--r-- | docs/source/development/reference/deprecated.rst | 270 | ||||
| -rw-r--r-- | docs/source/development/reference/index.rst | 1 |
5 files changed, 39 insertions, 276 deletions
diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index e214a5c0..7fe570d9 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -11,11 +11,15 @@ cs2cs Synopsis ******** - **cs2cs** [**-eEfIlrstvwW** [args]] [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ... + **cs2cs** [**-eEfIlrstvwW** [args]] + [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] + [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ... or - **cs2cs** [**-eEfIlrstvwW** [args]] {source_crs} {target_crs} file ... + **cs2cs** [**-eEfIlrstvwW** [args]] [--area name_or_code] + [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] + {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 @@ -144,6 +148,27 @@ The following control parameters can appear in any order: 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. .. only:: man diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index a07cf709..803c0a65 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -23,6 +23,7 @@ Synopsis | [--grid-check none|discard_missing|sort|known_available] | [--pivot-crs always|if_no_direct_transformation|never|{auth:code[,auth:code]*}] | [--show-superseded] [--hide-ballpark] + | [--allow-ellipsoidal-height-as-vertical-crs] | [--boundcrs-to-wgs84] | [--main-db-path path] [--aux-db-path path]* | [--identify] [--3d] @@ -212,6 +213,15 @@ The following control parameters can appear in any order: .. note:: only used for coordinate operation computation +.. option:: --allow-ellipsoidal-height-as-vertical-crs + + .. versionadded:: 8.0 + + Allow to export 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 diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 85c10c6d..f985279f 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -39,9 +39,8 @@ are maintained in a `separate git repository <https://github.com/OSGeo/proj-datu .. attention:: The ``proj_api.h`` header and the functions related to it is - considered deprecated from version 5.0.0 and onwards. The header will be - removed from PROJ in version 7.0.0 scheduled for release March 1st - 2020. + considered deprecated from version 5.0.0 and onwards. The header has been + removed in version 8.0.0 released March 1st 2021. .. attention:: diff --git a/docs/source/development/reference/deprecated.rst b/docs/source/development/reference/deprecated.rst deleted file mode 100644 index 19f43b41..00000000 --- a/docs/source/development/reference/deprecated.rst +++ /dev/null @@ -1,270 +0,0 @@ -.. _api: - -******************************************************************************** -Deprecated API -******************************************************************************** - -.. contents:: Contents - :depth: 3 - :backlinks: none - -Introduction ------------- - -Procedure ``pj_init()`` selects and initializes a cartographic -projection with its argument control parameters. ``argc`` is the number -of elements in the array of control strings argv that each contain -individual cartographic control keyword assignments (+ proj arguments). -The list must contain at least the proj=projection and Earth’s radius or -elliptical parameters. If the initialization of the projection is -successful a valid address is returned otherwise a NULL value. - -The ``pj_init_plus()`` function operates similarly to ``pj_init()`` but -takes a single string containing the definition, with each parameter -prefixed with a plus sign. For example -``+proj=utm +zone=11 +ellps=WGS84``. - -Once initialization is performed either forward or inverse projections -can be performed with the returned value of ``pj_init()`` used as the -argument proj. The argument structure projUV values u and v contain -respective longitude and latitude or x and y. Latitude and longitude are -in radians. If a projection operation fails, both elements of projUV are -set to ``HUGE_VAL`` (defined in ``math.h``). - -Note: all projections have a forward mode, but some do not have an -inverse projection. If the projection does not have an inverse the -projPJ structure element inv will be ``NULL``. - -The ``pj_transform`` function may be used to transform points between -the two provided coordinate systems. In addition to converting between -cartographic projection coordinates and geographic coordinates, this -function also takes care of datum shifts if possible between the source -and destination coordinate system. Unlike ``pj_fwd()`` and ``pj_inv()`` -it is also allowable for the coordinate system definitions -``(projPJ *)`` to be geographic coordinate systems (defined as -``+proj=latlong``). -The x, y and z arrays contain the input values of the points, and are replaced with the output values. -The function returns zero on success, or the error number (also in ``pj_errno``) -on failure. - -Memory associated with the projection may be freed with ``pj_free()``. - -Example -------- - -The following program reads latitude and longitude values in decimal -degrees, performs Mercator projection with a Clarke 1866 ellipsoid and a -33° latitude of true scale and prints the projected cartesian values in -meters: - -.. code:: - - #include <proj_api.h> - - main(int argc, char **argv) { - projPJ pj_merc, pj_latlong; - double x, y; - - if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) - exit(1); - if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) - exit(1); - while (scanf("%lf %lf", &x, &y) == 2) { - x *= DEG_TO_RAD; - y *= DEG_TO_RAD; - p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL ); - printf("%.2f\t%.2f\n", x, y); - } - exit(0); - } - - -For this program, an input of ``-16 20.25`` would give a result of -``-1495284.21 1920596.79``. - -API Functions -------------- - -pj_transform -============ - -:: - - int pj_transform( projPJ srcdefn, - projPJ dstdefn, - long point_count, - int point_offset, - double *x, - double *y, - double *z ); - - -Transform the x/y/z points from the source coordinate system to the -destination coordinate system. - -``srcdefn``: source (input) coordinate system. - -``dstdefn``: destination (output) coordinate system. - -``point_count``: the number of points to be processed (the size of the -x/y/z arrays). - -``point_offset``: the step size from value to value (measured in -doubles) within the x/y/z arrays - normally 1 for a packed array. May be -used to operate on xyz interleaved point arrays. - -``x``/``y``/``z``: The array of X, Y and Z coordinate values passed as -input, and modified in place for output. The Z may optionally be NULL. - -``return``: The return is zero on success, or a PROJ.4 error code. - -The ``pj_transform()`` function transforms the passed in list of points -from the source coordinate system to the destination coordinate system. -Note that geographic locations need to be passed in radians, not decimal -degrees, and will be returned similarly. The ``z`` array may be passed -as NULL if Z values are not available. - -If there is an overall failure, an error code will be returned from the -function. If individual points fail to transform - for instance due to -being over the horizon - then those x/y/z values will be set to -``HUGE_VAL`` on return. Input values that are ``HUGE_VAL`` will not be -transformed. - - -pj_init_plus -============ - -:: - - projPJ pj_init_plus(const char *definition); - -This function converts a string representation of a coordinate system -definition into a projPJ object suitable for use with other API -functions. On failure the function will return NULL and set pj_errno. -The definition should be of the general form -``+proj=tmerc +lon_0 +datum=WGS84``. Refer to PROJ.4 documentation and -the :ref:`transformation` notes for additional detail. - -Coordinate system objects allocated with ``pj_init_plus()`` should be -deallocated with ``pj_free()``. - - -pj_free -======= - -:: - - void pj_free( projPJ pj ); - -Frees all resources associated with pj. - - -pj_is_latlong -============= - -:: - - int pj_is_latlong( projPJ pj ); - -Returns TRUE if the passed coordinate system is geographic -(``proj=latlong``). - - -pj_is_geocent -============= - -:: - - int pj_is_geocent( projPJ pj );`` - -Returns TRUE if the coordinate system is geocentric (``proj=geocent``). - -pj_get_def -========== - -:: - - char *pj_get_def( projPJ pj, int options);`` - -Returns the PROJ.4 initialization string suitable for use with -``pj_init_plus()`` that would produce this coordinate system, but with -the definition expanded as much as possible (for instance ``+init=`` and -``+datum=`` definitions). - -pj_latlong_from_proj -==================== - -:: - - projPJ pj_latlong_from_proj( projPJ pj_in );`` - -Returns a new coordinate system definition which is the geographic -coordinate (lat/long) system underlying ``pj_in``. - -pj_set_finder -============== - -:: - - void pj_set_finder( const char *(*new_finder)(const char *) );`` - -Install a custom function for finding init and grid shift files. - -pj_set_searchpath -================= - -:: - - void pj_set_searchpath ( int count, const char **path );`` - -Set a list of directories to search for init and grid shift files. - - -pj_deallocate_grids -=================== - -:: - - void pj_deallocate_grids( void );`` - -Frees all resources associated with loaded and cached datum shift grids. - - -pj_strerrno -=========== - -:: - - char *pj_strerrno( int );`` - -Returns the error text associated with the passed in error code. - -pj_get_errno_ref -================ - -:: - - int *pj_get_errno_ref( void );`` - -Returns a pointer to the global pj\_errno error variable. - -pj_get_release -============== - -:: - - const char *pj_get_release( void );`` - -Returns an internal string describing the release version. - -Obsolete Functions -~~~~~~~~~~~~~~~~~~ - -``XY pj_fwd( LP lp, PJ *P );`` - -``LP pj_inv( XY xy, PJ *P );`` - -``projPJ pj_init(int argc, char **argv);`` - -.. _more info: pj_transform - diff --git a/docs/source/development/reference/index.rst b/docs/source/development/reference/index.rst index 1d39b1d0..caa893c3 100644 --- a/docs/source/development/reference/index.rst +++ b/docs/source/development/reference/index.rst @@ -10,4 +10,3 @@ Reference datatypes functions cpp/index.rst - deprecated |