Script Function JavaScript Source Code and API Reference

The following guidelines must be observed when creating JavaScript source code for the Script function. The implementation of JavaScript within In-Sight Explorer follows version 5 of the open standard approved by the European Computer Manufacturer’s Association, also known as ECMAScript 5 (ECMA5). For more information, see Script.

• Constructor
• Run Method
• Draw Method
• Save and Load Methods
• Timeout
• File Paths
• Script Modules
• Data Structure Inputs/Outputs
• Binary Structures Inputs/Outputs
• Shape Objects
• Process Object
• Console Object
• File System Module

Constructor

The JavaScript source code must set a "module.exports" equal to a function that represents the constructor of the tool. This function will be invoked, with no arguments, after the script is compiled, which initializes an instance of the Tool object.

For example:

function Tool() {
  // Initialize the tool statethis._partTotal = 0;
}
module.exports = Tool;

Run Method

The Tool object must define a "run" method, which is called whenever the Script function is executed. Otherwise, the Script function will return #ERR. The Script function's arguments will be passed to the script's run method in the order they are specified.

The following example shows the recommended syntax for defining the run method:

Tool.prototype.run = function(a, b) {
  return "The average is" + (a+b)/2;
}; 

Run Method Return Values

The run method may return any of the following types of values:

• A number
• true (1) or false (0)
• A string
• A Binary data structure
• A Blobs, Edges, Hist, IDMax, or Patterns data structure
• An Object
• An Array
• null, undefined, or no return statement (which is the same as an empty Object)

Draw Method

The Script function supports a "draw" method, which allows the function to generate graphics similar to the Image functions. The draw method is given a single argument, which is a graphics context object.

Use the following methods to generate graphics:

• plotArc(centerRow, centerColumn, startRow, startColumn, endRow, endColumn, name, color [,show])
• plotCircle(row, column, radius, name, color [,show])
• plotCross(row, column, angle, high, wide, name, color [,show])
• plotLine(row0, column0, row1, column1, name, color [,show] [,startAdornment] [,endAdornment])
• plotPoint(row, column, name, color [,show])
• plotRegion(row, column, high, wide, angle, curve, name, color [,show])

Drawing Shapes

In addition to the above graphics, there is a draw method for creating "shapes," which is the equivalent of the PlotPolygon and PlotCompositeRegion functions, where the "shape" can be any of the supported Shape Objects. For more information, see Shape Objects.

• plotShape(shape, name, color [,show])

The following example illustrates the correct syntax for defining the draw method:

Tool.prototype.draw = function(gr) {
  gr.plotPoint(this._foundRow, this._foundCol, "Found Feature", 0xFF00FF);
}; 

Save and Load Methods

The Script function supports "save" and "load" methods, which allow the function to archive its internal state when the job is saved, and to restore the state of the function when the job is loaded. The save method requires no arguments, and returns an Object that contains the state to be saved. The object will be stored in the job file, and when the job is loaded, the object will be provided as the lone argument for the function's load method.

The following example illustrates the recommended syntax for defining the save and load methods:

Tool.prototype.save = function() {
  return {total: this._total, avg: this._average};
};
Tool.prototype.load = function(saved) {
  this._total = saved.total;
  this._average = saved.avg;
}; 

Timeout

Each of the JavaScript methods that is called by the Script function (i.e. the constructor, run, draw, save and load methods) is subject to a timeout. By default, the default timeout is 10 seconds, with a 1 second default granularity (the timeout is specified in milliseconds, with a minimum value of 1 and a maximum of 60000; the granularity is also specified in milliseconds, with a minimum of 1 and a maximum of 10000). If any of the methods take longer than 10 seconds, the method will be aborted, exhibiting the same effect as though an exception had been thrown, with a message indicating that a timeout has occurred.

File Paths

For the JavaScript functions described in this topic that require a file name or directory path, they can either be a simple name (when referencing files on the local file system) or a URL (using the FTP scheme when referring to files and directories on an FTP server).

When a URL is used, it must follow the FTP URL format, as specified in RFC 1738: ftp://<user>:<password>@<host>:<port>/<url-path>

Script Modules

All In-Sight JavaScript code is loaded as modules that are offered privacy of their top scope; facility for importing singleton objects from other modules; and exporting their own API. This format is used for loading the JavaScript code contained within a Script function, as well as when loading external script modules from files.

The following example illustrates how to import source code:

/*
This script returns the roots of a quadratic equation, given the coefficients a,b,c from a standard form equation.
*/function Script() {

}
/*
This is a required statement, and enables the Spreadsheet to call the Script function, which initializes this cell.
*/
module.exports = Script;
  var quad = require('quadratic'); 	// Imports the module
/*
This is where the quadratic module can be put to use.
*/  
Script.prototype.run = function() { 
    var a = 1, b = 4, c = 2;
    return quad.roots(a,b,c); //Put the module to use		
} 

Global Scope

The global scope module is unique to that module, meaning that any free variables defined by the module are only visible to that module.

"require" Function

In a module, "require" is a free variable that acts as a function. The "require" function accepts a Module Identifier, and returns the exported API of the imported module. If the requested module cannot be returned, the "require" function will return the value "undefined."

"module" Variable

In a module, there is a free variable, "module," which is an Object. The "module" object has an "exports" property that represents the exported API of the module, and it is initially set as an empty object.

A module may simply add properties to the default-created "module.exports" object in order to export its API. Alternatively, a module may assign a new object to the "module.exports" property in order to export a different object as its API, rather than using the default-created empty exports object.

"exports" Variable

In a module, there is a free variable called "exports," which initializes the value of "module.exports."

Module Identifier

A module identifier is either the name of file on the local file system of an In-Sight vision system, or the name of a file on an FTP server, as specified under the File Paths section.

Data Structure Inputs/Outputs

The Blobs, Edges, Hist, IDMax, or Patterns data structures are supported both as inputs and outputs from a Script function. These data structures are read-only, and cannot be created or modified by JavaScript source code. Each of the data structures exposes methods that correspond to the corresponding Vision Data Access functions supported by the particular data structure. For more information, see Vision Data Access Functions.

For example, a Blobs data structure supports the following methods:

• blobs.getNFound() – Returns the number of blobs found.
• blobs.getAngle(index) – Returns the angle of an indexed blob's center of mass.
• blobs.getArea(index) – Returns the area (in pixels) of an indexed blob.

Binary Structures Inputs/Outputs

The Binary data structure returned by a BStringf or ReadDevice function, and the UserData data structure returned by the GetBufferData function are supported as inputs to a Script function. When these structures are passed into JavaScript, the binary data is copied into a JavaScript DataView object, which can be used to read/write individual bytes, or to create a different typed array view, such as an Int32Array or a Uint8Array. Because the Script function is given a copy of the data, the function can save or modify the contents of the DataView object without affecting the original source data.

When a JavaScript DataView, ArrayBuffer or other typed array object is returned by a JavaScript function, the data will be copied into a Binary data structure, which can be used by other In-Sight functions (such as a WriteDevice function) that accept a Binary data structure as an input argument.

The following example takes a Binary data structure as an input argument, views the data structure as an array of 32-bit floating point values, and then returns a new Binary data structure, which contains 64-bit floating point values, in the opposite order.

 Tool.exports.run = function(data) {
  var input = new Float32Array(data.buffer);
  var output = new Float64Array(input.length);
  for (var i=0; i<output.length; ++i)
    output[output.length - i] = input[i];
  return output;
}

The next example illustrates a function that formats and returns a hypothetical 14-byte binary message to be sent to a PLC. The function does not need to write padding fields because they are automatically initialized to zero. The returned value will be a 14-byte Binary data structure in the spreadsheet.

// Message Format:
// Byte padding[2]; /* Fill with zeroes */
// uint32 count; 	/* 32-bit unsigned integer, big-endian order */
// double delay;	/* 64-byte double, little-endian order */
//
Tool.exports.run = function(count, delay) {
  var data = new DataView(new ArrayBuffer(14));
  data.setUint32(2, count);			 // big-endian by default
  data.setFloat64(6, delay, true);		// little-endianreturn data;
}

FormatOutputBuffer Function

The FormatOutputBuffer function will accept a Binary data structure input, using the "String" data type. This allows a copy of the Binary data structure to be returned from a Script function into a Buffer data structure. The binary bytes are copied directly, and are not interpreted as a null-terminated character string. For more information, see FormatOutputBuffer.

Shape Objects

A shape object can be input to a Script function as an argument (for example, using a reference to an EditRegion function), and can be output as a return value. Shape objects are created by using constructor functions that are provided as members of the 'cognex' module.

The following illustrates how shape objects can be created:

function Example()
{
}			
var cognex = require('cognex');
module.exports = Example;

Example.prototype.run = function(x, y)
{
  var annulus = new cognex.Annulus(150, 250, 25, 45);
  var circle = new cognex.Circle(50, 250, 30);
  var fixture = new cognex.Fixture(230, 300, 45);
  var line = new cognex.Line(270, 530, 290, 50);
  var point = new cognex.Point(330, 500);
  var polygon = new cognex.Polygon();
  polygon.add(340,230);
  polygon.add(390,210);
  polygon.add(370,230);
  polygon.add(390,250);
  var region = new cognex.Region(440, 300, 40, 50, 30, 45);
  this.shapes = [annulus,circle,fixture,line,point,polygon,region];
  return this.shapes;
}

Example.prototype.draw = function(gr)
{
  this.shapes.forEach(function(shape) {gr.plotShape(shape, JSON.stringify(shape), 0xc0ffee*Math.random());});
}
 

Annulus

The Annulus constructor function requires the following arguments, and the object provides read/write properties with the same names:

• row or x: The x-offset.
• col or y: The y-offset.
• innerRadius: Defines the inner radius.
• outerRadius: Defines the outer radius.

Circle

The Circle constructor function requires the following arguments, and the object provides read/write properties with the same names:

• row or x: The x-offset.
• col or y: The y-offset.
• radius: Defines the radius.

Fixture

The Fixture constructor function requires the following arguments, and the object provides read/write properties with the same names:

• row: The row offset.
• column: The column offset.
• theta: The angular orientation.

Line

The Line constructor function requires the following arguments, and the object provides read/write properties with the same names:

• row0 or x0: The x-offset of the first endpoint.
• col0 or y0: The y-offset of the first endpoint.
• row1 or x1: The x-offset of the last endpoint.
• col1 or y1: The y-offset of the last endpoint.

Point

The Point constructor function requires the following arguments, and the object provides read/write properties with the same names:

• row or x: The x-offset.
• col or y: The y-offset.

Polygon

The Polygon constructor function requires no arguments, and returns an empty polygon. The polygon object provides the following properties and methods. In cases where an index (n) is specified, the first point has an index of zero.

• length: Returns the number of points in the polygon.
• add(x,y): Appends a new point to the polygon.
• clear(): Removes all points from the polygon.
• remove(n): Removes the specified point (n) from the polygon.
• set(n,x,y): Sets the coordinates of a point (n) of the polygon.
• row(n) or x(n): Returns the row/x-coordinate of point (n) of the polygon.
• col(n) or y(n): Returns the column/y-coordinate of point (n) of the polygon.

Region

The Region constructor function requires the following arguments, and the object provides read/write properties with the same names:

• row or x: The x-offset of the origin.
• col or y: The y-offset of the origin.
• high: The x-axis dimension of the region.
• wide: The y-axis dimension of the region.
• angle: The angular orientation, in degrees.
• curve: The angular deviation between the region's x-axis and the opposing boundary line.

Process Object

Within any module, a free variable, "process," provides an object with the following methods.

uptime()

This method returns the number of seconds, as a floating-point value, with sub-microsecond precision, since the system powered up.

The following illustrates how the method may be used:

var start = process.uptime();
someTimeConsumingFunction();
var elapsedSeconds = process.uptime() - start;

hrtime([time])

This method returns the current time in a high-resolution tuple Array (seconds, nanoseconds), where the first element is an integer number representing seconds, and the second element is an integer number representing nanoseconds since the start of the current second. The primary use of this method is for measuring time between intervals.

If this method is called without an argument, the returned time is relative to when the In-Sight vision system powered up. If the method is called with the result of a previous call to hrtime(), the returned time is the time difference, relative to the previous time.

The following illustrates how the method may be used:

var start = process.hrtime();
someTimeConsumingFunction();
var diff = process.hrtime(start);
var elapsedSeconds = diff[0] + diff[1] / 1e+9 

sleep(ms)

This method specifies that the Script function should sleep for the specified number of milliseconds.

memoryUsage()

This method returns an object with two properties:

• heapTotal: Indicates the total size of heap memory.
• heapUsed: Indicates the amount of heap memory currently in use.

Console Object

Within any module, a free variable, "console," provides an object with the following methods. The Console Output pane is a dockable component of the Edit Script dialog, and is also available as a dockable window in the Spreadsheet View (select the Script Console Output option from the View menu). For more information, see Edit Script Dialog.

console.log(message)

This method prints a message, as normal text, to the Console Output pane of the Edit Script dialog.

console.warn(message)

This method prints a message, with black text on a yellow background, to the Console Output pane of the Edit Script dialog.

console.error(message)

This method prints a message, with black text on a red background, to the Console Output pane of the Edit Script dialog.

File System Module

The "fs" module provides access to files on the local file system of an In-Sight vision system or Emulator, as well as those on remote FTP servers.

This module is obtained using the require function:

 var fs = require("fs");

The file system object provides the following methods.

appendFileSync(file name, data)

This method appends the given data to a file, if it exists, or writes the data to a new file if the file does not already exist. If the data parameter is a JavaScript typed array, such as a Uint8Array or a DataView, it will be written to the file as binary data, otherwise, it will be converted to a string, and written to the file as a UTF-8 string.

existsSync(file name)

This method returns true if the specified file exists.

readFileSync(file name [,"binary"])

This method reads and returns the entire contents of the file. The contents of the file are read as UTF-8 text, and returned as a string. If the optional "binary" argument is used, the contents of the file will be returned as binary data in a DataView. For example: 

var binaryData = fs.readFileSync('ftp://server/xyz.dat', "binary");

readdirSync(path)

This method reads the contents of a directory, and returns an array of file names. To read only the contents of an In-Sight vision system or Emulator's directory, specify an empty string or "."; to read the contents of a directory of an FTP server, specify the FTP URL, only.

statSync(path)

This method receives the status of a file or directory, and returns an object with the following property:

• size: The size, in bytes, of the file.

unlinkSync(file name)

This method is used to delete the file. However, if the file does not exist, the method will do nothing.

writeFileSync(file name, data)

This method writes the entire contents of the file, and will overwrite an existing file (if the file does not exist, the file will be created). If the data parameter is a JavaScript typed array, such as a Uint8Array or a DataView, it will be written to the file as binary data; otherwise it will be converted to a string (if it is not already a string), and written to the file as a UTF-8 string.

---

Copyright © 1999 - 2019  |  Cognex Corporation  |  All Rights Reserved.

In-Sight® Explorer Help  |  2019 October 02  |  Revision: 5.8.0.1