# Script

Executes user-defined JavaScript source code, which is created and edited using the Edit Script Dialog dialog. The Script function contains JavaScript source code (which can be saved and stored as a .js file) that defines its behavior. 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:

- 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. 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.

## Script Inputs

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 image
- An event
- A shape object
- A Binary data structure
- A data structure such as Blob, Edge, Histogram, or Patterns Vision Data Access Functions
- 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 Blob, Edges, Histogram, or Patterns data structure, the object that is passed into the Script function is only usable until the Run Method returns. 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.

- 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;
      }

Note: To access a Region object's width or height parameters within a script use .w and .h.

>     Script.prototype.run = function (image, myRegion) {

> >     return {
> >         x: myRegion.x,
> >         y: myRegion.y,
> >         //width: myRegion.width,
> >         //height: myRegion.height,
> >         width: myRegion.w,
> >         height: myRegion.h,
> >         angle: myRegion.angle,
> >         curve: myRegion.curve
> >     };

>     }

## 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 Blob, Edge, Histogram, or Patterns data structure A shape object An object An Image 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.