File indexing completed on 2024-04-28 15:09:04

 /*
     SPDX-FileCopyrightText: 2021 Hy Murveit <hy@murveit.com>
 
     SPDX-License-Identifier: GPL-2.0-or-later
 */
 
 #pragma once
 
 #include <dms.h>
 #include <skypoint.h>
 
 class FITSData;
 class TestPolarAlign;
 
 /*********************************************************************
  Polar alignment support class.  Note, the telescope can be pointing anywhere.
  It doesn't need to point at the pole.
 
  Use this class as follows:
  1) Construct with the geo information.
         PolarAlign polarAlign(geoLocation);
  2) Start the polar align procedure. Capture, solve and add wcs from the
     solve to the FITSData image. Then:
         polarAlign.addPoint(image);
  3) Rotate the mount in RA ~30 degrees (could be less or more) east (or west)
     and capture, solve and add wcs from the solve to the new image. Then:
         polarAlign.addPoint(image);
  4) Rotate the mount in RA another ~30 degrees east (or west)
     and capture, solve and add wcs from the solve to the new image. Then:
         polarAlign.addPoint(image);
  5) Find the mount's axis of rotation as follows:
         if (!polarAlign.findAxis())
           error();
  6) Compute the azimuth and altitude offset for the mount.
         double altitudeError = axisAlt - latitudeDegrees;
         double azimuthError = axisAz - 0;
  7) Compute the overall error
         dms polarError(hypot(azimuthError, altitudeError));
 
 Using the "move star" correction scheme:
 
  8a) Compute a target correction
         int correctedX, correctedY;
         if (!polarAlign.findCorrectedPixel(
                imageData, x, y, altitudeError, azimuthError, &correctedX, &correctedY))
           error();
  9a) The user uses the GEM azimuth and altitude adjustments to move the
     object at position x,y in the image to position correctedX, correctedY.
 
 Using the plate solve correction scheme:
 
  8b) Compute the remaining axis error (after partial correction)
          SkyPoint coords, solution;
          coords = [coordinates from plate-solving a refresh image]
          // The signs of the error indicate the correction direction
          processRefreshCoords(coords, currentTime, &azError, &altError);
  9b) The user uses the GEM azimuth and altitude adjustments to move the telescope.
       positive altitude error: reduce altitide.
       positive azimuth error: point telescope more to the left.
  *********************************************************************/
 
 class PolarAlign
 {
     public:
 
         // The polealignment scheme requires the GeoLocation to operate properly.
         // Certain aspects can be tested without it.
         PolarAlign(const GeoLocation *geo = nullptr);
 
         // Add a sample point.
         bool addPoint(const QSharedPointer<FITSData> &image);
 
         // Returns the i-th point (zero based).
         const SkyPoint getPoint(int index)
         {
             if (index >= 0 && index < points.size())
                 return points[index];
             return SkyPoint();
         }
 
         // Finds the mount's axis of rotation. Three points must have been added.
         // Returns false if the axis can't be found.
         bool findAxis();
 
         // Returns the image coordinate that pixel x,y should be moved to to correct
         // the mount's axis. Image is usually the 3rd PAA image. x,y are image coordinates.
         // 3 Points must have been added and findAxis() must have been called.
         // Uses the axis determined by findAxis().  Returns correctedX and correctedY,
         // the target position that the x,y pixel should move to.
         bool findCorrectedPixel(const QSharedPointer<FITSData> &image, const QPointF &pixel,
                                 QPointF *corrected, bool altOnly = false);
 
         // Returns the mount's azimuth and altitude error given the known geographic location
         // and the azimuth center and altitude center computed in findAxis().
         void calculateAzAltError(double *azError, double *altError) const;
 
         // Given the current axis, fill in azError and altError with the polar alignment
         // error, if a star at location pixel were move in the camera view to pixel2.
         // image would be the 3rd PAA image.
         // Returns false if the paa error couldn't be computer.
         bool pixelError(const QSharedPointer<FITSData> &image, const QPointF &pixel, const QPointF &pixel2,
                         double *azError, double *altError);
 
         /// reset starts the process over, removing the points.
         void reset();
 
         // Returns the mount's axis--for debugging.
         void getAxis(double *azAxis, double *altAxis) const;
 
         // This is not required, and is a hint as to how far the pixelError method should search
         // for a solution. The suggestion may be ignored if it is too large or small, but in
         // general this should be a degree or so larger than the polar alignment error in degrees.
         void setMaxPixelSearchRange(double degrees);
 
         // Compute the remaining polar-alignment azimuth and altitude error from a new image's coordinates
         // as compared with the coordinates from the last polar-align measurement image.
         // The differences between the two coordinates is a measure of the rotation that has been
         // applied during the polar-align correction phase.
         bool processRefreshCoords(const SkyPoint &coords, const KStarsDateTime &time,
                                   double *azError, double *altError,
                                   double *azAdjustment = nullptr, double *altAdjustment = nullptr) const;
 
         // Find the skypoints where the telescope needs to point (rotated there by adjusting az and alt)
         // in order for the mount to be properly polar aligned.
         bool refreshSolution(SkyPoint *solution, SkyPoint *altOnlySolution) const;
 
     private:
         // returns true in the northern hemisphere.
         // if no geo location available, defaults to northern.
         bool northernHemisphere() const;
 
         // These internal methods find the pixel with the desired azimuth and altitude.
         bool findAzAlt(const QSharedPointer<FITSData> &image, double azimuth, double altitude, QPointF *pixel) const;
 
         // Does the necessary processing so that azimuth and altitude values
         // can be retrieved for the x,y pixel in image.
         bool prepareAzAlt(const QSharedPointer<FITSData> &image, const QPointF &pixel, SkyPoint *point) const;
 
 
         // Internal utility used by the external findCorrectedPixel and by pixelError().
         // Similar args as the public findCorrectedPixel().
         bool findCorrectedPixel(const QSharedPointer<FITSData> &image, const QPointF &pixel,
                                 QPointF *corrected, double azError, double altError);
 
         // Internal utility used by the public pixelError, which iterates at different
         // resolutions passed in to this method. As the resoltion can be coarse, actualPixel
         // is the one used (as opposed to pixel2) for the error returned.
         void pixelError(const QSharedPointer<FITSData> &image, const QPointF &pixel, const QPointF &pixel2,
                         double minAz, double maxAz, double azInc,
                         double minAlt, double maxAlt, double altInc,
                         double *azError, double *altError, QPointF *actualPixel);
 
         // These three positions are used to estimate the polar alignment error.
         QVector<SkyPoint> points;
         QVector<KStarsDateTime> times;
 
         // The geographic location used to compute azimuth and altitude.
         const GeoLocation *geoLocation;
 
         // Values set by the last call to findAxis() that correspond to the mount's axis.
         double azimuthCenter { 0 };
         double altitudeCenter { 0 };
 
         // Constrains the search for the correction pixel. Units are degrees.
         double maxPixelSearchRange { 2 };
 
         friend TestPolarAlign;
 };