Add eclipse checking in spacecraftLocation

Author: Mark2000

docs/source/Support/bskReleaseNotes.rst

@@ -35,7 +35,7 @@ Version |release|
 - Deprecated :ref:`SpacecraftSystem`.  It was never completed and we have other ways to connect spacecraft components
 - Allow event conditions and effects to be defined by functions. This is preferred over the old string-based method, as it
   enables the use of arbitrary packages and objects in events and allows for event code to be parsed by IDE tools.
-- Add a sun message input and ``theta_solar`` threshold to :ref:`SpacecraftLocation`.
+- Add a sun message input and ``theta_solar`` threshold to :ref:`SpacecraftLocation`. Also supports including an eclipse message to determine illumination.
 
 
 Version 2.7.0 (April 20, 2025)

src/architecture/msgPayloadDefC/EclipseMsgPayload.h

@@ -23,7 +23,7 @@
 
 //!@brief Eclipse shadow factor message definition.
 typedef struct {
-    double shadowFactor;       //!< Proportion of shadowing due to eclipse 
+    double shadowFactor;       //!< Proportion of illumination due to eclipse. 0 = fully shadowed, 1 = fully illuminated.
 }EclipseMsgPayload;
 
 

src/simulation/environment/spacecraftLocation/spacecraftLocation.cpp

@@ -36,6 +36,7 @@ SpacecraftLocation::SpacecraftLocation()
     this->aHat_B.fill(0.0);
     this->theta = -1.0;
     this->theta_solar = -1.0;
+    this->min_shadow_factor = -1.0;
 
     this->planetState = this->planetInMsg.zeroMsgPayload;
     this->planetState.J20002Pfix[0][0] = 1;
@@ -85,7 +86,7 @@ SpacecraftLocation::Reset(uint64_t CurrentSimNanos)
     }
 
     if (this->theta_solar >= 0.0) {
-        if (this->aHat_B.norm() < 0.001){
+        if (this->aHat_B.norm() < 0.001) {
             bskLogger.bskLog(BSK_ERROR, "SpacecraftLocation must set aHat_B if you specify theta_solar");
         }
     }
@@ -152,11 +153,20 @@ SpacecraftLocation::ReadMessages()
         sunRead = this->sunInMsg.isWritten();
         this->sunData = this->sunInMsg();
     } else {
-        sunRead = false;
         this->r_HN_N.setZero();
     }
 
-    return (planetRead && scRead && sunRead);
+    //! - Zero eclipse information
+    this->eclipseInMsgData = eclipseInMsg.zeroMsgPayload;
+
+    bool eclipseRead = true;
+    if (this->eclipseInMsg.isLinked()) {
+        eclipseRead = this->eclipseInMsg.isWritten();
+        this->eclipseInMsgData = this->eclipseInMsg();
+    }
+
+
+    return (planetRead && scRead && sunRead && eclipseRead);
 }
 
 /*! write module messages
@@ -269,6 +279,14 @@ SpacecraftLocation::computeAccess()
                     this->accessMsgBuffer.at(c).hasIllumination = 0;
                 }
             }
+
+            // Check if eclipse is valid
+            if (this->eclipseInMsg.isLinked() and this->min_shadow_factor > 0.0) {
+                if (eclipseInMsgData.shadowFactor < this->min_shadow_factor) {
+                    this->accessMsgBuffer.at(c).hasAccess = 0;
+                    this->accessMsgBuffer.at(c).hasIllumination = 0;
+                }
+            }
         }
     }
 }

src/simulation/environment/spacecraftLocation/spacecraftLocation.h

@@ -27,6 +27,7 @@
 
 #include "architecture/messaging/messaging.h"
 #include "architecture/msgPayloadDefC/AccessMsgPayload.h"
+#include "architecture/msgPayloadDefC/EclipseMsgPayload.h"
 #include "architecture/msgPayloadDefC/SCStatesMsgPayload.h"
 #include "architecture/msgPayloadDefC/SpicePlanetStateMsgPayload.h"
 
@@ -55,10 +56,12 @@ class SpacecraftLocation : public SysModel
     Eigen::Vector3d aHat_B; //!< [] (optional) unit direction vector of the sensor/communication boresight axis
     double theta;           //!< [r] (optional) sensor/communication half-cone angle, must be set if shat_B is specified
     double theta_solar;     //!< [r] (optional) illumination half-cone angle, treating aHat_B as the surface normal
+    double min_shadow_factor; //!< [] (optional) minimum amount of illumination due to eclipse necessary to observe
 
     ReadFunctor<SCStatesMsgPayload> primaryScStateInMsg;        //!< primary spacecraft input message
-    ReadFunctor<SpicePlanetStateMsgPayload> planetInMsg;        //!< planet state input message
-    ReadFunctor<SpicePlanetStateMsgPayload> sunInMsg;           //!< [-] sun data input message
+    ReadFunctor<SpicePlanetStateMsgPayload> planetInMsg;        //!< (optional) planet state input message
+    ReadFunctor<SpicePlanetStateMsgPayload> sunInMsg;           //!< (optional) sun data input message
+    ReadFunctor<EclipseMsgPayload> eclipseInMsg;                //!< (optional) eclipse input message
     std::vector<Message<AccessMsgPayload>*> accessOutMsgs;      //!< vector of ground location access messages
     std::vector<ReadFunctor<SCStatesMsgPayload>> scStateInMsgs; //!< vector of other sc state input messages
     Eigen::Vector3d
@@ -72,6 +75,7 @@ class SpacecraftLocation : public SysModel
     SCStatesMsgPayload primaryScStatesBuffer;       //!< buffer of primary spacecraft states
     SpicePlanetStateMsgPayload planetState;         //!< buffer of planet data
     SpicePlanetStateMsgPayload sunData;             //!< buffer of sun data
+    EclipseMsgPayload eclipseInMsgData;             //!< buffer of eclipse data
 
     Eigen::Matrix3d dcm_PN; //!< Rotation matrix from inertial frame N to planet-centered to planet-fixed frame P
     Eigen::Vector3d r_PN_N; //!< [m] Planet to inertial frame origin vector.

src/simulation/environment/spacecraftLocation/spacecraftLocation.i

@@ -40,6 +40,8 @@ struct SpicePlanetStateMsg_C;
 struct SCStatesMsg_C;
 %include "architecture/msgPayloadDefC/AccessMsgPayload.h"
 struct AccessMsg_C;
+%include "architecture/msgPayloadDefC/EclipseMsgPayload.h"
+struct EclipseMsg_C;
 
 %pythoncode %{
 import sys

src/simulation/environment/spacecraftLocation/spacecraftLocation.rst

@@ -38,7 +38,10 @@ provides information on what this message is used for.
       - vector of other spacecraft state input messages.  These are set through ``addSpacecraftToModel()``
     * - sunInMsg
       - :ref:`SpicePlanetStateMsgPayload`
-      - (optional) sun state input message. Used for illumination checking if the message is connected and `theta_solar` is set.
+      - (optional) sun state input message. Used for illumination checking if the message is connected and ``theta_solar`` is set.
+    * - eclipseInMsg
+      - :ref:`EclipseMsgPayload`
+      - (optional) eclipse input message. Used for illumination checking if the message is connected and ``min_shadow_factor`` is set.
     * - accessOutMsgs
       - :ref:`AccessMsgPayload`
       - output vector of ground location access messages
@@ -120,6 +123,8 @@ If the ``sunInMsg`` is connected and :math:`\theta_{\text{solar,max}}` is set, t
 .. math::
     \arccos \left( \hat{\bf a} \cdot \hat{\bf s} \right) = \theta_{\text{solar}} \le \theta_{\text{solar,max}}
 
+If an eclipse message is connected and ``min_shadow_factor`` is set, the module will also check that the shadow factor is above this threshold.
+
 User Guide
 ----------
 A new instance of ``spacecraftLocation``, alongside necessary user-supplied parameters, can be created by calling: