GoWebScanCalProcessor.h

Go to the documentation of this file.

/**
* @file    GoWebScanCalProcessor.h
* @brief   Declares a GoWebScanCalProcessor 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_PROCESSOR_H
#define GO_WEB_SCAN_CAL_PROCESSOR_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>
#include <GoWebScanSdk/GoWebScanCalInput.h>
#include <GoWebScanSdk/GoWebScanCalInputNode.h>
#include <GoWebScanSdk/GoWebScanCalNode.h>
#include <GoWebScanSdk/GoWebScanConfig.h>
#include <GoWebScanSdk/GoWebScanConfigGroup.h>
#include <GoWebScanSdk/GoWebScanCal.h>

/**
* @struct  GoWebScanCalCombinerParams
* @extends kValue
* @ingroup GoWebScanSdk-Calibration
* @brief   Represents parameters of the calibration combiner algorithm.
*/
typedef struct GoWebScanCalProcessorIssue
{
    GoWebScanCalActivity activity;  ///< Stage or activity in the system calibration processing during which the vision issue occurred.
    GoWebScanCalNodeStatus status;  ///< Type of issue.
    k32s sensorId;                  ///< Sensor serial number.
    kSSize bankId;                  ///< Sensor camera index.

} GoWebScanCalProcessorIssue;

/**
* @class   GoWebScanCalProcessor
* @extends kObject
* @ingroup GoWebScanSdk-Calibration
* @brief   Represents an algorithm for processing system tiles containing a calibration bar
*          and generating the calibration containing profile Z and Y offsets and vision Y 
*          offsets and gains. Refer to GoWebScanCal for a description of the system 
*          calibration outputs and usage.
*          
*          Internally, GoWebScanCalProcessor delegates the processing of offsets and gains 
*          for each node to the GoWebScanCalProcessorNode class. After each node has been
*          processed, GoWebScanCalProcessor adjusts the profile and vision Y offsets per
*          node based on the overall system Y bias (per plane). If 
*          GoWebScanConfig_CalDetectLocators() is enabled, the class also calculates the X 
*          bias per plane and adjusts the node X offsets. If 
*          GoWebScanConfig_CalUseVisionIntensity() is not enabled, the class also calculates
*          the vision gain bias per channel and adjusts the node gains. 
*          
*          At the end of processing, a GoWebScanCal object is constructed and returned
*          containing the offsets, gains, and other calibration properties.
*          
*          Refer to GoWebScanCalProcessorNode for a detailed explanation of the calibration
*          processing sequence.
* @see     GoWebScanCal, GoWebScanCalProcessorNode, GoWebScanConfig_CalDetectLocators, 
*          GoWebScanConfig_CalUseVisionIntensity
*/
typedef kObject GoWebScanCalProcessor;

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

/**
 * Executes the system calibration processing on an input dataset (consisting of
 * Y-matched tile containing the calibration bar) and constructs and outputs
 * the calibration object. Refer to GoWebScanCal for a description of the system 
 * calibration outputs and usage.
 * 
 * @public              @memberof GoWebScanCalProcessor
 * @param   processor   GoWebScanCalProcessor object.
 * @param   input       Calibration input dataset.
 * @param   calibration Receives the constructed GoWebScanCal object.
 * @return              Operation status.
 * @see                 GoWebScanCal, GoWebScanCalProcessorNode
 */
GoWebScanFx(kStatus) GoWebScanCalProcessor_Execute(GoWebScanCalProcessor processor, GoWebScanCalInput input, GoWebScanCal* calibration);

/**
 * Gets a flag for whether the processing of profile data had any warnings. Warnings 
* mean the calibration completed but may be suboptimal.
 * 
 * @public              @memberof GoWebScanCalProcessor
 * @param   processor   GoWebScanCalProcessor object.
 * @return              Boolean for whether profile calibration processing had warnings.
 */
GoWebScanFx(kBool) GoWebScanCalProcessor_ProfileHasWarnings(GoWebScanCalProcessor processor);

/**
* Gets a flag for whether the processing of vision data had any warnings. Warnings 
* mean the calibration completed but may be suboptimal.
* 
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @return              Boolean for whether vision calibration processing had warnings.
*/
GoWebScanFx(kBool) GoWebScanCalProcessor_VisionHasWarnings(GoWebScanCalProcessor processor);

/**
* Gets a flag for whether the processing of profile data had any errors. Errors mean all
* or some aspects of the processing were not able to proceed and the generated 
* calibration file may be incomplete.
* 
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @return              Boolean for whether profile calibration processing had errors.
*/
GoWebScanFx(kBool) GoWebScanCalProcessor_ProfileHasErrors(GoWebScanCalProcessor processor);

/**
* Gets a flag for whether the processing of vision data had any errors. Errors mean all
* or some aspects of the processing were not able to proceed and the generated 
* calibration file may be incomplete.
* 
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @return              Boolean for whether vision calibration processing had errors.
*/
GoWebScanFx(kBool) GoWebScanCalProcessor_VisionHasErrors(GoWebScanCalProcessor processor);

/**
* Gets the number of system calibration processor nodes.
*
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @return              Count of processor nodes.
*/
GoWebScanFx(kSize) GoWebScanCalProcessor_NodeCount(GoWebScanCalProcessor processor);

/**
* Gets the number of profile issues that occurred during system calibration processing.
*
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @param   nodeIndex   Index of calibration processor node.
* @return              Count of issues.
*/
GoWebScanFx(kSize) GoWebScanCalProcessor_ProfileIssueCount(GoWebScanCalProcessor processor, kSize nodeIndex);

/**
* Gets the profile issue that occurred during system calibration processing at the specified index.
*
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @param   nodeIndex   Index of calibration processor node.
* @param   issueIndex  Index of profile issue.
* @return              Struct containing information on the issue.
*/
GoWebScanFx(GoWebScanCalProcessorIssue) GoWebScanCalProcessor_ProfileIssueAt(GoWebScanCalProcessor processor, kSize nodeIndex, kSize issueIndex);

/**
* Gets the number of vision issues that occurred during system calibration processing.
*
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @param   nodeIndex   Index of calibration processor node.
* @return              Count of issues.
*/
GoWebScanFx(kSize) GoWebScanCalProcessor_VisionIssueCount(GoWebScanCalProcessor processor, kSize nodeIndex);

/**
* Gets the vision issue that occurred during system calibration processing at the specified index.
*
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @param   nodeIndex   Index of calibration processor node.
* @param   issueIndex  Index of vision issue.
* @return              Struct containing information on the issue.
*/
GoWebScanFx(GoWebScanCalProcessorIssue) GoWebScanCalProcessor_VisionIssueAt(GoWebScanCalProcessor processor, kSize nodeIndex, kSize issueIndex);

/**
* Reset the processor to its original state.
*
* @public              @memberof GoWebScanCalProcessor
* @param   processor   GoWebScanCalProcessor object.
* @return              Struct containing information on the issue.
*/
GoWebScanFx(kStatus) GoWebScanCalProcessor_Reset(GoWebScanCalProcessor processor);

#include <GoWebScanSdk/GoWebScanCalProcessor.x.h>

#endif