XGen Python API

概要

XGen は Python API を提供し、これにより Python シェルから XGen の内部データへのアクセスを可能にしています。これは Maya の内部でも外部でも使用できます。この API は Maya の内部に拡張されています。これは、Maya 内部に適用する処理(たとえば、ガイドの「名前」を承認してパッチを取得する)を可能にするためですが、それ以外には適用しないでください。XGen とのすべてのインタラクションは、この API を利用して、またはユーザ インタフェースから実行する必要があります。MPxCommandを介してのアクセス、および XGen 内に存在する可能性のある MEL 関数を介してのアクセスは保証されていません。

以下にすべてのメソッドを、戻り値のタイプと期待するパラメータ タイプを示す疑似構文で一覧表示します。メソッドの呼び出しは、Python で通常行う方法で行われます。順番にパラメータを渡しても、名前を使用して必要に応じて並べ替えてもかまいません。

API のインポート

この API は、ベース API と Maya API という 2 つの部分に分かれています。UI は独立した 1 つのコンポーネントですが、この API は基本的に、基底となる C++ コード、そしてベース API を構成する Python レイヤー、さらに Maya 追加要素を取り込むためのもう１つの Python レイヤーで構成され、それに加えて Maya API を構成する予備の API 機能もあります。タスクにとって適切な API を取り込むことが重要です。そうしないと、予期せぬ結果になる場合があります。最適なアプローチは、次のコマンドを使用して、XGen に判断を任せることです。

import xgenm as xg

これにより、Maya を検出する xgen モジュールが取り込まれ、任意で API の Maya レイヤが取り込まれます。Maya の内部と外部で実行されるスクリプトを使用していて、API の Maya 専用部分からメソッドを呼び出す場合は、それらを条件付きブロック内に配置する必要があります。これに安全に対処する方法は、次のように XGen の Maya 検出を使用することです。

import xgenm.xgGlobal as xgg

if xgg.Maya
    #XGen の Maya API の使用など、Maya 特有の処理を行う

これは XGen グローバル モジュールを取り込みます。これには Maya を検出する機能があります。この設定が終わったら、その xgg.Maya を使用して自分が Maya にいて Maya コードをこれらの条件の範囲内で保護することを決定できます。

ベース API

次のメソッドは、Maya の内側でも外側でも使用することができます。これらは、基底となる XGen データに対し直接実行されます。その多くは、XGen へのさらに速いリンクが必要であれば、C++ の API として libXgAPI.so ライブラリから使用することもできます。

作成および削除

• string createDescription( string palette, string description, string primitive, string generator, string renderer, string method )()
  • 新しいディスクリプションを作成し、該当する名前のパレットの中に配置します。パレットが存在しない場合は、それも作成されます。
• bool deletePalette( string palette )()
  • 該当する名前のパレットを削除します。これによって、そのディスクリプション、パッチ、オブジェクト、FX モジュール、ガイドなどのすべてが削除されます。
• bool deleteDescription( string palette, string description )()
  • 該当する名前のディスクリプションを削除します。これによって、そのパッチ、オブジェクト、FX モジュール、ガイドなどのすべてが削除されます。

オブジェクトのアクセス

• string[] palettes()
  • 現在シーンにあるパレットのリストを取得します。
• string[] descriptions( string palette="" )()
  • 指定のパレットに関するディスクリプションのリストを取得します。または、パレット名がない場合はシーン内のすべてのディスクリプションを返します。
• string palette( string description )()
  • 指定のディスクリプションに関するパレットを取得します。これを実行するために、各パレットに関するディスクリプションのリストが検索されます。これは、すべてのディスクリプションに一意の名前が付いていることを前提にしています。
• string getActive( string palette, string description, string type )()
  • ディスクリプションから指定のタイプのアクティブなサブタイプを取得します。戻り値はサブタイプ(たとえば SplinePrimitive や CardPrimitive)です。
• bool setActive( string palette, string description, string subtype, bool previewer=False )()
  • ディスクリプションに対し指定のタイプのアクティブなサブタイプを設定します。指定されたサブタイプには完全な名前(たとえば CardPrimitive や FileRenderer)を付ける必要があります。
• string[] objects( string palette, string description, bool activeOnly=False )()
  • ディスクリプションに関するすべてのオブジェクト(SpherePrimitive や GuideRenderer など)のリストを取得します。
• bool initInterpolation( string palette, string description, string fileName="" )()
  • 指定されたディスクリプションのアクティブなプリミティブに対して補間を初期化します。ガイドが新しい位置に移動される、ガイドが追加される、ガイドが削除されるたびに実行する必要があります。

アトリビュートのアクセス

• bool attrExists( string attrName, string palette, string description="", string object="" )()
  • Xgen オブジェクトのアトリビュートの有無をクエリします。
• string getAttr( string attrName,string palette, string description="", string object="" )()
  • Xgen オブジェクトのアトリビュートの値を取得します。
• bool setAttr( string attrName, string value, string palette, string description="", string object ="")()
  • Xgen オブジェクトのアトリビュートの値を設定します。
• string[] attrs( string palette, string description="", string object="" )()
  • 指定されたノードに関するアトリビュートのリストを返します。これには、カスタム アトリビュートが含まれません。
• void addCustomAttr( string attrName, string palette, string description="", string object ="")()
  • カスタム アトリビュートを追加するアトリビュートには、次のテンプレート パターンを使用して名前を付ける必要があります。custom_<タイプ>_<名前> または custom_<タイプ>_<名前>[#]配列が拡張子[#]で指定されている場合、その配列の各要素にアトリビュートが追加されます。一般的な使用法は、パレットまたは RenderMan レンダラのいずれかにアトリビュートを追加することですが、任意のオブジェクトを指定することができます。
• void remCustomAttr( string attrName, string palette, string description="", string object="" )()
  • カスタム アトリビュートを除去するアトリビュートには、次のテンプレート パターンを使用して名前を付ける必要があります。custom_<タイプ>_<名前> または custom_<タイプ>_<名前>[#]配列は拡張子[#]で指定されている場合、その配列のすべてのアトリビュートが削除されます。
• string[] customAttrs( string palette, string description="", string object="" )()
  • 指定されたノードに関するカスタム アトリビュートのリストを返します。
• string[] allAttrs( string palette, string description="", string object="" )()
  • 指定されたノードに関するアトリビュートを網羅したリストを返します。

Fx モジュール

• string[] fxModules( string palette, string description)()
  • 指定したパレットとディスクリプションに関する fx モジュールのリストを取得します。現在アクティブなプリミティブに関して、実行される順序でモジュールが返されます。
• string fxModuleType( string palette, string description, string name )()
  • 指定された fx モジュールのタイプを取得します。アクティブなプリミティブに対してモジュールを検索します。
• string addFXModule( string palette, string description, string type, string name="" )()
  • 指定されたディスクリプションのアクティブなプリミティブに関する fx チェーンの最後に新しい fx モジュールを追加します。モジュールが正常に追加された場合は、その名前が返されます。エラー時には、空の文字列が返されます。
• bool removeFXModule( string palette, string description, string name )()
  • 指定されたディスクリプションのアクティブなプリミティブから、該当する名前の fx モジュールを除去します。成功すると「true」を、失敗すると「false」を戻り値として返します。
• bool moveFXModule( string palette, string description, string name, int dir )()
  • Fx モジュールを移動します。モジュール名は、指定されたディスクリプションのアクティブなプリミティブにあるモジュールの検索に使用されます。見つかると、そのモジュールが「dir」の値に応じて上または下に移動します。負の値が「上」、正の値が「下」を意味します。

カリング(Culling)

• string[] culledPrimPatches( string palette, string description )()
  • パレットとディスクリプションが指定されると、カリング済みのプリミティブがあるパッチの名前を返します。
• int[] culledPrimFaces( string palette, string description, string patchName )()
  • パレットとディスクリプションとパッチが指定されると、パッチ名、カリング済みのプリミティブがあるパッチのフェースを返します。
• set(int) culledPrims( string palette, string description, string patchName, int faceId )()
  • パレットとディスクリプションとパッチとフェース ID が指定されると、そのフェースのカリング済みのプリミティブ ID を返します。

バインド情報

• string[] boundGeometry( string palette, string description )()
  • パレットとディスクリプションが指定されると、ジオメトリのバインドされた部分すべてに関し名前を返します。XGen では、次の項目もパッチ名前です。
• int[] boundFaces( string palette, string description, string patchName )()
  • パレットとディスクリプションとパッチ名が指定されると、そのパッチからディスクリプションにバインドされているフェースのリストを返します。

ファイル入出力

• string importPalette( string palette, string deltas[], string nameSpace="" )()
  • 指定された差分ファイルを適用して xgen ファイルからパレットを読み込みます。任意でこのパレットを、指定されたネームスペースに配置することができます。Maya では、wrapPatches と呼ばれる 4 番目の引数(既定値は true)があり、オプションとして使用できます。これを False に設定すると、パレットを取り込むことができ、パッチやガイドをロードしないようにできます。こうすると、パレットをジオメトリなしで取り込み、参照用に使用し、それを他の要素に転送するなどの操作ができます。
• bool exportPalette( string palette, string fileName )()
  • 指定したパレットをディスク上の .xgen ファイルに書き出します。
• int createDelta( string palette, string newDelta )()
  • 差分ファイルのリストの適用後に Maya にロードされた現在のパレットとバース パレットと比較してから、差分を新しい差分ファイルに書き出します。この関数は、ファイルが正常に書き込まれた場合 1 を返し、処理は成功したが書き込まれたファイルがない(処理前と変化がない)場合は 0 を返し、エラー(差分ファイルに無効な変更が見つかる)が発生すれば -1 を返します。
• bool applyDelta( string paletteName, string delta )()
  • 差分を既存のパレットに適用します。
• string importDescription( string palette, string fileName )()
  • xdsc ファイルからディスクリプションを読み込み、パレットに挿入します。ディスクリプションは、パレットのネームスペースに配置されます。そのディスクリプションによって使用されたパレットのエクスプレッションがあれば、それが復元されます。名前の矛盾が見つかった場合は、新しいディスクリプションのエクスプレッションの値がパレットのエクスプレッションに配置され、古い値がエクスプレッションのコメントに配置されます。
• bool exportDescription( string palette, string description, string fileName, bool guides = false )()
  • パレットからディスクリプションを(使用される可能性のあるパレット エクスプレッションも含む)、xdsc ディスクリプション ファイルの中に書き出します。guides フラグは予約されており、現在は使用されていません。
• string importFXModule( string palette, string description, string fileName )()
  • FX モジュールを xgfx ファイルから読み込み、指定のディスクリプションのアクティブなプリミティブに挿入します。
• bool exportFXModule( string palette, string description, string name, string fileName )()
  • 指定されたディスクリプションのアクティブなプリミティブから、該当する名前の FX モジュールを書き出します。

イベントのコールバック

• registerCallback( string name, string function )()
  • 該当する名前の XGen イベントが発生した場合に呼び出される関数を登録します。イベント タイプには、PrePaletteCreate、PostPaletteCreate、PreDescriptionCreate、PostDescriptionCreate、および CurrentDescriptionSet があります。
• deregisterCallback( string name, string function )()
  • 該当する名前の XGen イベントが発生した場合に呼び出されないように関数の登録を抹消します。

メッセージ

• setMessageLevel( string type, int level )()
  • 特定のタイプのメッセージに関する冗長レベルを設定します。タイプは、debug、warning、stats、quitOnError のいずれかになります。最初の 3 タイプについては、0 から 5 までレベルを設定できます(5 が冗長性が最も高い)。quitOnError には、ブール値を設定します(1 がオンで 0 がオフ)。
• int getMessageLevel( string type )()
  • 特定のタイプのメッセージに関する冗長レベルを取得します。タイプは、debug、warning、stats、quitOnError のいずれかになります。最初の 3 タイプについては、0 から 5 までレベルが返ります(5 が冗長性が最も高い)。quitOnError では、返されるレベルが 0 か 1 になります(1 がオンで 0 がオフ)。

一般

• string version()
  • 現在実行されている XGen のバージョンのバージョン番号を取得します。
• string rootDir()
  • XGen のルート ディレクトリです。
• string iconDir()
  • XGen アイコンを保持するフォルダです。
• string globalRepo()
  • グローバル リポジトリの場所を指定します。
• string localRepo()
  • ローカル リポジトリの場所を指定します。
• string userRepo()
  • ユーザ リポジトリの場所を指定します。
• string promoteFunc()
  • 要素のプロモート関数の現在値です。
• string objNameSpace( string name )()
  • 指定したオブジェクトのネームスペースを取得します。
• string stripNameSpace( string name )()
  • オブジェクトからネームスペースを除去し、オブジェクトの名前だけを返します。
• string prepForAttribute( string value )()
  • 埋め込まれた新規行とタブ文字の付いた文字列が指定された場合、この関数が文字列の各文字を同じ文字をエンコードしたものに置き換えます。これにより、文字列を 1 行に保存することができます。これは XGen ファイル内への保存やディスクリプション エディタでの編集には重要です。この関数では、prepForEditor と連結して使用した場合に、ラウンド トリップの文字列書式化とアトリビュートの格納が可能です。
• string prepForEditor( string value )()
  • エンコードされたタブと新規行の文字の付いた文字列が指定された場合、この関数が文字列を文字が復元されるように変換して、文字列を複数行テキスト エディタの中で使用できるようにします。これにより、エンコードされた文字列を元のエディタ用の形式に復元することができます。この関数では、prepForAttribute と連結して使用した場合に、ラウンド トリップの文字列書式化とアトリビュートの格納が可能です。

Maya Extension の API

ベース API メソッドのすべてを Maya から使用できますが、次のメソッドを使用すれば API がさらに拡張されます。これらは、一般的にその状況では意味がないため、ベース API の一部としては提供されていません。たとえば、Maya で「ガイド名」を受け取り「パッチ名」を返すメソッドは標準 XGen に適用されません。これは、ガイドに名前がなく、単にジオメトリ名に合わせてパッチ名が付けられるためですそうは言っても、ベース API のメソッドのいくつかは Maya でオーバーライドされます。このため、Maya を使用しているときは常に、MayaAPI を通じて API を参照することで正しいレイヤーが参照されるようにする必要があります。

• string guidePatch( string guide )()
  • 指定された名前でガイドのパッチを取得します。
• string guideDescription( string guide )()
  • 指定された名前でガイドのディスクリプションを取得します。
• string guideIndex( string guide )()
  • そのディスクリプション内のガイドのインデックスを取得します。
• string[] descriptionGuides( string descr )()
  • 指定のディスクリプションに関するガイドを取得します。
• string[] descriptionPatches( string descr )()
  • 指定のディスクリプションに関するパッチを取得します。
• string[] palettePatches( string palette )()
  • 指定したパレット内に含まれるすべてのパッチのリストを取得します。
• string[] geometryPatches( string geometry )()
  • ジオメトリの指定ピースにバインドされたパッチを取得します。
• string[] geometriesPatches( string geomList[] )()
  • リスト内のジオメトリのいずれかにバインドされているパッチを取得します。この関数は、シーケンス内のジオメトリが多数ある場合、geometryPatches を呼び出すよりも効率的です。
• string geometryDescriptionPatch( string geometry, string desc )()
  • ジオメトリのピースとディスクリプションが指定されると、バインドされた単一のパッチを返します。
• string[] geometryFacePatches( string geometry, string faceId )()
  • ジオメトリのピースと faceId が指定されると、そのフェースに関連するすべてのパッチを返します。
• modifyFaceBinding( string palette, string description, string mode="Append" )()
  • 現在のディスクリプションのフェースのバインドを修正します。アペンドする モードでは、選択されているフェースが、関連付けられたジオメトリにバインドされているパッチに追加されます。ジオメトリにパッチが存在しない場合は、新しいパッチが作成されます。置き換える モードでは、関連付けられたジオメトリに対して、選択されたフェースがパッチ内のフェースに置き換わります。そして、削除する モードでは、パッチが存在すれば、関連付けられたジオメトリに対してパッチからフェースが除去されます。バインドされたフェースが実行後のパッチにない場合は、パッチが除去されます。
• fixPatchNames( string palette )()
  • パレット内のパッチのすべてに対し名前を更新します。ディスクリプションの名前が変更されるか、ディスクリプションがバインドされているジオメトリの名前が変更された場合、パッチもその名前を更新する必要があります。
• string nodeClass( string node )()
  • Maya のノードがあれば、XGen オブジェクトの一般的なクラスを返します。ノードが XGen オブジェクトではない場合は、None を返します。
• bool renderable( string node )()
  • オブジェクトがレンダリングできるものであれば、true を返します。これは、レンダリングできないオブジェクトにシェーダを割り当てるようなことを避けるために使用できます。
• string[] findSelectedPatches()
  • 現在の選択リストに関連するすべての XGen パッチを返します。ガイド、パッチ、ディスクリプション、ジオメトリなどのすべてが、関連するパッチに解決されます。
• string[] bakedGroomManagerBake( string pal, string desc )()
  • ベイク処理済みのグルーム マネージャの位置になるまで現在のグルームをベイク処理します。これにより、スタティックなグループが含まれる各ディスクリプションのバインドされたジオメトリに対して XPD ファイルができます。ディスクリプションは残り、ベイク処理済みのグルーム マネージャがアクティブになります。
• setExportAsDelta( bool value, string pal=None )()
  • パレットを全体として書き出すか差分ファイルとして書き出すかをコントロールします。渡された値が true に設定されていれば、パレットに変更があったときにのみ、差分ファイルがパレットに書き込まれます。パレットを渡されていない場合は、シーン内のすべてのパレットが新しい値に設定されます。

Maya MPX API

以下に MPxCommand を示します。これは、XGen API の一部を成し、Maya でのみ利用できます。

• bool xgmGuideGeom -guide string [-numVertices] [-basePoint | -controlPoints] [-lockBasePt]()
  • ガイドについての基本クエリです。
• bool xgmPatchInfo -patch string [-description | -geometry | -faceIds | -rename string]()
  • 基本的なパッチ クエリです。
• bool xgmBakeGuideVertices [-resetPivots]
  • ベイク処理がガイドの中を編集します。すべての微調整が除去されます。