GoWebScan API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoWebScanCal.h
Go to the documentation of this file.
1 /**
2 * @file GoWebScanCal.h
3 * @brief Declares a GoWebScanCal object.
4 *
5 * @internal
6 * Copyright (C) 2017-2018 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 
11 #ifndef GO_WEB_SCAN_CAL_H
12 #define GO_WEB_SCAN_CAL_H
13 
15 #include <kApi/Data/kXml.h>
16 
17 kBeginHeader()
18 
19 /**
20 * @class GoWebScanCal
21 * @extends kObject
22 * @ingroup GoWebScanSdk-Calibration
23 * @brief Represents a container for the system calibration. The system calibration corrects
24 * for mounting differences between sensors and performs a flatfield correction for
25 * vision sensors. The calibration file contains Z and Y offsets per spot for profile
26 * and tracheid sensors, and Y offsets and gains (for each color channel) for vision
27 * sensors. All offsets are stored in hex to save space in the file. Additionally,
28 * the calibration file also stores the X offset per camera (in decimal). This is only
29 * used when detection of locators is enabled during vision calibration. The algorithm
30 * aligns cameras to the centers of holes in the calibration bars, and calculates the
31 * X offset accordingly. Non-vision systems will have an X offset of 0. The calibration
32 * also contains an X and Y reference (in decimal) which represents the system bias.
33 * This reference allows for aligning multiple systems to each other.
34 *
35 * The data for all sensors is stored in a single XML file, and this class handles
36 * reading and writing the file. For systems with vision, a vision sensor's calibration
37 * data is stored under the serial number of the connected profile sensor.
38 *
39 * For profile sensors, Z and Y offsets are stored in 4-digit hex per spot. For vision
40 * sensors, the Y offsets for the first and last column in the vision image are stored
41 * in 4-digit hex; when the calibration is loaded, the offsets are linearly interpolated
42 * to the full vision width. The vision gains are also sampled to a lower image
43 * resolution (8 x 64) to save space and are linearly interpolated to the larger vision
44 * image size when the calibration is loaded. For precision, the log of each gain is
45 * calculated and normalized to [0, 1] and scaled to [0, 255] prior to hex conversion
46 * and saving. The hex spot offsets of a particular type (e.g. profile Y offsets) are
47 * concatenated together and stored as a single text string. Vision gains of the
48 * downsampled image are concatenated together and stored as a single string for each
49 * row and each channel.
50 *
51 * When using the calibration, GoWebScanCal first converts and upsamples the offsets and
52 * gains. Calibration data is applied early in processing: offsets are applied after
53 * masking and reorienting input data and prior to resampling in X and Y. Vision gains
54 * are applied after reorienting input data and prior to demosaicing and resampling. X
55 * offsets are used when performing the X-axis layout in GoWebScanConfig.
56 *
57 * Internally, GoWebScanCal stores the offsets and gains for individual nodes (cameras)
58 * as GoWebScanCalNode objects.
59 *
60 * Refer to GoWebScanCalProcessor and GoWebScanCalProcessorNode for a description of the
61 * calibration processing algorithm.
62 * @see GoWebScanCalProcessor, GoWebScanCalProcessorNode
63 */
64 typedef kObject GoWebScanCal;
65 
66 // Forward declaration
67 typedef kObject GoWebScanCalNode;
68 
69 /**
70 * Constructs a GoWebScanCal object.
71 *
72 * @public @memberof GoWebScanCal
73 * @param cal Receives the constructed GoWebScanCal object.
74 * @param allocator Memory allocator (or kNULL for default).
75 * @return Operation status.
76 */
77 GoWebScanFx(kStatus) GoWebScanCal_Construct(GoWebScanCal* cal, kAlloc allocator);
78 
79 /**
80  * Constructs and loads a GoWebScanCal object from a saved XML file.
81  *
82  * @public @memberof GoWebScanCal
83  * @param cal Receives the constructed GoWebScanCal object.
84  * @param fileName Filename (including path). Expected to be an XML file.
85  * @param alloc Memory allocator (or kNULL for default).
86  * @return Operation status.
87  */
88 GoWebScanFx(kStatus) GoWebScanCal_Load(GoWebScanCal* cal, const kChar* fileName, kAlloc alloc);
89 
90 /**
91  * Writes and stores a GoWebScanCal object to a XML file.
92  *
93  * @public @memberof GoWebScanCal
94  * @param cal GoWebScanCal object.
95  * @param fileName Filename (including path). Expected to be an XML file. If the file does
96  * not exist, it will be created.
97  * @return Operation status.
98  */
99 GoWebScanFx(kStatus) GoWebScanCal_Store(GoWebScanCal cal, const kChar* fileName);
100 
101 /**
102  * Constructs a calibration node object (GoWebScanCalNode) and adds it to the list of nodes. The node
103  * is given a unique ID based on its plane, system column, sensor ID, and bank ID (index of node with
104  * respect to the sensor).
105  *
106  * @public @memberof GoWebScanCal
107  * @param cal GoWebScanCal object.
108  * @param plane System plane.
109  * @param column System column index.
110  * @param deviceId Sensor ID. ID is of the connected profile sensor for vision systems.
111  * @param bankId Bank index.
112  * @param node Receives the constructed GoWebScanCalNode object.
113  * @return Operation status.
114  */
115 GoWebScanFx(kStatus) GoWebScanCal_AddNode(GoWebScanCal cal, GoWebScanSystemPlane plane, k32s column, k32s deviceId, k32s bankId, GoWebScanCalNode* node);
116 
117 /**
118  * Gets the number of nodes in the calibration.
119  *
120  * @public @memberof GoWebScanCal
121  * @param cal GoWebScanCal object.
122  * @return Node count.
123  */
124 GoWebScanFx(kSize) GoWebScanCal_NodeCount(GoWebScanCal cal);
125 
126 /**
127  * Gets the calibration node at a specified index in the system.
128  *
129  * @public @memberof GoWebScanCal
130  * @param cal GoWebScanCal object.
131  * @param index Node index.
132  * @return GoWebScanCalNode object representing the node's calibration.
133  */
134 GoWebScanFx(GoWebScanCalNode) GoWebScanCal_NodeAt(GoWebScanCal cal, kSize index);
135 
136 /**
137  * Finds and returns the calibration node with the specified device ID and bank ID.
138  *
139  * @public @memberof GoWebScanCal
140  * @param cal GoWebScanCal object.
141  * @param deviceId Sensor ID. ID is of the connected profile sensor for vision systems.
142  * @param bankId Bank index.
143  * @return GoWebScanCalNode object representing the node's calibration.
144  */
145 GoWebScanFx(GoWebScanCalNode) GoWebScanCal_FindNode(GoWebScanCal cal, k32s deviceId, k32s bankId);
146 
147 /**
148  * Gets the system Y reference in mils. This represents the Y-bias of the system and can be used
149  * to align multiple systems. Refer to GoWebScanSettings_SetCalYAdjustment() for how this should be
150  * applied by the user application.
151  *
152  * @public @memberof GoWebScanCal
153  * @param cal GoWebScanCal object.
154  * @return System Y reference (mils).
155  * @see GoWebScanSettings_SetCalYAdjustment
156  */
157 GoWebScanFx(k64s) GoWebScanCal_SystemYRef(GoWebScanCal cal);
158 
159 /**
160 * Sets the system Y reference in mils.
161 *
162 * @public @memberof GoWebScanCal
163 * @param cal GoWebScanCal object.
164 * @param yRef System Y reference (mils).
165 * @return Operation status.
166 */
167 GoWebScanFx(kStatus) GoWebScanCal_SetSystemYRef(GoWebScanCal cal, k64s yRef);
168 
169 /**
170 * Gets the system X reference in mils. This represents the X-bias of the system and can be used
171 * to align multiple systems. Refer to GoWebScanSettings_SetCalXAdjustment() for how this should be
172 * applied by the user application.
173 *
174 * @public @memberof GoWebScanCal
175 * @param cal GoWebScanCal object.
176 * @return System X reference (mils).
177 * @see GoWebScanSettings_SetCalXAdjustment
178 */
179 GoWebScanFx(k32s) GoWebScanCal_SystemXRef(GoWebScanCal cal);
180 
181 /**
182 * Sets the system X reference in mils.
183 *
184 * @public @memberof GoWebScanCal
185 * @param cal GoWebScanCal object.
186 * @param xRef System X reference (mils).
187 * @return Operation status.
188 */
189 GoWebScanFx(kStatus) GoWebScanCal_SetSystemXRef(GoWebScanCal cal, k32s xRef);
190 kEndHeader()
191 #include <GoWebScanSdk/GoWebScanCal.x.h>
192 
193 #endif
GoWebScanCalNode GoWebScanCal_FindNode(GoWebScanCal cal, k32s deviceId, k32s bankId)
Finds and returns the calibration node with the specified device ID and bank ID.
kStatus GoWebScanCal_SetSystemYRef(GoWebScanCal cal, k64s yRef)
Sets the system Y reference in mils.
GoWebScanCalNode GoWebScanCal_NodeAt(GoWebScanCal cal, kSize index)
Gets the calibration node at a specified index in the system.
Essential GoWebScan declarations.
k32s GoWebScanCal_SystemXRef(GoWebScanCal cal)
Gets the system X reference in mils.
kStatus GoWebScanCal_Load(GoWebScanCal *cal, const kChar *fileName, kAlloc alloc)
Constructs and loads a GoWebScanCal object from a saved XML file.
Represents a container for node-level system calibration data. Refer to GoWebScanCal for a descriptio...
kSize GoWebScanCal_NodeCount(GoWebScanCal cal)
Gets the number of nodes in the calibration.
Represents the top or bottom plane of the system.
kStatus GoWebScanCal_Construct(GoWebScanCal *cal, kAlloc allocator)
Constructs a GoWebScanCal object.
Represents a container for the system calibration. The system calibration corrects for mounting diffe...
k64s GoWebScanCal_SystemYRef(GoWebScanCal cal)
Gets the system Y reference in mils.
kStatus GoWebScanCal_AddNode(GoWebScanCal cal, GoWebScanSystemPlane plane, k32s column, k32s deviceId, k32s bankId, GoWebScanCalNode *node)
Constructs a calibration node object (GoWebScanCalNode) and adds it to the list of nodes...
kStatus GoWebScanCal_SetSystemXRef(GoWebScanCal cal, k32s xRef)
Sets the system X reference in mils.
kStatus GoWebScanCal_Store(GoWebScanCal cal, const kChar *fileName)
Writes and stores a GoWebScanCal object to a XML file.