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 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#

class GroundMapping : public SysModel#

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