このトピックでは、コマンドの引数とフラグの使用について説明します。
Maya API マニュアルのコンテキストでは、「フラグ」と「コマンド引数」という用語が特定の意味を持っています。これらの用語の意味を次に説明します。
import maya.cmds as cmds cmds.polyCube( sx=10, sy=15, sz=5, h=20 )
注: 単一のフラグは、値のタプル(たとえば、カラーの (r,g,b) 値)も受け入れることができます。タプルの各項目は、フラグ パラメータと呼ばれます。**以下の、複数のフラグ パラメータの解析で詳しく説明します。
import maya.cmds as cmds cmds.group( 'circle1', 'sphere1', n='group1' )
ここで、'circle1' および 'sphere1'は、cmds.group() のコマンド引数です。これらは、オブションの「n」フラグの前に配置されます。このフラグを使用して、結果として生じるグループの名前を指定します。
現在選択されている Maya オブジェクトをコマンドの引数として使用することもできます。この場合、コマンド引数とオブジェクトに互換性がなく、コマンドの構文定義で結合できません。**詳細については、MSyntax クラスのマニュアルを参照してください。
以下のプラグイン コードでは、渡されれたフラグに関連付けられている値を出力するコマンドを作成します。MSyntax および MArgParser クラスのマニュアルには、コマンドでフラグ、引数、選択したオブジェクトを使用する方法についての追加情報が含まれています。
Python API 2.0:
# pySampleCommandFlag.py import sys import maya.api.OpenMaya as OpenMaya # ... additional imports here ... kPluginCmdName = 'myCommandWithFlag' kShortFlagName = '-mf' kLongFlagName = '-myFlag' def maya_useNewAPI(): """ The presence of this function tells Maya that the plugin produces, and expects to be passed, objects created using the Maya Python API 2.0. """ pass ########################################################## # Plug-in ########################################################## class MyCommandWithFlagClass( OpenMaya.MPxCommand ): def __init__(self): ''' Constructor. ''' OpenMaya.MPxCommand.__init__(self) def doIt(self, args): ''' Command execution. ''' # We recommend parsing your arguments first. self.parseArguments( args ) # Remove the following 'pass' keyword and replace it with the code you want to run. pass def parseArguments(self, args): ''' The presence of this function is not enforced, but helps separate argument parsing code from other command code. ''' # The following MArgParser object allows you to check if specific flags are set. argData = OpenMaya.MArgParser( self.syntax(), args ) if argData.isFlagSet( kShortFlagName ): # In this case, we print the passed flag's value as an integer. # We use the '0' to index the flag's first and only parameter. flagValue = argData.flagArgumentInt( kShortFlagName, 0 ) print kLongFlagName + ': ' + str( flagValue ) # ... If there are more flags, process them here ... ########################################################## # Plug-in initialization. ########################################################## def cmdCreator(): ''' Create an instance of our command. ''' return MyCommandWithFlagClass() def syntaxCreator(): ''' Defines the argument and flag syntax for this command. ''' syntax = OpenMaya.MSyntax() # In this example, our flag will be expecting a numeric value, denoted by OpenMaya.MSyntax.kDouble. syntax.addFlag( kShortFlagName, kLongFlagName, OpenMaya.MSyntax.kDouble ) # ... Add more flags here ... return syntax def initializePlugin( mobject ): ''' Initialize the plug-in when Maya loads it. ''' mplugin = OpenMaya.MFnPlugin( mobject ) try: mplugin.registerCommand( kPluginCmdName, cmdCreator, syntaxCreator ) except: sys.stderr.write( 'Failed to register command: ' + kPluginCmdName ) def uninitializePlugin( mobject ): ''' Uninitialize the plug-in when Maya un-loads it. ''' mplugin = OpenMaya.MFnPlugin( mobject ) try: mplugin.deregisterCommand( kPluginCmdName ) except: sys.stderr.write( 'Failed to unregister command: ' + kPluginCmdName ) ########################################################## # Sample usage. ########################################################## ''' # Copy the following lines and run them in Maya's Python Script Editor: import maya.cmds as cmds cmds.loadPlugin( 'sampleCommandFlag.py' ) cmds.myCommandWithFlag( myFlag = 4 ) '''
Python API 1.0:
# sampleCommandFlag.py import sys import maya.OpenMayaMPx as OpenMayaMPx import maya.OpenMaya as OpenMaya # ... additional imports here ... kPluginCmdName = 'myCommandWithFlag' kShortFlagName = '-mf' kLongFlagName = '-myFlag' ########################################################## # Plug-in ########################################################## class MyCommandWithFlagClass( OpenMayaMPx.MPxCommand ): def __init__(self): ''' Constructor. ''' OpenMayaMPx.MPxCommand.__init__(self) def doIt(self, args): ''' Command execution. ''' # We recommend parsing your arguments first. self.parseArguments( args ) # Remove the following 'pass' keyword and replace it with the code you want to run. pass def parseArguments(self, args): ''' The presence of this function is not enforced, but helps separate argument parsing code from other command code. ''' # The following MArgParser object allows you to check if specific flags are set. argData = OpenMaya.MArgParser( self.syntax(), args ) if argData.isFlagSet( kShortFlagName ): # In this case, we print the passed flag's value as an integer. # We use the '0' to index the flag's first and only parameter. flagValue = argData.flagArgumentInt( kShortFlagName, 0 ) print kLongFlagName + ': ' + str( flagValue ) # ... If there are more flags, process them here ... ########################################################## # Plug-in initialization. ########################################################## def cmdCreator(): ''' Create an instance of our command. ''' return OpenMayaMPx.asMPxPtr( MyCommandWithFlagClass() ) def syntaxCreator(): ''' Defines the argument and flag syntax for this command. ''' syntax = OpenMaya.MSyntax() # In this example, our flag will be expecting a numeric value, denoted by OpenMaya.MSyntax.kDouble. syntax.addFlag( kShortFlagName, kLongFlagName, OpenMaya.MSyntax.kDouble ) # ... Add more flags here ... return syntax def initializePlugin( mobject ): ''' Initialize the plug-in when Maya loads it. ''' mplugin = OpenMayaMPx.MFnPlugin( mobject ) try: mplugin.registerCommand( kPluginCmdName, cmdCreator, syntaxCreator ) except: sys.stderr.write( 'Failed to register command: ' + kPluginCmdName ) def uninitializePlugin( mobject ): ''' Uninitialize the plug-in when Maya un-loads it. ''' mplugin = OpenMayaMPx.MFnPlugin( mobject ) try: mplugin.deregisterCommand( kPluginCmdName ) except: sys.stderr.write( 'Failed to unregister command: ' + kPluginCmdName ) ########################################################## # Sample usage. ########################################################## ''' # Copy the following lines and run them in Maya's Python Script Editor: import maya.cmds as cmds cmds.loadPlugin( 'sampleCommandFlag.py' ) cmds.myCommandWithFlag( myFlag = 4 ) '''
注: コマンド引数を使用する実用的な例については、「例: IK ジョイント チェーンを作成する」を参照してください。
引数またはフラグを処理しないコマンドと比較すると、initializePlugin() エントリ ポイントは、コマンドの引数構文を含むように修正する必要があります。
mplugin.registerCommand( kPluginCmdName, cmdCreator, syntaxCreator )
特に、MFnPlugin.registerCommand() への呼び出しに 3 番目のパラメータ syntaxCreator を含める必要があります。MFnPlugin.registerCommand() の関数パラメータを次に示します。
``` kShortFlagName = '-mf' kLongFlagName = '-myFlag'
# ...
def syntaxCreator(): ''' Defines the argument and flag syntax for this command. ''' syntax = OpenMaya.MSyntax()
# In this example, our flag will be expecting a numeric value, denoted by OpenMaya.MSyntax.kDouble. syntax.addFlag( kShortFlagName, kLongFlagName, OpenMaya.MSyntax.kDouble ) # ... Add more flags here ... return syntax
```
注: コマンド引数 を追加するには、MSyntax.addArg() 関数を使用します。詳細については、MSyntax クラスのマニュアルを参照してください。
コマンドの doIt() メソッドでは、渡された引数とフラグを解析する専用のコードが必要です。parseArguments() で、MSyntax オブジェクト(self.syntax() から取得)を使用して MArgParser オブジェクトと MArgList オブジェクト (args)をインスタンス化します。MArgParser.isFlagSet() を使用して特定のフラグが存在するかどうかをチェックします。MArgParser.flagArgumentInt() を呼び出すと、特定のフラグに整数として関連付けられている値が抽出されます。
def doIt(self, args): ''' Command execution. ''' # We recommend parsing your arguments first. self.parseArguments( args ) # Remove the following 'pass' keyword and replace it with the code you want to run. pass def parseArguments(self, args): ''' The presence of this function is not enforced, but helps separate argument parsing code from other command code. ''' # The following MArgParser object allows you to check if specific flags are set. argData = OpenMaya.MArgParser( self.syntax(), args ) if argData.isFlagSet( kShortFlagName ): # In this case, we print the passed flag's value as an integer. # We use the '0' to index the flag's first and only parameter. flagValue = argData.flagArgumentInt( kShortFlagName, 0 ) print kLongFlagName + ': ' + str( flagValue ) # ... If there are more flags, process them here ...
注: コマンド引数 を解析するには、MArgParser.commandArgument*() 関数を使用します。詳細については、MArgParser クラスのマニュアルを参照してください。
次の使用事例のように、複数のパラメータ(たとえば、3 次元ベクトル)が含まれているフラグを解析する必要があると仮定します。**
import maya.cmds as cmds cmds.loadPlugin( 'sampleCommandFlagTuple.py' ) cmds.myCommandWithTupleFlag( myTupleFlag = (10, 20, 30) )
これを実現するには、コードの 2 つのセクションを修正する必要があります。
``` def syntaxCreator(): ''' Defines the argument and flag syntax for this command. ''' syntax = OpenMaya.MSyntax()
# In this example, our flag will be expecting three OpenMaya.MSyntax.kDouble parameters. syntax.addFlag( kShortFlagName, kLongFlagName, (OpenMaya.MSyntax.kDouble, OpenMaya.MSyntax.kDouble, OpenMaya.MSyntax.kDouble) ) # ... Add more flags here ... return syntax
```
注: Python API 1.0 では、パラメータはタプル形式で渡されません。
``` def doIt(self, args): ''' Command execution. '''
# We recommend parsing your arguments first. self.parseArguments( args ) # Remove the following 'pass' keyword and replace it with the code you want to run. pass def parseArguments(self, args): ''' The presence of this function is not enforced, but helps separate argument parsing code from other command code. ''' # The following MArgParser object allows you to check if specific flags are set. argData = OpenMaya.MArgParser( self.syntax(), args ) if argData.isFlagSet( kShortFlagName ): # In this case, we print the passed flags's three parameters, indexed from 0 to 2. flagParam0 = argData.flagArgumentInt( kShortFlagName, 0 ) flagParam1 = argData.flagArgumentInt( kShortFlagName, 1 ) flagParam2 = argData.flagArgumentInt( kShortFlagName, 2 ) print kLongFlagName + '[0]: ' + str( flagParam0 ) print kLongFlagName + '[1]: ' + str( flagParam1 ) print kLongFlagName + '[2]: ' + str( flagParam2 )
```
次の Python コードは、指定したフラグで渡される 3 つのパラメータを出力するコマンドを作成します。
Python API 2.0:
# pySampleCommandFlagTuple.py import sys import maya.api.OpenMaya as OpenMaya # ... additional imports here ... kPluginCmdName = 'myCommandWithTupleFlag' kShortFlagName = '-tf' kLongFlagName = '-myTupleFlag' def maya_useNewAPI(): """ The presence of this function tells Maya that the plugin produces, and expects to be passed, objects created using the Maya Python API 2.0. """ pass ########################################################## # Plug-in ########################################################## class MyCommandWithFlagTupleClass( OpenMaya.MPxCommand ): def __init__(self): ''' Constructor. ''' OpenMaya.MPxCommand.__init__(self) def doIt(self, args): ''' Command execution. ''' # We recommend parsing your arguments first. self.parseArguments( args ) # Remove the following 'pass' keyword and replace it with the code you want to run. pass def parseArguments(self, args): ''' The presence of this function is not enforced, but helps separate argument parsing code from other command code. ''' # The following MArgParser object allows you to check if specific flags are set. argData = OpenMaya.MArgParser( self.syntax(), args ) if argData.isFlagSet( kShortFlagName ): # In this case, we print the passed flags's three parameters, indexed from 0 to 2. flagParam0 = argData.flagArgumentInt( kShortFlagName, 0 ) flagParam1 = argData.flagArgumentInt( kShortFlagName, 1 ) flagParam2 = argData.flagArgumentInt( kShortFlagName, 2 ) print kLongFlagName + '[0]: ' + str( flagParam0 ) print kLongFlagName + '[1]: ' + str( flagParam1 ) print kLongFlagName + '[2]: ' + str( flagParam2 ) # ... If there are more flags, process them here ... ########################################################## # Plug-in initialization. ########################################################## def cmdCreator(): ''' Create an instance of our command. ''' return MyCommandWithFlagTupleClass() def syntaxCreator(): ''' Defines the argument and flag syntax for this command. ''' syntax = OpenMaya.MSyntax() # In this example, our flag will be expecting three OpenMaya.MSyntax.kDouble parameters. syntax.addFlag( kShortFlagName, kLongFlagName, (OpenMaya.MSyntax.kDouble, OpenMaya.MSyntax.kDouble, OpenMaya.MSyntax.kDouble) ) # ... Add more flags here ... return syntax def initializePlugin( mobject ): ''' Initialize the plug-in when Maya loads it. ''' mplugin = OpenMaya.MFnPlugin( mobject ) try: mplugin.registerCommand( kPluginCmdName, cmdCreator, syntaxCreator ) except: sys.stderr.write( 'Failed to register command: ' + kPluginCmdName ) def uninitializePlugin( mobject ): ''' Uninitialize the plug-in when Maya un-loads it. ''' mplugin = OpenMaya.MFnPlugin( mobject ) try: mplugin.deregisterCommand( kPluginCmdName ) except: sys.stderr.write( 'Failed to unregister command: ' + kPluginCmdName ) ########################################################## # Sample usage. ########################################################## ''' # Copy the following lines and run them in Maya's Python Script Editor: import maya.cmds as cmds cmds.loadPlugin( 'sampleCommandFlagTuple.py' ) cmds.myCommandWithTupleFlag( myTupleFlag = (10, 20, 30) ) '''
Python API 1.0:
# sampleCommandFlagTuple.py import sys import maya.OpenMayaMPx as OpenMayaMPx import maya.OpenMaya as OpenMaya # ... additional imports here ... kPluginCmdName = 'myCommandWithTupleFlag' kShortFlagName = '-tf' kLongFlagName = '-myTupleFlag' ########################################################## # Plug-in ########################################################## class MyCommandWithFlagTupleClass( OpenMayaMPx.MPxCommand ): def __init__(self): ''' Constructor. ''' OpenMayaMPx.MPxCommand.__init__(self) def doIt(self, args): ''' Command execution. ''' # We recommend parsing your arguments first. self.parseArguments( args ) # Remove the following 'pass' keyword and replace it with the code you want to run. pass def parseArguments(self, args): ''' The presence of this function is not enforced, but helps separate argument parsing code from other command code. ''' # The following MArgParser object allows you to check if specific flags are set. argData = OpenMaya.MArgParser( self.syntax(), args ) if argData.isFlagSet( kShortFlagName ): # In this case, we print the passed flags's three parameters, indexed from 0 to 2. flagParam0 = argData.flagArgumentInt( kShortFlagName, 0 ) flagParam1 = argData.flagArgumentInt( kShortFlagName, 1 ) flagParam2 = argData.flagArgumentInt( kShortFlagName, 2 ) print kLongFlagName + '[0]: ' + str( flagParam0 ) print kLongFlagName + '[1]: ' + str( flagParam1 ) print kLongFlagName + '[2]: ' + str( flagParam2 ) # ... If there are more flags, process them here ... ########################################################## # Plug-in initialization. ########################################################## def cmdCreator(): ''' Create an instance of our command. ''' return OpenMayaMPx.asMPxPtr( MyCommandWithFlagTupleClass() ) def syntaxCreator(): ''' Defines the argument and flag syntax for this command. ''' syntax = OpenMaya.MSyntax() # In this example, our flag will be expecting three OpenMaya.MSyntax.kDouble parameters. syntax.addFlag( kShortFlagName, kLongFlagName, OpenMaya.MSyntax.kDouble, OpenMaya.MSyntax.kDouble, OpenMaya.MSyntax.kDouble ) # ... Add more flags here ... return syntax def initializePlugin( mobject ): ''' Initialize the plug-in when Maya loads it. ''' mplugin = OpenMayaMPx.MFnPlugin( mobject ) try: mplugin.registerCommand( kPluginCmdName, cmdCreator, syntaxCreator ) except: sys.stderr.write( 'Failed to register command: ' + kPluginCmdName ) def uninitializePlugin( mobject ): ''' Uninitialize the plug-in when Maya un-loads it. ''' mplugin = OpenMayaMPx.MFnPlugin( mobject ) try: mplugin.deregisterCommand( kPluginCmdName ) except: sys.stderr.write( 'Failed to unregister command: ' + kPluginCmdName ) ########################################################## # Sample usage. ########################################################## ''' # Copy the following lines and run them in Maya's Python Script Editor: import maya.cmds as cmds cmds.loadPlugin( 'sampleCommandFlagTuple.py' ) cmds.myCommandWithTupleFlag( myTupleFlag = (10, 20, 30) ) '''