GeographicLib  1.21
Code organization
Back to Utility programs. Forward to Other interfaces (Javascript, Python, Matlab, Octave). 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.

GeographicLib::TransverseMercator, GeographicLib::PolarStereographic, GeographicLib::LambertConformalConic, and GeographicLib::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).

GeographicLib::TransverseMercator::UTM and GeographicLib::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 GeographicLib::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). GeographicLib::AlbersEqualArea::CylindricalEqualArea, AzimuthalEqualAreaNorth, and AzimuthalEqualAreaSouth, likewise provide special cases of the equal area projection.

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

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

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

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

GeographicLib::Geodesic and GeographicLib::GeodesicLine perform geodesic calculations. The constructor for GeographicLib::Geodesic specifies the ellipsoid and the direct and inverse calculations are implemented as const member functions. GeographicLib::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 GeographicLib::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. Geod is a simple command line utility to perform geodesic calculations. GeographicLib::PolygonArea is a class which compute the area of geodesic polygons using the Geodesic class and Geod is a command line utility for the same purpose. GeographicLib::AzimuthalEquidistant, GeographicLib::CassiniSoldner, and GeographicLib::Gnomonic are projections based on the Geodesic class. GeodesicProj is a command line utility to exercise these projections.

GeographicLib::Geocentric and GeographicLib::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. GeographicLib::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.

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

GeographicLib::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 GeographicLib::GravityModel::Circle to return a GeographicLib::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.

GeographicLib::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 GeographicLib::MagneticModel::Circle to return a GeographicLib::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.

GeographicLib::Constants, GeographicLib::Math, GeographicLib::Utility, GeographicLib::DMS, are general utility class which are used internally by the library; in addition GeographicLib::EllipticFunction is used by GeographicLib::TransverseMercatorExact, GeographicLib::Accumulator is used by GeographicLib::PolygonArea, and GeographicLib::SphericalEngine, GeographicLib::CircularEngine, GeographicLib::SphericalHarmonic, GeographicLib::SphericalHarmonic1, and GeographicLib::SphericalHarmonic2 facilitate the summation of spherical harmonic series which is needed by and GeographicLib::MagneticModel and GeographicLib::MagneticCircle. One important definition is GeographicLib::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.

In general, the constructors for the classes in GeographicLib check their arguments and throw GeographicLib::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 GeographicLib::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. 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

Back to Utility programs. Forward to Other interfaces (Javascript, Python, Matlab, Octave). Up to Contents.