GoWebScanCal.h

Go to the documentation of this file.

/**
* @file    GoWebScanCal.h
* @brief   Declares a GoWebScanCal 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_H
#define GO_WEB_SCAN_CAL_H

#include <GoWebScanSdk/GoWebScanSdkDef.h>
#include <kApi/Data/kXml.h>

/**
* @class   GoWebScanCal
* @extends kObject
* @ingroup GoWebScanSdk-Calibration
* @brief   Represents a container for the system calibration. The system calibration corrects
*          for mounting differences between sensors and performs a flatfield correction for 
*          vision sensors. The calibration file contains Z and Y offsets per spot for profile
*          and tracheid sensors, and Y offsets and gains (for each color channel) for vision
*          sensors. All offsets are stored in hex to save space in the file. Additionally,
*          the calibration file also stores the X offset per camera (in decimal). This is only 
*          used when detection of locators is enabled during vision calibration. The algorithm 
*          aligns cameras to the centers of holes in the calibration bars, and calculates the 
*          X offset accordingly. Non-vision systems will have an X offset of 0. The calibration
*          also contains an X and Y reference (in decimal) which represents the system bias. 
*          This reference allows for aligning multiple systems to each other. 
*          
*          The data for all sensors is stored in a single XML file, and this class handles 
*          reading and writing the file. For systems with vision, a vision sensor's calibration 
*          data is stored under the serial number of the connected profile sensor.
*          
*          For profile sensors, Z and Y offsets are stored in 4-digit hex per spot. For vision 
*          sensors, the Y offsets for the first and last column in the vision image are stored 
*          in 4-digit hex; when the calibration is loaded, the offsets are linearly interpolated
*          to the full vision width. The vision gains are also sampled to a lower image 
*          resolution (8 x 64) to save space and are linearly interpolated to the larger vision 
*          image size when the calibration is loaded. For precision, the log of each gain is 
*          calculated and normalized to [0, 1] and scaled to [0, 255] prior to hex conversion 
*          and saving. The hex spot offsets of a particular type (e.g. profile Y offsets) are 
*          concatenated together and stored as a single text string. Vision gains of the 
*          downsampled image are concatenated together and stored as a single string for each 
*          row and each channel.
*          
*          When using the calibration, GoWebScanCal first converts and upsamples the offsets and
*          gains. Calibration data is applied early in processing: offsets are applied after 
*          masking and reorienting input data and prior to resampling in X and Y. Vision gains 
*          are applied after reorienting input data and prior to demosaicing and resampling. X
*          offsets are used when performing the X-axis layout in GoWebScanConfig.
*          
*          Internally, GoWebScanCal stores the offsets and gains for individual nodes (cameras)
*          as GoWebScanCalNode objects.
*          
*          Refer to GoWebScanCalProcessor and GoWebScanCalProcessorNode for a description of the 
*          calibration processing algorithm.
* @see     GoWebScanCalProcessor, GoWebScanCalProcessorNode
*/
typedef kObject GoWebScanCal;

// Forward declaration
typedef kObject GoWebScanCalNode; 

/**
* Constructs a GoWebScanCal object.
* 
* @public                  @memberof GoWebScanCal
* @param   cal             Receives the constructed GoWebScanCal object.
* @param   allocator       Memory allocator (or kNULL for default).
* @return                  Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCal_Construct(GoWebScanCal* cal, kAlloc allocator);

/**
 * Constructs and loads a GoWebScanCal object from a saved XML file.
 * 
 * @public              @memberof GoWebScanCal
 * @param   cal         Receives the constructed GoWebScanCal object.
 * @param   fileName    Filename (including path). Expected to be an XML file.
 * @param   alloc       Memory allocator (or kNULL for default).
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCal_Load(GoWebScanCal* cal, const kChar* fileName, kAlloc alloc);

/**
 * Writes and stores a GoWebScanCal object to a XML file.
 * 
 * @public              @memberof GoWebScanCal
 * @param   cal         GoWebScanCal object.
 * @param   fileName    Filename (including path). Expected to be an XML file. If the file does
 *                      not exist, it will be created.
 * @return              Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCal_Store(GoWebScanCal cal, const kChar* fileName);

/**
* Constructs and sets the values of a GoWebScanCal object from the given XML text.
*
* @public               @memberof GoWebScanCal
* @param    cal         Receives the constructed GoWebScanCal object.
* @param    str         Text of a GoWebScan XML.
* @param    alloc       Memory allocator (or kNULL for default).
* @return               Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCal_ImportFromText(GoWebScanCal* cal, const kChar* str, kAlloc alloc);

/**
* Constructs and sets the values of a GoWebScanCal object from the given XML kString.
*
* @public               @memberof GoWebScanCal
* @param    cal         Receives the constructed GoWebScanCal object.
* @param    str         kString containing the text of a GoWebScan XML.
* @param    alloc       Memory allocator (or kNULL for default).
* @return               Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCal_ImportFromString(GoWebScanCal* cal, kString str, kAlloc alloc);

/**
* Populates a kString with the text of a GoWebScanCal object.
*
* @public               @memberof GoWebScanCal
* @param    cal         GoWebScanCal object.
* @param    str         kString to be populated with the GoWebScan XML text.
* @return               Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCal_ExportToString(GoWebScanCal cal, kString str);

/**
 * Constructs a calibration node object (GoWebScanCalNode) and adds it to the list of nodes. The node
 * is given a unique ID based on its plane, system column, sensor ID, and bank ID (index of node with
 * respect to the sensor).
 * 
 * @public  @memberof GoWebScanCal
 * @param   cal         GoWebScanCal object.
 * @param   plane       System plane.
 * @param   column      System column index.
 * @param   deviceId    Sensor ID. ID is of the connected profile sensor for vision systems.
 * @param   bankId      Bank index.
 * @param   node        Receives the constructed GoWebScanCalNode object.
 * @return  Operation status.
 */
GoWebScanFx(kStatus) GoWebScanCal_AddNode(GoWebScanCal cal, GoWebScanSystemPlane plane, k32s column, k32s deviceId, k32s bankId, GoWebScanCalNode* node);

/**
 * Gets the number of nodes in the calibration.
 * 
 * @public       @memberof GoWebScanCal
 * @param   cal  GoWebScanCal object.
 * @return       Node count.
 */
GoWebScanFx(kSize) GoWebScanCal_NodeCount(GoWebScanCal cal); 

/**
 * Gets the calibration node at a specified index in the system.
 * 
 * @public          @memberof GoWebScanCal
 * @param   cal     GoWebScanCal object.
 * @param   index   Node index.
 * @return          GoWebScanCalNode object representing the node's calibration.
 */
GoWebScanFx(GoWebScanCalNode) GoWebScanCal_NodeAt(GoWebScanCal cal, kSize index); 

/**
 * Finds and returns the calibration node with the specified device ID and bank ID.
 * 
 * @public              @memberof GoWebScanCal
 * @param   cal         GoWebScanCal object.
 * @param   deviceId    Sensor ID. ID is of the connected profile sensor for vision systems.
 * @param   bankId      Bank index.
 * @return              GoWebScanCalNode object representing the node's calibration.
 */
GoWebScanFx(GoWebScanCalNode) GoWebScanCal_FindNode(GoWebScanCal cal, k32s deviceId, k32s bankId); 

/**
 * Gets the system Y reference in mils. This represents the Y-bias of the system and can be used
 * to align multiple systems. Refer to GoWebScanSettings_SetCalYAdjustment() for how this should be
 * applied by the user application.
 * 
 * @public          @memberof GoWebScanCal
 * @param   cal     GoWebScanCal object.
 * @return          System Y reference (mils).
 * @see             GoWebScanSettings_SetCalYAdjustment
 */
GoWebScanFx(k64s) GoWebScanCal_SystemYRef(GoWebScanCal cal); 

/**
* Sets the system Y reference in mils.
* 
* @public           @memberof GoWebScanCal
* @param   cal      GoWebScanCal object.
* @param   yRef     System Y reference (mils).
* @return           Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCal_SetSystemYRef(GoWebScanCal cal, k64s yRef); 

/**
* Gets the system X reference in mils. This represents the X-bias of the system and can be used
* to align multiple systems. Refer to GoWebScanSettings_SetCalXAdjustment() for how this should be
* applied by the user application.
* 
* @public          @memberof GoWebScanCal
* @param   cal     GoWebScanCal object.
* @return          System X reference (mils).
* @see             GoWebScanSettings_SetCalXAdjustment    
*/
GoWebScanFx(k32s) GoWebScanCal_SystemXRef(GoWebScanCal cal); 

/**
* Sets the system X reference in mils.
* 
* @public           @memberof GoWebScanCal
* @param   cal      GoWebScanCal object.
* @param   xRef     System X reference (mils).
* @return           Operation status.
*/
GoWebScanFx(kStatus) GoWebScanCal_SetSystemXRef(GoWebScanCal cal, k32s xRef); 

#include <GoWebScanSdk/GoWebScanCal.x.h>

#endif