.TH LIBTELLURIAN_DISTANCE 3 LIBTELLURIAN
.SH NAME
libtellurian_distance \- Calculate distance between two locations

.SH SYNOPSIS
.nf
#include <libtellurian.h>

double libtellurian_distance(double \fIlatitude1\fP, double \fIlongitude1\fP,
                             double \fIlatitude2\fP, double \fIlongitude2\fP,
                             double *\fIazimuth1_out\fP, double *\fIazimuth2_out\fP);

double libtellurian_distance_radians(double \fIlatitude1\fP, double \fIlongitude1\fP,
                                     double \fIlatitude2\fP, double \fIlongitude2\fP,
                                     double *\fIazimuth1_out\fP, double *\fIazimuth2_out\fP);

void libtellurian_azimuth(double \fIlatitude1\fP, double \fIlongitude1\fP,
                          double \fIlatitude2\fP, double \fIlongitude2\fP,
                          double *\fIazimuth1_out\fP, double *\fIazimuth2_out\fP);

void libtellurian_azimuth_radians(double \fIlatitude1\fP, double \fIlongitude1\fP,
                                  double \fIlatitude2\fP, double \fIlongitude2\fP,
                                  double *\fIazimuth1_out\fP, double *\fIazimuth2_out\fP);
.fi
.PP
Link with
.I -ltellurian
.IR -lm .

.SH DESCRIPTION
The
.BR libtellurian_distance ()
function models the Earth as an oblate
spheroid and calculates a good approximate
distance between two locations
.RI ( latitude1 ", " longitude1 )
and
.RI ( latitude2 ", " longitude2 ),
along the ellipsoid.
.PP
The coordinates shall be specified according
to GPS and in degrees.
.PP
At negligible cost, the function can also
calculate the forward azimuths. The forward
azimuth for the first point will be calculated
and stored, in degrees, in
.I *azimuth1_out
unless
.I azimuth1_out
is
.IR NULL ,
and the forward azimuth for the second point
will be calculated and stored, in degrees, in
.I *azimuth2_out
unless
.I azimuth2_out
is
.IR NULL .
.PP
The
.BR libtellurian_distance_radians ()
function is identical to the
.BR libtellurian_distance ()
function except that
.IR latitude1 ,
.IR longitude1 ,
.IR latitude2 ,
and
.I longitude2
shall be specified in radians, and
.I *azimuth1_out
and
.I *azimuth2_out
will be in radians.
.PP
The
.BR libtellurian_azimuth ()
and
.BR libtellurian_azimuth_radians ()
functions are identical to the
.BR libtellurian_distance ()
and
.BR libtellurian_distance_radians ()
functions, respectively, except that do not
calculate the distance between the points,
they only calculate the azimuths.

.SH RETURN VALUE
The
.BR libtellurian_distance ()
and
.BR libtellurian_distance_radians ()
functions return the distance, along the Earth's
surface, between the two points measured in
meters.
.PP
The
.BR libtellurian_azimuth ()
and
.BR libtellurian_azimuth_radians ()
functions do not return any value.

.SH ERRORS
None.

.SH APPLICATION USAGE
The application should use
.BR libtellurian_azimuth ()
or
.BR libtellurian_azimuth_radians ()
whenever the distance will not be used by the
application, likewise, if
.I *azimuth1_out
will not be used
.I azimuth1_out
should be set to
.I NULL
and if
.I *azimuth2_out
will not be used
.I azimuth2_out
should be set to
.IR NULL .
Although this currently has almost no impact on
the application, future versions of the library
may select different methods for performing the
calculations depending on what output is enabled.

.SH NOTES
The (forward) azimuths are defined as the
direction you travelling when you travel
along a great ellipsoid (which is the
shortest distance) from
.RI ( latitude1 ", " longitude1 )
in the direction of
.RI ( latitude2 ", " longitude2 ).
Hence,
.I *azimuth2_out
will be the direction you would continue
along the great ellipsoid, \m[red]not\m[]
the direction for returning to
.RI ( latitude1 ", " longitude1 ).

.SH SEE ALSO
.BR libtellurian (7),
.BR libtellurian_coarse_distance (3)