-// 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
#include <simgear/route/waypoint.hxx>
+/**
+ * A class to manage a list of waypoints (i.e. a route).
+ */
class SGRoute {
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 );
}
}
- // 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];
}
}
- // 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];
}
}
- // 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];
}
}
- // 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;
};
-// 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
SG_USING_STD(string);
+/**
+ * A class to manage waypoints.
+ */
+
class SGWayPoint {
public:
+ /**
+ * Waypoint mode.
+ * <li> 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.
+ * <li> 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.
+ * <li> CARTESIAN requests all math be done assuming the coordinates specify
+ * position in a Z = up world.
+ */
enum modetype {
WGS84 = 0,
SPHERICAL = 1,
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; }
- inline string get_id() const { return id; }
+ /**
+ * 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; }
+
};
projects / simgear.git / commitdiff