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 */
41class CatalogsComponent : public SkyComponent
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 */
105 CatalogObject &insertStaticObject(const CatalogObject &obj);
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};
CatalogObject
A simple container object to hold the minimum information for a Deep Sky Object to be drawn on the sk...
Definition catalogobject.h:41
CatalogsComponent
Represents objects loaded from an sqlite backed, trixel indexed catalog.
Definition catalogscomponent.h:42
CatalogsComponent::objectNearest
SkyObject * objectNearest(SkyPoint *p, double &maxrad) override
Find the SkyObject nearest the given SkyPoint.
Definition catalogscomponent.cpp:375
CatalogsComponent::findByName
SkyObject * findByName(const QString &name, bool exact=true) override
Search the underlying database for an object with the name.
Definition catalogscomponent.cpp:334
CatalogsComponent::objectsInArea
void objectsInArea(QList< SkyObject * > &list, const SkyRegion &region) override
Searches the region(s) and appends the SkyObjects found to the list of sky objects.
Definition catalogscomponent.cpp:346
CatalogsComponent::CatalogsComponent
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.
Definition catalogscomponent.cpp:29
CatalogsComponent::dropCache
void dropCache()
Clear the internal cache and effectively reload all objects from the database.
Definition catalogscomponent.h:111
CatalogsComponent::insertStaticObject
CatalogObject & insertStaticObject(const CatalogObject &obj)
Insert an object obj into m_static_objects and return a reference to the newly inserted object.
Definition catalogscomponent.cpp:300
CatalogsComponent::selected
bool selected() override
Wether to show the DSOs.
Definition catalogscomponent.h:121
CatalogsComponent::draw
void draw(SkyPainter *skyp) override
Draws the objects in the currently visible trixels by dynamically loading them from the database.
Definition catalogscomponent.cpp:69
CatalogsComponent::resizeCache
void resizeCache(const int percentage)
Set the cache size to the new percentage.
Definition catalogscomponent.h:74
CatalogsDB::DBManager
Manages the catalog database and provides an interface to provide an interface to query and modify th...
Definition catalogsdb.h:183
CatalogsDB::DBManager::get_catalog_colors
ColorMap get_catalog_colors()
Definition catalogsdb.cpp:1177
HTMesh::size
int size() const
returns the total number of trixels in the HTM.
Definition HTMesh.h:118
SkyComponent
SkyComponent represents an object on the sky map.
Definition skycomponent.h:96
SkyComponent::parent
SkyComposite * parent()
Definition skycomponent.h:137
SkyComposite
SkyComposite is a kind of container class for SkyComponent objects.
Definition skycomposite.h:30
SkyMap
This is the canvas on which the sky is painted.
Definition skymap.h:54
SkyMesh
Provides an interface to the Hierarchical Triangular Mesh (HTM) library written by A.
Definition skymesh.h:74
SkyObject
Provides all necessary information about an object in the sky: its coordinates, name(s),...
Definition skyobject.h:42
SkyPainter
Draws things on the sky, without regard to backend.
Definition skypainter.h:40
SkyPoint
The sky coordinates of a point in the sky.
Definition skypoint.h:45
TrixelCache
A simple integer indexed elastically cached wrapper around std::vector to hold container types conten...
Definition trixelcache.h:60
TrixelCache::set_size
void set_size(const size_t size)
Reset the cache size to size.
Definition trixelcache.h:155
TrixelCache::clear
void clear() noexcept
Clear the cache without changing it's size.
Definition trixelcache.h:187
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 13 2024 11:47:12 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.