(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 | ^ | 指定したパラメータの値を設定する。 |
例外
(Terragen 4) Terragen RPCを試す その1(準備・サンプル実行)
本記事の対象Terragen 4バージョン:Professional (Educational含む)
注意:本記事はTerragen RPCのベータ版(0.9.2)を基にしています。アップデートにより、コードに変更が加わる場合があります。
また、Windows 10/11前提で進めます。
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です。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")
次回予告
今回は簡単な例でしたが、もう少しいろんなAPIを使って遊んでいきます。
以上。
(Terragen 4) Terragen RPCを試す、の前振り
本記事の対象Terragen 4バージョン:Professional (Educational含む)
Terragen 4.6において、(個人的に)とても興味深いアップデートがありました。
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あたりを狙っています)とか言いながら書いてしまいました。