GoWebScanVisionCombiner.h

Go to the documentation of this file.

/**
* @file    GoWebScanVisionCombiner.h
* @brief   Declares a GoWebScanVisionCombiner 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_COMBINER_H
#define GO_WEB_SCAN_VISION_COMBINER_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>
#include <GoWebScanSdk/GoWebScanUtilities.h>
#include <GoWebScanSdk/GoWebScanPipeMsg.h>
#include <GoWebScanSdk/GoWebScanVisionInputMsg.h>
#include <GoWebScanSdk/GoWebScanProfileTileMsg.h>
#include <kApi/Data/kArrayList.h>

/**
 * @class   GoWebScanVisionCombiner
 * @extends kObject
 * @ingroup GoWebScanSdk-Algorithms
 * @brief   Represents an algorithm to retain vision and terrain messages until a matching set in Y is
 *          available. The combiner emits a frame when it has one vision image and all of the profiles
 *          that potentially overlap in Y with that vision image. 
 *          
 *          Algorithm steps: 
 *          -# Vision and terrain tiles are enqueued as they arrive.
 *          -# The min and max Y-extents of the demosaiced image are determined (after applying 
 *              Y-offsets from system calibration).
 *          -# Based on the Y-extents, any vision tiles completely overlapping with other vision 
 *              tiles are discarded.
 *          -# Based on the Y position min and max limits per vision tile, profile tiles are matched.
 */
typedef kObject GoWebScanVisionCombiner;

/**
* @struct  GoWebScanVisionCombinerParams
* @extends kValue
* @ingroup GoWebScanSdk-Algorithms
* @brief   Represents parameters of the vision combiner algorithm.
*/
typedef struct GoWebScanVisionCombinerParams
{
    k64s minimumTileYExtent;                            ///< Expected minimum Y extent of each vision tile
    k64s coherencyDistance;                             ///< Lane is disabled if the distance between the first undelivered tile and last undelivered tile exceed this threshold (mils).
    k64s coherencyTime;                                 ///< Lane is disabled if the time between the first undelivered tile and the last undelivered tile exceed this threshold (microseconds).
} GoWebScanVisionCombinerParams;

/** Defines the signature for the handler for accepting the output matched vision and profile tiles. */
typedef kStatus(kCall *GoWebScanVisionCombinerDataFx)(kPointer context, GoWebScanVisionInputMsg visionInput, k64s profileTileStart,
    GoWebScanProfileTileMsg* profileTiles, kSSize profileTileCount);

/** Defines the signature for the handler to compute the min and max Y-extents for a vision tile. */
typedef kStatus(kCall *GoWebScanVisionCombinerPositionFx)(kPointer context, GoWebScanVisionInputMsg visionInput, k64s* firstTile, k64s* lastTile);

/**
 * Constructs a GoWebScanVisionCombiner object.
 *
 * @public              @memberof GoWebScanVisionCombiner
 * @param  combiner     Receives the constructed GoWebScanVisionCombiner object. 
 * @param  args         Algorithm parameters.
 * @param  allocator    Memory allocator (or kNULL for default). 
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanVisionCombiner_Construct(GoWebScanVisionCombiner* combiner, const GoWebScanVisionCombinerParams* args, kAlloc allocator);

/**
* Sets the handler for accepting the output data from the algorithm. Typically the 
* matched vision and profile tiles would be passed to the vision resampler algorithm.
*
* @public           @memberof GoWebScanVisionCombiner
* @param  combiner  GoWebScanVisionCombiner object. 
* @param  data      Callback function
* @param  context   Receiver argument for callback.
* @return           Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionCombiner_SetDataHandler(GoWebScanVisionCombiner combiner, GoWebScanVisionCombinerDataFx data, kPointer context);

/**
 * Sets the handler for determining the min and max Y-extents of the vision tile.
 * 
 * @public              @memberof GoWebScanVisionCombiner
 * @param  combiner     GoWebScanVisionCombiner object. 
 * @param  data         Callback function
 * @param  context      Receiver argument for callback.
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanVisionCombiner_SetPositionHandler(GoWebScanVisionCombiner combiner, GoWebScanVisionCombinerPositionFx data, kPointer context);

/**
 * Adds a vision or profile tile message to the algorithm processing queue.
 * 
 * @public              @memberof GoWebScanVisionCombiner
 * @param   combiner    GoWebScanVisionCombiner object.
 * @param   msg         Tile message to add. Message type ID should be
 *                      GO_WEB_SCAN_MSG_TYPE_VISION_INPUT or GO_WEB_SCAN_MSG_TYPE_PROFILE_TILE.
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanVisionCombiner_Add(GoWebScanVisionCombiner combiner, GoWebScanPipeMsg msg);

/**
* Clears and relinquishes all lane tile queues.
*
* @public                   @memberof GoWebScanVisionCombiner
* @param  combiner          GoWebScanVisionCombiner object. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionCombiner_Clear(GoWebScanVisionCombiner combiner);

#include <GoWebScanSdk/GoWebScanVisionCombiner.x.h>

#endif