Arrays, Batching, and Aggregation
GoPxL supports data structures called arrays to help simplify otherwise complicated applications.
When working with arrays, you can select an array element (or all of the elements) across all arrayed tool outputs to make it easier to focus on a single array element. For more information, see Displaying and Pinning Outputs.
An array is a group of data items bundled into a single structure, such as multiple profiles or surfaces, multiple measurements, or multiple geometric features.
The items, or elements, in the array can be processed by other tools in one of two ways:
-
Batching: Tools in batching mode process each array element separately. In other words, the tools "loop" through the elements of the array. Typically, tools in batching mode will output an array of outputs, where each element corresponds to the elements in the input. You enable batching by checking the Enable batching parameter in a tool's Inputs section. For more information, see Batching.
-
Aggregating: Aggregating tools combine each element in the array and process it as a single piece of data. For more information, see Aggregating.
Most tools support the batching of array elements. Some tools support both batching and aggregating.
Array data can come from various sources:
-
Outputs from tools like Surface Blob, Surface Segmentation, and Surface Pattern Matching. For more information, see Arrays from Multi-instance Tools.
-
G4 and G5 (single- and multi-sensor) and multi-layer output. For more information, see Arrays from Multi-layer Output.
-
G2 multi-sensor output. For more information, see G2 Multi-sensor Output.
-
The Script tool. For more information, see Script.
-
The Array Create tool. For more information, see Array Create.
For information on working with arrays in the Displayed Outputs panel, see Displaying and Pinning Outputs.
Arrays from Multi-instance Tools
The Surface Blob, Surface Segmentation, and Surface Pattern Matching tools can identify multiple occurrences of features or parts in scan data. When you check Enable Array Output in the tool's Parameters section, the tool outputs an array containing the occurrences. Otherwise, the tools produce a separate output for each identified feature or part. In the following, a Surface Blob tool has identified five blobs in scan data.
Surface Blob tool identifying blobs in scan data.
When the tool's Enable Array Output setting is checked, the Surface Blob tool outputs an array containing all of the blobs it identifies.
An array containing objects identified in some scan data could be represented in the following way. (These are "blobs" from the Surface Blob tool.)
Note that array elements start at 0; that is, arrays are 0-based.
Other tools can then take this array as input. For more information, see Batching or Aggregating.
Arrays from Multi-layer Output
When configured for multi-layer scanning, confocal sensors can scan translucent or transparent targets and return a profile or a surface representing each layer. By default, these profiles are output as an array. (Note that you can optionally have GoPxL output the profiles individually by enabling Separate layer outputs on the Scan page; for more information, see Scan Modes and Intensity.)
The following illustration is a representation of multilayer Profile scan data from a confocal sensor, showing four profiles.
The structure of an array containing these profiles could be represented as follows:
Other tools can then take this array as input. For more information, see Batching or Aggregating.
G2 Multi-sensor Output
In G2 multi-sensor systems where sensors are in a top-bottom layout, Profile and Surface data can optionally be output as an array, where top data (from one or more sensors) is one array element, and bottom data (from one or more sensors) is another array element.
Other tools can then take this array as input. For more information, see Batching or Aggregating.
To understand how GoPxL communicates information related to batching and arrays, see Batch and Array Indicators in GoPxL.
Batching
When a tool is in batching mode, it processes each item in the input array individually. A tool in batching mode also outputs one or more arrays (such as measurements, Profile or Surface data, geometric features, and so on), where each element of the output arrays corresponds to an element in the input array.
When a tool is in batching mode, there is no limit to the number of elements in the input array (other than any CPU limitations).
Batching is enabled in tools by checking Enable batching in the tool's Inputs section, or by clicking the Batching icon (
) in a tool's block in the Tool Diagram panel (see below).
The following shows the Surface Bounding Box tool in batching mode (taking the Surface Blob tool's array of outputs as input). The tool calculates the bounding box for each element in the input array, and returns the enabled measurements as arrays. That is, it returns an X, Y, and Z measurement for each object.
Hovering over batched outputs in the Tool Diagram or in the Tool Configuration panel displays a list of the elements in the array.
When at least one result in the array is a fail, the output is considered a fail and the "Array[n]" label is red. Otherwise, it's green. Outputs within the pop-up list are displayed in green or red, depending on whether they represent pass or fail. You can copy the values of the measurement into the clipboard by clicking the copy icon (
). The format of the copied values is as follows:
[24.604,22.805,22.018,21.765,13.099]
Aggregating
Some tools can take arrays as an input and combine (or "aggregate") the data in the array elements and treat it as a single input (see below for an example). These tools are called "aggregating tools"; see Aggregating Tools for a list of the aggregating tools. In order for a tool to aggregate an array input, its Enable Batching parameter must be disabled. Otherwise, it will process the array elements individually. Note that aggregating tools also take non-array input (such as a single scan of Profile or Surface data), and simply process the data as usual.
Some aggregating tools are limited to a maximum of a 2-element array in their input. Other tools can accept an arbitrary number. See Aggregating Tools to determine the limits of a tool. Note that when a tool is in batching mode, there is no limit to the number of elements in the input array (other than any CPU limitations), regardless of the array size limitations when the tools is aggregating data.
|
Remember to uncheck Enable Batching if you want a tool to aggregate array inputs. |
Taking the example from above, if batching in the Surface Bounding Box tool is disabled, it will aggregate the scan data in the input array, and fit the bounding around the scan data of all the elements together.
Batch and Array Indicators in GoPxL
GoPxL communicates information related to batching and arrays by adding a "square bracket" badge ("[ ]") to input, output, and tool icons in the web interface.
In the Tool Diagram panel, for tools that support batching, a Batching icon (
) is displayed at the top of the tool block. Use this to toggle batching for that tool. If the tool is not currently selected (that is, you have clicked on it), indicated by a blue border, you must hover the mouse pointer over the top area of the tool block to see whether it supports batching.
When you enable batching on a tool, the Batching toggle icon turns blue, and GoPxL places yellow batching badges on various elements in the web interface. Below, the tool is in batching mode, and its inputs and outputs are therefore all arrays.
For tools that can take array inputs when batching is not enabled, the scan data input (Surface Input) shows a batching badge. Tools like this aggregate array inputs in this state; for more information, see Aggregating.
