1 // SPDX-License-Identifier: LGPL-2.1-or-later 2 // 3 // SPDX-FileCopyrightText: 2012 Rene Kuettner <rene@bitkanal.net> 4 // 5 6 #ifndef MARBLE_ECLIPSESITEM_H 7 #define MARBLE_ECLIPSESITEM_H 8 9 #include <QObject> 10 #include <QDateTime> 11 12 #include "GeoDataLineString.h" 13 #include "GeoDataCoordinates.h" 14 #include "GeoDataLinearRing.h" 15 16 #include <eclsolar.h> 17 18 namespace Marble 19 { 20 21 /** 22 * @brief The representation of an eclipse event 23 * 24 * This class represents an eclipse event on earth. It calculates all 25 * basic information like date and visibility upon initialization. 26 * Expensive calculations like boundary polygons are done the first time 27 * they are requested. 28 * 29 * The calculations are done using the eclsolar backend that has to be 30 * passed to the constructor. 31 */ 32 class EclipsesItem : public QObject 33 { 34 Q_OBJECT 35 36 public: 37 38 /** 39 * @brief A type of an eclipse event 40 */ 41 enum EclipsePhase { 42 TotalMoon = -4, 43 PartialMoon = -3, 44 PenumbralMoon = -1, 45 PartialSun = 1, 46 NonCentralAnnularSun = 2, 47 NonCentralTotalSun = 3, 48 AnnularSun = 4, 49 TotalSun = 5, 50 AnnularTotalSun = 6 51 }; 52 53 /** 54 * @brief Construct the EclipseItem object and trigger basic calculations 55 * @param ecl The EclSolar backend 56 * @param index The object index 57 * @param parent The parent object 58 */ 59 explicit EclipsesItem( EclSolar *ecl, int index, QObject *parent = nullptr ); 60 61 ~EclipsesItem() override; 62 63 /** 64 * @brief The index of the eclipse event 65 * 66 * Returns the index of the eclipse event. 67 * 68 * @return The eclipse events index. 69 */ 70 int index() const; 71 72 /** 73 * @brief Check if the event takes place at a given datetime 74 * @param dateTime The date time to check 75 * 76 * Checks whether or not this eclipse event takes place at the given 77 * @p dateTime. This is true if @p dateTime is between the global 78 * start and end dates of the event. 79 * 80 * @return True if the event takes place at @p dateTime or false otherwise. 81 */ 82 bool takesPlaceAt( const QDateTime &dateTime ) const; 83 84 /** 85 * @brief Returns the phase of this eclipse event 86 * @return the phase or type of this eclipse event 87 * @see phaseText 88 */ 89 EclipsesItem::EclipsePhase phase() const; 90 91 92 /** 93 * @brief Returns an icon of the eclipse type 94 * @return an icon representing the eclipse's type 95 */ 96 QIcon icon() const; 97 98 /** 99 * @brief Returns a human readable representation of the eclipse type 100 * @return A string representing the eclipse's type 101 * @see phase 102 */ 103 QString phaseText() const; 104 105 /** 106 * @brief Returns the date of the eclipse event's maximum 107 * @return The DateTime of the eclipse's maximum 108 * @see maxLocation 109 */ 110 const QDateTime& dateMaximum() const; 111 112 /** 113 * @brief Returns the start date of the eclipse's partial phase 114 * @return The start date of the partial phase 115 * @see endDatePartial 116 */ 117 const QDateTime& startDatePartial() const; 118 119 /** 120 * @brief Returns the end date of the eclipse's partial phase 121 * @return The end date of the partial phase 122 * @see startDatePartial 123 */ 124 const QDateTime& endDatePartial() const; 125 126 /** 127 * @brief Returns the number of hours the partial phase takes place 128 * @return The number of hours of the partial phase 129 * @see startDatePartial, endDatePartial 130 */ 131 int partialDurationHours() const; 132 133 /** 134 * @brief Returns the start date of the eclipse's total phase 135 * 136 * If the eclipse has a total phase, the date and time of its beginning 137 * is returned. If this is no total eclipse, an invalid datetime object 138 * will be returned. 139 * 140 * @return The start date of the total phase or an invalid date 141 * @see endDateTotal 142 */ 143 const QDateTime& startDateTotal() const; 144 145 /** 146 * @brief Returns the end date of the eclipse's total phase 147 * 148 * If the eclipse has a total phase, the date and time of its ending 149 * is returned. If this is no total eclipse, an invalid datetime object 150 * will be returned. 151 * 152 * @return The end date of the total phase or an invalid date 153 * @see startDateTotal 154 */ 155 const QDateTime& endDateTotal() const; 156 157 /** 158 * @brief Return the eclipse's magnitude 159 * @return The magnitude of the eclipse 160 */ 161 double magnitude() const; 162 163 /** 164 * @brief Return the coordinates of the eclipse's maximum 165 * @return GeoDataCoordinates of the eclipse's maximum 166 * @see dateMaximum 167 */ 168 const GeoDataCoordinates& maxLocation(); 169 170 /** 171 * @brief The eclipse's central line 172 * @return The central line of the eclipse 173 */ 174 const GeoDataLineString& centralLine(); 175 176 /** 177 * @brief Return the eclipse's umbra 178 * @return The eclipse's umbra 179 */ 180 const GeoDataLinearRing& umbra(); 181 182 /** 183 * @brief Return the eclipse's southern penumbra 184 * @return The eclipse's southern penumbra 185 */ 186 const GeoDataLineString& southernPenumbra(); 187 188 /** 189 * @brief Return the eclipse's northern penumbra 190 * @return The eclipse's northern umbra 191 */ 192 const GeoDataLineString& northernPenumbra(); 193 194 /** 195 * @brief Return the eclipse's sun boundaries 196 * @return The eclipse's sun boundaries 197 */ 198 const QList<GeoDataLinearRing>& sunBoundaries(); 199 200 /** 201 * @brief Return the shadow cone of the umbra 202 * @return The shadow cone of the umbra 203 */ 204 GeoDataLinearRing shadowConeUmbra(); 205 206 /** 207 * @brief Return the shadow cone of the penumbra 208 * @return The shadow cone of the penumbra 209 */ 210 GeoDataLinearRing shadowConePenumbra(); 211 212 /** 213 * @brief Return the shadow cone of the penumbra at 60 percent magnitude 214 * @return The shadow cone of the penumbra at 60 percent magnitude 215 */ 216 GeoDataLinearRing shadowCone60MagPenumbra(); 217 218 private: 219 /** 220 * @brief Initialize the eclipse item 221 * 222 * Initializes all properties of the eclipse item and does basic 223 * calculations. Expensive calculations are done as required. 224 * 225 * @see calculate 226 */ 227 void initialize(); 228 229 /** 230 * @brief Do detailed calculations 231 * 232 * Do the expensive calculations (like shadow cones) for this eclipse 233 * event. This is normally called on the first request of such data. 234 */ 235 void calculate(); 236 237 EclSolar *m_ecl; 238 int m_index; 239 bool m_calculationsNeedUpdate; 240 bool m_isTotal; 241 QDateTime m_dateMaximum; 242 QDateTime m_startDatePartial; 243 QDateTime m_endDatePartial; 244 QDateTime m_startDateTotal; 245 QDateTime m_endDateTotal; 246 EclipsesItem::EclipsePhase m_phase; 247 double m_magnitude; 248 249 GeoDataCoordinates m_maxLocation; 250 GeoDataLineString m_centralLine; 251 GeoDataLinearRing m_umbra; 252 GeoDataLineString m_southernPenumbra; 253 GeoDataLineString m_northernPenumbra; 254 GeoDataLinearRing m_shadowConeUmbra; 255 GeoDataLinearRing m_shadowConePenumbra; 256 GeoDataLinearRing m_shadowCone60MagPenumbra; 257 QList<GeoDataLinearRing> m_sunBoundaries; 258 }; 259 260 } 261 262 #endif // MARBLE_ECLIPSESITEM_H 263 264