GoWebScanCalProcessorNode.h

Go to the documentation of this file.

/**
* @file    GoWebScanCalProcessorNode.h
* @brief   Declares a GoWebScanCalProcessorNode 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_NODE_H
#define GO_WEB_SCAN_CAL_PROCESSOR_NODE_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>
#include <GoWebScanSdk/GoWebScanCalInput.h>
#include <GoWebScanSdk/GoWebScanConfigNode.h>

/**
* @class   GoWebScanCalProcessorNode
* @extends kObject
* @ingroup GoWebScanSdk-Calibration
* @brief   Represents an algorithm for processing node tiles containing a calibration bar,
*          and generating node profile Z and Y offsets and vision Y offsets and gains. 
*          Refer to GoWebScanCal for a description of the system calibration outputs and 
*          usage.
*          
*          GoWebScanCalProcessorNode executes a sequence of processing tasks for profile
*          and vision data. If a task fails in the sequence, the processing does not 
*          continue and an error and issue type is recorded. Vision processing will not
*          proceed if profile processing fails. Any warnings (issues that do not prevent 
*          processing from completing but may result in suboptimal calibration) that 
*          occur are recorded.
*          
*          For profile processing, the sequence is as follows:
*          -# The input profile data is inspected for any frame drops, time and distance
*              incoherencies, and insufficient data.
*          -# If user-defined obstructions are enabled, the profile data is masked
*              (otherwise the chain region is detected automatically later).
*          -# The input is reoriented in X (depending on X orientation) to standard 
*              system orientation.
*          -# The input is resampled in Y using the resolution set in
*              GoWebScanConfig_CalYRes().
*          -# The input is reoriented (depending on Y orientation) and transposed so the 
*             leading Y edge is vertical.
*          -# Z range outliers are removed using a histogram. Ranges from the chain should 
*              be removed in this step.
*          -# Y edge row outliers (of the transposed data) are removed using a histogram.
*             Removed data is filled (nearest neighbour).
*          -# A line is fit to the filtered Y edges which forms the <b>Y offsets</b>. 
*               Depending on the travel orientation, the fit edges are first offset by the 
*               calibration bar width.
*          -# A region of the Z filtered calibration bar data near the leading Y 
*               edge is used to determine the average Z range per spot. These ranges are
*               filtered again using a histogram (filtered to keep only the 0.25 to 0.75 
*               quantile). Removed data is filled (nearest neighbour).
*          -# The <b>Z offset</b> for each spot is calculated as the filtered average Z 
*               value. For the top sensors, the Z values are subtracted from the calibration 
*               target height to form the offsets.
*          .
*          
*          For vision processing, the sequence is as follows:
*          -# The input vision data is inspected for any frame drops, time and distance
*              incoherencies, and insufficient data.
*          -# Each input image is reoriented in X (depending on X orientation) to standard 
*              system orientation.
*          -# Each input image is demosaiced.
*          -# Input images are resampled in Y using the Y resolution data from the 
*              GoGeoCal file, and a single image containing the calibration bar is formed.
*          -# The input image is reoriented (depending on Y orientation) and transposed so 
*             the leading Y edge is vertical.
*          -# Y edge row outliers (of the transposed data) are removed using a histogram.
*          -# A line is fit to the filtered Y edges and the fit edges are sampled down
*               to two points which forms the <b>Y offsets</b>. 
*               Depending on the travel orientation, the downsampled edges are offset by the 
*               calibration bar width.
*          -# If GoWebScanSettings_CalDetectLocators() is enabled, a region near the center 
*               of the calibration bar image is determined, and each column is summed. The 
*               column sums are filtered via a histogram, and a center of gravity calculation 
*               is performed on the column sums to determine center of the hole. The 
*               <b>X offset</b> is calculated as the difference of the hole center (converted 
*               to an X distance) to the nominal X center.
*          -# A raw input image approximately 1/4 from the leading Y edge is selected for 
*               gain calculations. The color channels are separated into different images.
*          -# The individual channel image gradients are checked along X. If all rows have a
*               large enough edge, this may imply the calibration bar does not span the full
*               length, so a warning is produced.
*          -# The channel images are vertically smoothened using a local histogram filter.
*          -# The <b>gain coefficients</b> are calculated as the target intensity divided 
*               by the smoothened pixel value for each pixel per channel. The target  
*               intensity can be set by the user via 
*               GoWebScanSettings_CalUseVisionIntensity(), otherwise a default of 180 is used.
*          -# The gain coefficients are downsampled to smaller size for convenient storage
*               in the calibration file.
*                      
* @see     GoWebScanCal, GoWebScanCalProcessor, GoWebScanConfig, GoWebScanConfigNode
*/
typedef kObject GoWebScanCalProcessorNode;

/**
 * Constructs a GoWebScanCalProcessorNode object.
 * 
 * @public              @memberof GoWebScanCalProcessorNode
 * @param   node        Receives the constructed GoWebScanCalProcessorNode object.
 * @param   configNode  Node configuration.
 * @param   allocator   Memory allocator (or kNULL for default).
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCalProcessorNode_Construct(GoWebScanCalProcessorNode* node, GoWebScanConfigNode configNode, kAlloc allocator);

/**
 * Executes the calibration processing for a node.
 * 
 * @public          @memberof GoWebScanCalProcessorNode
 * @param   node    GoWebScanCalProcessorNode object.
 * @param   input   Input dataset.
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCalProcessorNode_Execute(GoWebScanCalProcessorNode node, GoWebScanCalInput input); 

/**
 * Sets the X offset in mils.
 * 
 * @public          @memberof GoWebScanCalProcessorNode
 * @param   node    GoWebScanCalProcessorNode object.
 * @param   value   X offset (mils).
 * @return          Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCalProcessorNode_SetXOffset(GoWebScanCalProcessorNode node, k32s value); 

/**
* Gets the X offset in mils.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          X offset (mils).
*/
GoWebScanFx(k32s) GoWebScanCalProcessorNode_XOffset(GoWebScanCalProcessorNode node); 

/**
 * Gets the array of profile Y offsets for each spot.
 * 
 * @public          @memberof GoWebScanCalProcessorNode
 * @param   node    GoWebScanCalProcessorNode object.
 * @return          Array of profile Y offsets. Type k32s.
 */
GoWebScanFx(kArray1) GoWebScanCalProcessorNode_ProfileYOffsets(GoWebScanCalProcessorNode node); 

/**
* Gets the array of profile Z offsets for each spot.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Array of profile Z offsets. Type k16s.
*/
GoWebScanFx(kArray1) GoWebScanCalProcessorNode_ProfileZOffsets(GoWebScanCalProcessorNode node);

/**
* Gets the array of vision Y offsets for each spot.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Array of vision Y offsets. Type k32s.
*/
GoWebScanFx(kArray1) GoWebScanCalProcessorNode_VisionYOffsets(GoWebScanCalProcessorNode node);

/**
* Gets the array of vision red gains for each pixel in the downsampled vision image.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Array of vision red gains. Type k64f.
*/
GoWebScanFx(kArray2) GoWebScanCalProcessorNode_VisionRGains(GoWebScanCalProcessorNode node); 

/**
* Gets the array of vision green gains for each pixel in the downsampled vision image.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Array of vision green gains. Type k64f.
*/
GoWebScanFx(kArray2) GoWebScanCalProcessorNode_VisionGGains(GoWebScanCalProcessorNode node); 

/**
* Gets the array of vision blue gains for each pixel in the downsampled vision image.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Array of vision blue gains. Type k64f.
*/
GoWebScanFx(kArray2) GoWebScanCalProcessorNode_VisionBGains(GoWebScanCalProcessorNode node); 

/**
* Gets the color filter array type of the vision image.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Color filter array type.
*/
GoWebScanFx(kCfa) GoWebScanCalProcessorNode_Cfa(GoWebScanCalProcessorNode node);

/**
* Gets the number of profile issues that occurred during system calibration processing.
*
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Count of issues.
*/
GoWebScanFx(kSize) GoWebScanCalProcessorNode_ProfileIssueCount(GoWebScanCalProcessorNode node);

/**
* Gets the profile issue that occurred during system calibration processing at the specified index.
*
* @public           @memberof GoWebScanCalProcessorNode
* @param   node     GoWebScanCalProcessorNode object.
* @param   index    Index of profile issue.
* @param   activity Stage or activity in the system calibration processing during which the profile issue occurred.
* @param   status   Type of profile issue.
* @return           Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCalProcessorNode_ProfileIssueAt(GoWebScanCalProcessorNode node, kSize index, GoWebScanCalActivity* activity, GoWebScanCalNodeStatus* status);

/**
* Gets the number of vision issues that occurred during system calibration processing.
*
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Count of issues.
*/
GoWebScanFx(kSize) GoWebScanCalProcessorNode_VisionIssueCount(GoWebScanCalProcessorNode node);

/**
* Gets the vision issue that occurred during system calibration processing at the specified index.
*
* @public           @memberof GoWebScanCalProcessorNode
* @param   node     GoWebScanCalProcessorNode object.
* @param   index    Index of vision issue.
* @param   activity Stage or activity in the system calibration processing during which the vision issue occurred.
* @param   status   Type of vision issue..
* @return           Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCalProcessorNode_VisionIssueAt(GoWebScanCalProcessorNode node, kSize index, GoWebScanCalActivity* activity, GoWebScanCalNodeStatus* status);

/**
* Gets a flag for whether the profile processing completed without errors (warnings
* may be present). 
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Boolean for whether profile processing completed without errors.
*/
GoWebScanFx(kBool) GoWebScanCalProcessorNode_ProfileIsComplete(GoWebScanCalProcessorNode node); 

/**
* Gets a flag for whether any warnings were generated during the profile processing.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Boolean for whether profile processing had warnings.
*/
GoWebScanFx(kBool) GoWebScanCalProcessorNode_ProfileHasWarnings(GoWebScanCalProcessorNode node); 

/**
* Gets a flag for whether any errors were generated during the profile processing.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Boolean for whether profile processing had errors.
*/
GoWebScanFx(kBool) GoWebScanCalProcessorNode_ProfileHasErrors(GoWebScanCalProcessorNode node); 

/**
* Gets a flag for whether the vision processing completed without errors (warnings
* may be present). 
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Boolean for whether vision processing completed without errors.
*/
GoWebScanFx(kBool) GoWebScanCalProcessorNode_VisionIsComplete(GoWebScanCalProcessorNode node); 

/**
* Gets a flag for whether any warnings were generated during the vision processing.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Boolean for whether vision processing had warnings.
*/
GoWebScanFx(kBool) GoWebScanCalProcessorNode_VisionHasWarnings(GoWebScanCalProcessorNode node); 

/**
* Gets a flag for whether any errors were generated during the vision processing.
* 
* @public          @memberof GoWebScanCalProcessorNode
* @param   node    GoWebScanCalProcessorNode object.
* @return          Boolean for whether vision processing had errors.
*/
GoWebScanFx(kBool) GoWebScanCalProcessorNode_VisionHasErrors(GoWebScanCalProcessorNode node); 

/**
 * Gets the node configuration.
 * 
 * @public          @memberof GoWebScanCalProcessorNode
 * @param   node    GoWebScanCalProcessorNode object.
 * @return          GoWebScanConfigNode object representing the node configuration.
 */
GoWebScanFx(GoWebScanConfigNode) GoWebScanCalProcessorNode_ConfigNode(GoWebScanCalProcessorNode node); 

#include <GoWebScanSdk/GoWebScanCalProcessorNode.x.h>

#endif