Importing

Python uses the import keyword to include functionality from a module into a script. For example:

import maya.OpenMaya as OpenMaya

import maya.OpenMayaMPx as OpenMayaMPx

import sys

It is possible for a scripted plug-in to be split among several files. The import command is used to load the functionality of the secondary file into the scripted plug-in.

import polyModifier

Any secondary scripts must be located in the same directory as the scripted plug-in.

Scripted plug-in initialization

When a scripted plug-in is loaded, Maya searches for an initializePlugin() function in its definition. Within this function, all proxy nodes are registered:

# 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

If the initializePlugin() function is not found, the scripted plug-in fails to load. In addition, during the load, Maya searches for an uninitializePlugin() function. If this is not found, then the scripted plug-in fails to load.

Scripted plug-in uninitialization

When Maya is attempting to unload the plug-in, the previously found uninitializePlugin() function is called to unload the resources of the 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

Creator functions

Creator functions are used to return a derived version of a proxy class to Maya. Virtual methods are implemented on the derived class which are called from Maya. An example of a class definition and a creator function is:

class scriptedCommand(OpenMayaMPx.MPxCommand):

	# ...

def cmdCreator():

	return OpenMayaMPx.asMPxPtr( scriptedCommand() )

It is very important to call the OpenMayaMPx.asMPxPtr() on the newly created proxy object. This call transfers ownership of the object from Python to Maya. Program errors will occur if you do not make this call since Python can unreference this object and destroy it. This will leave a dangling pointer in Maya.

Class implementation

Implementing a proxy class requires deriving from the Maya Python API object.

class scriptedCommand(OpenMayaMPx.MPxCommand):

	def __init__(self):

		OpenMayaMPx.MPxCommand.__init__(self)

	def doIt(self,argList):

		print "Hello World!"

The scriptedCommand class is derived from OpenMayaMPx.MPxCommand. The constructor or __init__ method must call the parent class __init__ method. All class methods require self as the first parameter, followed by the normal argument list. This command’s doIt() method simply prints out “Hello World!”.

Initialization Functions

Initialization functions are used within scripted plug-ins that define new proxy nodes using the MPxNode class. The following is an example that demonstrates how to create a simple scripted plug-in node, the output of which is the sine function.

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

The nodeInitializer() function is passed to registerNode() in the initializePlugin() function. As the plug-in loads, Maya calls the nodeInitializer() function to create the attributes of the node.

Error Conditions

The Maya Python API uses Python exceptions for querying and setting error states in script. In most cases, exceptions are used even though the class documentation indicates that a method has a return value. There are many situations where an exception can occur:

1. A call fails and the failure state needs to be preserved:

def uninitializePlugin(mobject):

	mplugin = OpenMayaMPx.MFnPlugin(mobject)

	try:

		mplugin.deregisterNode( sineNodeId )

	except:

		sys.stderr.write( "Failed to deregister node: %s" % kPluginNodeTypeName )

		raise

In this example, if the deregisterNode() call failed, the uninitializePlugin() call passes the exception back to Maya and the plug-in fails to unload.

1. A call fails and the failure state needs to be cleared:

This code can be modified to catch the error and still allow the plug-in to unload if the deregisterNode() call fails:

def uninitializePlugin(mobject):

	mplugin = OpenMayaMPx.MFnPlugin(mobject)

	try:

		mplugin.deregisterNode( sineNodeId )

	except:

		sys.stderr.write( "Failed to deregister node: %s" % kPluginNodeTypeName )

		pass

The only change being that the raise keyword has been changed to pass. This technique is useful for writing iterator code that may fail if incorrect objects are being examined.

3. Unknown parameter return value

In the Maya Python API, an unknown parameter return value is used to indicate that a method cannot handle a specific case and it is up to the caller to take care of the operation. One such method is MPxNode::compute(). In this situation, the Python code would return OpenMaya.kUnknownParameter.

Exceptions versus MStatus

As noted in the previous section, the Maya Python API uses exceptions to communicate status information rather than MStatus values. When trying to divine the Pythonic behavior of an API method from its C++ documentation, the rules below hold.

There are two ways in which C++ API methods can return MStatus values, either as the method's return value:

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

or through an optional pointer to an MStatus variable in its parameter list, usually as the final parameter:

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

Classes support slicing

All of the number arrays (MIntArray, MUintArray, MUint64Array, MFloatArray, and MDoubleArray) support Python-style slicing. For example:

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] #

Accessing static MObjects of an MPx class

The proxy classes provide some standard information to a developer about the node that is being used. This includes attribute objects that are used to define the node. To access a static class MObject in the Maya Python API, similar code can be used:

envelope = OpenMayaMPx.cvar.MPxDeformerNode_envelope

After making this call, the envelope will be an MObject for MPxDeformerNode::envelope.

Messages

Message classes are supported in the Maya Python API. A Python function is passed for the callback. This function must have the exact number of parameters required by the callback message. If it does not, an exception will occur when the message is invoked and information will be written to the console. Client data in the form of a python object can also be passed with most messages. The following is an example of a message:

# 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_" )

Modify Parameter Values Instead of Using an Assignment

In Python, it is best to modify a parameter rather than use an assignment. The code below contains an assignment and demonstrates how an error can occur:

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)

The second print command will emit all zeroes. In Python, either modify the parameter value or write the code so that a new value is returned. Rewrite the vectorTest() function as follows:

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) 

References to Basic Types

The Maya Python API contains many calls in which return values or parameters are references to basic types such as: int&, char&, float& etc. In the Maya Python API, all references are treated as pointers. As a result, special calls are required to create, set and access the values of these items.

A utility class called MScriptUtil that exists in the OpenMaya.py module provides methods for working with these type of parameters and return values. This class allows for creating data and then acquiring a pointer to the data so that information can be passed to class methods requiring references. See MScriptUtil for more information .

The following example should help to clarify the usage of MScriptUtil. It shows how to get the x, y and z values from a call to MFnLattice.getDivisions():

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(om.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()

Since getUint() is a static method of MScriptUtil, an alternative way of retrieving the final values is to call it directly from the class. For example:

x = OpenMaya.MScriptUtil.getUint(xptr)

Commands with Arguments

Commands with arguments must use the MSyntax and MArgParser classes within a scripted MPxCommand. See the following code for an example:

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

This example includes the syntax creator function along with parsing operations in the doIt() method of the class.

Protected methods

The Maya Python API contains several methods that should only be called from the class the method belongs to. We follow the Python designation of using an _ as the first letter of the method name to indicate that protection applies to this method. Several examples of these methods exist in the MPxNode class:

_forceCache()

_setMPSafe()

Please respect the method usage requirements of protected methods in the Maya Python API.

Need self but only API object is available

When implementing a proxy class in Python, it is natural to define methods within the Python class for handling the getting and setting of state. For example, you wish to maintain a vector as a class variable. Within the Maya Python API, there are methods that are creators of classes that can exist outside of the class. Often, these methods return a pointer value. In the Maya Python API, these pointer values are not the same as the self of a Python class. As a result, there is no straight forward way to access the class variables defined on self. A workaround using a dictionary and a special function OpenMayaMPx.asHashable() makes this possible.

Follow these steps:

1. Declare a dictionary object.

kTrackingDictionary = {}

1. In the initialization method of the object of interest, use the OpenMayaMPx.asHashable() method to store self in the dictionary.

	def __init__(self):

		OpenMayaMPx.MPxToolCommand.__init__(self)

		self.setCommandString(kPluginCmdName)

		self.__delta = OpenMaya.MVector()

		kTrackingDictionary[OpenMayaMPx.asHashable(self)] = self

1. Retrieve self from the dictionary using the pointer.

# Code is in a different class

# Pointer is returned

newCmd = self._newToolCommand()

# Use pointer to get to self of the command

self.__cmd = kTrackingDictionary.get(OpenMayaMPx.asHashable(newCmd), None)

# Set the class variable

self.__cmd.setVector(0.0, 0.0, 0.0)

1. Clean up the tracking dictionary.

	def __del__(self):

		del kTrackingDictionary[OpenMayaMPx.asHashable(self)]

For examples that demonstrate these principles, see the Development Kit.

Operating System Types

There are some methods in the Maya Python API that require <iosteam> operating system types. As these are not included in Python, a MStreamUtils class is available for creating and using these type of objects. Please check the Development kit for examples on how to use this class.

Calling into the Parent class

Often when writing an MPx proxy class, the scripts will require calling into the parent class. This is done using notation such as the following:

matrix = OpenMayaMPx.MPxTransformationMatrix.asMatrix(self)

Enum values

Enum values are accessed using a moduleName.className.value notation such as:

OpenMaya.MSyntax.kDouble

Using OpenGL

We have provided a wrapper class MGLFunctionTable for using OpenGL functionality in script on all of our support platforms. To acquire a reference to this class use the following code:

glRenderer = OpenMayaRender.MHardwareRenderer.theRenderer()

glFT = glRenderer.glFunctionTable()

Nested iterators and Garbage Collection

When writing nested iterators, it is normal to have the current item of the outer loop passed into an inner loop. For example, the current item of an MItSelectionList is passed into a MItSurfaceCV iterator. You may encounter garbage collection issues in this case where the inner iterator is holding on to information that may no longer be valid. You can work around this by resetting the inner iterator to None once its loop has been completed. This releases the iterator’s information before the outer loop continues, which is important if current items are being rebuilt or updated.