C library for Geodesics 1.52
Loading...
Searching...
No Matches
Geodesic routines implemented in C
Author
Charles F. F. Karney (charl.nosp@m.es@k.nosp@m.arney.nosp@m..com)
Version
1.52

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 C99.

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;
}
int main()
Definition: direct.c:21
API for the geodesic routines in C.
void GEOD_DLL geod_init(struct geod_geodesic *g, double a, double f)
void GEOD_DLL geod_inverse(const struct geod_geodesic *g, double lat1, double lon1, double lat2, double lon2, double *ps12, double *pazi1, double *pazi2)
double f
Definition: geodesic.h:184
double a
Definition: geodesic.h:183

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.52 (released 2021-03-13)
    • Be more aggressive in preventing negative s12 and m12 for short lines.
    • Initialize reference argument to remquo.
    • Work around inaccurate implementation of hypot with Visual Studio (win32).
  • Version 1.51 (released 2020-11-22)
    • C99 is now required, so there's no need for private implementations of various routines now defined in math.h.
  • 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.