GeographicLib: Getting started

GeographicLib 2.5.2

Loading...
Searching...
No Matches
Getting started
Back to Installing GeographicLib. Forward to Utility programs. Up to Contents.

Much (but not all!) of the useful functionality of GeographicLib is available via simple command line utilities. Interfaces to some of them are available via the web. See Utility programs for documentation on these.

In order to use GeographicLib from C++ code, you will need to

- Include the header files for the GeographicLib classes in your code. E.g.,
  #include <GeographicLib/LambertConformalConic.hpp>
  LambertConformalConic.hpp
  Header for GeographicLib::LambertConformalConic class.
- Include the GeographicLib:: namespace prefix to the GeographicLib classes, or include
  using namespace GeographicLib;
  GeographicLib
  Namespace for GeographicLib.
  Definition Accumulator.cpp:12
  in your code.
- Build your code with cmake. In brief, the necessary steps are:
  - include in your CMakeLists.txt files

            find_package (GeographicLib REQUIRED)
            include_directories (${GeographicLib_INCLUDE_DIRS})
            add_executable (program source1.cpp source2.cpp)
            target_link_libraries (program ${GeographicLib_LIBRARIES})

  - configure your package, e.g., with

            mkdir BUILD
            cd BUILD
            cmake -G "Visual Studio 14" -A x64 \
              -D CMAKE_PREFIX_PATH="C:/Program Files" \
              -D CMAKE_INSTALL_PREFIX="C:/Program Files/testgeog" \
              ..

    Note that you almost always want to configure and build your code somewhere other than the source directory (in this case, we use the BUILD subdirectory). Also, on Windows, make sure that the version of Visual Studio (14 in the example above) architecture (x64 in the example above) is compatible with that used to build GeographicLib. In this example, it's not necessary to specify `CMAKE_PREFIX_PATH`, because `C:/Program Files` is one of the system paths which is searched automatically.
  - build your package. On Linux and MacOS this usually involves just running make. On Windows, you can load the solution file created by cmake into Visual Studio; alternatively, you can get cmake to run build your code with

            cmake --build . --config Release --target ALL_BUILD

    You might also want to install your package (using "make install" or build the "INSTALL" target with the command above). CMake can create the build directory for you. This allows you to configure and run the build on Windows with

            cmake -G "Visual Studio 14" -A x64 \
              -D CMAKE_PREFIX_PATH="C:/Program Files" \
              -D CMAKE_INSTALL_PREFIX="C:/Program Files/testgeog" \
              -S . -B BUILD
            cmake --build BUILD --config Release --target ALL_BUILD

    or on Linux with

            cmake -D CMAKE_INSTALL_PREFIX="/tmp/testgeog" \
              -S . -B BUILD
            make -C BUILD -j4

NOTE: The inclusion of

      include_directories (${GeographicLib_INCLUDE_DIRS})

is only necessary if find_package found GeographicLib via the FindGeographicLib.cmake "module". However, it's OK to include this line even for "config" lookups.

The most import step in using cmake is the find_package command. The cmake documentation describes the locations searched by find_package (the appropriate rule for GeographicLib are those for "Config" mode lookups). In brief, the locations that are searched are (from least specific to most specific, i.e., in reverse order) are

- under the system paths, i.e., locations such as `C:/Program Files` and `/usr/local`);
- frequently, it's necessary to search within a "package directory" (or set of directories) for external dependencies; this is given by a (semicolon separated) list of directories specified by the cmake variable `CMAKE_PREFIX_PATH` (illustrated above);
- the package directory for GeographicLib can be overridden with the environment variable `GeographicLib_DIR` (which is the directory under which GeographicLib is installed);
- finally, if you need to point to a particular build of GeographicLib, define the cmake variable `GeographicLib_DIR`, which specifies the absolute path of the directory containing the configuration file `geographiclib-config.cmake` (for debugging this may be the top-level build directory, as opposed to installation directory, for GeographicLib).

Typically, specifying nothing or `CMAKE_PREFIX_PATH` suffices. However the two `GeographicLib_DIR` variables allow for a specific version to be chosen. On Windows systems (with Visual Studio), find_package will only find versions of GeographicLib built with the right version of the compiler. (If you used a non-cmake method of installing GeographicLib, you can try copying cmake/FindGeographicLib.cmake to somewhere in your `CMAKE_MODULE_PATH` in order for find_package to work. However, this method has not been thoroughly tested.)

If GeographicLib is not found, check the values of `GeographicLib_CONSIDERED_CONFIGS` and `GeographicLib_CONSIDERED_VERSIONS`; these list the configuration files and corresponding versions which were considered by find_package.

If GeographicLib is found, then the following cmake variables are set:

- `GeographicLib_FOUND` = 1
- `GeographicLib_VERSION` = 2.5.2
- `GeographicLib_INCLUDE_DIRS`
- `GeographicLib_LIBRARIES` = one of the following two:
- `GeographicLib_SHARED_LIBRARIES` = GeographicLib::GeographicLib_SHARED
- `GeographicLib_STATIC_LIBRARIES` = GeographicLib::GeographicLib_STATIC
- `GeographicLib_LIBRARY_DIRS`
- `GeographicLib_BINARY_DIRS`
- `GEOGRAPHICLIB_DATA` = value of this compile-time parameter
- `GEOGRAPHICLIB_PRECISION` = value of this compile-time parameter (usually 2). You can set this parameter before calling find_package and only versions with a matching value of GEOGRAPHICLIB_PRECISION will be found.

Either of `GeographicLib_SHARED_LIBRARIES` or `GeographicLib_STATIC_LIBRARIES` may be empty, if that version of the library is unavailable. If you require a specific version, SHARED or STATIC, of the library, add a `COMPONENTS` clause to find_package, e.g.,

      find_package (GeographicLib 2.0 REQUIRED COMPONENTS SHARED)

causes only packages which include the shared library to be found. If the package includes both versions of the library, then `GeographicLib_LIBRARIES` is set to the shared version, unless you include

      set (GeographicLib_USE_STATIC_LIBS ON)

before the find_package command. You can check whether `GeographicLib_LIBRARIES` refers to the shared or static library with

      get_target_property (_LIBTYPE ${GeographicLib_LIBRARIES} TYPE)

which results in `_LIBTYPE` being set to `SHARED_LIBRARY` or `STATIC_LIBRARY`. On Windows, cmake takes care of linking to the release or debug version of the library as appropriate. (This assumes that the Release and Debug versions of the libraries were built and installed. This is true for the Windows binary installer for GeographicLib version 1.34 and later.)

You can also use the pkg-config utility to specify compile and link flags. This requires that pkg-config be installed and that it's configured to search, e.g., /usr/local/lib/pgkconfig; if not, define the environment variable `PKG_CONFIG_PATH` to include this directory. The compile and link steps under Linux would typically be

    g++ -c -g -O3 `pkg-config --cflags geographiclib` testprogram.cpp
    g++ -g -o testprogram testprogram.o `pkg-config --libs geographiclib`

Here is a very simple test code, which uses the Geodesic class:

// Small example of using the GeographicLib::Geodesic class
#include <iostream>
#include <GeographicLib/Geodesic.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
const Geodesic& geod = Geodesic::WGS84();
// Distance from JFK to LHR
double
lat1 = 40.6, lon1 = -73.8, // JFK Airport
lat2 = 51.6, lon2 = -0.5; // LHR Airport
double s12;
geod.Inverse(lat1, lon1, lat2, lon2, s12);
cout << s12 / 1000 << " km\n";
}
main
int main(int argc, const char *const argv[])
Definition CartConvert.cpp:28
Geodesic.hpp
Header for GeographicLib::Geodesic class.
GeographicLib::Geodesic
Geodesic calculations
Definition Geodesic.hpp:175
GeographicLib::Geodesic::WGS84
static const Geodesic & WGS84()
Definition Geodesic.cpp:94
GeographicLib::Geodesic::Inverse
Math::real Inverse(real lat1, real lon1, real lat2, real lon2, real &s12, real &azi1, real &azi2, real &m12, real &M12, real &M21, real &S12) const
Definition Geodesic.hpp:689
std
Definition NearestNeighbor.hpp:806

This example is `examples/example-Geodesic-small.cpp`. If you compile, link, and run it according to the instructions above, it should print out

      5551.76 km

Here is a complete CMakeList.txt files you can use to build this test code using the installed library:

    cmake_minimum_required (VERSION 3.17.0)
    project (geodesictest)

    find_package (GeographicLib REQUIRED)

    if (NOT CMAKE_CONFIGURATION_TYPES AND NOT CMAKE_BUILD_TYPE)
      # Set a default build type for single-configuration cmake generators
      # if no build type is set.
      set (CMAKE_BUILD_TYPE "Release")
    endif ()

    add_executable (${PROJECT_NAME} example-Geodesic-small.cpp)
    target_link_libraries (${PROJECT_NAME} ${GeographicLib_LIBRARIES})

If GeographicLib is not installed on your system, you can download and compile the library as part of your project using CMake's `FetchContent` with:

    cmake_minimum_required (VERSION 3.17.0)
    project (geodesictest)

    include(FetchContent)
    FetchContent_Declare(GeographicLib
      GIT_REPOSITORY https://github.com/geographiclib/geographiclib.git
      GIT_TAG        r2.5.2
    )
    FetchContent_MakeAvailable(GeographicLib)

    if (NOT CMAKE_CONFIGURATION_TYPES AND NOT CMAKE_BUILD_TYPE)
      # Set a default build type for single-configuration cmake generators
      # if no build type is set.
      set (CMAKE_BUILD_TYPE "Release")
    endif ()

    add_executable (${PROJECT_NAME} example-Geodesic-small.cpp)
    target_link_libraries (${PROJECT_NAME} GeographicLib::GeographicLib)

In this case, the library needs to be specified as `GeographicLib::GeographicLib` instead of `${GeographicLib_LIBRARIES}`

The next steps are:

- Learn about and run the Utility programs.
- Read the section, Code organization, for an overview of the library.
- Browse the Class List for full documentation on the classes in the library.
- Look at the example code in the examples directory. Each file provides a very simple standalone example of using one GeographicLib class. These are included in the descriptions of the classes.
- Look at the source code for the utilities in the tools directory for more examples of using GeographicLib from C++ code, e.g., GeodesicProj.cpp is a program to performing various geodesic projections.

Here's a list of some of the abbreviations used here with links to the corresponding Wikipedia articles:

- WGS84, World Geodetic System 1984.
- UTM, Universal Transverse Mercator coordinate system.
- UPS, Universal Polar Stereographic coordinate system.
- MGRS, Military Grid Reference System.
- EGM, Earth Gravity Model.
- WMM, World Magnetic Model.
- IGRF, International Geomagnetic Reference Field.

Back to Installing GeographicLib. Forward to Utility programs. Up to Contents.