Kstars

skymesh.h
1/*
2 SPDX-FileCopyrightText: 2007 James B. Bowlin <bowlin@mindspring.com>
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
15class QPainter;
16class QPointF;
17class QPolygonF;
18
19class KSNumbers;
20class SkyPoint;
21class 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
30enum 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
73class 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 */
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};
HTMesh was originally intended to be a simple interface to the HTM library for the KStars project tha...
Definition HTMesh.h:57
int level() const
returns the mesh level.
Definition HTMesh.h:122
There are several time-dependent values used in position calculations, that are not specific to an ob...
Definition ksnumbers.h:43
Provides an interface to the Hierarchical Triangular Mesh (HTM) library written by A.
Definition skymesh.h:74
int incDrawID()
increments the drawID and returns the new value.
Definition skymesh.h:271
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 & 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
static SkyMesh * Instance()
returns the default instance of SkyMesh or null if it has not yet been created.
Definition skymesh.cpp:39
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
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
void debug(int debug)
Sets the debug level.
Definition skymesh.h:259
int debug() const
Returns the debug level.
Definition skymesh.h:255
DrawID drawID() const
Definition skymesh.h:264
static SkyMesh * Create(int level)
creates the single instance of SkyMesh.
Definition skymesh.cpp:25
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 setKSNumbers(KSNumbers *num)
sets the time for indexing StarObjects and CLines.
Definition skymesh.h:145
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
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
Trixel index(const SkyPoint *p)
returns the index of the trixel containing p.
Definition skymesh.cpp:74
The sky coordinates of a point in the sky.
Definition skypoint.h:45
This is a subclass of SkyObject.
Definition starobject.h:33
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 14 2024 11:55:03 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.