Functions¶

Threading contexts¶

PJ_CONTEXT* proj_context_create(void)¶

Create a new threading-context.

Returns:	`PJ_CONTEXT*`

void proj_context_destroy(PJ_CONTEXT *ctx)¶

Deallocate a threading-context.

Parameters:	ctx (PJ_CONTEXT*) – Threading context.

Transformation setup¶

PJ* proj_create(PJ_CONTEXT *ctx, const char *definition)¶

Create a transformation object from a proj-string.

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() 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 transformation 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 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**) – Vector of strings with proj-string parameters, e.g. `+proj=merc`
Returns:	`PJ*`

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 and srid_to should be the value part of a +init=... parameter set, i.e. “epsg:25833” or “IGNF:AMST63”. Any projection definition that can be found in a init-file in PROJ_LIB is a valid input to this function.

For now the function mimics the cs2cs app: An input and an output CRS is given and coordinates are transformed via a hub datum (WGS84). This transformation strategy is referred to as “early-binding” by the EPSG. The function can be extended to support “late-binding” transformations in the future without affecting users of the function. When the function is extended to the late-binding approach the area argument will be used. For now it is just a place-holder 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() or proj_context_errno().

The returned PJ-pointer should be deallocated with proj_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:	`PJ*`

PJ* proj_destroy(PJ *P)¶

Deallocate a PJ transformation object.

Parameters:	P (PJ*) –
Returns:	`PJ*`

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

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 for proj_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, and t 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 x-coordinates
y (double*) – Array of y-coordinates
z (double*) – Array of z-coordinates
t (double*) – Array of t-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
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 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().

Param:	PJ* P: 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().

Param:	PJ_CONTEXT* ctx: threading context.
Returns:	`int`

void proj_errno_set(PJ *P, int err)¶

Change the error-state 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 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 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 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:	`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:	`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.

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 NULL-entry. 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:	P (PJ) – Transformation 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.

Parameters:	P (PJ) – Transformation 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.

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.

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

The function also calculates the partial derivatives of the given coordinate.

Parameters:	P (const PJ) – Transformation object lp (const 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.

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

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

C API for ISO-19111 functionality¶

C API new generation

Defines

PROJ_H¶

Typedefs

typedef char **PROJ_STRING_LIST¶: Type representing a NULL terminated list of NUL-terminate strings.

Enums

enum PJ_OBJ_CATEGORY¶

Object category.

Values:

PJ_OBJ_CATEGORY_ELLIPSOID¶

PJ_OBJ_CATEGORY_DATUM¶

PJ_OBJ_CATEGORY_CRS¶

PJ_OBJ_CATEGORY_COORDINATE_OPERATION¶

enum PJ_OBJ_TYPE¶

Object type.

Values:

PJ_OBJ_TYPE_ELLIPSOID¶

PJ_OBJ_TYPE_GEODETIC_REFERENCE_FRAME¶

PJ_OBJ_TYPE_DYNAMIC_GEODETIC_REFERENCE_FRAME¶

PJ_OBJ_TYPE_VERTICAL_REFERENCE_FRAME¶

PJ_OBJ_TYPE_DYNAMIC_VERTICAL_REFERENCE_FRAME¶

PJ_OBJ_TYPE_DATUM_ENSEMBLE¶

PJ_OBJ_TYPE_GEODETIC_CRS¶

PJ_OBJ_TYPE_GEOGRAPHIC_CRS¶

PJ_OBJ_TYPE_VERTICAL_CRS¶

PJ_OBJ_TYPE_PROJECTED_CRS¶

PJ_OBJ_TYPE_COMPOUND_CRS¶

PJ_OBJ_TYPE_TEMPORAL_CRS¶

PJ_OBJ_TYPE_BOUND_CRS¶

PJ_OBJ_TYPE_OTHER_CRS¶

PJ_OBJ_TYPE_CONVERSION¶

PJ_OBJ_TYPE_TRANSFORMATION¶

PJ_OBJ_TYPE_CONCATENATED_OPERATION¶

PJ_OBJ_TYPE_OTHER_COORDINATE_OPERATION¶

PJ_OBJ_TYPE_UNKNOWN¶

enum PJ_WKT_TYPE¶

WKT version.

Values:

PJ_WKT2_2018¶: cf osgeo::proj::io::WKTFormatter::Convention::WKT2_2018

PJ_WKT2_2018_SIMPLIFIED¶: cf osgeo::proj::io::WKTFormatter::Convention::WKT2_2018_SIMPLIFIED

PJ_WKT2_2015¶: cf osgeo::proj::io::WKTFormatter::Convention::WKT2

PJ_WKT2_2015_SIMPLIFIED¶: cf osgeo::proj::io::WKTFormatter::Convention::WKT2_SIMPLIFIED

PJ_WKT1_GDAL¶: cf osgeo::proj::io::WKTFormatter::Convention::WKT1_GDAL

enum PJ_PROJ_STRING_TYPE¶

PROJ string version.

Values:

PJ_PROJ_5¶: cf osgeo::proj::io::PROJStringFormatter::Convention::PROJ_5

PJ_PROJ_4¶: cf osgeo::proj::io::PROJStringFormatter::Convention::PROJ_4

enum PROJ_CRS_EXTENT_USE¶

Specify how source and target CRS extent should be used to restrict candidate operations (only taken into account if no explicit area of interest is specified.

Values:

PJ_CRS_EXTENT_NONE¶: Ignore CRS extent

PJ_CRS_EXTENT_BOTH¶: Test coordinate operation extent against both CRS extent.

PJ_CRS_EXTENT_INTERSECTION¶: Test coordinate operation extent against the intersection of both CRS extent.

PJ_CRS_EXTENT_SMALLEST¶: Test coordinate operation against the smallest of both CRS extent.

enum PROJ_SPATIAL_CRITERION¶

Spatial criterion to restrict candiate operations.

Values:

PROJ_SPATIAL_CRITERION_STRICT_CONTAINMENT¶: The area of validity of transforms should strictly contain the are of interest.

PROJ_SPATIAL_CRITERION_PARTIAL_INTERSECTION¶: The area of validity of transforms should at least intersect the area of interest.

enum PROJ_GRID_AVAILABILITY_USE¶

Describe how grid availability is used.

Values:

PROJ_GRID_AVAILABILITY_USED_FOR_SORTING¶: Grid availability is only used for sorting results. Operations where some grids are missing will be sorted last.

PROJ_GRID_AVAILABILITY_DISCARD_OPERATION_IF_MISSING_GRID¶: Completely discard an operation if a required grid is missing.

PROJ_GRID_AVAILABILITY_IGNORED¶: Ignore grid availability at all. Results will be presented as if all grids were available.

Functions

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

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

Return

TRUE in case of success

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.

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.

Return

path, or nullptr

Parameters

ctx: PROJ context, or NULL for default context

PJ_OBJ *proj_obj_create_from_user_input(PJ_CONTEXT *ctx, const char *text)¶

Instanciate an object from a WKT string, PROJ string or object code (like “EPSG:4326”, “urn:ogc:def:crs:EPSG::4326”, “urn:ogc:def:coordinateOperation:EPSG::1671”).

This function calls osgeo::proj::io::createFromUserInput()

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

Return

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

Parameters

ctx: PROJ context, or NULL for default context
text: String (must not be NULL)

PJ_OBJ *proj_obj_create_from_wkt(PJ_CONTEXT *ctx, const char *wkt)¶

Instanciate an object from a WKT string.

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

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

Return

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

Parameters

ctx: PROJ context, or NULL for default context
wkt: WKT string (must not be NULL)

PJ_OBJ *proj_obj_create_from_proj_string(PJ_CONTEXT *ctx, const char *proj_string)¶

Instanciate an object from a PROJ string.

This function calls osgeo::proj::io::PROJStringParser::createFromPROJString()

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

Return

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

Parameters

ctx: PROJ context, or NULL for default context
proj_string: PROJ string (must not be NULL)

PJ_OBJ *proj_obj_create_from_database(PJ_CONTEXT *ctx, const char *auth_name, const char *code, PJ_OBJ_CATEGORY category, int usePROJAlternativeGridNames, const char *const *options)¶

Instanciate an object from a database lookup.

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

Return

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

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

void proj_obj_unref(PJ_OBJ *obj)¶

Drops a reference on an object.

This method should be called one and exactly one for each function returning a PJ_OBJ*

Parameters

obj: Object, or NULL.

PJ_OBJ_TYPE proj_obj_get_type(PJ_OBJ *obj)¶

Return the type of an object.

Return

its type.

Parameters

obj: Object (must not be NULL)

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_free_string_list().

Return

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

Parameters

ctx: PROJ context, or NULL for default context

PROJ_STRING_LIST proj_get_codes_from_database(PJ_CONTEXT *ctx, const char *auth_name, PJ_OBJ_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_free_string_list().

Return

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

Parameters

ctx: PROJ context, or NULL for default context.
auth_name: Authority name (must not be NULL)
type: Object type.
allow_deprecated: whether we should return deprecated objects as well.

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

int proj_obj_is_crs(PJ_OBJ *obj)¶

Return whether an object is a CRS.

Parameters

obj: Object (must not be NULL)

const char *proj_obj_get_name(PJ_OBJ *obj)¶

Get the name of an object.

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

Return

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

Parameters

obj: Object (must not be NULL)

const char *proj_obj_get_id_auth_name(PJ_OBJ *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.

Return

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

Parameters

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

const char *proj_obj_get_id_code(PJ_OBJ *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.

Return

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

Parameters

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

const char *proj_obj_as_wkt(PJ_OBJ *obj, PJ_WKT_TYPE type, const char *const *options)¶

Get a WKT representation of an object.

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

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.

Return

a string, or NULL in case of error.

Parameters

obj: Object (must not be NULL)
type: WKT version.
options: should be set to NULL for now

const char *proj_obj_as_proj_string(PJ_OBJ *obj, PJ_PROJ_STRING_TYPE type, const char *const *options)¶

Get a PROJ string representation of an object.

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

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.

Return

a string, or NULL in case of error.

Parameters

obj: Object (must not be NULL)
type: PROJ String version.
options: NULL-terminated list of strings with “KEY=VALUE” format. or NULL. The currently recognized option is USE_ETMERC=YES to use +proj=etmerc instead of +proj=tmerc

PJ_OBJ *proj_obj_get_source_crs(PJ_OBJ *obj)¶

Return the base CRS of a BoundCRS or the source CRS of a CoordinateOperation.

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

Return

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

Parameters

obj: Objet of type BoundCRS or CoordinateOperation (must not be NULL)

PJ_OBJ *proj_obj_get_target_crs(PJ_OBJ *obj)¶

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

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

Return

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

Parameters

obj: Objet of type BoundCRS or CoordinateOperation (must not be NULL)

PJ_OPERATION_FACTORY_CONTEXT *proj_create_operation_factory_context(PJ_CONTEXT *ctx, const char *authority)¶

Instanciate a context for building coordinate operations between two CRS.

The returned object must be unreferenced with proj_operation_factory_context_unref() after use.

Return

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

Parameters

ctx: Context, or NULL for default context.
authority: Name of authority to which to restrict the search of canidate operations. Or NULL to allow any authority.

void proj_operation_factory_context_unref(PJ_OPERATION_FACTORY_CONTEXT *ctxt)¶

Drops a reference on an object.

This method should be called one and exactly one for each function returning a PJ_OPERATION_FACTORY_CONTEXT*

Parameters

ctxt: Object, or NULL.

void proj_operation_factory_context_set_desired_accuracy(PJ_OPERATION_FACTORY_CONTEXT *ctxt, double accuracy)¶

Set the desired accuracy of the resulting coordinate transformations.

Parameters

ctxt: Operation factory context. must not be NULL
accuracy: Accuracy in meter (or 0 to disable the filter).

void proj_operation_factory_context_set_area_of_interest(PJ_OPERATION_FACTORY_CONTEXT *ctxt, double west_lon, double south_lat, double east_lon, double north_lat)¶

Set the desired area of interest for the resulting coordinate transformations.

For an area of interest crossing the anti-meridian, west_lon will be greater than east_lon.

Parameters

ctxt: Operation factory context. must not be NULL
west_lon: West longitude (in degrees).
south_lat: South latitude (in degrees).
east_lon: East longitude (in degrees).
north_lat: North latitude (in degrees).

void proj_operation_factory_context_set_crs_extent_use(PJ_OPERATION_FACTORY_CONTEXT *ctxt, PROJ_CRS_EXTENT_USE use)¶

Set how source and target CRS extent should be used when considering if a transformation can be used (only takes effect if no area of interest is explicitly defined).

The default is PJ_CRS_EXTENT_SMALLEST.

Parameters

ctxt: Operation factory context. must not be NULL
use: How source and target CRS extent should be used.

void proj_operation_factory_context_set_spatial_criterion(PJ_OPERATION_FACTORY_CONTEXT *ctxt, PROJ_SPATIAL_CRITERION criterion)¶

Set the spatial criterion to use when comparing the area of validity of coordinate operations with the area of interest / area of validity of source and target CRS.

The default is PROJ_SPATIAL_CRITERION_STRICT_CONTAINMENT.

Parameters

ctxt: Operation factory context. must not be NULL
criterion: patial criterion to use

void proj_operation_factory_context_set_grid_availability_use(PJ_OPERATION_FACTORY_CONTEXT *ctxt, PROJ_GRID_AVAILABILITY_USE use)¶

Set how grid availability is used.

The default is USE_FOR_SORTING.

Parameters

ctxt: Operation factory context. must not be NULL
use: how grid availability is used.

void proj_operation_factory_context_set_use_proj_alternative_grid_names(PJ_OPERATION_FACTORY_CONTEXT *ctxt, int usePROJNames)¶

Set whether PROJ alternative grid names should be substituted to the official authority names.

The default is true.

Parameters

ctxt: Operation factory context. must not be NULL
usePROJNames: whether PROJ alternative grid names should be used

void proj_operation_factory_context_set_allow_use_intermediate_crs(PJ_OPERATION_FACTORY_CONTEXT *ctxt, int allow)¶

Set whether an intermediate pivot CRS can be used for researching coordinate operations between a source and target CRS.

Concretely if in the database there is an operation from A to C (or C to A), and another one from C to B (or B to C), but no direct operation between A and B, setting this parameter to true, allow chaining both operations.

The current implementation is limited to researching one intermediate step.

By default, all potential C candidates will be used. proj_operation_factory_context_set_allowed_intermediate_crs() can be used to restrict them.

The default is true.

Parameters

ctxt: Operation factory context. must not be NULL
allow: whether intermediate CRS may be used.

void proj_operation_factory_context_set_allowed_intermediate_crs(PJ_OPERATION_FACTORY_CONTEXT *ctxt, const char *const *list_of_auth_name_codes)¶

Restrict the potential pivot CRSs that can be used when trying to build a coordinate operation between two CRS that have no direct operation.

Parameters

ctxt: Operation factory context. must not be NULL
list_of_auth_name_codes: an array of strings NLL terminated, with the format { “auth_name1”, “code1”, “auth_name2”, “code2”, … NULL }

PJ_OPERATION_RESULT *proj_obj_create_operations(PJ_OBJ *source_crs, PJ_OBJ *target_crs, PJ_OPERATION_FACTORY_CONTEXT *operationContext)¶

Find a list of CoordinateOperation from source_crs to target_crs.

The operations are sorted with the most relevant ones first: by descending area (intersection of the transformation area with the area of interest, or intersection of the transformation with the area of use of the CRS), and by increasing accuracy. Operations with unknown accuracy are sorted last, whatever their area.

Return

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

Parameters

source_crs: source CRS. Must not be NULL.
target_crs: source CRS. Must not be NULL.
operationContext: Search context. Must not be NULL.

int proj_operation_result_get_count(PJ_OPERATION_RESULT *result)¶

Return the number of CoordinateOperation in the result set.

Parameters

result: Objet of type PJ_OPERATION_RESULT (must not be NULL)

PJ_OBJ *proj_operation_result_get(PJ_OPERATION_RESULT *result, int index)¶

Return a CoordinateOperation in the result set.

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

Return

a new object that must be unreferenced with proj_obj_unref(), or nullptr in case of error.

Parameters

result: Objet of type PJ_OPERATION_RESULT (must not be NULL)
index: Index

void proj_operation_result_unref(PJ_OPERATION_RESULT *result)¶

Drops a reference on an object.

This method should be called one and exactly one for each function returning a PJ_OPERATION_RESULT*

Parameters

result: Object, or NULL.

PJ_OBJ *proj_obj_crs_get_geodetic_crs(PJ_OBJ *crs)¶

Get the geodeticCRS / geographicCRS from a CRS.

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

Return

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

Parameters

crs: Objet of type CRS (must not be NULL)

PJ_OBJ *proj_obj_crs_get_horizontal_datum(PJ_OBJ *crs)¶

Get the horizontal datum from a CRS.

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

Return

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

Parameters

crs: Objet of type CRS (must not be NULL)

PJ_OBJ *proj_obj_crs_get_sub_crs(PJ_OBJ *crs, int index)¶

Get a CRS component from a CompoundCRS.

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

Return

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

Parameters

crs: Objet of type CRS (must not be NULL)
index: Index of the CRS component (typically 0 = horizontal, 1 = vertical)

PJ_OBJ *proj_obj_crs_create_bound_crs_to_WGS84(PJ_OBJ *crs)¶

Returns potentially a BoundCRS, with a transformation to EPSG:4326, wrapping this CRS.

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

This is the same as method osgeo::proj::crs::CRS::createBoundCRSToWGS84IfPossible()

Return

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

Parameters

crs: Objet of type CRS (must not be NULL)

PJ_OBJ *proj_obj_get_ellipsoid(PJ_OBJ *obj)¶

Get the ellipsoid from a CRS or a GeodeticReferenceFrame.

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

Return

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

Parameters

obj: Objet of type CRS or GeodeticReferenceFrame (must not be NULL)

int proj_obj_ellipsoid_get_parameters(PJ_OBJ *ellipsoid, double *pSemiMajorMetre, double *pSemiMinorMetre, int *pIsSemiMinorComputed, double *pInverseFlattening)¶

Return ellipsoid parameters.

Return

TRUE in case of success.

Parameters

ellipsoid: Object of type Ellipsoid (must not be NULL)
pSemiMajorMetre: Pointer to a value to store the semi-major axis in metre. or NULL
pSemiMinorMetre: Pointer to a value to store the semi-minor axis in metre. or NULL
pIsSemiMinorComputed: Pointer to a boolean value to indicate if the semi-minor value was computed. If FALSE, its value comes from the definition. or NULL
pInverseFlattening: Pointer to a value to store the inverse flattening. or NULL

PJ_OBJ *proj_obj_get_prime_meridian(PJ_OBJ *obj)¶

Get the prime meridian of a CRS or a GeodeticReferenceFrame.

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

Return

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

Parameters

obj: Objet of type CRS or GeodeticReferenceFrame (must not be NULL)

int proj_obj_prime_meridian_get_parameters(PJ_OBJ *prime_meridian, double *pLongitude, double *pLongitudeUnitConvFactor, const char **pLongitudeUnitName)¶

Return prime meridian parameters.

Return

TRUE in case of success.

Parameters

prime_meridian: Object of type PrimeMeridian (must not be NULL)
pLongitude: Pointer to a value to store the longitude of the prime meridian, in its native unit. or NULL
pLongitudeUnitConvFactor: Pointer to a value to store the conversion factor of the prime meridian longitude unit to radian. or NULL
pLongitudeUnitName: Pointer to a string value to store the unit name. or NULL

PJ_OBJ *proj_obj_crs_get_coordoperation(PJ_OBJ *crs, const char **pMethodName, const char **pMethodAuthorityName, const char **pMethodCode)¶

Return the Conversion of a DerivedCRS (such as a ProjectedCRS), or the Transformation from the baseCRS to the hubCRS of a BoundCRS.

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

Return

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

Parameters

crs: Objet of type DerivedCRS or BoundCRSs (must not be NULL)
pMethodName: Pointer to a string value to store the method (projection) name. or NULL
pMethodAuthorityName: Pointer to a string value to store the method authority name. or NULL
pMethodCode: Pointer to a string value to store the method code. or NULL

int proj_coordoperation_is_instanciable(PJ_OBJ *coordoperation)¶

Return whether a coordinate operation can be instanciated as a PROJ pipeline, checking in particular that referenced grids are available.

Return

TRUE or FALSE.

Parameters

coordoperation: Objet of type CoordinateOperation or derived classes (must not be NULL)

int proj_coordoperation_get_param_count(PJ_OBJ *coordoperation)¶

Return the number of parameters of a SingleOperation.

Parameters

coordoperation: Objet of type SingleOperation or derived classes (must not be NULL)

int proj_coordoperation_get_param_index(PJ_OBJ *coordoperation, const char *name)¶

Return the index of a parameter of a SingleOperation.

Return

index (>=0), or -1 in case of error.

Parameters

coordoperation: Objet of type SingleOperation or derived classes (must not be NULL)
name: Parameter name. Must not be NULL

int proj_coordoperation_get_param(PJ_OBJ *coordoperation, int index, const char **pName, const char **pNameAuthorityName, const char **pNameCode, double *pValue, const char **pValueString, double *pValueUnitConvFactor, const char **pValueUnitName)¶

Return a parameter of a SingleOperation.

Return

TRUE in case of success.

Parameters

coordoperation: Objet of type SingleOperation or derived classes (must not be NULL)
index: Parameter index.
pName: Pointer to a string value to store the parameter name. or NULL
pNameAuthorityName: Pointer to a string value to store the parameter authority name. or NULL
pNameCode: Pointer to a string value to store the parameter code. or NULL
pValue: Pointer to a double value to store the parameter value (if numeric). or NULL
pValueString: Pointer to a string value to store the parameter value (if of type string). or NULL
pValueUnitConvFactor: Pointer to a double value to store the parameter unit conversion factor. or NULL
pValueUnitName: Pointer to a string value to store the parameter unit name. or NULL

int proj_coordoperation_get_grid_used_count(PJ_OBJ *coordoperation)¶

Return the number of grids used by a CoordinateOperation.

Parameters

coordoperation: Objet of type CoordinateOperation or derived classes (must not be NULL)

int proj_coordoperation_get_grid_used(PJ_OBJ *coordoperation, int index, const char **pShortName, const char **pFullName, const char **pPackageName, const char **pURL, int *pDirectDownload, int *pOpenLicense, int *pAvailable)¶

Return a parameter of a SingleOperation.

Return

TRUE in case of success.

Parameters

coordoperation: Objet of type SingleOperation or derived classes (must not be NULL)
index: Parameter index.
pShortName: Pointer to a string value to store the grid short name. or NULL
pFullName: Pointer to a string value to store the grid full filename. or NULL
pPackageName: Pointer to a string value to store the package name where the grid might be found. or NULL
pURL: Pointer to a string value to store the grid URL or the package URL where the grid might be found. or NULL
pDirectDownload: Pointer to a int (boolean) value to store whether *pURL can be downloaded directly. or NULL
pOpenLicense: Pointer to a int (boolean) value to store whether the grid is released with an open license. or NULL
pAvailable: Pointer to a int (boolean) value to store whether the grid is available at runtime. or NULL