これまで作成してきたスクリプトでは、ワークユニット、キューシートといった操作対象オブジェクトの名称をスクリプト内に直接記述してきました。
しかしこれでは、操作対象を変更しながら同一処理を適用させたい時に、直接コードを編集する作業が発生してしまい、手間やタイプミスの可能性が発生します。
この手間を無くすために、CRI Atom Craft ロボットにはスクリプトエディター用の拡張書式という機能が用意されています。
この機能は、スクリプト内に記述されたコメント情報をスクリプトリストやメニューに表示したり、スクリプトで定義した変数をエディター GUI 操作で簡単に更新できるようにしたりする機能です。
スクリプトエディター用の拡張書式を用いることで、スクリプト修正の手間やミスを軽減することができます。

このチュートリアルでは、スクリプトエディター用の拡張書式のユーザー変数機能を使ってキューの「ピッチ」パラメーターを GUI 操作で変更するスクリプトを作成します。

本チュートリアルは、チュートリアル「プロジェクトの作成と波形ファイルをキューに登録」で作成したプロジェクトを使用します。
プロジェクトを開いていない場合は、プロジェクトを開くか、「プロジェクトの作成と波形ファイルをキューに登録」にて作成したスクリプトを実行してから、チュートリアルを進めましょう。

スクリプトファイルの準備

スクリプトメニューで「スクリプトリスト...」を選択し、スクリプトリストウィンドウを表示します。
スクリプトリストウィンドウの新規作成ボタンを押して、以下の名前でスクリプトファイルを作成します。

スクリプトの保存先	スクリプトファイル名
tutorials [CRI]	tutorial06-1_user_variable.py

スクリプトの説明

作成したスクリプトをダブルクリックして、スクリプトエディターからのスクリプト実行で開きます。
モジュールのインポートの記述ができたら、スクリプトリストウィンドウでスクリプトの概要が確認できるように、スクリプトの説明を次のように記述しましょう。

# --Description:[チュートリアル]ユーザー変数を使ってキューの「ピッチ」パラメーターを変更

モジュールのインポート

スクリプトの説明が記述できたら、スクリプトで CRI Atom Craft を操作するため、次のモジュールをインポートします。

import cri.atomcraft.project
import cri.atomcraft.project as acproject
import cri.atomcraft.debug as acdebug

プロジェクト操作のために project モジュール、ログ出力のために debug モジュールをインポートします。
オブジェクトを扱うユーザー変数を定義する場合、インポート名を置き換えしていない cri.atomcraft.project のインポートが必要になります。

ユーザー変数として扱う変数の定義

はじめに、ユーザー変数の範囲を決めるため、スクリプトのコード内に「# –BeginUserVariable ~ # –EndUserVariable」を記述します。
「# –BeginUserVariable ~ # –EndUserVariable」の範囲内に定義した変数がスクリプトエディターからのスクリプト実行で、ユーザー変数として扱われるようになります。

キューのピッチを変更するため、「# –BeginUserVariable ~ # –EndUserVariable」内に次の変数を記述します。

パラメーターを変更するキューの変数
変更するパラメーターフィールド名を設定する変数
パラメーターの値を設定する変数

一連の内容をスクリプトで記述すると次のようになります。

# --BeginUserVariable
VARIABLE_CUE = None
VARIABLE_PARAMETER_NAME = ""
VARIABLE_PARAMETER_VALUE = 0
# --EndUserVariable

定義した変数には、初期値を設定しておきます。

ユーザー変数設定に表示する情報を定義

定義したユーザー変数をユーザー変数画面に表示するための情報を定義します。
以下のようにダブルクオーテーション (") 3つで囲われた docstring の中に、変数名、種類、説明を、定義した変数の前に記述します。

"""
変数名:
  type: 変数の種類
  comment: パラメーターの説明
"""

typeには、次の3種の種類があり変数の内容によって指定する種類を変更します。

タイプの種類	説明
object	変数がオブジェクトの場合に指定します
string	変数が文字列の場合に指定します
number	変数が数値の場合に指定します

スクリプトに記述すると、次のようになります。

# --BeginUserVariable
"""
VARIABLE_CUE:
  type: object
  comment: パラメーターを変更するキュー
VARIABLE_PARAMETER_NAME:
  type: string
  comment: パラメーターのフィールド名
VARIABLE_PARAMETER_VALUE:
  type: number
  comment: パラメーター値
"""
VARIABLE_CUE = None
VARIABLE_PARAMETER_NAME = ""
VARIABLE_PARAMETER_VALUE = 0
# --EndUserVariable

ここで、スクリプトエディターのツールバーボタンから [更新] ボタンをクリックすると、スクリプトエディター右の「ユーザー変数」にスクリプトエディターで記述したユーザー変数情報が表示されます。

ユーザー変数へのパラメーター設定

スクリプトエディターの「ユーザー変数」にスクリプトで設定したユーザー情報を表示できたら、各ユーザー変数を設定していきます。
VARIABLE_CUE に、 CRI Atom Craft のツリーからドラッグ&ドロップして設定します。
VARIABLE_PARAMETER_NAME、VARIABLE_PARAMETER_VALUE には、以下の値を設定します。

変数名	値
VARIABLE_PARAMETER_NAME	Pitch
VARIABLE_PARAMETER_VALUE	100

適用をクリックすると、スクリプトにスクリプトエディターの「ユーザー変数」の内容が反映されます。

定義した「ユーザー変数」を使ってキューのパラメーターを更新

ユーザー変数機能を使って、ユーザー変数に値が設定できました。
ユーザー変数を使って、キューのパラメーター更新を行います。
キューのパラメーター更新する処理をスクリプトで記述すると次のようになります。

acproject.set_value(VARIABLE_CUE, VARIABLE_PARAMETER_NAME, VARIABLE_PARAMETER_VALUE)
 
acdebug.log("[チュートリアル]ユーザー変数を使ってキューの「ピッチ」パラメーターの変更 が完了しました")

スクリプトの保存と実行

これで本チュートリアルのスクリプト記述は終了です。
スクリプトを保存し、実行しましょう。
スクリプトが正常に実行されると以下のように、キューのピッチの値がユーザー変数画面で設定した値に更新されます。

ユーザー変数機能を使って、キューのピッチを変更するスクリプトを紹介しました。
このスクリプトの対象はキューのみではなく、トラックなどを指定することも可能です。
また、ピッチ以外のパラメーター名を指定することもできます。
スクリプトを編集して色々と試してみてください。