kstars/kstars/geolocation.h

   1 /***************************************************************************
   2                           geolocation.h  -  K Desktop Planetarium
   3                              -------------------
   4     begin                : Sun Feb 11 2001
   5     copyright            : (C) 2001-2005 by Jason Harris
   6     email                : jharris@30doradus.org
   7     copyright            : (C) 2003-2005 by Pablo de Vicente
   8     email                : p.devicente@wanadoo.es
   9  ***************************************************************************/
  10
  11 /***************************************************************************
  12  *                                                                         *
  13  *   This program is free software; you can redistribute it and/or modify  *
  14  *   it under the terms of the GNU General Public License as published by  *
  15  *   the Free Software Foundation; either version 2 of the License, or     *
  16  *   (at your option) any later version.                                   *
  17  *                                                                         *
  18  ***************************************************************************/
  19
  20 #ifndef GEOLOCATION_H
  21 #define GEOLOCATION_H
  22
  23 #include <klocale.h>
  24
  25 #include "dms.h"
  26 #include "timezonerule.h"
  27 #include "kstarsdatetime.h"
  28
  29 /**@class GeoLocation
  30         *Contains all relevant information for specifying a location
  31         *on Earth: City Name, State/Province name, Country Name,
  32         *Longitude, Latitude, Elevation, Time Zone, and Daylight Savings
  33         *Time rule.
  34         *@short Relevant data about an observing location on Earth.
  35         *@author Jason Harris
  36         *@version 1.0
  37         */
  38
  39 class GeoLocation {
  40 public:
  41 /**
  42         *Default constructor; sets coordinates to zero.
  43         */
  44         GeoLocation();
  45
  46 /**Copy Constructor
  47         *@param g the GeoLocation to duplicate
  48         */
  49         GeoLocation( const GeoLocation &g );
  50
  51 /**Copy Constructor.  Differs from the above function only in argument type.
  52         *@param g pointer to the GeoLocation to duplicate
  53         */
  54         GeoLocation( GeoLocation *g );
  55
  56 /**Constructor using dms objects to specify longitude and latitude.
  57         *@param lng the longitude
  58         *@param lat the latitude
  59         *@param name the name of the city/town/location
  60         *@param province the name of the province/US state
  61         *@param country the name of the country
  62         *@param TZ the base time zone offset from Greenwich, UK
  63         *@param TZrule pointer to the daylight savings time rule
  64         *@param iEllips type of geodetic ellipsoid model
  65         *@param hght the elevation above sea level (in meters?)
  66         */
  67         GeoLocation( dms lng, dms lat, QString name="Nowhere", QString province="Nowhere", QString country="Nowhere", double TZ=0, TimeZoneRule *TZrule=NULL, int iEllips=4, double hght=-10 );
  68
  69 /**Constructor using doubles to specify longitude and latitude.
  70         *@param lng the longitude
  71         *@param lat the latitude
  72         *@param name the name of the city/town/location
  73         *@param province the name of the province/US state
  74         *@param country the name of the country
  75         *@param TZ the base time zone offset from Greenwich, UK
  76         *@param TZrule pointer to the daylight savings time rule
  77         *@param iEllips type of geodetic ellipsoid model
  78         *@param hght the elevation above sea level (in meters?)
  79         */
  80         GeoLocation( double lng, double lat, QString name="Nowhere", QString province="Nowhere", QString country="Nowhere", double TZ=0, TimeZoneRule *TZrule=NULL, int iEllips=4, double hght=-10 );
  81
  82 /**Constructor using doubles to specify X, Y and Z referred to the center of the Earth.
  83         *@param x the x-position, in m
  84         *@param y the y-position, in m
  85         *@param z the z-position, in m
  86         *@param name the name of the city/town/location
  87         *@param province the name of the province/US state
  88         *@param country the name of the country
  89         *@param TZ the base time zone offset from Greenwich, UK
  90         *@param TZrule pointer to the daylight savings time rule
  91         *@param iEllips type of geodetic ellipsoid model
  92         */
  93         GeoLocation( double x, double y, double z, QString name="Nowhere", QString province="Nowhere", QString country="Nowhere", double TZ=0, TimeZoneRule *TZrule=NULL, int iEllips=4 );
  94
  95
  96 /**Destructor (empty)
  97         */
  98         ~GeoLocation() {};
  99
 100 /**@return pointer to the longitude dms object
 101         */
 102         const dms* lng() const { return &Longitude; }
 103 /**@return pointer to the latitude dms object
 104         */
 105         const dms* lat() const { return &Latitude; }
 106 /**@return elevation above seal level (meters)
 107         */
 108         double height() const { return Height; }
 109 /**@return X position in m
 110         */
 111         double xPos() const { return PosCartX; }
 112 /**@return Y position in m
 113         */
 114         double yPos() const { return PosCartY; }
 115 /**@return Z position in m
 116         */
 117         double zPos() const { return PosCartZ; }
 118 /**@return index identifying the geodetic ellipsoid model
 119         */
 120         int ellipsoid() const { return indexEllipsoid; }
 121
 122 /**@return untranslated City name
 123         */
 124         QString name() const { return Name; }
 125 /**@return translated City name
 126         */
 127         QString translatedName() const { return i18n("City name (optional, probably does not need a translation)", Name.utf8().data()); }
 128 /**@return untranslated Province name
 129         */
 130         QString province() const { return Province; }
 131 /**@return translated Province name
 132         */
 133         QString translatedProvince() const { return i18n("Region/state name (optional, rarely needs a translation)", Province.utf8().data()); }
 134 /**@return untranslated Country name
 135         */
 136         QString country() const { return Country; }
 137 /**@return translated Country name
 138  */
 139         QString translatedCountry() const { return i18n("Country name (optional, but should be translated)", Country.utf8().data()); }
 140
 141 /**@return comma-separated city, province, country names (each localized)
 142  */
 143         QString fullName() const;
 144
 145 /**@return time zone without DST correction
 146         */
 147         double TZ0() const { return TimeZone; }
 148
 149 /**@return time zone, including any DST correction.
 150         */
 151         double TZ() const { return TimeZone + TZrule->deltaTZ(); }
 152
 153 /**@return pointer to time zone rule object
 154         */
 155         TimeZoneRule* tzrule() const { return TZrule; }
 156
 157 /**Set longitude according to dms argument.
 158         *@param l the new longitude
 159         */
 160         void setLong( dms l ) {
 161                 Longitude = l;
 162                 geodToCart();
 163         }
 164 /**Set longitude according to argument.
 165         *Differs from above function only in argument type.
 166         *@param l the new longitude
 167         */
 168         void setLong( double l ) {
 169                 Longitude.setD( l );
 170                 geodToCart();
 171         }
 172
 173 /**Set latitude according to dms argument.
 174         *@param l the new latitude
 175         */
 176         void setLat( dms l ) {
 177                 Latitude  = l;
 178                 geodToCart();
 179         }
 180
 181 /**Set latitude according to argument.
 182         *Differs from above function only in argument type.
 183         *@param l the new latitude
 184         */
 185         void setLat( double l ) {
 186                 Latitude.setD( l );
 187                 geodToCart();
 188         }
 189
 190 /**Set elevation above sea level
 191         *@param hg the new elevation (meters)
 192         */
 193         void setHeight( double hg ) {
 194                 Height  = hg;
 195                 geodToCart();
 196         }
 197
 198 /**Set X
 199         *@param x the new x-position (meters)
 200         */
 201         void setXPos( double x ) {
 202                 PosCartX  = x;
 203                 cartToGeod();
 204         }
 205 /**Set Y
 206         *@param y the new y-position (meters)
 207         */
 208         void setYPos( double y ) {
 209                 PosCartY  = y;
 210                 cartToGeod();
 211         }
 212 /**Set Z
 213         *@param z the new z-position (meters)
 214         */
 215         void setZPos( double z ) {
 216                 PosCartZ  = z;
 217                 cartToGeod();
 218         }
 219
 220 /**Update Latitude, Longitude and Height according to new ellipsoid. These are
 221         *computed from XYZ which do NOT change on changing the ellipsoid.
 222         *@p i = index to identify the ellipsoid
 223         */
 224         void changeEllipsoid( int i );
 225
 226 /**Set City name according to argument.
 227         *@p n new city name
 228         */
 229         void setName( const QString &n ) { Name = n; }
 230
 231 /**Set Province name according to argument.
 232         *@p n new province name
 233         */
 234         void setProvince( const QString &n ) { Province = n; }
 235
 236 /**Set Country name according to argument.
 237         *@p n new country name
 238         */
 239         void setCountry( const QString &n ) { Country = n; }
 240
 241 /**Sets Time Zone according to argument.
 242         *@p tz new timezone offset
 243         */
 244         void setTZ( double tz ) { TimeZone = tz; }
 245
 246 /**Sets DST rule pointer according to argument.
 247         *@p txr pointer to the new DST rule
 248         */
 249         void setTZrule( TimeZoneRule *tzr ) { TZrule = tzr; }
 250
 251 /**Set location data to that of the GeoLocation pointed to by argument.
 252         *Similar to copy constructor.
 253         *@param g pointer to the GeoLocation which should be duplicated.
 254         */
 255         void reset( GeoLocation *g );
 256
 257 /**Converts from cartesian coordinates in meters to longitude,
 258         *latitude and height on a standard geoid for the Earth. The
 259         *geoid is characterized by two parameters: the semimajor axis
 260         *and the flattening.
 261         *
 262         *@note The astronomical zenith is defined as the perpendicular to
 263         *the real geoid. The geodetic zenith is the perpendicular to the
 264         *standard geoid. Both zeniths differ due to local gravitational
 265         *anomalies.
 266         *
 267         * Algorithm is from "GPS Satellite Surveying", A. Leick, page 184.
 268         */
 269         void cartToGeod(void);
 270
 271 /**Converts from longitude, latitude and height on a standard
 272         *geoid of the Earth to cartesian coordinates in meters. The geoid
 273         *is characterized by two parameters: the semimajor axis and the
 274         *flattening.
 275         *
 276         *@note The astronomical zenith is defined as the perpendicular to
 277         *the real geoid. The geodetic zenith is the perpendicular to the
 278         *standard geoid. Both zeniths differ due to local gravitational
 279         *anomalies.
 280         *
 281         *Algorithm is from "GPS Satellite Surveying", A. Leick, page 184.
 282         */
 283         void geodToCart (void);
 284
 285 /**The geoid is an elliposid which fits the shape of the Earth. It is
 286         *characterized by two parameters: the semimajor axis and the
 287         *flattening.
 288         *
 289         *@p index is the index which allows to identify the parameters for the
 290         *chosen elliposid. 1="IAU76", 2="GRS80", 3="MERIT83", 4="WGS84",
 291         *5="IERS89"};
 292         */
 293         void setEllipsoid( int i );
 294
 295         dms GSTtoLST( const dms &gst ) const { return dms( gst.Degrees() + Longitude.Degrees() ); }
 296         dms LSTtoGST( const dms &lst ) const { return dms( lst.Degrees() - Longitude.Degrees() ); }
 297
 298         KStarsDateTime UTtoLT( const KStarsDateTime &ut ) const { return ut.addSecs( int( 3600.*TZ() ) ); }
 299         KStarsDateTime LTtoUT( const KStarsDateTime &lt ) const { return lt.addSecs( int( -3600.*TZ() ) ); }
 300
 301
 302         /* Computes the velocity in km/s of an observer on the surface of the Earth
 303          * referred to a system whose origin is the center of the Earth. The X and
 304          * Y axis are contained in the equator and the X axis is towards the nodes
 305          * line. The Z axis is along the poles.
 306          *
 307          * @param vtopo[] Topocentric velocity. The resultant velocity is available
 308          *        in this array.
 309          * @param gt. Greenwich sideral time for which we want to compute the topocentric velocity.
 310          */
 311         void TopocentricVelocity(double vtopo[], dms gt);
 312
 313 private:
 314         dms Longitude, Latitude;
 315         QString Name, Province, Country;
 316         TimeZoneRule *TZrule;
 317         double TimeZone, Height;
 318         double axis, flattening;
 319         long double PosCartX, PosCartY, PosCartZ;
 320         int indexEllipsoid;
 321 };
 322
 323 #endif