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 withproj_create()
and destroyed withproj_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 withproj_context_create()
and destroyed withproj_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.
-
double
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.
-
double
-
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.
-
double
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.
-
double
-
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.
-
double
Ancillary types for geodetic computations¶
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.
-
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
-
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)\).
-
double
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.
-
char * const *
Description of operation.
-
char *
-
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
-
char *
-
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.
-
char *
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.
-
const char *
-
PJ_PROJ_INFO
¶ Struct holding information about a
PJ
object. Populated byproj_pj_info()
. ThePJ_PROJ_INFO
object provides a view into the internals of aPJ
, so once thePJ
is destroyed or otherwise becomes invalid, so does thePJ_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.
-
const char *
-
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.
-