コマンド引数とフラグ

このトピックでは、コマンドの引数とフラグの使用について説明します。

「フラグ」と「コマンド引数」

Maya API マニュアルのコンテキストでは、「フラグ」と「コマンド引数」という用語が特定の意味を持っています。これらの用語の意味を次に説明します。

「フラグ」: フラグは、コマンドの通常の動作のオプションです。各フラグには、ロングネームとショートネームがあります。MEL コマンドで使用する場合は、フラグの前にハイフン(「-」)が付加されます。Python の場合、フラグは、ハイフンのない名前付き関数引数として表示されます。次の例では、「sx」、「sy」、「sz」、および「h」フラグが、各軸のサブディビジョンの数と cmds.polyCube() で作成したキューブの高さを指定しています。
```
import maya.cmds as cmds
cmds.polyCube( sx=10, sy=15, sz=5, h=20 )
```
注:また、単一のフラグは、値のタプル(たとえば、カラーの(R、G、B)値)を受け入れることができます。タプルの各項目は、フラグパラメータと呼ばれます。以下の、複数のフラグパラメータの解析で詳しく説明します。
「コマンド引数」: コマンド引数には、関連付けられた名前がありません。MEL コマンドでコマンド引数を使用する場合は、呼び出しの最後に表示されます。対照的に、Python の言語設計のため、コマンド引数は、maya.cmds 関数呼び出しの最初に表示されます。以下の例は、コマンド引数とフラグの違いを示しています。
```
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 ジョイントチェーンを作成する」を参照してください。

Maya プラグインエントリ/エグジットポイント: 引数構文を登録する

引数またはフラグを処理しないコマンドと比較すると、initializePlugin() エントリポイントは、コマンドの引数構文を含むように修正する必要があります。

mplugin.registerCommand( kPluginCmdName, cmdCreator, syntaxCreator )

特に、MFnPlugin.registerCommand() への呼び出しに 3 番目のパラメータ syntaxCreator を含める必要があります。MFnPlugin.registerCommand() の関数パラメータを次に示します。

コマンド名: コマンド 'myCommandWithFlag' の名前です。これにより、MEL または Python の maya.cmds モジュールを使用してコマンドを実行する方法が決定されます。
コマンド作成関数リファレンス: コマンド cmdCreator のインスタンスを作成する関数へのリファレンスです。
構文作成関数: MSyntax オブジェクト syntaxCreator を返す関数へのリファレンスです。この返された MSyntax オブジェクトは、各フラグの必要なタイプのほか、各フラグのロングネームとショートネームを定義します。フラグのショートネーム(kShortFlagName)は、ハイフンが前に付加された 1 または 2 文字の文字列にする必要があります('-mf')。一般的に、フラグのロングネーム(kLongFlagName)はより説明的であり、ハイフンを前に付加する必要があります('-myFlag')。
```
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 つのセクションを修正する必要があります。

構文作成関数: 構文作成関数では、MSyntax.addFlag()への呼び出しに 3 つの OpenMaya.MSyntax.kDouble パラメータのタプルが必要です。この新しいフラグ構文定義により、このフラグの単一の数値ではなく、3 つの数値のタプルが Maya で認識されます。

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 では、パラメータはタプル形式で渡されません。

引数の解析: parseArguments() のメソッド本体で、MArgParser.flagArgumentInt() への 3 つの個別の呼び出しに対してインデックス 0～2 を使用して、フラグの 3 つのパラメータを解析します。

    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 )

サンプルコマンドプラグイン: 複数のパラメータを持つ 1 つのフラグ

次の Python コードは、指定したフラグで渡される 3 つのパラメータを出力するコマンドを作成します。