Kstars

catalogscomponent.h
1 /*
2  SPDX-FileCopyrightText: 2001 Jason Harris <[email protected]>
3  SPDX-FileCopyrightText: 2021 Valentin Boettcher <hiro at protagon.space; @hiro98:tchncs.de>
4 
5  SPDX-License-Identifier: GPL-2.0-or-later
6 */
7 
8 #pragma once
9 
10 #include "skycomponent.h"
11 #include "catalogsdb.h"
12 #include "catalogobject.h"
13 #include "skymesh.h"
14 #include "trixelcache.h"
15 #include "Options.h"
16 
17 #include "polyfills/qstring_hash.h"
18 #include <unordered_map>
19 
20 class SkyMesh;
21 class SkyMap;
22 
23 /**
24  * \brief Represents objects loaded from an sqlite backed, trixel
25  * indexed catalog.
26  *
27  * The component doesn't follow the traditional list approach and
28  * loads it's skyobjects into an LRU cache (`TrixelCache`). For
29  * puproses of compatiblility with object search etc. some of the
30  * brightest objects are loaded into `m_static_objects` and registered
31  * within the component system. Furthermore, if some part of the code
32  * demands a pointer to a CatalogObject, it will be allocated into
33  * `m_static_objects` on demand.
34  *
35  * If you want to access DSOs in _new_ code you should use a local
36  * instance of `CatalogsDB::DBManager` instead and call `dropCache` if
37  * necessary.
38  *
39  * \sa CatalogsDB::DBManager
40  */
42 {
43  public:
44  using ObjectList = std::vector<CatalogObject>;
45 
46  /**
47  * Constructs the Catalogscomponent with a \p parent and a
48  * database file under the path \p db_filename. If \p load_ngc is
49  * specified, an attempt is made to load the default catalog from
50  * the default location into the db.
51  *
52  * The lru cache for the objects will be initialized to a capacity
53  * configurable by Options::dSOCachePercentage.
54  */
55  explicit CatalogsComponent(SkyComposite *parent, const QString &db_filename,
56  bool load_default = false);
57 
58  ~CatalogsComponent() override = default;
59 
60  /**
61  * Draws the objects in the currently visible trixels by
62  * dynamically loading them from the database.
63  */
64  void draw(SkyPainter *skyp) override;
65 
66  /**
67  * Set the cache size to the new \p percentage.
68  *
69  * The cache stores the objects of a certain \p percentage of all
70  * trixels. Setting `percentage = 100` short circuits the cache and loads
71  * all the objects into memory. This is reasonable for catalog sizes up
72  * to `10_000` objects.
73  */
74  void resizeCache(const int percentage)
75  {
76  m_mainCache.set_size(calculateCacheSize(percentage));
77  m_unknownMagCache.set_size(calculateCacheSize(percentage));
78  };
79 
80  /**
81  * \short Search the underlying database for an object with the \p
82  * name. \sa `CatalogsDB::DBManager::find_object_by_name` for
83  * details.
84  *
85  * If multiple objects match, the one with the hightest magnitude is
86  * returned.
87  *
88  * \return a pointer to the SkyObject whose name matches the argument, or
89  * a nullptr pointer if no match was found. (Due to way KStars works)
90  */
91  SkyObject *findByName(const QString &name, bool exact = true) override;
92 
93  void objectsInArea(QList<SkyObject *> &list, const SkyRegion &region) override;
94 
95  SkyObject *objectNearest(SkyPoint *p, double &maxrad) override;
96 
97  /**
98  * Insert an object \p obj into `m_static_objects` and return a
99  * reference to the newly inserted object. If the object is
100  * already present in the list, return a reference to
101  * that. Furthermore the object will be updated
102  * (`CatalogObject::JITupdate`) and inserted into the parent's
103  * `objectLists`.
104  */
106 
107  /**
108  * Clear the internal cache and effectively reload all objects
109  * from the database.
110  */
111  void dropCache()
112  {
113  m_mainCache.clear();
114  m_unknownMagCache.clear();
115  m_catalog_colors = m_db_manager.get_catalog_colors();
116  };
117 
118  /**
119  * Wether to show the DSOs.
120  */
121  bool selected() override
122  {
123  return Options::showDeepSky();
124  };
125 
126  private:
127  /**
128  * The database interface for the catalog.
129  */
130  CatalogsDB::DBManager m_db_manager;
131 
132  /**
133  * A pointer to a SkyMesh of the appropriate level.
134  *
135  * @note The use of a pointer here is a legacy from the
136  * SkyComponent implementation.
137  */
138  SkyMesh *m_skyMesh;
139 
140  /**
141  * The main container for the currently loaded objects.
142  */
143  ObjectList m_objects;
144 
145  /**
146  * The cache holding the DSOs of known magnitude
147  */
148  TrixelCache<ObjectList> m_mainCache;
149 
150  /**
151  * The cache holding the DSOs of unknown magnitude
152  */
153  TrixelCache<ObjectList> m_unknownMagCache;
154 
155  /**
156  * A trixel indexed map of lists containing manually loaded
157  * `CatalogObject`s.
158  *
159  * Because some `KStars` internal code requires pointers to SkyObjects
160  * and this component doesn't hold its objects, we have create a space to
161  * to own the objets that we create in methods like `findByName`. Thus it
162  * is expected that this list won't hold many objects and doesn't have to
163  * be emptied at runtime. The objects in this map are not drawn and have
164  * to be updated manually.
165  *
166  * __No objects should ever be removed from this list, as references and
167  * pointers to list members are required to remain valid.__
168  *
169  * __In new code, a local instance of `CatalogsDB::DBManager` should be
170  * used when access to CatalogObjects is required. Call `dropCache` if
171  * required.__
172  */
173  std::unordered_map<Trixel, CatalogsDB::CatalogObjectList> m_static_objects;
174 
175  /**
176  * A cache for catalog colors.
177  */
178  CatalogsDB::ColorMap m_catalog_colors;
179 
180  //@{
181  /** Helpers */
182 
183  void updateSkyMesh(SkyMap &map, MeshBufNum_t buf = DRAW_BUF);
184  size_t calculateCacheSize(const unsigned int percentage)
185  {
186  return m_skyMesh->size() * percentage / 100.f;
187  }
188 
189  /**
190  * Try importing the old skycomponents database.
191  */
192  void tryImportSkyComponents();
193 
194  //@}
195 };
Stores dms coordinates for a point in the sky. for converting between coordinate systems.
Definition: skypoint.h:44
ColorMap get_catalog_colors()
Manages the catalog database and provides an interface to provide an interface to query and modify th...
Definition: catalogsdb.h:181
void clear() noexcept
Clear the cache without changing it's size.
Definition: trixelcache.h:187
SkyComposite * parent()
Definition: skycomponent.h:137
CatalogsComponent(SkyComposite *parent, const QString &db_filename, bool load_default=false)
Constructs the Catalogscomponent with a parent and a database file under the path db_filename.
bool selected() override
Wether to show the DSOs.
CatalogObject & insertStaticObject(const CatalogObject &obj)
Insert an object obj into m_static_objects and return a reference to the newly inserted object.
int size() const
returns the total number of trixels in the HTM.
Definition: HTMesh.h:118
void draw(SkyPainter *skyp) override
Draws the objects in the currently visible trixels by dynamically loading them from the database.
Draws things on the sky, without regard to backend.
Definition: skypainter.h:38
void set_size(const size_t size)
Reset the cache size to size.
Definition: trixelcache.h:155
void resizeCache(const int percentage)
Set the cache size to the new percentage.
Canvas widget for displaying the sky bitmap; also handles user interaction events.
Definition: skymap.h:53
void objectsInArea(QList< SkyObject * > &list, const SkyRegion &region) override
Searches the region(s) and appends the SkyObjects found to the list of sky objects.
Represents objects loaded from an sqlite backed, trixel indexed catalog.
SkyObject * objectNearest(SkyPoint *p, double &maxrad) override
Find the SkyObject nearest the given SkyPoint.
SkyObject * findByName(const QString &name, bool exact=true) override
Search the underlying database for an object with the name.
A simple container object to hold the minimum information for a Deep Sky Object to be drawn on the sk...
Definition: catalogobject.h:40
void dropCache()
Clear the internal cache and effectively reload all objects from the database.
Information about an object in the sky.
Definition: skyobject.h:41
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 04:02:20 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.