GoWebScanDetector.h

Go to the documentation of this file.

/**
* @file    GoWebScanDetector.h
* @brief   Declares a GoWebScanDetector 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_DETECTOR_H
#define GO_WEB_SCAN_DETECTOR_H

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

/**
* @struct  GoWebScanDetectorParams
* @extends kValue
* @ingroup GoWebScanSdk-Algorithms
* @brief   Represents parameters of the detection algorithm.
*/
typedef struct GoWebScanDetectorParams
{
    kSSize tileColumns;                             ///< Expected width of input web tiles
    kSSize tileRows;                                ///< Expected length of input web tiles
    GoWebScanDetectionStyle detectionStyle;         ///< Method for triggering start of board
    k32s detectionColumns;                          ///< Threshold for minimum number of non-null columns to trigger start of board
    kSSize minRows;                                 ///< Minimum number of rows of detected board
    kSSize maxRows;                                 ///< Maximum number of rows of detected board
    kSSize minGapRows;                              ///< Minimum number of rows between consecutive detected boards
    kSSize marginRows;                              ///< Size of top and bottom margin added to detected board output
} GoWebScanDetectorParams;

/**
* @class   GoWebScanDetector
* @extends kObject
* @ingroup GoWebScanSdk-Algorithms
* @brief   Represents an algorithm for detecting discrete objects (typically boards) within web tiles.
*          The algorithm maintains an internal queue of web messages (tiles), and examines presence 
*          data one row at a time to determine if an object is currently detected.  A simple state 
*          machine is used to determine when to emit objects.
*          
*          The start of a board is triggered by a minimum number of non-null profiles. The detection
*          style can either be global, meaning the non-null profiles can be disconnected, or local,
*          which imposes the condition than the non-null profiles are contiguous.
*/
typedef kObject GoWebScanDetector;

/** Defines the signature for the handler for accepting the completed board. */
typedef kStatus(kCall *GoWebScanDetectorDataFx)(kPointer context, k64s tileIndex, GoWebScanSystemMsg* tiles, kSSize tileCount);

/**
* Constructs a GoWebScanDetector object.
*
* @public                   @memberof GoWebScanDetector
* @param  detector          Receives the constructed GoWebScanDetector object. 
* @param  args              Detector algorithm parameters.
* @param  allocator         Memory allocator (or kNULL for default). 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanDetector_Construct(GoWebScanDetector* detector, const GoWebScanDetectorParams* args, kAlloc allocator);

/**
* Sets the handler for accepting the completed board.
*
* @public                   @memberof GoWebScanDetector
* @param  detector          GoWebScanDetector object. 
* @param  data              Callback function
* @param  context           Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanDetector_SetDataHandler(GoWebScanDetector detector, GoWebScanDetectorDataFx data, kPointer context);

/**
* Adds an input web tile to processing queue.
*
* @public                   @memberof GoWebScanDetector
* @param  detector          GoWebScanDetector object. 
* @param  msg               Tile message to add.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanDetector_AddTile(GoWebScanDetector detector, GoWebScanPipeMsg msg);

/**
* Clears and relinquishes input tile queue.
*
* @public                   @memberof GoWebScanDetector
* @param  detector          GoWebScanDetector object. 
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanDetector_Clear(GoWebScanDetector detector);

#include <GoWebScanSdk/GoWebScanDetector.x.h>

#endif