diff options
| -rw-r--r-- | TODO | 3 | ||||
| -rw-r--r-- | libtellurian.7 | 88 | ||||
| -rw-r--r-- | libtellurian.h | 16 | ||||
| l--------- | libtellurian_azimuth.3 | 1 | ||||
| l--------- | libtellurian_azimuth_radians.3 | 1 | ||||
| l--------- | libtellurian_azimuthal_radius_radians.3 | 1 | ||||
| -rw-r--r-- | libtellurian_coarse_distance.3 | 60 | ||||
| l--------- | libtellurian_coarse_distance_radians.3 | 1 | ||||
| -rw-r--r-- | libtellurian_distance.3 | 109 | ||||
| l--------- | libtellurian_distance_radians.3 | 1 | ||||
| l--------- | libtellurian_elevated_gravity_radians.3 | 1 | ||||
| -rw-r--r-- | libtellurian_end_point.3 | 84 | ||||
| l--------- | libtellurian_end_point_radians.3 | 1 | ||||
| l--------- | libtellurian_gaussian_radius_radians.3 | 1 | ||||
| l--------- | libtellurian_meridan_radius_radians.3 | 1 | ||||
| l--------- | libtellurian_normal_gravity_radians.3 | 1 | ||||
| -rw-r--r-- | libtellurian_sea_level.3 | 59 | ||||
| l--------- | libtellurian_sea_level_radians.3 | 1 | ||||
| l--------- | libtellurian_transverse_radius_radians.3 | 1 |
19 files changed, 422 insertions, 9 deletions
@@ -1,3 +1,4 @@ -Add man pages +Add header man page +Add const man pages Finish libtellurian_end_point_radians Finish libtellurian_vincenty_inverse__ diff --git a/libtellurian.7 b/libtellurian.7 new file mode 100644 index 0000000..812fca8 --- /dev/null +++ b/libtellurian.7 @@ -0,0 +1,88 @@ +.TH LIBTELLURIAN 7 libtellurian +.SH NAME +libtellurian \- Geodesy library + +.SH SYNPOSIS +.ni +#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_elevated_gravity (3) +Adjust a gravity for some ellipsoidal height. +.PP +.I Radius of curvature calculation +.TP +.BR libtellurian_meridan_radius (3) +Calculate the Earth's meridan 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. diff --git a/libtellurian.h b/libtellurian.h index be7ec93..2113f29 100644 --- a/libtellurian.h +++ b/libtellurian.h @@ -361,7 +361,7 @@ double libtellurian_elevated_gravity_radians(double gravity, double latitude, do * Calculate the Earth's meridan radius of curvature at some latitude * * @param latitude GPS latitude coordinate, in degrees - * @return The meridan radius of curvature, in meters (for radians!) + * @return The meridan radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_meridan_radius(double latitude); @@ -370,7 +370,7 @@ double libtellurian_meridan_radius(double latitude); * Calculate the Earth's meridan radius of curvature at some latitude * * @param latitude GPS latitude coordinate, in radians - * @return The meridan radius of curvature, in meters (for radians) + * @return The meridan radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_meridan_radius_radians(double latitude); @@ -379,7 +379,7 @@ double libtellurian_meridan_radius_radians(double latitude); * Calculate the Earth's transverse radius of curvature at some latitude * * @param latitude GPS latitude coordinate, in degrees - * @return The transverse radius of curvature, in meters (for radians!) + * @return The transverse radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_transverse_radius(double latitude); @@ -388,7 +388,7 @@ double libtellurian_transverse_radius(double latitude); * Calculate the Earth's transverse radius of curvature at some latitude * * @param latitude GPS latitude coordinate, in radians - * @return The transverse radius of curvature, in meters (for radians) + * @return The transverse radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_transverse_radius_radians(double latitude); @@ -399,7 +399,7 @@ double libtellurian_transverse_radius_radians(double latitude); * * @param latitude GPS latitude coordinate, in degrees * @param azimuth The azimuth, in degrees - * @return The transverse radius of curvature, in meters (for radians!) + * @return The transverse radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_azimuthal_radius(double latitude, double azimuth); @@ -410,7 +410,7 @@ double libtellurian_azimuthal_radius(double latitude, double azimuth); * * @param latitude GPS latitude coordinate, in radians * @param azimuth The azimuth, in radians - * @return The transverse radius of curvature, in meters (for radians) + * @return The transverse radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_azimuthal_radius_radians(double latitude, double azimuth); @@ -419,7 +419,7 @@ double libtellurian_azimuthal_radius_radians(double latitude, double azimuth); * Calculate the Earth's Gaussian radius of curvature at some latitude * * @param latitude GPS latitude coordinate, in degrees - * @return The Gaussian radius of curvature, in meters (for radians!) + * @return The Gaussian radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_gaussian_radius(double latitude); @@ -428,7 +428,7 @@ double libtellurian_gaussian_radius(double latitude); * Calculate the Earth's Gaussian radius of curvature at some latitude * * @param latitude GPS latitude coordinate, in radians - * @return The Gaussian radius of curvature, in meters (for radians) + * @return The Gaussian radius of curvature, in meters */ LIBTELLURIAN_CONST__ double libtellurian_gaussian_radius_radians(double latitude); diff --git a/libtellurian_azimuth.3 b/libtellurian_azimuth.3 new file mode 120000 index 0000000..1489c40 --- /dev/null +++ b/libtellurian_azimuth.3 @@ -0,0 +1 @@ +libtellurian_distance.3
\ No newline at end of file diff --git a/libtellurian_azimuth_radians.3 b/libtellurian_azimuth_radians.3 new file mode 120000 index 0000000..fcca142 --- /dev/null +++ b/libtellurian_azimuth_radians.3 @@ -0,0 +1 @@ +libtellurian_azimuth.3
\ No newline at end of file diff --git a/libtellurian_azimuthal_radius_radians.3 b/libtellurian_azimuthal_radius_radians.3 new file mode 120000 index 0000000..044abb3 --- /dev/null +++ b/libtellurian_azimuthal_radius_radians.3 @@ -0,0 +1 @@ +libtellurian_azimuthal_radius.3
\ No newline at end of file diff --git a/libtellurian_coarse_distance.3 b/libtellurian_coarse_distance.3 new file mode 100644 index 0000000..f1c308c --- /dev/null +++ b/libtellurian_coarse_distance.3 @@ -0,0 +1,60 @@ +.TH LIBTELLURIAN_COARSE_DISTANCE 3 libtellurian +.SH NAME +libtellurian_coarse_distance \- Calculate distance between two locations + +.SH SYNPOSIS +.ni +#include <libtellurian.h> + +double libtellurian_coarse_distance(double \fIlatitude1\fP, double \fIlongitude1\fP, + double \fIlatitude2\fP, double \fIlongitude2\fP); + +double libtellurian_coarse_distance_radians(double \fIlatitude1\fP, double \fIlongitude1\fP, + double \fIlatitude2\fP, double \fIlongitude2\fP); +.fi +.PP +Link with +.I -ltellurian +.IR -lm . + +.SH DESCRIPTION +The +.BR libtellurian_coarse_distance () +function calculates a coarse approximate +spherical distance between two locations, +.RI ( latitude1 ", " longitude1 ) +and +.RI ( latitude2 ", " longitude2 ), +on the Earth's surface modelling the Earth +as a perfect sphere. +.PP +The coordinates shall be specified according +to GPS and in degrees. +.PP +The +.BR libtellurian_coarse_distance_radians () +function is identical to the +.BR libtellurian_coarse_distance () +function except that +.IR latitude1 , +.IR longitude1 , +.IR latitude2 , +and +.I longitude2 +shall be specified in radians. + +.SH RETURN VALUE +The +.BR libtellurian_coarse_distance () +and +.BR libtellurian_coarse_distance_radians () +functions return the distance, along the Earth's +surface, between the two points measured in +meters. + +.SH ERRORS +None. + +.SH SEE ALSO +.BR libtellurian (7), +.BR libtellurian_distance (3) diff --git a/libtellurian_coarse_distance_radians.3 b/libtellurian_coarse_distance_radians.3 new file mode 120000 index 0000000..48e4642 --- /dev/null +++ b/libtellurian_coarse_distance_radians.3 @@ -0,0 +1 @@ +libtellurian_coarse_distance.3
\ No newline at end of file diff --git a/libtellurian_distance.3 b/libtellurian_distance.3 new file mode 100644 index 0000000..47e0ee1 --- /dev/null +++ b/libtellurian_distance.3 @@ -0,0 +1,109 @@ +.TH LIBTELLURIAN_DISTANCE 3 libtellurian +.SH NAME +libtellurian_distance \- Calculate distance between two locations + +.SH SYNPOSIS +.ni +#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 degress, 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 SEE ALSO +.BR libtellurian (7), +.BR libtellurian_coarse_distance (3) diff --git a/libtellurian_distance_radians.3 b/libtellurian_distance_radians.3 new file mode 120000 index 0000000..1489c40 --- /dev/null +++ b/libtellurian_distance_radians.3 @@ -0,0 +1 @@ +libtellurian_distance.3
\ No newline at end of file diff --git a/libtellurian_elevated_gravity_radians.3 b/libtellurian_elevated_gravity_radians.3 new file mode 120000 index 0000000..afd5318 --- /dev/null +++ b/libtellurian_elevated_gravity_radians.3 @@ -0,0 +1 @@ +libtellurian_elevated_gravity.3
\ No newline at end of file diff --git a/libtellurian_end_point.3 b/libtellurian_end_point.3 new file mode 100644 index 0000000..3a93fe9 --- /dev/null +++ b/libtellurian_end_point.3 @@ -0,0 +1,84 @@ +.TH LIBTELLURIAN_END_POINT 3 libtellurian +.SH NAME +libtellurian_end_point \- Calculate travel end-point + +.SH SYNPOSIS +.ni +#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 the starting point will be stored 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 SEE ALSO +.BR libtellurian (7) diff --git a/libtellurian_end_point_radians.3 b/libtellurian_end_point_radians.3 new file mode 120000 index 0000000..94e8726 --- /dev/null +++ b/libtellurian_end_point_radians.3 @@ -0,0 +1 @@ +libtellurian_end_point.3
\ No newline at end of file diff --git a/libtellurian_gaussian_radius_radians.3 b/libtellurian_gaussian_radius_radians.3 new file mode 120000 index 0000000..847ddec --- /dev/null +++ b/libtellurian_gaussian_radius_radians.3 @@ -0,0 +1 @@ +libtellurian_gaussian_radius.3
\ No newline at end of file diff --git a/libtellurian_meridan_radius_radians.3 b/libtellurian_meridan_radius_radians.3 new file mode 120000 index 0000000..f8247e4 --- /dev/null +++ b/libtellurian_meridan_radius_radians.3 @@ -0,0 +1 @@ +libtellurian_meridan_radius.3
\ No newline at end of file diff --git a/libtellurian_normal_gravity_radians.3 b/libtellurian_normal_gravity_radians.3 new file mode 120000 index 0000000..6018cdd --- /dev/null +++ b/libtellurian_normal_gravity_radians.3 @@ -0,0 +1 @@ +libtellurian_normal_gravity.3
\ No newline at end of file diff --git a/libtellurian_sea_level.3 b/libtellurian_sea_level.3 new file mode 100644 index 0000000..80dc6ea --- /dev/null +++ b/libtellurian_sea_level.3 @@ -0,0 +1,59 @@ +.TH LIBTELLURIAN_SEA_LEVEL 3 libtellurian +.SH NAME +libtellurian_sea_level \- Calculate a geocentric radius + +.SH SYNPOSIS +.ni +#include <libtellurian.h> + +double libtellurian_sea_level(double \fIlatitude\fP); + +double libtellurian_sea_level_radians(double \fIlatitude\fP); +.fi +.PP +Link with +.I -ltellurian +.IR -lm . + +.SH DESCRIPTION +The +.BR libtellurian_sea_level () +function calculates the distance from the centre of +the Earth the ellipsoid, for any point on a the given +.IR latitude , +which givens the nominal sea level at this position, +which is close to the actual sea level, and is the +reference datum for the altitude (ellipsoidal height) +reported in raw GPS measurements. +.PP +The +.I latitude +shall be specified according to GPS and in degrees. +.PP +The +.BR libtellurian_sea_level_radians () +function is identical to the +.BR libtellurian_sea_level () +function except that +.I latitude +shall be specified in radians. + +.SH RETURN VALUE +The +.BR libtellurian_sea_level () +and +.BR libtellurian_sea_level_radians () +functions return the distance from the centre of +the Earth to the ellipsoid, measured in meters. + +.SH ERRORS +None. + +.SH NOTES +Some GPS systems, espcially those for hiking, surveying, +and aviation, report orthometric height (height above +sea level), rather than ellipsoidal height to make it +easier for the user to interpret. + +.SH SEE ALSO +.BR libtellurian (7) diff --git a/libtellurian_sea_level_radians.3 b/libtellurian_sea_level_radians.3 new file mode 120000 index 0000000..c881fac --- /dev/null +++ b/libtellurian_sea_level_radians.3 @@ -0,0 +1 @@ +libtellurian_sea_level.3
\ No newline at end of file diff --git a/libtellurian_transverse_radius_radians.3 b/libtellurian_transverse_radius_radians.3 new file mode 120000 index 0000000..134958f --- /dev/null +++ b/libtellurian_transverse_radius_radians.3 @@ -0,0 +1 @@ +libtellurian_transverse_radius.3
\ No newline at end of file |