GoWebScan API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoWebScanCalProcessorNode.h
Go to the documentation of this file.
1 /**
2 * @file GoWebScanCalProcessorNode.h
3 * @brief Declares a GoWebScanCalProcessorNode 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_PROCESSOR_NODE_H
12 #define GO_WEB_SCAN_CAL_PROCESSOR_NODE_H
13 
17 
18 kBeginHeader()
19 
20 /**
21 * @class GoWebScanCalProcessorNode
22 * @extends kObject
23 * @ingroup GoWebScanSdk-Calibration
24 * @brief Represents an algorithm for processing node tiles containing a calibration bar,
25 * and generating node profile Z and Y offsets and vision Y offsets and gains.
26 * Refer to GoWebScanCal for a description of the system calibration outputs and
27 * usage.
28 *
29 * GoWebScanCalProcessorNode executes a sequence of processing tasks for profile
30 * and vision data. If a task fails in the sequence, the processing does not
31 * continue and an error and issue type is recorded. Vision processing will not
32 * proceed if profile processing fails. Any warnings (issues that do not prevent
33 * processing from completing but may result in suboptimal calibration) that
34 * occur are recorded.
35 *
36 * For profile processing, the sequence is as follows:
37 * -# The input profile data is inspected for any frame drops, time and distance
38 * incoherencies, and insufficient data.
39 * -# If user-defined obstructions are enabled, the profile data is masked
40 * (otherwise the chain region is detected automatically later).
41 * -# The input is reoriented in X (depending on X orientation) to standard
42 * system orientation.
43 * -# The input is resampled in Y using the resolution set in
44 * GoWebScanConfig_CalYRes().
45 * -# The input is reoriented (depending on Y orientation) and transposed so the
46 * leading Y edge is vertical.
47 * -# Z range outliers are removed using a histogram. Ranges from the chain should
48 * be removed in this step.
49 * -# Y edge row outliers (of the transposed data) are removed using a histogram.
50 * Removed data is filled (nearest neighbour).
51 * -# A line is fit to the filtered Y edges which forms the <b>Y offsets</b>.
52 * Depending on the travel orientation, the fit edges are first offset by the
53 * calibration bar width.
54 * -# A region of the Z filtered calibration bar data near the leading Y
55 * edge is used to determine the average Z range per spot. These ranges are
56 * filtered again using a histogram (filterd to keep only the 0.25 to 0.75
57 * quantile). Removed data is filled (nearest neighbour).
58 * -# The <b>Z offset</b> for each spot is calculated as the filtered average Z
59 * value. For the top sensors, the Z values are subtracted from the calibration
60 * target height to form the offsets.
61 * .
62 *
63 * For vision processing, the sequence is as follows:
64 * -# The input vision data is inspected for any frame drops, time and distance
65 * incoherencies, and insufficient data.
66 * -# Each input image is reoriented in X (depending on X orientation) to standard
67 * system orientation.
68 * -# Each input image is demosaiced.
69 * -# Input images are resampled in Y using the Y resolution data from the
70 * GoGeoCal file, and a single image containing the calibration bar is formed.
71 * -# The input image is reoriented (depending on Y orientation) and transposed so
72 * the leading Y edge is vertical.
73 * -# Y edge row outliers (of the transposed data) are removed using a histogram.
74 * -# A line is fit to the filtered Y edges and the fit edges are sampled down
75 * to two points which forms the <b>Y offsets</b>.
76 * Depending on the travel orientation, the downsampled edges are offset by the
77 * calibration bar width.
78 * -# If GoWebScanSettings_CalDetectLocators() is enabled, a region near the center
79 * of the calibration bar image is determined, and each column is summed. The
80 * column sums are filtered via a histogram, and a center of gravity calculation
81 * is performed on the column sums to determine center of the hole. The
82 * <b>X offset</b> is calculated as the difference of the hole center (converted
83 * to an X distance) to the nominal X center.
84 * -# A raw input image approximately 1/4 from the leading Y edge is selected for
85 * gain calculations. The color channels are seperated into different images.
86 * -# The channel images are vertically smoothened using a local histogram filter.
87 * -# The <b>gain coefficients</b> are calculated as the target intensity divided
88 * by the smoothened pixel value for each pixel per channel. The target
89 * intensity can be set by the user via
90 * GoWebScanSettings_CalUseVisionIntensity(), otherwise a default of 180 is used.
91 * -# The gain coefficients are downsampled to smaller size for convenient storage
92 * in the calibration file.
93 *
94 * @see GoWebScanCal, GoWebScanCalProcessor, GoWebScanConfig, GoWebScanConfigNode
95 */
97 
98 /**
99  * Constructs a GoWebScanCalProcessorNode object.
100  *
101  * @public @memberof GoWebScanCalProcessorNode
102  * @param node Receives the constructed GoWebScanCalProcessorNode object.
103  * @param configNode Node configuration.
104  * @param allocator Memory allocator (or kNULL for default).
105  * @return Operation status.
106  */
107 GoWebScanFx(kStatus) GoWebScanCalProcessorNode_Construct(GoWebScanCalProcessorNode* node, GoWebScanConfigNode configNode, kAlloc allocator);
108 
109 /**
110  * Executes the calibration processing for a node.
111  *
112  * @public @memberof GoWebScanCalProcessorNode
113  * @param node GoWebScanCalProcessorNode object.
114  * @param input Input dataset.
115  * @return Operation status.
116  */
117 GoWebScanFx(kStatus) GoWebScanCalProcessorNode_Execute(GoWebScanCalProcessorNode node, GoWebScanCalInput input);
118 
119 /**
120  * Sets the X offset in mils.
121  *
122  * @public @memberof GoWebScanCalProcessorNode
123  * @param node GoWebScanCalProcessorNode object.
124  * @param value X offset (mils).
125  * @return Operation status.
126  */
127 GoWebScanFx(kStatus) GoWebScanCalProcessorNode_SetXOffset(GoWebScanCalProcessorNode node, k32s value);
128 
129 /**
130 * Gets the X offset in mils.
131 *
132 * @public @memberof GoWebScanCalProcessorNode
133 * @param node GoWebScanCalProcessorNode object.
134 * @return X offset (mils).
135 */
136 GoWebScanFx(k32s) GoWebScanCalProcessorNode_XOffset(GoWebScanCalProcessorNode node);
137 
138 /**
139  * Gets the array of profile Y offsets for each spot.
140  *
141  * @public @memberof GoWebScanCalProcessorNode
142  * @param node GoWebScanCalProcessorNode object.
143  * @return Array of profile Y offsets. Type k32s.
144  */
145 GoWebScanFx(kArray1) GoWebScanCalProcessorNode_ProfileYOffsets(GoWebScanCalProcessorNode node);
146 
147 /**
148 * Gets the array of profile Z offsets for each spot.
149 *
150 * @public @memberof GoWebScanCalProcessorNode
151 * @param node GoWebScanCalProcessorNode object.
152 * @return Array of profile Z offsets. Type k16s.
153 */
154 GoWebScanFx(kArray1) GoWebScanCalProcessorNode_ProfileZOffsets(GoWebScanCalProcessorNode node);
155 
156 /**
157 * Gets the array of vision Y offsets for each spot.
158 *
159 * @public @memberof GoWebScanCalProcessorNode
160 * @param node GoWebScanCalProcessorNode object.
161 * @return Array of vision Y offsets. Type k32s.
162 */
163 GoWebScanFx(kArray1) GoWebScanCalProcessorNode_VisionYOffsets(GoWebScanCalProcessorNode node);
164 
165 /**
166 * Gets the array of vision red gains for each pixel in the downsampled vision image.
167 *
168 * @public @memberof GoWebScanCalProcessorNode
169 * @param node GoWebScanCalProcessorNode object.
170 * @return Array of vision red gains. Type k64f.
171 */
172 GoWebScanFx(kArray2) GoWebScanCalProcessorNode_VisionRGains(GoWebScanCalProcessorNode node);
173 
174 /**
175 * Gets the array of vision green gains for each pixel in the downsampled vision image.
176 *
177 * @public @memberof GoWebScanCalProcessorNode
178 * @param node GoWebScanCalProcessorNode object.
179 * @return Array of vision green gains. Type k64f.
180 */
181 GoWebScanFx(kArray2) GoWebScanCalProcessorNode_VisionGGains(GoWebScanCalProcessorNode node);
182 
183 /**
184 * Gets the array of vision blue gains for each pixel in the downsampled vision image.
185 *
186 * @public @memberof GoWebScanCalProcessorNode
187 * @param node GoWebScanCalProcessorNode object.
188 * @return Array of vision blue gains. Type k64f.
189 */
190 GoWebScanFx(kArray2) GoWebScanCalProcessorNode_VisionBGains(GoWebScanCalProcessorNode node);
191 
192 /**
193 * Gets the color filter array type of the vision image.
194 *
195 * @public @memberof GoWebScanCalProcessorNode
196 * @param node GoWebScanCalProcessorNode object.
197 * @return Color filter array type.
198 */
199 GoWebScanFx(kCfa) GoWebScanCalProcessorNode_Cfa(GoWebScanCalProcessorNode node);
200 
201 /**
202 * Gets a flag for whether the profile processing completed without errors (warnings
203 * may be present).
204 *
205 * @public @memberof GoWebScanCalProcessorNode
206 * @param node GoWebScanCalProcessorNode object.
207 * @return Boolean for whether profile processing completed without errors.
208 */
209 GoWebScanFx(kBool) GoWebScanCalProcessorNode_ProfileIsComplete(GoWebScanCalProcessorNode node);
210 
211 /**
212 * Gets a flag for whether any warnings were generated during the profile processing.
213 *
214 * @public @memberof GoWebScanCalProcessorNode
215 * @param node GoWebScanCalProcessorNode object.
216 * @return Boolean for whether profile processing had warnings.
217 */
218 GoWebScanFx(kBool) GoWebScanCalProcessorNode_ProfileHasWarnings(GoWebScanCalProcessorNode node);
219 
220 /**
221 * Gets a flag for whether any errors were generated during the profile processing.
222 *
223 * @public @memberof GoWebScanCalProcessorNode
224 * @param node GoWebScanCalProcessorNode object.
225 * @return Boolean for whether profile processing had errors.
226 */
227 GoWebScanFx(kBool) GoWebScanCalProcessorNode_ProfileHasErrors(GoWebScanCalProcessorNode node);
228 
229 /**
230 * Gets a flag for whether the vision processing completed without errors (warnings
231 * may be present).
232 *
233 * @public @memberof GoWebScanCalProcessorNode
234 * @param node GoWebScanCalProcessorNode object.
235 * @return Boolean for whether vision processing completed without errors.
236 */
237 GoWebScanFx(kBool) GoWebScanCalProcessorNode_VisionIsComplete(GoWebScanCalProcessorNode node);
238 
239 /**
240 * Gets a flag for whether any warnings were generated during the vision processing.
241 *
242 * @public @memberof GoWebScanCalProcessorNode
243 * @param node GoWebScanCalProcessorNode object.
244 * @return Boolean for whether vision processing had warnings.
245 */
246 GoWebScanFx(kBool) GoWebScanCalProcessorNode_VisionHasWarnings(GoWebScanCalProcessorNode node);
247 
248 /**
249 * Gets a flag for whether any errors were generated during the vision processing.
250 *
251 * @public @memberof GoWebScanCalProcessorNode
252 * @param node GoWebScanCalProcessorNode object.
253 * @return Boolean for whether vision processing had errors.
254 */
255 GoWebScanFx(kBool) GoWebScanCalProcessorNode_VisionHasErrors(GoWebScanCalProcessorNode node);
256 
257 /**
258  * Gets the node configuration.
259  *
260  * @public @memberof GoWebScanCalProcessorNode
261  * @param node GoWebScanCalProcessorNode object.
262  * @return GoWebScanConfigNode object representing the node configuration.
263  */
264 GoWebScanFx(GoWebScanConfigNode) GoWebScanCalProcessorNode_ConfigNode(GoWebScanCalProcessorNode node);
265 
266 kEndHeader()
267 #include <GoWebScanSdk/GoWebScanCalProcessorNode.x.h>
268 
269 #endif
Represents a container for node-level parameters which are translated from user parameters set in GoW...
kBool GoWebScanCalProcessorNode_ProfileIsComplete(GoWebScanCalProcessorNode node)
Gets a flag for whether the profile processing completed without errors (warnings may be present)...
Declares a GoWebScanCalInput object.
kStatus GoWebScanCalProcessorNode_Construct(GoWebScanCalProcessorNode *node, GoWebScanConfigNode configNode, kAlloc allocator)
Constructs a GoWebScanCalProcessorNode object.
kStatus GoWebScanCalProcessorNode_SetXOffset(GoWebScanCalProcessorNode node, k32s value)
Sets the X offset in mils.
kArray1 GoWebScanCalProcessorNode_ProfileZOffsets(GoWebScanCalProcessorNode node)
Gets the array of profile Z offsets for each spot.
kArray2 GoWebScanCalProcessorNode_VisionGGains(GoWebScanCalProcessorNode node)
Gets the array of vision green gains for each pixel in the downsampled vision image.
kBool GoWebScanCalProcessorNode_ProfileHasErrors(GoWebScanCalProcessorNode node)
Gets a flag for whether any errors were generated during the profile processing.
Essential GoWebScan declarations.
kBool GoWebScanCalProcessorNode_VisionHasWarnings(GoWebScanCalProcessorNode node)
Gets a flag for whether any warnings were generated during the vision processing. ...
Represents an algorithm for processing node tiles containing a calibration bar, and generating node p...
Represents Y-matched system data containing a calibration bar, used for calibration processing...
kBool GoWebScanCalProcessorNode_VisionIsComplete(GoWebScanCalProcessorNode node)
Gets a flag for whether the vision processing completed without errors (warnings may be present)...
kArray1 GoWebScanCalProcessorNode_VisionYOffsets(GoWebScanCalProcessorNode node)
Gets the array of vision Y offsets for each spot.
GoWebScanConfigNode GoWebScanCalProcessorNode_ConfigNode(GoWebScanCalProcessorNode node)
Gets the node configuration.
kArray1 GoWebScanCalProcessorNode_ProfileYOffsets(GoWebScanCalProcessorNode node)
Gets the array of profile Y offsets for each spot.
k32s GoWebScanCalProcessorNode_XOffset(GoWebScanCalProcessorNode node)
Gets the X offset in mils.
kArray2 GoWebScanCalProcessorNode_VisionRGains(GoWebScanCalProcessorNode node)
Gets the array of vision red gains for each pixel in the downsampled vision image.
Declares a GoWebScanConfigNode object.
kBool GoWebScanCalProcessorNode_ProfileHasWarnings(GoWebScanCalProcessorNode node)
Gets a flag for whether any warnings were generated during the profile processing.
kBool GoWebScanCalProcessorNode_VisionHasErrors(GoWebScanCalProcessorNode node)
Gets a flag for whether any errors were generated during the vision processing.
kCfa GoWebScanCalProcessorNode_Cfa(GoWebScanCalProcessorNode node)
Gets the color filter array type of the vision image.
kArray2 GoWebScanCalProcessorNode_VisionBGains(GoWebScanCalProcessorNode node)
Gets the array of vision blue gains for each pixel in the downsampled vision image.
kStatus GoWebScanCalProcessorNode_Execute(GoWebScanCalProcessorNode node, GoWebScanCalInput input)
Executes the calibration processing for a node.