コントロールリグによるリギングのための Python スクリプティング

Python スクリプティングを使用してコントロールリグによるリギング処理を拡張およびカスタマイズします。

コントロールリグで Python スクリプティング を使用すると、ワークフローを自動化し、リギング プロセスのためのツールを作成できます。また、コントロールリグの Python ログ を使用してコマンドをリバースエンジニアリングし、スクリプトをコピーして他のプロジェクトと共有することもできます。

このドキュメントでは、コントロールリグでの Python スクリプティングの概要、コントロールリグの Python ログについて説明し、スクリプト サンプルをいくつか紹介します。

前提条件

スクリプティングの概要

Python は主にコントロールリグで、複数のモジュールで構成されるリグ グラフを操作するために使用されます。

モジュール名

説明

ControlRig

リグのランタイムが格納されています。

ControlRigDeveloper

リグに変更を加えるためのすべての機能が格納されています。

ControlRigEditor

フロントエンドとユーザー インターフェースのロジックが格納されています。

コントロールリグ グラフは、モデル - ビュー - コントローラー の設計パターンを使用して実装されています。このモデルは、グラフ自体であり、以下の用語を使用します。

コントロールリグの Python の用語

説明

RigUnit (リグユニット)

リグの関数を定義する C++ 構造体 (例:FRigUnit_GetBoneTransform)。

ピン

関数の 1 つの入力または出力。

リンク

2 つのピン間の接続。

ノード

RigUnit の視覚的な表現。

グラフ

リグ内のすべてのノードとリンクを含む有向グラフ。

PinPath (ピンパス)

グラフ内のピンのアドレスを記述した文字列 (例:NodeA.Translation.X)。

コントローラー

グラフで変更を行うために使用するオブジェクト。

RigElementKey (リグ要素キー)

ボーン、コントロール、Null、カーブから選択する。

ボーン

変形に使用するスケルトン内のリグの要素。

コントロール

相互作用に使用するリグの要素。

Null

中間トランスフォームに使用するリグの要素。

カーブ

浮動小数点チャンネルを格納するために使用するリグの要素。

形状

ビューポートのコントロールの視覚的な表現。

階層

リグ内のすべてのボーン、コントロール、Null、カーブを格納するコンテナ。

HierarchyController (階層コントローラー)

HierarchyController は、コントローラーと同じように、階層に変更を加えるために使用される。

コンパイラ

コントロールリグ グラフを高性能ランタイムにするためのオブジェクト。

VM

リグの実行に使用される仮想マシンのランタイム。

定数

ランタイム時に変更されない値。

パラメータ

リグへの入力またはリグからの出力として使用可能な値。

変数

ランタイム時に変更可能な値で、リグの実行後も保持される。

ControlRigBlueprint (コントロールリグブループリント)

グラフ、コントローラー、コンパイラ、VM を格納するアセット。

ファクトリ

新しいオブジェクトを作成およびインポートするオブジェクト。これは、Unreal Editor 全体で、アセットを作成するために使用されます。

Python は、Python Editor Script プラグイン から有効化されます。このプラグイン自体は、Unreal Engine でデフォルトで有効になっています。また、Control Rig プラグイン を有効にすると、依存関係にあるため Python Editor Script プラグインも自動的に有効になります。

コントロールリグにアクセスする

スクリプトを作成する際の最初のステップは、操作するメイン オブジェクト (この場合は ControlRigBlueprint オブジェクト) にアクセスすることです。複数のアクセス方法がありますが、コントロールリグに変更を加えるため、通常、最初のコマンドで、ControlRigDeveloper モジュールをロードします。

  unreal.load_module('ControlRigDeveloper')

既存のリグにアクセスするには、次のコマンド例を使用して、アセットをロードします。

  rig = unreal.load_object(name = '/Game/ControlRig/Samples/Mannequin_ControlRig', outer = None)

また、次のコマンドを使用して、現在開いているコントロールリグ アセットをロードすることもできます。

  rigs = unreal.ControlRigBlueprint.get_currently_open_rig_blueprints()

新しいコントロールリグ アセットを作成するには、次のコマンドを使用します。

  factory = unreal.ControlRigBlueprintFactory()
  rig = factory.create_new_control_rig_asset(desired_package_path = '/Game/TestRig')

最後に、次のコード サンプルを使用すると、スケルトンまたはスケルタル メッシュに基づくコントロールリグ アセットを作成できます。

  # スケルタルメッシュをロードする
  mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)
  # メッシュのコントロール リグを作成する
  factory = unreal.ControlRigBlueprintFactory
  rig = factory.create_control_rig_from_skeletal_mesh_or_skeleton(selected_object = mesh)

Python ログ

Python ログ では、コントロールリグ エディタ内で実行したすべてのアクションのテキスト ログを提供します。このログには、ビューポート、階層、グラフ内のアクションが含まれます。このログを使用すると、Python スクリプトで使用するコマンドを参照することができます。

このログにアクセスするには、コントロールリグのメインメニューから [Window (ウィンドウ)] > [Message Log (メッセージ ログ)] をクリックし、[Message Log (メッセージログ)] のサイドバーから [Control Rig Python Log (コントロールリグの Python ログ)] を選択します。

control rig python log

これで、リグ グラフでアクションを実行すると、ログに記録されるようになりました。

python log record actions

コマンドを保存して共有したり、他の場所で使用したりする必要がある場合は、ログの任意の行を選択して Ctrl + C キーを押してコピーし、任意のテキスト エディタに貼り付けることができます。また、Shift キーを押しながら選択すると、複数の行を選択できます。

python log copy paste

コマンドをテストするには、コマンドを [Output Log (アウトプット ログ)] に貼り付けて、実行します。この際、ログ タイプは必ず [Python] に設定します。この例では、新しいコントロールが作成されます。

python output log command

Python コンテキスト

Python コンテキストは、Python コマンドを実行するときに、どのコントロールリグ アセットに作用する必要があるかをコンテキスト化するために使用されます。デフォルトでは、コントロールリグを表示する際には、コンテキストは設定されていません。現在のコントロールリグのコンテキストを設定するには、[Class Settings (クラス設定)] の [Details] パネルで、[Run Python Context (Python コンテキストを実行)] クリックします。

run python context

この操作により、現在のコントロールリグ アセットを Python コンテキストにバインドする一連のコマンドが実行されます。このことにより、Python ログからコピーしたコマンドをこのコントロールリグ アセット内に貼り付けて実行することができます。

run python context commands

  blueprint.get_controller_by_name('').set_node_selection([])
  import unreal
  blueprint = unreal.load_object(name = '/Game/ShowAndTell202009/Pretzel/Mannequin_FBIK_CtrlRig', outer = None)
  library = blueprint.get_local_function_library()
  library_controller = blueprint.get_controller(library)
  hierarchy = blueprint.hierarchy
  hierarchy_controller = hierarchy.get_controller()

Python スクリプトのコピー

また、コントロールリグのノード、リグ要素、およびプロパティの全体をクリップボードにコピーすることができます。これを外部のスクリプト エディタに貼り付けたり、アウトプット ログに貼り付けることで、別のコントロールリグで実行することができます。Python スクリプトのコピーは、異なるリグ間のロジックの共有、デバッグ、比較に役立ちます。個別のコマンドのコピーと同様に、リグ全体をコピーすることも、コントロールリグから Python コマンドをリバースエンジニアリングするうえで役立ちます。

コントロールリグをコピーするには、[Class Settings] の [Details] パネルで [Copy Python Script (Python スクリプトをコピー)] をクリックします。

copy python script

Python スクリプトのサンプル

ノードを追加する

ノードは RigUnit 構造体の視覚的な表現であるため、グラフにノードを追加するためには、このユニットにアクセスする必要があります。

  unreal.load_module('ControlRigDeveloper')

  # すべての利用可能なユニットの配列を取得する
  units = unreal.ControlRigBlueprint.get_available_rig_units()

  # ユニットについての詳細を出力するs
  for unit in units:
      print(unit.get_path_name())
      print(unreal.EditorAssetLibrary.get_metadata_tag(unit, 'Keywords'))

次に、コントローラーにアクセスする必要があります。コントローラーは、グラフに変更を加えるために使用する中心的なオブジェクトです。

  controller = rig.get_controller()

グラフにノードを追加するには、add_struct_node 関数、add_comment_node 関数、add_parameter_node 関数、または add_variable_node 関数を使用できます。以下の例では、最も一般的なタイプである struct (構造体) ノードに焦点を当てています。struct ノードは RigUnit を視覚的に表現したものです。そのため、グラフ内のほとんどのノードは struct ノードです。

  # ユニットを取得する - パスなどでこれを取得することもできます
  unit = unreal.RigUnit_MathFloatAdd.static_struct()

  # ユニットの構造体、メソッド (常に Execute)、およびグラフ内の 2D 位置を入力したグラフにノードを追加する
  node = controller.add_unit_node(script_struct = unit, method_name = "Execute", position = unreal.Vector2D(0, 0))

階層を編集する

グラフの編集だけでなく、Python コードを使用して階層を編集することもできます。コントロールリグ階層の各リグ要素は、RigElementKey を使用して識別されます。RigElementKey には、要素の名前とタイプが格納されています。階層内の要素を作成したり操作したりする際には、このキーを使用する必要があります。

コントロールリグの要素は構造体です。つまり、コントロールリグの要素はその合計値を使用してコピーされます。そのため、要素を変更すると、階層内でその要素を再度設定する必要がある場合があります。

階層 は、要素のクエリ、グローバル/ローカル トランスフォームのゲットまたはセット、要素の初期値へのリセットに使用することができます。

HierarchyController を使用すると、要素の追加、削除、編集を行うことができます。また、必要に応じて要素の名前を変更したり、要素の親を変更するために使用できます。

現在の階層の調査を実行するには、次の Python コードを使用できます。

  # 階層オブジェクトにアクセスする
  hierarchy = rig.hierarchy

  # すべての要素のキーを取得し、それらを出力する
  elements = hierarchy.get_all_keys()
  for element in elements:
      print(element)

ボーンなどのリグ要素を作成するには、次のコードを使用できます。

  # 階層コントローラー オブジェクトにアクセスする
  hierarchy_ctrlr = rig.get_hierarchy_controller()

  # 新規ボーンを追加する
  new_bone_key = hierarchy_ctrlr.add_bone(name = "MyBone", parent = unreal.RigElementKey(), transform = unreal.Transform())

  # Z 上の 10 ユニット離れた親に新しい子ボーンを追加する
  child_transform = unreal.Transform(location = [0, 0, 10])

  new_child_bone_key = hierarchy_ctrlr.add_bone(name = "ChildBone", parent = new_bone_key, transform = child_transform)

変数およびアセットの操作

ゲッター ノードおよびセッター ノードを使用してコントロールリグ変数を作成するには、次のコードを使用できます。

  rig.add_member_variable("MyVariable", "Transform", is_public = True, is_read_only = False, default_value ="")

  # 変数ゲッター ノードを作成する
  controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = True, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Getter')

  # 変数セッター ノードを作成する
  controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = False, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Setter')

また、プレビュー メッシュは以下のコードを使用して変更できます。

  # スケルタルメッシュをロードする
  mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)

  # 新規 (空の) アセットを作成する
  factory = unreal.ControlRigBlueprintFactory()
  rig = factory.create_new_control_rig_asset(desired_package_path = '/Game/TestRig')

  # プレビュー メッシュを設定する
  rig.set_preview_mesh(preview_mesh = mesh)

コンテキストに応じて、次のいずれかのコードを使用して、コントロールリグをコンパイルすることができます。

  # VM の再コンパイルを強制する
  rig.recompile_vm()

  # 保留中の変更がある場合は、VM をコンパイルする
  rig.recompile_vm_if_required()

  # 自動コンパイルが有効でエディタが開いている場合、コンパイルをリクエストする
  rig.request_auto_vm_recompilation()

  # コントロール リグをリクエストし、初期パスを実行する (すべてのユニットを初期化)
  rig.request_control_rig_init()

  # コントロール リグをリクエストし、完全なブループリントのコンパイルを実行する
  unreal.BlueprintEditorLibrary.compile_blueprint(rig)

エディタの起動

エディタ起動時に Python スクリプトをロードすることができます。これは、カスタム ツールやビルトインの Python 関数のロードに役立ちます。このスクリプトとサンプルのスクリプト関数は、次のフォルダ パスのプロジェクト ディレクトリに格納されています。

Engine\Plugins\Animation\ControlRig\Content\Python

このフォルダの中に、init_unreal.py スクリプトがあり、次のコードが格納されています。

  import RigHierarchy.add_controls_for_selected
  import RigHierarchy.add_null_above_selected
  import RigHierarchy.align_items

  RigHierarchy.add_controls_for_selected.run()
  RigHierarchy.add_null_above_selected.run()
  RigHierarchy.align_items.run()

init_unreal.py python custom command

このコードは、追加機能を有効にするサンプル スクリプトをロードします。

たとえば、add_controls_for_selected は、選択したボーンのコントロールを追加のルールで作成する機能を有効にします。これらのルールは、Engine\Plugins\Animation\ControlRig\Content\Python\RigHierarchy\add_controls_for_selected.py に格納されているカスタムの Python スクリプトで決定されます。

add controls for selected

タグ
Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
キャンセル