Kstars

skyobject.h
1/*
2 SPDX-FileCopyrightText: 2001 Jason Harris <jharris@30doradus.org>
3
4 SPDX-License-Identifier: GPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "dms.h"
10#include "skypoint.h"
11
12#include <KLazyLocalizedString>
13
14#include <QSharedDataPointer>
15#include <QString>
16#include <QStringList>
17
18class QPoint;
19class GeoLocation;
20class KSPopupMenu;
21
22namespace {
23 const auto emptyString = QStringLiteral();
24 const auto unnamedString = kli18n("unnamed");
25 const auto unnamedObjectString = kli18n("unnamed object");
26 const auto starString = kli18n("star");
27}
28
29// Set the faintest sane magnitude to 36.0 (faintest visual magnitude visible with E-ELT, acc. to Wikipedia on Apparent Magnitude.)
30constexpr const float FAINTEST_MAGNITUDE = 36.0;
31
32/**
33 * @class SkyObject
34 * Provides all necessary information about an object in the sky:
35 * its coordinates, name(s), type, magnitude, and QStringLists of
36 * URLs for images and webpages regarding the object.
37 * @short Information about an object in the sky.
38 * @author Jason Harris
39 * @version 1.0
40 */
41class SkyObject : public SkyPoint
42{
43 public:
44 /**
45 * @short Type for Unique object IDenticator.
46 *
47 * Each object has unique ID (UID). For different objects UIDs must be different.
48 */
49 typedef qint64 UID;
50
51 /** @short Kind of UID */
52 static const UID UID_STAR;
53 static const UID UID_GALAXY;
54 static const UID UID_DEEPSKY;
55 static const UID UID_SOLARSYS;
56
57 /** Invalid UID. Real sky object could not have such UID */
58 static const UID invalidUID;
59
60 /**
61 * Constructor. Set SkyObject data according to arguments.
62 * @param t Type of object
63 * @param r catalog Right Ascension
64 * @param d catalog Declination
65 * @param m magnitude (brightness)
66 * @param n Primary name
67 * @param n2 Secondary name
68 * @param lname Long name (common name)
69 */
70 explicit SkyObject(int t = TYPE_UNKNOWN, dms r = dms(0.0), dms d = dms(0.0), float m = 0.0,
71 const QString &n = QString(), const QString &n2 = QString(), const QString &lname = QString());
72 /**
73 * Constructor. Set SkyObject data according to arguments. Differs from
74 * above function only in data type of RA and Dec.
75 * @param t Type of object
76 * @param r catalog Right Ascension
77 * @param d catalog Declination
78 * @param m magnitude (brightness)
79 * @param n Primary name
80 * @param n2 Secondary name
81 * @param lname Long name (common name)
82 */
83 SkyObject(int t, double r, double d, float m = 0.0, const QString &n = QString(), const QString &n2 = QString(),
84 const QString &lname = QString());
85
86 /** Destructor (empty) */
87 virtual ~SkyObject() override = default;
88
89 /**
90 * @short Create copy of object.
91 * This method is virtual copy constructor. It allows for safe
92 * copying of objects. In other words, KSPlanet object stored in
93 * SkyObject pointer will be copied as KSPlanet.
94 *
95 * Each subclass of SkyObject MUST implement clone method. There
96 * is no checking to ensure this, though.
97 *
98 * @return pointer to newly allocated object. Caller takes full responsibility
99 * for deallocating it.
100 */
101 virtual SkyObject *clone() const;
102
103 /**
104 * @enum TYPE
105 * The type classification of the SkyObject.
106 * @note Keep TYPE_UNKNOWN at 255. To find out how many known
107 * types exist, keep the NUMBER_OF_KNOWN_TYPES at the highest
108 * non-Unknown value. This is a fake type that can be used in
109 * comparisons and for loops.
110 */
111 enum TYPE
112 {
113 STAR = 0,
114 CATALOG_STAR = 1,
115 PLANET = 2,
116 OPEN_CLUSTER = 3,
117 GLOBULAR_CLUSTER = 4,
118 GASEOUS_NEBULA = 5,
119 PLANETARY_NEBULA = 6,
120 SUPERNOVA_REMNANT = 7,
121 GALAXY = 8,
122 COMET = 9,
123 ASTEROID = 10,
124 CONSTELLATION = 11,
125 MOON = 12,
126 ASTERISM = 13,
127 GALAXY_CLUSTER = 14,
128 DARK_NEBULA = 15,
129 QUASAR = 16,
130 MULT_STAR = 17,
131 RADIO_SOURCE = 18,
132 SATELLITE = 19,
133 SUPERNOVA = 20,
134 NUMBER_OF_KNOWN_TYPES = 21,
135 TYPE_UNKNOWN = 255
136 };
137 /**
138 * @return A translated string indicating the type name for a given type number
139 * @param t The type number
140 * @note Note the existence of a SkyObject::typeName( void ) method that is not static and returns the type of this object.
141 */
142 static QString typeName(const int t);
143 static QString typeShortName(const int t);
144
145 /** @return object's primary name. */
146 inline virtual QString name(void) const { return hasName() ? Name : unnamedString.toString(); }
147
148 /** @return object's primary name, translated to local language. */
149 inline QString translatedName() const
150 {
151 return i18n(
152 name()
153 .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?
154 }
155
156 /** @return object's secondary name */
157 inline QString name2(void) const { return (hasName2() ? Name2 : emptyString); }
158
159 /** @return object's secondary name, translated to local language. */
160 inline QString translatedName2() const { return (hasName2() ? i18n(Name2.toUtf8()) : emptyString); }
161
162 /**
163 * @return object's common (long) name
164 */
165 virtual QString longname(void) const { return hasLongName() ? LongName : unnamedObjectString.toString(); }
166
167 /**
168 * @return object's common (long) name, translated to local language.
169 */
170 QString translatedLongName() const { return i18n(longname().toUtf8()); }
171
172 /**
173 * Set the object's long name.
174 * @param longname the object's long name.
175 */
176 void setLongName(const QString &longname = QString());
177
178 /**
179 * @return the string used to label the object on the map
180 * In the default implementation, this just returns translatedName()
181 * Overridden by StarObject.
182 */
183 virtual QString labelString() const;
184
185 /**
186 * @return object's type identifier (int)
187 * @see enum TYPE
188 */
189 inline int type(void) const { return (int)Type; }
190
191 /**
192 * Set the object's type identifier to the argument.
193 * @param t the object's type identifier (e.g., "SkyObject::PLANETARY_NEBULA")
194 * @see enum TYPE
195 */
196 inline void setType(int t) { Type = (unsigned char)t; }
197
198 /**
199 * @return the type name for this object
200 * @note This just calls the static method by the same name, with the appropriate type number. See SkyObject::typeName( const int )
201 */
202 QString typeName() const;
203
204 /**
205 * @return object's magnitude
206 */
207 inline float mag() const { return sortMagnitude; }
208
209 /**
210 * @return the object's position angle. This is overridden in KSPlanetBase
211 * and DeepSkyObject; for all other SkyObjects, this returns 0.0.
212 */
213 inline virtual double pa() const { return 0.0; }
214
215 /**
216 * @return true if the object is a solar system body.
217 */
218 inline bool isSolarSystem() const { return (type() == 2 || type() == 9 || type() == 10 || type() == 12); }
219
220 /**
221 * Initialize the popup menut. This function should call correct
222 * initialization function in KSPopupMenu. By overloading the
223 * function, we don't have to check the object type when we need
224 * the menu.
225 */
226 virtual void initPopupMenu(KSPopupMenu *pmenu);
227
228 /** Show Type-specific popup menu. Overloading is done in the function initPopupMenu */
229 void showPopupMenu(KSPopupMenu *pmenu, const QPoint &pos);
230
231 /**
232 * Determine the time at which the point will rise or set. Because solar system
233 * objects move across the sky, it is necessary to iterate on the solution.
234 * We compute the rise/set time for the object's current position, then
235 * compute the object's position at that time. Finally, we recompute then
236 * rise/set time for the new coordinates. Further iteration is not necessary,
237 * even for the most swiftly-moving object (the Moon).
238 * @return the local time that the object will rise
239 * @param dt current UT date/time
240 * @param geo current geographic location
241 * @param rst If true, compute rise time. If false, compute set time.
242 * @param exact If true, use a second iteration for more accurate time
243 */
244 QTime riseSetTime(const KStarsDateTime &dt, const GeoLocation *geo, bool rst, bool exact = true) const;
245
246 /**
247 * @return the UT time when the object will rise or set
248 * @param dt target date/time
249 * @param geo pointer to Geographic location
250 * @param rst Boolean. If true will compute rise time. If false
251 * will compute set time.
252 * @param exact If true, use a second iteration for more accurate time
253 */
254 QTime riseSetTimeUT(const KStarsDateTime &dt, const GeoLocation *geo, bool rst, bool exact = true) const;
255
256 /**
257 * @return the Azimuth time when the object will rise or set. This function
258 * recomputes set or rise UT times.
259 * @param dt target date/time
260 * @param geo GeoLocation object
261 * @param rst Boolen. If true will compute rise time. If false
262 * will compute set time.
263 */
264 dms riseSetTimeAz(const KStarsDateTime &dt, const GeoLocation *geo, bool rst) const;
265
266 /**
267 * The same iteration technique described in riseSetTime() is used here.
268 * @return the local time that the object will transit the meridian.
269 * @param dt target date/time
270 * @param geo pointer to the geographic location
271 */
272 QTime transitTime(const KStarsDateTime &dt, const GeoLocation *geo) const;
273
274 /**
275 * @return the universal time that the object will transit the meridian.
276 * @param dt target date/time
277 * @param geo pointer to the geographic location
278 */
279 QTime transitTimeUT(const KStarsDateTime &dt, const GeoLocation *geo) const;
280
281 /**
282 * @return the altitude of the object at the moment it transits the meridian.
283 * @param dt target date/time
284 * @param geo pointer to the geographic location
285 */
286 dms transitAltitude(const KStarsDateTime &dt, const GeoLocation *geo) const;
287
288 /**
289 * The equatorial coordinates for the object on date dt are computed and returned,
290 * but the object's internal coordinates are not modified.
291 * @return the coordinates of the selected object for the time given by jd
292 * @param dt date/time for which the coords will be computed.
293 * @param geo pointer to geographic location (used for solar system only)
294 * @note Does not update the horizontal coordinates. Call EquatorialToHorizontal for that.
295 */
296 SkyPoint recomputeCoords(const KStarsDateTime &dt, const GeoLocation *geo = nullptr) const;
297
298 /**
299 * @short Like recomputeCoords, but also calls EquatorialToHorizontal before returning
300 */
301 SkyPoint recomputeHorizontalCoords(const KStarsDateTime &dt, const GeoLocation *geo) const;
302
303 inline bool hasName() const { return !Name.isEmpty(); }
304
305 inline bool hasName2() const { return !Name2.isEmpty(); }
306
307 inline bool hasLongName() const { return !LongName.isEmpty(); }
308
309 /**
310 * @short Given the Image title from a URL file, try to convert it to an image credit string.
311 */
312 QString messageFromTitle(const QString &imageTitle) const;
313
314 /**
315 * @return the pixel distance for offseting the object's name label
316 * @note overridden in StarObject, DeepSkyObject, KSPlanetBase
317 */
318 virtual double labelOffset() const;
319
320 /**
321 * @short Return UID for object.
322 * This method should be reimplemented in all concrete
323 * subclasses. Implementation for SkyObject just returns
324 * invalidUID. It's required SkyObject is not an abstract class.
325 */
326 virtual UID getUID() const;
327
328 // TODO: (Valentin) have another think about onFocus handlers :)
329
330 /**
331 * @brief hashBeenUpdated
332 * @return whether the coordinates of the object have been updated
333 *
334 * This is used for faster filtering.
335 */
336 bool hashBeenUpdated() { return has_been_updated; }
337
338 private:
339 /**
340 * Compute the UT time when the object will rise or set. It is an auxiliary
341 * procedure because it does not use the RA and DEC of the object but values
342 * given as parameters. You may want to use riseSetTimeUT() which is
343 * public. riseSetTimeUT() calls this function iteratively.
344 * @param dt target date/time
345 * @param geo pointer to Geographic location
346 * @param righta pointer to Right ascention of the object
347 * @param decl pointer to Declination of the object
348 * @param rst Boolean. If true will compute rise time. If false
349 * will compute set time.
350 * @return the time at which the given position will rise or set.
351 */
352 QTime auxRiseSetTimeUT(const KStarsDateTime &dt, const GeoLocation *geo, const dms *righta, const dms *decl,
353 bool riseT) const;
354
355 /**
356 * Compute the LST time when the object will rise or set. It is an auxiliary
357 * procedure because it does not use the RA and DEC of the object but values
358 * given as parameters. You may want to use riseSetTimeLST() which is
359 * public. riseSetTimeLST() calls this function iteratively.
360 * @param gLt Geographic latitude
361 * @param rga Right ascention of the object
362 * @param decl Declination of the object
363 * @param rst Boolean. If true will compute rise time. If false
364 * will compute set time.
365 */
366 dms auxRiseSetTimeLST(const dms *gLt, const dms *rga, const dms *decl, bool rst) const;
367
368 /**
369 * Compute the approximate hour angle that an object with declination d will have
370 * when its altitude is h (as seen from geographic latitude gLat).
371 * This function is only used by auxRiseSetTimeLST().
372 * @param h pointer to the altitude of the object
373 * @param gLat pointer to the geographic latitude
374 * @param d pointer to the declination of the object.
375 * @return the Hour Angle, in degrees.
376 */
377 double approxHourAngle(const dms *h, const dms *gLat, const dms *d) const;
378
379 /**
380 * Correct for the geometric altitude of the center of the body at the
381 * time of rising or setting. This is due to refraction at the horizon
382 * and to the size of the body. The moon correction has also to take into
383 * account parallax. The value we use here is a rough approximation
384 * suggested by J. Meeus.
385 *
386 * Weather status (temperature and pressure basically) is not taken
387 * into account although change of conditions between summer and
388 * winter could shift the times of sunrise and sunset by 20 seconds.
389 *
390 * This function is only used by auxRiseSetTimeLST().
391 * @return dms object with the correction.
392 */
393 dms elevationCorrection(void) const;
394
395 unsigned char Type;
396 float
397 sortMagnitude; // This magnitude is used for sorting / making decisions about the visibility of an object. Should not be NaN.
398
399 protected:
400 /**
401 * Set the object's sorting magnitude.
402 * @param m the object's magnitude.
403 */
404 inline void setMag(float m)
405 {
406 sortMagnitude =
407 m < FAINTEST_MAGNITUDE ?
408 m :
409 NaN::
410 f;
411 }
412 // FIXME: We claim sortMagnitude should not be NaN, but we are setting it to NaN above!! ^
413
414 /**
415 * Set the object's primary name.
416 * @param name the object's primary name
417 */
418 inline void setName(const QString &name) { Name = name; }
419
420 /**
421 * Set the object's secondary name.
422 * @param name2 the object's secondary name.
423 */
424 inline void setName2(const QString &name2 = QString()) { Name2 = name2; }
425
426 QString Name, Name2, LongName;
427
428 // Whether the coordinates of the object have been updated.
429 // The default value is chose for compatibility reasons.
430 // It primarily matters for objects which are filtered.
431 // See `KSAsteroid` for an example.
432 bool has_been_updated = true;
433};
GeoLocation
Contains all relevant information for specifying a location on Earth: City Name, State/Province name,...
Definition geolocation.h:28
KSPopupMenu
The KStars Popup Menu.
Definition kspopupmenu.h:35
KStarsDateTime
Extension of QDateTime for KStars KStarsDateTime can represent the date/time as a Julian Day,...
Definition kstarsdatetime.h:36
SkyObject
Provides all necessary information about an object in the sky: its coordinates, name(s),...
Definition skyobject.h:42
SkyObject::setName2
void setName2(const QString &name2=QString())
Set the object's secondary name.
Definition skyobject.h:424
SkyObject::initPopupMenu
virtual void initPopupMenu(KSPopupMenu *pmenu)
Initialize the popup menut.
Definition skyobject.cpp:67
SkyObject::setLongName
void setLongName(const QString &longname=QString())
Set the object's long name.
Definition skyobject.cpp:76
SkyObject::invalidUID
static const UID invalidUID
Invalid UID.
Definition skyobject.h:58
SkyObject::recomputeHorizontalCoords
SkyPoint recomputeHorizontalCoords(const KStarsDateTime &dt, const GeoLocation *geo) const
Like recomputeCoords, but also calls EquatorialToHorizontal before returning.
Definition skyobject.cpp:329
SkyObject::setMag
void setMag(float m)
Set the object's sorting magnitude.
Definition skyobject.h:404
SkyObject::clone
virtual SkyObject * clone() const
Create copy of object.
Definition skyobject.cpp:50
SkyObject::SkyObject
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.
Definition skyobject.cpp:30
SkyObject::hashBeenUpdated
bool hashBeenUpdated()
hashBeenUpdated
Definition skyobject.h:336
SkyObject::translatedName
QString translatedName() const
Definition skyobject.h:149
SkyObject::showPopupMenu
void showPopupMenu(KSPopupMenu *pmenu, const QPoint &pos)
Show Type-specific popup menu.
Definition skyobject.cpp:56
SkyObject::riseSetTimeAz
dms riseSetTimeAz(const KStarsDateTime &dt, const GeoLocation *geo, bool rst) const
Definition skyobject.cpp:190
SkyObject::~SkyObject
virtual ~SkyObject() override=default
Destructor (empty)
SkyObject::UID_STAR
static const UID UID_STAR
Kind of UID.
Definition skyobject.h:52
SkyObject::pa
virtual double pa() const
Definition skyobject.h:213
SkyObject::labelString
virtual QString labelString() const
Definition skyobject.cpp:499
SkyObject::transitTimeUT
QTime transitTimeUT(const KStarsDateTime &dt, const GeoLocation *geo) const
Definition skyobject.cpp:221
SkyObject::name
virtual QString name(void) const
Definition skyobject.h:146
SkyObject::transitAltitude
dms transitAltitude(const KStarsDateTime &dt, const GeoLocation *geo) const
Definition skyobject.cpp:244
SkyObject::translatedName2
QString translatedName2() const
Definition skyobject.h:160
SkyObject::translatedLongName
QString translatedLongName() const
Definition skyobject.h:170
SkyObject::messageFromTitle
QString messageFromTitle(const QString &imageTitle) const
Given the Image title from a URL file, try to convert it to an image credit string.
Definition skyobject.cpp:444
SkyObject::isSolarSystem
bool isSolarSystem() const
Definition skyobject.h:218
SkyObject::setName
void setName(const QString &name)
Set the object's primary name.
Definition skyobject.h:418
SkyObject::longname
virtual QString longname(void) const
Definition skyobject.h:165
SkyObject::name2
QString name2(void) const
Definition skyobject.h:157
SkyObject::UID
qint64 UID
Type for Unique object IDenticator.
Definition skyobject.h:49
SkyObject::transitTime
QTime transitTime(const KStarsDateTime &dt, const GeoLocation *geo) const
The same iteration technique described in riseSetTime() is used here.
Definition skyobject.cpp:239
SkyObject::getUID
virtual UID getUID() const
Return UID for object.
Definition skyobject.cpp:509
SkyObject::riseSetTime
QTime riseSetTime(const KStarsDateTime &dt, const GeoLocation *geo, bool rst, bool exact=true) const
Determine the time at which the point will rise or set.
Definition skyobject.cpp:93
SkyObject::type
int type(void) const
Definition skyobject.h:189
SkyObject::typeName
QString typeName() const
Definition skyobject.cpp:439
SkyObject::mag
float mag() const
Definition skyobject.h:207
SkyObject::setType
void setType(int t)
Set the object's type identifier to the argument.
Definition skyobject.h:196
SkyObject::riseSetTimeUT
QTime riseSetTimeUT(const KStarsDateTime &dt, const GeoLocation *geo, bool rst, bool exact=true) const
Definition skyobject.cpp:127
SkyObject::labelOffset
virtual double labelOffset() const
Definition skyobject.cpp:504
SkyObject::recomputeCoords
SkyPoint recomputeCoords(const KStarsDateTime &dt, const GeoLocation *geo=nullptr) const
The equatorial coordinates for the object on date dt are computed and returned, but the object's inte...
Definition skyobject.cpp:295
SkyObject::TYPE
TYPE
The type classification of the SkyObject.
Definition skyobject.h:112
SkyPoint
The sky coordinates of a point in the sky.
Definition skypoint.h:45
dms
An angle, stored as degrees, but expressible in many ways.
Definition dms.h:38
i18n
QString i18n(const char *text, const TYPE &arg...)
QString::isEmpty
bool isEmpty() const const
QString::toUtf8
QByteArray toUtf8() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 13 2024 11:47:12 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.