Script

Executes user-defined JavaScript source code, which is created and edited using the Edit Script dialog. For more information, see Edit Script Dialog.

The Script function contains JavaScript source code (which can be saved and stored as a .js file) that defines its behavior, and the source code only defines the behavior for the individual Script function. For example, if there are several Script functions in a job, a variable defined in one Script function will only be defined for that particular Script function, and not for all of the Script functions in the job.

Note:

This function is only available on In-Sight vision systems running In-Sight firmware 5.1.0 and later. For a complete list of models and supported firmware versions, see Firmware Versions.
The following limits apply to the memory allocated by all Script functions and external script modules used in any given job:
- The limit for the maximum number of bytes allocated for script memory is 4MB.
- The limit for the maximum number of bytes allocated for the stack is 64kB.
To avoid unnecessary memory allocation, all unused functions should be deleted from the script (such as those in the default example script, if they are not used). For example, a script with an unused sample draw function that generates a string object and plots it, will consume memory and CPU cycles.
The functionality of a Script function that has been cell stated to disable its execution differs from other Spreadsheet functions, explicitly upon a job load. For more information, see Cell State Dialog.

Generally, other Spreadsheet functions will retain the last value recorded after the function executed. Any functions that reference the disabled function will return the last value that was recorded. However, due to the Script function requiring the execution of its internal run method, upon loading a disabled Script function, it will display a Script data structure, but any Get function that references it will return #ERR because the Get function is expecting a specific returned value, which is not being returned since the Script function did not execute. For more information, see Get.
The Script function is not supported inside a Dialog function.

Script Inputs

Syntax: Script(Argument 1,...,Argument 100)

Unlike traditional In-Sight spreadsheet functions, the Script function is able to take a variety of different input arguments (from 1 to 100). Each argument must be a cell reference, a literal value, or an expression that yields one of the following value types:

A number
A string
An event
A shape object. For more information, see Script Function JavaScript Source Code and API Reference.
A Binary data structure
A Blobs, Edges, Hist, IDMax, or Patterns data structure
An Object or Array data structure (returned from another Script function)

Note:

If a cell range is specified as an argument, it will be expanded to the individual cell references contained in the range, and will thus consume an equal number of arguments as contained in the cell range.
When an argument to a Script function is a reference to another cell that is returning a Blobs, Edges, Hist, IDMax, or Patterns data structure, the object that is passed into the Script function is only usable until the Run Method returns. For more information, see Run Method.

The Script function can directly return this object, and it will be usable as the result value of the cell containing the Script function. However, if the script stores this object internally (using it in its Draw Method, for example), after the run method returns, the object will be unusable, and attempting to call any of its methods will result in an error. This also applies if the script returns a result structure such as a property of a script object returned by the run method. For instance, any of these properties will not be usable by a Get function, or by other Script functions, because the underlying objects are no longer valid.
While running on an In-Sight 5705 or 5705C vision system, the Script function may return incorrect results if a math operation contains NaN or an undefined value.

When writing a script, including code that validates input arguments may help to reduce errors, as shown in the example below:

function Tool()
{
}
module.exports = Tool;
function isNumber(n) {
  if (n === undefined || n == null || isNaN(parseFloat(n)) || !isFinite(n))
    return false;
  return true;
}
Tool.prototype.run = function(x, y)
{
  if (!isNumber(x) || !isNumber(y)){
    throw new Error("Usage: Requires 2 numeric arguments");
  return +x + +y;
}

Script Outputs

Returns

The function may return a value of any of the following types:

A number
true (1) or false (0)
A string
A Binary data structure
A Blobs, Edges, Hist, IDMax, or Patterns data structure
A shape object. For more information, see Script Function JavaScript Source Code and API Reference.
An object
null, undefined or no return statement (which is treated the same as an empty object)

The function will return #ERR for any of the following conditions:

If the source code does not contain a run method.
If any of the argument values is not of a supported type.
If the constructor throws an exception.

Note: The GetErrorString function may be used to retrieve the exception message, if one was written into the source code. All exceptions return the same error code (20000005).

Script Vision Data Access Functions

The Get function is used to access properties of objects returned by a Script function. For more information, see Get.