GoWebScanCalCombiner.h

Go to the documentation of this file.

/**
* @file    GoWebScanCalCombiner.h
* @brief   Declares a GoWebScanCalCombiner 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_CAL_COMBINER_H
#define GO_WEB_SCAN_CAL_COMBINER_H

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

/**
* @struct  GoWebScanCalCombinerParams
* @extends kValue
* @ingroup GoWebScanSdk-Calibration
* @brief   Represents parameters of the calibration combiner algorithm.
*/
typedef struct GoWebScanCalCombinerParams
{
    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).
    k32s tileYExtent;                           ///< Y-axis extent of tiles (mils).
} GoWebScanCalCombinerParams; 

/**
* @class   GoWebScanCalCombiner
* @extends kObject
* @ingroup GoWebScanSdk-Calibration
* @brief   Represents an algorithm for importing sensor messages collected during system calibration,
*          matching the messages in Y and removing messages with time or distance coherency violations, 
*          and sending the system tiles for further calibration processing. This class is similar to 
*          the GoWebScanTileCombiner algorithm but is specialized to work with raw (unresampled) 
*          sensor data and to store data in calibration input message objects (GoWebScanCalInputTile).      
* @see     GoWebScanCalInputTile    
*/
typedef kObject GoWebScanCalCombiner;

/** Defines the signature for the handler for converting the encoder ticks to a Y-axis position in mils. */
typedef k64s (kCall *GoWebScanCalCombinerEncoderToYFx)(kPointer context, k64s encoder);  

/** Defines the signature for the handler for accepting the output dataset. */
typedef kStatus (kCall *GoWebScanCalCombinerDataFx)(kPointer context, k64s tileId, GoWebScanCalInputTile* input, kSSize laneCount);  

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

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

/**
* Sets the handler for converting the encoder ticks to a Y-axis position in mils.
*
* @public                   @memberof GoWebScanCalCombiner
* @param  combiner          GoWebScanCalCombiner object. 
* @param  encoderToY        Callback function
* @param  context           Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCalCombiner_SetEncoderToYHandler(GoWebScanCalCombiner combiner, GoWebScanCalCombinerEncoderToYFx encoderToY, kPointer context);

/**
 * Adds a lane to the combiner. A lane represents a unique source of messages (a node and a
 * specific data type).
 * 
 * @public              @memberof GoWebScanCalCombiner
 * @param   combiner    GoWebScanCalCombiner object.
 * @param   profileId   ID of profile sensor.
 * @param   visionId    ID of the connected vision sensor. Field will be ignored for non-vision
 *                      systems.
 * @param   bankId      Bank index of the node.
 * @param   planeId     System plane of the node.
 * @param   columnId    Column index of the node.
 * @param   type        Data source type.
 * @param   yOffset     Y-offset from laser/tracheid plane to the data source's plane (mils).
 * @param   minYStep    Minimum Y-interval for unique/retained data (mils).
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCalCombiner_AddLane(GoWebScanCalCombiner combiner, k32s profileId, k32s visionId, k32s bankId, GoWebScanSystemPlane planeId, k32s columnId, GoWebScanDataSource type, k64s yOffset, k32s minYStep); 

/**
 * Adds a message to a lane. Data is cloned into internal message objects.
 * 
 * @public              @memberof GoWebScanCalCombiner
 * @param   combiner    GoWebScanCalCombiner object.
 * @param   deviceId    Source device ID of message.
 * @param   dataSet     Sensor message.
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCalCombiner_AddMsg(GoWebScanCalCombiner combiner, k32s deviceId, GoDataSet dataSet);

/**
 * Flush any existing sensor messages currently in the pipeline.
 *
 * @public              @memberof GoWebScanCalCombiner
 * @param   combiner    GoWebScanCalCombiner object.
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCalCombiner_Flush(GoWebScanCalCombiner combiner);

/**
 * Gets the number of lanes.
 * 
 * @public              @memberof GoWebScanCalCombiner
 * @param   combiner    GoWebScanCalCombiner object.
 * @return              Number of lanes.
 */
GoWebScanFx(kSize) GoWebScanCalCombiner_LaneCount(GoWebScanCalCombiner combiner);

/**
 * Gets the system plane of the lane.
 * 
 * @public              @memberof GoWebScanCalCombiner
 * @param   combiner    GoWebScanCalCombiner object.
 * @param   index       Lane index.
 * @return              System plane.
 */
GoWebScanFx(GoWebScanSystemPlane) GoWebScanCalCombiner_LanePlaneAt(GoWebScanCalCombiner combiner, kSSize index); 

/**
* Gets the column index of the lane.
* 
* @public              @memberof GoWebScanCalCombiner
* @param   combiner    GoWebScanCalCombiner object.
* @param   index       Lane index.
* @return              Column index.
*/
GoWebScanFx(k32s) GoWebScanCalCombiner_LaneColumnAt(GoWebScanCalCombiner combiner, kSSize index); 

/**
* Gets the source data type of the lane.
* 
* @public              @memberof GoWebScanCalCombiner
* @param   combiner    GoWebScanCalCombiner object.
* @param   index       Lane index.
* @return              Source data type.
*/
GoWebScanFx(GoWebScanDataSource) GoWebScanCalCombiner_LaneSourceTypeAt(GoWebScanCalCombiner combiner, kSSize index); 

/**
* Gets the number of times a lane has been disabled.
* 
* @public              @memberof GoWebScanCalCombiner
* @param   combiner    GoWebScanCalCombiner object.
* @param   index       Lane index.
* @return              Disable count.
*/
GoWebScanFx(k64s) GoWebScanCalCombiner_LaneDisableCountAt(GoWebScanCalCombiner combiner, kSSize index); 

/**
* Gets the number of message drops in a lane.
* 
* @public              @memberof GoWebScanCalCombiner
* @param   combiner    GoWebScanCalCombiner object.
* @param   index       Lane index.
* @return              Drop count.
*/
GoWebScanFx(k64s) GoWebScanCalCombiner_LaneDropCountAt(GoWebScanCalCombiner combiner, kSSize index);

/**
* Gets a flag for whether the combiner is in an error state.
* 
* @public              @memberof GoWebScanCalCombiner
* @param   combiner    GoWebScanCalCombiner object.
* @return              Boolean for whether combiner is in an error state.
*/
GoWebScanFx(kBool) GoWebScanCalCombiner_IsBroken(GoWebScanCalCombiner combiner); 

#include <GoWebScanSdk/GoWebScanCalCombiner.x.h>

#endif