# 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 is only 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 needs to 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, consumes 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 retains the last value recorded after the function executed. Any functions that reference the disabled function returns 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 displays a Script data structure, but any Get function that references it returns #ERR because the Get function is expecting a specific returned value, which is not being returned since the Script function did not execute.

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 is expanded to the individual cell references contained in the range, and thus consumes 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 is 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 is unusable, and attempting to call any of its methods results 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 are 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 can 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
> >     };

>     }

Outputs

Returns | The function can 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 returns #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 can be used to retrieve the exception message, if one was written into the source code. All exceptions return the same error code (20000005).

Vision Data Access functions

The Get function is used to access properties of objects returned by a Script function.