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 */
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 * @param useJ2000 if set to false, the method uses ra() and dec() instead
188 */
189 void index(const SkyPoint *center, double radius, MeshBufNum_t bufNum = DRAW_BUF, const bool useJ2000 = true);
190
191 /** @short finds the indices of the trixels covering the line segment
192 * connecting p1 and p2.
193 */
194 void index(const SkyPoint *p1, const SkyPoint *p2);
195
196 /** @short finds the indices of the trixels covering the triangle
197 * specified by vertices: p1, p2, and p3.
198 */
199 void index(const SkyPoint *p1, const SkyPoint *p2, const SkyPoint *p3);
200
201 /** @short finds the indices of the trixels covering the quadralateral
202 * specified by the vertices: p1, p2, p3, and p4.
203 */
204 void index(const SkyPoint *p1, const SkyPoint *p2, const SkyPoint *p3, const SkyPoint *p4);
205
206 /** @}*/
207
208 /** @name IndexHash Routines
209
210 The follow routines are used to index SkyList data structures. They
211 fill a QHash with the indices of the trixels that cover the data
212 structure. These are all used as callbacks in the LineListIndex
213 subclasses so they can use the same indexing code to index different
214 data structures. See also indexStarLine() above.
215 */
216
217 /** @{*/
218
219 /** @short fills a QHash with the trixel indices needed to cover all the
220 * line segments specified in the QVector<SkyPoints*> points.
221 *
222 * @param points the points of the line segment. The debug mode causes extra
223 * info to be printed.
224 */
225 const IndexHash &indexLine(SkyList *points);
226
227 /** @short as above but allows for skipping the indexing of some of
228 * the points.
229 *
230 * @param points the line segment to be indexed.
231 * @param skip a hash indicating which points to skip
232 * debugging info.
233 */
234 const IndexHash &indexLine(SkyList *points, IndexHash *skip);
235
236 /** @short fills a QHash with the trixel indices needed to cover the
237 * polygon specified in the QList<SkyPoints*> points. There is no
238 * version with a skip parameter because it does not make sense to
239 * skip some of the edges of a filled polygon.
240 *
241 * @param points the points of the line segment.
242 * The debug mode causes extra info to be printed.
243 */
244 const IndexHash &indexPoly(SkyList *points);
245
246 /** @short does the same as above but with a QPolygonF as the
247 * container for the points.
248 */
249 const IndexHash &indexPoly(const QPolygonF *points);
250
251 /** @}*/
252
253 /** @short Returns the debug level. This is used as a global debug level
254 * for LineListIndex and its subclasses.
255 */
256 int debug() const { return m_debug; }
257
258 /** @short Sets the debug level.
259 */
260 void debug(int debug) { m_debug = debug; }
261
262 /** @return the current drawID which gets incremented each time aperture()
263 * is called.
264 */
265 DrawID drawID() const { return m_drawID; }
266
267 /** @short increments the drawID and returns the new value. This is
268 * useful when you want to use the drawID to ensure you are not
269 * repeating yourself when iterating over the elements of an IndexHash.
270 * It is currently used in LineListIndex::reindex().
271 */
272 int incDrawID() { return ++m_drawID; }
273
274 /** @short Draws the outline of all the trixels in the specified buffer.
275 * This was very useful during debugging. I don't precess the points
276 * because I mainly use it with the IN_CONSTELL_BUF which is not
277 * precessed. We will probably have buffers serve double and triple
278 * duty in the production code to save space in which case this function
279 * may become less useful.
280 */
281 void draw(QPainter &psky, MeshBufNum_t bufNum = DRAW_BUF);
282
283 bool inDraw() const { return m_inDraw; }
284 void inDraw(bool inDraw) { m_inDraw = inDraw; }
285
286 private:
287 DrawID m_drawID;
288 int errLimit { 0 };
289 int m_debug { 0 };
290
291 IndexHash indexHash;
292 KSNumbers m_KSNumbers;
293
294 bool m_inDraw { false };
295 static int defaultLevel;
296 static QMap<int, SkyMesh *> pinstances;
297};
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:272
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:260
int debug() const
Returns the debug level.
Definition skymesh.h:256
DrawID drawID() const
Definition skymesh.h:265
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 Mon Nov 4 2024 16:38:44 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.