Module: groundMapping¶

Executive Summary¶

This module checks that a vector of mapping points are visible to a spacecraft instrument, outputting a vector of access messages for each mapping point.

Module Assumptions and Limitations¶

This module assumes that the location is affixed to a spherical body with a constant radius. Elevation constraints are computed assuming a conical field of view around the normal vector from the body’s surface at the location. This module also assumes the spacecraft instrument has a spherical field-of-view (FOV).

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.

Module I/O Messages¶
Msg Variable Name	Msg Type	Description
planetInMsg	SpicePlanetStateMsgPayload	(optional) Planet state input message
scStateInMsg	SCStatesMsgPayload	Spacecraft state input message
accessOutMsgs	AccessMsgPayload	vector of ground location access messages
currentGroundStateOutMsgs	GroundStateMsgPayload	vector of ground state messages

Detailed Module Description¶

The groundMapping module loops through a number of mapping points defined in the planet-frame, checking that:

The spacecraft is within the range and elevation requirements of the mapping point
The point is within the spacecraft instrument’s FOV cone

Range and Elevation¶

The range and elevation check follows the same logic as the Module: groundLocation module.

FOV Checking¶

Each mapping point is also checked to determine if its within the instrument’s FOV cone. This check is performed as follows:

The projection of the mapping point along the instrument’s boresight is computed and stored
If the above projection is less than 0, the point is not within the instrument’s FOV cone
If the above projection is greater than 0, the point may be within the instrument’s FOV cone
A final check is performed to compare the distance from mapping point to the instrument’s boresight vector. If this distance is less than the radius at the boresight projection distance, the point is within the instrument’s FOV

User Guide¶

To use this module, the user must first instantiate the module

groundMap = groundMapping.GroundMapping()
groundMap.ModelTag = "groundMapping"

The user must then set several variables within the module. First, the minimum elevation and maximum range should be set. The minimum elevation is the minimum required elevation of the spacecraft with respect to the mapping points. The minimum elevation is an optional parameter, defaulting to zero. The maximum range is the farthest distance the spacecraft can be from a mapping point to have access. This parameter is also optional, defaulting to a value of -1, which means that no maximum range is considered.

groundMap.minimumElevation = np.radians(45.)
groundMap.maximumRange = 1e9

The user must then set several variables regarding the spacecraft instrument. These include the position of the camera in the body-frame of the spacecraft, the normal vector of the instrument boresight defined in the body-frame of the spacecraft, and the half field-of-view of the instrument. The position of the camera defaults to zero and is an optional parameter. The normal vector of the instrument boresight, nHat_B, is also defaulted to zero, but is not an optional parameter. Finally, the halfFieldOfView is a required parameter and defaults to 10 degrees if not set.

groundMap.cameraPos_B = [0, 0, 0]
groundMap.nHat_B = [0, 0, 1]
groundMap.halfFieldOfView = np.radians(22.5)

The mapping points should then be added to the module one at a time. This is done as follows:

groundMap.addPointToModel(map_point)

The maximumRange variable is optional and defaults to -1. This means by default no maximum range is considered. Set it to a positive value to have hasAccess output message variable depend on range.

A groundLocation can be affixed to a specific planet by setting its planetInMsg input message:

groundTarget.planetInMsg.subscribeTo(planetMsg)

The spacecraft can be added to the module by calling:

groundMap.scStateInMsg.subscribeTo(scObject.scStateOutMsg)

Finally, logs for every mapping point can be created as follows:

mapLog = []
for idx in range(0, N):
    mapLog.append(groundMap.accessOutMsgs[idx].recorder())
    scSim.AddModelToTask(simTaskName, mapLog[idx])

class GroundMapping : public SysModel ¶

#include <groundMapping.h>

This module checks that a vector of mapping points are visible to a spacecraft’s imager, outputting a vector of accessMessages for each mapping point.

Public Functions

GroundMapping()¶: This is the constructor for the module class. It sets default variable values and initializes the various parts of the model

~GroundMapping()¶: Module Destructor

void addPointToModel(Eigen::Vector3d &r_LP_P_init)¶

Method to add map points

Parameters: r_LP_P_init – mapping point in planet-fixed frame

void Reset(uint64_t CurrentSimNanos)¶

This method is used to reset the module and checks that required input messages are connect.

Returns: void

void UpdateState(uint64_t CurrentSimNanos)¶

This is the main method that gets called every time the module is updated. Provide an appropriate description.

Returns: void

Public Members

double minimumElevation¶: [rad] (optional) minimum elevation above the local horizon needed to see a spacecraft; defaults to 10 degrees equivalent.

double maximumRange¶: [m] (optional) Maximum slant range to compute access for; defaults to -1, which represents no maximum range.

Eigen::Vector3d cameraPos_B¶: [m] (optional) Instrument position in body frame, defaults to (0,0,0)

double halfFieldOfView¶: [r] Instrument half-fov, defaults to 10 degrees

Eigen::Vector3d nHat_B¶: [-] Instrument unit direction vector in body frame components

BSKLogger bskLogger¶: — BSK Logging

ReadFunctor<SpicePlanetStateMsgPayload> planetInMsg¶: Planet state input message.

ReadFunctor<SCStatesMsgPayload> scStateInMsg¶: Spacecraft state input message.

std::vector<Message<GroundStateMsgPayload>*> currentGroundStateOutMsgs¶: vector of ground location output message

std::vector<Message<AccessMsgPayload>*> accessOutMsgs¶: vector of ground location access messages

Private Functions

void ReadMessages()¶: Read module messages

void computeAccess(uint64_t c)¶

Method to compute whether or not the spacecraft has access to the location

Parameters: c – index of the given location

void WriteMessages(uint64_t CurrentClock)¶: write module messages

void updateInertialPositions()¶: Method to update the relevant rotations matrices

uint64_t checkInstrumentFOV()¶: Method to compute whether or not the mapping point is in the instrument’s FOV

Private Members

std::vector<AccessMsgPayload> accessMsgBuffer¶: buffer of access output data

std::vector<GroundStateMsgPayload> currentGroundStateMsgBuffer¶: buffer of access output data

SCStatesMsgPayload scStateInMsgBuffer¶: buffer of spacecraft states

SpicePlanetStateMsgPayload planetInMsgBuffer¶: buffer of planet data

std::vector<Eigen::Vector3d> mappingPoints¶: Vector of mapping points.

Eigen::Matrix3d dcm_LP¶: Rotation matrix from planet-centered, planet-fixed frame P to site-local topographic (SEZ) frame L coordinates.

Eigen::Matrix3d dcm_PN¶: Rotation matrix from inertial frame N to planet-centered to planet-fixed frame P.

Eigen::Matrix3d dcm_PN_dot¶: Rotation matrix derivative from inertial frame N to planet-centered to planet-fixed frame P.

Eigen::Vector3d w_PN¶: [rad/s] Angular velocity of planet-fixed frame P relative to inertial frame N.

Eigen::Vector3d r_PN_N¶: [m] Planet position vector relative to inertial frame origin.

Eigen::Vector3d r_LP_P¶: [m] Ground Location position vector relative to to planet origin vector in planet frame coordinates.

Eigen::Vector3d r_LP_N¶: [m] Gound Location position vector relative to planet origin vector in inertial coordinates.

Eigen::Vector3d rhat_LP_N¶: [-] Surface normal vector from the target location in inertial coordinates.

Eigen::Vector3d r_LN_N¶: [m] Ground Location position vector relative to inertial frame origin in inertial coordinates.

Eigen::Vector3d r_North_N¶: [-] Inertial 3rd axis, defined internally as “North”.

Eigen::Vector3d r_BP_N¶: [m] Inertial position of the body frame wrt the planet

Eigen::Matrix3d dcm_NB¶: DCM from the body frame to the inertial frame.