GoWebScanVisionSampleTask.h

Go to the documentation of this file.

/**
* @file    GoWebScanVisionSampleTask.h
* @brief   Declares a GoWebScanVisionSampleTask 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_VISION_SAMPLE_TASK_H
#define GO_WEB_SCAN_VISION_SAMPLE_TASK_H

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

/**
 * @class   GoWebScanVisionSampleTask
 * @extends kObject
 * @ingroup GoWebScanSdk-Control
 * @brief   Represents a task for resampling raw vision data to generate vision tiles for a single camera.
 *          The task uses vision input data and terrain tiles, which are profile tiles that are sampled at
 *          a resolution appropriate for use by the vision sampler, and which has all of its null values
 *          filled in with best-guess values. The task accepts GoWebScanVisionInputMsg objects and
 *          GoWebScanProfileTileMsg objects (for presence data) and produces GoWebScanVisionTileMsg
 *          objects.
 * 
 *          When vision input or profile tile messages are received, they are passed immediately to the
 *          vision combiner, which retains messages until sufficient profile data is available cover the
 *          maximum potential Y-extent of the next vision message. When the vision combiner produces a
 *          frame, which includes a single vision input message and corresponding terrain tiles, the
 *          vision input is processed and then passed to the vision resampler. The vision resampler emits
 *          completed rows as they become available, and those rows are added to an output tile.
 *          
 *          Tiles emitted by the VisionSampleTask can contain null pixels. These occur when the field of 
 *          view of the camera is insufficient to cover the tile, when the speed of the system is too 
 *          great, resulting in Y-gaps between images, or when input images have been dropped. The x 
 *          field of the kRbg structure contains a zero value to indicate a null pixel, or a non-zero 
 *          value to indicate a valid pixel.
 *          
 *          Processing steps:
 *          -# Vision input and profile tile messages passed to vision combiner.
 *          -# Vision combiner matches vision input to a set of profile tiles. 
 *          -# Vision input is reoriented to standard system orientation.
 *          -# Gains from system calibration are applied to the vision input channels.
 *          -# Vision input is demosaiced to form an RGB image.
 *          -# Vision input is added to the GoWebScanVisionResampler algorithm.  
 *          -# Resampled row is assembled into emitted GoWebScanVisionTileMsg.
 * @see     GoWebScanVisionCombiner, GoWebScanVisionResampler, GoWebScanVisionTileMsg
*/
typedef kObject GoWebScanVisionSampleTask;

// Forward declaration
typedef kObject GoWebScanProcess;

/**
* Constructs a GoWebScanVisionSampleTask object.
* 
* @public              @memberof GoWebScanVisionSampleTask
* @param   task        Receives the constructed GoWebScanVisionSampleTask object.
* @param   process     Associated GoWebScanProcess object.
* @param   configNode  Node configuration.
* @param   allocator   Memory allocator (or kNULL for default).
* @return              Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionSampleTask_Construct(GoWebScanVisionSampleTask* task, GoWebScanProcess process, GoWebScanConfigNode configNode, kAlloc allocator);

/**
* Sets the handler for receiving resampled vision tiles.
*
* @public           @memberof GoWebScanVisionSampleTask
* @param  task      GoWebScanVisionSampleTask object. 
* @param  send      Callback function
* @param  context   Receiver argument for callback.
* @return           Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionSampleTask_SetReceiver(GoWebScanVisionSampleTask task, GoWebScanPipeSendFx send, kPointer context);

/**
* Dispatches a processing job (task + message) to the pipe. Sends the message to a task's
* message queue. The task will submit the message to the pipe for processing if no other job is
* pending.
* 
* @public          @memberof GoWebScanVisionSampleTask
* @param   task    GoWebScanVisionSampleTask object.
* @param   msg     Message to dispatch.
* @return          Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionSampleTask_Dispatch(GoWebScanVisionSampleTask task, GoWebScanPipeMsg msg);

/**
* 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 GoWebScanVisionSampleTask
* @param   task    GoWebScanVisionSampleTask object.
* @param   msg     Vision input message to enqueue.
* @return          Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionSampleTask_Send(GoWebScanVisionSampleTask task, GoWebScanPipeMsg msg);

/**
* Clears the vision combiner and vision resampler algorithms and resets internal variables.
* 
* @public          @memberof GoWebScanVisionSampleTask
* @param   task    GoWebScanVisionSampleTask object.
* @return          Operation status.
*/
GoWebScanFx(kStatus) GoWebScanVisionSampleTask_Clear(GoWebScanVisionSampleTask task);

/**
* Gets the node configuration for the node associated with this task.
* 
* @public          @memberof GoWebScanVisionSampleTask
* @param   task    GoWebScanVisionSampleTask object.
* @return          Node configuration.
*/
GoWebScanFx(GoWebScanConfigNode) GoWebScanVisionSampleTask_ConfigNode(GoWebScanVisionSampleTask task);

#include <GoWebScanSdk/GoWebScanVisionSampleTask.x.h>

#endif