path: root/libtellurian_end_point.3

.TH LIBTELLURIAN_END_POINT 3 libtellurian
.SH NAME
libtellurian_end_point \- Calculate travel end-point

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

void libtellurian_end_point(double \fIlatitude1\fP, double \fIlongitude1\fP,
                            double \fIazimuth1\fP, double \fIdistance\fP,
                            double *\fIlatitude2_out\fP, double *\fIlongitude2_out\fP,
                            double *\fIazimuth2_out\fP);

void libtellurian_end_point_radians(double \fIlatitude1\fP, double \fIlongitude1\fP,
                                    double \fIazimuth1\fP, double \fIdistance\fP,
                                    double *\fIlatitude2_out\fP, double *\fIlongitude2_out\fP,
                                    double *\fIazimuth2_out\fP);
.fi
.PP
Link with
.I -ltellurian
.IR -lm .

.SH DESCRIPTION
The
.BR libtellurian_end_point ()
function models the Earth as an oblate
spheroid and calculates a good approximate
location where a traveller starting at
.RI ( latitude1 ", " longitude1 )
travelling in an azimuthal direction,
.IR azimuth1 ,
for a specified
.IR distance ,
measured in meters, along the ellipsoid.
.PP
The location the traveller will end at will
be stored at
.RI ( *latitude2_out ", " *longitude2_out ).
along the ellipsoid. The azimuth from this
point to continue the on the extended, circular
path (eventually returning to the starting
pointer after having traveled the azimuthal
circumference of the Earth) in
.IR *azimuth2_out .
.PP
However
.IR latitude2_out ,
.IR longitude2_out ,
and
.I azimuth2_out
can each, independently, be set to
.IR NULL ,
which will cause the function to skip the
specific calculations needed for the value
stored in the referenced memory.
.PP
The coordinates shall be specified, and are
returned, according to GPS and in degrees.
Likewise
.I azimuth1
shall be in degrees, and
.I *azimuth2_out
will be in degress.
.PP
The
.BR libtellurian_end_point_radians ()
function is identical to the
.BR libtellurian_end_point ()
function except that radians are
used instead of degress for
.IR latitude1 ,
.IR longitude1 ,
.IR azimuth1 ,
.IR *latitude2_out ,
.IR *longitude2_out ,
and
.IR *azimuth2_out .

.SH RETURN VALUE
None.

.SH ERRORS
None.

.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 specified by
.I azimuth1
at this point. Hence,
.I *azimuth2_out
will be the direction you would continue
along the great ellipsoid, at
.RI ( *latitude2_out ", " *longitude2_out ),
\m[red]not\m[] the direction for returning to
.RI ( latitude1 ", " longitude1 ).

.SH SEE ALSO
.BR libtellurian (7)