Maya Python API を使用する

読み込み

Python は import キーワードを使用して、機能をモジュールからスクリプトにインクルードします。例:

import maya.OpenMaya as OpenMaya
import maya.OpenMayaMPx as OpenMayaMPx
import sys

スクリプト プラグインが複数のファイルに分割されていてもかまいません。import コマンドは、2 次ファイルの機能をスクリプト プラグインにロードするために使用します。

import polyModifier

すべての 2 次スクリプトは、スクリプト プラグインと同じディレクトリに配置する必要があります。

スクリプト プラグインを初期化する

スクリプト プラグインがロードされると、Maya は定義内の initializePlugin() 関数を検索します。この関数にすべてのプロキシ ノードが登録されます。

# Initialize the script plug-in
def initializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject)
    try:
        mplugin.registerCommand( kPluginCmdName, cmdCreator )
    except:
        sys.stderr.write( "Failed to register command: %s\n" % kPluginCmdName )
        raise

initializePlugin() 関数が見つからない場合、スクリプト プラグインのロードは失敗します。また、ロード時、Maya は uninitializePlugin() 関数も検索します。これが見つからない場合、スクリプト プラグインのロードは失敗します。

スクリプト プラグインの初期化を解除する

Maya では、プラグインのアンロード試行時にあらかじめ見つけておいた uninitializePlugin() 関数がコールされ、プラグインのリソースがアンロードされます。

def uninitializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject)
    try:
        mplugin.deregisterCommand( kPluginCmdName )
    except:
        sys.stderr.write( "Failed to unregister command: %s\n" % kPluginCmdName )
        raise

クリエータ関数

クリエータ関数は、派生したバージョンのプロキシ クラスを Maya に返すために使用します。バーチャル メソッドが Maya からコールする派生クラスに実装されます。以下は、クラス定義とクリエータ関数の例です。

class scriptedCommand(OpenMayaMPx.MPxCommand):
    # ...
def cmdCreator():
    return OpenMayaMPx.asMPxPtr( scriptedCommand() )

新しく作成したプロキシ オブジェクト上で OpenMayaMPx.asMPxPtr() をコールすることが非常に重要です。このコールにより、オブジェクトの所有権が Python から Maya に移行します。このコールを行わなければ、Python でこのオブジェクトの参照が解除され破棄されることがあるため、プログラム エラーが発生します。これにより、Maya にダングリング ポインタが残ります。

クラスの実装

プロキシ クラスの実装には、Maya Python API オブジェクトからの派生が必要です。

class scriptedCommand(OpenMayaMPx.MPxCommand):
    def __init__(self):
        OpenMayaMPx.MPxCommand.__init__(self)
    def doIt(self,argList):
        print "Hello World!"

scriptedCommand クラスは、OpenMayaMPx.MPxCommand から派生します。コンストラクタまたは __init__ メソッドは、親クラスの __init__ メソッドをコールする必要があります。すべてのクラス メソッドには、1 番目のパラメータとして self が必要です。この後、通常の引数リストが続きます。このコマンドの doIt() メソッドは「Hello World!」と出力します。

初期化関数

初期化関数は、MPxNode クラスを使用して新しいプロキシ ノードを定義するスクリプト プラグイン内で使用します。次は、その出力がサイン関数である単純なスクリプト プラグイン ノードを作成する方法を示すサンプルです。

import math, sys
import maya.OpenMaya as OpenMaya
import maya.OpenMayaMPx as OpenMayaMPx
kPluginNodeTypeName = "spSineNode"
sineNodeId = OpenMaya.MTypeId(0x8700)

# Node definition
class sineNode(OpenMayaMPx.MPxNode):
    # class variables
    input = OpenMaya.MObject()
    output = OpenMaya.MObject()
    
    def __init__(self):
        OpenMayaMPx.MPxNode.__init__(self)
        
    def compute(self,plug,dataBlock):
        if ( plug == sineNode.output ):
            dataHandle = dataBlock.inputValue( sineNode.input )
            
            inputFloat = dataHandle.asFloat()
            result = math.sin( inputFloat ) * 10.0
            outputHandle = dataBlock.outputValue( sineNode.output )
            outputHandle.setFloat( result )
            dataBlock.setClean( plug )
# creator
def nodeCreator():
    return OpenMayaMPx.asMPxPtr( sineNode() )
    
# initializer
def nodeInitializer():
    # input
    nAttr = OpenMaya.MFnNumericAttribute()
    sineNode.input = nAttr.create( "input", "in", OpenMaya.MFnNumericData.kFloat, 0.0 )
    nAttr.setStorable(1)
    # output
    nAttr = OpenMaya.MFnNumericAttribute()
    sineNode.output = nAttr.create( "output", "out", OpenMaya.MFnNumericData.kFloat, 0.0 )
    nAttr.setStorable(1)
    nAttr.setWritable(1)
    # add attributes
    sineNode.addAttribute( sineNode.input )
    sineNode.addAttribute( sineNode.output )
    sineNode.attributeAffects( sineNode.input, sineNode.output )
    
# initialize the script plug-in
def initializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject)
    try:
        mplugin.registerNode( kPluginNodeTypeName, sineNodeId, nodeCreator, nodeInitializer )
    except:
        sys.stderr.write( "Failed to register node: %s" % kPluginNodeTypeName )
        raise
        
# uninitialize the script plug-in
def uninitializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject)
    try:
        mplugin.deregisterNode( sineNodeId )
    except:
        sys.stderr.write( "Failed to register node: %s" % kPluginNodeTypeName )
        raise

nodeInitializer() 関数は、initializePlugin() 関数内で registerNode() に渡されます。プラグインのロード時、Maya では nodeInitializer() 関数がコールされてノードのアトリビュートが作成されます。

エラー条件

Maya Python APIでは、スクリプトの状態の照会と設定に Python の例外を使用します。ほとんとのケースでは、あるメソッドに戻り値があるとクラスのマニュアルに示されていても、例外が使用されます。例外が発生しうる状況にはいろいろあります。

1. コールが失敗し、失敗の状態を保持する必要がある場合。

   def uninitializePlugin(mobject):
       mplugin = OpenMayaMPx.MFnPlugin(mobject)
       try:
           mplugin.deregisterNode( sineNodeId )
       except:
           sys.stderr.write( "Failed to deregister node: %s" % kPluginNodeTypeName )
           raise
   

   この例では、deregisterNode() コールが失敗した場合、uninitializePlugin() コールは Maya に例外を返してプラグインのアンロードが失敗します。

2. コールが失敗し、失敗の状態をクリアする必要がある場合。

   このコードを修正してエラーをキャッチし、deregisterNode() コールが失敗した場合でもプラグインのアンロードを許可することができます。

   def uninitializePlugin(mobject):
       mplugin = OpenMayaMPx.MFnPlugin(mobject)
       try:
           mplugin.deregisterNode( sineNodeId )
       except:
           sys.stderr.write( "Failed to deregister node: %s" % kPluginNodeTypeName )
           pass
   

   唯一の違いは、raise キーワードが pass に変更されたことです。この技法は、正しくないオブジェクトを審査した場合に失敗するイテレータ コードを作成する場合に便利です。

   3. 不明なパラメータ戻り値。

   Maya Python API では、不明なパラメータ戻り値を使用してメソッドが特定のケースを処理できないことを示します。この操作を処理するかどうかは、コール元が決定します。このようなメソッドのひとつに MPxNode::compute() があります。この状況では、Python コードは OpenMaya.kUnknownParameter を返します。

例外と MStatus

前のセクションで説明したとおり、Maya Python API では、ステータス情報をやり取りするために、MStatus の値ではなく例外が使用されます。C++ ドキュメントから API メソッドの Python 的な動作を推測する場合、下記のルールが適用されます。

C++ API メソッドが MStatus 値を返す方法には、メソッドの返り値として返す方法と、

MStatus someMethod(Type arg1, Type arg2, ...) 

パラメータ リストの MStatus 変数(通常、最後のパラメータ)へのオプション ポインタとして返す方法の 2 通りがあります。

Type someMethod(Type arg1, Type arg2, ..., MStatus* ReturnStatus = NULL) 

クラスでスライスをサポートする

すべての番号配列(MIntA ray、MUintArray、MUint64Array、MFloatArray、および MDoubleArray)は Python スタイルのスライシングをサポート。 たとえば、次のようになります。

import maya.OpenMaya as OpenMaya 
array = OpenMaya.MUintArray() 
for i in range(0,9):
   array.append( i )
array[2:8:2]

# Result:[2, 4, 6] #

MPx クラスのスタティック MObject にアクセスする

プロキシ クラスは、開発者に対し、使用されているノードについての標準的な情報を提供します。これには、ノードの定義に使用するアトリビュート オブジェクトが含まれます。Maya Python API でスタティック クラス MObject にアクセスするためには、類似のコードを使用できます。

envelope = OpenMayaMPx.cvar.MPxDeformerNode_envelope

このコール後、エンベロープは MPxDeformerNode::envelope の MObject になります。

メッセージ

Maya Python API では、メッセージ クラスをサポートしています。Python の関数が、コールバック用に渡されます。この関数は、コールバック メッセージが必要とするのとちょうど同じ数のパラメータを持つ必要があります。そうでない場合、メッセージ起動時に例外が発生し、コンソールに情報が書き出されます。ほとんどのメッセージと一緒に、Python オブジェクトの形式のクライアント データを渡すことができます。次はメッセージのサンプルです。

# Message callback
def dagParentAddedCallback( child, parent, clientData ):
    print "dagParentAddedCallback..."
    print "\tchild %s" % child.fullPathName()
    print "\tparent %s" % parent.fullPathName()
    print "\tclient data %s" % clientData

# Create the mesage
def createParentAddedCallback(stringData):
    try:
        id = OpenMaya.MDagMessage.addParentAddedCallback( dagParentAddedCallback, stringData )
    except:
        sys.stderr.write( "Failed to install dag parent added callback\n" )
        messageIdSet = False
    else:
        messageIdSet = True
    return id
# Call the message creator
messageId = createParentAddedCallback( "_noData_" )

割り当てを使用する代わりにパラメータ値を修正する

Python では、割り当てを使用する代わりにパラメータを修正するほうが適切です。 次のコードには割り当てが含まれており、その場合にどのようにエラーが発生しうるかを示します。

import maya.OpenMaya as OpenMaya 
def vectorTest(v): 
    lv = OpenMaya.MVector(1,5,9) 
    v = lv 
    print "%g %g %g" % (v.x,v.y,v.z) 
v = OpenMaya.MVector() 
vectorTest(v) 
print "%g %g %g" % (v.x,v.y,v.z)

2 番目の print コマンドは(0,0,0)を出力します。Python で、パラメータ値を修正するかコードを作成して、新しい値が返されるようにします。次のように vectorTest() 関数を書き換えます。

def vectorTest(v): 
    lv = OpenMaya.MVector(1,5,9) 
    v.x = lv.x
    v.y = lv.y
    v.z = lv.z
    print "%g %g %g" % (v.x,v.y,v.z) 

基本型へのリファレンス

Maya Python API には、int&、char&、float& など、基本型へのリファレンスとなる値またはパラメータを返すコールがたくさんあります。Maya Python API では、すべてのリファレンスはポインタとして扱われます。結果として、これらの項目の値を作成、設定、アクセスするには、特別なコールが必要になります。

OpenMaya.py モジュールにあるMScriptUtil というユーティリティ クラスは、これらのタイプのパラメータで動作して値を返す手段を提供します。このクラスでは、データを作成してからそのデータへのポインタを取得してリファレンスを必要とするクラス メソッドに情報を渡すことができます。API Reference マニュアルの MScriptUtil を参照してください。

MScriptUtil の使用法については、以下の例を参考にしてください。MFnLattice.getDivisions() へのコールから x、y、z の値を取得する方法を示します。

import maya.OpenMaya as OpenMaya
import maya.OpenMayaAnim as Anim
xutil = OpenMaya.MScriptUtil()
xutil.createFromInt(0)
xptr = xutil.asUintPtr()
yutil = OpenMaya.MScriptUtil()
yutil.createFromInt(0)
yptr = yutil.asUintPtr()
zutil = OpenMaya.MScriptUtil()
zutil.createFromInt(0)
zptr = zutil.asUintPtr()
it = OpenMaya.MItDependencyNodes(OpenMaya.MFn.kFFD)
while not it.isDone():
    latDefFn = Anim.MFnLatticeDeformer( it.thisNode() )
    latFn = Anim.MFnLattice( latDefFn.deformLattice() )
    latFn.getDivisions(xptr, yptr, zptr)
    x = xutil.getUint(xptr)
    y = yutil.getUint(yptr)
    z = zutil.getUint(zptr)
    doSomethingUseful(x, y, z)
    it.next()

getUint() は MScriptUtil のスタティック メソッドであるため、クラスから直接コールしても最終値を取得できます。たとえば、次のようになります。

x = OpenMaya.MScriptUtil.getUint(xptr)

列挙型へのリファレンスは short int へのリファレンスとして扱う必要があります。

フラグ付きコマンド

フラグ付きコマンドは、MSyntax オブジェクトを使用して構文を指定し、MArgParser クラスまたは MArgDatabase クラスを使用してフラグを解析する必要があります。そうしないと、Python からコマンドを使用するときにフラグにアクセスできません。これは、Python と C++ のどちらで記述されたかに関係なく同じです。次は、フラグ付きコマンドを実装したプラグインの記述例です。

import maya.OpenMaya as OpenMaya
import maya.OpenMayaMPx as OpenMayaMPx
import sys, math
kPluginCmdName="spHelix"
kPitchFlag = "-p"
kPitchLongFlag = "-pitch"
kRadiusFlag = "-r"
kRadiusLongFlag = "-radius"

# command
class scriptedCommand(OpenMayaMPx.MPxCommand):
    def __init__(self):
        OpenMayaMPx.MPxCommand.__init__(self)
    
    def doIt(self, args):
        deg = 3
        ncvs = 20
        spans = ncvs - deg
        nknots = spans+2*deg-1
        radius = 4.0
        pitch = 0.5
        
        # Parse the arguments.
        argData = OpenMaya.MArgDatabase(self.syntax(), args)
        if argData.isFlagSet(kPitchFlag):
            pitch = argData.flagArgumentDouble(kPitchFlag, 0)
        if argData.isFlagSet(kRadiusFlag):
            radius = argData.flagArgumentDouble(kRadiusFlag, 0)
        controlVertices = OpenMaya.MPointArray()
        knotSequences = OpenMaya.MDoubleArray()
        
        # Set up cvs and knots for the helix
        for i in range(0, ncvs):
            controlVertices.append( OpenMaya.MPoint( radius * math.cos(i),
                pitch * i, radius * math.sin(i) ) )
        for i in range(0, nknots):
            knotSequences.append( i )
        
        # Now create the curve
        curveFn = OpenMaya.MFnNurbsCurve()
        
        nullObj = OpenMaya.MObject()
        try:
            # This plugin normally creates the curve by passing in the
            # cv's. A function to create curves by passing in the ep's
            # has been added. Set this to False to get that behaviour.
            if True:
                curveFn.create( controlVertices, knotSequences, deg, OpenMaya.MFnNurbsCurve.kOpen, 0, 0, nullObj )
            else:
                curveFn.createWithEditPoints(controlVertices, 3, OpenMaya.MFnNurbsCurve.kOpen, False, False, False)
        except:
            sys.stderr.write( "Error creating curve.\n" )
            raise
# Creator
def cmdCreator():
    # Create the command
    return OpenMayaMPx.asMPxPtr( scriptedCommand() )

# Syntax creator
def syntaxCreator():
    syntax = OpenMaya.MSyntax()
    syntax.addFlag(kPitchFlag, kPitchLongFlag, OpenMaya.MSyntax.kDouble)
    syntax.addFlag(kRadiusFlag, kRadiusLongFlag, OpenMaya.MSyntax.kDouble)
    return syntax

# Initialize the script plug-in
def initializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject, "Autodesk", "1.0", "Any")
    try:
        mplugin.registerCommand( kPluginCmdName, cmdCreator, syntaxCreator )
    except:
        sys.stderr.write( "Failed to register command: %s\n" % kPluginCmdName )
        raise
        
# Uninitialize the script plug-in
def uninitializePlugin(mobject):
    mplugin = OpenMayaMPx.MFnPlugin(mobject)
    try:
        mplugin.deregisterCommand( kPluginCmdName )
    except:
        sys.stderr.write( "Failed to unregister command: %s\n" % kPluginCmdName )
        raise

このサンプルでは、クラスの doIt() メソッドに、シンタックス クリエータ関数とパース処理が含まれます。

保護されたメソッド

Maya Python API には、メソッドが所属するクラスからのみコールされるメソッドがいくつか含まれています。Maya では、この保護がメソッドに適用されることを示すため、Python の指定に従って _ を付加しています。MPxNode クラスに、このようなメソッドのサンプルがいくつかあります。

_forceCache()
_setMPSafe()

Maya Python API 内では、保護されたメソッドの使用の要件を守ってください。

MPx ベースのオブジェクトから派生したオブジェクトを取得する

API メソッドによっては、カスタム オブジェクトを派生クラスのインスタンスではなく、MPx ベース クラスのインスタンスとして返します。たとえば、MPxContext。_newToolCommand() はカスタム ツール コマンドを MPxToolCommand オブジェクトとして、MPxSurfaceShapeUI.surfaceShape() はカスタム サーフェス シェイプを MPxSurfaceShape オブジェクトとして返します。これらのベース インスタンスはオリジナルの派生インスタンスと同じ内部 Maya オブジェクトを参照しますが、派生インスタンスに設定されたメンバー変数の値をまったく保持しない個別の Python オブジェクトです。このため、返されたオブジェクトのメンバー変数をコールまたはアクセスすると、不正な結果が生じることがあります。

この問題は、OpenMayaMPx.asHashable() 関数のプロパティを利用して解決できます。OpenMayaMPx.asHashable() は MPx オブジェクトを取り、Maya の基本オブジェクトを一意に識別するハッシュ値を返します。これは、オブジェクトが MPx ベース クラスのインスタンスであるか派生クラスのインスタンスであるかには関係ありません。両方が Maya の基本オブジェクトを参照していれば、同じハッシュ値を返します。これにより、ベース インスタンスを該当する派生インスタンスに翻訳できる辞書を設定することができます。

これにはまず、空の辞書をクラスに追加します。

class MoveToolCmd(OpenMayaMPx.MPxToolCommand):
    kTrackingDictionary = {}

このクラスの __init__ メソッドで、辞書にエントリを追加し、新しいオブジェクトのハッシュ値をオブジェクト自体にマッピングします。

def __init__(self): 
    OpenMayaMPx.MPxToolCommand.__init__(self)
    MoveToolCmd.kTrackingDictionary[OpenMayaMPx.asHashable(self)] = self 

クラスの __del__ メソッドで、ディクショナリから削除されたオブジェクトを除去します。

def __del__(self): 
    del MoveToolCmd.kTrackingDictionary[OpenMayaMPx.asHashable(self)] 

これでトラッキング ディクショナリができたので、これを利用して該当するベース オブジェクトから派生したオブジェクトを読み出すことができます。

class MoveContext(OpenMayaMPx.MPxSelectionContext): 
    ... 
    
    def doPress(self, event): 

        # Create an instance of the move tool command. 
        baseCmd = self._newToolCommand() 
        derivedCmd = MoveToolCmd.kTrackingDictionary.get( 
                        OpenMayaMPx.asHashable(baseCmd), None 
                     ) 

        # Call its methods.
        derivedCmd.setVector(0.0, 0.0, 0.0) 

カスタム ノード タイプ(MPxNode、MPxSurfaceShape など)の定義には、追加作業が必要です。Maya でファイルを開く、または新規ファイルの操作を行うと、各ノードで __del__ method を実行しなければシーンが破損します。つまり、これらのノードのエントリはトラッキング ディクショナリからは削除されないということです。これを回避するには、initializePlugin メソッドでコールバックをセットアップし、ファイルのオープンと新規ファイルの作成のトラッキング ディクショナリをクリアする必要があります。

fileOpenCB = 0
fileNewCB = 0

def clearTrackingDictionaries(unused):
    MyNode.kTrackingDictionary = {} 
    MySurfaceShape.kTrackingDictionary = {}

def initializePlugin(plugin): 
    ... 
    fileOpenCB = OpenMaya.MSceneMessage.addCallback(
                     OpenMaya.MSceneMessage.kBeforeOpen, 
                     clearTrackingDictionaries 
                 )
    fileNewCB  = OpenMaya.MSceneMessage.addCallback(
                     OpenMaya.MSceneMessage.kBeforeNew, 
                     clearTrackingDictionaries 
                 )
    ...
}

def uninitializePlugin(plugin): 
    ... 
    if fileOpenCB != 0:
        OpenMaya.MSceneMessage.removeCallback(fileOpenCB) 
        fileOpenCB = 0 

    if fileNewCB != 0: 
        OpenMaya.MSceneMessage.removeCallback(fileNewCB)
        fileNewCB = 0

オペレーティング システム タイプ

Maya Python API の一部のメソッドでは、<iosteam> オペレーティング システム タイプが必要です。これは Python に含まれていないので、このようなタイプのオブジェクトの作成と使用を行うための MStreamUtils クラスが使用可能です。このクラスの使用法を示すサンプルについては、Developer Kit を参照してください。

親クラスへのコール

MPx プロキシ クラスを作成する場合、スクリプトで親クラスへのコールが必要になることがあります。これは次のような表記法で行います。

matrix = OpenMayaMPx.MPxTransformationMatrix.asMatrix(self)

Enum 値

Enum 値は、次のように moduleName.className.value 表記法でアクセスすることができます。

OpenMaya.MSyntax.kDouble

OpenGL を使用する

サポートするすべてのプラットフォームで、OpenGL 機能をスクリプトで使用するためのラッパ(wrapper)クラス MGLFunctionTable を提供しています。このクラスへのリファレンスを取得するには、次のコードを使用します。

glRenderer = OpenMayaRender.MHardwareRenderer.theRenderer()
glFT = glRenderer.glFunctionTable()

ネストされたイテレータとガベージ コレクション

ネストされたイテレータを記述する場合、通常、外側のループで現在選択されている項目は、内側のループに渡されます。たとえば、MItSelectionList で現在選択されている項目は MItSurfaceCV イテレータに渡されます。内側のイテレータに、無効になった情報が保持されている場合には、ガベージ コレクションの問題が発生する可能性があります。この問題を回避するには、内側のループが完了したら、内側のイテレータをなし(None)にリセットします。この結果、外側のループを継続する前に、内側のイテレータの情報がリリースされます。現在選択されている項目をリビルドまたは更新している場合にはこれが重要です。