cobConverter#

Executive Summary#

Module reads in a message containing the pixel data extracted from the center of brightness (COB) measurement and transforms into a position measurement. The written message contains a heading (unit vector) and a covariance (measurement noise).

Additionally, the center of mass (COM) can be estimated using a Sun phase angle correction. In this case, another unit vector message is written containing the heading and covariance for the COM, as well as a message containing information about the COM offset.

The center of mass correction can be applied using the “Lambertian” or “Binary” method. If no correction should be performed, the method needs to be “NoCorrection”. The Lambertian method assumes that the body is a sphere with lambertian reflectance, while the Binary method assumes a brightness of either 1 or 0 in the image of the body.

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

cameraConfigInMsg

CameraConfigMsgPayload

Input the camera config message

opnavCOBInMsg

OpNavCOBMsgPayload

Input center of brightness message written out by the image processing module

opnavFilterInMsg

FilterMsgPayload

Input filter message

navAttInMsg

NavAttMsgPayload

Input navigation message containing the spacecraft attitude in the inertial frame

ephemInMsg

EphemerisMsgPayload

Input ephemeris message containing the spacecraft position in the inertial frame

opnavUnitVecCOBOutMsg

OpNavUnitVecMsgPayload

Output unit vector containing the heading vector of the COB and covariance in multiple frames for filtering

opnavUnitVecCOMOutMsg

OpNavUnitVecMsgPayload

Output unit vector containing the heading vector of the COM and covariance in multiple frames for filtering

opnavCOMOutMsg

OpNavCOMMsgPayload

Output message containing information about the COM offset due to the phase angle correction

Detailed Module Description#

Measurement mapping#

This module models the measurement that will be ingested by the following filter. This is essentially a stand-alone measurement model for the filter composed via messaging.

After reading the input center of brightness message which contains the pixel location of the center of brightness and the number of pixels that were found, the module reads the camera parameters and uses them to compute all necessary optics values.

The main relations used between all of the camera values can be found in this paper by J. A. Christian.

With this, the unit vector in the camera frame from focal point to center of brightness in the image plane is found by (equivalent to setting z=1):

\[\mathbf{r}_{COB}^C &= [K]^{-1} \mathbf{\bar{u}}_{COB}\]

where \(\mathbf{\bar{u}}_{COB} = [\mathrm{cob}_x, \mathrm{cob}_y, 1]^T\) with the pixel coordinates of the center of brightmess \(\mathrm{cob}_x\) and \(\mathrm{cob}_y\), \([K]\) is the camera calibration matrix and \(\mathbf{r}_{COB}^N\) is the unit vector describing the physical heading to the target in the camera frame.

The covariance of the COB error is found using the number of detected pixels and the camera parameters, given by:

\[\begin{split}P = \frac{\mathrm{numPixels}}{4 \pi \cdot ||\mathbf{\bar{u}}_{COB}||^2} \left( \begin{bmatrix} d_x^2 & 0 & 0 \\ 0 & d_y^2 & 0 \\ 0 & 0 & 1 \end{bmatrix}\right)\end{split}\]

where \(d_x\) and \(d_y\) are the first and second diagonal elements of the camera calibration matrix \([K]\). This covariance matrix is then transformed into the body frame and added to the covariance of the attitude error. Both individual covariance matrices, and thus the total covariance matrix, describe the measurement noise of a unit vector.

By reading the camera orientation and the current body attitude in the inertial frame, the final step is to rotate the covariance and heading vector in all the relevant frames for modules downstream. This is done simply by converting MRPs to DCMs and performing the matrix multiplication. If the incoming image is not valid, the module writes empty messages.

If a COM correction is to be performed, the offset factor \(\gamma\) due to the Sun phase angle correction is obtained for a phase angle \(\alpha\) using

\[\gamma = \frac{4}{3 \pi} (1 - \cos\alpha)\]

for the Binary method or

\[\gamma = \frac{3 \pi}{16} \left[ \frac{(\cos\alpha + 1) \sin\alpha}{\sin\alpha + (\pi - \alpha) \cos\alpha} \right]\]

for the Lambertian method. If no correction is to be performed, then \(\gamma = 0\). The correction for the COM location is performed according to this paper by S. Bhaskaran. First, the object radius \(R\) in meters is converted to the object radius in pixel units \(R_c\) by

\[R_c = \frac{R K_x f}{\rho} = \frac{R d_x}{\rho}\]

where \(K_x = d_x/f\), \(f\) is the focal length in meters, and \(\rho\) is the distance from the body center to the spacecraft in meters. Using the sun direction in the image plane \(\phi\), the COM location in pixel space is then computed using

\[\begin{split}\mathrm{com}_x = \mathrm{cob}_x - \gamma R_c \cos\phi \\ \mathrm{com}_y = \mathrm{cob}_y - \gamma R_c \sin\phi\end{split}\]

Finally, similar to the COB unit vector, the COM unit vector is obtained by

\[\mathbf{r}_{COM}^C &= [K]^{-1} \mathbf{\bar{u}}_{COM}\]

where \(\mathbf{\bar{u}}_{COM} = [\mathrm{com}_x, \mathrm{com}_y, 1]^T\).

An outlier detection may be performed for the COB. In this case, the filter message FilterMsgPayload is used to predict the location of the COB. If the location of the COB coming from the image is significantly different from the predicted COB, it is considered an outlier and the output unit vector is invalidated. For the output message to be valid, the following condition must be fulfilled:

\[e_{COB} = | \mathbf{u}_{COB} - \mathbf{u}_{COB, predicted} | \le n_\sigma \cdot \sigma\]

where \(\mathbf{u}_{COB} = [\mathrm{cob}_x, \mathrm{cob}_y]^T\) are the x-y coordinates of the COB coming from the image, \(\mathbf{u}_{COB, predicted}\) are the x-y coordinates of the predicted COB, \(n_\sigma\) are the number of standard deviations specified by the module input “numStandardDeviations”. The standard deviation \(\sigma\) is either set using the setStandardDeviation setter function, or automatically obtained by the module using the attitude covariance matrix (specified as parameter of the module) as well as the covariance of the COB estimation and the filter covariance (both of which are automatically computed).

User Guide#

This section is to outline the steps needed to setup a center of brightness converter in Python.

  1. Import the module:

    from Basilisk.fswAlgorithms import cobConverter

  2. Create an instantiation of converter class. The COM/COB correction method and object radius need to be specified:

    module = cobConverter.CobConverter(cobConverter.PhaseAngleCorrectionMethod_NoCorrection, R_obj)  # no correction
# module = cobConverter.CobConverter(cobConverter.PhaseAngleCorrectionMethod_Lambertian, R_obj)  # Lambertian method
# module = cobConverter.CobConverter(cobConverter.PhaseAngleCorrectionMethod_Binary, R_obj)  # Binary method

  3. The attitude error covariance matrix is set by:

    module.setAttitudeCovariance(covar_att_BN_B)

  4. The object radius in units of meters for the phase angle correction can be updated by:

    module.setRadius(R_obj)

  5. The COB outlier detection is enabled by:

    module.enableOutlierDetection()

  6. The number of acceptable standard deviations and the standard deviation itself for COB outlier detection are set by:

    module.setNumStandardDeviations(3)  # default 3
module.setStandardDeviation(100)  # if not set, then the standard deviation is dynamically updated by the module

  7. Subscribe to the messages:

    module.cameraConfigInMsg.subscribeTo(camInMsg)
module.opnavCOBInMsg.subscribeTo(cobInMsg)
module.opnavFilterInMsg.subscribeTo(filterInMsg)
module.navAttInMsg.subscribeTo(attInMsg)
module.ephemInMsg.subscribeTo(ephemInMsg)

  8. Add model to task:

    sim.AddModelToTask(taskName, module)

Class CobConverter#

class CobConverter : public SysModel#

visual limb finding module

Public Functions

void updateState(uint64_t currentSimNanos)#

During an update, this module transforms pixel values for the center of brightness into a unit vector direction in several frames (inertial, Camera, and Body).

Parameters:

currentSimNanos – The clock time at which the function was called (nanoseconds)

Returns:

void

void reset(uint64_t currentSimNanos)#

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.

Parameters:

currentSimNanos – The clock time at which the function was called (nanoseconds)

Returns:

void

void setRadius(const double radius)#

Set the object radius

Parameters:

double – radiusInput [m]

Returns:

void

double getRadius() const#

Get the object radius

Returns:

double radius [m]

void setAttitudeCovariance(const Eigen::Matrix3d covAtt_BN_B)#

Set the attitude error covariance matrix in body frame B, for unit vector measurements

Parameters:

cov_att_BN_B –

Returns:

void

Eigen::Matrix3d getAttitudeCovariance() const#

Get the attitude error covariance matrix in body frame B, for unit vector measurements

Returns:

Eigen::Matrix3d cov_att_BN_B

void setNumStandardDeviations(const double num)#

Set the number of standard deviations that are acceptable for the expected COB error

Parameters:

double – numStandardDeviations

Returns:

void

double getNumStandardDeviations() const#

Get the number of standard deviations that are acceptable for the expected COB error

Returns:

double numStandardDeviations

void setStandardDeviation(const double num)#

Set the accepted standard deviation for the expected COB error

Returns:

void

double getStandardDeviation() const#

Get the accepted standard deviation for the expected COB error

Returns:

double numStandardDeviations

bool isStandardDeviationSpecified() const#

Get whether or not a standard deviation is set

Returns:

bool specifiedStandardDeviation

void enableOutlierDetection()#

Enable the COB outlier detection

Returns:

void

void disableOutlierDetection()#

Disable the COB outlier detection

Returns:

void

bool isOutlierDetectionEnabled() const#

Get whether or not the COB outlier detection is performed

Returns:

bool performOutlierDetection