(Terragen4) Terragen RPCを試す そのX High Level APIまとめ

Terragen RPCでのHigh Level APIをまとめました。

バージョン0.9.1のリファレンスを元にまとめています。
Terragen RPC — Terragen RPC 0.9.1 documentation

各APIには細かい制約や注意事項がありますが、まだAPIは変わることが確実であり、不完全であることから、ここでは詳細に記述しません。
そもそも実際にコードを書く際は公式に用意されたドキュメント原文を参照するべきですので、あくまでこんなAPIがあるよ、といった参考程度にどうぞ。

カテゴリ分けは私がやったものです。

（本記事の）変更履歴

2022/11/5 初版
2022/11/6 誤記訂正

主要な用語

名称	型	意味
path	str	ノードの場所を指す(/Render Camera 等)
node_or_nodes	Node | list of Node	Nodeクラスのインスタンス（GUI上のノードやグループに相当）またはそのリストを指す。
class_name	str	Nodeの種類。‘group’, ‘camera’, ‘sunlight’, ‘image_map_shader'など。TGDファイルやTGCファイルに記録される際の名称。
param_name	str	パラメータ名
filename	str	ファイルパス（TBC 相対パスでもいけるか？）
values	str | number | tuple of numbers | list of numbers	値
value_string	str	値（文字列）

API

カテゴリ	API名	引数型	返り値型	説明
プロジェクト	project_filepath()	-	str	現在開いているプロジェクトのファイルパスを返す。
^	new_project()	-	-	新規プロジェクトを作成する。
^	open_project(filename)	str	-	filenameで指定されたプロジェクトを開く。
^	save_project(filename)	str	-	filenameで指定された名前でプロジェクトをファイルに保存する。
クリップファイル	insert_clip_file(filename)	str	bool	クリップファイルの内容をネットワークに追加する。（GUIでの“Insert Clip File…”と同様の効果）
^	insert_clip_file_after(filename, input_node)	filename: str	bool	input_nodeで指定したノードの出力に、クリップファイルの内容を結合する（GUIでの“Insert Clip File…”->"Add"と同様の効果）
^	^	input_node: Node	^	^
^	insert_clip_file_before(filename, output_node, output_param='input_node')	filename: str	bool	output_nodeで指定したノードの、output_paramで指定したパラメータにクリップファイルの内容を挿入する（GUIでの“Insert Clip File…”と同様の効果）
^	^	output_node: Node	^	^
^	^	output_param: str	^	^
ノード操作	root()	-	Node | None	ルートノードを返す。
^	node_by_path(path)	str	Node | None	pathで指定したノードを返す。
ノード選択	current_selection()	-	list of Node	ネットワーク上で選択されているノードを返す。
^	select_just(node_or_nodes)	Node | list of Node	-	現在選択されているノードを選択解除し、node_or_nodesで指定したノードを選択状態にする。
^	select_more(node_or_nodes)	Node | list of Node	-	現在選択されているノードに加えて、node_or_nodesで指定したノードを選択状態にする。
^	select_none()	-	-	ノードの選択を解除する。
ノード作成	create_child(of_node, class_name)	of_node: Node	Node | None	of_nodeで指定したノードに、class_nameで指定した種類のノードを作成する。
^	^	class_name: str	^	^
ノード削除	delete(node_or_nodes)	Node | list of Node	-	node_or_nodesで指定したノードを削除する。

Nodeクラスのメソッド

カテゴリ	API名	引数型	返り値型	説明
全般操作	name()	-	str	ノードの名前を返す。
^	path()	-	str	ノードのパスを返す。
^	parent_path()	-	str	親ノードのパスを返す。
^	parent()	-	Node	親ノードを返す。
^	children()	-	list of Node	子ノードを返す。
^	children_filtered_by_class(class_name)	str	list of Node	子ノードのうち、class_nameで指定された種類のノードを返す。
パラメータ	param_names()	-	list of str	ノードの持つパラメータ名の一覧を返す。
パラメータ値取得	get_param(param_name)	str	str(現状)	指定したパラメータの値を返す。（本来はそのパラメータに応じた型の値を返すが、現状はget_param_as_stringと同じ動きをする）
^	get_param_as_string(param_name)	str	str	指定したパラメータの値を文字列型で返す。
^	get_param_as_int(param_name)	str	int	指定したパラメータの値を整数型で返す。
^	get_param_as_float(param_name)	str	float	指定したパラメータの値を実数型で返す。
^	get_param_as_tuple(param_name)	str	tuple of 1, 2, or 3 floats	指定したパラメータの値をタプルで返す。
^	get_param_as_list(param_name)	str	list of 1, 2, or 3 floats	指定したパラメータの値をリストで返す。
パラメータ値設定	set_param(param_name, values)	param_name: str	-	指定したパラメータの値を設定する。
^	^	values: str | number | tuple of numbers | list of numbers	^	指定したパラメータの値を設定する。
^	set_param_from_string(param_name, value_string)	param_name: str	-	指定したパラメータの値を文字列で設定する。
^	^	value_string: str	^	指定したパラメータの値を設定する。

例外

APIの実行に失敗した場合、例外がスローされる。
　 TBD

(Terragen 4) Terragen RPCを試す その1（準備・サンプル実行）

本記事の対象Terragen 4バージョン：Professional (Educational含む)

前回

注意：本記事はTerragen RPCのベータ版（0.9.2）を基にしています。アップデートにより、コードに変更が加わる場合があります。

また、Windows 10/11前提で進めます。

1. Pythonをインストール

   サンプルを実行するために、Pythonをインストールします。
   つい最近3.11が出たばかりですが、バージョン違いで面倒なトラップを踏みたくないので、チュートリアルと同じ3.10.5とします。
   Python Release Python 3.10.5 | Python.org

   ページ下部の「Windows installer」をクリックしてダウンロードします。

   ダウンロードしたインストーラを起動して、インストールします。

   インストーラ下部のAdd Python 3.10 to PATHにチェックを入れておきます。
   

   インストールが終わったら、コマンドプロンプトを起動して、python --versionと打ちます。 ↓のように、3.10.5と出ればOKです。

   

2. Terragen RPCをダウンロード

   以前はGitHubからダウンロードする必要がありましたが、2023/7/6からpipからインストールできるようになっていました。 pipとは、Pythonで使える様々な拡張機能がダウンロードできるサービスのことです。（非常にざっくりな説明だから詳しい人怒らないで）

   下記のコマンドを実行だけで使えるようになります。

    pip install terragen-rpc
   

   

   さて、ここからは、https://planetside.co.uk/docs/terragen-rpc/high-py-api.htmlに記載されているサンプルコードを使って試していきましょう。

   メモ帳などのエディタを開き、下記のコードを書き（コピペでよいです）、「rpc-sample.py」という名前で保存してください。

   import terragen_rpc as tg
   
   # Print the nodes at the top level of the project
   
   project = tg.root()
   children = project.children()
   for c in children:
       print(c.path())
   
   # Print the parameters of a node whose path is "/Render Camera"
   
   camera = tg.node_by_path('/Render Camera')
   if camera:
       print(camera.param_names())
   else:
       print("Node not found")
   
   # Note: Exception handling was omitted from this example for brevity.
   # See other examples for exception handling.
   

   上記のスクリプトを実行しましょう。

   先に、Terragen 4.6を起動しておいてください。

   まず、rpc-sample.pyが保存されているフォルダで、エクスプローラの右クリックメニューから「ターミナルを開く」をクリックします。（ここでは英語版表示ですみません。Windows Terminalが開きます）
   

   または、エクスプローラのアドレスバーにcmdと打ち込み、Enterキーを押します。（コマンドプロンプトが開きます）

   開いたターミナルまたはコマンドプロンプトに、python rpc-sample.pyと打ってみましょう。こんな表示となるはずです。（Windows Terminalでの表示例です）
   

   お疲れさまでした。

   では、今実行したスクリプトの流れをざっくりと書きます（あんまりPythonの知識が無くてもいいように）。

   メインの処理は6行目からですね。

   まずノードネットワークの一番上の階層にアクセスし、children()でそこにあるノードたちを取得します。 childrenにはルートにぶら下がってる各ノードが格納されています。

    root = tg.root()
    children = root.children()
   

   それぞれのノードの、ルートからのパスを順番に表示していきます。パスはスラッシュから始まります。

    for c in children:
        print(c.path())
   

   

   これで一区切りです。

   次の行からはまた別の処理をしています。 node_by_path()で、パスが/Render Cameraのノードを探します。 あったら、そのノードがcameraに格納されます。 param_names()で、ノードが持つパラメータの名前の一覧を表示しています。 もし、パスが/Render Cameraのノードがなければ、エラーメッセージを表示します。

    # Print the parameters of a node whose path is "/Render Camera"
   
    camera = tg.node_by_path('/Render Camera')
    if camera:
        print(camera.param_names())
    else:
        print("Node not found")
   

3. 次回予告

   今回は簡単な例でしたが、もう少しいろんなAPIを使って遊んでいきます。

   以上。

(Terragen 4) Terragen RPCを試す、の前振り

本記事の対象Terragen 4バージョン：Professional (Educational含む)

Terragen 4.6において、（個人的に）とても興味深いアップデートがありました。

Coming soon: RPC API

RPC (Remote Procedure Call)とは、動作中のプログラムに対して外部からの操作を加えたり、プログラムからの応答を返したりする、いわゆる遠隔操作をするための規約のことを指します。 RPCのやり方にも多数ありますが、TerragenではJSON-RPCと呼ばれる手法を使っています。

JSON (JavaScript Object Notation)のことで、JavaScriptにおけるオブジェクトの書き方を基にした、データ構造の書き方のことです。 まあこの辺りはそのうち実例を示します。

このTerragen RPCにより、動作中のTerragen 4のノードを外部から参照したり、編集したりできるようになりました。 これによって、従来はできなかったいろいろな拡張が可能となります。 たとえば、以前私が作成したPBR Node Generatorも、今はコピー操作やTGCファイル経由でTG4にノードネットワークを追加していましたが、
・オブジェクトの一覧を表示・選択し、
・任意のオブジェクトに対してテクスチャ類を一括指定
・結果が即座にTG4側に反映される

のようなことが可能になります。 また、外部のアプリケーションとのリアルタイムの同期を行うようなスクリプトを作成すれば、他アプリケーションを使ったワークフローの効率化が可能となるでしょう。

JSON-RPC自体は言語に寄らず使用することができますが、Terragen RPCでは、PS社からPythonによるAPIラッパライブラリと、サンプルが公開されています。（バージョン0.9現在） Pythonコードにより簡単にTerragen 4を外部から操作することができます。

GitHub - planetside-software/terragen-rpc

（ここから少し専門的になりますが）

APIはHigh Level APIとLow Level APIに分かれています。
High Level APIは、例えばノードを作るとか、削除するとか、パラメータを更新・参照するとか、我々が普段GUI上でやっている操作をプログラムから行うための関数群です。
Low Level APIは、よりRPCの通信部分に近いところであり、（おそらく）アプリケーション側からは通常触ることがないものです。

（ここまで）

Terragen RPCのドキュメントはこちらにまとまっています。 また、チュートリアルとして、地球上の位置と時刻を指定することで太陽の位置を求めて設定するチュートリアルが用意されています（便利では！？）

Terragen RPC — Terragen RPC 0.9.1 documentation

次回以降、Terragen RPCを実際に試していきます。 最終的には、上で例示したPBR Node Generatorに組み込んでいきます（NodeベースからPythonベースに移植する決意がつきました）

本業はC++屋なのでC++でのAPIラッパ書くのもいいですね（やるとは言っていない）

今日は以上！

（個人的に今引っ越し中で遊べねえ〜〜〜うわ〜〜〜。次回更新は11/20あたりを狙っています）とか言いながら書いてしまいました。

次回：(Terragen 4) Terragen RPCを試す その1（準備・サンプル実行） - ++scenes;