kstars/kstars/dms.h

   1 /***************************************************************************
   2                           dms.h  -  K Desktop Planetarium
   3                              -------------------
   4     begin                : Sun Feb 11 2001
   5     copyright            : (C) 2001 by Jason Harris
   6     email                : jharris@30doradus.org
   7  ***************************************************************************/
   8
   9 /***************************************************************************
  10  *                                                                         *
  11  *   This program is free software; you can redistribute it and/or modify  *
  12  *   it under the terms of the GNU General Public License as published by  *
  13  *   the Free Software Foundation; either version 2 of the License, or     *
  14  *   (at your option) any later version.                                   *
  15  *                                                                         *
  16  ***************************************************************************/
  17
  18 #ifndef DMS_H
  19 #define DMS_H
  20
  21 #include <math.h>
  22 #include <qstring.h>
  23 #include <kdebug.h>
  24
  25 //TODO: Remove these when KStarsDateTime is added!
  26 #define J2000 2451545.0 //Julian Date for noon on Jan 1, 2000 (epoch J2000)
  27                        //defined here because this file is included in every other class.
  28 #define B1950 2433282.4235  // Julian date for Jan 0.9235, 1950
  29
  30 /**@class dms
  31         *@short An angle, stored as degrees, but expressible in many ways.
  32         *@author Jason Harris
  33         *@version 1.0
  34
  35         *dms encapsulates an angle.  The angle is stored as a double,
  36         *equal to the value of the angle in degrees.  Methods are available
  37         *for setting/getting the angle as a floating-point measured in
  38         *Degrees or Hours, or as integer triplets (degrees, arcminutes,
  39         *arcseconds or hours, minutes, seconds).  There is also a method
  40         *to set the angle according to a radian value, and to return the
  41         *angle expressed in radians.  Finally, a SinCos() method computes
  42         *the sin and cosine of the angle.  Once computed, the sin and cos
  43         *values are stored, so that subsequent SinCos() calls will be faster.
  44   */
  45
  46 class dms {
  47 public:
  48 /**@short Default Constructor.
  49         *
  50         *Set the floating-point value of the angle according to the four integer arguments.
  51         *@param d degree portion of angle (int).  Defaults to zero.
  52         *@param m arcminute portion of angle (int).  Defaults to zero.
  53         *@param s arcsecond portion of angle (int).  Defaults to zero.
  54         *@param ms arcsecond portion of angle (int).  Defaults to zero.
  55         */
  56         dms( const int &d=0, const int &m=0, const int &s=0, const int &ms=0 ) { setD( d, m, s, ms ); }
  57
  58 /**@short Construct an angle from a double value.
  59         *
  60         *Creates an angle whose value in Degrees is equal to the argument.
  61         *@param x angle expressed as a floating-point number (in degrees)
  62         */
  63   dms( const double &x ) { setD( x ); }
  64
  65 /**@short Construct an angle from a string representation.
  66         *
  67         *Attempt to create the angle according to the string argument.  If the string
  68         *cannot be parsed as an angle value, the angle is set to zero.
  69         *
  70         *@warning There is not an unambiguous notification that it failed to parse the string,
  71         *since the string could have been a valid representation of zero degrees.
  72         *If this is a concern, use the setFromString() function directly instead.
  73         *
  74         *@param s the string to parse as a dms value.
  75         *@param isDeg if true, value is in degrees; if false, value is in hours.
  76         *@sa setFromString()
  77         */
  78         dms( const QString &s, bool isDeg=true ) { setFromString( s, isDeg ); }
  79
  80 /**Destructor (empty).
  81         */
  82         ~dms() {}
  83
  84 /**@return integer degrees portion of the angle
  85         */
  86   const int degree() const { return int( D ) ; }
  87
  88 /**@return integer arcminutes portion of the angle.
  89         *@note an arcminute is 1/60 degree.
  90         */
  91   const int arcmin() const;
  92
  93 /**@return integer arcseconds portion of the angle
  94         *@note an arcsecond is 1/60 arcmin, or 1/3600 degree.
  95         */
  96   const int arcsec() const;
  97
  98 /**@return integer milliarcseconds portion of the angle
  99         *@note a  milliarcsecond is 1/1000 arcsecond.
 100         */
 101         const int marcsec() const;
 102
 103 /**@return angle in degrees expressed as a double.
 104         */
 105         const double& Degrees() const { return D; }
 106
 107 /**@return integer hours portion of the angle
 108         *@note an angle can be measured in degrees/arcminutes/arcseconds
 109         *or hours/minutes/seconds.  An hour is equal to 15 degrees.
 110         */
 111         const int hour() const { return int( reduce().Degrees()/15.0 ); }
 112
 113 /**@return integer minutes portion of the angle
 114         *@note a minute is 1/60 hour (not the same as an arcminute)
 115         */
 116         const int minute() const;
 117
 118 /**@return integer seconds portion of the angle
 119         *@note a second is 1/3600 hour (not the same as an arcsecond)
 120         */
 121         const int second() const;
 122
 123 /**@return integer milliseconds portion of the angle
 124         *@note a millisecond is 1/1000 second (not the same as a milliarcsecond)
 125         */
 126         const int msecond() const;
 127
 128 /**@return angle in hours expressed as a double.
 129         *@note an angle can be measured in degrees/arcminutes/arcseconds
 130         *or hours/minutes/seconds.  An hour is equal to 15 degrees.
 131         */
 132         const double Hours() const { return reduce().Degrees()/15.0; }
 133
 134 /**Sets integer degrees portion of angle, leaving the arcminute and
 135         *arcsecond values intact.
 136         *@param d new integer degrees value
 137         */
 138   void setDeg( const int &d ) { setD( d, arcmin(), arcsec() ); }
 139
 140 /**Sets integer arcminutes portion of angle, leaving the degrees
 141         *and arcsecond values intact.
 142         *@param m new integer arcminutes value
 143         */
 144   void setArcMin( const int &m ) { setD( degree(), m, arcsec() ); }
 145
 146 /**Sets integer arcseconds portion of angle, leaving the degrees
 147         *and arcminute values intact.
 148         *@param s new integer arcseconds value
 149         */
 150   void setArcSec( const int &s ) { setD( degree(), arcmin(), s ); }
 151
 152 /**Sets floating-point value of angle, in degrees.
 153         *@param x new angle (double)
 154         */
 155   void setD( const double &x );
 156
 157 /**@short Sets floating-point value of angle, in degrees.
 158         *
 159         *This is an overloaded member function; it behaves essentially
 160         *like the above function.  The floating-point value of the angle
 161         *(D) is determined from the following formulae:
 162         *
 163         *\f$ fabs(D) = fabs(d) + \frac{(m + (s/60))}{60} \f$
 164         *\f$ sgn(D) = sgn(d) \f$
 165         *
 166         *@param d integer degrees portion of angle
 167         *@param m integer arcminutes portion of angle
 168         *@param s integer arcseconds portion of angle
 169         *@param ms integer arcseconds portion of angle
 170         */
 171         void setD( const int &d, const int &m, const int &s, const int &ms=0 );
 172
 173 /**Sets integer hours portion of angle, leaving the minutes and
 174         *seconds values intact.
 175         *@param h new integer hours value
 176         *@sa setH() setDeg()
 177         */
 178         void setHour( const int &h ) { setH( h, minute(), second() ); }
 179
 180 /**Sets integer minutes portion of angle, leaving the hours and
 181         *seconds values intact.
 182         *@param m new integer minutes value
 183         *@sa setArcMin()
 184         */
 185         void setHMin( const int &m ) { setH( hour(), m, second() ); }
 186
 187 /**Sets integer seconds portion of angle, leaving the hours and
 188         *minutes values intact.
 189         *@param s new integer seconds value
 190         *@sa setArcSec()
 191         */
 192         void setHSec( const int &s ) { setH( hour(), minute(), s ); }
 193
 194 /**@short Sets floating-point value of angle, in hours.
 195         *
 196         *Converts argument from hours to degrees, then
 197         *sets floating-point value of angle, in degrees.
 198         *@param x new angle, in hours (double)
 199         *@sa setD()
 200         */
 201         void setH( const double &x );
 202
 203 /**@short Sets floating-point value of angle, in hours.
 204         *
 205         *Converts argument values from hours to degrees, then
 206         *sets floating-point value of angle, in degrees.
 207         *This is an overloaded member function, provided for convenience.  It
 208         *behaves essentially like the above function.
 209         *@param h integer hours portion of angle
 210         *@param m integer minutes portion of angle
 211         *@param s integer seconds portion of angle
 212         *@param ms integer milliseconds portion of angle
 213         *@sa setD()
 214         */
 215         void setH( const int &h, const int &m, const int &s, const int &ms=0 );
 216
 217 /**@short Copy value of another dms angle
 218         *@param d set angle according to this dms object
 219         */
 220         void set( const dms &d ) { setD( d.Degrees() ); }
 221
 222 /**Copy value of another dms angle.  Differs from above function only
 223         *in argument type.  Identical to setD(double d).
 224         *@param d set angle according to this double value
 225         *@sa setD()
 226         */
 227         void set( const double &d ) { setD( d ); }
 228
 229 /**@short Attempt to parse the string argument as a dms value, and set the dms object
 230         *accordingly.
 231         *@param s the string to be parsed as a dms value.  The string can be an int or
 232         *floating-point value, or a triplet of values (d/h, m, s) separated by spaces or colons.
 233         *@param isDeg if true, the value is in degrees.  Otherwise, it is in hours.
 234         *@return true if sting was parsed successfully.  Otherwise, set the dms value
 235         *to 0.0 and return false.
 236         */
 237         bool setFromString( const QString &s, bool isDeg=true );
 238
 239 /**
 240         *Addition operator.  Add two dms objects.
 241         *@param d add to current angle
 242         *@return sum of two angles, in a dms object
 243         */
 244 //  dms operator+ ( dms d );
 245 /**
 246         *Subtraction operator.  Subtract two dms objects.
 247         *@param d subtract from current angle
 248         *@return difference of two angles, in a dms object
 249         */
 250 //  dms operator- ( dms d );
 251 /**
 252         *Assignment operator.  Assign value of argument to current angle.
 253         *I wanted to pass the argument by reference, but I couldn't figure
 254         *out a good way to do it without generating an error or warning message.
 255         *@param a dms object to get angle value from
 256         *@return dms object, copy of argument.
 257         */
 258 //  dms operator= ( const dms a ) { return a; }
 259 /**
 260         *Assignment operator.  Assign value of argument to current angle.
 261         *@param d floating-point number to get angle value from
 262         *@return dms object, same value as argument.
 263         */
 264 //  dms operator= ( const double &d ) { return (dms( d )); }
 265
 266 /**@short Compute Sine and Cosine of the angle simultaneously.
 267         *On machines using glibc >= 2.1, calling SinCos() is somewhat faster
 268         *than calling sin() and cos() separately.
 269         *The values are returned through the arguments (passed by reference).
 270         *The Sin and Cos values are stored internally; on subsequent calls
 271         *to SinCos(), the stored values are returned directly (unless the
 272         *angle's value has changed).
 273         *@param s Sine of the angle
 274         *@param c Cosine of the angle
 275         *@sa sin() cos()
 276         */
 277         void SinCos( double &s, double &c ) const;
 278
 279 /**@short Compute the Angle's Sine.
 280         *
 281         *If the Sine/Cosine values have already been computed, then this
 282         *function simply returns the stored value.  Otherwise, it will compute
 283         *and store the values first.
 284         *@return the Sine of the angle.
 285         *@sa cos()
 286         */
 287         const double& sin( void ) const;
 288
 289 /**@short Compute the Angle's Cosine.
 290         *
 291         *If the Sine/Cosine values have already been computed, then this
 292         *function simply returns the stored value.  Otherwise, it will compute
 293         *and store the values first.
 294         *@return the Cosine of the angle.
 295         *@sa sin()
 296         */
 297         const double& cos( void ) const;
 298
 299 /**@short Express the angle in radians.
 300         *The computed Radians value is stored internally.  On subsequent calls,
 301         *the stored value is returned directly (unless the angle's value has
 302         *changed).
 303         *@return the angle in radians (double)
 304         */
 305         const double& radians( void ) const;
 306
 307 /**@short Set angle according to the argument, in radians.
 308         *
 309         *This function converts the argument to degrees, then sets the angle
 310         *with setD().
 311         *@param a angle in radians
 312         */
 313         void setRadians( const double &a );
 314
 315 /**return the equivalent angle between 0 and 360 degrees.
 316         *@warning does not change the value of the parent angle itself.
 317         */
 318         const dms reduce( void ) const;
 319
 320 /**@return a nicely-formatted string representation of the angle
 321         *in degrees, arcminutes, and arcseconds.
 322         */
 323         const QString toDMSString(const bool forceSign = false) const;
 324
 325 /**@return a nicely-formatted string representation of the angle
 326         *in hours, minutes, and seconds.
 327         */
 328         const QString toHMSString() const;
 329
 330 /**PI is a const static member; it's public so that it can be used anywhere,
 331         *as long as dms.h is included.
 332         */
 333         static const double PI;
 334
 335 /**DegToRad is a const static member equal to the number of radians in
 336         *one degree (dms::PI/180.0).
 337         */
 338         static const double DegToRad;
 339
 340 /**@short Static function to create a DMS object from a QString.
 341         *
 342         *There are several ways to specify the angle:
 343         *@li Integer numbers  ( 5 or -33 )
 344         *@li Floating-point numbers  ( 5.0 or -33.0 )
 345         *@li colon-delimited integers ( 5:0:0 or -33:0:0 )
 346         *@li colon-delimited with float seconds ( 5:0:0.0 or -33:0:0.0 )
 347         *@li colon-delimited with float minutes ( 5:0.0 or -33:0.0 )
 348         *@li space-delimited ( 5 0 0; -33 0 0 ) or ( 5 0.0 or -33 0.0 )
 349         *@li space-delimited, with unit labels ( 5h 0m 0s or -33d 0m 0s )
 350         *@param s the string to be parsed as an angle value
 351         *@param deg if TRUE, s is expressed in degrees; if FALSE, s is expressed in hours
 352         *@return a dms object whose value is parsed from the string argument
 353         */
 354         static dms fromString(QString & s, bool deg);
 355
 356 private:
 357         double D;
 358
 359         mutable double Radians;
 360         mutable double Sin, Cos;
 361         mutable bool scDirty, rDirty;
 362 };
 363
 364 #endif