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/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 + 4 files changed, 297 insertions(+) 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 (limited to 'docs/source/development/reference') 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 -- 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/reference') 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/reference') 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/reference') 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/reference') 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/reference') 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 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/reference') 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/reference') 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/reference') 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 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/reference') 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