diff --git a/simgear/route/route.hxx b/simgear/route/route.hxx index 6d2da1f7..326ca883 100644 --- a/simgear/route/route.hxx +++ b/simgear/route/route.hxx @@ -1,5 +1,8 @@ -// route.hxx -- Class to manage a list of waypoints (route) -// +/** + * \file route.hxx + * Provides a class to manage a list of waypoints (i.e. a route). + */ + // Written by Curtis Olson, started October 2000. // // Copyright (C) 2000 Curtis L. Olson - curt@hfrl.umn.edu @@ -44,6 +47,9 @@ SG_USING_STD(vector); #include +/** + * A class to manage a list of waypoints (i.e. a route). + */ class SGRoute { @@ -55,16 +61,22 @@ private: public: + /** Constructor */ SGRoute(); + + /** Destructor */ ~SGRoute(); - // clear the entire route + /** Clear the entire route */ inline void clear() { route.clear(); current_wp = 0; } - // add a waypoint + /** + * Add a waypoint. + * @param wp a waypoint + */ inline void add_waypoint( const SGWayPoint &wp ) { route.push_back( wp ); @@ -77,10 +89,16 @@ public: } } - // get the number of waypoints + /** + * Get the number of waypoints (i.e. route length ) + * @return route length + */ inline int size() const { return route.size(); } - // get the front waypoint + /** + * Get the front waypoint. + * @return the first waypoint. + */ inline SGWayPoint get_first() const { if ( route.size() ) { return route[0]; @@ -89,7 +107,10 @@ public: } } - // get the current waypoint + /** + * Get the current waypoint + * @return the current waypoint + */ inline SGWayPoint get_current() const { if ( current_wp < (int)route.size() ) { return route[current_wp]; @@ -98,21 +119,28 @@ public: } } - // set the current waypoint + /** + * Set the current waypoint + * @param number of waypoint to make current. + */ inline void set_current( int n ) { if ( n >= 0 && n < (int)route.size() ) { current_wp = n; } } - // increment the current waypoint + /** Increment the current waypoint pointer. */ inline void increment_current() { if ( current_wp < (int)route.size() - 1 ) { ++current_wp; } } - // get the nth waypoint + /** + * Get the nth waypoint + * @param n waypoint number + * @return the nth waypoint + */ inline SGWayPoint get_waypoint( const int n ) const { if ( n < (int)route.size() ) { return route[n]; @@ -121,17 +149,19 @@ public: } } - // delete the front waypoint + /** Delete the front waypoint */ inline void delete_first() { if ( route.size() ) { route.erase( route.begin() ); } } - // Calculate perpendicular distance from the current route segment - // This routine assumes all points are laying on a flat plane and - // ignores the altitude (or Z) dimension. For best results, use - // with CARTESIAN way points. + /** + * Calculate perpendicular distance from the current route segment + * This routine assumes all points are laying on a flat plane and + * ignores the altitude (or Z) dimension. For most accurate + * results, use with CARTESIAN way points. + */ double distance_off_route( double x, double y ) const; }; diff --git a/simgear/route/waypoint.hxx b/simgear/route/waypoint.hxx index f1ec7822..a02b6e31 100644 --- a/simgear/route/waypoint.hxx +++ b/simgear/route/waypoint.hxx @@ -1,5 +1,8 @@ -// waypoint.hxx -- Class to hold data and return info relating to a waypoint -// +/** + * \file waypoint.hxx + * Provides a class to manage waypoints + */ + // Written by Curtis Olson, started September 2000. // // Copyright (C) 2000 Curtis L. Olson - curt@hfrl.umn.edu @@ -41,10 +44,26 @@ SG_USING_STD(string); +/** + * A class to manage waypoints. + */ + class SGWayPoint { public: + /** + * Waypoint mode. + *
  • WGS84 requests all bearing and distance math be done assuming a + * WGS84 ellipsoid world. This is the most expensive computationally, + * but also the most accurate. + *
  • SPHERICAL requests all bearing and distance math be done assuming + * the world is a perfect sphere. This is less compuntationally + * expensive than using wgs84 math and still a fairly good + * approximation of the real world, especially over shorter distances. + *
  • CARTESIAN requests all math be done assuming the coordinates specify + * position in a Z = up world. + */ enum modetype { WGS84 = 0, SPHERICAL = 1, @@ -64,32 +83,82 @@ private: public: + /** Default constructor */ SGWayPoint(); + + /** + * Construct a waypoint + * @param lon destination longitude + * @param lat destination latitude + * @param alt target altitude + * @param mode type of coordinates/math to use + * @param s waypoint identifier + */ SGWayPoint( const double lon, const double lat, const double alt, const modetype m = WGS84, const string s = "" ); + + /** Destructor */ ~SGWayPoint(); - // Calculate course and distances. For WGS84 and SPHERICAL - // coordinates lat, lon, and course are in degrees, alt and - // distance are in meters. For CARTESIAN coordinates x = lon, y = - // lat. Course is in degrees and distance is in what ever units x - // and y are in. + /** + * Calculate course and distances. For WGS84 and SPHERICAL + * coordinates lat, lon, and course are in degrees, alt and + * distance are in meters. For CARTESIAN coordinates x = lon, y = + * lat. Course is in degrees and distance is in what ever units x + * and y are in. + * @param cur_lon (in) current longitude + * @param cur_lat (in) current latitude + * @param cur_alt (in) current altitude + * @param course (out) heading from current location to this waypoint + * @param distance (out) distance from current location to this waypoint + */ void CourseAndDistance( const double cur_lon, const double cur_lat, const double cur_alt, double *course, double *distance ) const; - // Calculate course and distances between two waypoints + /** + * Calculate course and distances between a specified starting waypoint + * and this waypoint. + * @param wp (in) original waypoint + * @param course (out) heading from current location to this waypoint + * @param distance (out) distance from current location to this waypoint + */ void CourseAndDistance( const SGWayPoint &wp, double *course, double *distance ) const; + /** @return waypoint mode */ inline modetype get_mode() const { return mode; } + + /** @return waypoint longitude */ inline double get_target_lon() const { return target_lon; } + + /** @return waypoint latitude */ inline double get_target_lat() const { return target_lat; } + + /** @return waypoint altitude */ inline double get_target_alt() const { return target_alt; } + + /** + * This value is not calculated by this class. It is simply a + * placeholder for the user to stash a distance value. This is useful + * when you stack waypoints together into a route. You can calculate the + * distance from the previous waypoint once and save it here. Adding up + * all the distances here plus the distance to the first waypoint gives you + * the total route length. Note, you must update this value yourself, this + * is for your convenience only. + * @return waypoint distance holder (what ever the user has stashed here) + */ inline double get_distance() const { return distance; } + + /** + * Set the waypoint distance value to a value of our choice. + * @param d distance + */ + inline void set_distance( double d ) { distance = d; } + + /** @return waypoint id */ inline string get_id() const { return id; } - inline void set_distance( double d ) { distance = d; } };