imageReader#

Executive Summary#

The ImageReaderInterface defines a common API for reading and pre-processing images for the center-of-brightness module. Two concrete implementations are provided:

ImageReaderFromFile — reads images from disk via OpenCV.
ImageReaderFromMessage — reads images from a CameraImageMsgPayload message containing encoded image bytes.

Both implementations share the same image-processing pipeline: BGR-to-grayscale conversion, box blur, binary thresholding, non-zero pixel extraction, and windowed filtering. The output is an array of pixel coordinates representing the locations of bright pixels within the requested window.

Interface#

ImageReaderInterface is an abstract base class with three pure virtual methods:

Interface Methods#
Method	Description
`getFullImageSize(cameraId)`	Returns the dimensions (width, height) of the most recently read image.
`getCurrentImageTimeTag(cameraId, previousTimeTag)`	Returns the new image time tag if a newer image is available, or 0 otherwise.
`getImageAsArray(center, windowSize, output)`	Reads and processes the image, then writes the pixel coordinates of all bright pixels within the specified window into `output`. Unused slots are filled with the sentinel value `(0, 0)`.

Image Processing Pipeline#

Both implementations perform the following steps inside getImageAsArray:

Load image — from file (ImageReaderFromFile) or from an encoded byte buffer in a message (ImageReaderFromMessage).
Convert to grayscale — cv::cvtColor with COLOR_BGR2GRAY.
Box blur — cv::blur with a kernel of size blurSize × blurSize pixels.
Binary threshold — pixels with intensity above pixelThreshold are set to 255; all others are set to 0.
Find non-zero pixels — cv::findNonZero returns the coordinates of all white pixels.
Window filtering — only coordinates that fall within the window [center - size/2, center + size/2) are kept. The result is written into the output array.

The maximum supported window size is 1024 × 1024 pixels (kMaxWindowSize = 1,048,576).

ImageReaderFromFile#

Reads images from disk using cv::imread.

Configuration#
Setter / Getter	Units	Description
`setFileName` / `getFileName`	-	Path to the image file to read. Must be set before calling `getImageAsArray`.
`setBlurSize` / `getBlurSize`	px	Box blur kernel size. Set to 1 for no blurring.
`setPixelThreshold` / `getPixelThreshold`	-	Binary threshold value (0–255). Pixels brighter than this are detected.
`setSaveImages` / `getSaveImages`	-	When true, saves the raw image to `saveDir` on each `getImageAsArray` call.
`setSaveDir` / `getSaveDir`	-	Output path for saved images.

getCurrentImageTimeTag always returns 1 (file-based reader has no freshness tracking).

Python example:

reader = centerOfBrightness.ImageReaderFromFile()
reader.setFileName("/path/to/image.png")
reader.setBlurSize(5)
reader.setPixelThreshold(50)

ImageReaderFromMessage#

Reads images from a CameraImageMsgPayload message. The payload must contain a pointer to encoded image bytes (JPEG or PNG) and set valid = 1.

Configuration#
Setter / Getter	Units	Description
`setBlurSize` / `getBlurSize`	px	Box blur kernel size. Set to 1 for no blurring.
`setPixelThreshold` / `getPixelThreshold`	-	Binary threshold value (0–255). Pixels brighter than this are detected.

Messages#
Msg Variable Name	Msg Type	Description
imageInMsg	CameraImageMsgPayload	Input message containing encoded image bytes and metadata.

getCurrentImageTimeTag reads the message and compares timeTag against the provided previousImageTimeTag. Returns the new time tag if newer, 0 otherwise.