Kstars

catalogscomponent.h
1/*
2 SPDX-FileCopyrightText: 2001 Jason Harris <jharris@30doradus.org>
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
20class SkyMesh;
21class 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 */
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 */
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};
A simple container object to hold the minimum information for a Deep Sky Object to be drawn on the sk...
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.
void objectsInArea(QList< SkyObject * > &list, const SkyRegion &region) override
Searches the region(s) and appends the SkyObjects found to the list of sky objects.
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.
void dropCache()
Clear the internal cache and effectively reload all objects from the database.
CatalogObject & insertStaticObject(const CatalogObject &obj)
Insert an object obj into m_static_objects and return a reference to the newly inserted object.
bool selected() override
Wether to show the DSOs.
void draw(SkyPainter *skyp) override
Draws the objects in the currently visible trixels by dynamically loading them from the database.
void resizeCache(const int percentage)
Set the cache size to the new percentage.
Manages the catalog database and provides an interface to provide an interface to query and modify th...
Definition catalogsdb.h:183
ColorMap get_catalog_colors()
int size() const
returns the total number of trixels in the HTM.
Definition HTMesh.h:118
SkyComponent represents an object on the sky map.
SkyComposite * parent()
SkyComposite is a kind of container class for SkyComponent objects.
This is the canvas on which the sky is painted.
Definition skymap.h:54
Provides an interface to the Hierarchical Triangular Mesh (HTM) library written by A.
Definition skymesh.h:74
Provides all necessary information about an object in the sky: its coordinates, name(s),...
Definition skyobject.h:42
Draws things on the sky, without regard to backend.
Definition skypainter.h:40
The sky coordinates of a point in the sky.
Definition skypoint.h:45
void set_size(const size_t size)
Reset the cache size to size.
void clear() noexcept
Clear the cache without changing it's size.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:48:27 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.