File indexing completed on 2024-04-14 03:43:13

 /*
     SPDX-FileCopyrightText: 2001 Jason Harris <jharris@30doradus.org>
 
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #pragma once
 
 #include "dms.h"
 #include "skypoint.h"
 
 #include <KLocalizedString>
 
 #include <QSharedDataPointer>
 #include <QString>
 #include <QStringList>
 
 class QPoint;
 class GeoLocation;
 class KSPopupMenu;
 
 namespace {
     constexpr const char *emptyString = "";
     constexpr const char *unnamedString       = I18N_NOOP("unnamed");
     constexpr const char *unnamedObjectString = I18N_NOOP("unnamed object");
     constexpr const char *starString          = I18N_NOOP("star");
 }
 
 // Set the faintest sane magnitude to 36.0 (faintest visual magnitude visible with E-ELT, acc. to Wikipedia on Apparent Magnitude.)
 constexpr const float FAINTEST_MAGNITUDE = 36.0;
 
 /**
  * @class SkyObject
  * Provides all necessary information about an object in the sky:
  * its coordinates, name(s), type, magnitude, and QStringLists of
  * URLs for images and webpages regarding the object.
  * @short Information about an object in the sky.
  * @author Jason Harris
  * @version 1.0
  */
 class SkyObject : public SkyPoint
 {
   public:
     /**
      * @short Type for Unique object IDenticator.
      *
      * Each object has unique ID (UID). For different objects UIDs must be different.
      */
     typedef qint64 UID;
 
     /** @short Kind of UID */
     static const UID UID_STAR;
     static const UID UID_GALAXY;
     static const UID UID_DEEPSKY;
     static const UID UID_SOLARSYS;
 
     /** Invalid UID. Real sky object could not have such UID */
     static const UID invalidUID;
 
     /**
      * Constructor.  Set SkyObject data according to arguments.
      * @param t Type of object
      * @param r catalog Right Ascension
      * @param d catalog Declination
      * @param m magnitude (brightness)
      * @param n Primary name
      * @param n2 Secondary name
      * @param lname Long name (common name)
      */
     explicit SkyObject(int t = TYPE_UNKNOWN, dms r = dms(0.0), dms d = dms(0.0), float m = 0.0,
                        const QString &n = QString(), const QString &n2 = QString(), const QString &lname = QString());
     /**
      * Constructor. Set SkyObject data according to arguments. Differs from
      * above function only in data type of RA and Dec.
      * @param t Type of object
      * @param r catalog Right Ascension
      * @param d catalog Declination
      * @param m magnitude (brightness)
      * @param n Primary name
      * @param n2 Secondary name
      * @param lname Long name (common name)
      */
     SkyObject(int t, double r, double d, float m = 0.0, const QString &n = QString(), const QString &n2 = QString(),
               const QString &lname = QString());
 
     /** Destructor (empty) */
     virtual ~SkyObject() override = default;
 
     /**
      * @short Create copy of object.
      * This method is virtual copy constructor. It allows for safe
      * copying of objects. In other words, KSPlanet object stored in
      * SkyObject pointer will be copied as KSPlanet.
      *
      * Each subclass of SkyObject MUST implement clone method. There
      * is no checking to ensure this, though.
      *
      *  @return pointer to newly allocated object. Caller takes full responsibility
      *  for deallocating it.
      */
     virtual SkyObject *clone() const;
 
     /**
      * @enum TYPE
      * The type classification of the SkyObject.
      * @note Keep TYPE_UNKNOWN at 255. To find out how many known
      * types exist, keep the NUMBER_OF_KNOWN_TYPES at the highest
      * non-Unknown value. This is a fake type that can be used in
      * comparisons and for loops.
      */
     enum TYPE
     {
         STAR                  = 0,
         CATALOG_STAR          = 1,
         PLANET                = 2,
         OPEN_CLUSTER          = 3,
         GLOBULAR_CLUSTER      = 4,
         GASEOUS_NEBULA        = 5,
         PLANETARY_NEBULA      = 6,
         SUPERNOVA_REMNANT     = 7,
         GALAXY                = 8,
         COMET                 = 9,
         ASTEROID              = 10,
         CONSTELLATION         = 11,
         MOON                  = 12,
         ASTERISM              = 13,
         GALAXY_CLUSTER        = 14,
         DARK_NEBULA           = 15,
         QUASAR                = 16,
         MULT_STAR             = 17,
         RADIO_SOURCE          = 18,
         SATELLITE             = 19,
         SUPERNOVA             = 20,
         NUMBER_OF_KNOWN_TYPES = 21,
         TYPE_UNKNOWN          = 255
     };
     /**
      * @return A translated string indicating the type name for a given type number
      * @param t The type number
      * @note Note the existence of a SkyObject::typeName( void ) method that is not static and returns the type of this object.
      */
     static QString typeName(const int t);
 
     /** @return object's primary name. */
     inline virtual QString name(void) const { return hasName() ? Name : unnamedString; }
 
     /** @return object's primary name, translated to local language. */
     inline QString translatedName() const
     {
         return i18n(
             name()
                 .toUtf8()); // FIXME: Hmm... that's funny. How does the string extraction work, if we are UTF8-ing the name first? Does the string extraction change to UTF8?
     }
 
     /** @return object's secondary name */
     inline QString name2(void) const { return (hasName2() ? Name2 : emptyString); }
 
     /** @return object's secondary name, translated to local language. */
     inline QString translatedName2() const { return (hasName2() ? i18n(Name2.toUtf8()) : emptyString); }
 
     /**
      * @return object's common (long) name
      */
     virtual QString longname(void) const { return hasLongName() ? LongName : unnamedObjectString; }
 
     /**
      * @return object's common (long) name, translated to local language.
      */
     QString translatedLongName() const { return i18n(longname().toUtf8()); }
 
     /**
      * Set the object's long name.
      * @param longname the object's long name.
      */
     void setLongName(const QString &longname = QString());
 
     /**
      * @return the string used to label the object on the map
      * In the default implementation, this just returns translatedName()
      * Overridden by StarObject.
      */
     virtual QString labelString() const;
 
     /**
      * @return object's type identifier (int)
      * @see enum TYPE
      */
     inline int type(void) const { return (int)Type; }
 
     /**
      * Set the object's type identifier to the argument.
      * @param t the object's type identifier (e.g., "SkyObject::PLANETARY_NEBULA")
      * @see enum TYPE
      */
     inline void setType(int t) { Type = (unsigned char)t; }
 
     /**
      * @return the type name for this object
      * @note This just calls the static method by the same name, with the appropriate type number. See SkyObject::typeName( const int )
      */
     QString typeName() const;
 
     /**
      * @return object's magnitude
      */
     inline float mag() const { return sortMagnitude; }
 
     /**
      * @return the object's position angle.  This is overridden in KSPlanetBase
      * and DeepSkyObject; for all other SkyObjects, this returns 0.0.
      */
     inline virtual double pa() const { return 0.0; }
 
     /**
      * @return true if the object is a solar system body.
      */
     inline bool isSolarSystem() const { return (type() == 2 || type() == 9 || type() == 10 || type() == 12); }
 
     /**
      * Initialize the popup menut. This function should call correct
      * initialization function in KSPopupMenu. By overloading the
      * function, we don't have to check the object type when we need
      * the menu.
      */
     virtual void initPopupMenu(KSPopupMenu *pmenu);
 
     /** Show Type-specific popup menu. Overloading is done in the function initPopupMenu */
     void showPopupMenu(KSPopupMenu *pmenu, const QPoint &pos);
 
     /**
      * Determine the time at which the point will rise or set.  Because solar system
      * objects move across the sky, it is necessary to iterate on the solution.
      * We compute the rise/set time for the object's current position, then
      * compute the object's position at that time.  Finally, we recompute then
      * rise/set time for the new coordinates.  Further iteration is not necessary,
      * even for the most swiftly-moving object (the Moon).
      * @return the local time that the object will rise
      * @param dt current UT date/time
      * @param geo current geographic location
      * @param rst If true, compute rise time. If false, compute set time.
      * @param exact If true, use a second iteration for more accurate time
      */
     QTime riseSetTime(const KStarsDateTime &dt, const GeoLocation *geo, bool rst, bool exact = true) const;
 
     /**
      * @return the UT time when the object will rise or set
      * @param dt  target date/time
      * @param geo pointer to Geographic location
      * @param rst Boolean. If true will compute rise time. If false
      * will compute set time.
      * @param exact If true, use a second iteration for more accurate time
      */
     QTime riseSetTimeUT(const KStarsDateTime &dt, const GeoLocation *geo, bool rst, bool exact = true) const;
 
     /**
      * @return the Azimuth time when the object will rise or set. This function
      * recomputes set or rise UT times.
      * @param dt  target date/time
      * @param geo GeoLocation object
      * @param rst Boolen. If true will compute rise time. If false
      * will compute set time.
      */
     dms riseSetTimeAz(const KStarsDateTime &dt, const GeoLocation *geo, bool rst) const;
 
     /**
      * The same iteration technique described in riseSetTime() is used here.
      * @return the local time that the object will transit the meridian.
      * @param dt  target date/time
      * @param geo pointer to the geographic location
      */
     QTime transitTime(const KStarsDateTime &dt, const GeoLocation *geo) const;
 
     /**
      * @return the universal time that the object will transit the meridian.
      * @param dt   target date/time
      * @param geo pointer to the geographic location
      */
     QTime transitTimeUT(const KStarsDateTime &dt, const GeoLocation *geo) const;
 
     /**
      * @return the altitude of the object at the moment it transits the meridian.
      * @param dt  target date/time
      * @param geo pointer to the geographic location
      */
     dms transitAltitude(const KStarsDateTime &dt, const GeoLocation *geo) const;
 
     /**
      * The equatorial coordinates for the object on date dt are computed and returned,
      * but the object's internal coordinates are not modified.
      * @return the coordinates of the selected object for the time given by jd
      * @param dt  date/time for which the coords will be computed.
      * @param geo pointer to geographic location (used for solar system only)
      * @note Does not update the horizontal coordinates. Call EquatorialToHorizontal for that.
      */
     SkyPoint recomputeCoords(const KStarsDateTime &dt, const GeoLocation *geo = nullptr) const;
 
     /**
      * @short Like recomputeCoords, but also calls EquatorialToHorizontal before returning
      */
     SkyPoint recomputeHorizontalCoords(const KStarsDateTime &dt, const GeoLocation *geo) const;
 
     inline bool hasName() const { return !Name.isEmpty(); }
 
     inline bool hasName2() const { return !Name2.isEmpty(); }
 
     inline bool hasLongName() const { return !LongName.isEmpty(); }
 
     /**
      * @short Given the Image title from a URL file, try to convert it to an image credit string.
      */
     QString messageFromTitle(const QString &imageTitle) const;
 
     /**
      * @return the pixel distance for offseting the object's name label
      * @note overridden in StarObject, DeepSkyObject, KSPlanetBase
      */
     virtual double labelOffset() const;
 
     /**
      * @short Return UID for object.
      * This method should be reimplemented in all concrete
      * subclasses. Implementation for SkyObject just returns
      * invalidUID. It's required SkyObject is not an abstract class.
      */
     virtual UID getUID() const;
 
     // TODO: (Valentin) have another think about onFocus handlers :)    
 
     /**
      * @brief hashBeenUpdated
      * @return whether the coordinates of the object have been updated
      *
      * This is used for faster filtering.
      */
     bool hashBeenUpdated() { return has_been_updated; }
 
   private:
     /**
      * Compute the UT time when the object will rise or set. It is an auxiliary
      * procedure because it does not use the RA and DEC of the object but values
      * given as parameters. You may want to use riseSetTimeUT() which is
      * public.  riseSetTimeUT() calls this function iteratively.
      * @param dt     target date/time
      * @param geo    pointer to Geographic location
      * @param righta pointer to Right ascention of the object
      * @param decl   pointer to Declination of the object
      * @param rst    Boolean. If true will compute rise time. If false
      * will compute set time.
      * @return the time at which the given position will rise or set.
      */
     QTime auxRiseSetTimeUT(const KStarsDateTime &dt, const GeoLocation *geo, const dms *righta, const dms *decl,
                            bool riseT) const;
 
     /**
      * Compute the LST time when the object will rise or set. It is an auxiliary
      * procedure because it does not use the RA and DEC of the object but values
      * given as parameters. You may want to use riseSetTimeLST() which is
      * public.  riseSetTimeLST() calls this function iteratively.
      * @param gLt Geographic latitude
      * @param rga Right ascention of the object
      * @param decl Declination of the object
      * @param rst Boolean. If true will compute rise time. If false
      * will compute set time.
      */
     dms auxRiseSetTimeLST(const dms *gLt, const dms *rga, const dms *decl, bool rst) const;
 
     /**
      * Compute the approximate hour angle that an object with declination d will have
      * when its altitude is h (as seen from geographic latitude gLat).
      * This function is only used by auxRiseSetTimeLST().
      * @param h pointer to the altitude of the object
      * @param gLat pointer to the geographic latitude
      * @param d pointer to the declination of the object.
      * @return the Hour Angle, in degrees.
      */
     double approxHourAngle(const dms *h, const dms *gLat, const dms *d) const;
 
     /**
      * Correct for the geometric altitude of the center of the body at the
      * time of rising or setting. This is due to refraction at the horizon
      * and to the size of the body. The moon correction has also to take into
      * account parallax. The value we use here is a rough approximation
      * suggested by J. Meeus.
      *
      * Weather status (temperature and pressure basically) is not taken
      * into account although change of conditions between summer and
      * winter could shift the times of sunrise and sunset by 20 seconds.
      *
      * This function is only used by auxRiseSetTimeLST().
      * @return dms object with the correction.
      */
     dms elevationCorrection(void) const;
 
     unsigned char Type;
     float
         sortMagnitude; // This magnitude is used for sorting / making decisions about the visibility of an object. Should not be NaN.
 
   protected:
     /**
      * Set the object's sorting magnitude.
      * @param m the object's magnitude.
      */
     inline void setMag(float m)
     {
         sortMagnitude =
             m < FAINTEST_MAGNITUDE ?
                 m :
                 NaN::
                     f;
     }
     // FIXME: We claim sortMagnitude should not be NaN, but we are setting it to NaN above!! ^
 
     /**
      * Set the object's primary name.
      * @param name the object's primary name
      */
     inline void setName(const QString &name) { Name = name; }
 
     /**
      * Set the object's secondary name.
      * @param name2 the object's secondary name.
      */
     inline void setName2(const QString &name2 = QString()) { Name2 = name2; }
 
     QString Name, Name2, LongName;
 
     // Whether the coordinates of the object have been updated.
     // The default value is chose for compatibility reasons.
     // It primarily matters for objects which are filtered.
     // See `KSAsteroid` for an example.
     bool has_been_updated = true;
 };