diff options
Diffstat (limited to 'docs/source/development/reference')
| -rw-r--r-- | docs/source/development/reference/datatypes.rst | 389 | ||||
| -rw-r--r-- | docs/source/development/reference/functions.rst | 109 |
2 files changed, 104 insertions, 394 deletions
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 + |