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

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

Choose your operating system:

Windows

macOS

Linux

コントロールリグで 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')

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

  # load a skeletal mesh
  mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)
  # create a control rig for the mesh
  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')

  # get an array of all available units
  units = unreal.ControlRigBlueprint.get_available_rig_units()

  # print details about the units
  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 ノードです。

  # get the unit - you might also get this by path or similar
  unit = unreal.RigUnit_MathFloatAdd.static_struct()

  # add the node to the graph provided the unit struct, the method (is always Execute) and 2D position in the graph
  node = controller.add_unit_node(script_struct = unit, method_name = "Execute", position = unreal.Vector2D(0, 0))

階層を編集する

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

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

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

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

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

  # access the hierarchy object
  hierarchy = rig.hierarchy

  # get all element keys and print them
  elements = hierarchy.get_all_keys()
  for element in elements:
      print(element)

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

  # access the hierarchy controller object
  hierarchy_ctrlr = rig.get_hierarchy_controller()

  # add a new bone
  new_bone_key = hierarchy_ctrlr.add_bone(name = "MyBone", parent = unreal.RigElementKey(), transform = unreal.Transform())

  # add a new child bone to a parent that is 10 units away on Z
  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 ="")

  # Create variable getter node
  controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = True, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Getter')

  # Create variable setter node
  controller.add_variable_node_from_object_path(MyVariable, 'FTransform', '/Script/CoreUObject.Transform', is_getter = False, default_value = '', position = unreal.Vector2D(), node_name = 'MyVariable_Setter')

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

  # load a skeletal mesh
  mesh = unreal.load_object(name = '/Game/Mannequin/Character/Mesh/SK_Mannequin.SK_Mannequin', outer = None)

  # create a new (empty) asset
  factory = unreal.ControlRigBlueprintFactory()
  rig = factory.create_new_control_rig_asset(desired_package_path = '/Game/TestRig')

  # set the preview mesh
  rig.set_preview_mesh(preview_mesh = mesh)

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

  # force a recompile of the VM
  rig.recompile_vm()

  # compile the VM if there are pending changes
  rig.recompile_vm_if_required()

  # request a compilation if auto compile is enabled and the editor is open
  rig.request_auto_vm_recompilation()

  # request the control rig to run an init pass (initialize all units)
  rig.request_control_rig_init()

  # request the control rig to run a full blueprint compile
  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