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 Functions are tools that are available in Spreadsheet for processing and analyzing acquisitions or other results. You can add functions to your Spreadsheet job to create tool chains and produce results for specific applications. 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 A job is a user-configured program in In-Sight EasyBuilder consisting of functions and designed for specific applications. You can create and edit jobs using the In-Sight EasyBuilder interface, and load them on a vision system for deployment in a live environment. 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 Acquisition is the process or result of the vision system acquiring a new image..
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

BitNot

Syntax: BitNot(Value)

Returns the bitwise inverse of Value.

Note: Processes only the lower 16 bits.

Examples

BitOr

Syntax: BitOr(Value1, Value2, ...)

Returns the bitwise OR of values.

Note: Processes only the lower 16 bits.

Examples

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.

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

OneShot

Syntax: OneShot(Val)

Returns true if Val is 1 on this execution and was 0 in the prior execution.

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

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.

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

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

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.

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 A fixture is a coordinate location on the image that keeps the tool in the place determined by the 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

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

Exact

Syntax: Exact(Text1, Text2)

Returns 1 if Text1 and Text2 are identical, else 0.

Note: Exact is case-sensitive.

Exact Examples

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

Left

Syntax: Left(Text, NumChars)

Returns the leftmost number of characters (NumChars) from a Text string.

Left Example

Len

Syntax: Len(Text)

Returns the number of characters (bytes) in a Text string.

Len Example

Lower

Syntax: Lower(Text)

Returns Text converted to lowercase.

Lower Example

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

Replace

Syntax: Replace(SrcText, StartChar, NumChars, NewText)

Returns SrcText, modified by NewText at the indexed position StartChar.

Replace Example

Right

Syntax: Right(Text, NumChars)

Returns the rightmost number of characters (NumChars) from a Text string.

Right Example

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 Vision Suite 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

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

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

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

Upper

Syntax: Upper(Text)

Returns Text converted to uppercase.

Upper Example

Value

Syntax: Value(NumericText)

Returns the floating point value of NumericText. Subsequent non-numeric characters are ignored.

Value Example

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 A blob is a group of pixels on the image that form a distinct pattern, typically used to represent objects, features, or areas of interest in object detection and segmentation tasks.'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 A histogram is a graphical representation of the distribution of pixel intensity values. A histogram refers to an array of pixels - how many and their individual greyscale values - within a region of interest (ROI). 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, 1GetAllTime(A0) should also be 80. However, if the cell containing 1GetAllTime(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 1GetAllTime(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, 1B2 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.
Timer	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.