GoWebScanVisionResampler.h

Go to the documentation of this file.

/**
* @file    GoWebScanVisionResampler.h
* @brief   Declares a GoWebScanVisionResampler object.
*
* @internal
* Copyright (C) 2017-2026 by LMI Technologies Inc.
* Licensed under the MIT License.
* Redistributed files must retain the above copyright notice.
*/

#ifndef GO_WEB_SCAN_VISION_RESAMPLER_H
#define GO_WEB_SCAN_VISION_RESAMPLER_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>
#include <GoWebScanSdk/GoWebScanConfig.h>

/**
 * @class   GoWebScanVisionResampler
 * @extends kObject
 * @ingroup GoWebScanSdk-Algorithms
 * @brief   Represents an algorithm for producing uniform-resolution resampled vision
 *          output given input terrain and demosaiced color vision tiles.
 *          
 *          Algorithm steps: 
 *          -# When processing an input image, each of the output rows that fall within its Y-location 
 *              limits is considered. Output rows that fall within this region are processed one at a time; 
 *              if the row has not been previously considered, its pixels are first cleared.
 *          -# For each pixel in a particular output row, the corresponding terrain Z value is first 
 *              looked up.
 *          -# Using the xRes(z) and yRes(z) functions provided by GoWebScanConfigNode, and the known 
 *              terrain Z value, the image resolutions are calculated. Using the image X-center 
 *              (GoWebScanConfigNode),  image Y-center (image stamp), and Y-offsets (GoWebScanConfigNode), 
 *              the address of the input pixel that best matches the location of the desired output pixel 
 *              is calculated. 
 *          -# When input images overlap, the pixels from each image are averaged together in the 
 *              output buffer. This implies that rows in the output buffer should be retained until the 
 *              trailing Y-location limit of the next input image is known; rows prior to the limit will no 
 *              longer be modified and can be emitted.
 */
typedef kObject GoWebScanVisionResampler;

/**
 * @struct  GoWebScanVisionResamplerParams
 * @extends kValue
 * @ingroup GoWebScanSdk-Algorithms
 * @brief   Represents parameters of the vision Y-resampler algorithm.
 */
typedef struct GoWebScanVisionResamplerParams
{
    kSSize imageWidth;                  ///< Expected width of vision images (pixels).
    kSSize imageHeight;                 ///< Expected height of vision images (pixels).
    k32s xCenter;                       ///< Center of vision node in system coords (mils).
    GoWebScanLinearFunction xResAsZ;    ///< Vision X resolution to Z fit as taken from sensor's GoGeoCal file.
    GoWebScanLinearFunction yResAsZ;    ///< Vision Y resolution to Z fit as taken from sensor's GoGeoCal file.
    GoWebScanLinearFunction zOffAsR;    ///< Vision Z offset to image row fit.
    k32s zMaximum;                      ///< Expected maximum Z value produced by profile sensors in system. Typically selected to be max of sensor's FOV.
    kSSize xStartPix;                   ///< Start of resampled data in system coords (pixels).
    kSSize xCountPix;                   ///< Count of resampled pixels in X (pixels).
    k32s xResolution;                   ///< Expected X-resolution of resampled output data (mils/pixel).
    k32s yResolution;                   ///< Expected Y-resolution of resampled output data (mils/pixel).
    k32s terrainXSubsampling;           ///< Terrain X-resolution is determined by this field (vision-x-resolution shifted right by terrainXSubsampling).
    kSSize yTilePix;                    ///< Expected Y-extent of vision tiles (pixels).
    k32s breakDistance;                 ///< Vision messages with a Y position greater than this threshold from the current message will be cleared and recycled (mils).
} GoWebScanVisionResamplerParams;

/** Defines the signature for the handler for accepting the output resampled rows. */
typedef kStatus(kCall *GoWebScanVisionResamplerDataFx)(kPointer context, k64s rowIndex, const GoWebScanInputAttr* attributes, const kRgb* points, kSSize pointCount);

/**
* Constructs a GoWebScanVisionResampler object.
*
* @public                   @memberof GoWebScanVisionResampler
* @param  resampler         Receives the constructed GoWebScanVisionResampler object. 
* @param  args              Algorithm parameters.
* @param  yOffsets          Y-offsets for each spot (mils). Calculated during system calibration.
* @param  allocator         Memory allocator (or kNULL for default). 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionResampler_Construct(GoWebScanVisionResampler* resampler, const GoWebScanVisionResamplerParams* args, const k32s* yOffsets, kAlloc allocator);

/**
* Sets the handler for accepting the processed resampled rows from the algorithm.
*
* @public                   @memberof GoWebScanVisionResampler
* @param  resampler         GoWebScanVisionResampler object. 
* @param  data              Callback function
* @param  context           Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionResampler_SetDataHandler(GoWebScanVisionResampler resampler, GoWebScanVisionResamplerDataFx data, kPointer context);

/**
 * Runs the vision resampler algorithm on a vision tile and set of terrain tiles that are matched (in Y).
 * 
 * @public                  @memberof GoWebScanVisionResampler
 * @param   resampler       GoWebScanVisionResampler object. 
 * @param   stamp           Input vision tile stamp.
 * @param   vision          Input vision image. Type kRgb.
 * @param   terrain         Pointer to start of buffer of terrain tiles matched in Y to vision image.
 * @param   terrainInputs   Pointer to start of buffer of terrain tile inputs.
 * @param   terrainCount    Count of matched terrain tiles.
 * @param   terrainTile     Terrain position (mils).
 * @return                  Operation status.
 */
GoWebScanFx(kStatus) GoWebScanVisionResampler_Process(GoWebScanVisionResampler resampler, const GoWebScanMsgStamp* stamp, kImage vision, kArray2* terrain, kArray1* terrainInputs, kSSize terrainCount, k64s terrainTile);

/**
* Clears internal buffers and resets the algorithm.
*
* @public                   @memberof GoWebScanVisionResampler
* @param  resampler         GoWebScanVisionResampler object. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionResampler_Clear(GoWebScanVisionResampler resampler);

#include <GoWebScanSdk/GoWebScanVisionResampler.x.h>

#endif