# Math Tool Functions

The Math tool provides a comprehensive dictionary of mathematical operations:

- Clocked Data Storage functions store a stream of values from a cell over time. Each function returns a single value selected from the stream of values whenever the specified event updates the spreadsheet.

- With Geometry and Measurement functions, you can easily compute the distance between standard geometric constructs, including circles, points, and line segments.
- Graphics:
  - Control functions insert interactive elements into the spreadsheet that allow users to make simple configuration changes to a job without having to use the Insert Function dialog or property sheet.
  - Image functions plot graphic overlays on top of the image.
- Mathematics functions:
  - Logic functions provide boolean algebraic and conditional testing capabilities. For all Logic functions 0 value means FALSE result and any non-zero result means TRUE.
  - Lookup functions allow you to search a range of values for a maximum, minimum, or index number, return X and Y coordinates, and #ERR data, and suppress #ERR cells to avoid error propagation through multiple functions.
  - Arithmetic functions provide various mathematical functions such as absolute value, power, truncation, rounding, and random number generation.
  - Statistics functions return maximum, minimum, mean (average), and standard deviation data for a group of values.
  - Trigonometry functions provide functions for and relating to sine, cosine, tangent, pi, degrees, and radians.
- Operator functions provide relational operators including =, <>, >, <, >=, and <=.

- String functions format alphanumerical data for display and for communications between the In-Sight vision system and a remote device.

- Vision Data Access (VDA) functions extract individual values from data structures, functions and other cell references.

- Vision Tools functions extract and process image features for further data analysis and decision making.

Note: Category names do not show in the Insert Function list. Functions show up as one list in alphabetical order.

## List of functions

Expand the following function description tables for a list of functions in each function group:

Clocked Data Storage Functions

Function | Description
--- | ---
Accumulate | Syntax: Accumulate(Event,Value,Reset,Preset) Sums a value over an infinite interval. The function returns the integral of a data stream sampled on each occurrence of the specified event. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the event on which to read the specified Value. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function. Note: The Accumulate function buffers the state of a referenced value before that value is updated by any other function that depends on the specified Event.
Value | A reference to the cell containing the source of the data stream to be accumulated. (-16777216 to 16777216; default = 1.000)
Reset | Forces the accumulator to reset to the Preset value.
0 = OFF (default) | The accumulator continues to sum the specified value indefinitely.
1 = ON | The accumulator resets immediately.
Preset | Specifies the minimum value to which the accumulator is reset when Reset is ON (-16777216 to 16777216; default = 0.000).
#### Outputs
Returns | A value representing the summation of the data stream over a time interval since the last Reset.
ClockedMax | Syntax: ClockedMax(Event,Value,Reset,Preset) Samples a stream of values over an infinite interval, then returns the maximum value sampled from the stream during that interval. ## Inputs
Parameter | Description
--- | ---
Event | Specifies the event that forces an update.This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function. Note: ClockedMax samples the state of the referenced value after that value is updated by any other function, unlike the Maximum function, which samples the state of a referenced value before that value is updated by any other function that depends on the specified Event.
Value | A reference to the source cell for the data stream on which a minimum is sought. (-16777216 to 16777216; default = 0).
Reset | Forces the function to reset its internal register to the value specified by Preset.
0 = OFF (default) | The function continues to sample Value in the current data stream.
1 = ON | The function resets the minimum value it returns and begins a new data stream from which to sample.
Preset | Specifies the minimum value to which the function is reset (-16777216 to 16777216; default = -16777216).
#### Outputs
Returns | A value representing the minimum of a data stream over an interval from Reset to current.
ClockedMin | Syntax: ClockedMin(Event,Value,Reset,Preset) Samples a stream of values over an infinite interval, then returns the minimum value sampled from the stream during that interval. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the update event on which to read Value. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function. Note: ClockedMin samples the state of the referenced value after that value is updated by any other function, unlike the Minimum function, which samples the state of a referenced value before that value is updated by any other function that depends on the specified Event.
Value | A reference to the source cell for the data stream on which a minimum is sought (-16777216 to 16777216; default = 0).
Reset | Forces the function to reset its internal register to the value specified by Preset.
0 = OFF (default) | The function continues to sample Value in the current data stream.
1 = ON | The function resets the minimum value it returns and begins a new data stream from which to sample.
Preset | Specifies the minimum value to which the function is reset (-16777216 to 16777216; default = -16777216).
#### Outputs
Returns | A value representing the minimum of a data stream over an interval from Reset to current.
ClockedSum | Syntax: ClockedSum(Event,Value,Reset,Preset)
Count | Syntax: Count(Event,Max Value,Reset,Preset) Counts events over an infinite interval. The function returns the Preset value plus the number of events that occurred since the last reset. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the update event on which to increment the counter. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function.
Max Value | Specifies the highest value allowed before the counter automatically resets itself to the minimum Preset value. (-16777216 to 16777216; default = 16777216)
Reset | Forces the counter to reset to the Preset value.
0 = OFF (default) | The counter is allowed to reach the Max Value before it resets.
1 = ON | The counter resets immediately, even though the Max Value has not been reached.
Preset | Specifies the minimum value to which the counter is reset when the Max Value is reached, or when Reset is ON. (-16777216 to 16777216; default = 0)
#### Outputs
Returns | A value, which is the Preset value plus the number of events that occurred since the last reset.
CountPassFail | Syntax: CountPassFail(Event,Value,CountWhenOffline,ResetEvents.Manual,ResetEvents.Online,ResetEvents.JobLoad) Counts and returns passes, failures and total events for a given referenced value. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the event on which to increment the counter. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function.
Value | Specifies a required reference to the cell containing the source of the data stream to be counted. If no cell is referenced, the function returns an #ERR for all results. The incremented counter, Pass, Fail, or #ERR, is based on the returned Value, as follows:
Pass | Value > 0
Fail | Value = 0
#ERR | Value < 0
Count When Offline | Specifies whether the counters are incremented while the sensor is Offline.
0 = OFF | Do not increment counters when the sensor is Offline.
1 = ON (default) | Increment counters when the sensor is Offline.
Reset Events | Forces the counters to reset depending on specific events.
Manual | Specifies whether the counters are reset to zero when the specified Event occurs. This parameter automatically references the Reset button, which is inserted into the spreadsheet when the function is initially created. Note: If this checkbox is manually toggled in the Property Sheet, the reference to the Reset button is removed. To use the Reset button, this parameter must reference the cell containing the Reset button.
0 = OFF (default) | Do not reset counters when the specified Event occurs.
1 = ON | Reset counters when the specified Event occurs.
Online | When the sensor is put Online, specifies whether the counters are reset to zero after the first Event occurs.
0 = OFF | When the sensor is put Online, do not reset counters after the first Event occurs.
1 = ON (default) | When the sensor is put Online, reset counters after the first Event occurs.
Job Load | Specifies whether the counters are reset to zero when a job is loaded.
0 = OFF | Do not reset counters when a job is loaded.
1 = ON (default) | Reset counters when a job is loaded.
#### Outputs
Returns | A Count data structure containing the incremented counters or #ERR if any of the input parameters are invalid.
Results | When CountPassFail is initially inserted into a cell, a result table and a Reset button are created in the spreadsheet. When the Reset button is pressed, all counters are reset to zero.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
Passes | GetPassCount(Count) | The incremental count of passes. The counter is incremented when the returned Value is greater than zero.
Failures | GetFailCount(Count) | The incremental count of failures. The counter is incremented when the returned Value is equal to zero.
Errors | GetErrorCount(Count) | The incremental count of errors. The counter is incremented when the returned Value is less than zero.
Total | GetTotalCount(Count) | The total number of passes, failures and errors.
Latch | Syntax: Latch(Event,Value) Stores (latches) an input value on the specified event. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the update event on which to read Value. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function.
Value | A reference to the cell containing the data to store (-16777216 to 16777216; default = 0.000).
#### Outputs
Returns | The value stored on the last event.
LatchString | Syntax: LatchString(Event,"String") Stores (latches) an alphanumeric input string on the specified event. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the update event on which to read String. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function.
String | A reference to the cell containing the string to store.
#### Outputs
Returns | The string stored on the last event.
Maximum | Syntax: Maximum(Event,Value,Reset,Preset) Samples a stream of values over an infinite interval, then returns the maximum value sampled from the stream during that interval. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the update event on which to read Value. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function. Note: Maximum samples the state of a referenced value before that value is updated by any other function that depends on the specified Event.
Value | A reference to the source cell for the data stream on which a maximum is sought.
Reset | Forces the function to reset its internal register to the value specified by Preset.
0 = OFF (default) | The function continues to sample Value in the current data stream.
1 = ON | The function resets the maximum value it returns, and begins a new data stream from which to sample.
Preset | Specifies the maximum value to which the function is reset (-16777216 to 16777216; default = -16777216).
#### Outputs
Returns | A value, which is the maximum value in a data stream since the last Reset occurred.
Minimum | Syntax: Minimum(Event,Value,Reset,Preset) Samples a stream of values over an infinite interval, then returns the minimum value sampled from the stream during that interval. #### Inputs
Parameter | Description
--- | ---
Event | Specifies the update event on which to read Value. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function. Note: Minimum samples the state of a referenced value before that value is updated by any other function that depends on the specified Event.
Value | A reference to the source cell for the data stream on which a minimum is sought.
Reset | Forces the function to reset its internal register to the value specified by Preset.
0 = OFF (default) | The function continues to sample Value in the current data stream.
1 = ON | The function resets the minimum value it returns and begins a new data stream from which to sample.
Preset | Specifies the minimum value to which the function is reset (-16777216 to 16777216; default = 16777216).
#### Outputs
Returns | A value representing the minimum of a data stream over an interval from Reset to current.
ShiftRegister | Syntax: ShiftRegister (Event,Value,Number of Steps,Reset) Implements a shift-register array, or data "stream", where the values of the cell are buffered into after each event. Note: After a reset, the first value that is read fills the shift-register. #### Inputs
Event | Specifies the update event on which to read Value. This parameter must be a reference to one of the following: The Acquired keyword, which represents the most recent image acquisition. A cell containing an Event function. A cell containing a Button function. Note: ShiftRegister buffers the state of the referenced value after that value is updated by any other function, unlike the DelayLine function, which buffers the state of a referenced value before that value is updated by any other function that depends on the specified Event.
Value | A reference to the cell containing the source data (-16777216 to 16777216; default = 0).
Number of Steps | Specifies the number of values in the function's internal shift-register array (1 to 5000; default = 10).
Reset | Forces the function to purge itself of previously read values. The first value read after Reset effectively "fills" the shift register.
0 = OFF (default) | The function continues to read in values to the data stream.
1 = ON | The function purges all values from the data stream.
#### Outputs
Returns | A Buffer data structure containing statistics for the specified Value over an interval from Reset to current.
Results | When the function is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
Last | GetValue(Delay, Index) | The last value contained in the structure.
Mean | GetMean(Delay) | The mean of all the values in the structure.
SDev | GetSDev(Delay) | The standard deviation of all the values in the structure.
Min | GetMin(Delay) | The smallest value contained in the structure.
Max | GetMax(Delay) | The largest value contained in the structure.
Additional data elements can be accessed using the following Vision Data Access functions:
Count | GetCount(Delay) | The number of values contained in the structure.
Sum | GetSum(Delay) | The sum of all values contained in the structure.

Geometry Functions

Type | Function | Description
--- | --- | ---
Fit Functions Note: If a Geometry function is using world coordinate data as a reference, the resulting graphics are not displayed correctly. | CircleFromNPoints | Syntax: CircleFromNPoints(Point X 0,Point Y 0,Point X 1,Point Y 1,Point X 2,Point Y 2,...,Point X N,Point Y N,Show) Fits a circle using three or more input points. #### Inputs
Parameter | Description
--- | ---
Point 0 | Specifies the coordinates of the first point.
Point X 0 | The X-coordinate of the first point.
Point Y 0 | The Y-coordinate of the first point.
Point 1 | Specifies the coordinates of the second point.
Point X 1 | The X-coordinate of the second point.
Point Y 1 | The Y-coordinate of the second point.
Point 2 | Specifies the coordinates of the third point.
Point X 2 | The X-coordinate of the third point.
Point Y 2 | The Y-coordinate of the third point.
Point 3..N | Optionally specifies the coordinates of any additional points.
Point X N | The X-coordinate of the Nth point.
Point Y N | The Y-coordinate of the Nth point.
Show | Specifies the graphics items to be displayed on a permanent basis.
0 = hide all | All graphics items are hidden except when the cell containing the CircleFromNPoints function is the active cell in the spreadsheet.
1 = result graphics only | The fitted circle graphic is displayed at all times. The input points are only displayed when the cell containing the CircleFromNPoints function is the active cell in the spreadsheet.
2 = input and result graphics | The fitted circle and the input points are displayed at all times.
#### Outputs
Returns | A CircleFit data structure containing the X, Y, radius and sigma of the fitted circle.
Results | When the function is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X | GetX(CircleFit) | The X-coordinate of the center of the circle.
Y | GetY(CircleFit) | The Y-coordinate of the center of the circle.
Radius | GetRadius(CircleFit) | The radius of the circle.
Sigma | GetSigma(CircleFit) | The square root of the sum of the squares of the distances from the points to the circle divided by the number of points.
Additional data elements can be accessed using the following Vision Data Access functions:
Distance | GetDistance(CircleFit, Index) | The distance between the indexed point and the circle. If the value is negative, the point is within the circle. If the indexed point is invalid, an #ERR is returned.
MaxDist | GetMaxDist(CircleFit) | The distance between the circle and the point farthest from the circle. If the value is negative, the point is within the circle.
MaxDistIndex | GetMaxDistIndex(CircleFit) | The index of the point farthest from the circle.
NPointsUsed | GetNPointsUsed(CircleFit) | The number of points used to fit the circle.
LineFromNPoints | Syntax: LineFromNPoints(Point X 0,Point Y 0,Point X 1,Point Y 1,[...Point X N,Point Y N,Show]) Fits a line using two or more input points. #### Inputs
Parameter | Description
--- | ---
Point 0 | Specifies the coordinates of the first point.
Point X 0 | The X-coordinate of the first point.
Point Y 0 | The Y-coordinate of the first point.
Point 1 | Specifies the coordinates of the second point.
Point X 1 | The X-coordinate of the second point.
Point Y 1 | The Y-coordinate of the second point.
Point 2..N | Specifies the coordinates of any additional points.
Point X N | The X-coordinate of the Nth point.
Point Y N | The Y-coordinate of the Nth point.
Show | Specifies the graphics items to be displayed on a permanent basis.
0 = hide all | All graphics items are hidden except when the cell containing the LineFromNPoints function is the active cell in the spreadsheet.
1 = result graphics only | The fitted line graphic is displayed at all times. The input points are only displayed when the cell containing the LineFromNPoints function is the active cell in the spreadsheet.
2 = input and result graphics | The fitted line and the input points are displayed at all times.
#### Outputs
Returns | A LineFit data structure if two or more valid points are included in data, or #ERR if only one or no valid point is included in data.
Results | When the function is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X0 | GetX(LineFit, 0) | The X-coordinate of the first endpoint.
Y0 | GetY(LineFit, 0) | The Y-coordinate of the first endpoint.
X1 | GetX(LineFit, 1) | The X-coordinate of the second endpoint.
Y1 | GetY(LineFit, 1) | The Y-coordinate of the second endpoint.
Chi2 | GetChi2(LineFit) | The sum of the squares of the distances from the points to the line.
Additional data elements can be accessed using the following Vision Data Access functions.
Distance | GetDistance(LineFit, Index) | The distance between the indexed point and the line.
MaxDist | GetMaxDist(LineFit) | The point that is farthest from the line.
MaxDistIndex | GetMaxDistIndex(LineFit) | The index of the point that is farthest from the line.
NPointsUsed | GetNPointsUsed(LineFit) | The number of points used to compute the line.
Measure | PointToCircle | Syntax: PointToCircle(Point.X,Point.Y,Circle.X,Circle.Y,Circle.Radius,Show) Computes the minimum distance from a point to the nearest point on a circle. If the point is inside the circle, distance is reported as a negative number. #### Inputs
Parameter | Description
--- | ---
Point | Specifies the coordinates of the point, which are used as the origin.
X | The X coordinate of the point.
Y | The Y coordinate of the point.
Circle | Specifies the coordinates and size of the circle.
X | The X-coordinate of the center of the circle.
Y | The Y-coordinate of the center of the circle.
Radius | The radius of the circle.
Show | Specifies the display mode for the graphical overlays of the function on top of the image.
0 = hide all | All graphics are hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = result graphics only | A line segment showing the minimum distance between the point and the circle is displayed at all times.
2 = input and result graphics | The point and the circle, and the line segment between them, are displayed at all times.
#### Outputs
Returns | Dist data structure containing the directed distance between the point and the nearest point on the circle.
Results | When the function is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X0 | GetX(Dist, 0) | The X coordinate of the point.
Y0 | GetY(Dist, 0) | The Y coordinate of the point.
X1 | GetX(Dist, 1) | The X-coordinate of the nearest point on the circle.
Y1 | GetY(Dist, 1) | The Y-coordinate of the nearest point on the circle.
Angle | GetAngle(Dist) | The point-to-point angle.
Distance | GetDistance(Dist) | The point-to-point distance.
PointToLine | Syntax: PointToLine(Point.X,Point.Y,Line.X 0,Line.Y 0,Line.X 1,Line.Y 1,Show) Computes the minimum distance from a point to a line. In this example, the PointToLine function is measuring the distance between a point and a line. The point is the origin, and the angle is calculated based on its position relative to the line. #### Inputs
Parameter | Description
--- | ---
Point | Specifies the coordinates of the point, which are used as the origin.
X | The X coordinate of the point.
Y | The Y coordinate of the point.
Line | Specifies the coordinates of the line.
X 0 | The X coordinate of the first endpoint of the line.
Y 0 | The Y coordinate of the first endpoint of the line.
X 1 | The X coordinate of the second endpoint of the line.
Y 1 | The Y coordinate of the second endpoint of the line.
Show | Specifies the display mode for the graphical overlays of the function on top of the image.
0 = hide all | All graphics are hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = result graphics only | A line segment showing the minimum distance between the point and the input line is displayed at all times.
2 = input and result graphics | The point, the input line, and the line segment between them are displayed at all times.
#### Outputs
Returns | Dist data structure containing the directed distance between the point and the nearest point on the line.
Results | When the function is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X0 | GetX(Dist, 0) | The X coordinate of the point.
Y0 | GetY(Dist, 0) | The Y coordinate of the point.
X1 | GetX(Dist, 1) | The X-coordinate of the nearest point on the line.
Y1 | GetY(Dist, 1) | The Y-coordinate of the nearest point on the line.
Angle | GetAngle(Dist) | The point-to-line angle.
Distance | GetDistance(Dist) | The point-to-line distance.
PointToPoint | Syntax: PointToPoint(Point 0.X,Point 0.Y,Point 1.X,Point 1.Y,Show) Computes the directed distance between two points. In this example, the PointToPoint function is measuring the distance between two points. The angle is calculated based on the first point's position relative to the second. #### Inputs
Parameter | Description
--- | ---
Point 0 | Specifies the coordinates of the first point, which is used as the origin.
X | The X-coordinate of the first point.
Y | The Y-coordinate of the first point.
Point 1 | Specifies the coordinates of the second point.
X | The X-coordinate of the second point.
Y | The Y-coordinate of the second point.
Show | Specifies the display mode for the graphical overlays of the function on top of the image.
0 = hide all | All graphics are hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = result graphics only | A line segment showing the minimum distance between the two input points is displayed at all times.
2 = input and result graphics | The two input points and the line segment between them are displayed at all times.
#### Outputs
Returns | Dist data structure containing the directed distance between the points.
Results | When the function is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X0 | GetX(Dist, 0) | The X-coordinate of the first point.
Y0 | GetY(Dist, 0) | The Y-coordinate of the first point.
X1 | GetX(Dist, 1) | The X-coordinate of the second point.
Y1 | GetY(Dist, 1) | The Y-coordinate of the second point.
Angle | GetAngle(Dist) | The point-to-point angle.
Distance | GetDistance(Dist) | The point-to-point distance.
PointToPointAngle | Syntax: PointToPointAngle(Point 0.X,Point 0.Y,Point 1.X,Point 1.Y) Computes the angle between two points. #### Inputs
Parameter | Description
--- | ---
Point 0 | Specifies the coordinates of the first point, which is used as the origin.
X | The X-coordinate of the first point.
Y | The Y-coordinate of the first point.
Point 1 | Specifies the coordinates of the second point.
X | The X-coordinate of the second point.
Y | The Y-coordinate of the second point.
#### Outputs
Returns | A value containing the angle between the two points, relative to the image X axis.
Note: Unlike most other Measure functions in the Geometry category, PointToPointAngle does not insert a Dist data structure or result table into the spreadsheet.
PointToPointDistance | Syntax: PointToPointDistance(Point 0.X,Point 0.Y,Point 1.X,Point 1.Y) Computes the distance between two points. #### Inputs
Parameter | Description
--- | ---
Point 0 | Specifies the coordinates of the first point.
X | The X-coordinate of the first point.
Y | The Y-coordinate of the first point.
Point 1 | Specifies the coordinates of the second point.
X | The X-coordinate of the second point.
Y | The Y-coordinate of the second point.
#### Outputs
Returns | A value containing the distance between the two points.
Note: Unlike most other Measure functions in the Geometry category, PointToPointDistance does not insert a Dist data structure or result table to the spreadsheet.

Graphics Functions

Type | Function | Description
--- | --- | ---
Control Note: Make sure to use the 'Acquired' keyword to specify the current image. | Button | Syntax: Button(Name,Trigger) Inserts a labeled push button control into the spreadsheet. Optionally, you can configure a button press to signal a spreadsheet event trigger. Tip: To access the property sheet for a Button, right-click the button and select Edit Function. Note: You can control a button control programmatically through In-Sight Native Mode commands, using the EV SetCellValue command. Enter a 1 to press the button down, and a 0 to release the button. Ensure that the command to release the button after pressing it is sent, otherwise the button remains as though it were pressed on. A button click generates two events. The state of the button changes from 0 to 1 when pressing the button down, then from 1 to 0 when releasing the button. If a button is configured to generate a soft event, the event is only triggered once on the down press of the button. #### Inputs
Parameter | Description
--- | ---
Name | Specifies a text string label that appears on the button itself.
Trigger | Optionally specifies a trigger signal to occur when the button is pressed.
-1 = none (default) | No trigger is signaled.
32 = manual | A manual trigger is signaled.
(80 to 87) = soft (0 to 7) | A soft trigger event is signaled.
#### Outputs
Returns | A value of 1 when the button is pressed. Otherwise, the return value is 0.
Results | A labeled Button control.
CheckBox | Syntax: CheckBox(Name) Inserts a labeled checkbox control into the spreadsheet. Note: To access the property sheet for a CheckBox, right-click the CheckBox and select Edit Function. #### Inputs
Parameter | Description
--- | ---
Name | Specifies a text string label to appear next to the CheckBox.
#### Outputs
Returns | A value of 0 when cleared (unchecked), and 1 when selected (checked.)
Results | A labeled CheckBox control.
#### Example A spreadsheet is configured as follows: A3=CheckBox("On") A4=A3 Cell A4 references cell A3 to determine the ON/OFF status of the "On" checkbox. When the checkbox is cleared, the value 0.000 is returned in cell A4. When the checkbox is selected, the value 1.000 is returned.
EditFloat | Syntax: EditFloat(Min,Max) Inserts a floating-point edit control into the spreadsheet. The control behaves like other interactive numeric input controls. Note: To access the property sheet for an EditFloat control, right-click the control and select Edit Function. #### Inputs
Parameter | Description
--- | ---
Min | Specifies the minimum value that the edit box control accepts (-16777216 to 16777216; default = 0).
Max | Specifies the maximum value that the edit box control accepts (-16777216 to 16777216; default = 100).
#### Outputs
Returns | The value entered into the control.
Results | An EditFloat control.
EditInt | Syntax: EditInt(Min,Max) Inserts an integer edit control into the spreadsheet. The control works like all other In-Sight interactive numeric input controls. Note: To access the property sheet for an EditInt control, right-click the control and select Edit Function. #### Inputs
Parameter | Description
--- | ---
Min | Specifies the minimum value that the edit box control accepts (-16777216 to 16777216; default = 0).
Max | Specifies the maximum value that the edit box control accepts (-16777216 to 16777216; default = 255).
#### Outputs
Returns | The value entered into the control.
Results | An EditInt control.
EditString | Syntax: EditString(Max String Length) Inserts an integer edit control into the spreadsheet. The control works like all other In-Sight interactive numeric input controls. Note: To access the property sheet for an EditInt control, right-click the control and select Edit Function. #### Inputs
Parameter | Description
--- | ---
Min | Specifies the minimum value that the edit box control accepts (-16777216 to 16777216; default = 0).
Max | Specifies the maximum value that the edit box control accepts (-16777216 to 16777216; default = 255).
#### Outputs
Returns | The value entered into the control.
Results | An EditInt control.
ListBox | Syntax: ListBox("String0","String1","String2",...) Inserts a drop-down list control in the spreadsheet. Note: Since the ListBox function can accept a variable number of strings, this function is not configured through a property sheet. This function can be configured directly in the cell or in the Formula Bar on the Job Edit toolbar. #### Inputs
Parameter | Description
--- | ---
String0, 1, 2, ... | A variable-length list of individual text strings, each of which returns a different value when selected by a user from the drop-down list.
#### Outputs
Returns | A value representing the index number (zero-based) of the selected item.
Results | A ListBox control. Note: The text string that is currently selected from the list can also be accessed using the GetString Vision Data Access function.
#### Example A spreadsheet is configured as follows: A3=ListBox("Item1","Item2","Item3") A4=A3 The function in cell A3 creates the list control, with "Item1" as the default selection. The index value of Item1 is 0, so the value in cell A4 is 0.000. If the user selects "Item2", then the value in cell A4 is 1.000. If "Item3" is selected, the value in cell A4 is 2.000. #### Vision Data Access Functions Additional data elements can be accessed using the following Vision Data Access functions:
GetString | GetString(ListBox) | Returns the text string.
Image Note: Make sure to use the 'Acquired' keyword to specify the current image. | PlotCircle | Syntax: PlotCircle(Circle.X,Circle.Y,Circle.Radius,Name,Color,Show) Plots a circle on the image. #### Inputs
Parameter | Description
--- | ---
Circle | Specifies the image coordinates of the circle to be plotted (-16777216 to 16777216).
X | The X coordinate of the center of circle.
Y | The Y coordinate of the center of circle.
Radius | The radius of the circle.
Name | Specifies a text label to display with the graphic on the image.
Color | Specifies the color of the plotted graphic. Default: 0x32CD32, LimeGreen; max: 0xFFFFFF. Configure different colors by providing the hexadecimal color code in the cell expression editor. For example, you can obtain the primary colors by mixing the highest intensity of the wanted color with the lowest intensity of the others:
Black | Red | Green | Blue | White
0x000000 | 0xFF0000 | 0x00FF00 | 0x0000FF | 0xFFFFFF
Show | Specifies the display mode for the graphic overlay on the image.
0 = OFF | The graphic is hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = ON (default) | The graphic is displayed at all times.
#### Outputs
Returns | A Plot data structure containing the graphic.
PlotCross | Syntax: PlotCro(Cross.X,Cross.Y,Cross.Angle,Cross.High,Cross.Wide,Name,Color,Show) Plots a cross on the image. #### Inputs
Parameter | Description
--- | ---
Cross | Specifies the image coordinates of the Cross to be plotted (-16777216 to 16777216).
X | The X coordinate of the center of the cross.
Y | The Y coordinate of the center of the cross.
Angle | The cross orientation.
High | The cross height.
Wide | The cross width.
Name | Specifies a text label to display with the graphic on the image.
Color | Specifies the color of the plotted graphic. Default: 0x32CD32, LimeGreen; max: 0xFFFFFF. Configure different colors by providing the hexadecimal color code in the cell expression editor. For example, you can obtain the primary colors by mixing the highest intensity of the wanted color with the lowest intensity of the others:
Black | Red | Green | Blue | White
0x000000 | 0xFF0000 | 0x00FF00 | 0x0000FF | 0xFFFFFF
Show | Specifies the display mode for the graphic overlay on the image.
0 = OFF | The graphic is hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = ON (default) | The graphic is displayed at all times.
#### Outputs
Returns | A Plot data structure containing the graphic.
PlotLine | Syntax: PlotLine(Line.X 0,Line.Y 0,Line.X 1,Line.Y 1,Name,Color,Show,Start Point Adornment,End Point Adornment) Plots a line segment in the image. #### Inputs
Parameter | Description
--- | ---
Line | Specifies the image coordinates of the Line to be plotted ().
X 0 | The X coordinate of the first endpoint of the line.
Y 0 | The Y coordinate of the first endpoint of the line.
X 1 | The X coordinate of the second endpoint of the line.
Y 1 | The Y coordinate of the second endpoint of the line.
Name | Specifies a text label to display with the graphic on the image.
Color | Specifies the color of the plotted graphic. Default: 0x32CD32, LimeGreen; max: 0xFFFFFF. Configure different colors by providing the hexadecimal color code in the cell expression editor. For example, you can obtain the primary colors by mixing the highest intensity of the wanted color with the lowest intensity of the others:
Black | Red | Green | Blue | White
0x000000 | 0xFF0000 | 0x00FF00 | 0x0000FF | 0xFFFFFF
Show | Specifies the display mode for the graphic overlay on the image.
0 = OFF | The graphic is hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = ON (default) | The graphic is displayed at all times.
Start Point Adornment | Specifies the adornment for the starting point of the line.
0 = None (default)
1 = Arrowhead
End Point Adornment | Specifies the adornment for the ending point of the line.
0 = None (default)
1 = Arrowhead
#### Outputs
Returns | A Plot data structure containing the graphic.
PlotPoint | Syntax: PlotPoint(Point.X,Point.Y,Name,Color,Show) Plots a Point crosshair in the image. #### Inputs
Parameter | Description
--- | ---
Point | Specifies the image coordinates of the point to be plotted (-16777216 to 16777216).
X | The X coordinate of the point.
Y | The Y coordinate of the point.
Name | Specifies a text label to display with the graphic on the image.
Color | Specifies the color of the plotted graphic. Default: 0x32CD32, LimeGreen; max: 0xFFFFFF. Configure different colors by providing the hexadecimal color code in the cell expression editor. For example, you can obtain the primary colors by mixing the highest intensity of the wanted color with the lowest intensity of the others:
Black | Red | Green | Blue | White
0x000000 | 0xFF0000 | 0x00FF00 | 0x0000FF | 0xFFFFFF
Show | Specifies the display mode for the graphic overlay on the image.
0 = OFF | The graphic is hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = ON (default) | The graphic is displayed at all times.
#### Outputs
Returns | A Plot data structure containing the graphic.
PlotString | Syntax: PlotString(String,Point.X,Point.Y,Color,Show) Plots a text string on the image. Tip: After inserting the PlotString function into the spreadsheet, highlight the spreadsheet cell of the function and use the Format Cells dialog to format the Font, Font Size and Font Style of the PlotString cell and the plotted text string. #### Inputs
Parameter | Description
--- | ---
String | Specifies the text string to be plotted.
Point | Specifies the image coordinates of the string to be plotted (-16777216 to 16777216).
X | The X coordinate of the string.
Y | The Y coordinate of the string.
Color | Specifies the color of the plotted graphic. Default: 0x32CD32, LimeGreen; max: 0xFFFFFF. Configure different colors by providing the hexadecimal color code in the cell expression editor. For example, you can obtain the primary colors by mixing the highest intensity of the wanted color with the lowest intensity of the others:
Black | Red | Green | Blue | White
0x000000 | 0xFF0000 | 0x00FF00 | 0x0000FF | 0xFFFFFF
Show | Specifies the display mode for the graphic overlay on the image.
0 = OFF | The graphic is hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = ON (default) | The graphic is displayed at all times.
#### Outputs
Returns | A Plot data structure containing the graphic.

Mathematics Functions

Type | Function | Description
--- | --- | ---
Logic | And | Syntax: And(Value1, Value2, ...) Returns the logical AND of a variable-length list of values.
BitAnd | BitAnd(Value1, Value2, ...) Returns the bitwise AND of values. Note: Processes only the lower 16 bits. Examples BitAnd(45, 77) returns 13. 45 = 0000 0000 0010 1101 in binary. 77 = 0000 0000 0100 1101 in binary. Individually comparing each common bit in these two 16-bit binary numbers using the And operation yields 0000 0000 0000 1101, which = 13 in decimal.
BitNot | Syntax: BitNot(Value) Returns the bitwise inverse of Value. Note: Processes only the lower 16 bits. Examples BitNot(45) returns 65490. 45 = 0000 0000 0010 1101 in binary. Inverting each 0 to a 1 and each 1 to a 0 yields 1111 1111 1101 0010 in binary, which is 65490 in decimal.
BitOr | Syntax: BitOr(Value1, Value2, ...) Returns the bitwise OR of values. Note: Processes only the lower 16 bits. Examples BitOr(45, 77) returns 109. 45 = 0000 0000 0010 1101 in binary. 77 = 0000 0000 0100 1101 in binary. Individually comparing each common bit in these two 16-bit binary numbers using the Or operation yields 0000 0000 0110 1101, which = 109 in decimal.
BitXor | Syntax: BitXor(Value1, Value2, ...) Returns the bitwise XOR (exclusive OR) of Values. (Logical XOR the result is TRUE if one – and only one – of the bits is TRUE. The result is FALSE if 2 or more bits are equal.) Note: Processes only the lower 16 bits. Examples BitXor(45, 77) returns 96. 45 = 0000 0000 0010 1101 in binary 77 = 0000 0000 0100 1101 in binary. 0110 0000 are the only non-common bits between 45 and 77, as demonstrated below.
45 | 77 | XOR per bit | XOR bit
--- | --- | --- | ---
0 | 0 | two 0s ≥ XOR FALSE | 0 (FALSE)
0 | 1 | only one 1 ≥ XOR TRUE | 1 (TRUE)
1 | 0 | only one 1 ≥ XOR TRUE | 1 (TRUE)
0 | 0 | two 0s ≥ XOR FALSE | 0 (FALSE)
1 | 1 | two 1s ≥ XOR FALSE | 0 (FALSE)
1 | 1 | two 1s ≥ XOR FALSE | 0 (FALSE)
0 | 0 | two 0s ≥ XOR FALSE | 0 (FALSE)
1 | 1 | two 0s≥ XOR FALSE | 0 (FALSE)
0110 0000 = 96 in decimal.
If | Syntax: If(Cond, Value1, Value2) Returns Value1 if Cond is non-zero. Otherwise, returns Value2. Note: If the condition or the arguments reference empty cells, they are interpreted as a zero (FALSE).
InRange | Syntax: InRange(Value, Start, End) Returns TRUE if Min(Start,End) ≤ Value ≤ Max(Start,End).
InTolerance | Syntax: InTolerance(actual, expected, tolerance %, margin) Determines if the actual value is within the relative tolerance of the expected value, if the difference between the two values is above the margin.
Not | Syntax: Not(Value) Returns 0 if Value is non-zero, or 1 if Value is 0. (Logical Inverse) Examples Not(-12345) returns 0. Not(3.14) returns 0. Not(2-1) returns 0. Not(1-1) returns 1.
OneShot | Syntax: OneShot(Val) Returns true if Val is 1 on this execution and was 0 in the prior execution.
Or | Syntax: Or(Value1, Value2, ...) Returns 0 if all values are zero. Otherwise, returns 1. (Logical OR the result is TRUE if any of the Values are TRUE.) Examples Or(45, -77) returns 1. Or(-1, 0, 1) returns 1. Or(0, 1-1) returns 0.
Lookup Note: For function arguments that require a text string, you cannot supply the string directly through If, Switch, or Choose. An example of an invalid text string:, Len(If(...)) To resolve this issue, place If, Switch, or Choose in a separate cell and create a reference to that cell. You can also change the order in the syntax: you can enter “If(Len( ) )” into one cell, that gives a valid text string. | Choose | Syntax: Choose(Index, Value0, [Value1, ...]) Returns the value of the indexed argument from a variable-length list.
CountError | Syntax: CountError(Cell1, [Cell2, ...]) Returns the number of errors in one or more cells or cell ranges.
ErrFree | Syntax: ErrFree(Cell or Cell Range) Converts #ERR to empty cells to suppress error propagation.
If | Syntax: If(Cond, Value1, Value2) Returns Value1 if Test is nonzero. Returns Value2 if Test is zero.
MaxI | Syntax: MaxI(Value0, [Value1, ...]) Returns the index of the maximum Value from a variable-length list of values.
MinI | Syntax: MinI(Value0, [Value1, ...]) Returns the index of the minimum Value from a variable-length list of values.
NthMaxI | Syntax: NthMaxI(N, Value0, [Value1, ...]) Returns the index of the Nth-largest Value from a variable-length list of values.
NthMinI | Syntax: NthMinI(N, Value0, [Value1, ...]) Returns the index of the Nth-smallest Value from a variable-length list of values.
Switch | Syntax: Switch(FindCase, Default, Case0, Value0, [Case1, Value1, ...]) Returns the value corresponding to the first Case that matches the FindCase. If the indexed case is FALSE, then the specified Default value is returned. If more than one Case in the formula matches the FindCase, then the value corresponding to the first matching Case is returned. Switch Example A4 = Switch(A2,-1,2,"C",3,"B",A3,"A") If cell A2=2, the value returned in cell A4 would be C. If cell A2=3, the value returned in cell A4 would be B. If cell A2=5, the value returned to cell A4 would be the default, -1, because there is no Case in the formula that matches the FindCase.
Arithmetic | Abs | Syntax: Abs(Value) Returns the absolute value of Value.
Exp | Syntax: Exp(Value) Returns e raised to the power of Value.
Int | Syntax: Int(Value) Returns the specified value rounded down to the next smaller integer.
Mod | Syntax: Mod(Value1, Value2) Returns the remainder of Value1 divided by Value2.
Power | Syntax: Power(Base, Exp) Returns Base raised to the power of Exp.
Rand | Syntax: Rand(Event) Returns a random Number (0.0 to 1.0) on an input Event. Each event triggers a new random number. Note: Rand must be the only item in the cell.
Round | Syntax: Round(Value) Returns Value rounded to the nearest integer.
RoundDown | Syntax: RoundDown(Value) Returns Value truncated down to the next-smaller integer.
RoundUp | Syntax: RoundUp(Value) Returns Value rounded up to the next-larger integer.
Sqrt | Syntax: Sqrt(Value) Returns the square root of Value.
Sum | Syntax: Sum(Value1, [Value2, ...]) Returns the sum of a variable-length list of Values.
Trunc | Syntax: Trunc(Value) Returns Value truncated toward zero to an integer. The result is Value without any fraction.
Operators Note: When certain snippets are inserted into the spreadsheet, the formula that appears in the Job Edit Toolbar may contain characters such as !, &&, ||, ==, <>, >=, <=, and !=. These characters are alternative code for the following logical and comparison operators: | NOT | Syntax: ! Logical NOT
AND | Syntax: && Logical AND
OR | Syntax: || Logical OR
Statistics | ComputeStats | Syntax: ComputeStats Computes statistics for a referenced value.
Max | Syntax: Max(Value0, [Value1, ...]) Returns the maximum Value from a variable-length list of Values.
Mean | Syntax: Mean(Value0, [Value1, ...]) Returns the average of a variable-length list of Values.
Min | Syntax: Min(Value0, [Value1, ...]) Returns the minimum value from a variable-length list of Values.
NthMax | Syntax: NthMax(N, Value0, [Value1, ...]) Returns Nth-largest value from a variable-length list of Values.
NthMin | Syntax: NthMin(N, Value0, [Value1, ...]) Returns Nth-smallest value from a variable-length list of Values.
SDev | Syntax: SDev(Value0, Value1, [Value2, ...]) Returns the biased standard deviation (where the denominator is N-1) of a variable-length list of Values.
SDevUnbiased | Syntax: SDevUnbiased(Value0, Value1, [Value2, ...]) Returns the unbiased standard deviation (where the denominator is N) of a variable-length list of Values.
Trigonometry | ACos | Syntax: ACos(Value) Returns the arc cosine of Value in degrees. Note: -1 ≤ Value ≤ 1
ASin | Syntax: ASin(Value) Returns the arc sine of Value in degrees. Note: -1 ≤ Value ≤ 1
ATan | Syntax: ATan(Value) Returns the arc tangent of Value in degrees, ±90.
ATan2 | Syntax: ATan2(DY,DX) Returns the arc tangent of the vector (x,y) = (DY,DX) in degrees, ±180.
Cos | Syntax: Cos(Angle) Returns the cosine of Angle in degrees.
Degrees | Syntax: Degrees(Radians) Returns an angle in degrees, given a value in radians.
Pi | Syntax: Pi Returns the value of pi ≈ 3.142.
Radians | Syntax: Radians(Degrees) Returns an angle in radians, given a value in degrees.
Sin | Syntax: Sin(Angle) Returns the sine of Angle in degrees.
Tan | Syntax: Tan(Angle) Returns the tangent of Angle in degrees.

Structure Functions

Function | Description
--- | ---
Circle | Syntax: Circle(Fixture.X,Fixture.Y,Fixture.Theta,Circle.X,Circle.Y,Circle.Radius,Show) Creates a fixtured Circle structure. #### Inputs Note: The Fixture and Circle parameters must be defined within the bounds of the image; otherwise, the function returns #ERR.
Parameter | Description
--- | ---
Fixture | Specifies the image coordinate system in which the circle is defined.
X | The X-offset.
Y | The Y-offset.
Theta | The orientation.
Circle | Specifies the size and position of the circle, in fixture coordinates.
X | The X-offset of the circle.
Y | The Y-offset of the circle.
Radius | The radius of the circle (1 to 16777216 ; default = 100).
Show | Specifies the display mode for the circle graphical overlay on the image.
0 = hide all (default) | The circle structure is not displayed unless the cell containing the Circle function is highlighted in the spreadsheet.
2 = input graphics only | The circle structure is displayed at all times.
#### Outputs
Returns | A Circle data structure, or #ERR if any of the input parameters are invalid.
Results | When Circle is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X | GetX(Circle) | The X-offset of the center of the circle, in image coordinates.
Y | GetY(Circle) | The Y-offset of the center of the circle, in image coordinates.
Radius | GetRadius(Circle) | The radius of the circle.
Fixture | Syntax: Fixture(Fixture.X,Fixture.Y,Fixture.Theta,Show Creates a Fixture structure. #### Inputs
Parameter | Description.
--- | ---
Fixture | Specifies the image coordinate system in which the fixture is defined.
X | The X-offset.
Y | The Y-offset.
Theta | The orientation.
Show | Specifies the display mode for the Fixture point graphical overlay on the image.
0 = hide all (default) | The fixture point graphic is not displayed unless the cell containing the Fixture function is highlighted in the spreadsheet.
2 = input graphics only | The fixture point graphic is displayed at all times.
#### Outputs
Returns | A Fixture data structure, or #ERR if any of the input parameters are invalid.
Results | When Fixture is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X | GetX(Fixture) | Returns the X-offset of the fixture, in image coordinates.
Y | GetY(Fixture) | Returns the Y-offset of the fixture, in image coordinates.
Angle | GetAngle(Fixture) | Returns the orientation angle, in image coordinates.
Line | Syntax: Line(Fixture.X,Fixture.Y,Fixture.Theta,Line.X 0,Line.Y 0,Line.X 1,Line.Y 1,Show) Creates a fixtured Line structure. #### Inputs Note: The Fixture and Line parameters must be defined within the bounds of the image. Otherwise, the function returns #ERR.
Parameter | Description
--- | ---
Fixture | Specifies the image coordinate system in which the line is defined.
X | The X-offset.
Y | The Y-offset.
Theta | The orientation.
Line | Specifies the endpoints of the line.
X 0 | The X-offset of the first endpoint.
Y 0 | The Y-offset of the first endpoint.
X 1 | The X-offset of the second endpoint.
Y 1 | The Y-offset of the second endpoint.
Show | Specifies the display mode for the Line graphic overlay on the image.
0 = hide all (default) | The line structure is not displayed unless the cell containing the Line function is highlighted in the spreadsheet.
2 = input graphics only | The line structure is displayed at all times.
#### Outputs
Returns | A Line data structure, or #ERR if any of the input parameters are invalid.
Results | When Line is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X0 | GetX(Line, 0) | The X-offset of the first endpoint, in image coordinates.
Y0 | GetY(Line, 0) | The Y-offset of the first endpoint, in image coordinates.
X1 | GetX(Line, 1) | The X-offset of the second endpoint, in image coordinates.
Y1 | GetY(Line, 1) | The Y-offset of the second endpoint, in image coordinates.
Point | Syntax: Point(Fixture.X,Fixture.Y,Fixture.Theta,Point.X,Point.Y,Show) Creates a fixtured Point structure. #### Inputs
Parameter | Description
--- | ---
Fixture | Specifies the image coordinate system in which the point is defined.
X | The X-offset.
Y | The Y-offset.
Theta | The orientation.
Point | Specifies the location of the point, in fixture coordinates.
X | The X-offset of the cross.
Y | The Y-offset of the cross.
Note: The Fixture and Point parameters must be defined within the bounds of the image. Otherwise, the function returns #ERR.
Show | Specifies the display mode for the Point overlay graphic on the image.
0 = hide all (default) | The point structure is hidden unless the cell containing the Point function is highlighted in the spreadsheet.
2 = input graphics only | The point structure is displayed at all times.
#### Outputs
Returns | A Point data structure, or #ERR if any of the input parameters are invalid.
Results | When Point is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X | GetX(Point) | The X-offset of the point, in image coordinates.
Y | GetY(Point) | The Y-offset of the point, in image coordinates.
Region | Syntax: Region(Fixture.X,Fixture.Y,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Region.Curve,Show) Creates a fixtured Region structure. #### Inputs Note: The Fixture and Region parameters must be defined within the bounds of the image; otherwise, the function will return #ERR.
Parameter | Description
--- | ---
Fixture | Specifies the image coordinate system in which the region is defined.
X | The X-offset.
Y | The Y-offset.
Theta | The orientation.
Region | Specifies the position, size, rotation, and curvature (if an annular sector, shaped like a circle or ring). Regions are always defined within the coordinate system of a Fixture.
X | The X-offset of the origin, in fixture coordinates.
Y | The Y-offset of the origin, in fixture coordinates.
High | The dimension along the X-axis of the region.
Wide | The dimension along the Y-axis of the region.
Angle | The orientation, in fixture coordinates.
Curve | The angular deviation between the x-axis and the opposing boundary line of the region.
Show | Specifies the display mode for the Region graphic overlay on the image.
0 = hide all (default) | The region structure graphic is hidden unless the cell containing the Region function is highlighted in the spreadsheet.
2 = input graphics only | The region structure graphic is displayed at all times.
#### Outputs
Returns | A Region data structure, or #ERR if any of the input parameters are invalid.
Results | When Region is initially inserted into a cell, a result table is created in the spreadsheet.
#### Vision Data Access Functions The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table.
X | GetX(Structure, [Index1], [Index2]) | Returns an X coordinate. Note: Index2, Edges-only, specifies an end point (0 or 1). Index2, ReadIDMax speficies symbol corner.
Y | GetY(Structure, [Index1], [Index2]) | Returns a Y coordinate. Note: Index2, Edges-only, specifies an end point (0 or 1). Index2, ReadIDMax speficies symbol corner.
High | GetHigh(Region) | The dimension along the X-axis of the region.
Wide | GetWide(Region) | The dimension along the Y-axis of the region.
Angle | GetAngle(Region) | The orientation, in image coordinates.
Curve | GetCurve(Region) | The angular deviation between the x-axis and the opposing boundary line of the region.

Text String Functions

Function | Description
--- | ---
Code | Syntax: Code(Text) Returns the integer value corresponding to the ASCII code for the first character in a string. Code Example If cell A2 contains the alphanumeric string, "ABC123", then the function Code(A2) returns 65.000, the ASCII code for "A".
Concatenate | Syntax: Concatenate(Arg1, [Arg2, Arg3, ...]) Returns the concatenation of multiple alphanumeric text strings. Numeric arguments are automatically converted to text. Note: The In-Sight 2000-110/120/120C vision sensor is only capable of returning Pass/Fail data as Output data, and the return value is converted to 0 or 1. Concatenate Example If cell A2 contains the alphanumeric string "A1B1", cell A3 contains the alphanumeric string "C1D2", and cell A4 contains the floating-point number 4.556, then the function Concatenate(A2,A3,A4) returns "A1B1C1D24.556"
Exact | Syntax: Exact(Text1, Text2) Returns 1 if Text1 and Text2 are identical, else 0. Note: Exact is case-sensitive. Exact Examples If cell A2 contains the string, "ABC123", and cell A3 contains the string, "ABC1234", then Exact(A2,A3) returns 0.000. If cell A2 contains the string, "VISION", and cell A3 contains the string, "VISION", then Exact(A2,A3) returns 1.000
Find | Syntax: Find(FindText, SrcText, [StartChar]) Returns the indexed position of the string Text1 contained in the string Text2. The search for Text1 starts at the optionally-specified StartChar position within Text2. Note: Find is case-sensitive. Find Examples If cell A2 contains the string "123" and cell A3 contains the string "ABC123", then Find(A2,A3,2) returns the (zero-based) Index value 3.000. The function Find(A2,A3,4) returns -1.000, because the entire string "123" cannot be found in the string "ABC123" if the search begins at Index 4.
Left | Syntax: Left(Text, NumChars) Returns the leftmost number of characters (NumChars) from a Text string. Left Example If cell A2 contains the alphanumeric string, "ABC123", then the function Left(A2,2) returns the string "AB".
Len | Syntax: Len(Text) Returns the number of characters (bytes) in a Text string. Len Example If cell A2 contains the alphanumeric string, "ABC123", then the function Len(A2) returns the integer value 6.000.
Lower | Syntax: Lower(Text) Returns Text converted to lowercase. Lower Example If cell A2 contains the alphanumeric string, "ABC123", then the function Lower(A2) returns the string "abc123".
Mid | Syntax: Mid(Text, StartChar, NumChars) Returns the Text starting from the indexed StartChar position in the alphanumeric string, for as many characters as specified by NumChars. Mid Example If cell A2 contains the alphanumeric string, "ABC123", then the function Mid(A2,2,2) returns the string "C1".
Replace | Syntax: Replace(SrcText, StartChar, NumChars, NewText) Returns SrcText, modified by NewText at the indexed position StartChar. Replace Example If cell A2 contains the alphanumeric string, "ABC123", and cell A3 contains the string "123", then Replace(A2,0,3,A3) returns the string "123123".
Right | Syntax: Right(Text, NumChars) Returns the rightmost number of characters (NumChars) from a Text string. Right Example If cell A2 contains the string, "ABC123", then Right(A2,2) returns the string "23".
Stringf | Syntax: Stringf(Format-string, [Text or Value, ...]) Returns a text string constructed using a "C" library standard Format-string. Tip: The FormatString function supports most Format-string parameters. Use the FormatString dialog to automatically configure the parameters within In-Sight Explorer. Note: The In-Sight 2000-110/120/120C vision sensor is only capable of returning Pass/Fail data as Output data, and the return value is converted to 0 or 1. The format-string must be enclosed in quotes ("). The format-string parameters are case-sensitive. When using the Stringf function, the backslash "\" is used to indicate a format control character follows. If a backslash is not followed by a control character ("n", "r", or "t") then the backslash is ignored. To display a single backslash, two backslashes must be entered (Example: Stringf("C:\\InSight2\\") = "C:\InSight2\"). Non-printable/control code ASCII characters are displayed as either a symbol or "garbage" text. Available Format-string parameters are:
%c | Returns the ASCII character corresponding to an integer Value. When supplied with an alphanumeric text string, returns the first character. Stringf %c Example If cell A2 contains the integer value 65.000, then Stringf("%c",A2) returns the character "A", which is the character corresponding to ASCII code 65. The function Stringf("Value = %c",A2) returns the string "Value = A". If cell A2 contains the string "123ABC", then Stringf("%c",A2) returns the character "1".
%d | Returns a string containing an integer Value. Stringf %d Examples If cell A2 contains the floating point value 123.456, then Stringf("%d",A2) returns the numeric string "123". The function Stringf("Value = %d",A2) returns the alphanumeric string "Value = 123". If cell A2 contains the string "ABC123", then Stringf("%d",A2) returns the numeric string "65", the ASCII code for the character "A".
%e | Returns a string containing a Scientific Notation Value. The number of decimal places may be specified by inserting a decimal point (.) and a number between the % and e parameters. Stringf %e Examples If cell A2 contains the floating point value 123.456, then Stringf("%e",A2) returns the numeric string "1.234560e+02". The function Stringf("%.1e",A2) returns the numeric string "1.2e+02", because only one number after the decimal point is specified.
%f | Returns a string containing a floating point Value. The number of decimal places may be specified by inserting a decimal point (.) and a number between the % and f parameters. Stringf %f Examples If cell A2 contains the floating point value 123.456, then Stringf("%f",A2) returns the numeric string "123.456001". The function Stringf("%.1f",A2) returns the numeric string "123.5", because only one number after the decimal point is specified.
%H | Returns a string containing the specific Host Name of the In-Sight sensor. Stringf %H Example If a cell contains the function Stringf("Host Name: %H") on an In-Sight sensor with the host name "is3k010203", the function returns the alphanumeric string "Host Name: is3k010203".
%I | Returns a string containing the specific IP Address of the In-Sight sensor. Stringf %I Example If a cell contains the function Stringf("IP Address: %I") on an In-Sight sensor with the IP Address "198.232.26.1", the function returns the alphanumeric string "IP Address: 198.232.26.1".
%M | Returns a string containing the specific Media Access Control (MAC) address of the In-Sight sensor. The MAC address is a hardware address that identifies a specific node of a network. Every In-Sight vision system has a unique MAC address assigned to it, which cannot be changed. For example, 00-d0-24-01-02-03. To locate the MAC address of an In-Sight vision system, look at the serial number label affixed to the vision system. Alternately, you can open the About In-Sight Explorer dialog. If you are using a vision system that has two Ethernet ports, for example the IS3800, use %M0 for the first and %M1 for the second MAC address. Stringf %M Example If a cell contains the function Stringf("MAC Address: %M") on an In-Sight sensor with the MAC Address "00-d0-24-01-02-03", the function returns the alphanumeric string "MAC Address: 00:d0:24:01:02:03".
%o | Returns a string containing the octal value for an integer, or the first character in an alphanumeric string. Stringf %o Examples If cell A2 contains the integer value 123.000, then Stringf("%o",A2) returns the numeric string "173", the octal value for the integer 123. If cell A2 contains the string "ABC123" then Stringf("%o",A2) returns the numeric string "101", the octal value for the character "A".
%s | Returns a string with alphanumeric characters appended. Stringf %s Examples If cell A2 contains the string "ABC", then Stringf("%s123",A2) returns the alphanumeric string "ABC123". If cell A2 contains the numeric string "123", then Stringf("%s.450",A2) returns the numeric string "123.450".
%T | Returns a string with the specific model type of the In-Sight sensor. Stringf %T Example If a cell contains the function Stringf("Model Type: %T") on an In-Sight 5400 sensor, the function returns the alphanumeric string "Model Type: 5400".
%u | Returns a string containing an unsigned integer Value. Stringf %u Examples If cell A2 contains the floating point value 123.456, then Stringf("%u",A2) returns the numeric string "123". The function Stringf("Value = %u",A2) returns the alphanumeric string "Value = 123". If cell A2 contains the string "ABC123", then Stringf("%u",A2) returns the numeric string "65", the ASCII code for the character "A".
%V | Returns a string containing the specific firmware version of the In-Sight sensor. Stringf %V Example If a cell contains the function Stringf("Firmware Version: %V") on an In-Sight sensor running firmware version 3.40.01, the function returns the alphanumeric string "Firmware Version: 3.40.01 (475)".
%x or %X | Returns a string containing the hexadecimal value for an integer value, or the first character in an alphanumeric string. Stringf %x Examples If cell A2 contains the integer value 123.000, then Stringf("%x",A2) returns the string "7b", the hex value for the integer 123. If cell A2 contains the string "ABC123", then Stringf("%x",A2) returns the numeric string "41", the hex value for the character "A".
The following Format-string parameters are used primarily for text formatting. For example, formatting the text of an email message in the WriteSMTP function:
\x## | Inserts the ASCII character specified by a hexadecimal number ## into the text. Stringf \x## Example If cell A2 contains Stringf("\x02123\x1bABC\x03456"), then the cell displays: ("<STX>123<ESC>ABC<ETX>456").
\n | Inserts a line feed into the text. This parameter is usually used in conjunction with \r (carriage return).
\r | Inserts a carriage return into the text. This parameter is usually used in conjunction with \n (line feed).
\t | Inserts a tab into the text.
Strtol | Syntax: Strtol(IntegerText) Converts numeric characters (decimal, hexadecimal, and octal) at the beginning of an alphanumeric string into an integer. Hexadecimal characters must begin with "0x" and octal characters must begin with "0". Strtol Examples Decimal: If cell A2 contains the text string "123ABC", then the function Strtol(A2) returns the integer value 123.000. Hexadecimal: If cell A2 contains the text string "0x123", Strtol(A2) returns the integer value 291.000. "0x12AB" = 4,779.000, since "A" and "B" are hexadecimal characters. "0x12GB" = 18.000, since "G" is not a hexadecimal character. Octal: If cell A2 contains the text string "0123ABC", Strtol(A2) returns the integer value 83.000.
Substitute | Syntax: Substitute(SrcText, OldText, NewText, [Instance]) Returns a text string constructed by substituting NewText for each occurrence of OldText in SrcText. If an optional Instance index is specified, then only that instance of the text is replaced. Substitute Example If cell A2 contains the text string "ABC123123", cell A3 contains the string "123", and cell A4 contains the string "abc", then Substitute(A2,A3,A4,1) replaces the second instance of "123" in SrcText and returns the string "ABC123abc".
Token | Syntax: Token(Text, Delimiter, Instance) Returns the text located at the specified Instance index (occurrence) of a delimited string. The Delimiter must be enclosed in quotes (") in the function. Token Example If cell A2 contains the comma delimited string "A,B,C,1,2,3" then Token(A2,",",2) returns "C" because C is at index 2 in the text.
Trim | Syntax: Trim(Text) Returns Text stripped of leading and trailing spaces, leaving only a single space between words (if any). All control characters (Carriage Return, Line Feed, etc.) are also stripped. Trim Example If cell A2 contains the string " ABC 123 ", then Trim(A2) returns the string "ABC 123".
Upper | Syntax: Upper(Text) Returns Text converted to uppercase. Upper Example If cell A2 contains the alphanumeric string, "abc123", then the function Upper(A2) returns the string "ABC123".
Value | Syntax: Value(NumericText) Returns the floating point value of NumericText. Subsequent non-numeric characters are ignored. Value Example If cell A2 contains the numeric string "123.4", then the function Value(A2) returns the floating point value 123.400. Note: An In-Sight cell allows you to enter up to 7-digit numeric value. If the Value function references a numeric text that has more than 8 digits, the value may not be exact due to the limitations of the floating point data type. For example: A2 = '68456668 A3 = Value(A2) In this case, the function returns 68456672.000.

Vision Data Access Functions

Type | Function | Description
--- | --- | ---
AutoLearnClassify | GetClassLabel | Syntax: GetClassLabel (Structure, [Index], [Model]) To use this function, add classes and then add images to each of the classes Note: Make sure to use the 'Acquired' keyword to specify the current image. GetClassLabel returns the string associated with each class.
GetModelHealth | Syntax: GetModelHealth(Structure) To use this function, add classes and then add images to each of the classes. Note: Make sure to use the 'Acquired' keyword to specify the current image. GetModelHealth returns a number (0-100) that represents the ‘health’ of the model, which indicates how likely the model is to be correct.
GetNClasses | Sytnax: GetNClasses(Structure) To use this function, add classes and then add images to each of the classes. Note: Make sure to use the 'Acquired' keyword to specify the current image. GetNClasses returns the number of classes-
GetNImages | Syntax: GetNImages(Structure, [Index], [Model]) To use this function, add classes and then add images to each of the classes. Note: Make sure to use the 'Acquired' keyword to specify the current image. GetNImages returns the number of images in each class.
Blobs | GetAngle | Syntax: GetAngle(Blobs, Index) Returns the angle of a blob's center of mass, relative to the center of the Region of Interest (ROI), that defines the area of the image to be inspected. The center of mass of a blob represents the blob's balance point. If a sheet of a uniform material were cut out in the shape of the blob, the point upon which the blob would balance is the center of mass. Note that the center of mass of a blob might not actually lie within the blob itself. For example, assume that the black region depicted in the following image is a blob, identified by the ExtractBlobs function. The red dot represents the blob's center of mass. The X-coordinate and Y-coordinate of the center of mass are returned by the GetX and GetY Vision Data Access functions, respectively.
GetArea | Syntax: GetArea(Blobs, Index) Returns the area (in pixels) of a blob. The area of a blob is calculated by counting the number of pixels contained within the blob. For example, consider the enlarged blob, shown in the following image: By counting the pixels, we can see that this blob has an area of 8 pixels.
GetHeight | Syntax: GetHeight(Blobs, Index) Returns the height of the indexed blob.
CircleFit | GetDistance | Syntax: GetDistance(CircleFit, Index) Returns the distance between the indexed point and the circle. If the value is negative, the point is within the circle. If the indexed point is invalid, an #ERR is returned.
GetMaxDist | Syntax: GetMaxDist(CircleFit) Returns the distance between the circle and the point farthest from the circle. If the value is negative, the point is within the circle.
GetMaxDistIndex | Syntax: GetMaxDistIndex(CircleFit) Returns the index of the point farthest from the circle.
GetNPointsUsed | Syntax: GetNPointsUsed(CircleFit) Returns the number of points used to fit the circle.
GetRadius | Syntax: GetRadius(CircleFit) Returns the radius of the circle.
GetSigma | Syntax: GetSigma(CircleFit) Returns the square root of the sum of the squares of the distances from the points to the circle divided by the number of points.
Clocked Data Storage | GetCount | Syntax: GetCount(Delay) Returns the Count value from a Delay structure.
GetErrorCount | Syntax: GetErrorCount(Count) Returns the incremental count of errors from a Count structure. The counter is incremented when the returned Value is less than zero.
GetFailCount | Syntax: GetFailCount(Count) Returns the incremental count of failures from a Count structure. The counter is incremented when the returned Value is equal to zero.
GetPassCount | Syntax: GetPassCount(Count) Returns the incremental count of passes from a Count structure. The counter is incremented when the returned Value is greater than zero.
GetTotalCount | Syntax: GetTotalCount(Count) Returns the total number of passes, failures and errors from a Count structure.
Controls | GetString | Syntax: GetString(ListBox) Returns the text string. If a cell containing the ListBox function is referenced, the text string that is currently selected from the list is returned.
Dist | GetDistance | Syntax: GetDistance(Dist) Returns the Distance value.
GetErrorCode | Syntax: GetErrorCode(Structure) GetErrorCode is a Vision Data Access function that returns a diagnostic code from most structures and functions. Note: If no error code is available for the #ERR, GetErrorCode returns -1.
GetErrorString | Syntax: GetErrorString(Structure) GetErrorString is a Vision Data Access function that returns diagnostic information from most structures and functions.
GetNFound | Syntax: GetNFound(Structure) Returns the number of patterns found.
GetValue | Syntax: GetValue(Structure,[Index],[Color]) Where Structure is a reference to a cell containing a ColorHist, Delay, or Hist data structure. Index optionally specifies the bin from which to count histrogram values (ColorHist and Hist only) Color optionally determines which color component is used to pull Histogram data (ColorHist only) GetValue is a Vision Data Access function that returns information from the following structures: ColorHist. Delay. Hist
Inspect Edge | GetWidth | Syntax: GetWidth(InspectEdgeWidth, Caliper Index) Returns the width value of the edge within the indexed Caliper. Returns 0 if no edges are found within the indexed Caliper.
Linefit | GetChi2 | Syntax: GetChi2(LineFit) Returns the sum of the squares of the distances from the points to the line.
GetDistance | Syntax: GetDistance(LineFit, Index) Returns the distance between the indexed point and the line.
GetMaxDist | Syntax: GetMaxDist(LineFit) Returns the point that is farthest from the line.
GetMaxDistIndex | Syntax: GetMaxDistIndex(LineFit) Returns the index of the point that is farthest from the line.
GetX | Syntax: GetX(Structure, [Index1], [Index2]) Returns an X coordinate.
GetY | Syntax: GetY(Structure, [Index1], [Index2]) Returns a Y coordinate.
Stats | GetLatest | Syntax: GetLatest(Stats) Returns the most recent value used to compute the statistics.
GetMax | Syntax: GetMax(Stats) Returns the largest value used to compute the statistics.
GetMean | Syntax: GetMean(Stats) Returns the mean (average) of the values.
GetMin | Syntax: GetMin(Stats) Returns the smallest value used to compute the statistics.
GetErrorCount | Syntax: GetErrorCount(Stats) Returns the total number of errors from the referenced value.
GetNumSamples | Syntax: GetNumSamples(Stats) Returns the total number of samples used for calculations.
GetRange | Syntax: GetRange(Stats) Returns the range between the minimum and maximum values.
GetSDev | Syntax: GetSDev(Stats) Returns the standard deviation of the values.
GetSum | Syntax: GetSum(Stats) Returns the sum of the values.
GetVariance | Syntax: GetVariance(Stats) Returns the variance in the values.
Structures Note: The Structure argument of the following functions must be a reference to the data structure returned by an Annulus, Circle, Cross, Fixture, Line, Mask, Point or Region function. The valid structures for each function are indicated in the description. | GetCurve | Syntax: GetCurve(Structure) Returns the Curve value from the indexed Region structure
GetNPoints | Syntax: GetNPoints(Structure) GetNPoints works with polygons and returns the number of points.
Timer | GetAllTime | Syntax: GetAllTime(Image) Returns the time, in milliseconds, for the image to be acquired and the job to execute, or #ERR if the input value is invalid. Note: This argument must use the Acquired keyword, which represents the most recently acquired image. The returned GetAllTime value does not include the sensor filmstrip execution time. The GetAllTime function and the status bar calculate time differently than the Profile Job dialog. The Profile Job dialog also accounts for the construction of result graphics. If this function is used in a formula, different values are returned depending on the cell location. For example, when GetAllTime(A0) is 80, 1*GetAllTime(A0) should also be 80. However, if the cell containing 1*GetAllTime(A0) is at the beginning of the job, it returns almost the same value as GetTime(A0), which does not include other tool's execution time. If 1*GetAllTime(A0) is at the end of the job, it includes all job execution time. To return the correct value, create a separate cell just for GetAllTime(A0), and use a cell reference for it in the formula. For example, if you create a GetAllTime(A0) in cell B2, 1*B2 returns the correct value regardless of the cell location. When the HMI Settings dialog's Maximum View Connections setting is set to 2 or more, the GetAllTime value returned by vision systems using In-Sight firmware 5.x.x is longer than vision systems using In-Sight firmware 4.x.x. In addition to image acquisition and job execution time, the GetAllTime value returned by vision systems running In-Sight firmware 5.x.x adds multiple view update time to the final value, while on vision systems running In-Sight firmware 4.x.x this value is not included.
GetTime | Syntax: GetTime(Cell1, [Cell2, ...]) Returns the time, in milliseconds, for a variable-length list of cells to execute or #ERR if the input value is invalid. If multiple cells are selected, the sum of all execution times is returned.