.TH LIBTELLURIAN 7 libtellurian
.SH NAME
libtellurian \- Geodesy library

.SH SYNPOSIS
.nf
#include <libtellurian.h>
.fi
.PP
Link with
.I -ltellurian
.IR -lm .

.SH DESCRIPTION
.B libtellurian
provides a collection of geodesy functions
and constants.
.PP
.B libtellurian
always uses meters as the length unit,
meters per square second as the acceleration unit,
and degrees for the angle unit, except when the
function name uses the suffix \(dq_radians\(dq, in which
case the function uses radians instead of degrees.
All functions that input or output angles have a
version that uses degress and a version that uses
radians. Unless otherwise specified, functions that
use degress convert the input and output to and from
radians and call the version of the function that
uses radians.
.PP
.B libtellurian
provides the following functions (with some similar
alternatives described in these functions' man pages):
.PP
.I Altitude calculation
.TP
.BR libtellurian_sea_level (3)
Calculate distance the centre of the Earth and a
point on the ellipsoid (reference datum for raw GPS
altitude).
.PP
.I Distance and direction calculation
.TP
.BR libtellurian_coarse_distance (3)
Calculate an approximate distance between two
points the on ellipsoid of the Earth. This is a
very cheap operation that is useful to filter out
points from a large collection to find the closest
ones.
.TP
.BR libtellurian_distance (3)
Calculate an accorate distance between two
points the on ellipsoid of the Earth, as well
as the forwards azimuths.
.PP
.I Travel projection
.TP
.BR libtellurian_end_point (3)
Calculate where a traveller will end up after
travelling for some distance in some direction.
.PP
.I Gravity calculation
.TP
.BR libtellurian_normal_gravity (3)
Calculate the normal gravity for some point on
the Earth's ellipsoid.
.TP
.BR libtellurian_effective_gravity (3)
Calculates the effective gravity, at some point
on Earth's ellipsoid, from the normal gravity
at the same point.
.TP
.BR libtellurian_elevated_gravity (3)
Adjust a gravity for some ellipsoidal height.
.PP
.I Radius of curvature calculation
.TP
.BR libtellurian_meridian_radius (3)
Calculate the Earth's meridian radius of
curvature for some latitude.
.TP
.BR libtellurian_transverse_radius (3)
Calculate the Earth's transverse radius of
curvature for some latitude.
.TP
.BR libtellurian_azimuthal_radius (3)
Calculate the Earth's azimuthal radius of
curvature for some latitude and azimuth.
.TP
.BR libtellurian_gaussian_radius (3)
Calculate the Earth's Gaussian (non-directional)
radius of curvature for some latitude.
.PP
See
.BR libtellurian.h (0)
for a listing of available constants.
.SH NOTES
Users, and developers in particular, shall be aware that
this library uses GPS coordinates which are geocentric.
This means that the latitude is base one the angle from
the centre on the earth. There are a number of other
systems, most famously as a linear function of the
arc length, or more commonly in geodesy, the geodesic
latitude which is the enable between the local normal
from the surface and equatorial plane. Users should
take great care ensure the correct correct system (GPS)
is used, and developers should be careful designing
functions for the GPS coordinate system and be aware
the geodesic formulae usually use geodesic latitudes.