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 \left\| \mathbf{\bar{u}}_{COB} \right\|^2} \left( \left[ \begin{array}{ccc} d_x^2 & 0 & 0 \\ 0 & d_y^2 & 0 \\ 0 & 0 & 1 \end{array} \right] \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.

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\).

The covariance of the COM error is found by firstly computing the total derivative of the angular error. Which can be found by calculating the partials of the Geometric model correction with respect to the flyby and asteroid states:

\[ \begin{align}\begin{aligned}\frac{\partial \beta_G}{\partial \mathbf{r}} = -\frac{4R}{3\pi r} \: \frac{(1 - \cos \alpha)}{1 + \left( \frac{4R}{3\pi r} (1 - \cos \alpha) \right)^2} \: \frac{ \mathbf{\hat{r}} ^T}{r}\\\frac{\partial \beta_G}{\partial R} = \frac{4}{3\pi r} \: \frac{(1 - \cos \alpha)}{1 + \left( \frac{4R}{3\pi r} (1 - \cos \alpha) \right)^2}\\\frac{\partial \beta_G}{\partial \alpha} = \frac{4R}{3\pi r} \: \frac{\sin \alpha}{1 + \left( \frac{4R}{3\pi r} (1 - \cos \alpha) \right)^2}\end{aligned}\end{align} \]

The next equation shows the partial of the phase angle with respect to the flyby and asteroid states:

\[\frac{\partial \alpha}{\partial \mathbf{r}} = \frac{ - \mathbf{\hat{s}} ^T}{r \sin \alpha} \left( \mathbf{I} - \mathbf{\hat{r}} \mathbf{\hat{r}} ^T \right)\]

This leads to standard deviation equation which is done by gathering the partials in the following equation:

\[\sigma_{\beta}^2 = \left( \frac{\partial \beta}{\partial \mathbf{r}} + \frac{\partial \beta}{\partial \alpha} \frac{\partial \alpha}{\partial \mathbf{r}} \right) [\mathbf{P}] \left( \frac{\partial \beta}{\partial \mathbf{r}} + \frac{\partial \beta}{\partial \alpha} \frac{\partial \alpha}{\partial \mathbf{r}} \right)^T + \left( \frac{\partial \beta}{\partial R}\right)^2 \sigma_{R}^2\]

where \([P]\) is the filter position covariance matrix and \(\sigma_{R}^2\) is the object’s radius uncertainty. The Following equation was used to find the com covariance matrix:

\[\begin{split}W_{\text{correction}} = \left( \left[ \begin{array}{ccc} d_x^2 + \dfrac{\sigma_{\beta}^2}{\psi_{i,x}} \cos \phi & 0 & 0 \\ 0 & d_y^2 + \dfrac{\sigma_{\beta}^2}{\psi_{i,y}} \sin \phi & 0 \\ 0 & 0 & 1 \end{array} \right] \right)\end{split}\]

where \(\psi_{i,x}\) and \(\psi_{i,y}\) are the iFOV. This matrix is then transformed into the body frame and added to the covariance of the attitude error and COB error. All 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.

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.

Import the module:

from Basilisk.fswAlgorithms import cobConverter

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

The attitude error covariance matrix is set by:
```
module.setAttitudeCovariance(covar_att_BN_B)
```
The object radius in units of meters for the phase angle correction can be updated by:
```
module.setRadius(R_obj)
```
The COB outlier detection is enabled by:
```
module.enableOutlierDetection()
```

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

Subscribe to the messages:

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

Add model to task:
```
sim.AddModelToTask(taskName, module)
```

Class CobConverter#

class CobConverter : public SysModel#

Converts center-of-brightness (COB) pixel measurements into unit vectors (camera, body, inertial frames), with optional phase-angle correction and outlier detection.

Public Functions

CobConverter(PhaseAngleCorrectionMethod method, double radiusObject)#

Construct a CobConverter.

Note

The radius is validated with an assertion.

Parameters:

method – Phase-angle correction method to apply.
radiusObject – Object radius in meters (must be > 0).

~CobConverter() final#: Default destructor.

void updateState(uint64_t currentSimNanos) override#

Update step: convert pixel-based COB into unit vectors and outputs.

Reads inputs, computes parameters and corrections, performs optional outlier detection, and writes out three payloads: COB unit vector, COM unit vector, and COM metadata.

Parameters:: currentSimNanos – Current simulation time in nanoseconds.

void reset(uint64_t currentSimNanos) override#

Reset internal state and validate required input connections.

Parameters:: currentSimNanos – Current simulation time in nanoseconds.
Throws:: std::invalid_argument – If any required input message link is missing.

void setRadius(double radius)#

Set the object radius.

Parameters:: radius – Object radius in meters (must be > 0).

double getRadius() const#

Get the object radius.

Returns:: Object radius in meters.

void setRadiusUncertainty(double radiusUncertainty)#

Set the object radius uncertainty.

Parameters:: radiusUncertainty – Object radius uncertainty in meters (>= 0).

double getRadiusUncertainty() const#

Get the object radius uncertainty.

Returns:: Object radius uncertainty in meters.

void setAttitudeCovariance(const Eigen::Matrix3d &covAtt_BN_B)#

Set the attitude error covariance matrix in body frame (for unit vector measurements).

Parameters:: covAtt_BN_B – 3x3 attitude covariance in body frame.

Eigen::Matrix3d getAttitudeCovariance() const#

Get the attitude error covariance matrix in body frame (for unit vector measurements).

Returns:: 3x3 attitude covariance in body frame.

void setNumStandardDeviations(double num)#

Set the number of standard deviations for outlier gating.

Parameters:: num – Number of sigmas (> 0).

double getNumStandardDeviations() const#

Get the configured number of standard deviations for outlier gating.

Returns:: Number of sigmas.

void setStandardDeviation(double num)#

Set an explicit standard deviation for the expected COB error.

Note

When set, outlier detection will use this fixed value instead of deriving one.

Parameters:: num – Standard deviation (> 0).

double getStandardDeviation() const#

Get the explicitly specified standard deviation (if set).

Returns:: Standard deviation value.

bool isStandardDeviationSpecified() const#

Determine whether a standard deviation has been explicitly specified.

Returns:: True if specified, false otherwise.

void enableOutlierDetection()#: Enable COB outlier detection.

void disableOutlierDetection()#: Disable COB outlier detection.

bool isOutlierDetectionEnabled() const#

Check whether COB outlier detection is enabled.

Returns:: True if enabled, false otherwise.