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

Transformation setup

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

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

Create a transformation object, or a CRS object, from:

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**) – Vector 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

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.

  • target_crs (const char*) – Destination SRS.

  • 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 of the CRS variety.

Parameters
  • options – should be set to NULL currently.

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

New in version 6.1.0.

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

The input object must be 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.

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

Parameters
  • ctx (PJ_CONTEXT*) – Threading context.

  • obj – Object of type CoordinateOperation

Returns

PJ*

PJ* proj_destroy(PJ *P)

Deallocate a PJ transformation object.

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

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

  1. fully populated

  2. a null pointer and/or a length of zero, which will be treated as a fully populated array of zeroes

  3. of length one, i.e. a constant, which will be treated as a fully populated array of that constant value

Note

Even though he coordinate components are named x, y, z and t, axis ordering of the to and from CRS is respected. Transformations exhibit the same behaviour 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, 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_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 – 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
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
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
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)

int proj_angular_input(PJ *P, enum PJ_DIRECTION dir)

Check if a operation expects input in radians or not.

Parameters
  • P (const 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 (const PJ*) – Transformation object

  • direction (PJ_DIRECTION) – Starting direction of transformation

Returns

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

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/non-sensical values). The exception is for ISO19111 objects of type CoordinateOperation that can be exported as a valid PROJ pipeline. In this case, objects will work for example with 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)

Set if the database must be closed after each C API call where it has been openeded, and automatically re-openeded when needed.

The default value is FALSE, that is the database remains open until the context is destroyed.

Since

6.2

Parameters
  • ctx: PROJ context, or NULL for default context

  • autoclose: Boolean parameter

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.

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.

  • options: should be set to NULL for now

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

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.

Return

value, or nullptr

Parameters
  • ctx: PROJ context, or NULL for default context

  • key: Metadata key. Must not be NULL

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.

Return

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

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.

  • 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 grammaer. It must be freed with proj_string_list_destroy().

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.

Return

Object that must be unreferenced with proj_destroy(), 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

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.

Return

TRUE in case of success

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”, “angular”, “scale”, “time” or “parametric”;

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.

Return

TRUE in case of success.

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

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

“Clone” an object.

Technically this just increases the reference counter on the object, since PJ objects are immutable.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • obj: Object to clone. Must not be NULL.

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.

Return

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

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

PJ_TYPE proj_get_type(const PJ *obj)

Return the type of an object.

Return

its type.

Parameters
  • obj: Object (must not be NULL)

int proj_is_deprecated(const PJ *obj)

Return whether an object is deprecated.

Return

TRUE if it is deprecated, FALSE otherwise

Parameters
  • obj: Object (must not be NULL)

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.

Return

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

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

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

Return whether two objects are equivalent.

Return

TRUE if they are equivalent

Parameters
  • obj: Object (must not be NULL)

  • other: Other object (must not be NULL)

  • criterion: Comparison criterion

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.

Return

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

Parameters
  • obj: Object (must not be NULL)

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.

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

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

Return

a string, or NULL in case of error.

Parameters
  • obj: Object (must not be NULL)

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.

Return

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

Parameters
  • obj: Object (must not be NULL)

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.

Return

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

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.

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.

Return

a string, or NULL in case of error.

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

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.

Return

a string, or NULL in case of error.

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. The currently recognized option is USE_APPROX_TMERC=YES to add the +approx flag to +proj=tmerc or +proj=utm

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.

Return

a string, or NULL in case of error.

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. Defauls to 2 (when multiline output is on).

    • SCHEMA=string. URL to PROJJSON schema. Can be set to empty string to disable it.

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.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

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

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.

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

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

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.

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. 90% means that CRS are equivalent, but the names are not exactly the same. 70% means that CRS are equivalent), but the names do not match at all. 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.

Return

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

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

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

Return

a NULL terminated list of NUL-terminated strings that must be freed with proj_string_list_destroy(), 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_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().

Return

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

See

proj_get_crs_info_list_from_database()

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.

PROJ_CRS_LIST_PARAMETERS *proj_get_crs_list_parameters_create(void)

Instantiate a default set of parameters to be used by proj_get_crs_list().

Return

a new object to free with proj_get_crs_list_parameters_destroy()

void proj_get_crs_list_parameters_destroy(PROJ_CRS_LIST_PARAMETERS *params)

Destroy an object returned by proj_get_crs_list_parameters_create()

PROJ_CRS_INFO **proj_get_crs_info_list_from_database(PJ_CONTEXT *ctx, const char *auth_name, const PROJ_CRS_LIST_PARAMETERS *params, int *out_result_count)

Enumerate CRS objects from the database, taking into account various criteria.

The returned object is an array of PROJ_CRS_INFO* pointers, whose last entry is NULL. This array should be freed with proj_crs_info_list_destroy()

When no filter parameters are set, this is functionnaly equivalent to proj_get_crs_info_list_from_database(), instantiating a PJ* object for each of the proj_create_from_database() and retrieving information with the various getters. However this function will be much faster.

Return

an array of PROJ_CRS_INFO* pointers to be freed with proj_crs_info_list_destroy(), or NULL in case of error.

Parameters
  • ctx: PROJ context, or NULL for default context

  • auth_name: Authority name, used to restrict the search. Or NULL for all authorities.

  • params: Additional criteria, or NULL. If not-NULL, params SHOULD have been allocated by proj_get_crs_list_parameters_create(), as the PROJ_CRS_LIST_PARAMETERS structure might grow over time.

  • out_result_count: Output parameter pointing to an integer to receive the size of the result list. Might be NULL

void proj_crs_info_list_destroy(PROJ_CRS_INFO **list)

Destroy the result returned by proj_get_crs_info_list_from_database().

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

Instantiate a context for building coordinate operations between two CRS.

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

If authority is NULL or the empty string, then coordinate operations from any authority will be searched, with the restrictions set in the authority_to_authority_preference database table. 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 operatiosn will be searched only in that authority namespace.

Return

Object that must be unreferenced with proj_operation_factory_context_destroy(), 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 candidate operations.

void proj_operation_factory_context_destroy(PJ_OPERATION_FACTORY_CONTEXT *ctx)

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
  • ctx: Object, or NULL.

void proj_operation_factory_context_set_desired_accuracy(PJ_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, double accuracy)

Set the desired accuracy of the resulting coordinate transformations.

Parameters
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: 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_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, double west_lon_degree, double south_lat_degree, double east_lon_degree, double north_lat_degree)

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

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: Operation factory context. must not be NULL

  • west_lon_degree: West longitude (in degrees).

  • south_lat_degree: South latitude (in degrees).

  • east_lon_degree: East longitude (in degrees).

  • north_lat_degree: North latitude (in degrees).

void proj_operation_factory_context_set_crs_extent_use(PJ_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, 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
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: 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_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, 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
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: Operation factory context. must not be NULL

  • criterion: patial criterion to use

void proj_operation_factory_context_set_grid_availability_use(PJ_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, PROJ_GRID_AVAILABILITY_USE use)

Set how grid availability is used.

The default is USE_FOR_SORTING.

Parameters
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: 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_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, int usePROJNames)

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

The default is true.

Parameters
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: 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_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, PROJ_INTERMEDIATE_CRS_USE use)

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, with the IF_NO_DIRECT_TRANSFORMATION stratgey, all potential C candidates will be used if there is no direct tranformation.

Parameters
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: Operation factory context. must not be NULL

  • use: whether and how intermediate CRS may be used.

void proj_operation_factory_context_set_allowed_intermediate_crs(PJ_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, 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
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: 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 }

void proj_operation_factory_context_set_discard_superseded(PJ_CONTEXT *ctx, PJ_OPERATION_FACTORY_CONTEXT *factory_ctx, int discard)

Set whether transformations that are superseded (but not deprecated) should be discarded.

Parameters
  • ctx: PROJ context, or NULL for default context

  • factory_ctx: Operation factory context. must not be NULL

  • discard: superseded crs or not

PJ_OBJ_LIST *proj_create_operations(PJ_CONTEXT *ctx, const PJ *source_crs, const PJ *target_crs, const 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_list_destroy(), or NULL in case of error.

Parameters
  • ctx: PROJ context, or NULL for default context

  • 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_list_get_count(const PJ_OBJ_LIST *result)

Return the number of objects in the result set.

Parameters
  • result: Object of type PJ_OBJ_LIST (must not be NULL)

PJ *proj_list_get(PJ_CONTEXT *ctx, const PJ_OBJ_LIST *result, int index)

Return an object from the result set.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • result: Object of type PJ_OBJ_LIST (must not be NULL)

  • index: Index

void proj_list_destroy(PJ_OBJ_LIST *result)

Drops a reference on the result set.

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

Parameters
  • result: Object, or NULL.

PJ *proj_crs_get_geodetic_crs(PJ_CONTEXT *ctx, const PJ *crs)

Get the geodeticCRS / geographicCRS from a CRS.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • crs: Object of type CRS (must not be NULL)

PJ *proj_crs_get_horizontal_datum(PJ_CONTEXT *ctx, const PJ *crs)

Get the horizontal datum from a CRS.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • crs: Object of type CRS (must not be NULL)

PJ *proj_crs_get_sub_crs(PJ_CONTEXT *ctx, const PJ *crs, int index)

Get a CRS component from a CompoundCRS.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • crs: Object of type CRS (must not be NULL)

  • index: Index of the CRS component (typically 0 = horizontal, 1 = vertical)

PJ *proj_crs_get_datum(PJ_CONTEXT *ctx, const PJ *crs)

Returns the datum of a SingleCRS.

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

Return

Object that must be unreferenced with proj_destroy(), or NULL in case of error (or if there is no datum)

Parameters
  • ctx: PROJ context, or NULL for default context

  • crs: Object of type SingleCRS (must not be NULL)

PJ *proj_crs_get_coordinate_system(PJ_CONTEXT *ctx, const PJ *crs)

Returns the coordinate system of a SingleCRS.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • crs: Object of type SingleCRS (must not be NULL)

PJ_COORDINATE_SYSTEM_TYPE proj_cs_get_type(PJ_CONTEXT *ctx, const PJ *cs)

Returns the type of the coordinate system.

Return

type, or PJ_CS_TYPE_UNKNOWN in case of error.

Parameters
  • ctx: PROJ context, or NULL for default context

  • cs: Object of type CoordinateSystem (must not be NULL)

int proj_cs_get_axis_count(PJ_CONTEXT *ctx, const PJ *cs)

Returns the number of axis of the coordinate system.

Return

number of axis, or -1 in case of error.

Parameters
  • ctx: PROJ context, or NULL for default context

  • cs: Object of type CoordinateSystem (must not be NULL)

int proj_cs_get_axis_info(PJ_CONTEXT *ctx, const PJ *cs, int index, const char **out_name, const char **out_abbrev, const char **out_direction, double *out_unit_conv_factor, const char **out_unit_name, const char **out_unit_auth_name, const char **out_unit_code)

Returns information on an axis.

Return

TRUE in case of success

Parameters
  • ctx: PROJ context, or NULL for default context

  • cs: Object of type CoordinateSystem (must not be NULL)

  • index: Index of the coordinate system (between 0 and proj_cs_get_axis_count() - 1)

  • out_name: Pointer to a string value to store the axis name. or NULL

  • out_abbrev: Pointer to a string value to store the axis abbreviation. or NULL

  • out_direction: Pointer to a string value to store the axis direction. or NULL

  • out_unit_conv_factor: Pointer to a double value to store the axis unit conversion factor. or NULL

  • out_unit_name: Pointer to a string value to store the axis unit name. or NULL

  • out_unit_auth_name: Pointer to a string value to store the axis unit authority name. or NULL

  • out_unit_code: Pointer to a string value to store the axis unit code. or NULL

PJ *proj_get_ellipsoid(PJ_CONTEXT *ctx, const PJ *obj)

Get the ellipsoid from a CRS or a GeodeticReferenceFrame.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

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

int proj_ellipsoid_get_parameters(PJ_CONTEXT *ctx, const PJ *ellipsoid, double *out_semi_major_metre, double *out_semi_minor_metre, int *out_is_semi_minor_computed, double *out_inv_flattening)

Return ellipsoid parameters.

Return

TRUE in case of success.

Parameters
  • ctx: PROJ context, or NULL for default context

  • ellipsoid: Object of type Ellipsoid (must not be NULL)

  • out_semi_major_metre: Pointer to a value to store the semi-major axis in metre. or NULL

  • out_semi_minor_metre: Pointer to a value to store the semi-minor axis in metre. or NULL

  • out_is_semi_minor_computed: Pointer to a boolean value to indicate if the semi-minor value was computed. If FALSE, its value comes from the definition. or NULL

  • out_inv_flattening: Pointer to a value to store the inverse flattening. or NULL

PJ *proj_get_prime_meridian(PJ_CONTEXT *ctx, const PJ *obj)

Get the prime meridian of a CRS or a GeodeticReferenceFrame.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

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

int proj_prime_meridian_get_parameters(PJ_CONTEXT *ctx, const PJ *prime_meridian, double *out_longitude, double *out_unit_conv_factor, const char **out_unit_name)

Return prime meridian parameters.

Return

TRUE in case of success.

Parameters
  • ctx: PROJ context, or NULL for default context

  • prime_meridian: Object of type PrimeMeridian (must not be NULL)

  • out_longitude: Pointer to a value to store the longitude of the prime meridian, in its native unit. or NULL

  • out_unit_conv_factor: Pointer to a value to store the conversion factor of the prime meridian longitude unit to radian. or NULL

  • out_unit_name: Pointer to a string value to store the unit name. or NULL

PJ *proj_crs_get_coordoperation(PJ_CONTEXT *ctx, const PJ *crs)

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_destroy() 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_destroy(), or NULL in case of error.

Parameters
  • ctx: PROJ context, or NULL for default context

  • crs: Object of type DerivedCRS or BoundCRSs (must not be NULL)

int proj_coordoperation_get_method_info(PJ_CONTEXT *ctx, const PJ *coordoperation, const char **out_method_name, const char **out_method_auth_name, const char **out_method_code)

Return information on the operation method of the SingleOperation.

Return

TRUE in case of success.

Parameters
  • ctx: PROJ context, or NULL for default context

  • coordoperation: Object of type SingleOperation (typically a Conversion or Transformation) (must not be NULL)

  • out_method_name: Pointer to a string value to store the method (projection) name. or NULL

  • out_method_auth_name: Pointer to a string value to store the method authority name. or NULL

  • out_method_code: Pointer to a string value to store the method code. or NULL

int proj_coordoperation_is_instantiable(PJ_CONTEXT *ctx, const PJ *coordoperation)

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

Return

TRUE or FALSE.

Parameters
  • ctx: PROJ context, or NULL for default context

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

int proj_coordoperation_has_ballpark_transformation(PJ_CONTEXT *ctx, const PJ *coordoperation)

Return whether a coordinate operation has a “ballpark” transformation, that is a very approximate one, due to lack of more accurate transformations.

Typically a null geographic offset between two horizontal datum, or a null vertical offset (or limited to unit changes) between two vertical datum. Errors of several tens to one hundred meters might be expected, compared to more accurate transformations.

Return

TRUE or FALSE.

Parameters
  • ctx: PROJ context, or NULL for default context

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

int proj_coordoperation_get_param_count(PJ_CONTEXT *ctx, const PJ *coordoperation)

Return the number of parameters of a SingleOperation.

Parameters
  • ctx: PROJ context, or NULL for default context

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

int proj_coordoperation_get_param_index(PJ_CONTEXT *ctx, const PJ *coordoperation, const char *name)

Return the index of a parameter of a SingleOperation.

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

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

  • name: Parameter name. Must not be NULL

int proj_coordoperation_get_param(PJ_CONTEXT *ctx, const PJ *coordoperation, int index, const char **out_name, const char **out_auth_name, const char **out_code, double *out_value, const char **out_value_string, double *out_unit_conv_factor, const char **out_unit_name, const char **out_unit_auth_name, const char **out_unit_code, const char **out_unit_category)

Return a parameter of a SingleOperation.

Return

TRUE in case of success.

Parameters
  • ctx: PROJ context, or NULL for default context

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

  • index: Parameter index.

  • out_name: Pointer to a string value to store the parameter name. or NULL

  • out_auth_name: Pointer to a string value to store the parameter authority name. or NULL

  • out_code: Pointer to a string value to store the parameter code. or NULL

  • out_value: Pointer to a double value to store the parameter value (if numeric). or NULL

  • out_value_string: Pointer to a string value to store the parameter value (if of type string). or NULL

  • out_unit_conv_factor: Pointer to a double value to store the parameter unit conversion factor. or NULL

  • out_unit_name: Pointer to a string value to store the parameter unit name. or NULL

  • out_unit_auth_name: Pointer to a string value to store the unit authority name. or NULL

  • out_unit_code: Pointer to a string value to store the unit code. or NULL

  • out_unit_category: Pointer to a string value to store the parameter name. or NULL. This value might be “unknown”, “none”, “linear”, “angular”, “scale”, “time” or “parametric”;

int proj_coordoperation_get_grid_used_count(PJ_CONTEXT *ctx, const PJ *coordoperation)

Return the number of grids used by a CoordinateOperation.

Parameters
  • ctx: PROJ context, or NULL for default context

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

int proj_coordoperation_get_grid_used(PJ_CONTEXT *ctx, const PJ *coordoperation, int index, const char **out_short_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)

Return a parameter of a SingleOperation.

Return

TRUE in case of success.

Parameters
  • ctx: PROJ context, or NULL for default context

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

  • index: Parameter index.

  • out_short_name: Pointer to a string value to store the grid short name. or 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

double proj_coordoperation_get_accuracy(PJ_CONTEXT *ctx, const PJ *obj)

Return the accuracy (in metre) of a coordinate operation.

Return

the accuracy, or a negative value if unknown or in case of error.

Parameters
  • ctx: PROJ context, or NULL for default context

  • coordoperation: Coordinate operation. Must not be NULL.

int proj_coordoperation_get_towgs84_values(PJ_CONTEXT *ctx, const PJ *coordoperation, double *out_values, int value_count, int emit_error_if_incompatible)

Return the parameters of a Helmert transformation as WKT1 TOWGS84 values.

Return

TRUE in case of success, or FALSE if coordoperation is not compatible with a WKT1 TOWGS84 representation.

Parameters
  • ctx: PROJ context, or NULL for default context

  • coordoperation: Object of type Transformation, that can be represented as a WKT1 TOWGS84 node (must not be NULL)

  • out_values: Pointer to an array of value_count double values.

  • value_count: Size of out_values array. The suggested size is 7 to get translation, rotation and scale difference parameters. Rotation and scale difference terms might be zero if the transformation only includes translation parameters. In that case, value_count could be set to 3.

  • emit_error_if_incompatible: Boolean to inicate if an error must be logged if coordoperation is not compatible with a WKT1 TOWGS84 representation.

int proj_concatoperation_get_step_count(PJ_CONTEXT *ctx, const PJ *concatoperation)

Returns the number of steps of a concatenated operation.

The input object must be a concatenated operation.

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • concatoperation: Concatenated operation (must not be NULL)

PJ *proj_concatoperation_get_step(PJ_CONTEXT *ctx, const PJ *concatoperation, int i_step)

Returns a step of a concatenated operation.

The input object must be a concatenated operation.

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

Return

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

Parameters
  • ctx: PROJ context, or NULL for default context

  • concatoperation: Concatenated operation (must not be NULL)

  • i_step: Index of the step to extract. Between 0 and proj_concatoperation_get_step_count()-1