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