Added functions API reference

1 files changed, 433 insertions, 0 deletions

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`)