centerOfBrightness#

Executive Summary#

Module reads in a message containing a pointer to an image and writes out the weighted center of brightness of the image for any pixel above a parametrized threshold. A window mask can be specified such that only the pixels within the specified window are considered. The module also computes the normalized total brightness of all bright pixels (brightness between 0 and 1, summed up over all bright pixels) and determines the rolling average of the brightness over the last few time steps. If there are no bright pixels, the brightness history (and rolling average) will not be updated.

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
opnavCirclesOutMsg	OpNavCOBMsgPayload	output center of brightness message containing number of detected pixels, and center-of-brightness in pixel space, as well as the rolling average of the total brightness.
imageInMsg	CameraImageMsgPayload	camera image input message containing the pointer to the image

Detailed Module Description#

Image Processing#

The module performs a small set of operations to prepare the image for the center of brightness detection. Firstly, it applies a Gaussian blur on the image, which helps soften the edges of bright objects and improves the detection performance. Secondly it thresholds the image in order to remove any dim pixels that may not be of interest to the detection algorith. Both of these are implemented using OpenCV methods.

Afterwards the weighted center-of-brightness is implemented by finding all the non-zero pixels (all pixels that were not thresholded down), and finding their intensity (which will be their weight). Assuming the image is made up of pixels \(p\) with and x and y component, that \(I\) is the intensity, and \(I_{\mathrm{min}\) is the threshold value, the center of brightness within the window of the image (\(\mathrm{window} \in \mathrm{image}\)) is then defined as:

\[\begin{split}\mathcal{P} &= \{p \in \mathrm{window} \hspace{5cm} | \hspace{5cm} I(p) > I_{\mathrm{min}\} \\ I_\mathrm{tot} &= \sum_{p \in \mathcal{P}} I(p) \\ p_{\mathrm{cob}} &= \frac{1}{I_\mathrm{tot}}\sum_{p \in \mathcal{P}} I(p) * p }\end{split}\]

where the center of brightess \(p_{\mathrm{cob}}\) has an x and y component which are then written to the message. The normalized total brightness is equal to

\[I_\mathrm{tot, normalized} = \frac{I_\mathrm{tot}}{255}\]

and the rolling average is computed over the last \(N\) time steps, as specified by numberOfPointsBrightnessAverage. If the relative increase of the rolling brightness average from one time step to the next is below the threshold brightnessIncreaseThreshold, the image is tagged as invalid.

If the incoming image is not valid, or there were no pixels above the threshold, the image is tagged as invalid. Downstream algorithms can therefore know when to skip a measurement.

User Guide#

This section is to outline the steps needed to setup a Center of Brightness in Python.

Import the centerOfBrightness class:

from Basilisk.fswAlgorithms import centerOfBrightness

Create an instantiation of centerOfBrightness:

cobAlgorithm = centerOfBrightness.CenterOfBrightness()

Define the image processing parameters. For example:

cobAlgorithm.blurSize = 7
cobAlgorithm.threshold = 10

Define the window mask (optional):

cobAlgorithm.setWindowCenter(windowCenter)
cobAlgorithm.setWindowSize(windowWidth, windowHeight)

Specify the number of data points to be used for the rolling average of total brightness (optional):
```
cobAlgorithm.numberOfPointsBrightnessAverage = 5
```
Specify the minimum relative brightness increase of the rolling average of total brightness (optional):
```
moduleConfig.setRelativeBrightnessIncreaseThreshold(0.1)
```
Subscribe to the image message output by the camera model or visualization interface:
```
cobAlgorithm.imageInMsg.subscribeTo(imgInMsg)
```
The angular states of the body are created using an output message opnavCOBOutMsg.

sim.AddModelToTask(taskName, cobAlgorithm)

Class CenterOfBrightness#

class CenterOfBrightness : public SysModel#

visual object tracking using center of brightness detection

Public Functions

CenterOfBrightness()#: Module constructor

~CenterOfBrightness()#: Module destructor

void updateState(uint64_t currentSimNanos)#

This module reads an OpNav image and extracts the weighted center of brightness. It performs a grayscale, a blur, and a threshold on the image before summing the weighted pixel intensities in order to average them with the total detected intensity. This provides the center of brightness measurement (as well as the total number of bright pixels)

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 setWindowCenter(const Eigen::VectorXi &center)#

Set the mask center for windowing

Parameters:: Eigen::Vector2i – center [px]
Returns:: void

Eigen::VectorXi getWindowCenter() const#

Get the mask center for windowing

Returns:: Eigen::Vector2i center [px]

void setWindowSize(int32_t width, int32_t height)#

Set the mask size for windowing

Parameters:

int32_t – width [px]
int32_t – height [px]

Returns:

void

Eigen::VectorXi getWindowSize() const#

Get the mask center for windowing

Returns:: Eigen::Vector2i size [px]

void setRelativeBrightnessIncreaseThreshold(double increaseThreshold)#

Set threshold for the increase in brightness for images not to be invalidated

Parameters:: double – increaseThreshold
Returns:: void

double getRelativeBrightnessIncreaseThreshold() const#

Get threshold for the increase in brightness for images not to be invalidated

Returns:: double increaseThreshold

void setPixelThreshold(double PixelThreshold)#

Set the pixel brightness threshold used for detecting bright pixels

Parameters:: double – pixelThreshold
Returns:: void

double getPixelThreshold() const#

Get the pixel brightness threshold used for detecting bright pixels

Returns:: double pixelThreshold

void setFileName(const std::string &fileName)#

Set the filename for the module to read an image directly

Parameters:: std::string – fileName
Returns:: void

std::string getFileName() const#

Get the filename for the module to read an image directly

Returns:: std::string fileName

void setBlurSize(int32_t blur)#

Set the blur size for the image processing filter

Parameters:: int32_t – blur
Returns:: void

int32_t getBlurSize() const#

Get the blur size for the image processing filter

Returns:: int32_t blur

void setSaveImages(bool save)#

Enable or disable saving debug images to file

Parameters:: bool – save
Returns:: void

bool getSaveImages() const#

Get whether saving debug images is enabled

Returns:: bool save

void setSaveDir(const std::string &directory)#

Set the directory where images should be saved

Parameters:: std::string – directory
Returns:: void

std::string getSaveDir() const#

Get the directory where images are saved

Returns:: std::string directory

void setNumberOfPointsBrightnessAverage(int32_t rollingAverage)#

Set the number of points used for rolling brightness averaging

Parameters:: int32_t – rollingAverage
Returns:: void

int32_t getNumberOfPointsBrightnessAverage() const#

Get the number of points used for rolling brightness averaging

Returns:: int32_t rollingAverage

Public Members

Message<OpNavCOBMsgPayload> opnavCOBOutMsg#: The name of the OpNav center of brightness output message.

ReadFunctor<CameraImageMsgPayload> imageInMsg#: The name of the camera output message.

BSKLogger bskLogger#: — BSK Logging