* $Id$
**************************************************************************/
+/** \file newbucket.hxx
+ * A class and associated utiltity functions to manage world scenery tiling.
+ */
#ifndef _NEWBUCKET_HXX
#define _NEWBUCKET_HXX
#include <simgear/compiler.h>
#include <simgear/constants.h>
-#ifdef FG_HAVE_STD_INCLUDES
+#ifdef SG_HAVE_STD_INCLUDES
# include <cmath>
# include <cstdio> // sprintf()
-# include <iostream>
#else
# include <math.h>
# include <stdio.h> // sprintf()
-# include <iostream.h>
#endif
+#include STL_IOSTREAM
+
// I don't understand ... <math.h> or <cmath> should be included
-// already depending on how you defined FG_HAVE_STD_INCLUDES, but I
+// already depending on how you defined SG_HAVE_STD_INCLUDES, but I
// can go ahead and add this -- CLO
#ifdef __MWERKS__
-# include <math.h> // needed fabs()
+SG_USING_STD(sprintf);
+SG_USING_STD(fabs);
#endif
#include STL_STRING
-FG_USING_STD(string);
+SG_USING_STD(string);
-#if ! defined( FG_HAVE_NATIVE_SGI_COMPILERS )
-FG_USING_STD(ostream);
+#if ! defined( SG_HAVE_NATIVE_SGI_COMPILERS )
+SG_USING_STD(ostream);
#endif
+/**
+ * standard size of a bucket in degrees (1/8 of a degree)
+ */
+#define SG_BUCKET_SPAN 0.125
-#define FG_BUCKET_SPAN 0.125 // 1/8 of a degree
-#define FG_HALF_BUCKET_SPAN 0.0625 // 1/2 of 1/8 of a degree = 1/16 = 0.0625
-
-class FGBucket;
-ostream& operator<< ( ostream&, const FGBucket& );
-bool operator== ( const FGBucket&, const FGBucket& );
-
-class FGBucket {
-
-private:
- double cx, cy; // centerpoint (lon, lat) in degrees of bucket
- int lon; // longitude index (-180 to 179)
- int lat; // latitude index (-90 to 89)
- int x; // x subdivision (0 to 7)
- int y; // y subdivision (0 to 7)
-
-public:
-
- // default constructor
- FGBucket();
-
- // create a bucket which would contain the specified lon/lat
- FGBucket(const double lon, const double lat);
-
- // create a bucket based on "long int" index
- FGBucket(const long int bindex);
-
- // create an impossible bucket if false
- FGBucket(const bool is_good);
-
- ~FGBucket();
-
- // Set the bucket params for the specified lat and lon
- void set_bucket( double dlon, double dlat );
- void set_bucket( double *lonlat ) {
- set_bucket( lonlat[0], lonlat[1] );
- }
-
- void make_bad ( void );
-
- // Generate the unique scenery tile index for this bucket
- long int gen_index();
- string gen_index_str() const;
-
- // Build the path name for this bucket
- string gen_base_path() const;
-
- // return the center lon of a tile
- double get_center_lon() const;
-
- // return width of the tile
- double get_width() const;
-
- // return the center lat of a tile
- double get_center_lat() const;
-
- // return height of the tile
- double get_height() const;
-
- // Informational methods
- inline int get_lon() const { return lon; }
- inline int get_lat() const { return lat; }
- inline int get_x() const { return x; }
- inline int get_y() const { return y; }
-
- // friends
- friend ostream& operator<< ( ostream&, const FGBucket& );
- friend bool operator== ( const FGBucket&, const FGBucket& );
-};
+/**
+ * half of a standard SG_BUCKET_SPAN
+ */
+#define SG_HALF_BUCKET_SPAN ( 0.5 * SG_BUCKET_SPAN )
// return the horizontal tile span factor based on latitude
-inline double bucket_span( double l ) {
+static double sg_bucket_span( double l ) {
if ( l >= 89.0 ) {
return 360.0;
} else if ( l >= 88.0 ) {
}
-// Set the bucket params for the specified lat and lon
-inline void FGBucket::set_bucket( double dlon, double dlat ) {
- //
- // latitude first
- //
- double span = bucket_span( dlat );
- double diff = dlon - (double)(int)dlon;
-
- // cout << "diff = " << diff << " span = " << span << endl;
-
- if ( (dlon >= 0) || (fabs(diff) < FG_EPSILON) ) {
- lon = (int)dlon;
- } else {
- lon = (int)dlon - 1;
- }
-
- // find subdivision or super lon if needed
- if ( span < FG_EPSILON ) {
- // polar cap
- lon = 0;
- x = 0;
- } else if ( span <= 1.0 ) {
- x = (int)((dlon - lon) / span);
- } else {
- if ( (dlon >= 0) || (fabs(diff) < FG_EPSILON) ) {
- lon = (int)( (int)(lon / span) * span);
- } else {
- // cout << " lon = " << lon
- // << " tmp = " << (int)((lon-1) / span) << endl;
- lon = (int)( (int)((lon + 1) / span) * span - span);
- if ( lon < -180 ) {
- lon = -180;
- }
- }
- x = 0;
- }
-
- //
- // then latitude
- //
- diff = dlat - (double)(int)dlat;
-
- if ( (dlat >= 0) || (fabs(diff) < FG_EPSILON) ) {
- lat = (int)dlat;
- } else {
- lat = (int)dlat - 1;
- }
- y = (int)((dlat - lat) * 8);
-}
-
+/**
+ * A class to manage world scenery tiling.
+ * This class encapsulates the world tiling scheme. It provides ways
+ * to calculate a unique tile index from a lat/lon, and it can provide
+ * information such as the dimensions of a given tile.
+ */
-// default constructor
-inline FGBucket::FGBucket() {}
+class SGBucket {
+private:
+ double cx, cy; // centerpoint (lon, lat) in degrees of bucket
+ int lon; // longitude index (-180 to 179)
+ int lat; // latitude index (-90 to 89)
+ int x; // x subdivision (0 to 7)
+ int y; // y subdivision (0 to 7)
-// constructor for specified location
-inline FGBucket::FGBucket(const double dlon, const double dlat) {
- set_bucket(dlon, dlat);
-}
+public:
+ /**
+ * Default constructor.
+ */
+ SGBucket();
+
+ /**
+ * Construct a bucket given a specific location.
+ * @param dlon longitude specified in degrees
+ * @param dlat latitude specified in degrees
+ */
+ SGBucket(const double dlon, const double dlat);
+
+ /** Construct a bucket.
+ * @param is_good if false, create an invalid bucket. This is
+ * useful * if you are comparing cur_bucket to last_bucket and
+ * you want to * make sure last_bucket starts out as something
+ * impossible.
+ */
+ SGBucket(const bool is_good);
+
+ /** Construct a bucket given a unique bucket index number.
+ * @param bindex unique bucket index
+ */
+ SGBucket(const long int bindex);
+
+ /**
+ * Default destructor.
+ */
+ ~SGBucket();
+
+ /**
+ * Reset a bucket to represent a new lat and lon
+ * @param dlon longitude specified in degrees
+ * @param dlat latitude specified in degrees
+ */
+ void set_bucket( double dlon, double dlat );
-// create an impossible bucket if false
-inline FGBucket::FGBucket(const bool is_good) {
- set_bucket(0.0, 0.0);
- if ( !is_good ) {
+ /**
+ * Reset a bucket to represent a new lat and lon
+ * @param lonlat an array of double[2] holding lon and lat
+ * (specified) in degrees
+ */
+ void set_bucket( double *lonlat );
+
+ /**
+ * Create an impossible bucket.
+ * This is useful if you are comparing cur_bucket to last_bucket
+ * and you want to make sure last_bucket starts out as something
+ * impossible.
+ */
+ inline void make_bad() {
+ set_bucket(0.0, 0.0);
lon = -1000;
}
-}
+ /**
+ * Generate the unique scenery tile index for this bucket
+ *
+ * The index is constructed as follows:
+ *
+ * 9 bits - to represent 360 degrees of longitude (-180 to 179)
+ * 8 bits - to represent 180 degrees of latitude (-90 to 89)
+ *
+ * Each 1 degree by 1 degree tile is further broken down into an 8x8
+ * grid. So we also need:
+ *
+ * 3 bits - to represent x (0 to 7)
+ * 3 bits - to represent y (0 to 7)
+ * @return tile index
+ */
+ inline long int gen_index() const {
+ return ((lon + 180) << 14) + ((lat + 90) << 6) + (y << 3) + x;
+ }
-// Parse a unique scenery tile index and find the lon, lat, x, and y
-inline FGBucket::FGBucket(const long int bindex) {
- long int index = bindex;
-
- lon = index >> 14;
- index -= lon << 14;
- lon -= 180;
-
- lat = index >> 6;
- index -= lat << 6;
- lat -= 90;
-
- y = index >> 3;
- index -= y << 3;
-
- x = index;
-}
-
-
-// default destructor
-inline FGBucket::~FGBucket() {}
-
-
-// Generate the unique scenery tile index for this bucket
-//
-// The index is constructed as follows:
-//
-// 9 bits - to represent 360 degrees of longitude (-180 to 179)
-// 8 bits - to represent 180 degrees of latitude (-90 to 89)
-//
-// Each 1 degree by 1 degree tile is further broken down into an 8x8
-// grid. So we also need:
-//
-// 3 bits - to represent x (0 to 7)
-// 3 bits - to represent y (0 to 7)
-
-inline long int FGBucket::gen_index() {
- return ((lon + 180) << 14) + ((lat + 90) << 6) + (y << 3) + x;
-}
-
-inline string FGBucket::gen_index_str() const {
- char tmp[20];
- sprintf(tmp, "%ld",
- (((long)lon + 180) << 14) + ((lat + 90) << 6) + (y << 3) + x);
- return (string)tmp;
-}
-
-
-// return the center lon of a tile
-inline double FGBucket::get_center_lon() const {
- double span = bucket_span( lat + y / 8.0 + FG_HALF_BUCKET_SPAN );
-
- if ( span >= 1.0 ) {
- return lon + span / 2.0;
- } else {
- return lon + x * span + span / 2.0;
+ /**
+ * Generate the unique scenery tile index for this bucket in ascii
+ * string form.
+ * @return tile index in string form
+ */
+ inline string gen_index_str() const {
+ char tmp[20];
+ sprintf(tmp, "%ld",
+ (((long)lon + 180) << 14) + ((lat + 90) << 6) + (y << 3) + x);
+ return (string)tmp;
}
-}
+ /**
+ * Build the base path name for this bucket.
+ * @return base path in string form
+ */
+ string gen_base_path() const;
-// return the center lat of a tile
-inline double FGBucket::get_center_lat() const {
- return lat + y / 8.0 + FG_HALF_BUCKET_SPAN;
-}
+ /**
+ * @return the center lon of a tile.
+ */
+ inline double get_center_lon() const {
+ double span = sg_bucket_span( lat + y / 8.0 + SG_HALF_BUCKET_SPAN );
+ if ( span >= 1.0 ) {
+ return lon + span / 2.0;
+ } else {
+ return lon + x * span + span / 2.0;
+ }
+ }
-// return width of the tile
-inline double FGBucket::get_width() const {
- return bucket_span( get_center_lat() );
-}
+ /**
+ * @return the center lat of a tile.
+ */
+ inline double get_center_lat() const {
+ return lat + y / 8.0 + SG_HALF_BUCKET_SPAN;
+ }
+ /**
+ * @return the width of the tile in degrees.
+ */
+ double get_width() const;
-// return height of the tile
-inline double FGBucket::get_height() const {
- return FG_BUCKET_SPAN;
-}
+ /**
+ * @return the height of the tile in degrees.
+ */
+ double get_height() const;
+ /**
+ * @return the width of the tile in meters.
+ */
+ double get_width_m() const;
+
+ /**
+ * @return the height of the tile in meters.
+ */
+ double get_height_m() const;
+
+ // Informational methods.
+
+ /**
+ * @return the lon of the lower left corner of this tile.
+ */
+ inline int get_lon() const { return lon; }
-// create an impossible bucket
-inline void FGBucket::make_bad( void ) {
- set_bucket(0.0, 0.0);
- lon = -1000;
-}
+ /**
+ * @return the lat of the lower left corner of this tile.
+ */
+ inline int get_lat() const { return lat; }
+ /**
+ * @return the x coord within the 1x1 degree chunk this tile.
+ */
+ inline int get_x() const { return x; }
-// offset a bucket struct by the specified tile units in the X & Y
-// direction
-FGBucket fgBucketOffset( double dlon, double dlat, int x, int y );
+ /**
+ * @return the y coord within the 1x1 degree chunk this tile.
+ */
+ inline int get_y() const { return y; }
+ // friends
-// calculate the offset between two buckets
-void fgBucketDiff( const FGBucket& b1, const FGBucket& b2, int *dx, int *dy );
+ friend ostream& operator<< ( ostream&, const SGBucket& );
+ friend bool operator== ( const SGBucket&, const SGBucket& );
+};
+/**
+ * \relates SGBucket
+ * Return the bucket which is offset from the specified dlon, dlat by
+ * the specified tile units in the X & Y direction.
+ * @param dlon starting lon in degrees
+ * @param dlat starting lat in degrees
+ * @param x number of bucket units to offset in x (lon) direction
+ * @param y number of bucket units to offset in y (lat) direction
+ * @return offset bucket
+ */
+SGBucket sgBucketOffset( double dlon, double dlat, int x, int y );
+
+
+/**
+ * \relates SGBucket
+ * Calculate the offset between two buckets (in quantity of buckets).
+ * @param b1 bucket 1
+ * @param b2 bucket 2
+ * @param dx offset distance (lon) in tile units
+ * @param dy offset distance (lat) in tile units
+ */
+void sgBucketDiff( const SGBucket& b1, const SGBucket& b2, int *dx, int *dy );
+
+
+/**
+ * Write the bucket lon, lat, x, and y to the output stream.
+ * @param out output stream
+ * @param b bucket
+ */
inline ostream&
-operator<< ( ostream& out, const FGBucket& b )
+operator<< ( ostream& out, const SGBucket& b )
{
return out << b.lon << ":" << b.x << ", " << b.lat << ":" << b.y;
}
+/**
+ * Compare two bucket structures for equality.
+ * @param b1 bucket 1
+ * @param b2 bucket 2
+ * @return comparison result
+ */
inline bool
-operator== ( const FGBucket& b1, const FGBucket& b2 )
+operator== ( const SGBucket& b1, const SGBucket& b2 )
{
return ( b1.lon == b2.lon &&
b1.lat == b2.lat &&