GoWebScanTileCombiner.h

Go to the documentation of this file.

/**
* @file    GoWebScanTileCombiner.h
* @brief   Declares a GoWebScanTileCombiner 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_TILE_COMBINER_H
#define GO_WEB_SCAN_TILE_COMBINER_H

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

/**
* @class   GoWebScanTileCombiner
* @extends kObject
* @ingroup GoWebScanSdk-Algorithms
* @brief   Represents an algorithm for matching tiles received from different sources. Each source 
*          is represented by a combiner lane, which has a FIFO queue of received tiles.  When a tile 
*          is received, the combiner logic decides whether to emit a frame (set of tiles that have 
*          the same position) or wait. A time threshold and a distance threshold must both be 
*          exceeded to cause a coherency violation. The primary consideration is time - when a lane 
*          has not received a frame within the specified time window, something has gone wrong and  
*          the lane should be disabled as soon as possible. But if the system reverses (no new tiles), 
*          and then runs forward again (new tiles when it catches up), a false coherency violation can 
*          be generated if time is the only criteria.  A small distance coherency threshold is used to 
*          prevent these false violations. 
*/
typedef kObject GoWebScanTileCombiner;

/**
* @struct  GoWebScanTileCombinerParams
* @extends kValue
* @ingroup GoWebScanSdk-Algorithms
* @brief   Represents parameters of the tile combiner algorithm.
*/
typedef struct GoWebScanTileCombinerParams
{
    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).
    k64s breakDistance;                 ///< While the first undelivered tile and last undelivered tile have a position difference greater than this threshold, all combiner frames are dropped (mils).

} GoWebScanTileCombinerParams;

/** Defines the signature for the handler for accepting the output dataset. */
typedef kStatus(kCall *GoWebScanTileCombinerDataFx)(kPointer context, k64s tileIndex, GoWebScanPipeMsg* tiles, kSSize laneCount, kSSize tileCount);

/** Defines the signature for the handler for a lane being enabled or disabled. */
typedef kStatus(kCall* GoWebScanTileCombinerLaneChangeFx)(kPointer context, const k32s* id, kSize length);

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

/**
* Adds a lane to the combiner. A lane represents a unique source of tiles and is identified by
* the 4 element ID field in the tile message stamp.
*
* @public                   @memberof GoWebScanTileCombiner
* @param  combiner          GoWebScanTileCombiner object. 
* @param  msgId             Message type ID.
* @param  id1               Second element of lane ID.
* @param  id2               Third element of lane ID.
* @param  id3               Fourth element of lane ID.
* @return                   Operation status.
* @see                      GoWebScanMsgStamp
*/
GoWebScanFx(kStatus) GoWebScanTileCombiner_AddLane(GoWebScanTileCombiner combiner, k32s msgId, k32s id1, k32s id2, k32s id3);

/**
* Removes all lanes from the combiner. A lane represents a unique source of tiles and is identified by
* the 4 element ID field in the tile message stamp.
*
* @public                   @memberof GoWebScanTileCombiner
* @param  combiner          GoWebScanTileCombiner object.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanTileCombiner_RemoveLanes(GoWebScanTileCombiner combiner);

/**
* Sets the handler for accepting the output data from the algorithm.
*
* @public                   @memberof GoWebScanTileCombiner
* @param  combiner          GoWebScanTileCombiner object. 
* @param  data              Callback function
* @param  context           Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanTileCombiner_SetDataHandler(GoWebScanTileCombiner combiner, GoWebScanTileCombinerDataFx data, kPointer context);

/**
* Adds a tile message to the algorithm processing queue. The tile is added to the lane that
* corresponds to the message stamp ID.
*
* @public                   @memberof GoWebScanTileCombiner
* @param  combiner          GoWebScanTileCombiner object. 
* @param  msg               Tile message to add.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanTileCombiner_AddTile(GoWebScanTileCombiner combiner, GoWebScanPipeMsg msg);

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

/**
* Gets the lane ID for a given lane index.
*
* @public                   @memberof GoWebScanTileCombiner
* @param  combiner          GoWebScanTileCombiner object. 
* @param  index             Lane index.
* @param  id0               Receives the first element of the lane ID.
* @param  id1               Receives the second element of the lane ID.
* @param  id2               Receives the third element of the lane ID.
* @param  id3               Receives the fourth element of the lane ID.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanTileCombiner_LaneAt(GoWebScanTileCombiner combiner, kSSize index, k32s* id0, k32s* id1, k32s* id2, k32s* id3);

/**
* Set handler for when lane is disabled. Function calls for disabling or enabling a lane enter an asynchronous queue.
*
* @public                   @memberof GoWebScanTileCombiner
* @param  combiner          GoWebScanTileCombiner object.
* @param  function          Callback function.
* @param  receiver          Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanTileCombiner_SetLaneDisabledHandler(GoWebScanTileCombiner combiner, GoWebScanTileCombinerLaneChangeFx function, kPointer receiver);

/**
* Set handler for when lane is re-enabled. Function calls for disabling or enabling a lane enter an asynchronous queue.
*
* @public                   @memberof GoWebScanTileCombiner
* @param  combiner          GoWebScanTileCombiner object.
* @param  function          Callback function.
* @param  receiver          Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanTileCombiner_SetLaneEnabledHandler(GoWebScanTileCombiner combiner, GoWebScanTileCombinerLaneChangeFx function, kPointer receiver);

#include <GoWebScanSdk/GoWebScanTileCombiner.x.h>

#endif