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/functions.rst | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/source/development/reference/functions.rst (limited to 'docs/source/development/reference/functions.rst') 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 +================================================================================ + + -- 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/functions.rst') 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/functions.rst') 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/functions.rst | 27 ++++++++++++++----------- 1 file changed, 15 insertions(+), 12 deletions(-) (limited to 'docs/source/development/reference/functions.rst') 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/functions.rst | 43 +++++++++++++++++++++++++ 1 file changed, 43 insertions(+) (limited to 'docs/source/development/reference/functions.rst') 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/functions.rst | 109 ++++++++++++++---------- 1 file changed, 63 insertions(+), 46 deletions(-) (limited to 'docs/source/development/reference/functions.rst') 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/functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source/development/reference/functions.rst') 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/functions.rst | 156 +++++++++--------------- 1 file changed, 56 insertions(+), 100 deletions(-) (limited to 'docs/source/development/reference/functions.rst') 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