Maya Python for Games and Film: A Complete Reference for the Maya Python API

by Adam Mechtley, Ryan Trowbridge

Overview

Maya Python for Games and Film is the first book to focus exclusively on how to implement Python with Maya. Written by trusted authorities in the field, this in-depth guide will help you master Maya Python, whether you're a seasoned technical artist looking to make the transition from MEL to Python or an aspiring artist not wanting to scramble for information.

Product Details

ISBN-13:	9780123785794
Publisher:	CRC Press
Publication date:	09/28/2011
Sold by:	Barnes & Noble
Format:	eBook
Pages:	408
File size:	7 MB

About the Author

Adam Mechtley, Ryan Trowbridge

Read an Excerpt

Maya Python for Games and Film

A Complete Reference for Maya Python and the Maya Python API

---

By Adam Mechtley Ryan Trowbridge

Morgan Kaufmann

Copyright © 2012 Elsevier Inc.
All right reserved.
ISBN: 978-0-12-378579-4

---

Chapter One

Maya Command Engine and User Interface

CHAPTER OUTLINE

Interacting with Maya 4 Maya Embedded Language 5 Python 5 C++ Application Programming Interface 6 Python API 6 Executing Python in Maya 6 Command Line 6 Script Editor 8 Maya Shelf 10 Maya Commands and the Dependency Graph 11 Introduction to Python Commands 15 Flag Arguments and Python Core Object Types 19 Numbers 20 Strings 20 Lists 20 Tuples 21 Booleans 21 Flag = Object Type 21 Command Modes and Command Arguments 22 Create Mode 22 Edit Mode 23 Query Mode 23 Python Command Reference 24 Synopsis 25 Return Value 25 Related 25 Flags 25 Python Examples 26 Python Version 26 Python Online Documentation 26 Concluding Remarks 27

BY THE END OF THIS CHAPTER, YOU WILL BE ABLE TO:

* Compare and contrast the four Maya programming interfaces.

* Use the Command Line and Script Editor to execute Python commands.

* Create a button in the Maya GUI to execute custom scripts.

* Describe how Python interacts with Maya commands.

* Define nodes and connections.

* Describe Maya's command architecture.

* Learn how to convert MEL commands into Python.

* Locate help for Python commands.

* Compare and contrast command arguments and flag arguments.

* Define the set of core Python data types that work with Maya commands.

* Compare and contrast the three modes for using commands.

* Identify the version of Python that Maya is using.

* Locate important Python resources online.

To fully understand what can be done with Python in Maya, we must first discuss how Maya has been designed. There are several ways that users can interact with or modify Maya. The standard method is to create content using Maya's graphical user interface (GUI). This interaction works like any other software application: Users press buttons or select menu items that create or modify their documents or workspaces. Despite how similar Maya is to other software, however, its underlying design paradigm is unique in many ways. Maya is an open product, built from the ground up to be capable of supporting new features designed by users. Any Maya user can modify or add new features, which can include a drastic redesign of the main interface or one line of code that prints the name of the selected object.

In this chapter, we will explore these topics as you begin programming in Python. First, we briefly describe Maya's different programming options and how they fit into Maya's user interface. Next, we jump into Python by exploring different means of executing Python code in Maya. Finally, we explore some basic Maya commands, the primary means of modifying the Maya scene.

INTERACTING WITH MAYA

Although the focus of this book is on using Python to interact with Maya, we should briefly examine all of Maya's programming interfaces to better understand why Python is so unique. Autodesk has created four different programming interfaces to interact with Maya, using three different programming languages. Anything done in Maya will use some combination of these interfaces to create the result seen in the workspace. Figure 1.1 illustrates how these interfaces interact with Maya.

Maya Embedded Language

Maya Embedded Language (MEL) was developed for use with Maya and is used extensively throughout the program. MEL scripts fundamentally define and create the Maya GUI. Maya's GUI executes MEL instructions and Maya commands. Users can also write their own MEL scripts to perform most common tasks. MEL is relatively easy to create, edit, and execute, but it is also only used in Maya and has a variety of technical limitations. Namely, MEL has no support for object-oriented programming. MEL can only communicate with Maya through a defined set of interfaces in the Command Engine (or by calling Python). We will talk more about the Command Engine later in this chapter.

Python

Python is a scripting language that was formally introduced to Maya in version 8.5. Python can execute the same Maya commands as MEL using Maya's Command Engine. However, Python is also more robust than MEL because it is an object-oriented language. Moreover, Python has existed since 1980 and has an extensive library of built-in features as well as a large community outside of Maya users.

C++ Application Programming Interface

The Maya C++ application programming interface (API) is the most flexible way to add features to Maya. Users can add new Maya objects and features that can execute substantially faster than MEL alternatives. However, tools developed using the C++ API must be compiled for new versions of Maya and also for each different target platform. Because of its compilation requirements, the C++ API cannot be used interactively with the Maya user interface, so it can be tedious to test even small bits of code. C++ also has a much steeper learning curve than MEL or Python.

Python API

When Autodesk introduced Python into Maya, they also created wrappers for many of the classes in the Maya C++ API. As such, developers can use much of the API functionality from Python. The total scope of classes accessible to the Python API has grown and improved with each new version of Maya. This powerful feature allows users to manipulate Maya API objects in ordinary scripts, as well as to create plug-ins that add new features to Maya.

In this book, we focus on the different uses of Python in Maya, including commands, user interfaces, and the Python API. Before we begin our investigation, we will first look at the key tools that Maya Python programmers have at their disposal.

EXECUTING PYTHON IN MAYA

Maya has many tools built into its GUI that allow users to execute Python code. Before you begin programming Python code in Maya, you should familiarize yourself with these tools so that you know not only what tool is best for your current task, but also where to look for feedback from your scripts.

Command Line

The first tool of interest is the Command Line. It is located along the bottom of the Maya GUI. You can see the Command Line highlighted in Figure 1.2. The Command Line should appear in the Maya GUI by default. If you cannot see the Command Line, you can enable it from the Maya main menu by selecting Display -> UI Elements -> Command Line.

The far left side of the Command Line has a toggle button, which says "MEL" by default. If you press this button it will display "Python." The language displayed on this toggle button tells Maya which scripting language to use when executing commands entered in the text field immediately to the right of the button. The right half of the Command Line, a gray bar, displays the results of the commands that were entered in the text field. Let's create a polygon sphere using the Command Line.

1. Switch the Command Line button to "Python." The button is located on the left side of the Command Line.

2. Click on the text field in the Command Line and enter the following line of text.

import maya.cmds;

3. Press Enter.

4. Next enter the following line of code in the text field.

maya.cmds.polySphere();

5. Press Enter. The above command will create a polygon sphere object in the viewport and will print the following results on the right side of the Command Line.

# Result: [u'pSphere1', u'polySphere1']

You can use the Command Line any time you need to quickly execute a command. The Command Line will only let you enter one line of code at a time though, which will not do you much good if you want to write a complicated script. To perform more complex operations, you need the Script Editor.

Script Editor

One of the most important tools for the Maya Python programmer is the Script Editor. The Script Editor is an interface for creating short scripts to interact with Maya. The Script Editor (shown on the right side in Figure 1.2) consists of two panels. The top panel is called the History Panel and the bottom panel is called the Input Panel. Let's open the Script Editor and execute a command to make a sphere.

1. Open a new scene by pressing Ctrl + N.

2. Open the Script Editor using either the button located near the bottom right corner of Maya's GUI, on the right side of the Command Line (highlighted in Figure 1.2), or by navigating to Window -> General Editors -> Script Editor in Maya's main menu. By default the Script Editor displays two tabs above the Input Panel. One tab says "MEL" and the other tab says "Python."

3. Select the Python tab in the Script Editor.

4. Click somewhere inside the Input Panel and type the following lines of code.

import maya.cmds; maya.cmds.polySphere();

5. When you are finished press the Enter key on your numeric keypad. If you do not have a numeric keypad, press Ctrl + Return.

The Enter key on the numeric keypad and the Ctrl + Return shortcut are used only for executing code when working in the Script Editor. The regular Return key simply moves the input cursor to the next line in the Input Panel. This convention allows you to enter scripts that contain more than one line without executing them prematurely.

Just as in the Command Line example, the code you just executed created a generic polygon sphere. You can see the code you executed in the History Panel, but you do not see the same result line that you saw when using the Command Line. In the Script Editor, you will only see a result line printed when you execute a single line of code at a time.

6. Enter the same lines from step 4 into the Input Panel, but do not execute them.

7. Highlight the second line with your cursor by triple-clicking it and then press Ctrl + Return. The results from the last command entered should now be shown in the History Panel.

# Result: [u'pSphere2', u'polySphere2']

Apart from printing results, there are two important things worth noting about the previous step. First, highlighting a portion of code and then pressing Ctrl + Return will execute only the highlighted code. Second, highlighting code in this way before executing it prevents the contents of the Input Panel from emptying out.

Another useful feature of the Script Editor is that it has support for marking menus. Marking menus are powerful, context-sensitive, gesture-based menus that appear throughout the Maya application. If you are unfamiliar with marking menus in general, we recommend consulting any basic Maya user's guide.

To access the Script Editor's marking menu, click and hold the right mouse button (RMB) anywhere in the Script Editor window. If you have nothing selected inside the Script Editor, the marking menu will allow you to quickly create new tabs (for either MEL or Python) as well as navigate between the tabs. As you can see, clicking the RMB, quickly flicking to the left or right, and releasing the RMB allows you to rapidly switch between your active tabs, no matter where your cursor is in the Script Editor window. However, the marking menu can also supply you with context-sensitive operations, as in the following brief example.

1. Type the following code into the Input Panel of the Script Editor, but do not execute it.

maya.cmds.polySphere()

2. Use the left mouse button (LMB) to highlight the word polySphere in the Input Panel.

3. Click and hold the RMB to open the Script Editor's marking menu. You should see a new set of options in the bottom part of the marking menu.

4. Move your mouse over the Command Documentation option in the bottom of the marking menu and release the RMB. Maya should now open a web browser displaying the help documentation for the polySphere command.

As you can see, the Script Editor is a very useful tool not only for creating and executing Python scripts in Maya, but also for quickly pulling up information about commands in your script. We will look at the command documentation later in this chapter.

At this point, it is worth mentioning that it can be very tedious to continually type common operations into the Script Editor. While the Script Editor does allow you to save and load scripts, you may want to make your script part of the Maya GUI. As we indicated earlier, clicking GUI controls in Maya simply calls commands or executes scripts that call commands. Another tool in the Maya GUI, the Shelf, allows you to quickly make a button out of any script.

(Continues...)

---

Excerpted from Maya Python for Games and Film by Adam Mechtley Ryan Trowbridge Copyright © 2012 by Elsevier Inc. . Excerpted by permission of Morgan Kaufmann. All rights reserved. No part of this excerpt may be reproduced or reprinted without permission in writing from the publisher.
Excerpts are provided by Dial-A-Book Inc. solely for the personal use of visitors to this web site.

---

Table of Contents

Contents

Acknowledgments....................xiii
Introduction: Welcome to Maya Python....................xv
CHAPTER 1 Maya Command Engine and User Interface....................3
CHAPTER 2 Python Data Basics....................29
CHAPTER 3 Writing Python Programs in Maya....................63
CHAPTER 4 Modules....................111
CHAPTER 5 Object-Oriented Programming in Maya....................147
CHAPTER 6 Principles of Maya Tool Design....................179
CHAPTER 7 Basic Tools with Maya Commands....................193
CHAPTER 8 Advanced Graphical User Interfaces with Qt....................233
CHAPTER 9 Understanding C++ and the API Documentation....................261
CHAPTER 10 Programming a Command....................285
CHAPTER 11 Data Flow in Maya....................327
CHAPTER 12 Programming a Dependency Node....................351
INDEX....................377