Data types¶

This section describes the numerous data types in use in PROJ.4. As a rule of thumb PROJ.4 data types are prefixed with PJ_, or in one particular case, is simply called PJ. A few notable exceptions can be traced back to the very early days of PROJ.4 when the PJ_ prefix was not consistenly used.

Transformation objects¶

PJ¶: Object containing everything related to a given projection or transformation. As a user of the PROJ.4 library you are only exposed to pointers to this object and the contents is hidden behind the public API. PJ objects are created with proj_create() and destroyed with proj_destroy().

PJ_DIRECTION¶

Enumeration that is used to convey in which direction a given transformation should be performed. Used in transformation function call as described in the section on transformation functions.

Forward transformations are defined with the :c:

typedef enum proj_direction {
    PJ_FWD   =  1,   /* Forward    */
    PJ_IDENT =  0,   /* Do nothing */
    PJ_INV   = -1    /* Inverse    */
} PJ_DIRECTION;

PJ_FWD¶: Perform transformation in the forward direction.

PJ_IDENT¶: Identity. Do nothing.

PJ_INV¶: Perform transformation in the inverse direction.

PJ_CONTEXT¶: Context objects enable safe multi-threaded usage of PROJ.4. Each PJ object is connected to a context (if not specified, the default context is used). All operations within a context should be performed in the same thread. PJ_CONTEXT objects are created with proj_context_create() and destroyed with proj_context_destroy().

PJ_AREA¶: Opaque object describing an area in which a transformation is performed.

Note

This object is not fully implemented yet. It is to be used with proj_create_crs_to_crs() to select the best transformation between the two input coordinate reference systems.

2 dimensional coordinates¶

Various 2-dimensional coordinate data types.

PJ_LP¶

Geodetic coordinate, latitude and longitude. Usually in radians.

typedef struct { double lam, phi; } PJ_LP;

double PJ_LP.lam¶: Longitude. Lambda.

double PJ_LP.phi¶: Latitude. Phi.

PJ_XY¶

2-dimensional cartesian coordinate.

typedef struct { double x, y; } PJ_XY;

double PJ_XY.x¶: Easting.

double PJ_XY.y¶: Northing.

PJ_UV¶

2-dimensional generic coordinate. Usually used when contents can be either a PJ_XY or PJ_LP.

typedef struct {double u, v; } PJ_UV;

double PJ_UV.u¶: Longitude or easting, depending on use.

double PJ_UV.v¶: Latitude or northing, depending on use.

3 dimensional coordinates¶

The following data types are the 3-dimensional equivalents to the data types above.

PJ_LPZ¶

3-dimensional version of PJ_LP. Holds longitude, latitude and a vertical component.

typedef struct { double lam, phi, z; } PJ_LPZ;

double PJ_LPZ.lam¶: Longitude. Lambda.

double PJ_LPZ.phi¶: Latitude. Phi.

double PJ_LPZ.z¶: Vertical component.

PJ_XYZ¶

Cartesian coordinate in 3 dimensions. Extension of PJ_XY.

typedef struct { double x, y, z; } PJ_XYZ;

double PJ_XYZ.x¶: Easting or the X component of a 3D cartesian system.

double PJ_XYZ.y¶: Northing or the Y component of a 3D cartesian system.

double PJ_XYZ.z¶: Vertical component or the Z component of a 3D cartesian system.

PJ_UVW¶

3-dimensional extension of PJ_UV.

typedef struct {double u, v, w; } PJ_UVW;

double PJ_UVW.u¶: Longitude or easting, depending on use.

double PJ_UVW.v¶: Latitude or northing, depending on use.

double PJ_UVW.w¶: Vertical component.

Spatiotemporal coordinate types¶

The following data types are extensions of the triplets above into the time domain.

PJ_LPZT¶

Spatiotemporal version of PJ_LPZ.

typedef struct {
    double lam;
    double phi;
    double z;
    double t;
} PJ_LPZT;

double PJ_LPZT.lam¶: Longitude.

double PJ_LPZT.phi¶: Latitude

double PJ_LPZT.z¶: Vertical component.

double PJ_LPZT.t¶: Time component.

PJ_XYZT¶

Generic spatiotemporal coordinate. Usefull for e.g. cartesian coordinates with an attached time-stamp.

typedef struct {
    double x;
    double y;
    double z;
    double t;
} PJ_XYZT;

double PJ_XYZT.x¶: Easting or the X component of a 3D cartesian system.

double PJ_XYZT.y¶: Northing or the Y component of a 3D cartesian system.

double PJ_XYZT.z¶: Vertical or the Z component of a 3D cartesian system.

double PJ_XYZT.t¶: Time component.

PJ_UVWT¶

Spatiotemporal version of PJ_UVW.

typedef struct { double u, v, w, t; } PJ_UVWT;

double PJ_UVWT.e¶: First horizontal component.

double PJ_UVWT.n¶: Second horizontal component.

double PJ_UVWT.w¶: Vertical component.

double PJ_UVWT.t¶: Temporal component.

Ancillary types for geodetic computations¶

PJ_OPK¶

Rotations, for instance three euler angles.

typedef struct { double o, p, k; } PJ_OPK;

double PJ_OPK.o¶: First rotation angle, omega.

double PJ_OPK.p¶: Second rotation angle, phi.

double PJ_OPK.k¶: Third rotation angle, kappa.

Complex coordinate types¶

PJ_COORD¶

General purpose coordinate union type, applicable in two, three and four dimensions. This is the default coordinate datatype used in PROJ.

typedef union {
    double v[4];
    PJ_XYZT xyzt;
    PJ_UVWT uvwt;
    PJ_LPZT lpzt;
    PJ_XYZ  xyz;
    PJ_UVW  uvw;
    PJ_LPZ  lpz;
    PJ_XY   xy;
    PJ_UV   uv;
    PJ_LP   lp;
} PJ_COORD ;

double v[4]: Generic four-dimensional vector.

PJ_XYZT PJ_COORD.xyzt¶: Spatiotemporal cartesian coordinate.

PJ_UVWT PJ_COORD.uvwt¶: Spatiotemporal generic coordinate.

PJ_LPZT PJ_COORD.lpzt¶: Longitude, latitude, vertical and time components.

PJ_XYZ PJ_COORD.xyz¶: 3-dimensional cartesian coordinate.

PJ_UVW PJ_COORD.uvw¶: 3-dimensional generic coordinate.

PJ_LPZ PJ_COORD.lpz¶: Longitude, latitude and vertical component.

PJ_XY PJ_COORD.xy¶: 2-dimensional cartesian coordinate.

PJ_UV PJ_COORD.uv¶: 2-dimensional generic coordinate.

PJ_LP PJ_COORD.lp¶: Longitude and latitude.

Projection derivatives¶

PJ_FACTORS¶

Various cartographic properties, such as scale factors, angular distortion and meridian convergence. Calculated with proj_factors().

typedef struct {
    double meridional_scale;
    double parallel_scale;
    double areal_scale;

    double angular_distortion;
    double meridian_parallel_angle;
    double meridian_convergence;

    double tissot_semimajor;
    double tissot_semiminor;

    double dx_dlam;
    double dx_dphi;
    double dy_dlam;
    double dy_dphi;
} PJ_FACTORS;

double PJ_FACTORS.meridional_scale¶: Meridional scale at coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.parallel_scale¶: Parallel scale at coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.areal_scale¶: Areal scale factor at coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.angular_distortion¶: Angular distortion at coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.meridian_parallel_angle¶

Meridian/parallel angle, \(\theta^\prime\), at coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.meridian_convergence¶: Meridian convergence at coordinate \(\left(\lambda,\phi\right)\). Sometimes also described as grid declination.

double PJ_FACTORS.tissot_semimajor¶: Maximum scale factor.

double PJ_FACTORS.tissot_semiminor¶: Minimum scale factor.

double PJ_FACTORS.dx_dlam¶: Partial derivative \(\frac{\partial x}{\partial \lambda}\) of coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.dy_dlam¶: Partial derivative \(\frac{\partial y}{\partial \lambda}\) of coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.dx_dphi¶: Partial derivative \(\frac{\partial x}{\partial \phi}\) of coordinate \(\left(\lambda,\phi\right)\).

double PJ_FACTORS.dy_dphi¶: Partial derivative \(\frac{\partial y}{\partial \phi}\) of coordinate \(\left(\lambda,\phi\right)\).

List structures¶

PJ_OPERATIONS¶

Description a PROJ.4 operation

struct PJ_OPERATIONS {
    char    *id;                 /* operation keyword */
    PJ *(*proj)(PJ *);           /* operation  entry point */
    char    * const *descr;      /* description text */
};

char *id¶: Operation keyword.

PJ *(*op)(PJ *)¶: Operation entry point.

char * const *: Description of operation.

PJ_ELLPS¶

Description of ellipsoids defined in PROJ.4

struct PJ_ELLPS {
    char    *id;
    char    *major;
    char    *ell;
    char    *name;
};

char *id¶: Keyword name of the ellipsoid.

char *major¶: Semi-major axis of the ellipsoid, or radius in case of a sphere.

char *ell¶: Elliptical parameter, e.g. rf=298.257 or b=6356772.2.

char *name¶: Name of the ellipsoid

PJ_UNITS¶

Distance units defined in PROJ.

struct PJ_UNITS {
    char    *id;           /* units keyword */
    char    *to_meter;     /* multiply by value to get meters */
    char    *name;         /* comments */
    double   factor;       /* to_meter factor in actual numbers */
};

char *id¶: Keyword for the unit.

char *to_meter¶: Text representation of the factor that converts a given unit to meters

char *name¶: Name of the unit.

double factor¶: Conversion factor that converts the unit to meters.

PJ_PRIME_MERIDIANS¶

Prime meridians defined in PROJ.

struct PJ_PRIME_MERIDIANS {
    char    *id;
    char    *defn;
};

char *id¶: Keyword for the prime meridian

char *def¶: Offset from Greenwich in DMS format.

Info structures¶

PJ_INFO¶

Struct holding information about the current instance of PROJ. Struct is populated by proj_info().

typedef struct {
    int           major;
    int           minor;
    int           patch;
    const char   *release;
    const char   *version;
    const char   *searchpath;
} PJ_INFO;

const char *PJ_INFO.release¶: Release info. Version number and release date, e.g. “Rel. 4.9.3, 15 August 2016”.

const char *PJ_INFO.version¶: Text representation of the full version number, e.g. “4.9.3”.

int PJ_INFO.major¶: Major version number.

int PJ_INFO.minor¶: Minor version number.

int PJ_INFO.patch¶: Patch level of release.

const char PJ_INFO.searchpath¶: Search path for PROJ. List of directories separated by semicolons (Windows) or colons (non-Windows), e.g. “C:\Users\doctorwho;C:\OSGeo4W64\share\proj”. Grids and init files are looked for in directories in the search path.

PJ_PROJ_INFO¶

Struct holding information about a PJ object. Populated by proj_pj_info(). The PJ_PROJ_INFO object provides a view into the internals of a PJ, so once the PJ is destroyed or otherwise becomes invalid, so does the PJ_PROJ_INFO

typedef struct {
    const char  *id;
    const char  *description;
    const char  *definition;
    int          has_inverse;
    double       accuracy;
} PJ_PROJ_INFO;

const char *PJ_PROJ_INFO.id¶: Short ID of the operation the PJ object is based on, that is, what comes afther the +proj= in a proj-string, e.g. “merc”.

const char *PJ_PROJ_INFO.description¶: Long describes of the operation the PJ object is based on, e.g. “Mercator Cyl, Sph&Ell lat_ts=”.

const char *PJ_PROJ_INFO.definition¶: The proj-string that was used to create the PJ object with, e.g. “+proj=merc +lat_0=24 +lon_0=53 +ellps=WGS84”.

int PJ_PROJ_INFO.has_inverse¶: 1 if an inverse mapping of the defined operation exists, otherwise 0.

double PJ_PROJ_INFO.accuracy¶: Expected accuracy of the transformation. -1 if unknown.

PJ_GRID_INFO¶

Struct holding information about a specific grid in the search path of PROJ. Populated with the function proj_grid_info().

typedef struct {
    char        gridname[32];
    char        filename[260];
    char        format[8];
    LP          lowerleft;
    LP          upperright;
    int         n_lon, n_lat;
    double      cs_lon, cs_lat;
} PJ_GRID_INFO;

char PJ_GRID_INFO.gridname[32]: Name of grid, e.g. “BETA2007.gsb”.

char PJ_GRID_INFO¶: Full path of grid file, e.g. “C:\OSGeo4W64\share\proj\BETA2007.gsb”

char PJ_GRID_INFO.format[8]: File format of grid file, e.g. “ntv2”

LP PJ_GRID_INFO.lowerleft¶: Geodetic coordinate of lower left corner of grid.

LP PJ_GRID_INFO.upperright¶: Geodetic coordinate of upper right corner of grid.

int PJ_GRID_INFO.n_lon¶: Number of grid cells in the longitudinal direction.

int PJ_GRID_INFO.n_lat¶: Number of grid cells in the latitudianl direction.

double PJ_GRID_INFO.cs_lon¶: Cell size in the longitudinal direction. In radians.

double PJ_GRID_INFO.cs_lat¶: Cell size in the latitudinal direction. In radians.

PJ_INIT_INFO¶

Struct holding information about a specific init file in the search path of PROJ. Populated with the function proj_init_info().

typedef struct {
    char        name[32];
    char        filename[260];
    char        version[32];
    char        origin[32];
    char        lastupdate[16];
} PJ_INIT_INFO;

char PJ_INIT_INFO.name[32]: Name of init file, e.g. “epsg”.

char PJ_INIT_INFO.filename[260]: Full path of init file, e.g. “C:\OSGeo4W64\share\proj\epsg”

char PJ_INIT_INFO.version[32]: Version number of init-file, e.g. “9.0.0”

char PJ_INIT_INFO.origin[32]: Originating entity of the init file, e.g. “EPSG”

char PJ_INIT_INFO.lastupdate¶: Date of last update of the init-file.