Added some convenience functions to point3d.

[simgear.git] / simgear / math / polar3d.hxx

diff --git a/simgear/math/polar3d.hxx b/simgear/math/polar3d.hxx
index acd24ae7a9d5c23e2411fca511981d922298e1ba..9d7ebc07a26d3e00ef580d0ca729fa7f6505d999 100644 (file)
--- a/simgear/math/polar3d.hxx
+++ b/simgear/math/polar3d.hxx
@@ -1,5 +1,8 @@
-// polar.hxx -- routines to deal with polar math and transformations
-//
+/**
+ * \file polar3d.hxx
+ * Routines to deal with polar math and transformations.
+ */
+
 // Written by Curtis Olson, started June 1997.
 //
 // Copyright (C) 1997  Curtis L. Olson  - curt@infoplane.com
@@ -22,8 +25,8 @@
 // $Id$
 
 
-#ifndef _POLAR_HXX
-#define _POLAR_HXX
+#ifndef _POLAR3D_HXX
+#define _POLAR3D_HXX
 
 
 #ifndef __cplusplus                                                          
@@ -37,15 +40,23 @@
 #include <simgear/math/point3d.hxx>
 
 
-// Find the Altitude above the Ellipsoid (WGS84) given the Earth
-// Centered Cartesian coordinate vector Distances are specified in
-// meters.
+/** 
+ * Find the Altitude above the Ellipsoid (WGS84) given the Earth
+ * Centered Cartesian coordinate vector Distances are specified in
+ * meters.
+ * @param cp point specified in cartesian coordinates
+ * @return altitude above the (wgs84) earth in meters
+ */
 double sgGeodAltFromCart(const Point3D& cp);
 
 
-// Convert a polar coordinate to a cartesian coordinate.  Lon and Lat
-// must be specified in radians.  The SG convention is for distances
-// to be specified in meters
+/**
+ * Convert a polar coordinate to a cartesian coordinate.  Lon and Lat
+ * must be specified in radians.  The SG convention is for distances
+ * to be specified in meters
+ * @param p point specified in polar coordinates
+ * @return the same point in cartesian coordinates
+ */
 inline Point3D sgPolarToCart3d(const Point3D& p) {
     double tmp = cos( p.lat() ) * p.radius();
 
@@ -55,20 +66,30 @@ inline Point3D sgPolarToCart3d(const Point3D& p) {
 }
 
 
-// Convert a cartesian coordinate to polar coordinates (lon/lat
-// specified in radians.  Distances are specified in meters.
+/**
+ * Convert a cartesian coordinate to polar coordinates (lon/lat
+ * specified in radians.  Distances are specified in meters.
+ * @param cp point specified in cartesian coordinates
+ * @return the same point in polar coordinates
+ */
 inline Point3D sgCartToPolar3d(const Point3D& cp) {
     return Point3D( atan2( cp.y(), cp.x() ),
-                   FG_PI_2 - 
+                   SGD_PI_2 - 
                    atan2( sqrt(cp.x()*cp.x() + cp.y()*cp.y()), cp.z() ),
                    sqrt(cp.x()*cp.x() + cp.y()*cp.y() + cp.z()*cp.z()) );
 }
 
 
-// calc new lon/lat given starting lon/lat, and offset radial, and
-// distance.  NOTE: starting point is specifed in radians, distance is
-// specified in meters (and converted internally to radians)
-// ... assumes a spherical world
+/**
+ * Calculate new lon/lat given starting lon/lat, and offset radial, and
+ * distance.  NOTE: starting point is specifed in radians, distance is
+ * specified in meters (and converted internally to radians)
+ * ... assumes a spherical world.
+ * @param orig specified in polar coordinates
+ * @param course offset radial
+ * @param dist offset distance
+ * @return destination point in polar coordinates
+ */
 inline Point3D calc_gc_lon_lat( const Point3D& orig, double course,
                                double dist ) {
     Point3D result;
@@ -83,24 +104,31 @@ inline Point3D calc_gc_lon_lat( const Point3D& orig, double course,
     // printf("calc_lon_lat()  offset.theta = %.2f offset.dist = %.2f\n",
     //        offset.theta, offset.dist);
 
-    dist *= METER_TO_NM * NM_TO_RAD;
+    dist *= SG_METER_TO_NM * SG_NM_TO_RAD;
     
     result.sety( asin( sin(orig.y()) * cos(dist) + 
                       cos(orig.y()) * sin(dist) * cos(course) ) );
 
-    if ( cos(result.y()) < FG_EPSILON ) {
+    if ( cos(result.y()) < SG_EPSILON ) {
         result.setx( orig.x() );      // endpoint a pole
     } else {
         result.setx( 
            fmod(orig.x() - asin( sin(course) * sin(dist) / 
-                                 cos(result.y()) ) + FG_PI, FG_2PI) - FG_PI );
+                                 cos(result.y()) )
+                 + SGD_PI, SGD_2PI) - SGD_PI );
     }
 
     return result;
 }
 
 
-// calc course/dist
+/**
+ * Calculate course/dist given two spherical points.
+ * @param start starting point
+ * @param dest ending point
+ * @param course resulting course
+ * @param dist resulting distance
+ */
 inline void calc_gc_course_dist( const Point3D& start, const Point3D& dest, 
                                 double *course, double *dist ) {
     // d = 2*asin(sqrt((sin((lat1-lat2)/2))^2 + 
@@ -132,10 +160,10 @@ inline void calc_gc_course_dist( const Point3D& start, const Point3D& dest,
 
     double tc1;
 
-    if ( cos(start.y()) < FG_EPSILON ) {
+    if ( cos(start.y()) < SG_EPSILON ) {
        // EPS a small number ~ machine precision
        if ( start.y() > 0 ) {
-           tc1 = FG_PI;        // starting from N pole
+           tc1 = SGD_PI;        // starting from N pole
        } else {
            tc1 = 0;            // starting from S pole
        }
@@ -149,11 +177,11 @@ inline void calc_gc_course_dist( const Point3D& start, const Point3D& dest,
     if ( sin( dest.x() - start.x() ) < 0 ) {
         tc1 = tmp5;
     } else {
-        tc1 = 2 * FG_PI - tmp5;
+        tc1 = 2 * SGD_PI - tmp5;
     }
 
     *course = tc1;
-    *dist = d * RAD_TO_NM * NM_TO_METER;
+    *dist = d * SG_RAD_TO_NM * SG_NM_TO_METER;
 }
 
-#endif // _POLAR_HXX
+#endif // _POLAR3D_HXX