C library for Geodesics  1.50.1
Geodesic routines implemented in C
Author
Charles F. F. Karney (charl.nosp@m.es@k.nosp@m.arney.nosp@m..com)
Version
1.50

The documentation for other versions is available at https://geographiclib.sourceforge.io/m.nn/C for versions numbers m.nn ≥ 1.28.

Abstract

This is a C implementation of the geodesic algorithms from GeographicLib. This is a self-contained library (requiring only the standard C math library) which makes it easy to do geodesic computations for an ellipsoid of revolution in a C program. It is included with version 4.9.0 of PROJ and later. It uses ANSI C as described in B. W. Kernigan and D. M. Ritchie, The C Programming Language, 2nd Ed. (Prentice Hall, 1988), and so should compile correctly with just about any C compiler. However, the C99 math functions are used if they are available.

Downloading the source

The C library is part of GeographicLib which available for download at

as either a compressed tar file (tar.gz) or a zip file. After unpacking the source, the C library can be found in the directory legacy/C. The library consists of two files geodesic.c and geodesic.h.

The library is also included as part of PROJ starting with version 4.9.0, where it is used as the computational backend for geod(1). Instructions for how to use the library via proj.4 are given below.

Licensed under the MIT/X11 License; see LICENSE.txt.

Library documentation

Here is the application programming interface for the library (this is just the documentation for the header file, geodesic.h). See also the documentation on the structures geod_geodesic, geod_geodesicline, and geod_polygon.

Sample programs

Also included are 3 small test programs:

  • direct.c is a simple command line utility for solving the direct geodesic problem;
  • inverse.c is a simple command line utility for solving the inverse geodesic problem;
  • planimeter.c is a simple command line utility for computing the area of a geodesic polygon given its vertices.

Here, for example, is inverse.c

/**
* @file inverse.c
* @brief A test program for geod_inverse()
**********************************************************************/
#include <stdio.h>
#include "geodesic.h"
#if defined(_MSC_VER)
/* Squelch warnings about scanf */
# pragma warning (disable: 4996)
#endif
/**
* A simple program to solve the inverse geodesic problem.
*
* This program reads in lines with lat1, lon1, lat2, lon2 and prints out lines
* with azi1, azi2, s12 (for the WGS84 ellipsoid).
**********************************************************************/
int main() {
double a = 6378137, f = 1/298.257223563; /* WGS84 */
double lat1, lon1, azi1, lat2, lon2, azi2, s12;
struct geod_geodesic g;
geod_init(&g, a, f);
while (scanf("%lf %lf %lf %lf", &lat1, &lon1, &lat2, &lon2) == 4) {
geod_inverse(&g, lat1, lon1, lat2, lon2, &s12, &azi1, &azi2);
printf("%.15f %.15f %.10f\n", azi1, azi2, s12);
}
return 0;
}

To compile, link, and run this, you would typically use

cc -o inverse inverse.c geodesic.c -lm
echo 30 0 29.5 179.5 | ./inverse 

These sample programs can also be built with the supplied cmake file, CMakeLists.txt, as follows

mkdir BUILD
cd BUILD
cmake ..
make
make test
echo 30 0 29.5 179.5 | ./inverse 

Alternatively, if you have proj.4 installed, you can compile and link with

cc -c inverse.c
cc -o inverse inverse.o -lproj
echo 30 0 29.5 179.5 | ./inverse 

If proj.4 is installed, e.g., in /usr/local, you might have to use

cc -c -I/usr/local/include inverse.c
cc -o inverse inverse.o -lproj -L/usr/local/lib -Wl,-rpath=/usr/local/lib
echo 30 0 29.5 179.5 | ./inverse 

Using the library

  • Put
    #include "geodesic.h"
    in your source code. If you are using the library via proj.4, change this to
    #include <geodesic.h>
  • Make calls to the geodesic routines from your code. The interface to the library is documented in geodesic.h.
  • Compile and link as described above.
  • If linking with proj.4, you might want to check that the version of proj.4 contains the geodesic routines. You can do this with
    #include <proj_api.h>
    #if PJ_VERSION >= 490
    #include <geodesic.h>
    #endif
    ...
  • You can check the version of the geodesic library with, e.g.,
    #if GEODESIC_VERSION >= GEODESIC_VERSION_NUM(1,40,0)
    ...
    #endif

External links

Change log

  • Version 1.50 (released 2019-09-22)
    • Allow arbitrarily complex polygons in geod_polygon_*. In the case of self-intersecting polygons the area is accumulated "algebraically", e.g., the areas of the 2 loops in a figure-8 polygon will partially cancel.
    • Workaround bugs in fmod and sin in Visual Studio 10, 11, and 12 and relax delta for GeodSolve59 in geodtest (tagged v1.49.1-c).
    • Fix bug in geod_polygon_addedge which caused the count of pole encirclings to be wrong, sometimes resulting in an incorrect area if a polygon vertex had longitude = 0 (tagged v1.49.2-c).
  • Version 1.49 (released 2017-10-05)
    • Fix more warning messages from some compilers; add tests.
  • Version 1.48 (released 2017-04-09)
    • This is the version slated for the version of proj.4 after 4.9.4 (tagged v1.48.1-c).
    • Fix warnings messages from some compilers.
    • Change default range for longitude and azimuth to (−180°, 180°] (instead of [−180°, 180°)).
  • Version 1.47 (released 2017-02-15)
    • This is the version incorporated into proj.4 version 4.9.3 (tagged v1.46.1-c).
    • Fix the order of declarations, incorporating the patches in version 1.46.1.
    • Improve accuracy of area calculation (fixing a flaw introduced in version 1.46).
  • Version 1.46 (released 2016-02-15)
    • Add s13 and a13 to the geod_geodesicline struct.
    • Add geod_directline, geod_gendirectline, and geod_inverseline.
    • More accurate inverse solution when longitude difference is close to 180°.
  • Version 1.45 (released 2015-09-30)
    • The solution of the inverse problem now correctly returns NaNs if one of the latitudes is a NaN.
    • Include a test suite that can be run with "make test" after configuring with cmake.
    • Add geod_polygon_clear().
  • Version 1.44 (released 2015-08-14)
    • This is the version incorporated into proj.4 version 4.9.2.
    • Improve accuracy of calculations by evaluating trigonometric functions more carefully and replacing the series for the reduced length with one with a smaller truncation error.
    • The allowed ranges for longitudes and azimuths is now unlimited; it used to be [−540°, 540°).
    • Enforce the restriction of latitude to [−90°, 90°] by returning NaNs if the latitude is outside this range.
    • The inverse calculation sets s12 to zero for coincident points at pole (instead of returning a tiny quantity).
  • Version 1.40 (released 2014-12-18)
    • This is the version incorporated into proj.4 version 4.9.1.
  • Version 1.32 (released 2013-07-12)
    • This is the version incorporated into proj.4 version 4.9.0.
geod_inverse
void GEOD_DLL geod_inverse(const struct geod_geodesic *g, double lat1, double lon1, double lat2, double lon2, double *ps12, double *pazi1, double *pazi2)
geod_geodesic::f
double f
Definition: geodesic.h:184
geodesic.h
API for the geodesic routines in C.
geod_geodesic::a
double a
Definition: geodesic.h:183
geod_geodesic
Definition: geodesic.h:182
main
int main()
Definition: direct.c:21
geod_init
void GEOD_DLL geod_init(struct geod_geodesic *g, double a, double f)