From 7ea472f54849f3230d5865884ef75c4edcda3fa8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 28 Aug 2017 08:07:48 +0200 Subject: Major restructure and rewrite of docs. A section on "Using PROJ.4" has been introduced giving a introduction on how to use PROJ.4. The Parameters section has been removed and the content reworked into other sections. Additionally the order of chapters has been changed to provide a more complete and readable experience for users of the documentation. --- docs/source/development/api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/source/development') diff --git a/docs/source/development/api.rst b/docs/source/development/api.rst index 5b915edf..356f32b5 100644 --- a/docs/source/development/api.rst +++ b/docs/source/development/api.rst @@ -143,7 +143,7 @@ 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:`parameters` notes for additional detail. +the :ref:`transformation` notes for additional detail. Coordinate system objects allocated with ``pj_init_plus()`` should be deallocated with ``pj_free()``. -- cgit v1.2.3 From c0aaf4c5f489b43ce5a9d0a3cc325e853d04585a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 3 Sep 2017 18:30:02 +0200 Subject: Use same spelling of PROJ.4 across all doc pages. --- docs/source/development/bindings.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/bindings.rst b/docs/source/development/bindings.rst index a1c2a9e0..80babcb2 100644 --- a/docs/source/development/bindings.rst +++ b/docs/source/development/bindings.rst @@ -4,37 +4,37 @@ Language bindings ******************************************************************************** -Proj.4 bindings are available for a number of different development platforms. +PROJ.4 bindings are available for a number of different development platforms. Python ====== `pyproj `_: -Python interface (wrapper for proj.4) +Python interface (wrapper for PROJ.4) Ruby ======= `proj4rb `_: -Bindings for proj.4 in ruby +Bindings for PROJ.4 in ruby TCL ======== `proj4tcl `_: -Bindings for proj.4 in tcl (critcl source) +Bindings for PROJ.4 in tcl (critcl source) MySQL ===== `fProj4 `_: -Bindings for proj.4 in MySQL +Bindings for PROJ.4 in MySQL Excel ======== `proj.xll `_: -Excel add-in for proj.4 map projections +Excel add-in for PROJ.4 map projections Visual Basic ================== -- cgit v1.2.3 From 5dc4fb39db01bf06945b063116c10af7661a7999 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 4 Sep 2017 22:32:20 +0200 Subject: Added more pages to 'development' chapter. Moved old API description to section named 'deprecated'. Created a quickstart page for the development chapter. Scaffolding in place for the rest of the chapter. --- docs/source/development/api.rst | 270 ----------------------- docs/source/development/errorhandling.rst | 7 + docs/source/development/index.rst | 7 +- docs/source/development/quickstart.rst | 100 +++++++++ docs/source/development/reference/datatypes.rst | 8 + docs/source/development/reference/deprecated.rst | 270 +++++++++++++++++++++++ docs/source/development/reference/functions.rst | 7 + docs/source/development/reference/index.rst | 12 + docs/source/development/threads.rst | 5 - docs/source/development/transformations.rst | 7 + 10 files changed, 416 insertions(+), 277 deletions(-) delete mode 100644 docs/source/development/api.rst create mode 100644 docs/source/development/errorhandling.rst create mode 100644 docs/source/development/quickstart.rst create mode 100644 docs/source/development/reference/datatypes.rst create mode 100644 docs/source/development/reference/deprecated.rst create mode 100644 docs/source/development/reference/functions.rst create mode 100644 docs/source/development/reference/index.rst create mode 100644 docs/source/development/transformations.rst (limited to 'docs/source/development') diff --git a/docs/source/development/api.rst b/docs/source/development/api.rst deleted file mode 100644 index 356f32b5..00000000 --- a/docs/source/development/api.rst +++ /dev/null @@ -1,270 +0,0 @@ -.. _api: - -******************************************************************************** -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 -degress, 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 - - 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/errorhandling.rst b/docs/source/development/errorhandling.rst new file mode 100644 index 00000000..58199e3f --- /dev/null +++ b/docs/source/development/errorhandling.rst @@ -0,0 +1,7 @@ +.. _errorhandling: + +================================================================================ +Error handling +================================================================================ + + diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 2e6e5622..9f5c8d89 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -5,13 +5,16 @@ Development ================================================================================ These pages are primarily focused towards developers either contributing to the -proj.4 project or using the library in their own software. +PROJ.4 project or using the library in their own software. .. toctree:: :maxdepth: 1 - api + quickstart + transformations + errorhandling threads + reference/index bindings diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst new file mode 100644 index 00000000..7137d85a --- /dev/null +++ b/docs/source/development/quickstart.rst @@ -0,0 +1,100 @@ +.. _dev_quickstart: + +================================================================================ +Quick start +================================================================================ + +This is a short introduction to the PROJ.4 API. In the following section we +create a simple program that transforms a geodetic coordinate to UTM and back +again. The program is explained a few lines at a time. The complete program can +be seen at the end of the section. + +See the following sections for more in-depth descriptions of different parts of +the PROJ.4 API or consult the :doc:`API reference ` for specifics. + +Before the PROJ.4 API can be used it is necessary to include the ``proj.h`` header +file. Here ``stdio.h`` is also included so we can print some text to the screen: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 39-40 + +Let's declare a few variables that'll be used later in the program. Each variable +will be discussed below. +See the :doc:`reference for more info on data types `. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 43-45 + :dedent: 4 + +For use in multi-threaded programs the ``PJ_CONTEXT`` threading-context is used. +In this particular example it is not needed, but for the sake of completeness +it created here. The section on :doc:`threads ` discusses +this in detail. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 48 + :dedent: 4 + +Next we create the ``PJ`` transformation object ``P`` with the function +``proj_create``. ``proj_create`` takes the threading context ``C`` created above, +and a proj-string that defines the desired transformation. Here we transform +from geodetic coordinate to UTM zone 32N. +It is recommended to create one threading-context per thread used by the program. +This ensures that all ``PJ`` objects created in the same context will be sharing +resources such as error-numbers and loaded grids. +In case the creation of the ``PJ`` object fails an error message is displayed and +the program returns. See :doc:`errorhandling` for further +details. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 50-52 + :dedent: 4 + +PROJ.4 uses it's own data structures for handling coordinates. Here we use a +``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note +that the input values are converted to radians with ``proj_torad``. This is +necessary since PROJ.4 is using radians internally. See :doc:`transformations` +for further details. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 56 + :dedent: 4 + +The coordinate defined above is transformed with ``proj_trans_coord``. For this +a ``PJ`` object, a transformation direction (either forward or inverse) and the +coordinate is needed. The transformed coordinate is returned in ``b``. +Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 59-60 + :dedent: 4 + +The inverse transformation (UTM to geodetic) is done similar to above, +this time using ``PJ_INV`` as the direction. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 61-62 + :dedent: 4 + +Before ending the program the allocated memory needs to be released again: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 65-66 + :dedent: 4 + + +A complete compilable version of the above can be seen here: + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :linenos: + :lines: 39- + diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst new file mode 100644 index 00000000..193ec238 --- /dev/null +++ b/docs/source/development/reference/datatypes.rst @@ -0,0 +1,8 @@ +.. _datatypes: + +================================================================================ +Data types +================================================================================ + + + diff --git a/docs/source/development/reference/deprecated.rst b/docs/source/development/reference/deprecated.rst new file mode 100644 index 00000000..c748d461 --- /dev/null +++ b/docs/source/development/reference/deprecated.rst @@ -0,0 +1,270 @@ +.. _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 +degress, 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 + + 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/functions.rst b/docs/source/development/reference/functions.rst new file mode 100644 index 00000000..3ceffb5b --- /dev/null +++ b/docs/source/development/reference/functions.rst @@ -0,0 +1,7 @@ +.. _functions: + +================================================================================ +Functions +================================================================================ + + diff --git a/docs/source/development/reference/index.rst b/docs/source/development/reference/index.rst new file mode 100644 index 00000000..9e92384c --- /dev/null +++ b/docs/source/development/reference/index.rst @@ -0,0 +1,12 @@ +.. _reference: + +================================================================================ +Reference +================================================================================ + +.. toctree:: + :maxdepth: 1 + + datatypes + functions + deprecated diff --git a/docs/source/development/threads.rst b/docs/source/development/threads.rst index 33072408..a557fa07 100644 --- a/docs/source/development/threads.rst +++ b/docs/source/development/threads.rst @@ -4,11 +4,6 @@ Threads ================================================================================ -.. contents:: Contents - :depth: 3 - :backlinks: none - - This page is about efforts to make PROJ.4 thread safe. Key Thread Safety Issues diff --git a/docs/source/development/transformations.rst b/docs/source/development/transformations.rst new file mode 100644 index 00000000..b03ce368 --- /dev/null +++ b/docs/source/development/transformations.rst @@ -0,0 +1,7 @@ +.. _dev_transformations: + +================================================================================ +Transformations +================================================================================ + + -- cgit v1.2.3 From 3cb1c28f116283e7ab3cde15ebe119a3bb96564a Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 5 Sep 2017 22:21:18 +0200 Subject: Added data types reference section. --- docs/source/development/reference/datatypes.rst | 883 ++++++++++++++++++++++++ 1 file changed, 883 insertions(+) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 193ec238..991fcfc5 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -4,5 +4,888 @@ Data types ================================================================================ +This section describe the multiplude of data types in use in PROJ.4. As a rule +of thumb PROJ.4 data types are prefixed with ``PJ_``, or in one particular case, +is simply called :c:type:`PJ`. A few notable exceptions can be traced +back to the very early days of PROJ.4 when the ``PJ_`` prefix was not +consistenly used. +Transformation objects +-------------------------------------------------------------------------------- +.. c:type:: PJ + + Object containing everything related to a given projection or transformation. + As a user of the PROJ.4 library your are only exposed to pointers to this + object and the contents are hidden in the public API. :c:type:`PJ` objects + are created with :c:func:`proj_create` and destroyed with + :c:func:`proj_destroy`. + +.. c:type:: PJ_CONTEXT + + Context objects enables safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` + object is connected to a context (if not specified, the default context is + used). All operations within a context should be performed in the same thread. + :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` + and destroyed with :c:func:`proj_context_destroy`. + +2 dimensional coordinates +-------------------------------------------------------------------------------- + +Various 2-dimensional coordinate data types. + +.. c:type:: LP + + Geodetic coordinate, latitude and longitude. Usually in radians. + + .. code-block:: C + + typedef struct { double lam, phi; } LP; + + .. c:member:: double LP.lam + + Longitude. Lambda. + + .. c:member:: double LP.phi + + Latitude. Phi. + + +.. c:type:: XY + + 2-dimensional cartesian coordinate. + + .. code-block:: C + + typedef struct { double x, y; } XY; + + + .. c:member:: double XY.lam + + Easting. + + .. c:member:: double XY.phi + + Northing. + + +.. c:type:: UV + + 2-dimensional generic coordinate. Usually used when contents can be either + a :c:type:`XY` or :c:type:`UV`. + + .. code-block:: C + + typedef struct {double u, v; } UV; + + + .. c:member:: double UV.u + + Longitude or easting, depending on use. + + .. c:member:: double UV.v + + Latitude or northing, depending on use. + + +.. c:type:: PJ_EN + + Generic easting/northing coordinate. + + .. code-block:: C + + typedef struct { double e, n; } PJ_EN; + + .. c:member:: double PJ_EN.e + + Easting + + .. c:member:: double PJ_EN.n + + Northing + +3 dimensional coordinates +-------------------------------------------------------------------------------- + +The following data types are the 3-dimensional equivalents to the data +types above. + +.. c:type:: LPZ + + 3-dimensional version of :c:type:`LP`. Holds longitude, latitude and + vertical component. + + .. code-block:: C + + typedef struct { double lam, phi, z; } LPZ; + + .. c:member:: double LPZ.lam + + Longitude. Lambda. + + .. c:member:: double LPZ.phi + + Latitude. Phi. + + .. c:member:: double LPZ.z + + Vertical component. + + +.. c:type:: XYZ + + Cartesian coordinate in 3 dimensions. Extension of :c:type:`XY`. + + .. code-block:: C + + typedef struct { double x, y, z; } XYZ; + + .. c:member:: double XYZ.x + + Easting. + + .. c:member:: double XYZ.y + + Northing. + + .. c:member:: double XYZ.z + + Vertical component. + + +.. c:type:: UVW + + 3-dimensional extension of :c:type:`UV`. + + .. code-block:: C + + typedef struct {double u, v, w; } UVW; + + .. c:member:: double UVW.u + + Longitude or easting, depending on use. + + .. c:member:: double UVW.v + + Latitude or northing, depending on use. + + .. c:member:: double UVW.w + + Vertical component. + + +.. c:type:: PJ_ENH + + Easting, northing and height. + + .. code-block:: C + + typedef struct {double e, n, h; } PJ_ENH; + + .. c:member:: double PJ_ENH.e + + Easting + + .. c:member:: double PJ_ENH.n + + Northing + + .. c:member:: double PJ_ENH.h + + Height + + +Spatiotemporal coordinate types +-------------------------------------------------------------------------------- + +The following data types are extensions of the triplets above into the time +domain. + + +.. c:type:: PJ_LPZT + + Spatiotemporal version of :c:type:`LPZ`. + + .. code-block:: C + + typedef struct { + double lam; + double phi; + double z; + double t; + } PJ_LPZT; + + + .. c:member:: double PJ_LPZT.lam + + Longitude. + + .. c:member:: double PJ_LPZT.phi + + Latitude + + .. c:member:: double PJ_LPZT.z + + Vertical component. + + .. c:member:: double PJ_LPZT.t + + Time component. + +.. c:type:: PJ_XYZT + + Generic spatiotemporal coordinate. Usefull for e.g. cartesian coordinates with + an attached time-stamp. + + .. code-block:: C + + typedef struct { + double x; + double y; + double z; + double t; + } PJ_XYZT; + + + .. c:member:: double PJ_XYZT.x + + Easting. + + .. c:member:: double PJ_XYZT.y + + Northing. + + .. c:member:: double PJ_XYZT.z + + Vertical component. + + .. c:member:: double PJ_XYZT.t + + Time component. + + +.. c:type:: PJ_UVWT + + Spatiotemporal version of :c:type:`PJ_UVW`. + + .. code-block:: C + + typedef struct { double u, v, w, t; } PJ_UVWT; + + .. c:member:: double PJ_UVWT.e + + First horizontal component. + + .. c:member:: double PJ_UVWT.n + + Second horizontal component. + + .. c:member:: double PJ_UVWT.w + + Vertical component. + + .. c:member:: double PJ_UVWT.t + + Temporal component. + + + +.. c:type:: PJ_ENHT + + Spatiotemporal version of :c:type:`PJ_ENH`. + + .. code-block:: C + + typedef struct {double e, n, h, t; } PJ_ENHT; + + .. c:member:: double PJ_ENHT.e + + Easting + + .. c:member:: double PJ_ENHT.n + + Northing + + .. c:member:: double PJ_ENHT.h + + Height + + .. c:member:: double PJ_ENHT.t + +Ancillary types for geodetic computations +-------------------------------------------------------------------------------- + + +.. c:type:: PJ_OPK + + Rotations, for instance three euler angles. + + .. code-block:: C + + typedef struct { double o, p, k; } PJ_OPK; + + .. c:member:: double PJ_OPK.o + + First rotation angle, omega. + + .. c:member:: double PJ_OPK.p + + Second rotation angle, phi. + + .. c:member:: double PJ_OPK.k + + Third rotation angle, kappa. + + +.. c:type:: PJ_DMS + + Describe a longitude or latitude by degrees, minutes and seconds. + + .. code-block:: C + + typedef struct { double d, m, s; } PJ_DMS; + + .. c:member:: double PJ_DMS.d + + Degrees. + + .. c:member:: double PJ_DMS.m + + Minutes + + .. c:member:: double PJ_DMS.s + + Seconds. + + +.. c:type:: PJ_EZN + + Geoid undulation and deflections of the vertical. + + .. code-block:: C + + typedef struct { double e, z, N; } PJ_EZN; + + .. c:member:: double PJ_EZN.e + + Deflection of the vertical, eta. + + .. c:member:: double PJ_EZN.z + + Deflection of the vertical, zeta + + .. c:member:: double PJ_EZN.N + + Geoid undulation. + + +.. c:type:: PJ_AF + + Ellipsoidal parameters. + + .. code-block:: C + + typedef struct {double a, f; } PJ_AF; + + .. c:member:: double PJ_AF.a + + Major axis of ellipsoid. + + .. c:member:: double PJ_AF.f + + Flattening of ellipsoid. + + +Complex coordinate types +-------------------------------------------------------------------------------- + +.. c:type:: PJ_PAIR + + .. code-block:: C + + typedef union { + XY xy; + LP lp; + UV uv; + PJ_AF af; + PJ_EN en; + double v[2]; + } PJ_PAIR; + + .. c:member:: XY PJ_PAIR.xy + + Coordinate in projected space. + + .. c:member:: LP PJ_PAIR.lp + + Coordinate in lat/long space. + + .. c:member:: UV PJ_PAIR.uv + + Coordinate either in lat/lon or projected space. + + .. c:member:: PJ_AF PJ_PAIR.af; + + Ellipsoidal parameters. + + .. c:member:: PJ_EN PJ_PAIR.en + + Easting/Northing pair. + + .. c:member:: double PJ_PAIR.v[2] + + Generic 2D-vector. + +.. c:type:: PJ_TRIPLET + + Union type that groups all coordinate data types of two and tree dimensions. + + .. code-block:: C + + typedef union { + PJ_OPK opk; + PJ_ENH enh; + PJ_EZN ezn; + PJ_DMS dms; + double v[3]; + XYZ xyz; + LPZ lpz; + UVW uvw; + XY xy; + LP lp; + UV uv; + PJ_AF af; + } PJ_TRIPLET; + + .. c:member:: PJ_OPK PJ_TRIPLET.opk + + Rotations. + + .. c:member:: PJ_ENH PJ_TRIPLET.enh + + Easting, northing and height. + + .. c:member:: PJ_EZN PJ_TRIPLET.ezn + + Geoid undulation and deflections of the vertical. + + .. c:member:: PJ_DMS PJ_TRIPLET.dsm + + Degrees, minutes and seconds. + + .. c:member:: double PJ_TRIPLET.v[3] + + Generic 3-dimensional vector. + + .. c:member:: XYZ PJ_TRIPLET.xyz + + Coordinates in projected space. + + .. c:member:: LPZ PJ_TRIPLET.lpz + + Geodetic coordinates, including height. + + .. c:member:: UVW PJ_TRIPLET.uvw + + Either geodetic or projected coordinates. + + .. c:member:: XY PJ_TRIPLET.xy + + Horizontal coordinates in projected space. + + .. c:member:: LP PJ_TRIPLET.lp + + Geodetic coordinates. + + .. c:member:: UV PJ_TRIPLET.uv + + Geodetic or projected coordinate. + + .. c:member:: PJ_AF PJ_TRIPLET.af + + Ellipsoidal paramaters. + +.. c:type:: PJ_COORD + + General purpose coordinate union type usefull in two, three and four dimensions. + + .. code-block:: C + + typedef union { + PJ_XYZT xyzt; + PJ_UVWT uvwt; + PJ_ENHT enht; + PJ_LPZT lpzt; + PJ_ENH enh; + PJ_EN en; + double v[4]; + XYZ xyz; + UVW uvw; + LPZ lpz; + XY xy; + UV uv; + LP lp; + } PJ_COORD ; + + .. c:member:: PJ_XYZT PJ_COORD.xyzt + + Spatiotemporal cartesian coordinate. + + .. c:member:: PJ_UVWT PJ_COORD.uvwt + + Spatiotemporal generic coordinate. + + .. c:member:: PJ_ENHT PJ_COORD.enht + + Easting, northing, height and time. + + .. c:member:: PJ_LPZT PJ_COORD.lpzt + + Longitude, latitude, vertical and time components. + + .. c:member:: PJ_ENH PJ_COORD.enh + + Easting, northing and height + + .. c:member:: PJ_EN PJCOORD.en + + Easting and northing. + + .. c:member:: double v[4] + + Generic four-dimensional vector. + + .. c:member:: XYZ PJ_COORD.xyz + + 3-dimensional cartesian coordinate. + + .. c:member:: UVW PJ_COORD.uvw + + 3-dimensional generic coordinate. + + .. c:member:: LPZ PJ_COORD.lpz + + Longitude, latitude and vertical component. + + .. c:member:: XY PJ_COORD.xy + + 2-dimensional cartesian coordinate. + + .. c:member:: UV PJ_COORD.uv + + 2-dimensional generic coordinate. + + .. c:member:: LP PJ_COORD.lp + + Longitude and latitude. + + +.. c:type:: PJ_OBS + + Geodetic observation data type. + + .. code-block:: C + + typedef struct { + PJ_COORD coo; + PJ_TRIPLET anc; + int id; + unsigned int flags; + } PJ_OBS; + + .. c:member:: PJ_COORD PJ_OBS.coo + + Coordinate data + + .. c:member:: PJ_TRIPLET PJ_OBS.anc + + Ancillary data + + .. c:member:: int PJ_OBS.id + + Integer ancillary data, e.g. observation number, EPSG code, etc. + + .. c:member:: unsigned int PJ_OBS.flags + + Additional data intended for flags. + + +Projection derivatives +------------------------------------------------------------------------------- + +.. c:type:: PJ_DERIVS + + Partial derivatives of geodetic coordinate :math:`\left(\lambda,\phi\right)`. + Calculated with :c:func:`proj_derivatives`. + + .. code-block:: C + + typedef struct { + double x_l, x_p; + double y_l, y_p; + } PJ_DERIVS; + + .. c:member:: double PJ_DERIVS.x_l + + :math:`\frac{\partial x}{\partial \lambda}` + + .. c:member:: double PJ_DERIVS.x_p + + :math:`\frac{\partial x}{\partial \phi}` + + .. c:member:: double PJ_DERIVS.y_l + + :math:`\frac{\partial y}{\partial \lambda}` + + .. c:member:: double PJ_DERIVS.y_p + + :math:`\frac{\partial y}{\partial \phi}` + + +.. c:type:: PJ_FACTORS + + Various cartographic properties, such as scale factors, angular distortion + and meridian convergence. Calculated with :c:func:`proj_factors`. Depending + on the underlying projection, values can be calculated either numerically + or analytically. + + .. code-block:: C + + typedef struct { + struct PJ_DERIVS der; + double h, k; + double omega, thetap; + double conv; + double s; + double a, b; + int code; + } PJ_FACTORS; + + .. c:member:: PJ_DERIVS PJ_FACTORS.der + + Partial derivatives of coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.h + + Meridian scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.k + + Parallel scale at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.omega + + Angular distortion at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.thetap + + Meridian/parallel angle, :math:`\theta^\prime`, at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.conv + + Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. + Sometimes also described as *grid declination*. + + .. c:member:: double PJ_FACTORS.s + + Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.a + + Maximum scale error. + + .. c:member:: double PJ_FACTORS.b + + Minimum scale error. + + .. c:member:: int code + + Bitmask determing if calculation of various factors was done numerically + or analytically. If a bit flags is set the calculation was done analytically. + The following bit flags exists: + + .. c:macro:: PJ_IS_ANAL_XL_YL + + Longitude derivatives are calculated analytically + + .. c:macro:: PJ_IS_ANAL_XP_YP + + Latitude derivatives are calculated analyticall. + + .. c:macro:: PJ_IS_ANAL_HK + + Meridinal and parallel scale factors are calculated analytically. + + .. c:macro:: PJ_IS_ANAL_CONV + + Meridian convergence calculated analytically. + + +Info structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_INFO + + Struct holding information about the current instance of PROJ.4. Struct is + populated by :c:func:`proj_info`. + + .. code-block:: C + + typedef struct { + char release[64]; + char version[64]; + int major; + int minor; + int patch; + char searchpath[512]; + } PJ_INFO; + + .. c:member:: char PJ_INFO.release[64] + + Release info. Version number and release date, + e.g. "Rel. 4.9.3, 15 August 2016". + + .. c:member:: char PJ_INFO.version[64] + + Text representation of the full version number, + e.g. "4.9.3". + + .. c:member:: int PJ_INFO.major + + Major version number. + + .. c:member:: int PJ_INFO.minor + + Minor version number. + + .. c:member:: int PJ_INFO.patch + + Patch level of release. + + .. c:member:: char PJ_INFO.searchpath[512] + + Search path for PROJ.4. List of directories separated by + semicolons, e.g. "C:\Users\doctorwho;C:\OSGeo4W64\\share\proj". + Grids and init files are looked for in directories in the search path. + +.. c:type:: PJ_PROJ_INFO + + Struct holding information about a :c:type:`PJ` object. Populated by + :c:func:`proj_pj_info`. + + .. code-block:: C + + typedef struct { + char id[16]; + char description[128]; + char definition[512]; + int has_inverse; + } PJ_PROJ_INFO; + + .. c:member:: char PJ_PROJ_INFO.id[16] + + Short ID of the operation the :c:type:`PJ` object is based on, that is, + what comes afther the ``+proj=`` in a proj-string, e.g. "*merc*". + + .. c:member:: char PJ_PROJ_INFO.description[128] + + Long describes of the operation the :c:type:`PJ` object is based on, + e.g. "*Mercator Cyl, Sph&Ell lat_ts=*". + + .. c:member:: char PJ_PROJ_INFO.definition[512] + + The proj-string that was used to create the :c:type:`PJ` object with, + e.g. "*+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84*". + + .. c:member:: int PJ_PROJ_INFO.has_inverse + + 1 if an inverse mapping of the defined operation exists, otherwise 0. + +.. c:type:: PJ_GRID_INFO + + Struct holding information about a specific grid in the search path of + PROJ.4. Populated with the function :c:func:`proj_grid_info`. + + .. code-block:: C + + typedef struct { + char gridname[32]; + char filename[260]; + char format[8]; + LP lowerleft; + LP upperright; + int n_lon, n_lat; + double cs_lon, cs_lat; + } PJ_GRID_INFO; + + .. c:member:: char PJ_GRID_INFO.gridname[32] + + Name of grid, e.g. "*BETA2007.gsb*". + + .. c:member:: char PJ_GRID_INFO + + Full path of grid file, e.g. "*C:\OSGeo4W64\\share\proj\BETA2007.gsb*" + + .. c:member:: char PJ_GRID_INFO.format[8] + + File format of grid file, e.g. "*ntv2*" + + .. c:member:: LP PJ_GRID_INFO.lowerleft + + Geodetic coordinate of lower left corner of grid. + + .. c:member:: LP PJ_GRID_INFO.upperright + + Geodetic coordinate of upper right corner of grid. + + .. c:member:: int PJ_GRID_INFO.n_lon + + Number of grid cells in the longitudinal direction. + + .. c:member:: int PJ_GRID_INFO.n_lat + + Number of grid cells in the latitudianl direction. + + .. c:member:: double PJ_GRID_INFO.cs_lon + + Cell size in the longitudinal direction. In radians. + + .. c:member:: double PJ_GRID_INFO.cs_lat + + Cell size in the latitudinal direction. In radians. + + +.. c:type:: PJ_INIT_INFO + + Struct holding information about a specific init file in the search path of + PROJ.4. Populated with the function :c:func:`proj_init_info`. + + .. code-block:: C + + typedef struct { + char name[32]; + char filename[260]; + char version[32]; + char origin[32]; + char lastupdate[16]; + } PJ_INIT_INFO; + + .. c:member:: char PJ_INIT_INFO.name[32] + + Name of init file, e.g. "*epsg*". + + .. c:member:: char PJ_INIT_INFO.filename[260] + + Full path of init file, e.g. "*C:\OSGeo4W64\share\proj\epsg*" + + .. c:member:: char PJ_INIT_INFO.version[32] + + Version number of init-file, e.g. "*9.0.0*" + + .. c:member:: char PJ_INIT_INFO.origin[32] + + Originating entity of the init file, e.g. "*EPSG*" + + .. c:member:: char PJ_INIT_INFO.lastupdate + + Date of last update of the init-file. -- cgit v1.2.3 From 1f60b8c407ac202916cf4570683935fcca451531 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 12 Sep 2017 16:42:02 +0200 Subject: Added functions API reference --- docs/source/development/reference/functions.rst | 433 ++++++++++++++++++++++++ 1 file changed, 433 insertions(+) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 3ceffb5b..fc546f33 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -4,4 +4,437 @@ Functions ================================================================================ +Threading contexts +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. c:function:: PJ_CONTEXT* proj_context_create(void) + + Create a new threading-context. + + :returns: :c:type:`PJ_CONTEXT*` + +.. c:function:: void proj_context_destroy(PJ_CONTEXT *ctx) + + Deallacote a threading-context. + + :param PJ_CONTEXT* ctx: Threading context. + +Transformation setup +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition) + + Create a transformation object from a proj-string. + + Example call: + + .. code-block:: C + + PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel"); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context. + :param `definition`: Proj-string of the desired transformation. + :type `definition`: const char* + + +.. c:function:: PJ* proj_create_argv(PJ_CONTEXT *ctx, int argc, char **argv) + + Create transformation object with argc/argv-style initialization. For this + application each parameter in the defining proj-string is an entry in :c:data:`argv`. + + Example call: + + .. code-block:: C + + char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"}; + PJ* P = proj_create_argv(0, 3, args); + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param PJ_CONTEXT* ctx: Threading context + :param int argc: Count of arguments in :c:data:`argv` + :param char** argv: Vector of strings with proj-string parameters, e.g. ``+proj=merc`` + :returns: :c:type:`PJ*` + +.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to) + + Create a transformation object that is a pipeline between two known + coordinate reference systems. + + :c:data:`srid_from` and :c:data:`srid_to` should be the value part of a ``+init=...`` parameter + set, i.e. "epsg:25833" or "IGNF:AMST63". Any projection definition that + can be found in a init-file in :envvar:`PROJ_LIB` is a valid input to this function. + + For now the function mimics the cs2cs app: An input and an output CRS is + given and coordinates are transformed via a hub datum (WGS84). This + transformation strategy is referred to as "early-binding" by the EPSG. The + function can be extended to support "late-binding" transformations in the + future without affecting users of the function. + + Example call: + + .. code-block:: C + + PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833"); + + 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* + :returns: :c:type:`PJ*` + +.. c:function:: PJ* proj_destroy(PJ *P) + + Deallocate a :c:type:`PJ` transformation object. + + :param PJ* P: + :returns: :c:type:`PJ*` + +Coordinate transformation +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_COORD proj_trans_coord(PJ *P, enum proj_direction direction, PJ_COORD coord) + + Transform a single :c:type:`PJ_COORD` coordinate. + + :param PJ* P: + :param `direction`: Transformation direction. + :type `direction`: enum proj_direction + :param PJ_COORD coord: Coordinate that will be transformed. + :returns: :c:type:`PJ_COORD` + + +.. c:function:: PJ_OBS proj_trans_obs(PJ *P, enum proj_direction direction, PJ_OBS obs) + + Transform a single :c:type:`PJ_OBS` observation. + + :param PJ* P: + :param `direction`: Transformation direction. + :type `direction`: enum proj_direction + :param PJ_OBS obs: Observation data to transform. + :returns: :c:type:`PJ_OBS` + + + +.. c:function:: size_t proj_transform(PJ *P, enum proj_direction direction, \ + double *x, size_t sx, size_t nx, double *y, \ + size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ + double *t, size_t st, size_t nt) + + Transform a series of coordinates, where the individual coordinate dimension + may be represented by an array that is either + + 1. fully populated + 2. a null pointer and/or a length of zero, which will be treated as a + fully populated array of zeroes + 3. of length one, i.e. a constant, which will be treated as a fully + populated array of that constant value + + The strides, :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, + represent the step length, in bytes, between + consecutive elements of the corresponding array. This makes it possible for + :c:func:`proj_transform` to handle transformation of a large class of application + specific data structures, without necessarily understanding the data structure + format, as in: + + .. code-block:: C + + typedef struct { + double x, y; + int quality_level; + char surveyor_name[134]; + } XYQS; + + XYQS survey[345]; + double height = 23.45; + size_t stride = sizeof (XYQS); + + ... + + proj_transform ( + P, PJ_INV, sizeof(XYQS), + &(survey[0].x), stride, 345, /* We have 345 eastings */ + &(survey[0].y), stride, 345, /* ...and 345 northings. */ + &height, 1, /* The height is the constant 23.45 m */ + 0, 0 /* and the time is the constant 0.00 s */ + ); + + This is similar to the inner workings of the deprecated pj_transform function, but the + stride functionality has been generalized to work for any size of basic unit, + not just a fixed number of doubles. + + In most cases, the stride will be identical for x, y, z, and t, since they will + typically be either individual arrays (stride = sizeof(double)), or strided + views into an array of application specific data structures (stride = sizeof (...)). + + But in order to support cases where :c:data:`x`, :c:data:`y`, :c:data:`z`, + and :c:data:`t` come from heterogeneous sources, individual strides, + :c:data:`sx`, :c:data:`sy`, :c:data:`sz`, :c:data:`st`, are used. + + .. note:: Since :c:func:`proj_transform` does its work *in place*, this means that even the + supposedly constants (i.e. length 1 arrays) will return from the call in altered + state. Hence, remember to reinitialize between repeated calls. + + :param PJ* P: Transformation object + :param `direction`: Transformation direction + :type `enum proj_direction`: + :param double* x: Array of x-coordinates + :param double* y: Array of y-coordinates + :param double* z: Array of z-coordinates + :param double* t: Array of t-coordinates + :param size_t sx: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nx: Number of elements in the corresponding array + :param size_t sy: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nv: Number of elements in the corresponding array + :param size_t sz: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nz: Number of elements in the corresponding array + :param size_t st: Step lenght, in bytes, between consecutive elements of the corresponding array + :param size_t nt: Number of elements in the corresponding array + :returns: Number of transformations succesfully completed + + + +.. c:function:: size_t proj_transform_coord(PJ *P, enum proj_direction direction, size_t n, PJ_COORD *coord) + + Batch transform an array of :c:type:`PJ_COORD`. + + :param PJ* P: + :param `direction`: Transformation direction + :type `direction`: enum proj_direction + :param size_t n: Number of cordinates in :c:data:`coord` + :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number + +.. c:function:: size_t proj_transform_obs(PJ *P, enum proj_direction direction, size_t n, PJ_OBS *obs) + + Batch transform an array of :c:type:`PJ_OBS`. + + :param PJ* P: + :param `direction`: Transformation direction + :type `direction`: enum proj_direction + :param size_t n: Number of observations in :c:data:`obs` + :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number + + +Initializers +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) + + Initializer for the :c:type:`PJ_COORD` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; + + or + + .. code-block:: C + + PJ_COORD c; + // Assign using the PJ_XYZT struct in the union + c.xyzt.x = 10.0; + c.xyzt.y = 20.0; + c.xyzt.z = 30.0; + c.xyzt.t = 40.0; + + Since :c:type:`PJ_COORD` is a union of structs, the above assignment can + also be expressed in terms of the other types in the union, e.g. + :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. + + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :returns: :c:type:`PJ_COORD` + +.. c:function:: PJ_OBS proj_obs(double x, double y, double z, double t,\ + double o, double p, double k,\ + int id, unsigned int flags) + + Initializer for the :c:type:`PJ_OBS` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_OBS c = {{{1.0, 2.0, 3.0, 4.0}}, {{5.0, 6.0, 7.0}}, 8, 9}; + + or + + .. code-block:: C + + PJ_OBS c; + // Assign using the PJ_COORD part of the struct in the union + o.coo.v[0] = 1.0; + o.coo.v[1] = 2.0; + o.coo.v[2] = 3.0; + o.coo.v[3] = 4.0; + o.anc.v[0] = 5.0; + o.anc.v[1] = 6.0; + o.anc.v[2] = 7.0; + o.id = 8; + o.flags = 9; + + which is a bit too verbose in most practical applications. + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :param double o: 1st component in a :c:type:`PJ_TRIPLET` + :param double p: 2nd component in a :c:type:`PJ_TRIPLET` + :param double k: 3rd component in a :c:type:`PJ_TRIPLET` + :param int id: Ancillary data, e.g. an ID + :param `flags`: Flags + :type `flags`: unsigned int + :returns: :c:type:`PJ_OBS` + +Info functions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_INFO proj_info(void) + + Get information about the current instance of the PROJ.4 library. + + :returns: :c:type:`PJ_INFO` + +.. c:function:: PJ_PROJ_INFO proj_pj_info(const PJ *P) + + Get information about a specific transformation object, :c:data:`P`. + + :param `P`: Transformation object + :type `P`: const PJ* + :returns: :c:type:`PJ_PROJ_INFO` + +.. c:function:: PJ_GRID_INFO proj_grid_info(const char *gridname) + + Get information about a specific grid. + + :param `gridname`: Gridname in the PROJ.4 searchpath + :type `gridname`: const char* + :returns: :c:type:`PJ_GRID_INFO` + +.. c:function:: PJ_INIT_INFO proj_init_info(const char *initname) + + Get information about a specific init file. + + :param `initname`: Init file in the PROJ.4 searchpath + :type `initname`: const char* + :returns: :c:type:`PJ_INIT_INFO` + + +Distances +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_lp_dist(PJ *P, LP a, LP b) + + Calculate geodesic distance between two points in geodetic coordinates. + + :param PJ* P: Transformation object + :param LP a: Coordinate of first point + :param LP b: Coordinate of second point + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xy_dist(XY a, XY, b) + + Calculate 2-dimensional euclidean between two projected coordinates. + + :param XY a: First coordinate + :param XY b: Second coordinate + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xyz_dist(XYZ a, XYZ b) + + Calculate 3-dimensional euclidean between two projected coordinates. + + :param XYZ a: First coordinate + :param XYZ b: Second coordinate + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + + +Various +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_roundtrip(PJ *P, enum proj_direction direction, int n, PJ_OBS obs) + + Measure internal consistency of a given transformation. The function + performs :c:data:`n` round trip transformations starting in either + the forward or reverse :c:data:`direction`. Returns the euclidean + distance of the starting point :c:data:`obs` and the resulting + coordinate after :c:data:`n` iterations back and forth. + + :param PJ* P: + :param `direction`: Starting direction of transformation + :type `direction`: enum proj_direction + :param int n: Number of roundtrip transformations + :param PJ_OBS obs: Input coordinate + :returns: :c:type:`double` Distance between original coordinate and the \ + resulting coordinate after :c:data:`n` transformation iterations. + +.. c:function:: PJ_DERIVS proj_derivatives(const PJ *P, const LP lp) + + Calculate partial derivatives of geodetic coordinates. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `lp`: Geodetic coordinate + :type `lp`: const LP + :returns: :c:type:`PJ_DERIVS` + +.. c:function:: PJ_FACTORS proj_factors(const PJ *P, const LP lp) + + Calculate various cartographic properties, such as scale factors, angular + distortion and meridian convergence. Depending on the underlying projection + values will be calculated either numerically (default) or analytically. + + The function also calculates the partial derivatives of the given + coordinate. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `lp`: Geodetic coordinate + :type `lp`: const LP + :returns: :c:type:`PJ_FACTORS` + +.. c:function:: double proj_torad(double angle_in_degrees) + + Convert degrees to radians. + + :param double angle_in_degrees: Degrees + :returns: :c:type:`double` Radians + +.. c:function:: double proj_todeg(double angle_in_radians) + + Convert radians to degrees + + :param double angle_in_radians: Radians + :returns: :c:type:`double` Degrees + +.. c:function:: double proj_dmstor(const char *is, char **rs) + + Convert string of degrees, minutes and seconds to radians. + Works similarly to the C standard library function :c:func:`strtod`. + + :param `is`: Value to be converted to radians + :type `is`: const char* + :param `rs`: Reference to an already allocated char*, whose value is \ + set by the function to the next character in :c:data:`is` \ + after the numerical value. + +.. c:function:: char *proj_rtodms(char *s, double r, int pos, int neg) + + Convert radians to string representation of degrees, minutes and seconds. + + :param char* s: Buffer that holds the output string + :param double r: Value to convert to dms-representation + :param int pos: Character denoting positive direction, typically `'N'` or `'E'`. + :param int neg: Character denoting negative direction, typically `'S'` or `'W'`. + :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) -- cgit v1.2.3 From 1f546602f1da800199ad298968154f2c71de6daf Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 27 Sep 2017 22:06:29 +0200 Subject: add proj_errno_* functions to API reference --- docs/source/development/reference/functions.rst | 63 +++++++++++++++++++++++++ 1 file changed, 63 insertions(+) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index fc546f33..3b6d4489 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -297,6 +297,69 @@ Initializers :type `flags`: unsigned int :returns: :c:type:`PJ_OBS` +Error reporting +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: int proj_errno(PJ *P) + + Get a reading of the current error-state of :c:data:`P`. An non-zero error + codes indicates an error either with the transformation setup or during a + transformation. + + :param: PJ* P: Transformation object. + + :returns: :c:type:`int` + +.. c:function:: void proj_errno_set(PJ *P, int err) + +Change the error-state of :c:data:`P` to `err`. + + :param PJ* P: Transformation object. + :param int err: Error number. + +.. c:function:: int proj_errno_reset(PJ *P) + + Clears the error number in :c:data:`P`, and bubbles it up to the context. + + Example: + + .. code-block:: C + + void foo (PJ *P) { + int last_errno = proj_errno_reset (P); + + do_something_with_P (P); + + /* failure - keep latest error status */ + if (proj_errno(P)) + return; + /* success - restore previous error status */ + proj_errno_restore (P, last_errno); + return; + } + + :param: PJ* P: Transformation object. + + :returns: :c:type:`int` Returns the previous value of the errno, for convenient reset/restore operations. + +.. c:function:: void proj_errno_restore(PJ *P, int err) + + Reduce some mental impedance in the canonical reset/restore use case: + Basically, :c:func:`proj_errno_restore()` is a synonym for + :c:func:`proj_errno_set()`, but the use cases are very different: + *set* indicate an error to higher level user code, *restore* passes previously + set error indicators in case of no errors at this level. + + Hence, although the inner working is identical, we provide both options, + to avoid some rather confusing real world code. + + See usage example under :c:func:`proj_errno_reset` + + :param PJ* P: Transformation object. + :param int err: Error code. + + + Info functions ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -- cgit v1.2.3 From f8d26297de7f6092e78bcd33876510c7082c3f35 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 9 Oct 2017 21:48:24 +0200 Subject: Add PJ_DIRECTION to API referece [skip ci] --- docs/source/development/reference/datatypes.rst | 29 +++++++++++++++++++++++++ docs/source/development/reference/functions.rst | 27 +++++++++++++---------- 2 files changed, 44 insertions(+), 12 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 991fcfc5..7e314dce 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -21,6 +21,34 @@ Transformation objects are created with :c:func:`proj_create` and destroyed with :c:func:`proj_destroy`. +.. c:type:: PJ_DIRECTION + + Enumeration that is used to convey in which direction a given transformation + should be performed. Used in transformation function call as described in + the section on :ref:`transformation functions `. + + Forward transformations are defined with the :c: + + .. code-block:: C + + typedef enum proj_direction { + PJ_FWD = 1, /* Forward */ + PJ_IDENT = 0, /* Do nothing */ + PJ_INV = -1 /* Inverse */ + } PJ_DIRECTION; + + .. c:member:: PJ_FWD + + Perform transformation in the forward direction. + + .. c:member:: PJ_IDENT + + Identity. Do nothing. + + .. c:member:: PJ_INV + + Perform transformation in the inverse direction. + .. c:type:: PJ_CONTEXT Context objects enables safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` @@ -29,6 +57,7 @@ Transformation objects :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` and destroyed with :c:func:`proj_context_destroy`. + 2 dimensional coordinates -------------------------------------------------------------------------------- diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 3b6d4489..daefce4b 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -95,33 +95,36 @@ Transformation setup :param PJ* P: :returns: :c:type:`PJ*` +.. _coord_trans_functions: + Coordinate transformation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: PJ_COORD proj_trans_coord(PJ *P, enum proj_direction direction, PJ_COORD coord) + +.. c:function:: PJ_COORD proj_trans_coord(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) Transform a single :c:type:`PJ_COORD` coordinate. :param PJ* P: :param `direction`: Transformation direction. - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param PJ_COORD coord: Coordinate that will be transformed. :returns: :c:type:`PJ_COORD` -.. c:function:: PJ_OBS proj_trans_obs(PJ *P, enum proj_direction direction, PJ_OBS obs) +.. c:function:: PJ_OBS proj_trans_obs(PJ *P, PJ_DIRECTION direction, PJ_OBS obs) Transform a single :c:type:`PJ_OBS` observation. :param PJ* P: :param `direction`: Transformation direction. - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param PJ_OBS obs: Observation data to transform. :returns: :c:type:`PJ_OBS` -.. c:function:: size_t proj_transform(PJ *P, enum proj_direction direction, \ +.. c:function:: size_t proj_transform(PJ *P, PJ_DIRECTION direction, \ double *x, size_t sx, size_t nx, double *y, \ size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ double *t, size_t st, size_t nt) @@ -182,7 +185,7 @@ Coordinate transformation :param PJ* P: Transformation object :param `direction`: Transformation direction - :type `enum proj_direction`: + :type `PJ_DIRECTION`: :param double* x: Array of x-coordinates :param double* y: Array of y-coordinates :param double* z: Array of z-coordinates @@ -199,23 +202,23 @@ Coordinate transformation -.. c:function:: size_t proj_transform_coord(PJ *P, enum proj_direction direction, size_t n, PJ_COORD *coord) +.. c:function:: size_t proj_transform_coord(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) Batch transform an array of :c:type:`PJ_COORD`. :param PJ* P: :param `direction`: Transformation direction - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param size_t n: Number of cordinates in :c:data:`coord` :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number -.. c:function:: size_t proj_transform_obs(PJ *P, enum proj_direction direction, size_t n, PJ_OBS *obs) +.. c:function:: size_t proj_transform_obs(PJ *P, PJ_DIRECTION direction, size_t n, PJ_OBS *obs) Batch transform an array of :c:type:`PJ_OBS`. :param PJ* P: :param `direction`: Transformation direction - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param size_t n: Number of observations in :c:data:`obs` :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number @@ -426,7 +429,7 @@ Distances Various ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_roundtrip(PJ *P, enum proj_direction direction, int n, PJ_OBS obs) +.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_OBS obs) Measure internal consistency of a given transformation. The function performs :c:data:`n` round trip transformations starting in either @@ -436,7 +439,7 @@ Various :param PJ* P: :param `direction`: Starting direction of transformation - :type `direction`: enum proj_direction + :type `direction`: PJ_DIRECTION :param int n: Number of roundtrip transformations :param PJ_OBS obs: Input coordinate :returns: :c:type:`double` Distance between original coordinate and the \ -- cgit v1.2.3 From f73ec9d887d9cddf014d33a53bf6f87390004a63 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 9 Oct 2017 22:48:44 +0200 Subject: Add documentation for datatypes and functions related to internal lists in PROJ.4. [skip ci] --- docs/source/development/reference/datatypes.rst | 104 ++++++++++++++++++++++++ docs/source/development/reference/functions.rst | 43 ++++++++++ 2 files changed, 147 insertions(+) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 7e314dce..85cedea6 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -749,6 +749,110 @@ Projection derivatives Meridian convergence calculated analytically. +List structures +------------------------------------------------------------------------------- + +.. c:type:: PJ_OPERATIONS + + Description a PROJ.4 operation + + .. code-block:: C + + struct PJ_OPERATIONS { + char *id; /* operation keyword */ + PJ *(*proj)(PJ *); /* operation entry point */ + char * const *descr; /* description text */ + }; + + .. c:member:: char *id + + Operation keyword. + + .. c:member:: PJ *(*op)(PJ *) + + Operation entry point. + + .. c:member:: char * const * + + Description of operation. + + +.. c:type:: PJ_ELLPS + + Description of ellipsoids defined in PROJ.4 + + .. code-block:: C + + struct PJ_ELLPS { + char *id; + char *major; + char *ell; + char *name; + }; + + .. c:member:: char *id + + Keyword name of the ellipsoid. + + .. c:member:: char *major + + Semi-major axis of the ellipsoid, or radius in case of a sphere. + + .. c:member:: char *ell + + Elliptical parameter, e.g. `rf=298.257` or `b=6356772.2`. + + .. c:member:: char *name + + Name of the ellipsoid + +.. c:type:: PJ_UNITS + + Distance units defined in PROJ.4. + + .. code-block:: C + + struct PJ_UNITS { + char *id; /* units keyword */ + char *to_meter; /* multiply by value to get meters */ + char *name; /* comments */ + double factor; /* to_meter factor in actual numbers */ + }; + + .. c:member:: char *id + + Keyword for the unit. + + .. c:member:: char *to_meter + + Text representation of the factor that converts a given unit to meters + + .. c:member:: char *name + + Name of the unit. + + .. c:member:: double factor + + Conversion factor that converts the unit to meters. + +.. c:type:: PJ_PRIME_MERIDIANS + + Prime meridians defined in PROJ.4. + + .. code-block:: C + + struct PJ_PRIME_MERIDIANS { + char *id; + char *defn; + }; + + .. c:member:: char *id + + Keyword for the prime meridian + + .. c:member:: char *def + + Offset from Greenwich in DMS format. Info structures ------------------------------------------------------------------------------- diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index daefce4b..10af19d4 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -396,6 +396,49 @@ Info functions :type `initname`: const char* :returns: :c:type:`PJ_INIT_INFO` +Lists +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: const PJ_OPERATIONS* proj_list_operations(void) + + Get a pointer to an array of all operations in PROJ.4. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + Print a list of all operations in PROJ.4: + + .. code-block:: C + + PJ_OPERATIONS *ops; + for (ops = proj_list_operations(); ops->id; ++ops) + printf("%s\n", ops->id); + + + :returns: :c:type:`PJ_OPERATIONS*` + +.. c:function:: const PJ_ELLPS* proj_list_ellps(void) + + Get a pointer to an array of ellipsoids defined in PROJ.4. The last entry + of the returned array is a NULL-entry. The array is statically allocated + and does not need to be freed after use. + + :returns: :c:type:`PJ_ELLPS*` + +.. c:function:: const PJ_UNITS* proj_list_units(void) + + Get a pointer to an array of distance units defined in PROJ.4. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + :returns: :c:type:`PJ_UNITS*` + +.. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void) + + Get a pointer to an array of prime meridians defined in PROJ.4. The last + entry of the returned array is a NULL-entry. The array is statically + allocated and does not need to be freed after use. + + :returns: :c:type:`PJ_PRIME_MERIDIANS*` Distances ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -- cgit v1.2.3 From 1f096c9f9cf1ef4c152c53605bf6f6347209b4b5 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Wed, 15 Nov 2017 21:31:51 +0100 Subject: Added a transition guide to aid migration from old to new API --- docs/source/development/index.rst | 1 + docs/source/development/migration.rst | 137 ++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 docs/source/development/migration.rst (limited to 'docs/source/development') diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 9f5c8d89..318e3778 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -17,4 +17,5 @@ PROJ.4 project or using the library in their own software. threads reference/index bindings + migration diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst new file mode 100644 index 00000000..d9014a36 --- /dev/null +++ b/docs/source/development/migration.rst @@ -0,0 +1,137 @@ +.. _API_migration: + +================================================================================ +Version 4 to 5 API Migration +================================================================================ + +This is a transition guide for developers wanting to migrate their code to use +PROJ version 5. + +The difference between the old and new API is best shown with examples. Below +we implement the same program with the two different API's. The program reads +input latitude and longitude from the command line and convert them to +projected coordinates with the Mercator projection. + +We start by writing the progran for PROJ v. 4: + +.. code-block:: C + + #include + + 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")) ) + return 1; + if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) + return 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); + } + + return 0; + } + +The same program implemented using PROJ v. 5: + +.. code-block:: C + + #include + + main(int argc, char **argv) { + PJ *P; + PJ_COORD c; + + P = proj_create(PJ_DEFAULT_CTX, "+proj=merc +ellps=clrk66 +lat_ts=33"); + if (P==0) + return 1; + + while (scanf("%lf %lf", &c.lp.lam, &c.lp.phi) == 2) { + c.lp.lam = proj_todeg(c.lp.lam); + c.lp.phi = proj_todeg(c.lp.phi); + c = proj_trans(P, PJ_FWD, c); + printf("%.2f\t%.2f\n", c.xy.x, c.xy.y); + } + + } + +Looking at the two different programs, there's a few immediate +differences that catches the eye. First off, the included header file describing +the API has changed from ``proj_api.h`` to simply ``proj.h``. All functions in ``proj.h`` +belongs to the ``proj_`` namespace. + +With the new API also comes new datatypes. E.g. the transformation object ``projPJ`` +which has been changed to a pointer of type ``PJ``. This is done to highlight the +actual nature of the object, instead of hiding it away behind a typedef. New data +types for handling coordinates have also been introduced. In the above example we +use the ``PJ_COORD``, which is a union of various types. The benefit of this is that +it is possible to use the various structs in the union to communicate what state +the data is in at different points in the program. For instance as in the above +example where the coordinate is read from STDIN as a geodetic coordinate, +communicated to the reader of the code by using the ``c.lp`` struct. +After it has been projected we print it to STDOUT by accessing the individual +elements in ``c.xy`` to illustrate that the coordinate is now in projected space. +Data types are prefixed with `PJ_`. + +The final, and perhaps biggest, change is that the fundamental concept of +transformations in PROJ are now handled in a single transformation object (``PJ``) +and not by stating the source and destination systems as previously. It is of +course still possible to do just that, but the transformation object now +captures the whole transformation from source to destination in one. In the +example with the old API the source system is described as +``+proj=latlon +ellps=clrk66`` and the destination system is described as +``+proj=merc +ellps=clrk66 +lat_ts=33``. Since the Mercator projection accepts +geodetic coordinates as its input, the description of the source in this case +is superflous. We use that to our advantage in the new API and simply state +the destination. This is simple at a glance, but is actually a big conceptual +change. We are now focused on the path between two systems instead of what the +source and destination systems are. + + +Function mapping from old to new API +############################################################################### + ++---------------------------------------+---------------------------------------+ +| **Old API functions** | **New API functions** | ++---------------------------------------+---------------------------------------+ +| pj_fwd | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_inv | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_fwd3 | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_inv3 | proj_trans | ++---------------------------------------+---------------------------------------+ +| pj_transform | proj_trans_array or proj_trans_generic| ++---------------------------------------+---------------------------------------+ +| pj_init | proj_create | ++---------------------------------------+---------------------------------------+ +| pj_init_plus | proj_create | ++---------------------------------------+---------------------------------------+ +| pj_free | proj_destroy | ++---------------------------------------+---------------------------------------+ +| pj_is_latlong | proj_angular_output | ++---------------------------------------+---------------------------------------+ +| pj_is_geocent | proj_angular_outout | ++---------------------------------------+---------------------------------------+ +| pj_get_def | proj_pj_info | ++---------------------------------------+---------------------------------------+ +| pj_latlong_from_proj | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_set_finder | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_set_searchpath | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_deallocate_grids | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_strerrno | *No equivalent* | ++---------------------------------------+---------------------------------------+ +| pj_get_errno_ref | proj_errno | ++---------------------------------------+---------------------------------------+ +| pj_get_release | proj_info | ++---------------------------------------+---------------------------------------+ -- cgit v1.2.3 From 25b011042fdff451ca2826afe82251c06d883fb8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 27 Nov 2017 16:33:42 +0100 Subject: Update API reference to reflect recent changes to the API --- docs/source/development/reference/datatypes.rst | 389 +++--------------------- docs/source/development/reference/functions.rst | 109 ++++--- 2 files changed, 104 insertions(+), 394 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 85cedea6..1253b1a2 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -58,6 +58,14 @@ Transformation objects and destroyed with :c:func:`proj_context_destroy`. +.. c:type:: PJ_AREA + + Opaque object describing an area in which a transformation is performed. + + .. note:: This object is not fully implemented yet. 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 -------------------------------------------------------------------------------- @@ -117,22 +125,6 @@ Various 2-dimensional coordinate data types. Latitude or northing, depending on use. -.. c:type:: PJ_EN - - Generic easting/northing coordinate. - - .. code-block:: C - - typedef struct { double e, n; } PJ_EN; - - .. c:member:: double PJ_EN.e - - Easting - - .. c:member:: double PJ_EN.n - - Northing - 3 dimensional coordinates -------------------------------------------------------------------------------- @@ -203,27 +195,6 @@ types above. Vertical component. -.. c:type:: PJ_ENH - - Easting, northing and height. - - .. code-block:: C - - typedef struct {double e, n, h; } PJ_ENH; - - .. c:member:: double PJ_ENH.e - - Easting - - .. c:member:: double PJ_ENH.n - - Northing - - .. c:member:: double PJ_ENH.h - - Height - - Spatiotemporal coordinate types -------------------------------------------------------------------------------- @@ -318,29 +289,6 @@ domain. Temporal component. - -.. c:type:: PJ_ENHT - - Spatiotemporal version of :c:type:`PJ_ENH`. - - .. code-block:: C - - typedef struct {double e, n, h, t; } PJ_ENHT; - - .. c:member:: double PJ_ENHT.e - - Easting - - .. c:member:: double PJ_ENHT.n - - Northing - - .. c:member:: double PJ_ENHT.h - - Height - - .. c:member:: double PJ_ENHT.t - Ancillary types for geodetic computations -------------------------------------------------------------------------------- @@ -366,173 +314,9 @@ Ancillary types for geodetic computations Third rotation angle, kappa. -.. c:type:: PJ_DMS - - Describe a longitude or latitude by degrees, minutes and seconds. - - .. code-block:: C - - typedef struct { double d, m, s; } PJ_DMS; - - .. c:member:: double PJ_DMS.d - - Degrees. - - .. c:member:: double PJ_DMS.m - - Minutes - - .. c:member:: double PJ_DMS.s - - Seconds. - - -.. c:type:: PJ_EZN - - Geoid undulation and deflections of the vertical. - - .. code-block:: C - - typedef struct { double e, z, N; } PJ_EZN; - - .. c:member:: double PJ_EZN.e - - Deflection of the vertical, eta. - - .. c:member:: double PJ_EZN.z - - Deflection of the vertical, zeta - - .. c:member:: double PJ_EZN.N - - Geoid undulation. - - -.. c:type:: PJ_AF - - Ellipsoidal parameters. - - .. code-block:: C - - typedef struct {double a, f; } PJ_AF; - - .. c:member:: double PJ_AF.a - - Major axis of ellipsoid. - - .. c:member:: double PJ_AF.f - - Flattening of ellipsoid. - - Complex coordinate types -------------------------------------------------------------------------------- -.. c:type:: PJ_PAIR - - .. code-block:: C - - typedef union { - XY xy; - LP lp; - UV uv; - PJ_AF af; - PJ_EN en; - double v[2]; - } PJ_PAIR; - - .. c:member:: XY PJ_PAIR.xy - - Coordinate in projected space. - - .. c:member:: LP PJ_PAIR.lp - - Coordinate in lat/long space. - - .. c:member:: UV PJ_PAIR.uv - - Coordinate either in lat/lon or projected space. - - .. c:member:: PJ_AF PJ_PAIR.af; - - Ellipsoidal parameters. - - .. c:member:: PJ_EN PJ_PAIR.en - - Easting/Northing pair. - - .. c:member:: double PJ_PAIR.v[2] - - Generic 2D-vector. - -.. c:type:: PJ_TRIPLET - - Union type that groups all coordinate data types of two and tree dimensions. - - .. code-block:: C - - typedef union { - PJ_OPK opk; - PJ_ENH enh; - PJ_EZN ezn; - PJ_DMS dms; - double v[3]; - XYZ xyz; - LPZ lpz; - UVW uvw; - XY xy; - LP lp; - UV uv; - PJ_AF af; - } PJ_TRIPLET; - - .. c:member:: PJ_OPK PJ_TRIPLET.opk - - Rotations. - - .. c:member:: PJ_ENH PJ_TRIPLET.enh - - Easting, northing and height. - - .. c:member:: PJ_EZN PJ_TRIPLET.ezn - - Geoid undulation and deflections of the vertical. - - .. c:member:: PJ_DMS PJ_TRIPLET.dsm - - Degrees, minutes and seconds. - - .. c:member:: double PJ_TRIPLET.v[3] - - Generic 3-dimensional vector. - - .. c:member:: XYZ PJ_TRIPLET.xyz - - Coordinates in projected space. - - .. c:member:: LPZ PJ_TRIPLET.lpz - - Geodetic coordinates, including height. - - .. c:member:: UVW PJ_TRIPLET.uvw - - Either geodetic or projected coordinates. - - .. c:member:: XY PJ_TRIPLET.xy - - Horizontal coordinates in projected space. - - .. c:member:: LP PJ_TRIPLET.lp - - Geodetic coordinates. - - .. c:member:: UV PJ_TRIPLET.uv - - Geodetic or projected coordinate. - - .. c:member:: PJ_AF PJ_TRIPLET.af - - Ellipsoidal paramaters. .. c:type:: PJ_COORD @@ -541,13 +325,10 @@ Complex coordinate types .. code-block:: C typedef union { + double v[4]; PJ_XYZT xyzt; PJ_UVWT uvwt; - PJ_ENHT enht; PJ_LPZT lpzt; - PJ_ENH enh; - PJ_EN en; - double v[4]; XYZ xyz; UVW uvw; LPZ lpz; @@ -556,6 +337,10 @@ Complex coordinate types LP lp; } PJ_COORD ; + .. c:member:: double v[4] + + Generic four-dimensional vector. + .. c:member:: PJ_XYZT PJ_COORD.xyzt Spatiotemporal cartesian coordinate. @@ -564,26 +349,10 @@ Complex coordinate types Spatiotemporal generic coordinate. - .. c:member:: PJ_ENHT PJ_COORD.enht - - Easting, northing, height and time. - .. c:member:: PJ_LPZT PJ_COORD.lpzt Longitude, latitude, vertical and time components. - .. c:member:: PJ_ENH PJ_COORD.enh - - Easting, northing and height - - .. c:member:: PJ_EN PJCOORD.en - - Easting and northing. - - .. c:member:: double v[4] - - Generic four-dimensional vector. - .. c:member:: XYZ PJ_COORD.xyz 3-dimensional cartesian coordinate. @@ -609,68 +378,9 @@ Complex coordinate types Longitude and latitude. -.. c:type:: PJ_OBS - - Geodetic observation data type. - - .. code-block:: C - - typedef struct { - PJ_COORD coo; - PJ_TRIPLET anc; - int id; - unsigned int flags; - } PJ_OBS; - - .. c:member:: PJ_COORD PJ_OBS.coo - - Coordinate data - - .. c:member:: PJ_TRIPLET PJ_OBS.anc - - Ancillary data - - .. c:member:: int PJ_OBS.id - - Integer ancillary data, e.g. observation number, EPSG code, etc. - - .. c:member:: unsigned int PJ_OBS.flags - - Additional data intended for flags. - - Projection derivatives ------------------------------------------------------------------------------- -.. c:type:: PJ_DERIVS - - Partial derivatives of geodetic coordinate :math:`\left(\lambda,\phi\right)`. - Calculated with :c:func:`proj_derivatives`. - - .. code-block:: C - - typedef struct { - double x_l, x_p; - double y_l, y_p; - } PJ_DERIVS; - - .. c:member:: double PJ_DERIVS.x_l - - :math:`\frac{\partial x}{\partial \lambda}` - - .. c:member:: double PJ_DERIVS.x_p - - :math:`\frac{\partial x}{\partial \phi}` - - .. c:member:: double PJ_DERIVS.y_l - - :math:`\frac{\partial y}{\partial \lambda}` - - .. c:member:: double PJ_DERIVS.y_p - - :math:`\frac{\partial y}{\partial \phi}` - - .. c:type:: PJ_FACTORS Various cartographic properties, such as scale factors, angular distortion @@ -681,73 +391,51 @@ Projection derivatives .. code-block:: C typedef struct { - struct PJ_DERIVS der; - double h, k; - double omega, thetap; - double conv; - double s; - double a, b; - int code; - } PJ_FACTORS; + double meridional_scale; + double parallel_scale; + double areal_scale; - .. c:member:: PJ_DERIVS PJ_FACTORS.der + double angular_distortion; + double meridian_parallel_angle; + double meridian_convergence; - Partial derivatives of coordinate :math:`\left(\lambda,\phi\right)`. + double tissot_semimajor; + double tissot_semiminor; + } PJ_FACTORS; - .. c:member:: double PJ_FACTORS.h + .. c:member:: double PJ_FACTORS.meridional_scale - Meridian scale at coordinate :math:`\left(\lambda,\phi\right)`. + Meridional scale at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.k + .. c:member:: double PJ_FACTORS.parallel_scale Parallel scale at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.omega + .. c:member:: double PJ_FACTORS.areal_scale + + Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.angular_distortion Angular distortion at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.thetap + .. c:member:: double PJ_FACTORS.meridian_parallel_angle Meridian/parallel angle, :math:`\theta^\prime`, at coordinate :math:`\left(\lambda,\phi\right)`. - .. c:member:: double PJ_FACTORS.conv + .. c:member:: double PJ_FACTORS.meridian_convergence Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. Sometimes also described as *grid declination*. - .. c:member:: double PJ_FACTORS.s - - Areal scale factor at coordinate :math:`\left(\lambda,\phi\right)`. - - .. c:member:: double PJ_FACTORS.a + .. c:member:: double PJ_FACTORS.tissot_semimajor Maximum scale error. - .. c:member:: double PJ_FACTORS.b + .. c:member:: double PJ_FACTORS.tissot_semiminor Minimum scale error. - .. c:member:: int code - - Bitmask determing if calculation of various factors was done numerically - or analytically. If a bit flags is set the calculation was done analytically. - The following bit flags exists: - - .. c:macro:: PJ_IS_ANAL_XL_YL - - Longitude derivatives are calculated analytically - - .. c:macro:: PJ_IS_ANAL_XP_YP - - Latitude derivatives are calculated analyticall. - - .. c:macro:: PJ_IS_ANAL_HK - - Meridinal and parallel scale factors are calculated analytically. - - .. c:macro:: PJ_IS_ANAL_CONV - - Meridian convergence calculated analytically. List structures ------------------------------------------------------------------------------- @@ -913,6 +601,7 @@ Info structures char description[128]; char definition[512]; int has_inverse; + double accuracy; } PJ_PROJ_INFO; .. c:member:: char PJ_PROJ_INFO.id[16] @@ -934,6 +623,10 @@ Info structures 1 if an inverse mapping of the defined operation exists, otherwise 0. + .. c:member:: double PJ_PROJ_INFO.accuracy + + Expected accuracy of the transformation. -1 if unknown. + .. c:type:: PJ_GRID_INFO Struct holding information about a specific grid in the search path of @@ -957,7 +650,7 @@ Info structures .. c:member:: char PJ_GRID_INFO - Full path of grid file, e.g. "*C:\OSGeo4W64\\share\proj\BETA2007.gsb*" + Full path of grid file, e.g. *"C:\\OSGeo4W64\\share\\proj\\BETA2007.gsb"* .. c:member:: char PJ_GRID_INFO.format[8] @@ -1009,7 +702,7 @@ Info structures .. c:member:: char PJ_INIT_INFO.filename[260] - Full path of init file, e.g. "*C:\OSGeo4W64\share\proj\epsg*" + Full path of init file, e.g. "*C:\\OSGeo4W64\\share\\proj\\epsg*" .. c:member:: char PJ_INIT_INFO.version[32] diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 10af19d4..ea128954 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -58,7 +58,7 @@ Transformation setup :param char** argv: Vector of strings with proj-string parameters, e.g. ``+proj=merc`` :returns: :c:type:`PJ*` -.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to) +.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *srid_from, const char *srid_to, PJ_AREA *area) Create a transformation object that is a pipeline between two known coordinate reference systems. @@ -71,13 +71,15 @@ Transformation setup given and coordinates are transformed via a hub datum (WGS84). This transformation strategy is referred to as "early-binding" by the EPSG. The function can be extended to support "late-binding" transformations in the - future without affecting users of the function. + future without affecting users of the function. When the function is extended + to the late-binding approach the :c:data:`area` argument will be used. For + now it is just a place-holder for a future improved implementation. Example call: .. code-block:: C - PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833"); + PJ *P = proj_create_crs_to_crs(0, "epsg:25832", "epsg:25833", 0); The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. @@ -86,6 +88,8 @@ Transformation setup :type `srid_from`: const char* :param `srid_to`: Destination SRID. :type `srid_to`: const char* + :param `area`: Descriptor of the desired area for the transformation. + :type `area`: PJ_AREA :returns: :c:type:`PJ*` .. c:function:: PJ* proj_destroy(PJ *P) @@ -101,7 +105,7 @@ Coordinate transformation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: PJ_COORD proj_trans_coord(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) +.. c:function:: PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) Transform a single :c:type:`PJ_COORD` coordinate. @@ -112,22 +116,10 @@ Coordinate transformation :returns: :c:type:`PJ_COORD` -.. c:function:: PJ_OBS proj_trans_obs(PJ *P, PJ_DIRECTION direction, PJ_OBS obs) - - Transform a single :c:type:`PJ_OBS` observation. - - :param PJ* P: - :param `direction`: Transformation direction. - :type `direction`: PJ_DIRECTION - :param PJ_OBS obs: Observation data to transform. - :returns: :c:type:`PJ_OBS` - - - -.. c:function:: size_t proj_transform(PJ *P, PJ_DIRECTION direction, \ - double *x, size_t sx, size_t nx, double *y, \ - size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ - double *t, size_t st, size_t nt) +.. c:function:: size_t proj_trans_generic(PJ *P, PJ_DIRECTION direction, \ + double *x, size_t sx, size_t nx, double *y, \ + size_t sy, size_t ny, double *z, size_t sz, size_t nz, \ + double *t, size_t st, size_t nt) Transform a series of coordinates, where the individual coordinate dimension may be represented by an array that is either @@ -159,7 +151,7 @@ Coordinate transformation ... - proj_transform ( + proj_trans_generic ( P, PJ_INV, sizeof(XYQS), &(survey[0].x), stride, 345, /* We have 345 eastings */ &(survey[0].y), stride, 345, /* ...and 345 northings. */ @@ -202,7 +194,7 @@ Coordinate transformation -.. c:function:: size_t proj_transform_coord(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) +.. c:function:: size_t proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) Batch transform an array of :c:type:`PJ_COORD`. @@ -212,16 +204,6 @@ Coordinate transformation :param size_t n: Number of cordinates in :c:data:`coord` :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number -.. c:function:: size_t proj_transform_obs(PJ *P, PJ_DIRECTION direction, size_t n, PJ_OBS *obs) - - Batch transform an array of :c:type:`PJ_OBS`. - - :param PJ* P: - :param `direction`: Transformation direction - :type `direction`: PJ_DIRECTION - :param size_t n: Number of observations in :c:data:`obs` - :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number - Initializers ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -443,7 +425,7 @@ Lists Distances ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_lp_dist(PJ *P, LP a, LP b) +.. c:function:: double proj_lp_dist(const PJ *P, LP a, LP b) Calculate geodesic distance between two points in geodetic coordinates. @@ -452,6 +434,15 @@ Distances :param LP b: Coordinate of second point :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. +.. c:function:: double proj_lp_dist(const PJ *P, LPZ a, LPZ b) + + Calculate geodesic distance between two points in geodetic coordinates. + + :param PJ* P: Transformation object + :param LPZ a: Coordinate of first point + :param LPZ b: Coordinate of second point + :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. + .. c:function:: double proj_xy_dist(XY a, XY, b) Calculate 2-dimensional euclidean between two projected coordinates. @@ -472,15 +463,16 @@ Distances Various ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_OBS obs) +.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coo) Measure internal consistency of a given transformation. The function performs :c:data:`n` round trip transformations starting in either the forward or reverse :c:data:`direction`. Returns the euclidean - distance of the starting point :c:data:`obs` and the resulting + distance of the starting point :c:data:`coo` and the resulting coordinate after :c:data:`n` iterations back and forth. :param PJ* P: + :type `P`: const PJ* :param `direction`: Starting direction of transformation :type `direction`: PJ_DIRECTION :param int n: Number of roundtrip transformations @@ -488,17 +480,7 @@ Various :returns: :c:type:`double` Distance between original coordinate and the \ resulting coordinate after :c:data:`n` transformation iterations. -.. c:function:: PJ_DERIVS proj_derivatives(const PJ *P, const LP lp) - - Calculate partial derivatives of geodetic coordinates. - - :param `P`: Transformation object - :type `P`: const PJ* - :param `lp`: Geodetic coordinate - :type `lp`: const LP - :returns: :c:type:`PJ_DERIVS` - -.. c:function:: PJ_FACTORS proj_factors(const PJ *P, const LP lp) +.. c:function:: PJ_FACTORS proj_factors(PJ *P, LP lp) Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence. Depending on the underlying projection @@ -547,3 +529,38 @@ Various :param int pos: Character denoting positive direction, typically `'N'` or `'E'`. :param int neg: Character denoting negative direction, typically `'S'` or `'W'`. :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) + + +.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) + + Convert geographical to geocentric latitude. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :param `coo`: Coordinate + :type `coo`: PJ_COORD + :returns: :c:type:`PJ_COORD` Converted coordinate + + +.. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir) + + Check if a operation expects angular input. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: :c:type:`int` 1 if angular input is expected, otherwise 0 + +.. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir) + + Check if an operation returns angular output. + + :param `P`: Transformation object + :type `P`: const PJ* + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: :c:type:`int` 1 if angular output is returned, otherwise 0 + -- cgit v1.2.3 From 28f7894d9aee8eecc691fd691a0e27ff0914ce08 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 1 Feb 2018 16:46:06 +0100 Subject: Update datatype and function reference to reflect recent code changes [skip ci] --- docs/source/development/reference/datatypes.rst | 26 +++++++++++++++++++++++++ docs/source/development/reference/functions.rst | 4 ++-- 2 files changed, 28 insertions(+), 2 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 1253b1a2..80e9ae4c 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -401,6 +401,11 @@ Projection derivatives double tissot_semimajor; double tissot_semiminor; + + double dx_dlam; + double dx_dphi; + double dy_dlam; + double dy_dphi; } PJ_FACTORS; .. c:member:: double PJ_FACTORS.meridional_scale @@ -436,6 +441,27 @@ Projection derivatives Minimum scale error. + .. c:member:: double PJ_FACTORS.dx_dlam + + Partial derivative :math:`\frac{\partial x}{\partial \lambda}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dy_dlam + + + Partial derivative :math:`\frac{\partial y}{\partial \lambda}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dx_dphi + + Partial derivative :math:`\frac{\partial x}{\partial \phi}` of coordinate + :math:`\left(\lambda,\phi\right)`. + + .. c:member:: double PJ_FACTORS.dy_dphi + + + Partial derivative :math:`\frac{\partial y}{\partial \phi}` of coordinate + :math:`\left(\lambda,\phi\right)`. List structures ------------------------------------------------------------------------------- diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index ea128954..14c0b52a 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -531,9 +531,9 @@ Various :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) -.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) +.. c:function:: PJ_COORD proj_geocentric_latitude(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) - Convert geographical to geocentric latitude. + Convert from geographical latitude to geocentric latitude. :param `P`: Transformation object :type `P`: const PJ* -- cgit v1.2.3 From a9e08ad008b1ff16d6139aab5e813058c922eef8 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 22:37:10 +0100 Subject: API reference updates to reflect recent changes across the code-base [skip ci]. --- docs/source/development/reference/datatypes.rst | 106 ++++++++-------- docs/source/development/reference/functions.rst | 156 +++++++++--------------- 2 files changed, 110 insertions(+), 152 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index 1253b1a2..89a9306e 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -62,7 +62,7 @@ Transformation objects Opaque object describing an area in which a transformation is performed. - .. note:: This object is not fully implemented yet. It is used with + .. 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. @@ -71,56 +71,56 @@ Transformation objects Various 2-dimensional coordinate data types. -.. c:type:: LP +.. c:type:: PJ_LP Geodetic coordinate, latitude and longitude. Usually in radians. .. code-block:: C - typedef struct { double lam, phi; } LP; + typedef struct { double lam, phi; } PJ_LP; - .. c:member:: double LP.lam + .. c:member:: double PJ_LP.lam Longitude. Lambda. - .. c:member:: double LP.phi + .. c:member:: double PJ_LP.phi Latitude. Phi. -.. c:type:: XY +.. c:type:: PJ_XY 2-dimensional cartesian coordinate. .. code-block:: C - typedef struct { double x, y; } XY; + typedef struct { double x, y; } PJ_XY; - .. c:member:: double XY.lam + .. c:member:: double PJ_XY.lam Easting. - .. c:member:: double XY.phi + .. c:member:: double PJ_XY.phi Northing. -.. c:type:: UV +.. c:type:: PJ_UV 2-dimensional generic coordinate. Usually used when contents can be either - a :c:type:`XY` or :c:type:`UV`. + a :c:type:`PJ_XY` or :c:type:`PJ_LP`. .. code-block:: C - typedef struct {double u, v; } UV; + typedef struct {double u, v; } PJ_UV; - .. c:member:: double UV.u + .. c:member:: double PJ_UV.u Longitude or easting, depending on use. - .. c:member:: double UV.v + .. c:member:: double PJ_UV.v Latitude or northing, depending on use. @@ -131,66 +131,66 @@ Various 2-dimensional coordinate data types. The following data types are the 3-dimensional equivalents to the data types above. -.. c:type:: LPZ +.. c:type:: PJ_LPZ - 3-dimensional version of :c:type:`LP`. Holds longitude, latitude and + 3-dimensional version of :c:type:`PJ_LP`. Holds longitude, latitude and vertical component. .. code-block:: C - typedef struct { double lam, phi, z; } LPZ; + typedef struct { double lam, phi, z; } PJ_LPZ; - .. c:member:: double LPZ.lam + .. c:member:: double PJ_LPZ.lam Longitude. Lambda. - .. c:member:: double LPZ.phi + .. c:member:: double PJ_LPZ.phi Latitude. Phi. - .. c:member:: double LPZ.z + .. c:member:: double PJ_LPZ.z Vertical component. -.. c:type:: XYZ +.. c:type:: PJ_XYZ - Cartesian coordinate in 3 dimensions. Extension of :c:type:`XY`. + Cartesian coordinate in 3 dimensions. Extension of :c:type:`PJ_XY`. .. code-block:: C - typedef struct { double x, y, z; } XYZ; + typedef struct { double x, y, z; } PJ_XYZ; - .. c:member:: double XYZ.x + .. c:member:: double PJ_XYZ.x Easting. - .. c:member:: double XYZ.y + .. c:member:: double PJ_XYZ.y Northing. - .. c:member:: double XYZ.z + .. c:member:: double PJ_XYZ.z Vertical component. -.. c:type:: UVW +.. c:type:: PJ_UVW - 3-dimensional extension of :c:type:`UV`. + 3-dimensional extension of :c:type:`PJ_UV`. .. code-block:: C - typedef struct {double u, v, w; } UVW; + typedef struct {double u, v, w; } PJ_UVW; - .. c:member:: double UVW.u + .. c:member:: double PJ_UVW.u Longitude or easting, depending on use. - .. c:member:: double UVW.v + .. c:member:: double PJ_UVW.v Latitude or northing, depending on use. - .. c:member:: double UVW.w + .. c:member:: double PJ_UVW.w Vertical component. @@ -204,7 +204,7 @@ domain. .. c:type:: PJ_LPZT - Spatiotemporal version of :c:type:`LPZ`. + Spatiotemporal version of :c:type:`PJ_LPZ`. .. code-block:: C @@ -321,6 +321,7 @@ Complex coordinate types .. c:type:: PJ_COORD General purpose coordinate union type usefull in two, three and four dimensions. + This is the default coordinate datatype used in PROJ. .. code-block:: C @@ -329,12 +330,12 @@ Complex coordinate types PJ_XYZT xyzt; PJ_UVWT uvwt; PJ_LPZT lpzt; - XYZ xyz; - UVW uvw; - LPZ lpz; - XY xy; - UV uv; - LP lp; + PJ_XYZ xyz; + PJ_UVW uvw; + PJ_LPZ lpz; + PJ_XY xy; + PJ_UV uv; + PJ_LP lp; } PJ_COORD ; .. c:member:: double v[4] @@ -353,27 +354,27 @@ Complex coordinate types Longitude, latitude, vertical and time components. - .. c:member:: XYZ PJ_COORD.xyz + .. c:member:: PJ_XYZ PJ_COORD.xyz 3-dimensional cartesian coordinate. - .. c:member:: UVW PJ_COORD.uvw + .. c:member:: PJ_UVW PJ_COORD.uvw 3-dimensional generic coordinate. - .. c:member:: LPZ PJ_COORD.lpz + .. c:member:: PJ_LPZ PJ_COORD.lpz Longitude, latitude and vertical component. - .. c:member:: XY PJ_COORD.xy + .. c:member:: PJ_XY PJ_COORD.xy 2-dimensional cartesian coordinate. - .. c:member:: UV PJ_COORD.uv + .. c:member:: PJ_UV PJ_COORD.uv 2-dimensional generic coordinate. - .. c:member:: LP PJ_COORD.lp + .. c:member:: PJ_LP PJ_COORD.lp Longitude and latitude. @@ -496,7 +497,7 @@ List structures .. c:type:: PJ_UNITS - Distance units defined in PROJ.4. + Distance units defined in PROJ. .. code-block:: C @@ -525,7 +526,7 @@ List structures .. c:type:: PJ_PRIME_MERIDIANS - Prime meridians defined in PROJ.4. + Prime meridians defined in PROJ. .. code-block:: C @@ -547,7 +548,7 @@ Info structures .. c:type:: PJ_INFO - Struct holding information about the current instance of PROJ.4. Struct is + Struct holding information about the current instance of PROJ. Struct is populated by :c:func:`proj_info`. .. code-block:: C @@ -585,8 +586,9 @@ Info structures .. c:member:: char PJ_INFO.searchpath[512] - Search path for PROJ.4. List of directories separated by - semicolons, e.g. "C:\Users\doctorwho;C:\OSGeo4W64\\share\proj". + Search path for PROJ. List of directories separated by + semicolons (Windows) or colons (non-Windows), e.g. + "C:\\Users\\doctorwho;C:\\OSGeo4W64\\share\\proj". Grids and init files are looked for in directories in the search path. .. c:type:: PJ_PROJ_INFO @@ -630,7 +632,7 @@ Info structures .. c:type:: PJ_GRID_INFO Struct holding information about a specific grid in the search path of - PROJ.4. Populated with the function :c:func:`proj_grid_info`. + PROJ. Populated with the function :c:func:`proj_grid_info`. .. code-block:: C @@ -684,7 +686,7 @@ Info structures .. c:type:: PJ_INIT_INFO Struct holding information about a specific init file in the search path of - PROJ.4. Populated with the function :c:func:`proj_init_info`. + PROJ. Populated with the function :c:func:`proj_init_info`. .. code-block:: C diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index ea128954..8770f99b 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -205,83 +205,6 @@ Coordinate transformation :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number -Initializers -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) - - Initializer for the :c:type:`PJ_COORD` union. The function is - shorthand for the otherwise convoluted assignment. - Equivalent to - - .. code-block:: C - - PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; - - or - - .. code-block:: C - - PJ_COORD c; - // Assign using the PJ_XYZT struct in the union - c.xyzt.x = 10.0; - c.xyzt.y = 20.0; - c.xyzt.z = 30.0; - c.xyzt.t = 40.0; - - Since :c:type:`PJ_COORD` is a union of structs, the above assignment can - also be expressed in terms of the other types in the union, e.g. - :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. - - - :param double x: 1st component in a :c:type:`PJ_COORD` - :param double y: 2nd component in a :c:type:`PJ_COORD` - :param double z: 3rd component in a :c:type:`PJ_COORD` - :param double t: 4th component in a :c:type:`PJ_COORD` - :returns: :c:type:`PJ_COORD` - -.. c:function:: PJ_OBS proj_obs(double x, double y, double z, double t,\ - double o, double p, double k,\ - int id, unsigned int flags) - - Initializer for the :c:type:`PJ_OBS` union. The function is - shorthand for the otherwise convoluted assignment. - Equivalent to - - .. code-block:: C - - PJ_OBS c = {{{1.0, 2.0, 3.0, 4.0}}, {{5.0, 6.0, 7.0}}, 8, 9}; - - or - - .. code-block:: C - - PJ_OBS c; - // Assign using the PJ_COORD part of the struct in the union - o.coo.v[0] = 1.0; - o.coo.v[1] = 2.0; - o.coo.v[2] = 3.0; - o.coo.v[3] = 4.0; - o.anc.v[0] = 5.0; - o.anc.v[1] = 6.0; - o.anc.v[2] = 7.0; - o.id = 8; - o.flags = 9; - - which is a bit too verbose in most practical applications. - - :param double x: 1st component in a :c:type:`PJ_COORD` - :param double y: 2nd component in a :c:type:`PJ_COORD` - :param double z: 3rd component in a :c:type:`PJ_COORD` - :param double t: 4th component in a :c:type:`PJ_COORD` - :param double o: 1st component in a :c:type:`PJ_TRIPLET` - :param double p: 2nd component in a :c:type:`PJ_TRIPLET` - :param double k: 3rd component in a :c:type:`PJ_TRIPLET` - :param int id: Ancillary data, e.g. an ID - :param `flags`: Flags - :type `flags`: unsigned int - :returns: :c:type:`PJ_OBS` - Error reporting ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -350,7 +273,7 @@ Info functions .. c:function:: PJ_INFO proj_info(void) - Get information about the current instance of the PROJ.4 library. + Get information about the current instance of the PROJ library. :returns: :c:type:`PJ_INFO` @@ -366,7 +289,7 @@ Info functions Get information about a specific grid. - :param `gridname`: Gridname in the PROJ.4 searchpath + :param `gridname`: Gridname in the PROJ searchpath :type `gridname`: const char* :returns: :c:type:`PJ_GRID_INFO` @@ -374,7 +297,7 @@ Info functions Get information about a specific init file. - :param `initname`: Init file in the PROJ.4 searchpath + :param `initname`: Init file in the PROJ searchpath :type `initname`: const char* :returns: :c:type:`PJ_INIT_INFO` @@ -383,11 +306,11 @@ Lists .. c:function:: const PJ_OPERATIONS* proj_list_operations(void) - Get a pointer to an array of all operations in PROJ.4. The last entry + Get a pointer to an array of all operations in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. - Print a list of all operations in PROJ.4: + Print a list of all operations in PROJ: .. code-block:: C @@ -400,7 +323,7 @@ Lists .. c:function:: const PJ_ELLPS* proj_list_ellps(void) - Get a pointer to an array of ellipsoids defined in PROJ.4. The last entry + Get a pointer to an array of ellipsoids defined in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. @@ -408,7 +331,7 @@ Lists .. c:function:: const PJ_UNITS* proj_list_units(void) - Get a pointer to an array of distance units defined in PROJ.4. The last + Get a pointer to an array of distance units defined in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. @@ -416,7 +339,7 @@ Lists .. c:function:: const PJ_PRIME_MERIDIANS* proj_list_prime_meridians(void) - Get a pointer to an array of prime meridians defined in PROJ.4. The last + Get a pointer to an array of prime meridians defined in PROJ. The last entry of the returned array is a NULL-entry. The array is statically allocated and does not need to be freed after use. @@ -425,44 +348,77 @@ Lists Distances ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -.. c:function:: double proj_lp_dist(const PJ *P, LP a, LP b) +.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b) Calculate geodesic distance between two points in geodetic coordinates. :param PJ* P: Transformation object - :param LP a: Coordinate of first point - :param LP b: Coordinate of second point + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. -.. c:function:: double proj_lp_dist(const PJ *P, LPZ a, LPZ b) +.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b) Calculate geodesic distance between two points in geodetic coordinates. :param PJ* P: Transformation object - :param LPZ a: Coordinate of first point - :param LPZ b: Coordinate of second point + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. -.. c:function:: double proj_xy_dist(XY a, XY, b) +.. c:function:: double proj_xy_dist(PJ_COORD a, PJ_COORD b) Calculate 2-dimensional euclidean between two projected coordinates. - :param XY a: First coordinate - :param XY b: Second coordinate + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. -.. c:function:: double proj_xyz_dist(XYZ a, XYZ b) +.. c:function:: double proj_xyz_dist(PJ_COORD a, PJ_COORD b) Calculate 3-dimensional euclidean between two projected coordinates. - :param XYZ a: First coordinate - :param XYZ b: Second coordinate + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate :returns: :c:type:`double` Distance between :c:data:`a` and :c:data:`b` in meters. Various ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. c:function:: PJ_COORD proj_coord(double x, double y, double z, double t) + + Initializer for the :c:type:`PJ_COORD` union. The function is + shorthand for the otherwise convoluted assignment. + Equivalent to + + .. code-block:: C + + PJ_COORD c = {{10.0, 20.0, 30.0, 40.0}}; + + or + + .. code-block:: C + + PJ_COORD c; + // Assign using the PJ_XYZT struct in the union + c.xyzt.x = 10.0; + c.xyzt.y = 20.0; + c.xyzt.z = 30.0; + c.xyzt.t = 40.0; + + Since :c:type:`PJ_COORD` is a union of structs, the above assignment can + also be expressed in terms of the other types in the union, e.g. + :c:type:`PJ_UVWT` or :c:type:`PJ_LPZT`. + + + :param double x: 1st component in a :c:type:`PJ_COORD` + :param double y: 2nd component in a :c:type:`PJ_COORD` + :param double z: 3rd component in a :c:type:`PJ_COORD` + :param double t: 4th component in a :c:type:`PJ_COORD` + :returns: :c:type:`PJ_COORD` + + .. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coo) Measure internal consistency of a given transformation. The function @@ -480,7 +436,7 @@ Various :returns: :c:type:`double` Distance between original coordinate and the \ resulting coordinate after :c:data:`n` transformation iterations. -.. c:function:: PJ_FACTORS proj_factors(PJ *P, LP lp) +.. c:function:: PJ_FACTORS proj_factors(PJ *P, PJ_COORD lp) Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence. Depending on the underlying projection @@ -492,7 +448,7 @@ Various :param `P`: Transformation object :type `P`: const PJ* :param `lp`: Geodetic coordinate - :type `lp`: const LP + :type `lp`: const PJ_COORD :returns: :c:type:`PJ_FACTORS` .. c:function:: double proj_torad(double angle_in_degrees) @@ -531,7 +487,7 @@ Various :returns: :c:type:`char*` Pointer to output buffer (same as :c:data:`s`) -.. c:function:: PJ_COORD proj_geoc_lat(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) +.. c:function:: PJ_COORD proj_geocentric_latitude(const PJ *P, PJ_DIRECTION direction, PJ_COORD coo) Convert geographical to geocentric latitude. -- cgit v1.2.3 From 631145da4d23db670cb378fdae14dc6f3555513b Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 23:09:40 +0100 Subject: Change most occurences of PROJ.4 to PROJ [skip ci] --- docs/source/development/bindings.rst | 14 +++++++------- docs/source/development/cmake.rst | 4 ++-- docs/source/development/index.rst | 2 +- docs/source/development/quickstart.rst | 10 +++++----- docs/source/development/threads.rst | 8 ++++---- 5 files changed, 19 insertions(+), 19 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/bindings.rst b/docs/source/development/bindings.rst index 80babcb2..3fac1869 100644 --- a/docs/source/development/bindings.rst +++ b/docs/source/development/bindings.rst @@ -4,40 +4,40 @@ Language bindings ******************************************************************************** -PROJ.4 bindings are available for a number of different development platforms. +PROJ bindings are available for a number of different development platforms. Python ====== `pyproj `_: -Python interface (wrapper for PROJ.4) +Python interface (wrapper for PROJ) Ruby ======= `proj4rb `_: -Bindings for PROJ.4 in ruby +Bindings for PROJ in ruby TCL ======== `proj4tcl `_: -Bindings for PROJ.4 in tcl (critcl source) +Bindings for PROJ in tcl (critcl source) MySQL ===== `fProj4 `_: -Bindings for PROJ.4 in MySQL +Bindings for PROJ in MySQL Excel ======== `proj.xll `_: -Excel add-in for PROJ.4 map projections +Excel add-in for PROJ map projections Visual Basic ================== -`PROJ.4 VB Wrappers `_: +`PROJ VB Wrappers `_: By Eric G. Miller. diff --git a/docs/source/development/cmake.rst b/docs/source/development/cmake.rst index 1429ae88..5a8ce624 100644 --- a/docs/source/development/cmake.rst +++ b/docs/source/development/cmake.rst @@ -1,10 +1,10 @@ .. _cmake: ******************************************************************************** -Using Proj.4 in CMake projects +Using PROJ in CMake projects ******************************************************************************** -The recommended way to use the Proj.4 library in a CMake project is to +The recommended way to use the PROJ library in a CMake project is to link to the imported library target ``${PROJ4_LIBRARIES}`` provided by the CMake configuration which comes with the library. Typical usage is: diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 743224a6..3f8a7bf6 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -5,7 +5,7 @@ Development ================================================================================ These pages are primarily focused towards developers either contributing to the -PROJ.4 project or using the library in their own software. +PROJ project or using the library in their own software. .. toctree:: diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index 7137d85a..960cddbf 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -4,15 +4,15 @@ Quick start ================================================================================ -This is a short introduction to the PROJ.4 API. In the following section we +This is a short introduction to the PROJ API. In the following section we create a simple program that transforms a geodetic coordinate to UTM and back again. The program is explained a few lines at a time. The complete program can be seen at the end of the section. See the following sections for more in-depth descriptions of different parts of -the PROJ.4 API or consult the :doc:`API reference ` for specifics. +the PROJ API or consult the :doc:`API reference ` for specifics. -Before the PROJ.4 API can be used it is necessary to include the ``proj.h`` header +Before the PROJ API can be used it is necessary to include the ``proj.h`` header file. Here ``stdio.h`` is also included so we can print some text to the screen: .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c @@ -54,10 +54,10 @@ details. :lines: 50-52 :dedent: 4 -PROJ.4 uses it's own data structures for handling coordinates. Here we use a +PROJ uses it's own data structures for handling coordinates. Here we use a ``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note that the input values are converted to radians with ``proj_torad``. This is -necessary since PROJ.4 is using radians internally. See :doc:`transformations` +necessary since PROJ is using radians internally. See :doc:`transformations` for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c diff --git a/docs/source/development/threads.rst b/docs/source/development/threads.rst index a557fa07..674f4bd1 100644 --- a/docs/source/development/threads.rst +++ b/docs/source/development/threads.rst @@ -4,7 +4,7 @@ Threads ================================================================================ -This page is about efforts to make PROJ.4 thread safe. +This page is about efforts to make PROJ thread safe. Key Thread Safety Issues -------------------------------------------------------------------------------- @@ -14,14 +14,14 @@ Key Thread Safety Issues introduction of the projCtx execution context. * the datum shift using grid files uses globally shared lists of loaded grid information. Access to this has been made safe in 4.7.0 with the introduction - of a proj.4 mutex used to protect access to these memory structures (see + of a PROJ mutex used to protect access to these memory structures (see pj_mutex.c). projCtx -------------------------------------------------------------------------------- Primarily in order to avoid having pj_errno as a global variable, a "thread -context" structure has been introduced into a variation of the PROJ.4 API for +context" structure has been introduced into a variation of the PROJ API for the 4.8.0 release. The pj_init() and pj_init_plus() functions now have context variations called pj_init_ctx() and pj_init_plus_ctx() which take a projections context. @@ -68,7 +68,7 @@ src/multistresstest.c -------------------------------------------------------------------------------- A small multi-threaded test program has been written (src/multistresstest.c) -for testing multithreaded use of PROJ.4. It performs a series of reprojections +for testing multithreaded use of PROJ. It performs a series of reprojections to setup a table expected results, and then it does them many times in several threads to confirm that the results are consistent. At this time this program is not part of the builds but it can be built on linux like: -- cgit v1.2.3 From c7398bd44d47ac824bb7f81bfdfe60fff3b9b675 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Mon, 19 Feb 2018 23:54:30 +0100 Subject: Added background info to API migration guide [skip ci]. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brazenly stolen from mailing list post by Thomas Knudsen [0] and modified slightly to fit the context. [0] http://lists.maptools.org/pipermail/proj/2018-February/007995.html --- docs/source/development/migration.rst | 62 +++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 3 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/migration.rst b/docs/source/development/migration.rst index d9014a36..eb509bcf 100644 --- a/docs/source/development/migration.rst +++ b/docs/source/development/migration.rst @@ -7,12 +7,69 @@ Version 4 to 5 API Migration This is a transition guide for developers wanting to migrate their code to use PROJ version 5. -The difference between the old and new API is best shown with examples. Below + +Background +############################################################################### + +Before we go on, a bit of background is needed. The new API takes a different +view of the world than the old because it is needed in order to obtain high +accuracy transformations. The old API is constructed in such a way that any transformation +between two coordinate reference systems *must* pass through the ill-defined +WGS84 reference frame, using it as a hub. The new API does away with this limitation to +transformations in PROJ. It is still possible to do that type of transformations +but in many cases there will be a better alternative. + +The world view represented by the old API is always sufficient if all you care about is +meter level accuracy - and in many cases it will provide much higher accuracy +than that. But the view that “WGS84 is the *true* foundation of the world, and +everything else can be transformed natively to and from WGS84” is inherently flawed. + +First and foremost because any time WGS84 is mentioned, you should ask yourself +“Which of the six WGS84 realizations are we talking about here?”. + +Second, because for many (especially legacy) systems, it may not be straightforward +to transform to WGS84 (or actually ITRF-something, ETRS-something or NAD-something +which appear to be the practical meaning of the term WGS84 in everyday PROJ related +work), while centimeter-level accurate transformations may exist between pairs of +older systems. + +The concept of a hub reference frame (“datum”) is not inherently bad, but in many +cases you need to handle and select that datum with more care than the old API allows. +The primary aim of the new API is to allow just that. And to do that, you must realize +that the world is inherently 4 dimensional. You may in many cases assume one or more of +the coordinates to be constant, but basically, to obtain geodetic accuracy transformations, +you need to work in 4 dimensions. + +Now, having described the background for introducing the new API, let's try to show +how to use it. First note that in order to go from system A to system B, the old API +starts by doing an **inverse** transformation from system A to WGS84, then does a +**forward** transformation from WGS84 to system B. + +With ``cs2cs`` being the command line interface to the old API, and ``cct`` being the same +for the new, this example of doing the same thing in both world views will should give +an idea of the differences: + +:: + + $ echo 300000 6100000 | cs2cs +proj=utm +zone=33 +ellps=GRS80 +to +proj=utm +zone=32 +ellps=GRS80 + 683687.87 6099299.66 0.00 + + + $ echo 300000 6100000 0 0 | cct +proj=pipeline +step +inv +proj=utm +zone=33 +ellps=GRS80 +step +proj=utm +zone=32 +ellps=GRS80 + 683687.8667 6099299.6624 0.0000 0.0000 + +Lookout for the ``+inv`` in the first ``+step``, indicating an inverse transform. + + +Code example +############################################################################### + +The difference between the old and new API is shown here with a few examples. Below we implement the same program with the two different API's. The program reads input latitude and longitude from the command line and convert them to projected coordinates with the Mercator projection. -We start by writing the progran for PROJ v. 4: +We start by writing the program for PROJ v. 4: .. code-block:: C @@ -92,7 +149,6 @@ the destination. This is simple at a glance, but is actually a big conceptual change. We are now focused on the path between two systems instead of what the source and destination systems are. - Function mapping from old to new API ############################################################################### -- cgit v1.2.3 From 0ddbb3612928bf88eac686360a58ca5a9ac14b51 Mon Sep 17 00:00:00 2001 From: Thomas Knudsen Date: Fri, 23 Feb 2018 12:13:01 +0100 Subject: datatypes.rst: linuistics + INFO datatypes Some minor linguistic corrections + general update to make the documentation reflect the updates in PR #775 --- docs/source/development/reference/datatypes.rst | 79 +++++++++++++------------ 1 file changed, 40 insertions(+), 39 deletions(-) (limited to 'docs/source/development') diff --git a/docs/source/development/reference/datatypes.rst b/docs/source/development/reference/datatypes.rst index f2f1d9c9..7f2c4b41 100644 --- a/docs/source/development/reference/datatypes.rst +++ b/docs/source/development/reference/datatypes.rst @@ -4,7 +4,7 @@ Data types ================================================================================ -This section describe the multiplude of data types in use in PROJ.4. As a rule +This section describes the numerous data types in use in PROJ.4. As a rule of thumb PROJ.4 data types are prefixed with ``PJ_``, or in one particular case, is simply called :c:type:`PJ`. A few notable exceptions can be traced back to the very early days of PROJ.4 when the ``PJ_`` prefix was not @@ -16,8 +16,8 @@ Transformation objects .. c:type:: PJ Object containing everything related to a given projection or transformation. - As a user of the PROJ.4 library your are only exposed to pointers to this - object and the contents are hidden in the public API. :c:type:`PJ` objects + As a user of the PROJ.4 library you are only exposed to pointers to this + object and the contents is hidden behind the public API. :c:type:`PJ` objects are created with :c:func:`proj_create` and destroyed with :c:func:`proj_destroy`. @@ -51,7 +51,7 @@ Transformation objects .. c:type:: PJ_CONTEXT - Context objects enables safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` + Context objects enable safe multi-threaded usage of PROJ.4. Each :c:type:`PJ` object is connected to a context (if not specified, the default context is used). All operations within a context should be performed in the same thread. :c:type:`PJ_CONTEXT` objects are created with :c:func:`proj_context_create` @@ -97,11 +97,11 @@ Various 2-dimensional coordinate data types. typedef struct { double x, y; } PJ_XY; - .. c:member:: double PJ_XY.lam + .. c:member:: double PJ_XY.x Easting. - .. c:member:: double PJ_XY.phi + .. c:member:: double PJ_XY.y Northing. @@ -134,7 +134,7 @@ types above. .. c:type:: PJ_LPZ 3-dimensional version of :c:type:`PJ_LP`. Holds longitude, latitude and - vertical component. + a vertical component. .. code-block:: C @@ -163,15 +163,15 @@ types above. .. c:member:: double PJ_XYZ.x - Easting. + Easting or the X component of a 3D cartesian system. .. c:member:: double PJ_XYZ.y - Northing. + Northing or the Y component of a 3D cartesian system. .. c:member:: double PJ_XYZ.z - Vertical component. + Vertical component or the Z component of a 3D cartesian system. .. c:type:: PJ_UVW @@ -249,15 +249,15 @@ domain. .. c:member:: double PJ_XYZT.x - Easting. + Easting or the X component of a 3D cartesian system. .. c:member:: double PJ_XYZT.y - Northing. + Northing or the Y component of a 3D cartesian system. .. c:member:: double PJ_XYZT.z - Vertical component. + Vertical or the Z component of a 3D cartesian system. .. c:member:: double PJ_XYZT.t @@ -320,7 +320,7 @@ Complex coordinate types .. c:type:: PJ_COORD - General purpose coordinate union type usefull in two, three and four dimensions. + General purpose coordinate union type, applicable in two, three and four dimensions. This is the default coordinate datatype used in PROJ. .. code-block:: C @@ -385,9 +385,7 @@ Projection derivatives .. c:type:: PJ_FACTORS Various cartographic properties, such as scale factors, angular distortion - and meridian convergence. Calculated with :c:func:`proj_factors`. Depending - on the underlying projection, values can be calculated either numerically - or analytically. + and meridian convergence. Calculated with :c:func:`proj_factors`. .. code-block:: C @@ -434,13 +432,15 @@ Projection derivatives Meridian convergence at coordinate :math:`\left(\lambda,\phi\right)`. Sometimes also described as *grid declination*. + .. c:member:: double PJ_FACTORS.tissot_semimajor - Maximum scale error. + Maximum scale factor. .. c:member:: double PJ_FACTORS.tissot_semiminor - Minimum scale error. + Minimum scale factor. + .. c:member:: double PJ_FACTORS.dx_dlam @@ -449,7 +449,6 @@ Projection derivatives .. c:member:: double PJ_FACTORS.dy_dlam - Partial derivative :math:`\frac{\partial y}{\partial \lambda}` of coordinate :math:`\left(\lambda,\phi\right)`. @@ -460,7 +459,6 @@ Projection derivatives .. c:member:: double PJ_FACTORS.dy_dphi - Partial derivative :math:`\frac{\partial y}{\partial \phi}` of coordinate :math:`\left(\lambda,\phi\right)`. @@ -580,20 +578,20 @@ Info structures .. code-block:: C typedef struct { - char release[64]; - char version[64]; - int major; - int minor; - int patch; - char searchpath[512]; + int major; + int minor; + int patch; + const char *release; + const char *version; + const char *searchpath; } PJ_INFO; - .. c:member:: char PJ_INFO.release[64] + .. c:member:: const char *PJ_INFO.release Release info. Version number and release date, e.g. "Rel. 4.9.3, 15 August 2016". - .. c:member:: char PJ_INFO.version[64] + .. c:member:: const char *PJ_INFO.version Text representation of the full version number, e.g. "4.9.3". @@ -610,7 +608,7 @@ Info structures Patch level of release. - .. c:member:: char PJ_INFO.searchpath[512] + .. c:member:: const char PJ_INFO.searchpath Search path for PROJ. List of directories separated by semicolons (Windows) or colons (non-Windows), e.g. @@ -620,29 +618,32 @@ Info structures .. c:type:: PJ_PROJ_INFO Struct holding information about a :c:type:`PJ` object. Populated by - :c:func:`proj_pj_info`. + :c:func:`proj_pj_info`. The :c:type:`PJ_PROJ_INFO` object provides a + view into the internals of a :c:type:`PJ`, so once the :c:type:`PJ` + is destroyed or otherwise becomes invalid, so does the + :c:type:`PJ_PROJ_INFO` .. code-block:: C typedef struct { - char id[16]; - char description[128]; - char definition[512]; - int has_inverse; - double accuracy; + const char *id; + const char *description; + const char *definition; + int has_inverse; + double accuracy; } PJ_PROJ_INFO; - .. c:member:: char PJ_PROJ_INFO.id[16] + .. c:member:: const char *PJ_PROJ_INFO.id Short ID of the operation the :c:type:`PJ` object is based on, that is, what comes afther the ``+proj=`` in a proj-string, e.g. "*merc*". - .. c:member:: char PJ_PROJ_INFO.description[128] + .. c:member:: const char *PJ_PROJ_INFO.description Long describes of the operation the :c:type:`PJ` object is based on, e.g. "*Mercator Cyl, Sph&Ell lat_ts=*". - .. c:member:: char PJ_PROJ_INFO.definition[512] + .. c:member:: const char *PJ_PROJ_INFO.definition The proj-string that was used to create the :c:type:`PJ` object with, e.g. "*+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84*". -- cgit v1.2.3