Kstars

skymesh.h
1 /*
2  SPDX-FileCopyrightText: 2007 James B. Bowlin <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "ksnumbers.h"
10 #include "typedef.h"
11 #include "htmesh/HTMesh.h"
12 
13 #include <QMap>
14 
15 class QPainter;
16 class QPointF;
17 class QPolygonF;
18 
19 class KSNumbers;
20 class SkyPoint;
21 class StarObject;
22 
23 // These enums control the trixel storage. Separate buffers are available for
24 // indexing and intersecting. Currently only one buffer is required. Multiple
25 // buffers could be used for intermingling drawing and searching or to have a
26 // non-precessed aperture for objects that don't precess. If a buffer number
27 // is greater than or equal to NUM_BUF a brief error message will be printed
28 // and then KStars will crash. This is a feature, not a bug.
29 
30 enum MeshBufNum_t
31 {
32  DRAW_BUF = 0,
33  NO_PRECESS_BUF = 1,
34  OBJ_NEAREST_BUF = 2,
35  IN_CONSTELL_BUF = 3,
36  NUM_MESH_BUF
37 };
38 
39 /** @class SkyMesh
40  * Provides an interface to the Hierarchical Triangular Mesh (HTM) library
41  * written by A. Szalay, John Doug Reynolds, Jim Gray, and Peter Z. Kunszt.
42  *
43  * HTM divides the celestial sphere up into little triangles (trixels) and
44  * gives each triangle a unique integer id. We index objects by putting a
45  * pointer to the object in a data structure accessible by the id number, for
46  * example QList<QList<StarObject*> or QHash<int, QList<LineListComponent*>.
47  *
48  * Use aperture(centerPoint, radius) to get a list of trixels visible in the
49  * circle. Then use a MeshIterator to iterate over the indices of the visible
50  * trixels. Look up each index in the top level QHash or QList data structure
51  * and the union of all the elements of the QList's returned will contain all
52  * the objects visible in the circle in the sky specified in the aperture()
53  * call.
54  *
55  * The drawID is used for extended objects that may be covered by more than
56  * one trixel. Every time aperture() is called, drawID is incremented by one.
57  * Extended objects should each contain their own drawID. If an object's
58  * drawID is the same as the current drawID then it shouldn't be drawn again
59  * because it was already drawn in this draw cycle. If the drawID is
60  * different then it should be drawn and then the drawID should be set to the
61  * current drawID() so it doesn't get drawn again this cycle.
62  *
63  * The list of visible trixels found from an aperture() call or one of the
64  * primitive index() by creating a new MeshIterator instance:
65  *
66  * MeshIterator( HTMesh *mesh )
67  *
68  * The MeshIterator has its own bool hasNext(), int next(), and int size()
69  * methods for iterating through the integer indices of the found trixels or
70  * for just getting the total number of found trixels.
71  */
72 
73 class SkyMesh : public HTMesh
74 {
75  protected:
76  SkyMesh(int level);
77  // FIXME: check copy ctor
78  SkyMesh(SkyMesh &skyMesh);
79 
80  public:
81  /** @short creates the single instance of SkyMesh. The level indicates
82  * how fine a mesh we will use. The number of triangles (trixels) in the
83  * mesh will be 8 * 4^level so a mesh of level 5 will have 8 * 4^5 = 8 *
84  * 2^10 = 8192 trixels. The size of the triangles are roughly pi / *
85  * 2^(level + 1) so a level 5 mesh will have triangles size roughly of
86  * .05 radians or 2.8 degrees.
87  */
88  static SkyMesh *Create(int level);
89 
90  /** @short returns the default instance of SkyMesh or null if it has not
91  * yet been created.
92  */
93  static SkyMesh *Instance();
94 
95  /**
96  *@short returns the instance of SkyMesh corresponding to the given level
97  *@return the instance of SkyMesh at the given level, or nullptr if it has not
98  *yet been created.
99  */
100  static SkyMesh *Instance(int level);
101 
102  /**
103  *@short finds the set of trixels that cover the circular aperture
104  * specified after first performing a reverse precession correction on
105  * the center so we don't have to re-index objects simply due to
106  * precession. The drawID also gets incremented which is useful for
107  * drawing extended objects. Typically a safety factor of about one
108  * degree is added to the radius to account for proper motion,
109  * refraction and other imperfections.
110  *@param center Center of the aperture
111  *@param radius Radius of the aperture in degrees
112  *@param bufNum Buffer to use
113  *@note See HTMesh.h for more
114  */
115  void aperture(SkyPoint *center, double radius, MeshBufNum_t bufNum = DRAW_BUF);
116 
117  /** @short returns the index of the trixel containing p.
118  */
119  Trixel index(const SkyPoint *p);
120 
121  /**
122  * @short returns the sky region needed to cover the rectangle defined by two
123  * SkyPoints p1 and p2
124  * @param p1 top-left SkyPoint of the rectangle
125  * @param p2 bottom-right SkyPoint of the rectangle
126  */
127  const SkyRegion &skyRegion(const SkyPoint &p1, const SkyPoint &p2);
128 
129  /** @name Stars and CLines
130  Routines used for indexing stars and CLines.
131  The following four routines are used for indexing stars and CLines.
132  They differ from the normal routines because they take proper motion
133  into account while the normal routines always index the J2000
134  position.
135 
136  Since the proper motion depends on time, it is essential to call
137  setKSNumbers to set the time before doing the indexing. The default
138  value is J2000.
139  */
140 
141  /** @{*/
142 
143  /** @short sets the time for indexing StarObjects and CLines.
144  */
145  void setKSNumbers(KSNumbers *num) { m_KSNumbers = KSNumbers(*num); }
146 
147  /** @short returns the trixel that contains the star at the set
148  * time with proper motion taken into account but not precession.
149  * This is a feature not a bug.
150  */
151  Trixel indexStar(StarObject *star);
152 
153  /** @short fills the default buffer with all the trixels needed to cover
154  * the line connecting the two stars.
155  */
156  void indexStar(StarObject *star1, StarObject *star2);
157 
158  /** @short Fills a hash with all the trixels needed to cover all the line
159  * segments in the SkyList where each SkyPoint is assumed to be a star
160  * and proper motion is taken into account. Used only by
161  * ConstellationsLines.
162  */
163  const IndexHash &indexStarLine(SkyList *points);
164 
165  /** @}*/
166 
167  //----- Here come index routines for various shapes -----
168 
169  /** @name Multi Shape Index Routines
170  * The first two routines use QPoint and the rest use SkyPoint
171  */
172 
173  /** @{*/
174 
175  /** @short finds the indices of the trixels that cover the triangle
176  * specified by the three QPointF's.
177  */
178  void index(const QPointF &p1, const QPointF &p2, const QPointF &p3);
179 
180  /** @short Finds the trixels needed to cover the quadrilateral specified
181  * by the four QPointF's.
182  */
183  void index(const QPointF &p1, const QPointF &p2, const QPointF &p3, const QPointF &p4);
184 
185  /** @short finds the indices of the trixels covering the circle specified
186  * by center and radius.
187  */
188  void index(const SkyPoint *center, double radius, MeshBufNum_t bufNum = DRAW_BUF);
189 
190  /** @short finds the indices of the trixels covering the line segment
191  * connecting p1 and p2.
192  */
193  void index(const SkyPoint *p1, const SkyPoint *p2);
194 
195  /** @short finds the indices of the trixels covering the triangle
196  * specified by vertices: p1, p2, and p3.
197  */
198  void index(const SkyPoint *p1, const SkyPoint *p2, const SkyPoint *p3);
199 
200  /** @short finds the indices of the trixels covering the quadralateral
201  * specified by the vertices: p1, p2, p3, and p4.
202  */
203  void index(const SkyPoint *p1, const SkyPoint *p2, const SkyPoint *p3, const SkyPoint *p4);
204 
205  /** @}*/
206 
207  /** @name IndexHash Routines
208 
209  The follow routines are used to index SkyList data structures. They
210  fill a QHash with the indices of the trixels that cover the data
211  structure. These are all used as callbacks in the LineListIndex
212  subclasses so they can use the same indexing code to index different
213  data structures. See also indexStarLine() above.
214  */
215 
216  /** @{*/
217 
218  /** @short fills a QHash with the trixel indices needed to cover all the
219  * line segments specified in the QVector<SkyPoints*> points.
220  *
221  * @param points the points of the line segment. The debug mode causes extra
222  * info to be printed.
223  */
224  const IndexHash &indexLine(SkyList *points);
225 
226  /** @short as above but allows for skipping the indexing of some of
227  * the points.
228  *
229  * @param points the line segment to be indexed.
230  * @param skip a hash indicating which points to skip
231  * debugging info.
232  */
233  const IndexHash &indexLine(SkyList *points, IndexHash *skip);
234 
235  /** @short fills a QHash with the trixel indices needed to cover the
236  * polygon specified in the QList<SkyPoints*> points. There is no
237  * version with a skip parameter because it does not make sense to
238  * skip some of the edges of a filled polygon.
239  *
240  * @param points the points of the line segment.
241  * The debug mode causes extra info to be printed.
242  */
243  const IndexHash &indexPoly(SkyList *points);
244 
245  /** @short does the same as above but with a QPolygonF as the
246  * container for the points.
247  */
248  const IndexHash &indexPoly(const QPolygonF *points);
249 
250  /** @}*/
251 
252  /** @short Returns the debug level. This is used as a global debug level
253  * for LineListIndex and its subclasses.
254  */
255  int debug() const { return m_debug; }
256 
257  /** @short Sets the debug level.
258  */
259  void debug(int debug) { m_debug = debug; }
260 
261  /** @return the current drawID which gets incremented each time aperture()
262  * is called.
263  */
264  DrawID drawID() const { return m_drawID; }
265 
266  /** @short increments the drawID and returns the new value. This is
267  * useful when you want to use the drawID to ensure you are not
268  * repeating yourself when iterating over the elements of an IndexHash.
269  * It is currently used in LineListIndex::reindex().
270  */
271  int incDrawID() { return ++m_drawID; }
272 
273  /** @short Draws the outline of all the trixels in the specified buffer.
274  * This was very useful during debugging. I don't precess the points
275  * because I mainly use it with the IN_CONSTELL_BUF which is not
276  * precessed. We will probably have buffers serve double and triple
277  * duty in the production code to save space in which case this function
278  * may become less useful.
279  */
280  void draw(QPainter &psky, MeshBufNum_t bufNum = DRAW_BUF);
281 
282  bool inDraw() const { return m_inDraw; }
283  void inDraw(bool inDraw) { m_inDraw = inDraw; }
284 
285  private:
286  DrawID m_drawID;
287  int errLimit { 0 };
288  int m_debug { 0 };
289 
290  IndexHash indexHash;
291  KSNumbers m_KSNumbers;
292 
293  bool m_inDraw { false };
294  static int defaultLevel;
295  static QMap<int, SkyMesh *> pinstances;
296 };
void setKSNumbers(KSNumbers *num)
sets the time for indexing StarObjects and CLines.
Definition: skymesh.h:145
int incDrawID()
increments the drawID and returns the new value.
Definition: skymesh.h:271
Stores dms coordinates for a point in the sky. for converting between coordinate systems.
Definition: skypoint.h:44
void aperture(SkyPoint *center, double radius, MeshBufNum_t bufNum=DRAW_BUF)
finds the set of trixels that cover the circular aperture specified after first performing a reverse ...
Definition: skymesh.cpp:56
void draw(QPainter &psky, MeshBufNum_t bufNum=DRAW_BUF)
Draws the outline of all the trixels in the specified buffer.
Definition: skymesh.cpp:276
const IndexHash & indexStarLine(SkyList *points)
Fills a hash with all the trixels needed to cover all the line segments in the SkyList where each Sky...
Definition: skymesh.cpp:131
Definition: HTMesh.h:56
Store several time-dependent astronomical quantities.
Definition: ksnumbers.h:42
void debug(int debug)
Sets the debug level.
Definition: skymesh.h:259
Trixel indexStar(StarObject *star)
returns the trixel that contains the star at the set time with proper motion taken into account but n...
Definition: skymesh.cpp:79
DrawID drawID() const
Definition: skymesh.h:264
subclass of SkyObject specialized for stars.
Definition: starobject.h:32
int level() const
returns the mesh level.
Definition: HTMesh.h:122
const IndexHash & indexPoly(SkyList *points)
fills a QHash with the trixel indices needed to cover the polygon specified in the QList<SkyPoints*> ...
Definition: skymesh.cpp:208
static SkyMesh * Instance()
returns the default instance of SkyMesh or null if it has not yet been created.
Definition: skymesh.cpp:39
const SkyRegion & skyRegion(const SkyPoint &p1, const SkyPoint &p2)
returns the sky region needed to cover the rectangle defined by two SkyPoints p1 and p2
Definition: skymesh.cpp:312
int debug() const
Returns the debug level.
Definition: skymesh.h:255
const IndexHash & indexLine(SkyList *points)
fills a QHash with the trixel indices needed to cover all the line segments specified in the QVector<...
Definition: skymesh.cpp:126
Trixel index(const SkyPoint *p)
returns the index of the trixel containing p.
Definition: skymesh.cpp:74
static SkyMesh * Create(int level)
creates the single instance of SkyMesh.
Definition: skymesh.cpp:25
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 04:06:21 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.