SensorUtil Additions (#5406)

* Adds sensor util updates

* Added Body Tests

* Comment out nonworking test

* Fixed Velocity Test

* Added changelog

CHANGELOG.md

@@ -45,6 +45,9 @@ release.
 - Fixed <i>noproj</i> bug where missing shapemodel-related keywords (RayTraceEngine, BulletParts, Tolerance) are dropped when the output label is created. This resulted in the Bullet collision detection engine not being used. Issue: [#5377](https://github.com/USGS-Astrogeology/ISIS3/issues/5377)
 - Fixed ISIS failing to expand env variables with an "_" in them. [#5402](https://github.com/DOI-USGS/ISIS3/pull/5402)
 
+### Added
+- Added 8 new functions to the Sensor Utility Library: Slant Distance, Target Center Distance, Right Ascension Declination, Local Solar Time, Line Resolution, Sample Resolution, Pixel Resolution, and Solar Longitude.
+
 ## [8.1.0] - 2024-01-08
 
 ### Changed

SensorUtilities/include/MathUtils.h

@@ -5,6 +5,8 @@
 
 namespace SensorUtilities {
 
+  const double RAD2DEG = 57.29577951308232087679815481;
+
   /**
    * Structure for a 2-dimensional spherical ground point.
    * Latitude and longitude are in radians.
@@ -29,6 +31,17 @@ namespace SensorUtilities {
   };
 
 
+  /**
+   * Structure for right ascension and declination angles.
+   * Right Ascenion angle in degrees.
+   * Declination angle in degrees.
+   */
+  struct RaDec {
+    double ra;
+    double dec;
+  };
+
+
   /**
    * Structure for a point in an image.
    * The line and sample origin is the upper-left corner at (0, 0).
@@ -50,6 +63,11 @@ namespace SensorUtilities {
     double y;
     double z;
 
+    /**
+     * Default Vec constructor needed for python wrapper.
+     */
+    Vec() {};
+
     /**
      * Construct a vector from 3 values
      */
@@ -68,6 +86,15 @@ namespace SensorUtilities {
     operator std::vector<double>() const;
   };
 
+  /**
+   * Structure for a 3 by 3 Matrix.
+   */
+  struct Matrix {
+    Vec a;
+    Vec b;
+    Vec c;
+  };
+
 
   bool operator==(const GroundPt2D& lhs, const GroundPt2D& rhs);
 
@@ -129,6 +156,16 @@ namespace SensorUtilities {
   double distance(Vec start, Vec stop);
 
 
+  /**
+   * Converts coordinate from radians to degrees
+   * 
+   * @param radianLatLon coordinate in radians
+   * 
+   * @return Coordinate in degrees
+   */
+  GroundPt2D radiansToDegrees(GroundPt2D radianLatLon);
+
+
   /**
    * Convert spherical coordinates to rectangular coordinates
    *
@@ -149,7 +186,49 @@ namespace SensorUtilities {
    */
    GroundPt3D rectToSpherical(Vec rectangular);
 
-}
+
+
+  /**
+   * Computes and returns the ground azimuth between the ground point and
+   * another point of interest, such as the subspacecraft point or the
+   * subsolar point. 
+   *
+   * @param groundPt Ground point latitude and longitude
+   * @param subPt latitude and longitude of a point of interest (e.g. subspacecraft or subsolar)
+   *
+   * @return double The azimuth in degrees
+   */
+  double groundAzimuth(GroundPt2D groundPt, GroundPt2D subPt);
+
+
+  /**
+   * Find the component of a vector that is perpendicular to a second vector.
+   */
+  Vec perpendicularVec(Vec aVec, Vec bVec);
+
 
-#endif
+  /**
+   * Compute the cross product of two Vecs.
+   */
+  Vec crossProduct(Vec aVec, Vec bVec);
+
+
+  /**
+   * Multiply a scalar and a Vec.
+   */
+  Vec scaleVector(Vec vec, double scalar);
+
+
+  /**
+   * Find the unit vector along a Vec.
+   */
+  Vec unitVector(Vec vec);
+
+
+  /**
+   * Multiply a Matrix with a Vec.
+   */
+  Vec matrixVecProduct(Matrix mat, Vec vec);
+}
 
+#endif

SensorUtilities/include/SensorUtilities.h

@@ -9,7 +9,6 @@
 
 namespace SensorUtilities {
 
-
   /**
    * Structure for storing the state of an observer at a specific image coordinate
    * and time.
@@ -85,8 +84,30 @@ namespace SensorUtilities {
        * Get the position for the illumination source at a given time.
        */
       virtual Vec position(double time) = 0;
+      /**
+       * Get the velocity for the illumination source at a given time.
+       */
+      virtual Vec velocity(double time) = 0;
   };
 
+  /**
+   * Interface for the location of the body source.
+   * Implementations of this interface operate in object space.
+   */
+  class Body {
+    public:
+      /**
+       * Get the rotation matrix for the body source at a given time.
+       */
+      virtual std::vector<double> rotation(double time) = 0;
+
+      /**
+       * J2000 position vector to BodyFixed position vector. 
+       * 
+       * @param pos J2000 position to get as a bodyFixed vector   
+      */
+      virtual Vec fixedVector(Vec pos) = 0;
+  };
 
   /**
    * Compute the phase angle at an image point.
@@ -127,6 +148,22 @@ namespace SensorUtilities {
   double illuminationDistance(const ImagePt &imagePoint, Sensor *sensor, Shape *shape, Illuminator *illuminator);
 
 
+  /**
+   * Return the distance between the spacecraft and surface point.
+   *
+   * @return the distance in meters
+   */
+  double slantDistance(ImagePt imagePoint, Sensor *sensor, Shape *shape);
+
+
+  /**
+   * Return the distance between the spacecraft and center point of a body.
+   *
+   * @return the distance in meters
+   */
+  double targetCenterDistance(ImagePt &imagePoint, Sensor *sensor, Body *body);
+
+
   /**
    * Compute the latitude and longitude on the body below the sensor
    * when an image coordinate was observed.
@@ -173,7 +210,63 @@ namespace SensorUtilities {
    * @return The local radius in meters
    */
   double localRadius(const GroundPt2D &groundPt, Shape *shape, double maxRadius=1e9);
-}
 
-#endif
 
+  /**
+   * Computes the right ascension angle (sky longitude) and declination angle (sky latitude).
+   * 
+   * @returns right ascension angle in degrees and declination angle in degrees.
+   */
+  RaDec rightAscensionDeclination(ImagePt &imagePoint, Sensor *sensor);
+
+
+  /**
+   * Computes the local solar time in hours
+   * 
+   * @param imagePoint The line and sample
+   * @param sensor The sensor model used to calculate ground coordinates
+   * @param shape The shape to compute the local radius of
+   * @param illuminator The illumination model
+   * 
+   * @returns local solar time in hours
+   */
+  double localSolarTime(ImagePt &imagePoint, Sensor *sensor, Shape *shape, Illuminator *illuminator);
+
+  /**
+   * @brief Returns the line resolution at the current position in meters.
+   *
+   * @return @b double The line resolution
+   */
+  double lineResolution(const ImagePt &imagePoint, Sensor *sensor, Shape *shape, double focalLength, double pixelPitch, double lineScaleFactor=1);
+
+
+  /**
+   * @brief Returns the sample resolution at the current position in meters.
+   *
+   * @return @b double The sample resolution
+   */ 
+  double sampleResolution(const ImagePt &imagePoint, Sensor *sensor, Shape *shape, double focalLength, double pixelPitch, double sampleScaleFactor=1);
+
+
+  /**
+   * @brief Returns the pixel resolution at the current position in meters/pixel.
+   * 
+   * @return @b double The pixel resolution
+   */
+  double pixelResolution(const ImagePt &imagePoint, Sensor *sensor, Shape *shape, double focalLength, double pixelPitch, double lineScaleFactor=1, double sampleScaleFactor=1);
+
+
+  /**
+   * 
+   * Computes the solar longitude for the given ephemeris time.
+   * 
+   * @param imagePoint The line and sample
+   * @param sensor The sensor model used to calculate ground coordinates
+   * @param illuminator The illumination model
+   * @param body The target body
+   * 
+   * @returns solar longitude in degrees.
+   */
+  double solarLongitude(ImagePt &imagePoint, Sensor *sensor, Illuminator *illuminator, Body *body);
+}
+#endif