...HEADmaster

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

1 files changed, 40 insertions, 28 deletions

diff --git a/libtellurian.h b/libtellurian.h
index 609f61d..b294e9c 100644
--- a/libtellurian.h
+++ b/libtellurian.h
@@ -132,6 +132,18 @@
 
 
 /**
+ * The radius, in meters, used by the `libtellurian_coarse_distance`
+ * and `libtellurian_coarse_distance_radians`
+ * 
+ * If you divide the return value of those function by this constant
+ * and then multiply the result with the local radius
+ * (`libtellurian_sea_level`), you will acquire or better local
+ * approximation of the actual distance.
+ */
+extern const double libtellurian_coarse_distance_radius;
+
+
+/**
  * Calculate the distance of the nominal sea level (geocentric
  * radius), for some point on the Earth's surface, from the
  * centre of the Earth
@@ -191,14 +203,14 @@ double libtellurian_coarse_distance_radians(double latitude1, double longitude1,
  * This function is gives good approximate values
  * using an oblate spheroid as a model for the Earth
  * 
- * @param   latitude1     GPS latitude coordinate for the first point, in degrees
- * @param   longitude1    GPS longitude coordinate for the first point, in degrees
- * @param   latitude2     GPS latitude coordinate for the second point, in degrees
- * @param   longitude2    GPS longitude coordinate for the second point, in degrees
+ * @param   latitude1     GPS latitude coordinate for the starting point, in degrees
+ * @param   longitude1    GPS longitude coordinate for the starting point, in degrees
+ * @param   latitude2     GPS latitude coordinate for the end point, in degrees
+ * @param   longitude2    GPS longitude coordinate for the end point, in degrees
  * @param   azimuth1_out  Output parameter for the forward azimuth, in degrees,
- *                        at the first point; or `NULL`
+ *                        at the starting point; or `NULL`
  * @param   azimuth2_out  Output parameter for the forward azimuth, in degrees,
- *                        at the second point; or `NULL`
+ *                        at the end point; or `NULL`
  * @return                Approximate distance between the two points
  * 
  * Calculating the the forward azimuths is not free, but it
@@ -219,14 +231,14 @@ double libtellurian_distance(double latitude1, double longitude1,
  * This function is gives good approximate values
  * using an oblate spheroid as a model for the Earth
  * 
- * @param   latitude1     GPS latitude coordinate for the first point, in radians
- * @param   longitude1    GPS longitude coordinate for the first point, in radians
- * @param   latitude2     GPS latitude coordinate for the second point, in radians
- * @param   longitude2    GPS longitude coordinate for the second point, in radians
+ * @param   latitude1     GPS latitude coordinate for the starting point, in radians
+ * @param   longitude1    GPS longitude coordinate for the starting point, in radians
+ * @param   latitude2     GPS latitude coordinate for the end point, in radians
+ * @param   longitude2    GPS longitude coordinate for the end point, in radians
  * @param   azimuth1_out  Output parameter for the forward azimuth, in radians,
- *                        at the first point; or `NULL`
+ *                        at the starting point; or `NULL`
  * @param   azimuth2_out  Output parameter for the forward azimuth, in radians,
- *                        at the second point; or `NULL`
+ *                        at the end point; or `NULL`
  * @return                Approximate distance between the two points
  * 
  * Calculating the the forward azimuths is not free, but it
@@ -247,14 +259,14 @@ double libtellurian_distance_radians(double latitude1, double longitude1,
  * This function is gives good approximate values
  * using an oblate spheroid as a model for the Earth
  * 
- * @param  latitude1     GPS latitude coordinate for the first point, in degrees
- * @param  longitude1    GPS longitude coordinate for the first point, in degrees
- * @param  latitude2     GPS latitude coordinate for the second point, in degrees
- * @param  longitude2    GPS longitude coordinate for the second point, in degrees
+ * @param  latitude1     GPS latitude coordinate for the starting point, in degrees
+ * @param  longitude1    GPS longitude coordinate for the starting point, in degrees
+ * @param  latitude2     GPS latitude coordinate for the end point, in degrees
+ * @param  longitude2    GPS longitude coordinate for the end point, in degrees
  * @param  azimuth1_out  Output parameter for the forward azimuth, in degrees,
- *                       at the first point; or `NULL`
+ *                       at the starting point; or `NULL`
  * @param  azimuth2_out  Output parameter for the forward azimuth, in degrees,
- *                       at the second point; or `NULL`
+ *                       at the end point; or `NULL`
  * 
  * This function is identical to libtellurian_distance`
  * except it does not compute the distance between the
@@ -270,14 +282,14 @@ void libtellurian_azimuth(double latitude1, double longitude1,
  * This function is gives good approximate values
  * using an oblate spheroid as a model for the Earth
  * 
- * @param  latitude1     GPS latitude coordinate for the first point, in radians
- * @param  longitude1    GPS longitude coordinate for the first point, in radians
- * @param  latitude2     GPS latitude coordinate for the second point, in radians
- * @param  longitude2    GPS longitude coordinate for the second point, in radians
+ * @param  latitude1     GPS latitude coordinate for the starting point, in radians
+ * @param  longitude1    GPS longitude coordinate for the starting point, in radians
+ * @param  latitude2     GPS latitude coordinate for the end point, in radians
+ * @param  longitude2    GPS longitude coordinate for the end point, in radians
  * @param  azimuth1_out  Output parameter for the forward azimuth, in radians,
- *                       at the first point; or `NULL`
+ *                       at the starting point; or `NULL`
  * @param  azimuth2_out  Output parameter for the forward azimuth, in radians,
- *                       at the second point; or `NULL`
+ *                       at the end point; or `NULL`
  * 
  * 
  * This function is identical to libtellurian_distance_radians`
@@ -299,8 +311,8 @@ void libtellurian_azimuth_radians(double latitude1, double longitude1,
  *                         coordinate, in degrees; or `NULL`
  * @param  longitude2_out  Output parameter for the end point's GPS longitude
  *                         coordinate, in degrees; or `NULL`
- * @param  azimuth2_out    Output parameter for the direction from the end point
- *                         to the starting point, in degrees; or `NULL`
+ * @param  azimuth2_out    Output parameter for the forward azimuth at the endpoint,
+ *                         in degrees; or `NULL`
  */
 void libtellurian_end_point(double latitude1, double longitude1, double azimuth1, double distance,
                             double *latitude2_out, double *longitude2_out, double *azimuth2_out);
@@ -317,8 +329,8 @@ void libtellurian_end_point(double latitude1, double longitude1, double azimuth1
  *                         coordinate, in radians; or `NULL`
  * @param  longitude2_out  Output parameter for the end point's GPS longitude
  *                         coordinate, in radians; or `NULL`
- * @param  azimuth2_out    Output parameter for the direction from the end point
- *                         to the starting point, in radians; or `NULL`
+ * @param  azimuth2_out    Output parameter for the forward azimuth at the endpoint,
+ *                         in radians; or `NULL`
  */
 void libtellurian_end_point_radians(double latitude1, double longitude1, double azimuth1, double distance,
                                     double *latitude2_out, double *longitude2_out, double *azimuth2_out);