GoWebScanDetectionTask.h

Go to the documentation of this file.

/**
* @file    GoWebScanDetectionTask.h
* @brief   Declares a GoWebScanDetectionTask 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_DETECTION_TASK_H
#define GO_WEB_SCAN_DETECTION_TASK_H

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

/**
* @class   GoWebScanDetectionTask
* @extends kObject
* @ingroup GoWebScanSdk-Control
* @brief   Represents a task for identifying discrete objects within presence data, aggregating 
*          web tiles into complete objects, performing optional post-processing, and emitting the 
*          results. GoWebScanDetectionTask is only used in Detection Mode, and is the final stage 
*          before results are delivered back to the GoWebScanProcess object. 
*          
*          Upon arrival, web messages are immediately added to a GoWebScanDetector object, which 
*          identifies groups of tiles forming a complete object. When the GoWebScanDetector finds 
*          a complete object, a detector frame is passed back to GoWebScanDetectionTask for 
*          processing.  Individual web tiles are appended to form object-sized images (one image 
*          per top/bottom group and per profile/vision/tracheid type), which are then (optionally) 
*          post-processed. The final results are combined into a single GoWebScanSystemMsg and 
*          emitted from GoWebScanDetectionTask.
*          
*          Processing steps:
*          -# GoWebScanSystemMsg objects from GoWebScanWebTask are added to the GoWebScanDetector
*              algorithm.
*          -# After the detector has found a complete object, the task combines the web tiles 
*              containing the object.
*          -# If the edge filter option is enabled, edge spikes and disconnected regions are
*              filtered.
*          -# If the background filter is enabled, the background of tracheid and vision data is
*              removed.
*          -# The final GoWebScanSystemMsg is emitted.
* @see     GoWebScanDetector, GoWebScanWebTask, GoWebScanSystemMsg, GoWebScanEdgeFilter
*/
typedef kObject GoWebScanDetectionTask;

// Forward declaration
typedef kObject GoWebScanProcess;

/**
 * Constructs a GoWebScanDetectionTask object.
 * 
 * @public              @memberof GoWebScanDetectionTask
 * @param   task        Receives the constructed GoWebScanDetectionTask object.
 * @param   process     Associated GoWebScanProcess object which will receive the detected result.
 * @param   config      System configuration.
 * @param   allocator   Memory allocator (or kNULL for default).
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanDetectionTask_Construct(GoWebScanDetectionTask* task, GoWebScanProcess process, GoWebScanConfig config, kAlloc allocator);

/**
* Sets the handler for receiving emitted detected boards.
*
* @public           @memberof GoWebScanDetectionTask
* @param  task      GoWebScanDetectionTask object. 
* @param  send      Callback function
* @param  context   Receiver argument for callback.
* @return           Operation status.
*/
GoWebScanFx(kStatus) GoWebScanDetectionTask_SetReceiver(GoWebScanDetectionTask task, GoWebScanPipeSendFx send, kPointer context);

/**
 * Adds a message to the processing queue. Dequeues a message at the end of the queue to submit
 * to the pipe for scheduling if no other job is currently pending.
 * 
 * @public          @memberof GoWebScanDetectionTask
 * @param   task    GoWebScanDetectionTask object.
 * @param   msg     Message to enqueue.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanDetectionTask_Send(GoWebScanDetectionTask task, GoWebScanPipeMsg msg);

/**
 * Clears detector algorithm and resets internal variables.
 * 
 * @public          @memberof GoWebScanDetectionTask
 * @param   task    GoWebScanDetectionTask object.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanDetectionTask_Clear(GoWebScanDetectionTask task);

#include <GoWebScanSdk/GoWebScanDetectionTask.x.h>

#endif