Kstars

starcorrespondence.h
1 /*
2  SPDX-FileCopyrightText: 2020 Hy Murveit <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include <QObject>
10 #include <QList>
11 #include <QVector>
12 #include <QVector2D>
13 
14 #include "fitsviewer/fitsdata.h"
15 #include "vect.h"
16 
17 /*
18  * This class is useful to track a guide star by noting its position relative to other stars.
19  * It is intended to be resilient to translation, a bit of positional noise, and slight field rotation.
20  * The class is initialized with a set of reference (x,y) positions from stars, where one is
21  * designated a guide star. Then, given a set of new input star positions, it determines a mapping
22  * of the new stars to the references. Some reference stars may not be in the new star group, and
23  * there may be new stars that don't appear in the references. However, the guide star must appear
24  * in both sets for this to be successful.
25  */
26 
27 class StarCorrespondence
28 {
29  public:
30  // Initializes with reference stars.
31  // One of the stars with index guideStar is a special "guide star".
32  StarCorrespondence(const QList<Edge> &stars, int guideStar);
33  StarCorrespondence();
34  ~StarCorrespondence() {}
35 
36  // If the default constructor was called, then initialize must be called with the
37  // reference star positions and the index in stars of the guideStar.
38  void initialize(const QList<Edge> &stars, int guideStar);
39 
40  // Clears the references.
41  void reset();
42 
43  // Associate the input stars with the reference stars.
44  // StarMap[i] will contain the index of a reference star that corresponds to the ith star.
45  // Some input stars may have no reference (starMap->at(i) == -1), and some references may
46  // not correspond to any input stars. There will be no star-reference mapping with
47  // distance longer than maxDistance. If adapt is true, the input positions are used
48  // to incrementally adapt the reference positions.
49  Edge find(const QList<Edge> &stars, double maxDistance, QVector<int> *starMap, bool adapt = true, double minFraction = 0.5);
50 
51  // Returns the number of reference stars.
52  int size() const
53  {
54  return references.size();
55  }
56 
57  // Return a reference to the ith reference star. Caller's responsiblity
58  // to make sure i >= 0 && i < references.size();
59  // Recompute the reference coordinates as we may adapt them.
60  Edge reference(int i) const
61  {
62  Edge star = references[i];
63  star.x = references[guideStarIndex].x + guideStarOffsets[i].x;
64  star.y = references[guideStarIndex].y + guideStarOffsets[i].y;
65  return star;
66  }
67  QVector2D offset(int i) const
68  {
69  QVector2D offset;
70  offset.setX(guideStarOffsets[i].x);
71  offset.setY(guideStarOffsets[i].y);
72  return offset;
73  }
74 
75  int guideStar() const
76  {
77  return guideStarIndex;
78  }
79 
80  void setAllowMissingGuideStar(bool value = true)
81  {
82  allowMissingGuideStar = value;
83  }
84 
85  void setImageSize(int width, int height)
86  {
87  imageWidth = width;
88  imageHeight = height;
89  }
90 
91  int getNumReferencesFound() const
92  {
93  return m_NumReferencesFound;
94  }
95 
96  private:
97  // The Offsets structure is used to keep the positions of the reference stars
98  // relative to the guide star.
99  struct Offsets
100  {
101  double x; // The x position of the star (in pixels), relative to the guide star.
102  double y; // The y position of the star (in pixels), relative to the guide star.
103 
104  Offsets(double x_, double y_) : x(x_), y(y_) {}
105  Offsets() : x(0), y(0) {} // RPi compiler required this constructor.
106  };
107 
108  // Update the reference-star offsets given the new star positions.
109  // The adaption is similar to a 25-sample moving average.
110  void initializeAdaptation();
111  void adaptOffsets(const QList<Edge> &stars, const QVector<int> &starMap);
112 
113  // Utility used by find. Useful for iterating when the guide star is missing.
114  int findInternal(const QList<Edge> &stars, double maxDistance, QVector<int> *starMap,
115  int guideStarIndex, const QVector<Offsets> &offsets,
116  int *numFound, int *numNotFound, double minFraction) const;
117 
118  // Used to when guide star is missing. Creates offsets as if other stars were the guide star.
119  void makeOffsets(const QVector<Offsets> &offsets, QVector<Offsets> *targetOffsets, int targetStar) const;
120 
121  // When the guide star is missing, but star correspondence was successful, use the positions
122  // of the stars that were found to create a virtual guide star--inferring a guide star position
123  // using the offsets from the (unfound) guide star to the stars that were found.
124  // Offsets are offsets that were created for a new "substitude guide star".
125  // StarMap is the map made for that substitude by findInternal().
126  // Offset is the offset from the original guide star to that substitute guide star.
127  Edge inventStarPosition(const QList<Edge> &stars, const QVector<int> &starMap,
128  QVector<Offsets> offsets, Offsets offset) const;
129 
130  // Finds the star closest to x,y. Returns the index in sortedStars.
131  // sortedStars should be sorted in x, which allows for a speedup in search.
132  int findClosestStar(double x, double y, const QList<Edge> sortedStars,
133  double maxDistance, double *distance) const;
134 
135  // The offsets of the reference stars relative to the guide star.
136  QVector<Offsets> guideStarOffsets;
137 
138  // Size stats for the reference stars.
139  QVector<float> referenceSums;
140  QVector<float> referenceNumPixels;
141 
142  QList<Edge> references; // The original reference stars.
143  int guideStarIndex; // The index of the guide star in references.
144  bool initialized = false; // Set to true once the references and guideStar index has been set.
145 
146  // If this is true, it will attempt star correspondence even if the guide star is missing.
147  bool allowMissingGuideStar { false };
148 
149  // IIR filter parameter used to adapt offsets.
150  double alpha;
151 
152  // Setting imageWidth and height can speed up searching for stars in an image
153  // by eliminating positions far outside the image.
154  int imageWidth { 100000000 };
155  int imageHeight { 100000000 };
156 
157  // Number of references found in last call to find().
158  int m_NumReferencesFound { 0 };
159 
160  // A copy of the original reference offsets used so that the values don't move too far.
161  QVector<Offsets> originalGuideStarOffsets;
162 };
163 
void initialize(StandardShortcut id)
void setX(float x)
void setY(float y)
QAction * find(const QObject *recvr, const char *slot, QObject *parent)
KGuiItem reset()
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 21 2023 04:05:29 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.