Functions¶
Threading contexts¶

PJ_CONTEXT*
proj_context_create
(void)¶ Create a new threadingcontext.
Returns: PJ_CONTEXT*

void
proj_context_destroy
(PJ_CONTEXT *ctx)¶ Deallocate a threadingcontext.
Parameters:  ctx (PJ_CONTEXT*) – Threading context.
Transformation setup¶

PJ*
proj_create
(PJ_CONTEXT *ctx, const char *definition)¶ Create a transformation object from a projstring.
Example call:
PJ *P = proj_create(0, "+proj=etmerc +lat_0=38 +lon_0=125 +ellps=bessel");
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
proj_errno()
orproj_context_errno()
.The returned
PJ
pointer should be deallocated withproj_destroy()
.Parameters:  ctx (PJ_CONTEXT*) – Threading context.
 definition (const char*) – Projstring of the desired transformation.

PJ*
proj_create_argv
(PJ_CONTEXT *ctx, int argc, char **argv)¶ Create transformation object with argc/argvstyle initialization. For this application each parameter in the defining projstring is an entry in
argv
.Example call:
char *args[3] = {"proj=utm", "zone=32", "ellps=GRS80"}; PJ* P = proj_create_argv(0, 3, args);
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
proj_errno()
orproj_context_errno()
.The returned
PJ
pointer should be deallocated withproj_destroy()
.Parameters:  ctx (PJ_CONTEXT*) – Threading context
 argc (int) – Count of arguments in
argv
 argv (char**) – Vector of strings with projstring parameters, e.g.
+proj=merc
Returns:

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.
srid_from
andsrid_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 initfile inPROJ_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 “earlybinding” by the EPSG. The function can be extended to support “latebinding” transformations in the future without affecting users of the function. When the function is extended to the latebinding approach the
area
argument will be used. For now it is just a placeholder for a future improved implementation.Example call:
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
proj_errno()
orproj_context_errno()
.The returned
PJ
pointer should be deallocated withproj_destroy()
.Parameters:  ctx (PJ_CONTEXT*) – Threading context.
 srid_from (const char*) – Source SRID.
 srid_to (const char*) – Destination SRID.
 area (PJ_AREA) – Descriptor of the desired area for the transformation.
Returns:
Coordinate transformation¶

PJ_COORD
proj_trans
(PJ *P, PJ_DIRECTION direction, PJ_COORD coord)¶ Transform a single
PJ_COORD
coordinate.Parameters:  P (PJ*) –
 direction (PJ_DIRECTION) – Transformation direction.
 coord (PJ_COORD) – Coordinate that will be transformed.
Returns:

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
 fully populated
 a null pointer and/or a length of zero, which will be treated as a fully populated array of zeroes
 of length one, i.e. a constant, which will be treated as a fully populated array of that constant value
The strides,
sx
,sy
,sz
,st
, represent the step length, in bytes, between consecutive elements of the corresponding array. This makes it possible forproj_transform()
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, 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
x
,y
,z
, andt
come from heterogeneous sources, individual strides,sx
,sy
,sz
,st
, are used.Note
Since
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.Parameters:  P (PJ*) – Transformation object
 direction – Transformation direction
 x (double*) – Array of xcoordinates
 y (double*) – Array of ycoordinates
 z (double*) – Array of zcoordinates
 t (double*) – Array of tcoordinates
 sx (size_t) – Step length, in bytes, between consecutive elements of the corresponding array
 nx (size_t) – Number of elements in the corresponding array
 sy (size_t) – Step length, in bytes, between consecutive elements of the corresponding array
 nv (size_t) – Number of elements in the corresponding array
 sz (size_t) – Step length, in bytes, between consecutive elements of the corresponding array
 nz (size_t) – Number of elements in the corresponding array
 st (size_t) – Step length, in bytes, between consecutive elements of the corresponding array
 nt (size_t) – Number of elements in the corresponding array
Returns: Number of transformations successfully completed

size_t
proj_trans_array
(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord)¶ Batch transform an array of
PJ_COORD
.Parameters:  P (PJ*) –
 direction (PJ_DIRECTION) – Transformation direction
 n (size_t) – Number of coordinates in
coord
Returns: size_t
0 if all observations are transformed without error, otherwise returns error number
Error reporting¶

int
proj_errno
(PJ *P)¶ Get a reading of the current errorstate of
P
. An nonzero error codes indicates an error either with the transformation setup or during a transformation. In casesP
is 0 the error number of the default context is read. A text representation of the error number can be retrieved withproj_errno_string()
.Param: PJ* P: Transformation object. Returns: int

int
proj_context_errno
(PJ_CONTEXT *ctx)¶ Get a reading of the current errorstate of
ctx
. An nonzero error codes indicates an error either with the transformation setup or during a transformation. A text representation of the error number can be retrieved withproj_errno_string()
.Param: PJ_CONTEXT* ctx: threading context. Returns: int
Change the errorstate of P
to err.
param PJ* P: Transformation object. param int err: Error number.

int
proj_errno_reset
(PJ *P)¶ Clears the error number in
P
, and bubbles it up to the context.Example:
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: int
Returns the previous value of the errno, for convenient reset/restore operations.

void
proj_errno_restore
(PJ *P, int err)¶ Reduce some mental impedance in the canonical reset/restore use case: Basically,
proj_errno_restore()
is a synonym forproj_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
proj_errno_reset()
Parameters:  P (PJ*) – Transformation object.
 err (int) – Error code.

const char*
proj_errno_string
(int err)¶ New in version 5.1.0.
Get a text representation of an error number.
Parameters:  err (int) – Error number.
Returns: const char*
String with description of error.
Logging¶

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
level
and returns the previous logging level. If called withlevel
set toPJ_LOG_TELL
the function returns the current logging level without changing it.Parameters:  ctx (PJ_CONTEXT*) – Threading context.
 level (PJ_LOG_LEVEL) – New logging level.
Returns: New in version 5.1.0.

void
proj_log_func
(PJ_CONTEXT *ctx, void *app_data, PJ_LOG_FUNCTION logf)¶ Override the internal log function of PROJ.
Parameters:  ctx (PJ_CONTEXT*) – Threading context.
 app_data (void*) – Pointer to data structure used by the calling application.
 logf (PJ_LOG_FUNCTION) – Log function that overrides the PROJ log function.
New in version 5.1.0.
Info functions¶

PJ_INFO
proj_info
(void)¶ Get information about the current instance of the PROJ library.
Returns: PJ_INFO

PJ_PROJ_INFO
proj_pj_info
(const PJ *P)¶ Get information about a specific transformation object,
P
.Parameters:  P (const PJ*) – Transformation object
Returns:

PJ_GRID_INFO
proj_grid_info
(const char *gridname)¶ Get information about a specific grid.
Parameters:  gridname (const char*) – Gridname in the PROJ searchpath
Returns:

PJ_INIT_INFO
proj_init_info
(const char *initname)¶ Get information about a specific init file.
Parameters:  initname (const char*) – Init file in the PROJ searchpath
Returns:
Lists¶

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 NULLentry. The array is statically allocated and does not need to be freed after use.
Print a list of all operations in PROJ:
PJ_OPERATIONS *ops; for (ops = proj_list_operations(); ops>id; ++ops) printf("%s\n", ops>id);
Returns: PJ_OPERATIONS*

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 NULLentry. The array is statically allocated and does not need to be freed after use.
Returns: PJ_ELLPS*

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 NULLentry. The array is statically allocated and does not need to be freed after use.
Returns: PJ_UNITS*

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 NULLentry. The array is statically allocated and does not need to be freed after use.
Returns: PJ_PRIME_MERIDIANS*
Distances¶

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.
Parameters: Returns: double
Distance betweena
andb
in meters.

double
proj_lpz_dist
(const PJ *P, PJ_COORD a, PJ_COORD b)¶ Calculate geodesic distance between two points in geodetic coordinates. Similar to
proj_lp_dist()
but also takes the height above the ellipsoid into account.Parameters: Returns: double
Distance betweena
andb
in meters.
Various¶

PJ_COORD
proj_coord
(double x, double y, double z, double t)¶ Initializer for the
PJ_COORD
union. The function is shorthand for the otherwise convoluted assignment. Equivalent toPJ_COORD c = {{10.0, 20.0, 30.0, 40.0}};
or
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
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.PJ_UVWT
orPJ_LPZT
.Parameters: Returns:

double
proj_roundtrip
(PJ *P, PJ_DIRECTION direction, int n, PJ_COORD *coord)¶ Measure internal consistency of a given transformation. The function performs
n
round trip transformations starting in either the forward or reversedirection
. Returns the euclidean distance of the starting pointcoo
and the resulting coordinate aftern
iterations back and forth.Parameters:  P (const PJ*) –
 direction (PJ_DIRECTION) – Starting direction of transformation
 n (int) – Number of roundtrip transformations
 coord (PJ_COORD) – Input coordinate
Returns: double
Distance between original coordinate and the resulting coordinate aftern
transformation iterations.

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.
The function also calculates the partial derivatives of the given coordinate.
Parameters:  P (const PJ*) – Transformation object
 lp (const PJ_COORD) – Geodetic coordinate
Returns:

double
proj_torad
(double angle_in_degrees)¶ Convert degrees to radians.
Parameters:  angle_in_degrees (double) – Degrees
Returns: double
Radians

double
proj_todeg
(double angle_in_radians)¶ Convert radians to degrees
Parameters:  angle_in_radians (double) – Radians
Returns: double
Degrees

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
strtod()
.Parameters:  is (const char*) – Value to be converted to radians
 rs – Reference to an already allocated char*, whose value is set by the function to the next character in
is
after the numerical value.

char *
proj_rtodms
(char *s, double r, int pos, int neg)¶ Convert radians to string representation of degrees, minutes and seconds.
Parameters:  s (char*) – Buffer that holds the output string
 r (double) – Value to convert to dmsrepresentation
 pos (int) – Character denoting positive direction, typically ‘N’ or ‘E’.
 neg (int) – Character denoting negative direction, typically ‘S’ or ‘W’.
Returns: char*
Pointer to output buffer (same ass
)

PJ_COORD
proj_geocentric_latitude
(const PJ *P, PJ_DIRECTION direction, PJ_COORD coord)¶ Convert from geographical latitude to geocentric latitude.
Parameters:  P (const PJ*) – Transformation object
 direction (PJ_DIRECTION) – Starting direction of transformation
 coord (PJ_COORD) – Coordinate
Returns: PJ_COORD
Converted coordinate

int
proj_angular_input
(PJ *P, enum PJ_DIRECTION dir)¶ Check if a operation expects angular input.
Parameters:  P (const PJ*) – Transformation object
 direction (PJ_DIRECTION) – Starting direction of transformation
Returns: int
1 if angular input is expected, otherwise 0

int
proj_angular_output
(PJ *P, enum PJ_DIRECTION dir)¶ Check if an operation returns angular output.
Parameters:  P (const PJ*) – Transformation object
 direction (PJ_DIRECTION) – Starting direction of transformation
Returns: int
1 if angular output is returned, otherwise 0