Back to Utility programs. Forward to GeographicLib in other languages. Up to Contents.

Here is a brief description of the relationship between the various components of GeographicLib. All of these are defined in the GeographicLib namespace.

TransverseMercator, PolarStereographic, LambertConformalConic, and AlbersEqualArea provide the basic projections. The constructors for these classes specify the ellipsoid and the forward and reverse projections are implemented as const member functions. TransverseMercator uses Krüger's series which have been extended to sixth order in the square of the eccentricity. PolarStereographic, LambertConformalConic, and AlbersEqualArea use the exact formulas for the projections (e.g., from Snyder).

TransverseMercator::UTM and PolarStereographic::UPS are const static instantiations specific for the WGS84 ellipsoid with the UTM and UPS scale factors. (These do not add the standard false eastings or false northings for UTM and UPS.) Similarly LambertConformalConic::Mercator is a const static instantiation of this projection for a WGS84 ellipsoid and a standard parallel of 0 (which gives the Mercator projection). AlbersEqualArea::CylindricalEqualArea, AzimuthalEqualAreaNorth, and AzimuthalEqualAreaSouth, likewise provide special cases of the equal area projection.

UTMUPS uses TransverseMercator::UTM and PolarStereographic::UPS to perform the UTM and UPS projections. The class offers a uniform interface to UTM and UPS by treating UPS as UTM zone 0. This class stores no internal state and the forward and reverse projections are provided via static member functions. The forward projection offers the ability to override the standard UTM/UPS choice and the UTM zone.

MGRS transforms between UTM/UPS coordinates and MGRS. UPS coordinates are handled as UTM zone 0. This class stores no internal state and the forward (UTM/UPS to MGRS) and reverse (MGRS to UTM/UPS) conversions are provided via static member functions.

GeoCoords holds a single geographic location which may be specified as latitude and longitude, UTM or UPS, or MGRS. Member functions are provided to convert between coordinate systems and to provide formatted representations of them. GeoConvert is a simple command line utility to provide access to the GeoCoords class.

TransverseMercatorExact is a drop in replacement for TransverseMercator which uses the exact formulas, based on elliptic functions, for the projection as given by Lee. TransverseMercatorProj is a simple command line utility to test to the TransverseMercator and TransverseMercatorExact.

Geodesic and GeodesicLine perform geodesic calculations. The constructor for Geodesic specifies the ellipsoid and the direct and inverse calculations are implemented as const member functions. Geocentric::WGS84 is a const static instantiation of Geodesic specific for the WGS84 ellipsoid. In order to perform a series of direct geodesic calculations on a single line, the GeodesicLine class can be used. This packages all the information needed to specify a geodesic. A const member function returns the coordinates a specified distance from the starting point. GeodSolve is a simple command line utility to perform geodesic calculations. PolygonAreaT is a class which compute the area of geodesic polygons using the Geodesic class and Planimeter is a command line utility for the same purpose. AzimuthalEquidistant, CassiniSoldner, and Gnomonic are projections based on the Geodesic class. GeodesicProj is a command line utility to exercise these projections.

GeodesicExact and GeodesicLineExact are drop in replacements for Geodesic and GeodesicLine in which the solution is given in terms of elliptic integrals (computed by EllipticFunction). These classes should be used if the absolute value of the flattening exceeds 0.02. The -E option to GeodSolve uses these classes.

NearestNeighbor is a header-only class for efficiently Finding nearest neighbors of a collection of points where the distance function obeys the triangle inequality. The geodesic distance obeys this condition.

Geocentric and LocalCartesian convert between geodetic and geocentric or a local cartesian system. The constructor for specifies the ellipsoid and the forward and reverse projections are implemented as const member functions. Geocentric::WGS84 is a const static instantiation of Geocentric specific for the WGS84 ellipsoid. CartConvert is a simple command line utility to provide access to these classes.

Geoid evaluates geoid heights by interpolation. This is provided by the operator() member function. GeoidEval is a simple command line utility to provide access to this class. This class requires installation of data files for the various geoid models; see Installing the geoid datasets for details.

Ellipsoid is a class which performs latitude conversions and returns various properties of the ellipsoid.

GravityModel evaluates the earth's gravitational field using a particular gravity model. Various member functions return the gravitational field, the gravity disturbance, the gravity anomaly, and the geoid height Gravity is a simple command line utility to provide access to this class. If the field several points on a circle of latitude are sought then use GravityModel::Circle to return a GravityCircle object whose member functions performs the calculations efficiently. (This is particularly important for high degree models such as EGM2008.) These classes requires installation of data files for the various gravity models; see Installing the gravity models for details. NormalGravity computes the gravity of the so-called level ellipsoid.

MagneticModel evaluates the earth's magnetic field using a particular magnetic model. The field is provided by the operator() member function. MagneticField is a simple command line utility to provide access to this class. If the field several points on a circle of latitude are sought then use MagneticModel::Circle to return a MagneticCircle object whose operator() member function performs the calculation efficiently. (This is particularly important for high degree models such as emm2010.) These classes requires installation of data files for the various magnetic models; see Installing the magnetic field models for details.

Constants, Math, Utility, DMS, are general utility class which are used internally by the library; in addition EllipticFunction is used by TransverseMercatorExact, Ellipsoid, and GeodesicExact, and GeodesicLineExact; Accumulator is used by PolygonAreaT, and SphericalEngine, CircularEngine, SphericalHarmonic, SphericalHarmonic1, and SphericalHarmonic2 facilitate the summation of spherical harmonic series which is needed by and MagneticModel and MagneticCircle. One important definition is Math::real which is the type used for real numbers. This allows the library to be easily switched to using floats, doubles, or long doubles. However all the testing has been with real set to double and the library should be installed in this way.

GeographicLib uniformly represents all angle-like variables (latitude, longitude, azimuth) in terms of degrees. To convert from degrees to radians, multiple the quantity by Math::degree(). To convert from radians to degrees , divide the quantity by Math::degree().

In general, the constructors for the classes in GeographicLib check their arguments and throw GeographicErr exceptions with a explanatory message if these are illegal. The member functions, e.g., the projections implemented by TransverseMercator and PolarStereographic, the solutions to the geodesic problem, etc., typically do not check their arguments; the calling program should ensure that the arguments are legitimate. However, the functions implemented by UTMUPS, MGRS, and GeoCoords do check their arguments and may throw GeographicErr exceptions. Similarly Geoid may throw exceptions on file errors. If a function does throw an exception, then the function arguments used for return values will not have been altered.

GeographicLib attempts to act sensibly with NaNs. NaNs in constructors typically throw errors (an exception is GeodesicLine). However, calling the class functions with NaNs as arguments is not an error; NaNs are returned as appropriate. "INV" is treated as an invalid zone designation by UTMUPS. "INVALID" is the corresponding invalid MGRS string (and similarly for GARS, Geohash, and Georef strings). NaNs allow the projection of polylines which are separated by NaNs; in this format they can be easily plotted in MATLAB.

A note about portability. For the most part, the code uses standard C++ and should be able to be deployed on any system with a modern C++ compiler. System dependencies come into

Math – GeographicLib needs to define functions such as atanh for systems that lack them. The system dependence will disappear with the adoption of C++11 because the needed functions are part of that standard.
use of long double – the type is used only for testing. On systems which lack this data type the cmake and autoconf configuration methods should detect its absence and omit the code that depends on it.
Geoid, GravityModel, and MagneticModel – these class uses system-dependent default paths for looking up the respective datasets. It also relies on getenv to find the value of the environment variables.
Utility::readarray reads numerical data from binary files. This assumes that floating point numbers are in IEEE format. It attempts to handled the "endianness" of the target platform using the GEOGRAPHICLIB_WORDS_BIGENDIAN macro (which sets the compile-time constant Math::bigendian).

An attempt is made to maintain backward compatibility with GeographicLib (especially at the level of your source code). Sometimes it's necessary to take actions that depend on what version of GeographicLib is being used; for example, you may want to use a new feature of GeographicLib, but want your code still to work with older versions. In that case, you can test the values of the macros GEOGRAPHICLIB_VERSION_MAJOR, GEOGRAPHICLIB_VERSION_MINOR, and GEOGRAPHICLIB_VERSION_PATCH; these expand to numbers (and the last one is usually 0); these macros appeared starting in version 1.31. There's also a macro GEOGRAPHICLIB_VERSION_STRING which expands to, e.g., "2.1.2"; this macro has been defined since version 1.9. Since version 1.37, there's also been a macro GEOGRAPHICLIB_VERSION which encodes the version as a single number, e.g, 1003900. Do not rely on this particular packing; instead use the macro GEOGRAPHICLIB_VERSION_NUM(a,b,c) which allows you to compare versions with, e.g.,

#if GEOGRAPHICLIB_VERSION >= GEOGRAPHICLIB_VERSION_NUM(1,37,0)
...
#endif 

Back to Utility programs. Forward to GeographicLib in other languages. Up to Contents.