Functions¶

Threading contexts¶

PJ_CONTEXT *proj_context_create(void)¶

Create a new threading-context.

Returns: a new context

PJ_CONTEXT *proj_context_clone(PJ_CONTEXT *ctx)¶

New in version 7.2.

Create a new threading-context based on an existing context.

Returns: a new context

void proj_context_destroy(PJ_CONTEXT *ctx)¶

Deallocate a threading-context.

Parameters

ctx (PJ_CONTEXT *) -- Threading 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.

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:

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 proj_errno() or proj_context_errno().

The returned PJ-pointer should be deallocated with proj_destroy().

Parameters

ctx (PJ_CONTEXT *) -- Threading context.
definition (const char*) -- Proj-string of the desired transformation.

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 argv.

Example call:

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 proj_errno() or proj_context_errno().

The returned PJ-pointer should be deallocated with proj_destroy().

Parameters

ctx (PJ_CONTEXT *) -- Threading context.
argc (int) -- Count of arguments in argv
argv (char **) -- Array of strings with proj-string parameters, e.g. +proj=merc

Returns

PJ *

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 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 proj_create() representing a CRS

Starting with PROJ 9.2, source_crs or target_crs can be a CoordinateMetadata with an associated coordinate epoch (but only one of them, not both).

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 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:

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() or proj_context_errno().

The returned PJ-pointer should be deallocated with proj_destroy().

Parameters

ctx (PJ_CONTEXT *) -- Threading context.
source_crs (const char*) -- Source CRS or CoordinateMetadata.
target_crs (const char*) -- Destination SRS or CoordinateMetadata
area (PJ_AREA *) -- Descriptor of the desired area for the transformation.

Returns

PJ *

PJ *proj_create_crs_to_crs_from_pj(PJ_CONTEXT *ctx, PJ *source_crs, PJ *target_crs, PJ_AREA *area, const char *const *options)¶

New in version 6.2.0.

Create a transformation object that is a pipeline between two known coordinate reference systems.

This is the same as proj_create_crs_to_crs() except that the source and target CRS are passed as PJ* objects which must be of the CRS variety.

Starting with PROJ 9.2, source_crs or target_crs can be a CoordinateMetadata with an associated coordinate epoch (but only one of them, not both).

Parameters

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 Ballpark transformation in the candidate coordinate operations.
ONLY_BEST=YES/NO: (PROJ >= 9.2) Can be set to YES to cause PROJ to error out if the best transformation, known of PROJ, and usable by PROJ if all grids known and usable by PROJ were accessible, cannot be used. Best transformation should be understood as the transformation returned by proj_get_suggested_operation() if all known grids were accessible (either locally or through network). Note that the default value for this option can be also set with the PROJ_ONLY_BEST_DEFAULT environment variable, or with the only_best_default setting of proj.ini (the ONLY_BEST option when specified overrides such default value).
FORCE_OVER=YES/NO: can be set to YES to force the +over flag on the transformation returned by this function. See Longitude Wrapping

PJ *proj_normalize_for_visualization(PJ_CONTEXT *ctx, const PJ *obj)¶

Returns a PJ* object whose axis order is the one expected for visualization purposes.

The input object must be either:

a coordinate operation, that has been created with proj_create_crs_to_crs(). If the axis order of its source or target CRS is northing,easting, then an axis swap operation will be inserted.
or a CRS. The axis order of geographic CRS will be longitude, latitude [,height], and the one of projected CRS will be easting, northing [, height]

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object of type CRS, or CoordinateOperation created with proj_create_crs_to_crs() (must not be NULL)

Returns

a new PJ* object to free with proj_destroy() in case of success, or nullptr in case of error

PJ *proj_destroy(PJ *P)¶

Deallocate a PJ transformation object.

Parameters

P (const PJ *) -- Transformation object

Returns

PJ *

Area of interest¶

New in version 6.0.0.

PJ_AREA *proj_area_create(void)¶

Create an area of use.

Such an area of use is to be passed to proj_create_crs_to_crs() to specify the area of use for the choice of relevant coordinate operations.

Returns: PJ_AREA * to be deallocated with proj_area_destroy()

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 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.

Parameters

area -- Pointer to an object returned by proj_area_create().
west_lon_degree -- West longitude, in degrees. In [-180,180] range.
south_lat_degree -- South latitude, in degrees. In [-90,90] range.
east_lon_degree -- East longitude, in degrees. In [-180,180] range.
north_lat_degree -- North latitude, in degrees. In [-90,90] range.

void proj_area_destroy(PJ_AREA *area)¶

Deallocate a PJ_AREA object.

:param PJ_AREA* area

Coordinate transformation¶

PJ_COORD proj_trans(PJ *P, PJ_DIRECTION direction, PJ_COORD coord)¶

Transform a single PJ_COORD coordinate.

If the input coordinate contains any NaNs you are guaranteed to get a coordinate with all NaNs as a result.

Changed in version 9.2.0: Define NaN handling. Prior NaN handling behavior was undefined.

Parameters

P (PJ *) -- Transformation object
direction (PJ_DIRECTION) -- Transformation direction.
coord (PJ_COORD) -- Coordinate that will be transformed.

Returns

PJ_COORD

PJ *proj_trans_get_last_used_operation(PJ *P)¶

New in version 9.1.0.

Return the operation used during the last invocation of proj_trans(). This is especially useful when P has been created with proj_create_crs_to_crs() and has several alternative operations. The returned object must be freed with proj_destroy().

Parameters

P (PJ *) -- Transformation object

Returns

PJ *

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

Note

Even though the coordinate components are named x, y, z and t, axis ordering of the to and from CRS is respected. Transformations exhibit the same behavior as if they were gathered in a PJ_COORD struct.

The strides, sx, sy, sz, st, represent the step length, in bytes, between consecutive elements of the corresponding array. This makes it possible for proj_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 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, and t come from heterogeneous sources, individual strides, sx, sy, sz, st, are used.

Note

Since 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.

Parameters

P (PJ *) -- Transformation object
direction (PJ_DIRECTION) -- Transformation direction.
x (double *) -- Array of x-coordinates
sx (size_t) -- Step length, in bytes, between consecutive elements of the corresponding array
nx (size_t) -- Number of elements in the corresponding array
y (double *) -- Array of y-coordinates
sy (size_t) -- Step length, in bytes, between consecutive elements of the corresponding array
ny (size_t) -- Number of elements in the corresponding array
z (double *) -- Array of z-coordinates
sz (size_t) -- Step length, in bytes, between consecutive elements of the corresponding array
nz (size_t) -- Number of elements in the corresponding array
t (double *) -- Array of t-coordinates
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

int proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord)¶

Batch transform an array of 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

Parameters

P (PJ *) -- Transformation object
direction (PJ_DIRECTION) -- Transformation direction.
n (size_t) -- Number of coordinates in coord

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.

int proj_trans_bounds(PJ_CONTEXT *context, PJ *P, PJ_DIRECTION direction, double xmin, double ymin, double xmax, double ymax, double *out_xmin, double *out_ymin, double *out_xmax, double *out_ymax, int densify_pts)¶

Transform boundary,.

Transform boundary densifying the edges to account for nonlinear transformations along these edges and extracting the outermost bounds.

If the destination CRS is geographic, the first axis is longitude, and xmax < xmin then the bounds crossed the antimeridian. In this scenario there are two polygons, one on each side of the antimeridian. The first polygon should be constructed with (xmin, ymin, 180, ymax) and the second with (-180, ymin, xmax, ymax).

If the destination CRS is geographic, the first axis is latitude, and ymax < ymin then the bounds crossed the antimeridian. In this scenario there are two polygons, one on each side of the antimeridian. The first polygon should be constructed with (ymin, xmin, ymax, 180) and the second with (ymin, -180, ymax, xmax).

Since: 8.2

Parameters

context -- The PJ_CONTEXT object.
P -- The PJ object representing the transformation.
direction -- The direction of the transformation.
xmin -- Minimum bounding coordinate of the first axis in source CRS (target CRS if direction is inverse).
ymin -- Minimum bounding coordinate of the second axis in source CRS. (target CRS if direction is inverse).
xmax -- Maximum bounding coordinate of the first axis in source CRS. (target CRS if direction is inverse).
ymax -- Maximum bounding coordinate of the second axis in source CRS. (target CRS if direction is inverse).
out_xmin -- Minimum bounding coordinate of the first axis in target CRS (source CRS if direction is inverse).
out_ymin -- Minimum bounding coordinate of the second axis in target CRS. (source CRS if direction is inverse).
out_xmax -- Maximum bounding coordinate of the first axis in target CRS. (source CRS if direction is inverse).
out_ymax -- Maximum bounding coordinate of the second axis in target CRS. (source CRS if direction is inverse).
densify_pts -- Recommended to use 21. This is the number of points to use to densify the bounding polygon in the transformation.

Returns

an integer. 1 if successful. 0 if failures encountered.

Error reporting¶

int proj_errno(PJ *P)¶

Get a reading of the current error-state of P. An non-zero error codes indicates an error either with the transformation setup or during a transformation. In cases P is 0 the error number of the default context is read. A text representation of the error number can be retrieved with proj_errno_string().

Consult Error codes for the list of error codes (PROJ >= 8.0)

Parameters

P (PJ *) -- Transformation object

Returns

int

int proj_context_errno(PJ_CONTEXT *ctx)¶

Get a reading of the current error-state of 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 proj_errno_string().

Consult Error codes for the list of error codes (PROJ >= 8.0)

Parameters

ctx (PJ_CONTEXT *) -- threading context.

Returns

int

void proj_errno_set(PJ *P, int err)¶

Change the error-state of P to err.

Parameters

P (PJ *) -- Transformation object
err (int) -- 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;
}

Parameters

P (PJ *) -- 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 for 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 proj_errno_reset()

Parameters

P (PJ *) -- Transformation object
err (int) -- Error number.

const char *proj_errno_string(int err)¶

New in version 5.1.0.

Get a text representation of an error number.

Deprecated since version This: function is potentially thread-unsafe, replaced by proj_context_errno_string().

Parameters

err (int) -- Error number.

Returns

const char* String with description of error.

const char *proj_context_errno_string(PJ_CONTEXT *ctx, int err)¶

New in version 8.0.0.

Get a text representation of an error number.

Parameters

ctx (PJ_CONTEXT *) -- threading context.
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 with level set to PJ_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

PJ_LOG_LEVEL

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_PROJ_INFO

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_GRID_INFO

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

PJ_INIT_INFO

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 NULL-entry. 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: const 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 NULL-entry. The array is statically allocated and does not need to be freed after use.

Returns: const 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 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 proj_get_units_from_database()

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

Returns: const 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.

The coordinates in a and b needs to be given as longitude and latitude in radians. Note that the axis order of the 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.

Parameters

P (const PJ *) -- Transformation or CRS object
a (PJ_COORD) -- Coordinate of first point
b (PJ_COORD) -- Coordinate of second point

Returns

double Distance between a and b 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.

The coordinates in a and b needs to be given as longitude and latitude in radians. Note that the axis order of the 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.

Parameters

P (const PJ *) -- Transformation or CRS object
a (PJ_COORD) -- Coordinate of first point
b (PJ_COORD) -- Coordinate of second point

Returns

double Distance between a and b in meters.

double proj_xy_dist(PJ_COORD a, PJ_COORD b)¶

Calculate 2-dimensional euclidean between two projected coordinates.

Parameters

a (PJ_COORD) -- First coordinate
b (PJ_COORD) -- Second coordinate

Returns

double Distance between a and b in meters.

double proj_xyz_dist(PJ_COORD a, PJ_COORD b)¶

Calculate 3-dimensional euclidean between two projected coordinates.

Parameters

a (PJ_COORD) -- First coordinate
b (PJ_COORD) -- Second coordinate

Returns

double Distance between a and b in meters.

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 a and b needs to be given as longitude and latitude in radians. Note that the axis order of the 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.

Parameters

P (const PJ *) -- Transformation or CRS object
a (PJ_COORD) -- Coordinate of first point
b (PJ_COORD) -- Coordinate of second point

Returns

PJ_COORD where the first value is the distance between a and 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¶

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 to

PJ_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 or PJ_LPZT.

Parameters

x (double) -- 1st component in a PJ_COORD
y (double) -- 2nd component in a PJ_COORD
z (double) -- 3rd component in a PJ_COORD
t (double) -- 4th component in a PJ_COORD

Returns

PJ_COORD

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 reverse direction. Returns the euclidean distance of the starting point coo and the resulting coordinate after n iterations back and forth.

If the input coordinate has any NaNs and the expected output of all NaNs is returned then the final distance will be 0.

Changed in version 9.2.0: Define expected NaN distance of 0.

Parameters

P (PJ *) -- Transformation object
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 after n 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.

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.

Parameters

P (PJ *) -- Transformation object
lp (PJ_COORD) -- Geodetic coordinate

Returns

PJ_FACTORS

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.

Deprecated since version 9.2: Use proj_rtodms2() instead.

Parameters

s (char *) -- Buffer that holds the output string
r (double) -- Value to convert to dms-representation
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 as s)

char *proj_rtodms2(char *s, size_t sizeof_s, double r, int pos, int neg)¶

New in version 9.2.0.

Convert radians to string representation of degrees, minutes and seconds.

Parameters

s (char *) -- Buffer that holds the output string
sizeof_s (size_t) -- Size of s buffer
r (double) -- Value to convert to dms-representation
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 as s)

int proj_angular_input(PJ *P, enum PJ_DIRECTION dir)¶

Check if an operation expects input in radians or not.

Parameters

P (PJ *) -- Transformation object
direction (PJ_DIRECTION) -- Starting direction of transformation

Returns

int 1 if input units is expected in radians, otherwise 0

int proj_angular_output(PJ *P, enum PJ_DIRECTION dir)¶

Check if an operation returns output in radians or not.

Parameters

P (PJ *) -- Transformation object
direction (PJ_DIRECTION) -- Starting direction of transformation

Returns

int 1 if output units is expected in radians, otherwise 0

int proj_degree_input(PJ *P, enum PJ_DIRECTION dir)¶

New in version 7.1.0.

Check if an operation expects input in degrees or not.

Parameters

P (PJ *) -- Transformation object
direction (PJ_DIRECTION) -- Starting direction of transformation

Returns

int 1 if input units is expected in degrees, otherwise 0

int proj_degree_output(PJ *P, enum PJ_DIRECTION dir)¶

New in version 7.1.0.

Check if an operation returns output in degrees or not.

Parameters

P (PJ *) -- Transformation object
direction (PJ_DIRECTION) -- Starting direction of transformation

Returns

int 1 if output units is expected in degrees, otherwise 0

Setting custom I/O functions¶

New in version 7.0.0.

int proj_context_set_fileapi(PJ_CONTEXT *ctx, const PROJ_FILE_API *fileapi, void *user_data)¶

Set a file API

All callbacks should be provided (non NULL pointers). If read-only usage is intended, then the callbacks might have a dummy implementation.

Since: 7.0

Note

Those callbacks will not be used for SQLite3 database access. If custom I/O is desired for that, then proj_context_set_sqlite3_vfs_name() should be used.

Parameters

ctx -- PROJ context, or NULL
fileapi -- Pointer to file API structure (content will be copied).
user_data -- Arbitrary pointer provided by the user, and passed to the above callbacks. May be NULL.

Returns

TRUE in case of success.

void proj_context_set_sqlite3_vfs_name(PJ_CONTEXT *ctx, const char *name)¶

Set the name of a custom SQLite3 VFS.

This should be a valid SQLite3 VFS name, such as the one passed to the sqlite3_vfs_register(). See https://www.sqlite.org/vfs.html

It will be used to read proj.db or create&access the cache.db file in the PROJ user writable directory.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
name -- SQLite3 VFS name. If NULL is passed, default implementation by SQLite will be used.

void proj_context_set_file_finder(PJ_CONTEXT *ctx, proj_file_finder finder, void *user_data)¶

Assign a file finder callback to a context.

This callback will be used whenever PROJ must open one of its resource files (proj.db database, grids, etc...)

The callback will be called with the context currently in use at the moment where it is used (not necessarily the one provided during this call), and with the provided user_data (which may be NULL). The user_data must remain valid during the whole lifetime of the context.

A finder set on the default context will be inherited by contexts created later.

Since: PROJ 6.0

Parameters

ctx -- PROJ context, or NULL for the default context.
finder -- Finder callback. May be NULL
user_data -- User data provided to the finder callback. May be NULL.

void proj_context_set_search_paths(PJ_CONTEXT *ctx, int count_paths, const char *const *paths)¶

Sets search paths.

Those search paths will be used whenever PROJ must open one of its resource files (proj.db database, grids, etc...)

If set on the default context, they will be inherited by contexts created later.

Starting with PROJ 7.0, the path(s) should be encoded in UTF-8.

Since: PROJ 6.0

Parameters

ctx -- PROJ context, or NULL for the default context.
count_paths -- Number of paths. 0 if paths == NULL.
paths -- Paths. May be NULL.

void proj_context_set_ca_bundle_path(PJ_CONTEXT *ctx, const char *path)¶

Sets CA Bundle path.

Those CA Bundle path will be used by PROJ when curl and PROJ_NETWORK are enabled.

If set on the default context, they will be inherited by contexts created later.

The path should be encoded in UTF-8.

Since: PROJ 7.2

Parameters

ctx -- PROJ context, or NULL for the default context.
path -- Path. May be NULL.

Network related functionality¶

New in version 7.0.0.

int proj_context_set_network_callbacks(PJ_CONTEXT *ctx, proj_network_open_cbk_type open_cbk, proj_network_close_cbk_type close_cbk, proj_network_get_header_value_cbk_type get_header_value_cbk, proj_network_read_range_type read_range_cbk, void *user_data)¶

Define a custom set of callbacks for network access.

All callbacks should be provided (non NULL pointers).

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
open_cbk -- Callback to open a remote file given its URL
close_cbk -- Callback to close a remote file.
get_header_value_cbk -- Callback to get HTTP headers
read_range_cbk -- Callback to read a range of bytes inside a remote file.
user_data -- Arbitrary pointer provided by the user, and passed to the above callbacks. May be NULL.

Returns

TRUE in case of success.

int proj_context_set_enable_network(PJ_CONTEXT *ctx, int enabled)¶

Enable or disable network access.

This overrides the default endpoint in the PROJ configuration file or with the PROJ_NETWORK environment variable.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
enable -- TRUE if network access is allowed.

Returns

TRUE if network access is possible. That is either libcurl is available, or an alternate interface has been set.

int proj_context_is_network_enabled(PJ_CONTEXT *ctx)¶

Return if network access is enabled.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL

Returns

TRUE if network access has been enabled

void proj_context_set_url_endpoint(PJ_CONTEXT *ctx, const char *url)¶

Define the URL endpoint to query for remote grids.

This overrides the default endpoint in the PROJ configuration file or with the PROJ_NETWORK_ENDPOINT environment variable.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
url -- Endpoint URL. Must NOT be NULL.

const char *proj_context_get_url_endpoint(PJ_CONTEXT *ctx)¶

Get the URL endpoint to query for remote grids.

Since: 7.1

Parameters

ctx -- PROJ context, or NULL

Returns

Endpoint URL. The returned pointer would be invalidated by a later call to proj_context_set_url_endpoint()

const char *proj_context_get_user_writable_directory(PJ_CONTEXT *ctx, int create)¶

Get the PROJ user writable directory for datumgrid files.

Since: 7.1

Parameters

ctx -- PROJ context, or NULL
create -- If set to TRUE, create the directory if it does not exist already.

Returns

The path to the PROJ user writable directory.

void proj_grid_cache_set_enable(PJ_CONTEXT *ctx, int enabled)¶

Enable or disable the local cache of grid chunks

This overrides the setting in the PROJ configuration file.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
enabled -- TRUE if the cache is enabled.

void proj_grid_cache_set_filename(PJ_CONTEXT *ctx, const char *fullname)¶

Override, for the considered context, the path and file of the local cache of grid chunks.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
fullname -- Full name to the cache (encoded in UTF-8). If set to NULL, caching will be disabled.

void proj_grid_cache_set_max_size(PJ_CONTEXT *ctx, int max_size_MB)¶

Override, for the considered context, the maximum size of the local cache of grid chunks.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
max_size_MB -- Maximum size, in mega-bytes (1024*1024 bytes), or negative value to set unlimited size.

void proj_grid_cache_set_ttl(PJ_CONTEXT *ctx, int ttl_seconds)¶

Override, for the considered context, the time-to-live delay for re-checking if the cached properties of files are still up-to-date.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
ttl_seconds -- Delay in seconds. Use negative value for no expiration.

void proj_grid_cache_clear(PJ_CONTEXT *ctx)¶

Clear the local cache of grid chunks.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL

int proj_is_download_needed(PJ_CONTEXT *ctx, const char *url_or_filename, int ignore_ttl_setting)¶

Return if a file must be downloaded or is already available in the PROJ user-writable directory.

The file will be determinted to have to be downloaded if it does not exist yet in the user-writable directory, or if it is determined that a more recent version exists. To determine if a more recent version exists, PROJ will use the "downloaded_file_properties" table of its grid cache database. Consequently files manually placed in the user-writable directory without using this function would be considered as non-existing/obsolete and would be unconditionally downloaded again.

This function can only be used if networking is enabled, and either the default curl network API or a custom one have been installed.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
url_or_filename -- URL or filename (without directory component)
ignore_ttl_setting -- If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.

Returns

TRUE if the file must be downloaded with proj_download_file()

int proj_download_file(PJ_CONTEXT *ctx, const char *url_or_filename, int ignore_ttl_setting, int (*progress_cbk)(PJ_CONTEXT*, double pct, void *user_data), void *user_data)¶

Download a file in the PROJ user-writable directory.

The file will only be downloaded if it does not exist yet in the user-writable directory, or if it is determined that a more recent version exists. To determine if a more recent version exists, PROJ will use the "downloaded_file_properties" table of its grid cache database. Consequently files manually placed in the user-writable directory without using this function would be considered as non-existing/obsolete and would be unconditionally downloaded again.

This function can only be used if networking is enabled, and either the default curl network API or a custom one have been installed.

Since: 7.0

Parameters

ctx -- PROJ context, or NULL
url_or_filename -- URL or filename (without directory component)
ignore_ttl_setting -- If set to FALSE, PROJ will only check the recentness of an already downloaded file, if the delay between the last time it has been verified and the current time exceeds the TTL setting. This can save network accesses. If set to TRUE, PROJ will unconditionally check from the server the recentness of the file.
progress_cbk -- Progress callback, or NULL. The passed percentage is in the [0, 1] range. The progress callback must return TRUE if download must be continued.
user_data -- User data to provide to the progress callback, or NULL

Returns

TRUE if the download was successful (or not needed)

Cleanup¶

void proj_cleanup()¶: New in version 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¶

New in version 6.0.0.

The PJ* objects returned by proj_create_from_wkt(), 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 proj_trans_generic(). Conversely, objects returned by proj_create() and proj_create_argv(), which are not of type CRS (can be tested with proj_is_crs()), will return an error when used with functions of this section.

void proj_string_list_destroy(PROJ_STRING_LIST list)¶: Free a list of NULL terminated strings.

void proj_context_set_autoclose_database(PJ_CONTEXT *ctx, int autoclose)¶

Starting with PROJ 8.1, this function does nothing.

If you want to take into account changes to the PROJ database, you need to re-create a new context.

Since: 6.2 deprecated Since 8.1

Parameters

ctx -- Ignored
autoclose -- Ignored

int proj_context_set_database_path(PJ_CONTEXT *ctx, const char *dbPath, const char *const *auxDbPaths, const char *const *options)¶

Explicitly point to the main PROJ CRS and coordinate operation definition database ("proj.db"), and potentially auxiliary databases with same structure.

Starting with PROJ 8.1, if the auxDbPaths parameter is an empty array, the PROJ_AUX_DB environment variable will be used, if set. It must contain one or several paths. If several paths are provided, they must be separated by the colon (:) character on Unix, and on Windows, by the semi-colon (;) character.

Parameters

ctx -- PROJ context, or NULL for default context
dbPath -- Path to main database, or NULL for default.
auxDbPaths -- NULL-terminated list of auxiliary database filenames, or NULL.
options -- should be set to NULL for now

Returns

TRUE in case of success

const char *proj_context_get_database_path(PJ_CONTEXT *ctx)¶

Returns the path to the database.

The returned pointer remains valid while ctx is valid, and until proj_context_set_database_path() is called.

Parameters

ctx -- PROJ context, or NULL for default context

Returns

path, or nullptr

const char *proj_context_get_database_metadata(PJ_CONTEXT *ctx, const char *key)¶

Return a metadata from the database.

The returned pointer remains valid while ctx is valid, and until proj_context_get_database_metadata() is called.

Available keys:

DATABASE.LAYOUT.VERSION.MAJOR
DATABASE.LAYOUT.VERSION.MINOR
EPSG.VERSION
EPSG.DATE
ESRI.VERSION
ESRI.DATE
IGNF.SOURCE
IGNF.VERSION
IGNF.DATE
NKG.SOURCE
NKG.VERSION
NKG.DATE
PROJ.VERSION
PROJ_DATA.VERSION : PROJ-data version most compatible with this database.

Parameters

ctx -- PROJ context, or NULL for default context
key -- Metadata key. Must not be NULL

Returns

value, or nullptr

PROJ_STRING_LIST proj_context_get_database_structure(PJ_CONTEXT *ctx, const char *const *options)¶

Return the database structure.

Return SQL statements to run to initiate a new valid auxiliary empty database. It contains definitions of tables, views and triggers, as well as metadata for the version of the layout of the database.

Since: 8.1

Parameters

ctx -- PROJ context, or NULL for default context
options -- null-terminated list of options, or NULL. None currently.

Returns

list of SQL statements (to be freed with proj_string_list_destroy()), or NULL in case of error.

PJ_GUESSED_WKT_DIALECT proj_context_guess_wkt_dialect(PJ_CONTEXT *ctx, const char *wkt)¶

Guess the "dialect" of the WKT string.

Parameters

ctx -- PROJ context, or NULL for default context
wkt -- String (must not be NULL)

PJ *proj_create_from_wkt(PJ_CONTEXT *ctx, const char *wkt, const char *const *options, PROJ_STRING_LIST *out_warnings, PROJ_STRING_LIST *out_grammar_errors)¶

Instantiate an object from a WKT string.

This function calls osgeo::proj::io::WKTParser::createFromWKT()

The returned object must be unreferenced with proj_destroy() after use. It should be used by at most one thread at a time.

Parameters

ctx -- PROJ context, or NULL for default context
wkt -- WKT string (must not be NULL)
options -- null-terminated list of options, or NULL. Currently supported options are:
- STRICT=YES/NO. Defaults to NO. When set to YES, strict validation will be enabled.
- UNSET_IDENTIFIERS_IF_INCOMPATIBLE_DEF=YES/NO. Defaults to YES. When set to YES, object identifiers are unset when there is a contradiction between the definition from WKT and the one from the database./
out_warnings -- Pointer to a PROJ_STRING_LIST object, or NULL. If provided, *out_warnings will contain a list of warnings, typically for non recognized projection method or parameters. It must be freed with proj_string_list_destroy().
out_grammar_errors -- Pointer to a PROJ_STRING_LIST object, or NULL. If provided, *out_grammar_errors will contain a list of errors regarding the WKT grammar. It must be freed with proj_string_list_destroy().

Returns

Object that must be unreferenced with proj_destroy(), or NULL in case of error.

PJ *proj_create_from_database(PJ_CONTEXT *ctx, const char *auth_name, const char *code, PJ_CATEGORY category, int usePROJAlternativeGridNames, const char *const *options)¶

Instantiate an object from a database lookup.

The returned object must be unreferenced with proj_destroy() after use. It should be used by at most one thread at a time.

Parameters

ctx -- Context, or NULL for default context.
auth_name -- Authority name (must not be NULL)
code -- Object code (must not be NULL)
category -- Object category
usePROJAlternativeGridNames -- Whether PROJ alternative grid names should be substituted to the official grid names. Only used on transformations
options -- should be set to NULL for now

Returns

Object that must be unreferenced with proj_destroy(), or NULL in case of error.

int proj_uom_get_info_from_database(PJ_CONTEXT *ctx, const char *auth_name, const char *code, const char **out_name, double *out_conv_factor, const char **out_category)¶

Get information for a unit of measure from a database lookup.

Parameters

ctx -- Context, or NULL for default context.
auth_name -- Authority name (must not be NULL)
code -- Unit of measure code (must not be NULL)
out_name -- Pointer to a string value to store the parameter name. or NULL. This value remains valid until the next call to proj_uom_get_info_from_database() or the context destruction.
out_conv_factor -- Pointer to a value to store the conversion factor of the prime meridian longitude unit to radian. or NULL
out_category -- Pointer to a string value to store the parameter name. or NULL. This value might be "unknown", "none", "linear", "linear_per_time", "angular", "angular_per_time", "scale", "scale_per_time", "time", "parametric" or "parametric_per_time"

Returns

TRUE in case of success

int proj_grid_get_info_from_database(PJ_CONTEXT *ctx, const char *grid_name, const char **out_full_name, const char **out_package_name, const char **out_url, int *out_direct_download, int *out_open_license, int *out_available)¶

Get information for a grid from a database lookup.

Parameters

ctx -- Context, or NULL for default context.
grid_name -- Grid name (must not be NULL)
out_full_name -- Pointer to a string value to store the grid full filename. or NULL
out_package_name -- Pointer to a string value to store the package name where the grid might be found. or NULL
out_url -- Pointer to a string value to store the grid URL or the package URL where the grid might be found. or NULL
out_direct_download -- Pointer to a int (boolean) value to store whether *out_url can be downloaded directly. or NULL
out_open_license -- Pointer to a int (boolean) value to store whether the grid is released with an open license. or NULL
out_available -- Pointer to a int (boolean) value to store whether the grid is available at runtime. or NULL

Returns

TRUE in case of success.

PJ *proj_clone(PJ_CONTEXT *ctx, const PJ *obj)¶

"Clone" an object.

The object might be used independently of the original object, provided that the use of context is compatible. In particular if you intend to use a clone in a different thread than the original object, you should pass a context that is different from the one of the original object (or later assign a different context with proj_assign_context()).

The returned object must be unreferenced with proj_destroy() after use. It should be used by at most one thread at a time.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object to clone. Must not be NULL.

Returns

Object that must be unreferenced with proj_destroy(), or NULL in case of error.

PJ_OBJ_LIST *proj_create_from_name(PJ_CONTEXT *ctx, const char *auth_name, const char *searchedName, const PJ_TYPE *types, size_t typesCount, int approximateMatch, size_t limitResultCount, const char *const *options)¶

Return a list of objects by their name.

Parameters

ctx -- Context, or NULL for default context.
auth_name -- Authority name, used to restrict the search. Or NULL for all authorities.
searchedName -- Searched name. Must be at least 2 character long.
types -- List of object types into which to search. If NULL, all object types will be searched.
typesCount -- Number of elements in types, or 0 if types is NULL
approximateMatch -- Whether approximate name identification is allowed.
limitResultCount -- Maximum number of results to return. Or 0 for unlimited.
options -- should be set to NULL for now

Returns

a result set that must be unreferenced with proj_list_destroy(), or NULL in case of error.

PJ_TYPE proj_get_type(const PJ *obj)¶

Return the type of an object.

Parameters

obj -- Object (must not be NULL)

Returns

its type.

int proj_is_deprecated(const PJ *obj)¶

Return whether an object is deprecated.

Parameters

obj -- Object (must not be NULL)

Returns

TRUE if it is deprecated, FALSE otherwise

PJ_OBJ_LIST *proj_get_non_deprecated(PJ_CONTEXT *ctx, const PJ *obj)¶

Return a list of non-deprecated objects related to the passed one.

Parameters

ctx -- Context, or NULL for default context.
obj -- Object (of type CRS for now) for which non-deprecated objects must be searched. Must not be NULL

Returns

a result set that must be unreferenced with proj_list_destroy(), or NULL in case of error.

int proj_is_equivalent_to(const PJ *obj, const PJ *other, PJ_COMPARISON_CRITERION criterion)¶

Return whether two objects are equivalent.

Use proj_is_equivalent_to_with_ctx() to be able to use database information.

Parameters

obj -- Object (must not be NULL)
other -- Other object (must not be NULL)
criterion -- Comparison criterion

Returns

TRUE if they are equivalent

int proj_is_equivalent_to_with_ctx(PJ_CONTEXT *ctx, const PJ *obj, const PJ *other, PJ_COMPARISON_CRITERION criterion)¶

Return whether two objects are equivalent.

Possibly using database to check for name aliases.

Since: 6.3

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object (must not be NULL)
other -- Other object (must not be NULL)
criterion -- Comparison criterion

Returns

TRUE if they are equivalent

int proj_is_crs(const PJ *obj)¶

Return whether an object is a CRS.

Parameters

obj -- Object (must not be NULL)

const char *proj_get_name(const PJ *obj)¶

Get the name of an object.

The lifetime of the returned string is the same as the input obj parameter.

Parameters

obj -- Object (must not be NULL)

Returns

a string, or NULL in case of error or missing name.

const char *proj_get_id_auth_name(const PJ *obj, int index)¶

Get the authority name / codespace of an identifier of an object.

The lifetime of the returned string is the same as the input obj parameter.

Parameters

obj -- Object (must not be NULL)
index -- Index of the identifier. 0 = first identifier

Returns

a string, or NULL in case of error or missing name.

const char *proj_get_id_code(const PJ *obj, int index)¶

Get the code of an identifier of an object.

The lifetime of the returned string is the same as the input obj parameter.

Parameters

obj -- Object (must not be NULL)
index -- Index of the identifier. 0 = first identifier

Returns

a string, or NULL in case of error or missing name.

const char *proj_get_remarks(const PJ *obj)¶

Get the remarks of an object.

The lifetime of the returned string is the same as the input obj parameter.

Parameters

obj -- Object (must not be NULL)

Returns

a string, or NULL in case of error.

int proj_get_domain_count(const PJ *obj)¶

Get the number of domains/usages for a given object.

Most objects have a single domain/usage, but for some of them, there might be multiple.

Since: 9.2

Parameters

obj -- Object (must not be NULL)

Returns

the number of domains, or 0 in case of error.

const char *proj_get_scope(const PJ *obj)¶

Get the scope of an object.

In case of multiple usages, this will be the one of first usage.

The lifetime of the returned string is the same as the input obj parameter.

Parameters

obj -- Object (must not be NULL)

Returns

a string, or NULL in case of error or missing scope.

const char *proj_get_scope_ex(const PJ *obj, int domainIdx)¶

Get the scope of an object.

The lifetime of the returned string is the same as the input obj parameter.

Since: 9.2

Parameters

obj -- Object (must not be NULL)
domainIdx -- Index of the domain/usage. In [0,proj_get_domain_count(obj)[

Returns

a string, or NULL in case of error or missing scope.

int proj_get_area_of_use(PJ_CONTEXT *ctx, const PJ *obj, double *out_west_lon_degree, double *out_south_lat_degree, double *out_east_lon_degree, double *out_north_lat_degree, const char **out_area_name)¶

Return the area of use of an object.

In case of multiple usages, this will be the one of first usage.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object (must not be NULL)
out_west_lon_degree -- Pointer to a double to receive the west longitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_south_lat_degree -- Pointer to a double to receive the south latitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_east_lon_degree -- Pointer to a double to receive the east longitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_north_lat_degree -- Pointer to a double to receive the north latitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_area_name -- Pointer to a string to receive the name of the area of use. Or NULL. *p_area_name is valid while obj is valid itself.

Returns

TRUE in case of success, FALSE in case of error or if the area of use is unknown.

int proj_get_area_of_use_ex(PJ_CONTEXT *ctx, const PJ *obj, int domainIdx, double *out_west_lon_degree, double *out_south_lat_degree, double *out_east_lon_degree, double *out_north_lat_degree, const char **out_area_name)¶

Return the area of use of an object.

In case of multiple usages, this will be the one of first usage.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object (must not be NULL)
domainIdx -- Index of the domain/usage. In [0,proj_get_domain_count(obj)[
out_west_lon_degree -- Pointer to a double to receive the west longitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_south_lat_degree -- Pointer to a double to receive the south latitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_east_lon_degree -- Pointer to a double to receive the east longitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_north_lat_degree -- Pointer to a double to receive the north latitude (in degrees). Or NULL. If the returned value is -1000, the bounding box is unknown.
out_area_name -- Pointer to a string to receive the name of the area of use. Or NULL. *p_area_name is valid while obj is valid itself.

Returns

TRUE in case of success, FALSE in case of error or if the area of use is unknown.

const char *proj_as_wkt(PJ_CONTEXT *ctx, const PJ *obj, PJ_WKT_TYPE type, const char *const *options)¶

Get a WKT representation of an object.

The returned string is valid while the input obj parameter is valid, and until a next call to proj_as_wkt() with the same input object.

This function calls osgeo::proj::io::IWKTExportable::exportToWKT().

This function may return NULL if the object is not compatible with an export to the requested type.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object (must not be NULL)
type -- WKT version.
options -- null-terminated list of options, or NULL. Currently supported options are:
- MULTILINE=YES/NO. Defaults to YES, except for WKT1_ESRI
- INDENTATION_WIDTH=number. Defaults to 4 (when multiline output is on).
- OUTPUT_AXIS=AUTO/YES/NO. In AUTO mode, axis will be output for WKT2 variants, for WKT1_GDAL for ProjectedCRS with easting/northing ordering (otherwise stripped), but not for WKT1_ESRI. Setting to YES will output them unconditionally, and to NO will omit them unconditionally.
- STRICT=YES/NO. Default is YES. If NO, a Geographic 3D CRS can be for example exported as WKT1_GDAL with 3 axes, whereas this is normally not allowed.
- ALLOW_ELLIPSOIDAL_HEIGHT_AS_VERTICAL_CRS=YES/NO. Default is NO. If set to YES and type == PJ_WKT1_GDAL, a Geographic 3D CRS or a Projected 3D CRS will be exported as a compound CRS whose vertical part represents an ellipsoidal height (for example for use with LAS 1.4 WKT1).
- ALLOW_LINUNIT_NODE=YES/NO. Default is YES starting with PROJ 9.1. Only taken into account with type == PJ_WKT1_ESRI on a Geographic 3D CRS.

Returns

a string, or NULL in case of error.

const char *proj_as_proj_string(PJ_CONTEXT *ctx, const PJ *obj, PJ_PROJ_STRING_TYPE type, const char *const *options)¶

Get a PROJ string representation of an object.

The returned string is valid while the input obj parameter is valid, and until a next call to proj_as_proj_string() with the same input object.

This function calls osgeo::proj::io::IPROJStringExportable::exportToPROJString().

This function may return NULL if the object is not compatible with an export to the requested type.

Warning

If a CRS object was not created from a PROJ string, exporting to a PROJ string will in most cases cause a loss of information. This can potentially lead to erroneous transformations.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object (must not be NULL)
type -- PROJ String version.
options -- NULL-terminated list of strings with "KEY=VALUE" format. or NULL. Currently supported options are:
- USE_APPROX_TMERC=YES to add the +approx flag to +proj=tmerc or +proj=utm.
- MULTILINE=YES/NO. Defaults to NO
- INDENTATION_WIDTH=number. Defaults to 2 (when multiline output is on).
- MAX_LINE_LENGTH=number. Defaults to 80 (when multiline output is on).

Returns

a string, or NULL in case of error.

const char *proj_as_projjson(PJ_CONTEXT *ctx, const PJ *obj, const char *const *options)¶

Get a PROJJSON string representation of an object.

The returned string is valid while the input obj parameter is valid, and until a next call to proj_as_proj_string() with the same input object.

This function calls osgeo::proj::io::IJSONExportable::exportToJSON().

This function may return NULL if the object is not compatible with an export to the requested type.

Since: 6.2

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object (must not be NULL)
options -- NULL-terminated list of strings with "KEY=VALUE" format. or NULL. Currently supported options are:
- MULTILINE=YES/NO. Defaults to YES
- INDENTATION_WIDTH=number. Defaults to 2 (when multiline output is on).
- SCHEMA=string. URL to PROJJSON schema. Can be set to empty string to disable it.

Returns

a string, or NULL in case of error.

PJ *proj_get_source_crs(PJ_CONTEXT *ctx, const PJ *obj)¶

Return the base CRS of a BoundCRS or a DerivedCRS/ProjectedCRS, or the source CRS of a CoordinateOperation, or the CRS of a CoordinateMetadata.

The returned object must be unreferenced with proj_destroy() after use. It should be used by at most one thread at a time.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object of type BoundCRS or CoordinateOperation (must not be NULL)

Returns

Object that must be unreferenced with proj_destroy(), or NULL in case of error, or missing source CRS.

PJ *proj_get_target_crs(PJ_CONTEXT *ctx, const PJ *obj)¶

Return the hub CRS of a BoundCRS or the target CRS of a CoordinateOperation.

The returned object must be unreferenced with proj_destroy() after use. It should be used by at most one thread at a time.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object of type BoundCRS or CoordinateOperation (must not be NULL)

Returns

Object that must be unreferenced with proj_destroy(), or NULL in case of error, or missing target CRS.

PJ_OBJ_LIST *proj_identify(PJ_CONTEXT *ctx, const PJ *obj, const char *auth_name, const char *const *options, int **out_confidence)¶

Identify the CRS with reference CRSs.

The candidate CRSs are either hard-coded, or looked in the database when it is available.

Note that the implementation uses a set of heuristics to have a good compromise of successful identifications over execution time. It might miss legitimate matches in some circumstances.

The method returns a list of matching reference CRS, and the percentage (0-100) of confidence in the match. The list is sorted by decreasing confidence.

100% means that the name of the reference entry perfectly matches the CRS name, and both are equivalent. In which case a single result is returned. Note: in the case of a GeographicCRS whose axis order is implicit in the input definition (for example ESRI WKT), then axis order is ignored for the purpose of identification. That is the CRS built from GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]], PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]] will be identified to EPSG:4326, but will not pass a isEquivalentTo(EPSG_4326, util::IComparable::Criterion::EQUIVALENT) test, but rather isEquivalentTo(EPSG_4326, util::IComparable::Criterion::EQUIVALENT_EXCEPT_AXIS_ORDER_GEOGCRS)
90% means that CRS are equivalent, but the names are not exactly the same.
70% means that CRS are equivalent, but the names are not equivalent.
25% means that the CRS are not equivalent, but there is some similarity in the names.

Other confidence values may be returned by some specialized implementations.

This is implemented for GeodeticCRS, ProjectedCRS, VerticalCRS and CompoundCRS.

Parameters

ctx -- PROJ context, or NULL for default context
obj -- Object of type CRS. Must not be NULL
auth_name -- Authority name, or NULL for all authorities
options -- Placeholder for future options. Should be set to NULL.
out_confidence -- Output parameter. Pointer to an array of integers that will be allocated by the function and filled with the confidence values (0-100). There are as many elements in this array as proj_list_get_count() returns on the return value of this function. *confidence should be released with proj_int_list_destroy().

Returns

a list of matching reference CRS, or nullptr in case of error.

PROJ_STRING_LIST proj_get_geoid_models_from_database(PJ_CONTEXT *ctx, const char *auth_name, const char *code, const char *const *options)¶

Returns a list of geoid models available for that crs.

The list includes the geoid models connected directly with the crs, or via "Height Depth Reversal" or "Change of Vertical Unit" transformations. The returned list is NULL terminated and must be freed with proj_string_list_destroy().

Since: 8.1

Parameters

ctx -- Context, or NULL for default context.
auth_name -- Authority name (must not be NULL)
code -- Object code (must not be NULL)
options -- should be set to NULL for now

Returns

list of geoid models names (to be freed with proj_string_list_destroy()), or NULL in case of error.

void proj_int_list_destroy(int *list)¶: Free an array of integer.

PROJ_STRING_LIST proj_get_authorities_from_database(PJ_CONTEXT *ctx)¶

Return the list of authorities used in the database.

The returned list is NULL terminated and must be freed with proj_string_list_destroy().

Parameters

ctx -- PROJ context, or NULL for default context

Returns

a NULL terminated list of NUL-terminated strings that must be freed with proj_string_list_destroy(), or NULL in case of error.

PROJ_STRING_LIST proj_get_codes_from_database(PJ_CONTEXT *ctx, const char *auth_name, PJ_TYPE type, int allow_deprecated)¶

Returns the set of authority codes of the given object type.

The returned list is NULL terminated and must be freed with proj_string_list_destroy().