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:

  1. The spacecraft is within the range and elevation requirements of the mapping point

  2. 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:

  1. The projection of the mapping point along the instrument’s boresight is computed and stored

  2. If the above projection is less than 0, the point is not within the instrument’s FOV cone

  3. If the above projection is greater than 0, the point may be within the instrument’s FOV cone

  4. 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

&#8212; 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.