GoWebScanProcess.h

Go to the documentation of this file.

/**
* @file    GoWebScanProcess.h
* @brief   Declares a GoWebScanProcess 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_PROCESS_H
#define GO_WEB_SCAN_PROCESS_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>
#include <GoWebScanSdk/GoWebScanConfig.h>
#include <GoWebScanSdk/GoWebScanPipeMsg.h>
#include <GoWebScanSdk/GoWebScanTileCombiner.h>
#include <GoWebScanSdk/GoWebScanRecording.h>

typedef enum
{
    GO_WEB_SCAN_PROCESS_RECORD_STATUS_OK,
    GO_WEB_SCAN_PROCESS_RECORD_STATUS_STOPPED_AT_MAX_BOARD_COUNT,
    GO_WEB_SCAN_PROCESS_RECORD_STATUS_STOPPED_AT_MEMORY_LIMIT

} GoWebScanProcessRecordStatus;

/**
* @class   GoWebScanProcess
* @extends kObject
* @ingroup GoWebScanSdk-Control
* @brief   Represents a task for processing raw sensor data to produce system web tiles (Web
*          mode) or detected objects (Detection mode).  
*          The GoWebScanProcess class accepts configuration via a GoWebScanConfig instance, and 
*          provides a simple API to initialize the processor, pass sensor data to the processor,
*          retrieve completed system messages, and clear the processor. Internally, the 
*          processor delegates processing responsibilities to the Task classes in the Control 
*          group. A GoWebScanProcess object can optionally run processing tasks concurrently. 
*          Tasks are run when they receive messages, and messages are passed from task to task 
*          as processing steps execute. Task execution and message exchange are supported by 
*          the classes in the Pipe group.
*          
*          A GoWebScanProcess object has a GoWebScanPipe object, and each GoWebScanProcess Task 
*          object (e.g. GoWebScanProfileSampleTask) has an associated GoWebScanPipeTask. 
*          Individual processor tasks are passed references to downstream tasks (receivers) at 
*          initialization time (e.g  a GoWebScanProfileSampleTask has a reference to the 
*          GoWebScanSyncTask to which it sends messages).
*          
*          Following initialization, the user application should pass inbound sensor messages
*          to the GoWebScanProcess. The GoWebScanProcess handles the initial dispatch to various 
*          data sampling tasks.  From there, messages flow from task to task, eventually 
*          resulting in outbound messages sent back to the GoWebScanProcess. Outbound messages 
*          are queued by the GoWebScanProcess object and can be accepted by the user application
*          at any time. 

*/
typedef kObject GoWebScanProcess;

/**
* Constructs a GoWebScanProcess object.
* 
* @public              @memberof GoWebScanProcess
* @param   process     Receives the constructed GoWebScanProcess object.
* @param   config      System configuration.
* @param   allocator   Memory allocator (or kNULL for default).
* @return              Operation status.
*/
GoWebScanFx(kStatus) GoWebScanProcess_Construct(GoWebScanProcess* process, GoWebScanConfig config, kAlloc allocator);

/**
 * Accepts inbound sensor message sets and dispatches the messages to data processing tasks. The
 * messages are cloned into internal message objects. As such, the GoDataSet object is still
 * owned by the calling function and must be destroyed by it. If recording is enabled, GoWebScanProcess
 * will record copies of all the GoDataSet objects, in the order they are processed.
 * 
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @param   dataSet Set of sensor messages. Must have one of type GO_DATA_MESSAGE_TYPE_STAMP with
 *                  remaining messages of type GO_DATA_MESSAGE_TYPE_PROFILE for profile,
 *                  GO_DATA_MESSAGE_TYPE_TRACHEID for tracheid, or GO_DATA_MESSAGE_TYPE_VIDEO for
 *                  vision.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_Process(GoWebScanProcess process, GoDataSet dataSet);

/**
 * Returns outbound processed results if any are available. The function will return an error if
 * the outbound queue is empty (no new result available), and so the function can be run in a
 * loop until it fails to receive all results in the queue. Ownership of the result is passed
 * to the calling function. The result will be of type GoWebScanSystemMsg and will contain tiles
 * for all data types (profile, tracheid, or vision) and planes (top or bottom) in the system.
 * GoWebScanSystemMsg_TileAt() can be used to retrieve the system tiles for a specific data type
 * and plane.
 * 
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @param   msg     Receives the outbound processed result. Should be cast into a GoWebScanSystemMsg.
 * @param   timeout Timeout for receiving result (in microseconds). kINFINITE to wait indefinitely.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_Receive(GoWebScanProcess process, GoWebScanPipeMsg* msg, k64s timeout);

/**
 * Initializes the processing tasks. Should be called prior to GoWebScanProcess_Process().
 * 
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_Start(GoWebScanProcess process);

/**
 * Aborts all outstanding processing and resets the state. 
 * 
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_Clear(GoWebScanProcess process);

/**
 * Gets the current count of errors in the processor.
 * 
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Error count.
 */
GoWebScanFx(kSSize) GoWebScanProcess_ErrorCount(GoWebScanProcess process);

/**
 * Return whether or not recording is enabled. If recording is enabled, GoWebScanProcess
 * will record copies of all the GoDataSet objects, in the order they are processed.
 *
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Recording enabled.
 */
GoWebScanFx(kBool) GoWebScanProcess_RecordingEnabled(GoWebScanProcess process);

/**
 * Enable or disable recording. If recording is enabled, GoWebScanProcess will record copies 
 * of all the GoDataSet objects, in the order they are processed.
 *
 * @public                      @memberof GoWebScanProcess
 * @param   process             GoWebScanProcess object.
 * @param   recordingEnabled    kTRUE to enable recording, or kFALSE to disable recording.
 * @return                      Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_EnableRecording(GoWebScanProcess process, kBool recordingEnabled);

/**
 * Return the number of GoDataSet objects that have been recorded.
 *
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Number of recorded GoDataSet objects.
 */
GoWebScanFx(kSize) GoWebScanProcess_DataSetCount(GoWebScanProcess process);

/**
 * Save a file containing the recorded GoDataSet objects to the specified file path.
 *
 * @public              @memberof GoWebScanProcess
 * @param   process     GoWebScanProcess object.
 * @param   filePath    Path to save to.
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_SaveRecording(GoWebScanProcess process, const kChar* filePath);

/**
 * Clear the recorded GoDataSet objects. As such, the number of processed boards corresponding to the recorded
 * data will become zero.
 *
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_ClearRecording(GoWebScanProcess process);

/**
 * Access a recorded GoDataSet object by index.
 *
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @param   index   Recorded GoDataSet index.
 * @return          Pointer to the recorded GoDataSet.
 */
GoWebScanFx(const GoDataSet*) GoWebScanProcess_DataSetAt(GoWebScanProcess process, kSize index);

/**
 * Return the number of boards processed from GoDataSet objects that were recorded.
 *
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Number of boards processed with recorded data.
 */
GoWebScanFx(kSize) GoWebScanProcess_RecordBoardCount(GoWebScanProcess process);

/**
 * Return the max number of boards that may result from the recorded GoDataSet objects. Once this
 * value is reached, additional GoDataSet objects are no longer recorded.
 *
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Number of boards processed with recorded data.
 */
GoWebScanFx(kSize) GoWebScanProcess_MaxRecordBoardCount(GoWebScanProcess process);

/**
 * Set the max number of boards that may result from the recorded GoDataSet objects. Once this value 
 * is reached, additional GoDataSet objects are no longer recorded. This function may not be called
 * if any GoDataSet object has been recorded, and will return kERROR_STATE in such a case. The recording
 * must first be cleared by calling GoWebScanProcess_ClearRecording.
 *
 * @public                      @memberof GoWebScanProcess
 * @param   process             GoWebScanProcess object.
 * @param   maxRecordBoardCount Number of boards to record data for.
 * @return                      Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_SetMaxRecordBoardCount(GoWebScanProcess process, kSize maxRecordBoardCount);

/**
 * Return the approximate total size in bytes of the recorded GoDataSet objects.
 *
 * @public                  @memberof GoWebScanProcess
 * @param   process         GoWebScanProcess object.
 * @return                  Size in bytes of recorded GoDataSet objects.
 */
GoWebScanFx(k64u) GoWebScanProcess_RecordSize(GoWebScanProcess process);

/**
 * Return the max allowed size in bytes of the recorded GoDataSet objects. Once this value is reached, 
 * additional GoDataSet objects are no longer recorded.
 *
 * @public          @memberof GoWebScanProcess
 * @param   process GoWebScanProcess object.
 * @return          Max size in bytes of recorded GoDataSet objects.
 */
GoWebScanFx(k64u) GoWebScanProcess_MaxRecordSize(GoWebScanProcess process);

/**
 * Set the max allowed size in bytes of the recorded GoDataSet objects. Once this value
 * is reached, additional GoDataSet objects are no longer recorded. This function may not be called
 * if any GoDataSet object has been recorded, and will return kERROR_STATE in such a case. The recording
 * must first be cleared by calling GoWebScanProcess_ClearRecording.
 *
 * @public                  @memberof GoWebScanProcess
 * @param   process         GoWebScanProcess object.
 * @param   maxRecordSize   Max size in bytes of recorded GoDataSet objects.
 * @return                  Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_SetMaxRecordSize(GoWebScanProcess process, k64u maxRecordSize);

/**
 * Get the recording of processed sensor message sets.
 *
 * @public                  @memberof GoWebScanProcess
 * @param   process         GoWebScanProcess object.
 * @return                  The recording.
 */
GoWebScanFx(GoWebScanRecording) GoWebScanProcess_Recording(GoWebScanProcess process);

/**
 * Return the status of the GoDataSet object recording functionality. A status of 
 * GO_WEB_SCAN_PROCESS_RECORD_STATUS_OK indicates there are no issues. A status of
 * GO_WEB_SCAN_PROCESS_RECORD_STATUS_STOPPED_AT_MAX_BOARD_COUNT indicates that recording has
 * stopped, despite being enabled, since the max number of boards resulting from recorded data
 * has been reached. A status of GO_WEB_SCAN_PROCESS_RECORD_STATUS_STOPPED_AT_MEMORY_LIMIT
 * indicates that recording has stopped, despite being enabled, since the max specified recording size
 * in bytes has been reached.
 *
 * @public                  @memberof GoWebScanProcess
 * @param   process         GoWebScanProcess object.
 * @return                  Recording status.
 */
GoWebScanFx(GoWebScanProcessRecordStatus) GoWebScanProcess_ProcessRecordStatus(GoWebScanProcess process);

/**
 * Sets a callback function that can be used to receive output board data asynchronously.
 *
 * Sensor data messages can be received synchronously using the GoWebScanProcess_Receive function
 * or asynchronously by registering a callback function.  If a callback function is registered,
 * a background thread will be created to perform notifications.
 *
 * To unregister a previously-registered data handler, call this function using kNULL in place
 * of the callback function argument.
 *
 * @public                  @memberof GoWebScanProcess
 * @param   process         GoWebScanProcess object.
 * @param   function        Data callback function (or kNULL to unregister).
 * @param   receiver        Receiver argument for callback.
 * @return                  Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_SetDataHandler(GoWebScanProcess process, GoDataFx function, kPointer receiver);

/**
 * Refresh the process. This must be called prior to starting if there are any changes to the config.
 *
 * @public                  @memberof GoWebScanProcess
 * @param   process         GoWebScanProcess object.
 * @return                  Operation status.
 */
GoWebScanFx(kStatus) GoWebScanProcess_Refresh(GoWebScanProcess process);

/**
* Set handler for when sync task disables a camera lane. Function calls for disabling or enabling a lane enter an asynchronous queue.
updated
*
* @public                   @memberof GoWebScanProcess
* @param  process           GoWebScanProcess object.
* @param  function          Callback function.
* @param  receiver          Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanProcess_SetLaneDisabledHandler(GoWebScanProcess process, GoWebScanTileCombinerLaneChangeFx function, kPointer receiver);

/**
* Set handler for when sync task re-enables a camera lane. Function calls for disabling or enabling a lane enter an asynchronous queue.
*
* @public                   @memberof GoWebScanProcess
* @param  process           GoWebScanProcess object.
* @param  function          Callback function.
* @param  receiver          Receiver argument for callback.
* @return                   Operation status.
*/
GoWebScanFx(kStatus) GoWebScanProcess_SetLaneEnabledHandler(GoWebScanProcess process, GoWebScanTileCombinerLaneChangeFx function, kPointer receiver);

#include <GoWebScanSdk/GoWebScanProcess.x.h>

#endif