Maya Python for Games and Film
A Complete Reference for Maya Python and the Maya Python API
- Adam Mechtley, got his start in the games industry as a Technical Artist for THQ. Currently an independent contractor, Adam's clients include 2XL Games and Flashbang Studios.
- Ryan Trowbridge, is a Character TD at Naughty Dog Inc. He got his start at Pipeworks Software and has consulted with Buzz Monkey Software.
--Intermediate level Maya users who may have some understanding of Maya's longstanding scripting interface, MEL, and are moving to Python for Maya scripting.
--Intermedia level Python users.
--Job titles: Professional Technical Artists or Tools Programmers in the video game or film industries.
--Students in technical or vocational programs who are pursuing careers in the above-listed fields.
- Published: September 2011
- Imprint: MORGAN KAUFMANN
- ISBN: 978-0-12-378578-7
Table of Contents
Introduction To Maya Python
Project: Contrast a MEL and a Python API version of a Flatten Mesh script
Goal: This introductory chapter explains what the book is about and will excite readers about the possibilities Python affords them in Maya. We provide them a simple script, both a MEL version and a Python API version, that flattens a dense mesh to show them a quick example of some of the dramatic performance boosts they will learn how to harness. Fundamentally, this chapter will help highlight why readers bought the book, what they can expect to learn, and why it is so cool!
Part 1. Command-Level Python in Maya
Chapter 1. The Maya Command Engine and User Interface
Project: Input simple commands using script editor
Goal: This chapter briefly describes the basic low-level structure of Maya by focusing on its command engine. A more detailed description of the architecture appears later in the section dealing with the API. Following this description, we briefly examine Maya's three programming interfaces and what each is best suited for. Finally, we introduce readers to Maya's script editor and command line so they can begin entering simple commands and know where to find their output.
Chapter 2. Python Basics
Project: Translating basic MEL operations into Python
Goal: This chapter provides a brief overview of the Python language for new users. We first examine the principles of Python syntax (declarations, white space, operators) and compare Python to MEL (variable typing, semicolons). We then introduce Python's core object types and explain how reference counting works in relation to mutable/immutable data types and simple/complex data types. Finally, we explain what modules are and how they differ from the source command in MEL. We explain what import does, how to load and reload modules (math and sys), and where the command looks for modules. Finally, this chapter shows the reader where to find Python's online documentation for more information.
Chapter 3. Start Programming in Maya Python
Project: Create and modify various Maya nodes
Goal: This chapter introduces the Maya cmds module and assists readers in creating basic Python programs. We compare Python to MEL examples by first explaining all of the keywords for establishing flow control in Python including conditionals, loops, and exception handling. Second, we describe what functions are and how to create them in Python. We discuss how to create arguments, assign default values, how to return data, override functions, and use lambda.
Chapter 4. Object-Oriented Programming in Maya Python
Project: Create a script that adds noise to animation using classes to store keys
Goal: This chapter shows one of the key advantages of Python over MEL by introducing the concept of object-oriented programming. We briefly explain what objects are and what the constituent parts of classes are. Readers will learn how to define a class from scratch and how to inherit from an existing class. The project is a script that stores animation key data in a custom class in order to add noise to an animation curve.
Chapter 5. Working With Files
Project: Save and load a pose using files
Goal: This chapter demonstrates the basics of writing data out to a file and reading it back in to another scene. The project saves a character's pose to a text file and reads it back in to apply it to another character. We will explain how to search hierarchies and write the position, rotation, and scale values to a file.
Chapter 6. Writing Complex Programs in Maya Python
Project: Create a script that implements step-through debugging and performs different operations on different types of objects (sphere, cube, locator)
Goal: This chapter gets the reader ready to start doing more complex work in Maya Python. We explain how to configure the Maya environment and provide suggestions for text editors that are well-suited to working with Python. Additionally, we provide tips for debugging scripts in Maya Python. Specifically, we cover the use of exception handling and status messages as well as using the pydb module to step through code.
Part 2. Designing Maya User Interfaces with Python
Chapter 1. Principles of Maya Tool Design
Project: Analyze various existing tools and interfaces that ship with Maya
Goal: This chapter centers around the theory behind designing good Maya tools and interfaces. It analyzes Maya's existing user interface to provide guidelines for making tools that work predictably and are easy to use. It also explores higher-level concepts for code organization to ensure that tools and user interfaces can be easily extended. Areas of focus include location and inclusion of common buttons and options, use of selection order and descriptive naming, as well as separation of functionality and form.
Chapter 2. Basic User Interfaces with Maya Python
Project: Align Tool
Goal: This chapter introduces readers to the basics of creating a Maya UI using the cmds module including windows, panels, controls, layouts, and menus. The project is a simple tool that allows users to align one object with another based on a set of options (position and/or rotation along one, two, or three axes).
Chapter 3. External User Interfaces and mayapy
Project: Rename Object in Files
Goal: This chapter explains how to use the mayapy application to operate in Maya without having to open its user interface. Readers will learn about the basics of creating applications that operate using Maya from the outside. Readers will walk through an example that lets them make mass changes to a large number of files without having to even open Maya's UI.
Chapter 4. Advanced User Interfaces with Maya Python and QT
Project: External batch rigging tool with UI
Goal: This chapter introduces readers to the concept of using external UI libraries to create custom user interfaces. We first discuss why some developers use external UI libraries and then shift focus onto a brief overview of the popular QT toolset (PyQT module and GUI Builder). The project has readers create an external user interface with PyQT that works with mayapy to batch rig a number of files (add IK handles to selected limbs).
Part 3. Fundamentals of the Maya Python API
Chapter 1. Understanding C++ and the API Documentation
Project: Walk through the MVector class in the API documentation
Goal: This chapter introduces the concept of the API and briefly describes what it is and how it differs from the scripts that readers have written up to this point as well as how it fits into the overall Maya architecture. The chapter walks readers through the C++ API's documentation so they are able to locate information when they need it, explains how to identify what functionality is not accessible to Python, and summarizes some of the major differences between the Python and C++ APIs including the MScriptUtil and MStatus classes.
Chapter 2. Writing Scripts that Implement the API
Project: Align Tool
Goal: This chapter has readers import the OpenMaya module and write scripts that use basic API functionality. The chapter further explains what classes are not usable from within a script (e.g. MPx classes) and how to use the MScriptUtil class to deal with pointers and references in the API. The project is a simple tool that allows users to align one object with another based on a set of options (position and/or rotation along one, two, or three axes and coordinate space).
Chapter 3. Programming a Command
Project: Select All in Frustum
Goal: This chapter revisits Maya's command engine and explains it in more detail, including its undo/redo mechanism. Readers walk through the basic parts of a command and learn how to write their own simple commands that take and parse arguments. The project is a command that lets users select all objects within the view frustum of a type specified via a command flag.
Part 4. The Maya Python API and the Dependency Graph
Chapter 1. Data Flow in Maya
Project: Multiply Utility Node
Goal: This chapter explains Maya's dependency graph architecture in great detail. It provides examples of how messages and data are propagated throughout the scenegraph, how nodes operate on the data, and what ramifications this structure has. We explain the concept of working with plugs, attributes, and datahandles by showing an example of a simple multiply utility node which uses ordinary and array attributes for input and output.
Chapter 2. Programming a Dependency Graph Node
Project: Build Rotation node
Goal: This chapter explains the anatomy of a dependency graph node. Readers will walk through an example wherein they create their own nodes and each part of the process is explained in detail. The project is a node that builds the rotation for an object from a specified aim vector and up vector in the scene. Readers will also learn how to make a custom attribute editor panel for their node.
Chapter 3. Programming Special Types of Nodes
Project: Multi-Shape Locator and Inflate Deformer
Goal: This chapter discusses special types of nodes that can be created in the API, including locators with their own custom shapes and manipulators, as well as deformers. The projects explaining the special requirements of these nodes are a locator that can render as a variety of different shapes (box, sphere, square, circle, etc.) and a deformer node that inflates an object by translating its vertices along their normals.
Chapter 4. Improving Performance of Custom Nodes
Project: Convert Python Inflate node into C++
Goal: This chapter discusses the performance limitations of custom Python nodes as compared to their C++ counterparts. It profiles the Inflate Deformer node from the previous chapter to illustrate which Python operations slow down computation and how to work around them. Finally, this chapter shows how readers can use their knowledge of the API and good coding practice to easily convert their custom Python nodes into C++ if necessary.