- Author
- Charles F. F. Karney (charl.nosp@m.es@k.nosp@m.arney.nosp@m..com)
- Version
- 1.51
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
#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;
}
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)
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.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.