Module: locationPointing
Executive Summary
This module computes attitude guidance and reference messages for two imaging modes:
Location Pointing Mode: An attitude guidance message is generated to make a specified spacecraft pointing vector point at an inertial target location. This location can be on a planet if this module is connected with GroundStateMsgPayload, on a celestial object center using EphemerisMsgPayload, or on a spacecraft using NavTransMsgPayload.
Strip Imaging Mode: When connected to a StripStateMsgPayload message, the module first points the body-fixed pointing vector at the moving target on the strip centerline. It then performs an additional rotation about this pointing direction so that a secondary body-fixed vector becomes orthogonal to the strip scanning direction. This secondary rotation is applied only if the pointing vector and the strip scanning direction fulfill the non-collinearity constraint.
Message Connection Descriptions
The following table lists all the module input and output messages. The module msg connection is set by the user from python. The msg type contains a link to the message structure definition, while the description provides information on what this message is used for.
Msg Variable Name |
Msg Type |
Description |
|---|---|---|
scAttInMsg |
input msg with inertial spacecraft attitude states |
|
scTransInMsg |
input msg with inertial spacecraft translational states |
|
locationInMsg |
input msg containing the inertial point location of interest |
|
locationstripInMsg |
(alternative) input msg from Module: stripLocation containing the inertial position and velocity of the current strip target point |
|
celBodyInMsg |
(alternative) input msg containing the inertial point location of a celestial body of interest |
|
scTargetInMsg |
(alternative) input msg with inertial target spacecraft translational states |
|
attGuidOutMsg |
output message with the attitude guidance |
|
attRefOutMsg |
output message with the attitude reference |
Detailed Module Description
Location Pointing Mode
The inertial location of interest w.r.t the inertial origin is given by \({\bf r}_{L/N}\) and can be either extracted from locationInMsg when
a location on a planet is provided, celBodyInMsg when a celestial body’s ephemeris location is provided (for pointing
at the Sun or the Earth), scTargetInMsg when pointing at another spacecraft, or locationstripInMsg when performing
strip imaging.
The vector pointing from the satellite location \({\bf r}_{S/N}\) to this location is then
Let \(\hat{\bf r}_{L/S}\) be the normalized heading vector to this location.
The unit vector \(\hat{\bf p}_B\) is a body-fixed vector and denotes the body axis which is to point towards the desired location \(L\). Thus this mode performs a 2-degree of freedom attitude guidance and control solution.
The eigen-axis to rotate \(\hat{\bf p}_B\) towards \(\hat{\bf r}_{L/S}\) is given by
The principle rotation angle \(\phi\) is
The attitude tracking error \({\pmb\sigma}_{B/R}\) is then given by
The reference attitude \({\pmb\sigma}_{R/N}\) is obtained by composing the spacecraft attitude \({\pmb\sigma}_{B/N}\) with the tracking error:
where \(\oplus\) denotes the MRP addition operator.
When the module is not in strip imaging mode the outputs are set directly:
Strip Imaging Mode
When the locationstripInMsg input from the Module: stripLocation module is connected, the module enters
strip imaging mode. The StripStateMsgPayload message provides the inertial position w.r.t to the inertial origin
\({\bf r}_{L/N}\) and the inertial velocity w.r.t the planet center
\({\bf v}_{LP/N}\) of the current target point moving along the central line of the strip.
The standard location pointing computation described above is first performed to obtain \({\pmb\sigma}_{R/N}\) (the reference that points \(\hat{\bf p}_B\) at the current target). An additional rotation about the pointing axis \(\hat{\bf p}_B\) is then computed so that a secondary body-fixed vector \(\hat{\bf c}_B\) specified by the user and in the plane orthogonal to the pointing axis becomes perpendicular to the strip scanning direction. This ensures that the instrument’s cross-track axis is correctly aligned during image acquisition.
Step 1 – Compute the scanning direction in the reference body frame. The normalized target velocity \(\hat{\bf v}_{LP/N}\) is expressed in the reference frame R using the DCM \([RN]\) obtained from \({\pmb\sigma}_{R/N}\):
The component of \(\hat{\bf v}_{LP/R}\) perpendicular to the pointing axis is then:
and is normalized to \(\hat{\bf v}_{\perp}\).
If \(|\hat{\bf p}_B \times \hat{\bf v}_{LP/R}|\) is smaller than a user-defined threshold alignmentThreshold
(default 0.1), then \(\hat{\bf p}_B\) and \(\hat{\bf v}_{LP/R}\) are nearly collinear and the perpendicular
direction is undefined or unstable. In that case no extra rotation is applied and the outputs
fall back to the standard location-pointing values.
Step 2 – Choose the sign of \(\hat{\bf v}_{\perp}\). Both \(+\hat{\bf v}_{\perp}\) and \(-\hat{\bf v}_{\perp}\) are valid perpendicular-to-strip directions. The sign is chosen so that the rotation angle is minimized, i.e. the sign that satisfies \(\hat{\bf c}_B \cdot \hat{\bf v}_{\perp} > 0\) is selected.
Step 3 – Compute the extra rotation MRP \({\pmb\sigma}_{R_2/R}\). The rotation that aligns \(\hat{\bf c}_B\) with \(\hat{\bf v}_{\perp}\) about \(\hat{\bf p}_B\) is computed analogously to the standard pointing rotation. The eigen-axis is:
and the rotation angle is:
The MRP of this extra rotation is then:
Step 4 – Compose to get the final reference. The combined reference attitude that both points \(\hat{\bf p}_B\) at the target and aligns \(\hat{\bf c}_B\) perpendicular to the strip scanning direction is:
Step 5 – Compute the final tracking error. The tracking error is recomputed with respect to the updated reference:
where \(\ominus\) denotes MRP subtraction.
The outputs in strip imaging mode are therefore:
Angular Rate Computation
The tracking error rates \({\pmb\omega}_{B/R}\) are obtained through numerical differentiation of the
MRP values. During the first module Update evaluation the numerical differencing is not possible and
this value is thus set to zero.
Note
The module checks for several conditions such as heading vectors being collinear, the MRP switching during the numerical differentiation, etc. In strip imaging mode, the non-collinearity constraint between \(\hat{\bf p}_B\) and the target velocity is also checked. When the two vectors are nearly parallel, the extra strip rotation is skipped and the module falls back to pure location pointing.
User Guide
For location pointing, the one required variable that must be set is pHat_B. This is body-fixed unit vector which is to be
pointed at the desired inertial location. The user should only connect one location of interest input message, either locationInMsg,
celBodyInMsg or scTargetInMsg. Connecting multiple will result in a warning and the module defaults to using the ground location,
planet location or spacecraft location, in that order.
By default this is a 2D attitude control module in attitude and a 2D rate control. In particular, the rates about the
desired heading axis are not damped. By setting the module variable useBoresightRateDamping to 1,
the body rates about about the desired heading
angle are added to the rate tracking error yielding a 3D rate control implementation.
Note that useBoresightRateDamping is ignored during strip imaging, as strip imaging already performs
full 3D attitude control.
For strip imaging, the user should connect locationstripInMsg (a StripStateMsgPayload from Module: stripLocation)
and additionally set the cHat_B body-fixed vector. This vector must be perpendicular to pHat_B and
represents the instrument cross-track axis that needs to be aligned perpendicular to the strip scanning direction.
The variable alignmentThreshold (default 0.1) controls the collinearity threshold: if
\(|\hat{\bf p}_B \times \hat{\bf v}_{LP/R}|\) is below this value the extra strip rotation is skipped.
The variable stripInertialSpeedThreshold (default \(10^{-12}\) m/s) defines the minimum inertial target velocity magnitude (relative to planet origin vector)
required to compute a valid scanning direction; if the strip speed magnitude is below this threshold, the module
falls back to pure location pointing.
This module in both modes provides two output messages in the form of AttGuidMsgPayload and AttRefMsgPayload. The first guidance message, describing body relative to reference tracking errors, can be directly connected to an attitude control module. However, at times we need to have the attitude reference message as the output to feed to Module: attTrackingError.
The variable smallAngle defines an angular threshold (in radians, default zero) below which a rotation is
set to zero. It applies separately to the pointing rotation and the strip rotation. This is to avoid numerical issues when the angles are very small.
Functions
-
void SelfInit_locationPointing(locationPointingConfig *configData, int64_t moduleID)
This method initializes the output messages for this module.
- Parameters:
configData – The configuration data associated with this module
moduleID – The module identifier
-
void Update_locationPointing(locationPointingConfig *configData, uint64_t callTime, int64_t moduleID)
This method takes the estimated body states and position relative to the ground to compute the current attitude/attitude rate errors and pass them to control.
- Parameters:
configData – The configuration data associated with the module
callTime – The clock time at which the function was called (nanoseconds)
moduleID – The module identifier
-
void Reset_locationPointing(locationPointingConfig *configData, uint64_t callTime, int64_t moduleID)
This method performs a complete reset of the module. Local module variables that retain time varying states between function calls are reset to their default values. Check if required input messages are connected.
- Parameters:
configData – The configuration data associated with the module
callTime – [ns] time the method is called
moduleID – The module identifier
-
struct locationPointingConfig
- #include <locationPointing.h>
This module is used to generate the attitude reference message in order to have a spacecraft point at a location on the ground.
Public Members
-
double pHat_B[3]
body fixed vector that is to be aimed at a location
-
double cHat_B[3]
body fixed vector representing the scan line of the camera (must be orthogonal to pHat_B by definition)
-
double smallAngle
[rad] angle value that specifies what is near 0 or 180 degrees
-
int useBoresightRateDamping
[int] flag to use rate damping about the sensor boresight (ignored for strip imaging)
-
double alignmentThreshold
threshold for collinearity check between pHat_B and v_TP_B during strip imaging; defaults to 0.1
-
double stripInertialSpeedThreshold
[m/s] minimum inertial target velocity magnitude (relative to planet origin vector) required to compute strip direction; defaults to 1e-12
-
double sigma_BR_old[3]
older sigma_BR value, stored for finite diff
-
uint64_t time_old
[ns] prior time value
-
double init
module initialization counter
-
double eHat180_B[3]
eigen axis to use if commanded axis is 180 from pHat
-
NavAttMsg_C scAttInMsg
input msg with inertial spacecraft attitude states
-
NavTransMsg_C scTransInMsg
input msg with inertial spacecraft position states
-
GroundStateMsg_C locationInMsg
input msg with location relative to planet
-
StripStateMsg_C locationstripInMsg
input msg with location and velocity of the current target point on the strip, relative to planet
-
EphemerisMsg_C celBodyInMsg
input celestial body message
-
NavTransMsg_C scTargetInMsg
input msg with inertial target spacecraft position states
-
AttGuidMsg_C attGuidOutMsg
attitude guidance output message
-
AttRefMsg_C attRefOutMsg
attitude reference output message
-
BSKLogger *bskLogger
BSK Logging.
-
double pHat_B[3]