Here is a brief description of the relationship between the various components of GeographicLib.
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 (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. TransverseMercatorTest 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::AzimuthalEquidistant, GeographicLib::CassiniSoldner, and GeographicLib::Gnomonic are projections based on the Geodesic class. EquidistantTest 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 datasets for details.
GeographicLib::Constants, GeographicLib::Math, GeographicLib::DMS, and GeographicLib::EllipticFunction are utility classes which are used internally by the library. One important definition is GeographicLib::Math::real_t 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_t set to double and the library should be installed in this way.
In order to avoid name clashes, all there classes are in the GeographicLib namespace. The header files are included with the GeographicLib/ directory prefix. If compiling within the GeographicLib/src or GeographicLib/tools directories, "../include" should be included in the header search path (e.g., with -I../include). The cpp files implementing the classes include "using namespace std;", however, the headers files and the utility programs do not.
There's an "install" target in the Makefile which installs the library components into $(PREFIX)/lib, $(PREFIX)/include/GeographicLib, $(PREFIX)/bin, $(PREFIX)/share/GeographicLib/doc. Once installed, the library can be used by setting
in tools/Makefile.
The following definitions can be used in your Makefile when using GeographicLib, once it has been installed:
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 be 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.