diff options
Diffstat (limited to '_sources/development/reference/functions.rst.txt')
| -rw-r--r-- | _sources/development/reference/functions.rst.txt | 970 |
1 files changed, 970 insertions, 0 deletions
diff --git a/_sources/development/reference/functions.rst.txt b/_sources/development/reference/functions.rst.txt new file mode 100644 index 00000000..7a6b37a1 --- /dev/null +++ b/_sources/development/reference/functions.rst.txt @@ -0,0 +1,970 @@ +.. _functions: + +================================================================================ +Functions +================================================================================ + +Threading contexts +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_CONTEXT* proj_context_create(void) + + Create a new threading-context. + + :returns: a new context + +.. c:function:: PJ_CONTEXT* proj_context_clone(PJ_CONTEXT *ctx) + + .. versionadded:: 7.2 + + Create a new threading-context based on an existing context. + + :returns: a new context + +.. c:function:: void proj_context_destroy(PJ_CONTEXT *ctx) + + Deallocate a threading-context. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + + +Transformation setup +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The objects returned by the functions defined in this section have minimal +interaction with the functions of the +`C API for ISO-19111 functionality`_, and vice versa. See its introduction +paragraph for more details. + +.. c:function:: PJ* proj_create(PJ_CONTEXT *ctx, const char *definition) + + Create a transformation object, or a CRS object, from: + + - a proj-string, + - a WKT string, + - an object code (like "EPSG:4326", "urn:ogc:def:crs:EPSG::4326", + "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an Object name. e.g "WGS 84", "WGS 84 / UTM zone 31N". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for compound coordinate reference systems + (e.g "urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717" or custom abbreviated + syntax "EPSG:2393+5717"), + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.4/projjson.schema.json (*added in 6.2*) + - a compound CRS made from two object names separated with " + ". e.g. "WGS 84 + EGM96 height" (*added in 7.1*) + + Example call: + + .. code-block:: C + + PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel"); + + If a proj-string contains a +type=crs option, then it is interpreted as + a CRS definition. In particular geographic CRS are assumed to have axis + in the longitude, latitude order and with degree angular unit. The use + of proj-string to describe a CRS is discouraged. It is a legacy means of + conveying CRS descriptions: use of object codes (EPSG:XXXX typically) or + WKT description is recommended for better expressivity. + + If a proj-string does not contain +type=crs, then it is interpreted as a + coordination operation / transformation. + + If creation of the transformation object fails, the function returns `0` and + the PROJ error number is updated. The error number can be read with + :c:func:`proj_errno` or :c:func:`proj_context_errno`. + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_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 a transformation object, or a CRS 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); + + If there is a type=crs argument, then the arguments are interpreted as + a CRS definition. In particular geographic CRS are assumed to have axis + in the longitude, latitude order and with degree angular unit. + + If there is no type=crs argument, then it is interpreted as a + coordination operation / transformation. + + If creation of the transformation object fails, the function returns `0` and + the PROJ error number is updated. The error number can be read with + :c:func:`proj_errno` or :c:func:`proj_context_errno`. + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param argc: Count of arguments in :c:data:`argv` + :type argc: `int` + :param argv: Array of strings with proj-string parameters, e.g. ``+proj=merc`` + :type argv: `char **` + :returns: :c:type:`PJ` * + +.. c:function:: PJ* proj_create_crs_to_crs(PJ_CONTEXT *ctx, const char *source_crs, const char *target_crs, PJ_AREA *area) + + Create a transformation object that is a pipeline between two known + coordinate reference systems. + + source_crs and target_crs can be : + + - a "AUTHORITY:CODE", like EPSG:25832. When using that syntax for a source + CRS, the created pipeline will expect that the values passed to :c:func:`proj_trans` + respect the axis order and axis unit of the official definition ( + so for example, for EPSG:4326, with latitude first and longitude next, + in degrees). Similarly, when using that syntax for a target CRS, output + values will be emitted according to the official definition of this CRS. + + - a PROJ string, like "+proj=longlat +datum=WGS84". + When using that syntax, the axis order and unit for geographic CRS will + be longitude, latitude, and the unit degrees. + + - the name of a CRS as found in the PROJ database, e.g "WGS84", "NAD27", etc. + + - more generally any string accepted by :c:func:`proj_create` representing + a CRS + + An "area of use" can be specified in area. When it is supplied, the more + accurate transformation between two given systems can be chosen. + + When no area of use is specific and several coordinate operations are possible + depending on the area of use, this function will internally store those + candidate coordinate operations in the return PJ object. Each subsequent + coordinate transformation done with :c:func:`proj_trans` will then select + the appropriate coordinate operation by comparing the input coordinates with + the area of use of the candidate coordinate operations. + + Example call: + + .. code-block:: C + + PJ *P = proj_create_crs_to_crs(0, "EPSG:25832", "EPSG:25833", 0); + + If creation of the transformation object fails, the function returns `0` and + the PROJ error number is updated. The error number can be read with + :c:func:`proj_errno` or :c:func:`proj_context_errno`. + + + The returned :c:type:`PJ`-pointer should be deallocated with :c:func:`proj_destroy`. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param `source_crs`: Source CRS. + :type `source_crs`: `const char*` + :param `target_crs`: Destination SRS. + :type `target_crs`: `const char*` + :param `area`: Descriptor of the desired area for the transformation. + :type `area`: :c:type:`PJ_AREA` * + :returns: :c:type:`PJ` * + +.. c:function:: PJ* proj_create_crs_to_crs_from_pj(PJ_CONTEXT *ctx, PJ *source_crs, PJ *target_crs, PJ_AREA *area, const char* const *options) + + .. versionadded:: 6.2.0 + + Create a transformation object that is a pipeline between two known + coordinate reference systems. + + This is the same as :c:func:`proj_create_crs_to_crs` except that the source and + target CRS are passed as PJ* objects which must be of the CRS variety. + + :param `options`: a list of NUL terminated options, or NULL. + + The list of supported options is: + + - AUTHORITY=name: to restrict the authority of coordinate operations + looked up in the database. When not specified, coordinate + ``operations from any authority`` will be searched, with the restrictions set + in the authority_to_authority_preference database table related to the authority + of the source/target CRS themselves. + If authority is set to "any", then coordinate operations from any authority will be searched + If authority is a non-empty string different of ``any``, then coordinate operations + will be searched only in that authority namespace (e.g ``EPSG``). + + - ACCURACY=value: to set the minimum desired accuracy (in metres) of the + candidate coordinate operations. + + - ALLOW_BALLPARK=YES/NO: can be set to NO to disallow the use of + :term:`Ballpark transformation` in the candidate coordinate operations. + + - FORCE_OVER=YES/NO: can be set to YES to force the +over flag on the transformation + returned by this function. + +.. doxygenfunction:: proj_normalize_for_visualization + :project: doxygen_api + +.. c:function:: PJ* proj_destroy(PJ *P) + + Deallocate a :c:type:`PJ` transformation object. + + :param `P`: Transformation object + :type `P`: const :c:type:`PJ` * + :returns: :c:type:`PJ` * + +Area of interest +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. versionadded:: 6.0.0 + + +.. c:function:: PJ_AREA* proj_area_create(void) + + Create an area of use. + + Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to + specify the area of use for the choice of relevant coordinate operations. + + :returns: :c:type:`PJ_AREA` * to be deallocated with :c:func:`proj_area_destroy` + + +.. c:function:: void proj_area_set_bbox(PJ_AREA *area, double west_lon_degree, double south_lat_degree, double east_lon_degree, double north_lat_degree) + + Set the bounding box of the area of use + + Such an area of use is to be passed to :c:func:`proj_create_crs_to_crs` to + specify the area of use for the choice of relevant coordinate operations. + + In the case of an area of use crossing the antimeridian (longitude +/- 180 degrees), + `west_lon_degree` will be greater than `east_lon_degree`. + + :param `area`: Pointer to an object returned by :c:func:`proj_area_create`. + :param `west_lon_degree`: West longitude, in degrees. In [-180,180] range. + :param `south_lat_degree`: South latitude, in degrees. In [-90,90] range. + :param `east_lon_degree`: East longitude, in degrees. In [-180,180] range. + :param `north_lat_degree`: North latitude, in degrees. In [-90,90] range. + +.. c:function:: void proj_area_destroy(PJ_AREA* area) + + Deallocate a :c:type:`PJ_AREA` object. + + :param PJ_AREA* area + + +.. _coord_trans_functions: + +Coordinate transformation +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + + +.. c:function:: PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord) + + Transform a single :c:type:`PJ_COORD` coordinate. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Transformation direction. + :type `direction`: PJ_DIRECTION + :param coord: Coordinate that will be transformed. + :type coord: :c:type:`PJ_COORD` + :returns: :c:type:`PJ_COORD` + + +.. 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 + + 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 + + .. note:: Even though the coordinate components are named :c:data:`x`, :c:data:`y`, + :c:data:`z` and :c:data:`t`, axis ordering of the to and from CRS + is respected. Transformations exhibit the same behavior + as if they were gathered in a :c:type:`PJ_COORD` struct. + + + 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_trans_generic` 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_trans_generic ( + P, PJ_INV, + &(survey[0].x), stride, 345, /* We have 345 eastings */ + &(survey[0].y), stride, 345, /* ...and 345 northings. */ + &height, sizeof(double), 1, /* The height is the constant 23.45 m */ + 0, 0, 0 /* and the time is the constant 0.00 s */ + ); + + This is similar to the inner workings of the deprecated :c:func:`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_trans_generic` 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 P: Transformation object + :type P: :c:type:`PJ` * + :param direction: Transformation direction. + :type direction: PJ_DIRECTION + :param x: Array of x-coordinates + :type x: `double *` + :param sx: Step length, in bytes, between consecutive elements of the corresponding array + :type sx: `size_t` + :param nx: Number of elements in the corresponding array + :type nx: `size_t` + :param y: Array of y-coordinates + :type y: `double *` + :param sy: Step length, in bytes, between consecutive elements of the corresponding array + :type sy: `size_t` + :param ny: Number of elements in the corresponding array + :type ny: `size_t` + :param z: Array of z-coordinates + :type z: `double *` + :param sz: Step length, in bytes, between consecutive elements of the corresponding array + :type sz: `size_t` + :param nz: Number of elements in the corresponding array + :type nz: `size_t` + :param t: Array of t-coordinates + :type t: `double *` + :param st: Step length, in bytes, between consecutive elements of the corresponding array + :type st: `size_t` + :param nt: Number of elements in the corresponding array + :type nt: `size_t` + :returns: Number of transformations successfully completed + + + +.. c:function:: int proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) + + Batch transform an array of :c:type:`PJ_COORD`. + + Performs transformation on all points, even if errors occur on some points + (new to 8.0. Previous versions would exit early in case of failure on a given point) + + Individual points that fail to transform will have their components set to + ``HUGE_VAL`` + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Transformation direction. + :type `direction`: PJ_DIRECTION + :param n: Number of coordinates in :c:data:`coord` + :type n: `size_t` + :returns: `int` 0 if all observations are transformed without error, otherwise returns error number. + This error number will be a precise error number if all coordinates that fail to transform + for the same reason, or a generic error code if they fail for different + reasons. + + + +.. doxygenfunction:: proj_trans_bounds + :project: doxygen_api + + +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. In cases :c:data:`P` is `0` the error number of the default + context is read. A text representation of the error number can be retrieved + with :c:func:`proj_errno_string`. + + Consult :ref:`error_codes` for the list of error codes (PROJ >= 8.0) + + :param P: Transformation object + :type P: :c:type:`PJ` * + + :returns: `int` + +.. c:function:: int proj_context_errno(PJ_CONTEXT *ctx) + + Get a reading of the current error-state of :c:data:`ctx`. An non-zero error + codes indicates an error either with the transformation setup or during a + transformation. A text representation of the error number can be retrieved + with :c:func:`proj_errno_string`. + + Consult :ref:`error_codes` for the list of error codes (PROJ >= 8.0) + + :param ctx: threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + + :returns: `int` + +.. c:function:: void proj_errno_set(PJ *P, int err) + + Change the error-state of :c:data:`P` to `err`. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param err: Error number. + :type err: `int` + +.. 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 P: Transformation object + :type P: :c:type:`PJ` * + + :returns: `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 P: Transformation object + :type P: :c:type:`PJ` * + :param err: Error number. + :type err: `int` + +.. c:function:: const char* proj_errno_string(int err) + + .. versionadded:: 5.1.0 + + Get a text representation of an error number. + + .. deprecated:: This function is potentially thread-unsafe, replaced by :c:func:`proj_context_errno_string`. + + :param err: Error number. + :type err: `int` + + :returns: `const char*` String with description of error. + +.. c:function:: const char* proj_context_errno_string(PJ_CONTEXT* ctx, int err) + + .. versionadded:: 8.0.0 + + Get a text representation of an error number. + + :param ctx: threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + + :param err: Error number. + :type err: `int` + + :returns: `const char*` String with description of error. + +Logging +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_LOG_LEVEL proj_log_level (PJ_CONTEXT *ctx, PJ_LOG_LEVEL level) + + Get and set logging level for a given context. Changes the log level to + :c:data:`level` and returns the previous logging level. If called with + :c:data:`level` set to :c:type:`PJ_LOG_TELL` the function returns the current + logging level without changing it. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param level: New logging level. + :type level: PJ_LOG_LEVEL + + :returns: :c:type:`PJ_LOG_LEVEL` + + .. versionadded:: 5.1.0 + +.. c:function:: void proj_log_func (PJ_CONTEXT *ctx, void *app_data, PJ_LOG_FUNCTION logf) + + Override the internal log function of PROJ. + + :param ctx: Threading context. + :type ctx: :c:type:`PJ_CONTEXT` * + :param app_data: Pointer to data structure used by the calling application. + :type app_data: `void *` + :param logf: Log function that overrides the PROJ log function. + :type logf: :c:type:`PJ_LOG_FUNCTION` + + .. versionadded:: 5.1.0 + +Info functions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: PJ_INFO proj_info(void) + + Get information about the current instance of the PROJ 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 :c:type:`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 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 searchpath + :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. 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: + + .. code-block:: C + + PJ_OPERATIONS *ops; + for (ops = proj_list_operations(); ops->id; ++ops) + printf("%s\n", ops->id); + + + :returns: const :c:type:`PJ_OPERATIONS` * + +.. c:function:: const PJ_ELLPS* proj_list_ellps(void) + + 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. + + :returns: const :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. 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. + + Note: starting with PROJ 7.1, this function is deprecated by + :cpp:func:`proj_get_units_from_database` + + :returns: const :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. 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: const :c:type:`PJ_PRIME_MERIDIANS` * + +Distances +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: double proj_lp_dist(const PJ *P, PJ_COORD a, PJ_COORD b) + + Calculate geodesic distance between two points in geodetic coordinates. The + calculated distance is between the two points located on the ellipsoid. + + The coordinates in :c:data:`a` and :c:data:`b` needs to be given as longitude + and latitude in radians. Note that the axis order of the :c:data:`P` object + is not taken into account in this function, so even though a CRS object comes + with axis ordering latitude/longitude coordinates used in this function should + be reordered as longitude/latitude. + + :param P: Transformation or CRS object + :type P: const :c:type:`PJ` * + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_lpz_dist(const PJ *P, PJ_COORD a, PJ_COORD b) + + Calculate geodesic distance between two points in geodetic coordinates. + Similar to :c:func:`proj_lp_dist` but also takes the height above the ellipsoid + into account. + + The coordinates in :c:data:`a` and :c:data:`b` needs to be given as longitude + and latitude in radians. Note that the axis order of the :c:data:`P` object + is not taken into account in this function, so even though a CRS object comes + with axis ordering latitude/longitude coordinates used in this function should + be reordered as longitude/latitude. + + :param P: Transformation or CRS object + :type P: const :c:type:`PJ` * + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xy_dist(PJ_COORD a, PJ_COORD b) + + Calculate 2-dimensional euclidean between two projected coordinates. + + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: double proj_xyz_dist(PJ_COORD a, PJ_COORD b) + + Calculate 3-dimensional euclidean between two projected coordinates. + + :param PJ_COORD a: First coordinate + :param PJ_COORD b: Second coordinate + :returns: `double` Distance between :c:data:`a` and :c:data:`b` in meters. + +.. c:function:: PJ_COORD proj_geod(const PJ *P, PJ_COORD a, PJ_COORD b) + + Calculate the geodesic distance as well as forward and reverse azimuth + between two points on the ellipsoid. + + The coordinates in :c:data:`a` and :c:data:`b` needs to be given as longitude + and latitude in radians. Note that the axis order of the :c:data:`P` object + is not taken into account in this function, so even though a CRS object comes + with axis ordering latitude/longitude coordinates used in this function should + be reordered as longitude/latitude. + + :param P: Transformation or CRS object + :type P: const :c:type:`PJ` * + :param PJ_COORD a: Coordinate of first point + :param PJ_COORD b: Coordinate of second point + :returns: `PJ_COORD` where the first value is the distance between :c:data:`a` + and :c:data:`b` in meters, the second value is the forward azimuth + and the third value is the reverse azimuth. The fourth coordinate + value is unused. + + + +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 x: 1st component in a :c:type:`PJ_COORD` + :type x: `double` + :param y: 2nd component in a :c:type:`PJ_COORD` + :type y: `double` + :param z: 3rd component in a :c:type:`PJ_COORD` + :type z: `double` + :param t: 4th component in a :c:type:`PJ_COORD` + :type t: `double` + :returns: :c:type:`PJ_COORD` + + +.. c:function:: double proj_roundtrip(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coord) + + 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:`coo` and the resulting + coordinate after :c:data:`n` iterations back and forth. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :param n: Number of roundtrip transformations + :type n: `int` + :param coord: Input coordinate + :type coord: :c:type:`PJ_COORD` * + :returns: `double` Distance between original coordinate and the \ + resulting coordinate after :c:data:`n` transformation iterations. + +.. 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 + values will be calculated either numerically (default) or analytically. + + Starting with PROJ 8.2, the P object can be a projected CRS, for example + instantiated from a EPSG CRS code. The factors computed will be those of the + map projection implied by the transformation from the base geographic CRS of + the projected CRS to the projected CRS. + + The input geodetic coordinate lp should be such that lp.lam is the longitude + in radian, and lp.phi the latitude in radian (thus independently of the + definition of the base CRS, if P is a projected CRS). + + The function also calculates the partial derivatives of the given + coordinate. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `lp`: Geodetic coordinate + :type `lp`: :c:type:`PJ_COORD` + :returns: :c:type:`PJ_FACTORS` + +.. c:function:: double proj_torad(double angle_in_degrees) + + Convert degrees to radians. + + :param angle_in_degrees: Degrees + :type angle_in_degrees: `double` + :returns: `double` Radians + +.. c:function:: double proj_todeg(double angle_in_radians) + + Convert radians to degrees + + :param angle_in_radians: Radians + :type angle_in_radians: `double` + :returns: `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 s: Buffer that holds the output string + :type s: `char *` + :param r: Value to convert to dms-representation + :type r: `double` + :param pos: Character denoting positive direction, typically `'N'` or `'E'`. + :type pos: `int` + :param neg: Character denoting negative direction, typically `'S'` or `'W'`. + :type neg: `int` + :returns: `char*` Pointer to output buffer (same as :c:data:`s`) + + +.. c:function:: int proj_angular_input (PJ *P, enum PJ_DIRECTION dir) + + Check if an operation expects input in radians or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if input units is expected in radians, otherwise 0 + +.. c:function:: int proj_angular_output (PJ *P, enum PJ_DIRECTION dir) + + Check if an operation returns output in radians or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if output units is expected in radians, otherwise 0 + +.. c:function:: int proj_degree_input (PJ *P, enum PJ_DIRECTION dir) + + .. versionadded:: 7.1.0 + + Check if an operation expects input in degrees or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if input units is expected in degrees, otherwise 0 + +.. c:function:: int proj_degree_output (PJ *P, enum PJ_DIRECTION dir) + + .. versionadded:: 7.1.0 + + Check if an operation returns output in degrees or not. + + :param P: Transformation object + :type P: :c:type:`PJ` * + :param `direction`: Starting direction of transformation + :type `direction`: PJ_DIRECTION + :returns: `int` 1 if output units is expected in degrees, otherwise 0 + + +Setting custom I/O functions +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. versionadded:: 7.0.0 + +.. doxygenfunction:: proj_context_set_fileapi + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_sqlite3_vfs_name + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_file_finder + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_search_paths + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_ca_bundle_path + :project: doxygen_api + + +Network related functionality +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. versionadded:: 7.0.0 + +.. doxygenfunction:: proj_context_set_network_callbacks + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_enable_network + :project: doxygen_api + +.. doxygenfunction:: proj_context_is_network_enabled + :project: doxygen_api + +.. doxygenfunction:: proj_context_set_url_endpoint + :project: doxygen_api + +.. doxygenfunction:: proj_context_get_url_endpoint + :project: doxygen_api + +.. doxygenfunction:: proj_context_get_user_writable_directory + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_enable + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_filename + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_max_size + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_set_ttl + :project: doxygen_api + +.. doxygenfunction:: proj_grid_cache_clear + :project: doxygen_api + +.. doxygenfunction:: proj_is_download_needed + :project: doxygen_api + +.. doxygenfunction:: proj_download_file + :project: doxygen_api + + +Cleanup +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. c:function:: void proj_cleanup() + + .. versionadded:: 6.2.0 + + This function frees global resources (grids, cache of +init files). It + should be called typically before process termination, and *after* having + freed PJ and PJ_CONTEXT objects. + + +C API for ISO-19111 functionality ++++++++++++++++++++++++++++++++++ + +.. versionadded:: 6.0.0 + +The PJ* objects returned by :c:func:`proj_create_from_wkt`, +:c:func:`proj_create_from_database` and other functions in that section +will have generally minimal interaction with the functions declared in the +previous sections (calling those functions on those objects +will either return an error or default/nonsensical values). The exception is +for ISO19111 objects of type CoordinateOperation that can be exported as a +valid PROJ pipeline. In this case, objects will work for example with +:c:func:`proj_trans_generic`. +Conversely, objects returned by :c:func:`proj_create` and :c:func:`proj_create_argv`, +which are not of type CRS (can be tested with :c:func:`proj_is_crs`), +will return an error when used with functions of this section. + +.. doxygengroup:: iso19111_functions + :project: doxygen_api + :content-only: + |