Script 函数 JavaScript 源代码和 API 引用：

为 Script 函数创建 JavaScript 源代码时必须遵守以下准则。JavaScript 的实现遵循欧洲计算机制造商协会批准的开放标准版本 5，也称为 ECMAScript 5 (ECMA5)。

构造函数

JavaScript 源代码必须将“module.exports”设置为等于表示工具构造函数的函数。编译脚本后将调用此函数，不带参数，这会初始化 Tool 对象的实例。

例如：

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

run 方法

Tool 对象必须定义“run”方法，每当执行 Script 函数时都会调用该方法；否则，脚本函数将返回 #ERR。Script 函数的参数将按照指定的顺序传递给脚本的运行方法。

以下示例显示了用于定义 run 方法的推荐语法：

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

run 方法返回值

run 方法可能会返回以下任何类型的值：

• 数字
• true (1) 或 false (0)
• 字符串
• Binary 数据结构
• 斑点、边缘、直方图、 或 图案Vision Data Access functions 数据结构
• 形状对象
• 对象
• 图像
• null、undefined（未定义）或无返回语句（被视为与空对象相同）。

draw 方法

Script 函数支持“draw”方法，该方法允许函数生成类似于 图像 函数的图像。draw 方法带一个参数，为图形上下文对象。

使用以下方法生成图形：

• plotArc(centerX, centerY, startX, startY, endX, endY, 名称, 颜色 [,显示])
• plotCircle(X, Y, 半径, 名称, 颜色 [,显示])
• plotCross(X, Y, 角度, 宽度, 高度, 名称, 颜色 [,显示])
• plotLine(X0, Y0, X1, Y1, 名称, 颜色 [,显示] [,startAdornment] [,endAdornment])
• plotPoint(X, Y, 名称, 颜色 [,显示])
• plotRegion(X, Y, 宽度, 高度, 角度, 曲线, 名称, 颜色 [,显示])

绘制形状

除了上述图形之外，还有一种用于创建“形状”的绘制方法，相当于 PlotPolygon and PlotCompositeRegion 函数，其中“形状”可以是任何受支持的 Shape 对象。

• plotShape(形状, 名称, 颜色 [,显示])

以下示例说明了定义 draw 方法的正确语法：

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

save 和 load 方法

Script 函数支持“save”和“load”方法，允许函数在保存作业时存档其内部状态，并在加载作业时恢复函数的状态。save 方法不需要任何参数，并返回包含要保存的状态的 Object。该对象将存储在作业文件中，当加载作业时，该对象将作为函数 load 方法的唯一参数提供。

以下示例说明了用于定义 save 和 load 方法的推荐语法：

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

超时

Script 函数调用的每个 JavaScript 方法（即构造函数、run、draw、save 和 load 方法）都会超时。默认情况下，默认超时时间为 10 秒，默认粒度为 1 秒（超时时间以毫秒为单位指定，最小值为 1，最大值为 60000；粒度也以毫秒为单位指定，最小值为 1，最大值为 10000）。如果任何方法花费的时间超过 10 秒，该方法将被中止，表现出与抛出异常相同的效果，并显示一条消息指示已发生超时。

也可以手动更改所有脚本单元的超时持续时间，如以下脚本所示。

            function Script() {
}

module.exports = Script;
Script.prototype.run = function (arg0) {

            // Find the script configuration object.
var scriptConfig = process.binding("InSight.Camera").config.script;

            // Change the (shared) Script timeout.
scriptConfig.toolTimeout = 3000 /*ms*/;
return true;
}

文件路径

对于本主题中描述的需要文件名或目录路径的 JavaScript 函数，它们可以是简单名称（当引用本地文件系统上的文件时）或 URL（当引用 FTP 服务器上的本地文件和目录时使用 FTP 方案）。

使用 URL 时，它必须遵循 FTP URL 格式，如在 RFC 1738: ftp://<用户>:<密码>@<主机>:<端口>/<url 路径> 中指定

脚本模块

所有 In-Sight JavaScript 代码都作为模块加载，这些模块提供其顶级范围的隐私；从其他模块导入单例对象的工具；并导出其自己的 API。此格式用于加载 Script 函数中包含的 JavaScript 代码，以及从文件加载外部脚本模块。

以下示例说明了如何导入源代码：

            /*
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		
} 

全局范围

全局范围模块对于该模块是唯一的，这意味着该模块定义的任何自由变量仅对该模块可见。

“require”函数

在模块中，“require”是一个充当函数的自由变量。“require”函数接受模块标识符，并返回导入模块的导出 API。如果无法返回请求的模块，“require”函数将返回值“undefined”。

“模块”变量

在模块中，有一个自由变量“模块”，它是 Object。“module”对象有一个“exports”属性，表示模块的导出 API，它最初被设置为空对象。

模块可以简单地向默认创建的“module.exports”对象添加属性以导出其 API。或者，模块可以将新对象分配给“module.exports”属性，以便将不同的对象导出为其 API，而不是使用默认创建的空导出对象。

“exports”变量

在模块中，有一个名为“exports”的自由变量，它初始化“module.exports”的值。

模块标识符

模块标识符是 In-Sight 视觉系统本地文件系统上的文件名，或者是 FTP 服务器上的文件名，由文件路径部分指定。

数据结构输入/输出

支持将 斑点、边缘、直方图、或 图案Vision Data Access functions 数据结构作为脚本函数的输入和输出。这些数据结构是只读的，不能由 JavaScript 源代码创建或修改。每个数据结构都公开了对应于特定数据结构支持的相应 Vision Data Access functionsVision Data Access functions 方法。

例如，Blobs 数据结构支持以下方法：

• blobs.getNFound() – 返回找到的斑点数。
• blobs.getAngle(index) – 返回索引斑点质心的角度。
• blobs.getArea(index) – 返回索引斑点的面积（以像素为单位）。

形状对象

形状对象可以作为参数输入到 Script 函数（例如，使用对 EditRegion 函数的引用），并且可以作为返回值输出。形状对象是通过使用作为“cognex”模块成员提供的构造函数创建的。

下面说明了如何创建形状对象：

            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

Annulus 构造函数需要以下参数，并且该对象提供具有相同名称的读/写属性：

• X：x 偏移。
• Y：y 偏移。
• innerRadius：定义内半径。
• outerRadius：定义外半径。

圆

Circle 构造函数需要以下参数，并且该对象提供具有相同名称的读/写属性：

• X：x 偏移。
• Y：y 偏移。
• 半径：定义半径。

固定

Fixture 构造函数需要以下参数，并且该对象提供具有相同名称的读/写属性：

• X：x 偏移。
• Y：y 偏移。
• theta：角度方向。

Line

Line 构造函数需要以下参数，并且该对象提供具有相同名称的读/写属性：

• x0：第一个端点的 x 偏移。
• y0：第一个端点的 y 偏移。
• x1：最后一个端点的 x 偏移。
• y1：最后一个端点的 y 偏移。

点

Point 构造函数需要以下参数，对象提供具有相同名称的读/写属性：

• X：x 偏移。
• Y：y 偏移。

多边形

Polygon 构造函数不需要任何参数，并返回空多边形。多边形对象提供以下属性和方法：

• 长度：返回多边形中的点数。例如，三角形多边形具有三个点。
• add(x,y)：将新点追加到多边形。
• clear()：从多边形中删除所有点。
• remove(n)：从多边形中移除指定点 (n)。如果索引是索引有效范围之外的数字，则不执行任何操作。
• set(n,x,y)：设置多边形的点 (n) 的坐标。
• x(n)：返回多边形点 (n) 的 x 坐标。
• y(n)：返回多边形点 (n) 的 y 坐标。
• clone()：返回多边形的副本。

• points：获取或设置包含多边形点坐标的数字数组：

  [x0, y0, x1, y1, x2, y2, ...]

  读取此属性将返回一个包含多边形点副本的新数组，因此修改该数组不会有任何效果，除非它被分配回 points 属性。

  提示:在多边形点上迭代时，在循环开始时仅读取一次此属性比在每次迭代时都读取它要高效得多。

  将此属性设置为值数组时，每个元素都将转换为单精度浮点值。如果此属性设置的值不是具有偶数个元素的数组，则会抛出异常。如果数组中的任何值不能转换为单精度浮点数范围内的数字，则行为未定义。

• reserve(计数)：预留空间存储计数点，但不改变长度属性。这可能会更快地创建大型多边形。如果无法分配请求的空间，将抛出异常。

• translate(tx, ty)：将指定值添加到多边形中的每个点。每个点变换如下：

  new_x = x + tx

  new_y = y + ty

• scale(xScale, yScale)：将多边形中的每个点乘以指定值。每个点变换如下：

  new_x = x * xScale

  new_y = y * yScale

• transform(m00, m01, m10, m11, tx, ty)：将变换矩阵应用于多边形点。每个点变换如下：

  new_x = x * m00 + y * m01 + tx

  new_y = x * m10 + y * m11 + ty

如果指定了索引 (n)，则第一个点的索引为零。如果索引 (n) 不存在，则 getter 返回零，而 setter 返回索引超界错误，除非另有说明。

区域

Region 构造函数需要以下参数，并且该对象提供具有相同名称的读/写属性：

• X：原点的 x 偏移。
• Y：原点的 y 偏移。
• w：区域的 x 轴维度。
• h：区域的 y 轴维度。
• 角度：角度方向，以度为单位。
• 曲线：在区域 x 轴和相对的边缘界线之间的角度偏差。

process 对象

在任何模块中，自由变量“process”提供了具有以下方法的对象。

uptime()

此方法返回自系统启动以来的秒数作为浮点值，精度为亚微秒。

下面说明如何使用该方法：

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

hrtime([时间])

此方法以高分辨率元组 Array (秒, 纳秒) 返回当前时间，其中第一个元素是表示秒的整数，第二个元素是表示从当前秒开始的纳秒的整数。此方法的主要用途是测量间隔之间的时间。

如果在不带参数的情况下调用此方法，则返回的时间是相对于 In-Sight 视觉系统启动的时间。如果使用先前调用 hrtime() 的结果调用该方法，则返回的时间是相对于先前时间的时差。

下面说明如何使用该方法：

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

sleep(毫秒)

此方法指定 Script 函数应休眠指定的毫秒数。

memoryUsage()

此方法返回具有两个属性的对象：

• heapTotal：指示堆内存的总大小。
• heapUsed：指示当前使用的堆内存量。

console 对象

在任何模块中，自由变量“console”提供了具有以下方法的对象。

console.log(消息)

此方法将消息作为普通文本输出到“输出”窗格。

console.warn(消息)

此方法将消息（黄色背景上的黑色文本）输出到“输出”窗格。

console.error(消息)

此方法将消息（红底黑字）输出到“输出”窗格。

文件系统模块

“fs”模块提供对 In-Sight 视觉系统 的本地文件系统以及远程 FTP 服务器上文件的访问权限。

该模块是使用 require 函数获得的：

 var fs = require("fs");

文件系统对象提供以下方法。

appendFileSync(文件名, 数据)

此方法将给定数据追加到文件（如果存在），或者如果文件不存在，则将数据写入新文件。如果数据参数是 JavaScript 类型的数组，例如Uint8Array 或 DataView，则将其作为二进制数据写入文件，否则，将其转换为字符串，并作为 UTF-8 字符串写入文件。

existsSync(文件名)

如果指定的文件存在，则此方法返回 true。

readFileSync(文件名 [,"二进制"])

此方法读取并返回文件的全部内容。文件的内容作为 UTF-8 文本读取，并作为字符串返回。如果使用可选的“二进制”参数，则文件的内容将作为 DataView 中的二进制数据返回。例如：

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

readdirSync(路径)

此方法读取目录的内容，并返回一个文件名数组。要只读取 In-Sight 视觉系统目录的内容，请指定空字符串或“.”；要读取 FTP 服务器目录的内容，请仅指定 FTP URL。

statSync(路径)

此方法接收文件或目录的状态，并返回具有以下属性的对象：

• 大小：文件的大小（以字节为单位）。

unlinkSync(文件名)

该方法用于删除文件。但是，如果文件不存在，该方法将不执行任何操作。

writeFileSync(文件名, 数据)

此方法写入文件的全部内容，并将覆盖现有文件（如果文件不存在，将创建文件）。如果数据参数是 JavaScript 类型的数组，例如 Uint8Array 或 DataView，它将作为二进制数据写入文件；否则它将被转换为字符串（如果还不是字符串），并作为 UTF-8 字符串写入文件。