Third commit

Signed-off-by: Mattias Andrée <m@maandree.se>

19 files changed, 422 insertions, 9 deletions

diff --git a/TODO b/TODO
index 09145cf..7974f98 100644
--- a/TODO
+++ b/TODO
@@ -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