Skip to content

Latest commit

 

History

History
786 lines (523 loc) · 28.6 KB

functions.rst

File metadata and controls

786 lines (523 loc) · 28.6 KB
Raw

Functions

Threading contexts

Transformation setup

The objects returned by the functions defined in this section have minimal interaction with the the functions of the C API for ISO-19111 functionality, and vice versa. See its introduction paragraph for more details.

Area of interest

6.0.0

Coordinate transformation

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 he coordinate components are named :cx, :cy, :cz and :ct, axis ordering of the to and from CRS is respected. Transformations exhibit the same behaviour as if they were gathered in a :cPJ_COORD struct.

The strides, :csx, :csy, :csz, :cst, represent the step length, in bytes, between consecutive elements of the corresponding array. This makes it possible for :cproj_trans_generic to handle transformation of a large class of application specific data structures, without necessarily understanding the data structure format, as in:

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 :cpj_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 :cx, :cy, :cz, and :ct come from heterogeneous sources, individual strides, :csx, :csy, :csz, :cst, are used.

Note

Since :cproj_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 PJ* P

Transformation object

param direction

Transformation 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

param double* t

Array of t-coordinates

param size_t sx

Step length, 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 length, 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 length, 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 length, in bytes, between consecutive elements of the corresponding array

param size_t nt

Number of elements in the corresponding array

returns

Number of transformations successfully completed

Error reporting

Change the error-state of :cP to err.

param PJ* P

Transformation object.

param int err

Error number.

Logging

Info functions

Lists

Distances

Various

Setting custom I/O functions

7.0.0

proj_context_set_fileapi

proj_context_set_sqlite3_vfs_name

Network related functionality

7.0.0

proj_context_set_network_callbacks

proj_context_set_enable_network

proj_context_is_network_enabled

proj_context_set_url_endpoint

proj_grid_cache_set_enable

proj_grid_cache_set_filename

proj_grid_cache_set_max_size

proj_grid_cache_set_ttl

proj_grid_cache_clear

proj_is_download_needed

proj_download_file

Cleanup

C API for ISO-19111 functionality

6.0.0

The PJ* objects returned by :cproj_create_from_wkt, :cproj_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/non-sensical 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 :cproj_trans_generic. Conversely, objects returned by :cproj_create and :cproj_create_argv, which are not of type CRS (can be tested with :cproj_is_crs), will return an error when used with functions of this section.

iso19111_functions