Script 関数の JavaScript ソースコードと API リファレンス:

Script 関数用に JavaScript ソースコードを作成する場合、次のガイドラインに従う必要があります。In-Sight Explorer 内へ JavaScript を実装するには、欧州電子計算機工業会によって承認されているオープンスタンダードのバージョン 5 (ECMAScript 5 (ECMA5) としても知られています) に従います。

コンストラクタ

JavaScript ソースコードで、ツールのコンストラクタを表す関数に相当する「module.exports」を設定する必要があります。この関数は引数なしで呼び出され、スクリプトのコンパイル後に、Tool オブジェクトのインスタンスを初期化します。

次に例を示します。

            function Tool() {
  // ツールの状態を初期化
  this._partTotal = 0;
}
module.exports = Tool;

Run メソッド

Tool オブジェクトで「Run」メソッドを定義する必要があります。これは Script 関数が実行されると必ず呼び出され、呼び出されない場合、Script 関数は #ERR を返します。Script 関数の引数は、指定された順にスクリプトの Run メソッドに渡されます。

次の例は、Run メソッドの定義で推奨されるシンタックスを示しています。

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

Run メソッドの戻り値

Run メソッドは、次の型の値のいずれかを返すことができます。

• 数値
• true (1) または false (0)
• 文字列
• バイナリデータ構造体
• ブロブ、エッジ、ヒスト、IDMax、またはパターンデータ構造体
• オブジェクト
• 配列
• null、undefined、または no return ステートメント (空のオブジェクトと同じです)

Draw メソッド

Script 関数は「Draw」メソッドをサポートしており、Image 関数に似たグラフィックスをこの関数に生成させることができます。Draw メソッドには、グラフィックスコンテキストオブジェクトである引数が 1 つ指定されます。

次のメソッドを使用してグラフィックスを生成します。

• plotArc(中心行, 中心列, 開始行, 開始列, 終了行, 終了列, 名前, 色 [,表示])
• plotCircle(行, 列, 半径, 名前, 色 [,表示)
• plotCross(行, 列, 角度, 高さ, 幅, 名前, 色 [,表示])
• plotLine(行 0, 列 0, 行 1, 列 1, 名前, 色 [,表示] [,修飾開始] [,修飾終了])
• plotPoint(行, 列, 名前, 色 [,表示])
• plotRegion(行, 列, 高さ, 幅, 角度, カーブ, 名前, 色 [,表示])

形状の描画

上記のグラフィックスに加えて、「形状」を作成する Draw メソッドがあります。これは PlotPolygon および PlotCompositeRegion 関数に相当し、ここで「形状」はサポート対象の 形状オブジェクトのいずれかとすることができます。

• plotShape(形状, 名前, 色 [,表示])

次の例は、Draw メソッドを定義する場合の正しいシンタックスを示しています。

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

Save および Loadメソッド

Script 関数は「Save」および「Load」メソッドをサポートしており、この関数によってジョブの保存時にその内部状態をアーカイブして、ジョブのロード時にこの関数の状態を復元することができます。Save メソッドには引数は必要なく、保存する状態を含んでいるオブジェクトを返します。このオブジェクトはジョブファイルに格納され、ジョブのロード時に、関数の Load メソッド用の 1 つの引数としてこのオブジェクトが提供されます。

次の例は、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 秒を超える時間がかかった場合、そのメソッドは中断され、例外がスローされたかのような結果を示して、タイムアウトが発生したことを示すメッセージが表示されます。

ファイルパス

このトピックで説明している、ファイル名またはディレクトリパスを必要とする JavaScript 関数では、簡易名 (ローカルファイルシステム上のファイルを参照する場合) または URL (FTP サーバ上のファイルおよびディレクトリを参照する場合に FTP スキームを使用) を使用することができます。

URL を使用する場合、FTP URL 形式に従う必要があり、RFC 1738 で指定されています (ftp://<ユーザ>:<パスワード>@<ホスト>:<ポート>/<URL パス>)。

Script モジュール

すべての In-Sight JavaScript コードは、トップスコープのプライバシーが提供されるモジュールとしてロードされ、名前のないオブジェクトをその他のモジュールからインポートし、独自の API をエクスポートする機能を備えています。この形式は Script 関数に含まれている JavaScript コードのロードに使用し、外部スクリプトモジュールをファイルからロードする場合にも使用します。

次の例は、ソースコードのインポート方法を示しています。

            /*
このスクリプトは、標準形式の式の係数 a、b、c で指定された二次方程式のルートを返します。
*/
function Script() {

}
/*
これは必須ステートメントであり、スプレッドシートで Script 関数を呼び出せるようにして、このセルを初期化します。
*/
module.exports = Script;
  var quad = require('quadratic'); 	// モジュールをインポート
/*
これは二次式モジュールを使用可能にする場所です。
*/  
Script.prototype.run = function() { 
    var a = 1, b = 4, c = 2;
    return quad.roots(a,b,c); //モジュールを使用可能に		
} 

グローバルスコープ

グローバルスコープモジュールはそのモジュールで一意です。つまり、モジュールで定義されている自由変数は、そのモジュールでのみ可視です。

「require」関数

モジュール内で、「require」は関数として動作する自由変数です。「require」関数はモジュール識別子を受け入れ、インポートされたモジュールでエクスポートされた API を返します。要求したモジュールが返されなかった場合は、「require」関数が「undefined」の値を返します。

「module」変数

モジュール内には自由変数があり、これはオブジェクトです。「module」オブジェクトは、モジュールのエクスポートされた API を表す「exports」プロパティを含んでおり、最初は空のオブジェクトとして設定されています。

モジュールでは、その API をエクスポートするため、デフォルトで作成されている「module.exports」オブジェクトにプロパティを単純に追加することができます。または、別のオブジェクトを API としてエクスポートするために、デフォルトで作成されている空のエクスポートオブジェクトを使用するのではなく、「module.exports」プロパティに新しいオブジェクトを割り当てることもできます。

「exports」変数

モジュールには「exports」と呼ばれる自由変数があり、「module.exports」の値を初期化します。

モジュール識別子

モジュール識別子は In-Sight ビジョンシステムのローカルファイルシステム上のファイルの名前、または FTP サーバ上のファイルの名前のいずれかであり、[ファイルパス] セクションで指定します。

データ構造体の入力/出力

ブロブ、エッジ、ヒスト、IDMax、またはパターンデータ構造体は、Script からの入力および出力の両方としてサポートされています。これらのデータ構造体は読み取り専用であり、JavaScript ソースコードで作成または変更することはできません。データ構造体のそれぞれは、特定のデータ構造体によってサポートされる対応するデータアクセス関数に対応するメソッドを表示しています。

例えば、ブロブデータ構造体は次のメソッドをサポートしています。

• blobs.getNFound() - 検出されたブロブの数を返します。
• blobs.getAngle(index) - インデックス付きブロブの重心の角度を返します。
• blobs.getArea(index) - インデックス付きブロブの面積 (ピクセル単位) を返します。

バイナリ構造体の入力/出力

BStringf または ReadDevice 関数によって返されたバイナリデータ構造体、および GetBufferData 関数によって返された データ構造体は、Script 関数への入力としてサポートされています。これらの構造体が JavaScript に渡されると、バイナリデータが JavaScript DataView オブジェクトにコピーされ、これを使用して個別のバイトの読み取り/書き込みを行ったり、Int32Array または Uint8Array などのさまざまな型の配列ビューを作成したりすることができます。Script 関数にはデータのコピーが与えられるので、この関数は DataView オブジェクトの内容を、元のソースデータに反映させずに保存または変更することができます。

JavaScript DataView、ArrayBuffer、またはその他の型の配列オブジェクトが JavaScript 関数によって返されると、そのデータはバイナリデータ構造体にコピーされます。これは、バイナリデータ構造体を入力引数として受け入れるその他の In-Sight 関数 (WriteDevice 関数など) によって使用することができます。

次の例ではバイナリデータ構造体を入力引数数として取得し、そのデータ構造体を 32 ビット浮動小数点の配列として表示して、新しいバイナリデータ構造体を返します。これには 64 ビット浮動小数点の値が逆の順序で含まれています。

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

次の例は、PLC に送信される仮想的な 14 バイトのバイナリメッセージを、フォーマットして返す関数を示しています。この関数は自動的にゼロに初期化されるので、パディングフィールドに書き込む必要はありません。返された値は、スプレッドシートで 14 バイトのバイナリデータ構造体となります。

            // メッセージ形式: 
// Byte padding[2]; /* ゼロで埋める。*/
// uint32 count; 	/* 32 ビット符号なし整数、ビッグエンディアンオーダー。*/
// double delay;	/* 64 バイトダブル、リトルエンディアンオーダー。*/
//
Tool.exports.run = function(count, delay) {
  var data = new DataView(new ArrayBuffer(14));
  data.setUint32(2, count);			 // デフォルトではビッグエンディアン
  data.setFloat64(6, delay, true);		// リトルエンディアン 
  return data;
}

FormatOutputBuffer 関数

FormatOutputBuffer 関数は、「String」データ型を使用して データ構造体の入力を受け入れます。これによって、Script 関数から返されるバイナリデータ構造体をバッファデータ構造体にコピーすることができます。バイナリバイトは直接コピーされ、Null 終了文字列として解釈されることはありません。

形状オブジェクト

形状オブジェクトは、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 コンストラクタ関数は次の引数を必要とし、オブジェクトは読み取り/書き込みプロパティを同じ名前で提供します。

• row または x:  X オフセット。
• col または y:  Y オフセット。
• innerRadius: 内側の半径を定義します。
• outerRadius: 外側の半径を定義します。

Circle 関数

Circle コンストラクタ関数は次の引数を必要とし、オブジェクトは読み取り/書き込みプロパティを同じ名前で提供します。

• row または x: X オフセット。
• col または y: Y オフセット。
• radius: 半径を定義します。

Fixture 関数

Fixture コンストラクタ関数は次の引数を必要とし、オブジェクトは読み取り/書き込みプロパティを同じ名前で提供します。

• row: 行オフセット
• column: 列オフセット
• theta: 角度

Line 関数

Line コンストラクタ関数は次の引数を必要とし、オブジェクトは読み取り/書き込みプロパティを同じ名前で提供します。

• row0 または x0: 始点の X オフセット
• col0 または y0:  始点の Y オフセット
• row1 または x1: 終点の X オフセット
• col1 または y1: 終点の Y オフセット

Point 関数

Point コンストラクタ関数は次の引数を必要とし、オブジェクトは読み取り/書き込みプロパティを同じ名前で提供します。

• row または x: X オフセット。
• col または y: Y オフセット。

Polygon 関数

Polygon コンストラクタ関数は引数を必要とせず、空のポリゴンを返します。ポリゴンオブジェクトは次のプロパティとメソッドを提供します。インデックス (n) が指定されている場合は、最初の点にゼロのインデックスがあります。

• length: ポリゴン内の点の数を返します。
• add(x,y): ポリゴンに新しい点を追加します。
• clear(): ポリゴンからすべての点を削除します。
• remove(n): ポリゴンから指定した点 (n) を削除します。
• set(n,x,y): ポリゴンの点 (n) の座標を設定します。
• row(n) or x(n):  ポリゴンの点 (n) の行/X 座標を返します。
• col(n) or y(n): ポリゴンの点 (n) の列/Y 座標を返します。

Region 関数

Region コンストラクタ関数は次の引数を必要とし、オブジェクトは読み取り/書き込みプロパティを同じ名前で提供します。

• row または x: 原点の X オフセット。
• col または y: 原点の Y オフセット。
• high: 領域の X 軸寸法。
• wide: 領域の Y 軸寸法。
• angle: 角度 (度単位)。
• curve:  領域の X 軸と反対側の境界線との間の角度変位。

Process オブジェクト

モジュール内で、自由変数「process」は次のメソッドでオブジェクトを返します。

uptime()

このメソッドは、システムの起動に続いて、秒数を浮動小数点値としてサブマイクロ秒の精度で返します。

メソッドの使用方法を次に示します。

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

hrtime([時間])

このメソッドは、現在の時間を高分解能のタプル配列で返します (秒、ナノ秒)。ここで、最初の要素は現在の秒の開始以来の秒を表す整数値、2 番目の要素はナノ秒を表す整数値です。このメソッドの主な用途は、間隔の合間の時間を計測することです。

このメソッドが引数なしで呼び出された場合、返される時間は In-Sight ビジョンシステムの起動時間に相対します。このメソッドが前回の hrtime() への呼び出しの結果によって呼び出された場合は、返される時間は前回の時間に対する時間差です。

メソッドの使用方法を次に示します。

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

sleep(ms)

このメソッドで、Script 関数が指定されたミリ秒数の間スリープ状態になるように指定します。

memoryUsage()

このメソッドは次の 2 つのプロパティを含むオブジェクトを返します。

• heapTotal: ヒープメモリの合計サイズを示します。
• heapUsed: 現在使用されているヒープメモリの量を示します。

Console オブジェクト

モジュール内で、自由変数「console」は次のメソッドでオブジェクトを提供します。[コンソール出力] ペインは、[スクリプトの編集] ダイアログのドッキング可能なコンポーネントであり、スプレッドシートビュー内のドッキング可能なウィンドウとしても使用できます ([表示] メニューから [スクリプトコンソール出力] オプションを選択します)。

console.log(メッセージ)

このメソッドは、メッセージを標準の文字で、[スクリプトの編集] ダイアログの [コンソール出力] ペインに出力します。

console.warn(メッセージ)

このメソッドは、メッセージを黄色背景に黒文字で、[スクリプトの編集] ダイアログの [コンソール出力] ペインに出力します。

console.error(メッセージ)

このメソッドは、メッセージを赤背景に黒文字で、[スクリプトの編集] ダイアログの [コンソール出力] ペインに出力します。

ファイルシステムモジュール

「fs」モジュールによって、Sight ビジョンシステムまたはエミュレータのローカルファイルシステム上のファイル、およびリモート FTP サーバ上のファイルにアクセスすることができます。

このモジュールは次の必須関数を使用して取得されます。

 var fs = require("fs");

ファイルシステムオブジェクトは、次のメソッドを提供します。

appendFileSync(ファイル名, データ)

このメソッドでは、指定されたデータがある場合はファイルに付加し、ファイルがすでに存在しない場合は新しいファイルにデータを書き込みます。データパラメータが Uint8Array または DataView などの JavaScript 型の配列の場合は、バイナリデータとしてファイルに書き込まれ、それ以外の場合は、文字列に変換されて UTF-8 文字列としてファイルに書き込まれます。

existsSync(ファイル名)

指定したファイルが存在する場合、このメソッドは true を返します。

readFileSync(ファイル名 [,"binary"])

このメソッドは、ファイル全体の内容を読み取って返します。ファイルの内容は UTF-8 テキストとして読み取られ、文字列として返されます。オプションの「binary」引数を使用する場合は、ファイルの内容が DataView のバイナリデータとして返されます。次に例を示します。 

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

readdirSync(パス)

このメソッドはディレクトリの内容を読み取り、ファイル名の配列を返します。In-Sight ビジョンシステムまたはエミュレータのディレクトリの内容のみを読み取るには、空の文字列または「.」を指定し、FTP サーバのディレクトリの内容を読み取って、FTP URL のみを指定します。

statSync(パス)

このメソッドはファイルまたはディレクトリのステータスを受け取り、次のプロパティを含むオブジェクトを返します。

• size:  バイト単位でのファイルのサイズ。

unlinkSync(ファイル名)

このメソッドを使用してファイルを削除します。ただし、ファイルが存在しない場合は何も返しません。

writeFileSync(ファイル名, データ)

このメソッドはファイルの内容全体を書き込み、既存のファイルを上書きします (ファイルが存在しない場合は、ファイルが作成されます)。データパラメータが Uint8Array または DataView などの JavaScript 型の配列の場合は、バイナリデータとしてファイルに書き込まれ、それ以外の場合は、(文字列に変換されていない場合は) 文字列に変換されて UTF-8 文字列としてファイルに書き込まれます。