Intro to Python Scripting for Maya

Maya is a 3D modelling software from Autodesk that is used by some of the biggest 3D animation studios in the world. If you’ve seen a computer-animated film, at least part of it was probably made in Maya.

This tutorial is going to take you through writing a Python script in Maya using cmds, step-by-step! As an example, we’ll be writing a script to generate party hats in random colour combinations. This project is good for people who have a little bit of experience in programming but no experience in Maya. I’ll be using Maya 2018 but the interface and commands should be similar for other recent-ish versions.

An example party hat

Step 1: Download and Install Maya

You might be thinking: “I’m not about to drop $$$$$ just to make some party hats!” but the good news for you is that students can get a license to several Autodesk products for free! (Bless the kind souls at Autodesk) https://www.autodesk.com/education/free-software/featured

I won’t walk through the installation but make sure that you have enough time and space on your computer to install it! It’s a hefty piece of software.

Step 2: Open up Maya

Try not to be too overwhelmed by the abundance of buttons/menus and limitless possibilities stretched out before you.

*exhales sharply*

Step 3: Recover enough to follow the rest of this tutorial

It’s okay, take your time! Maybe explore a little using these handy basic controls:

To create a basic sphere to play with: Create > Polygon Primitives > Sphere

Switching views: Hover over one of the views and press the space bar to enlarge it to the full window. Press again to go pack to the 4-pane view

Rotating your view: Hold down alt and click and drag your mouse to rotate your view in the perspective pane

Move: w (or the icon on the left toolbar)

Rotate: e (or the icon on the left toolbar)

Scale: r (or the icon on the left toolbar)

Step 4: Open up the Script Editor

Windows > General Editors >Script Editor

This is where you’ll call your python scripts or write commands directly

Windows > General Editors >Script Editor

The editor might be in a separate window but you can dock it in place

Select the python tab (highlighted in the screenshot above)

Try creating/moving/rotating/selecting shapes and pay attention to what happens in the script editor!

Step 5: Translate your actions into cmds commands

According to the Maya 2016 guide, cmds is a Python wrapper for MEL (Maya Embedded Language). You can use it to script many of the actions that you do in the editor windows!

In the previous step, you may have noticed that every action that you make in the panels is reflected in a MEL command in the top part of the script editor. This is extremely useful for when you want to write your own script!

You can look up documentation for cmds here: http://help.autodesk.com/cloudhelp/2018/CHS/Maya-Tech-Docs/CommandsPython/

To find the cmds command associated with your action, just filter for the command in the “ By substring(s)” box at the top left of the cmds documentation page.

Example of filtering by ‘polySphere’

Click on the result and you’ll see detailed documentation with sample code at the bottom!

Step 6: Getting stated on the project!

Phew, after hours of being lost in the rabbit hole that is Maya, you’re finally ready to start an example project!

Make sure to place the script in a location where Maya can access them. To figure out which script paths are accessible to Maya, run the following command in the MEL tab of the script editor:

getenv “MAYA_SCRIPT_PATH”

This will display the paths in the output window above the editor.

Pick your favourite text editor and make a python file called hatCreator.py in one of the locations listed.

Step 7: Importing cmds

Start off your script by importing the two external packages that we need: cmds and random (to generate the random colour values later on)

import maya.cmds as cmds
import random

Step 8: Create the hat components

In this super-simplified model of a party hat, the only two polygons you need are a cone and a sphere (for the pompom on the hat).

Create a function, createHat(), that takes in 2 optional parameters, cone_colour and pompom_colour (that default to None in the case that the user wants a random colour). In this script, if the colour is not specified, a random one will be generated.

def createHat(cone_colour=None, pompom_colour=None):

Now we need to create the polygons that make up the hat: a cone for the base and a sphere for the pompom. The pompom will have to be scaled down from the default size and moved up on the y axis to be on the right spot on the cone.

    # Create the cone and pompom
    cone_obj, cone_node = cmds.polyCone()
    pompom_obj, pompom_node = cmds.polySphere(r=0.25)
    # Move the pompom to the right spot on the hat cone
    cmds.move(0, 1.06, 0)

We’ll come back to this function later when we need to combine the two shapes.

Step 9: Adding colour

Since we’ll be changing the colours for both objects, let’s make a function to assign a material to an object and change its colour. The function change_colour() will take in the object, the name of the material and the colour

def change_colour(object, material, colour):

This is a tricky part that will require some references to the documentation. Now if you look up “ surfaceShaderList” on the Maya docs, you’ll see a section of example code at the bottom:

This can be adapted to be used in our function to create a new shading node:

# create a material with the given name 
    cmds.sets(name=material+'MaterialGroup', renderable=True, empty=True)
    cmds.shadingNode(material, name=material+'Shader', asShader=True)

Now let’s set the object’s colour to the specified colour (or randomly if nothing is given). The colour attributes are given as RGB (Red Green Blue) values with each number being between 0 and 1.

    if not colour:
        # randomly generate a colour   0 to 1 on each axis   r g b
        red = random.random()
        green = random.random()
        blue = random.random()
        cmds.setAttr(material+'Shader.color', red, green, blue, type='double3')

    else:
        # we should add some error catching here
        red = colour[0]
        green = colour[1]
        blue = colour[2]
        cmds.setAttr(material+'Shader.color', red, green, blue, type='double3')

    cmds.surfaceShaderList(material+'Shader', add=material+'MaterialGroup')
    cmds.sets(object, e=True, forceElement=material+'MaterialGroup')

Step 10: Putting it all together

At this point you have a cone, a sphere and a function to change their colours. All you have to do is put them together!

Let’s go back to createHat(cone_colour=None, pompom_colour=None) from Step 8. Under the existing code in the function, add the code to join colour the objects and then merge them into one.

    change_colour(cone_obj, 'blinn', cone_colour)
    change_colour(pompom_obj, 'lambert', pompom_colour)
    # merge them into one shape (polyUnite)
    cmds.polyUnite(cone_obj, pompom_obj, n='hat')

Step 11 : Running the Script

To run the script, put the following lines of code in the python section of the script editor. Press the ‘play’ button to run your script.

import hatCreator
reload(hatCreator)
hatCreator.createHat()

Import your script

Press the ‘play’ button to run your script

The completed code can be found here: https://github.com/Cheryl-Lao/BitsAndBytes/blob/master/hatCreatorV1.py

Step 12: Put on your party hats and celebrate!

You just wrote your first script for Maya!

Step 13: Notice the unexpected

If you’ve read this far and played with the script a little, you might notice that there’s an issue: When you generate a second hat, the first hat changes colour as well! Do you know why this is?

So in sync!

Step 14: Try to fix it?

I’m tempted to quote my overpriced textbooks to say this is “left as an exercise to the reader” but I’ll probably post a follow-up later on. In the meantime, you now have a bit of an intro to writing scripts for Maya!