- Author
- Charles F. F. Karney (charl.nosp@m.es@k.nosp@m.arney.nosp@m..com)
- Version
- 1.49
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.4 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.4 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
#include <stdio.h>
#if defined(_MSC_VER)
# pragma warning (disable: 4996)
#endif
double a = 6378137,
f = 1/298.257223563;
double lat1, lon1, azi1, lat2, lon2, azi2, s12;
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 in your source code. If you are using the library via proj.4, change this to
- 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
#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.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.