Library documentation

To use the library put

#include "geodesic.h"

in your source code. If you are using the library via PROJ, change this to

#include <geodesic.h>

The documention of the library is given in the header file, geodesic.h. Here is a brief summary of the functions.

Simple geodesic problems:

• Define a geod_geodesic object and initialize it with geod_init().
• Call geod_direct() and geod_inverse() to solve the direct and inverse geodesic problems.
• geod_gendirect() and geod_geninverse() are more general versions of these routines which allow additional quantites, a12, m12, M12, M21, S12, to be computed. You can also specify the distance in the direct problem in terms of the arc length a12, instead of the distance s12 using the GEOD_ARCMODE flag. Additionally you can keep track of how many times a geodsic encircles the ellipsoid with the GEOD_LONG_UNROLL flag.

The library allows multiple points on a single geodesic line (specified by lat1, lon1, and azi1) to be computed efficiently as follows:

• Define a geod_geodesicline object and initialize it with geod_lineinit().
• Call geod_position() or geod_genposition() to compute the position and azimuth, lat2, lon2, and azi2, at a point a certain distance s12 from the starting point.
• Optionally, you can register the position of a point 3 by specifying s13 or a13 using geod_setdistance() or geod_gensetdistance.
• Alternatively, point 3 can be set up by initializing the geod_geodesicline object with geod_directline(), geod_gendirectline(), or geod_inverseline().

Finally, the library provides a way to compute the area of a polygon. The polygon is defined by adding successively either vertices or edges. This is done "progressively", to allow the area to be tracked as the polygon "grows".

• Define a geod_polygon object and initialize it with geod_polygon_init(). You can declare that the object denotes a polyline instead of a polygon, in which case the area computation is skipped.
• Add an initial point with geod_polygon_addpoint() and successively vertices or edges with geod_polygon_addpoint() or geod_polygon_addedge().
• Call geod_polygon_compute() to return the length and area so far (with polygons, but not polylines, being implicitly closed). Additional vertices or edges may be added subsequently.
• Call geod_polygon_testpoint() or geod_polygon_testedge() to compute the results if a vertex or edge were tentatively added. This would allow a graphical user interface to continuously update the area and length as the cursor is moved which selecting the next vertex.
• geod_polygon_clear() reinitializes the polygon.
• geod_polygonarea() is a convenience function of computing the area directly using arrays latitudes and longitudes.

You can check the version of the geodesic library with, e.g.,

#if GEODESIC_VERSION >= GEODESIC_VERSION_NUM(1,40,0)
...
#endif