Getting Started¶

Importing PyMEL¶

To get started we need to import the pymel module:

from pymel.core import *

This brings everything in pymel into the main namespace, meaning that you won’t have to prefix the maya commands with the module name.

from pymel.core import *
s = sphere() # create a nurbsSphere
sphere = 'mySphere'  # oops, we've overwritten the sphere command with a string
sphere()
# Error: name 'sphere' is not defined
# Traceback (most recent call last):
#   File "<maya console>", line 1, in <module>
# NameError: name 'sphere' is not defined #

An Intro to PyMEL Objects in Maya¶

Before we proceed let’s make sure we have a clean scene so that you’ll get the same results as me:

f=newFile(f=1) #start clean

Let’s start by listing the cameras in the scene. We do this in the same way that we would with maya.cmds:

ls(type='camera')
# Result: [nt.Camera(u'frontShape'), nt.Camera(u'perspShape'), nt.Camera(u'sideShape'), nt.Camera(u'topShape')]

Just for comparison, let’s do the same thing using maya.cmds:

import maya.cmds as cmds
cmds.ls(type='camera')
# Result: [u'frontShape', u'perspShape', u'sideShape', u'topShape']

Notice the difference in the returned results. In the second example using maya.cmds, the ls function returns a list of strings. For those of us coming from a MEL background, a list of names as strings is what we would expect out of ls. PyMEL returns something much better – instances of PyNode classes – which are like strings on steroids. In addition to methods for operating on node names as strings, these classes have methods for operating on the type of node or UI element that the string represents.

Let’s use one of these camera objects to get some information. To do this using maya.cmds we might write something like this:

cam = ls(type='camera')[0]
camera( cam, query=True, aspectRatio=True)
# Result: 1.5
camera( cam, query=True, focalLength=True)
# Result: 35.0
camera( cam, edit=True, focalLength=20)

Rewriting this in an object-oriented way is fairly straight-forward:

cam = ls(type='camera')[0]
cam.getAspectRatio()
# Result: 1.5
cam.getFocalLength()
# Result: 35.0
cam.setFocalLength(20)

The two examples start out the same way: with the ls function. This is how we get our raw material to work with, in this case our node objects. In general, we can get nodes in 3 ways:

• list them based on some criteria
• create them
• get them by their name if we know it

Once we have our list of nodes, we can begin to work in an object-oriented fashion. There is not a hard-fast rule for converting from a procedural style to an object-oriented one, but here are some general guidelines:

• the argument to the command – in this case cam – becomes the operating object on the left
• instead of flags – focalLength and aspectRatio we use methods, which are attached to right of the object with a period .
• query methods are typically prefixed with ‘get’ and edit methods are prefixed with ‘set’. If a query does not have a corresponding edit, it may not have a ‘get’ prefix.

So, in our case query=True, aspectRatio=True becomes .getAspectRatio. And query=True, focalLength=True becomes .getFocalLength.

Getting Help¶

If you are ever unsure of what method to use, just use the builtin python help command on the node class (the capitalized node type). First find out what type of node you’re working with. we’ll continue from the example above, with our cam variable:

print repr(cam)

This prints nt.Camera(u'frontShape'). The nt.Camera part tells you what type of object it is. Now we can get help on that object type:

help(nt.Camera)

This prints all the documentation on the Camera node type. If you want help on a particular method, you can do this:

help(nt.Camera.getFocalLength)

You can do the same thing for any function as well:

help(ls)

Attributes¶

I think it’s time we learned how to set some attributes. Let’s go back and take a look at our plane’s transform and access an Attribute object. Just like nodes, attributes have their own class with methods that encompass the dozens of MEL commands for operating on them.:

print `plane.translateX`
# Result: Attribute(u'pPlane1.translateX')

To get and set attributes:

plane.translateX.get()
# Result: 0.0
plane.translateX.set(10.0)

Here’s a few examples of how to query and edit properties of attributes:

plane.translateX.isLocked()
# Result: False
plane.translateX.setLocked(True)
plane.translateX.isKeyable()
# Result: True
plane.translateX.setKeyable(False)

Connections¶

Now let’s look into getting other objects connected to our plane shape. The Attribute.connections method accepts the same flags as the procedural command listConnections.

Below we get incoming and outgoing connections:

shape.connections()
# Result: [ShadingEngine(u'initialShadingGroup'), PolyPlane(u'polyPlane1')]

inputs is a shorcut to connections(source=True):

shape.inputs()
# Result: [PolyPlane(u'polyPlane1')]

outputs is a shorcut to connections(source=False):

shape.outputs()
# Result: [ShadingEngine(u'initialShadingGroup')]

Notice that when we enable the plugs flag that the result becomes an Attribute instead of a node type.:

shape.inputs(plugs=1)
# Result: [Attribute(u'polyPlane1.output')]

Here’s another handy feature of python: it supports 2D arrays, meaning you can put lists inside lists. PyMEL takes advantage of that in many situations, including when we enable the connections flag, which causes listConnections to list source-destination pairs.:

shape.connections(c=1, p=1)
# Result: [(Attribute(u'pPlaneShape1.instObjGroups[0]'), Attribute(u'initialShadingGroup.dagSetMembers[0]')), (Attribute(u'pPlaneShape1.inMesh'), Attribute(u'polyPlane1.output'))]

This is particularly useful for looping

for source, destination in shape.connections(c=1, p=1):
...     print source, destination

pPlaneShape1.instObjGroups[0] initialShadingGroup.dagSetMembers[0]
pPlaneShape1.inMesh polyPlane1.output

Using Existing Objects by Name¶

In many cases, you won’t be creating objects directly in your code, but will want to gain access to an existing object by name. PyMEL provides two ways of doing this. Both of them will automatically choose the correct PyMEL class for your object.

The PyNode class:

PyNode( 'defaultRenderGlobals').startFrame.get()
# Result: 1.0

The SCENE object ( an instance of the Scene class )

SCENE.defaultRenderGlobals.startFrame.get()
# Result: 1.0

Mel Scripts¶

Calling MEL scripts through maya.mel.eval is a nuisance because it requires so much string formatting on the programmer’s part. pymel.mel handles all of that for you so you can use your MEL scripts as if they were python functions. This includes automatically formatting all iterable types into maya arrays.

See out pymel.core.language.Mel for more information.

What to Change¶

All of the MEL functions in maya.cmds exist in pymel, with a few exceptions ( see Module Documentation ). MEL functions that operate on nodes and/or attributes almost always fall into one or more of these categories: creating, listing, querying/editing. As you begin shifting toward a more object-oriented approach, you will still retain the need for procedural programming. Use these guidelines for what aspects of PyMEL are best suited to object-oriented programming:

1. creating nodes and UI elements : remains mostly procedural
2. listing objects and UI elements: object-oriented, except for general listing commands like ls
3. querying and editing objects and UI elements: object-oriented, except for commands that operate on many nodes at once, like select and delete

Partial Conversion is Bad, mmkay¶

Mixing maya.cmds module with pymel.core will result in problems, because maya.cmds doesn’t know what to do with anything other than very basic data types. Passing a PyNode, Matrix, Vector, or other custom type to a maya.cmds function will result in errors. Your best bet is to completely replace maya.cmds with pymel throughout your code in one go. This might sound frightening, but it will ultimately lead to fewer errors than partial PyMEL integration. The purely procedural part of pymel.core will behave exactly the same as maya.cmds as long as it is replaced wholesale, but if it is not, results returned from PyMEL functions will cause errors when passed to maya.cmds functions, and results from maya.cmds will need to be cast to PyNodes.

There are only a handful of maya.cmds wraps in PyMEL that are not backward compatible. They all fall into the category of functions which now return a list of tuple pairs instead of a flat list:

listConnections( connections=True )
keyframe( q=True, valueChange=True )
keyframe( q=True, timeChange=True )
ls( showType=True )

These changes are all noted in the docstrings of each function.