Maya python for games and film

Maya Python for Games and Film A Complete Reference for Maya Python and the Maya Python API Adam Mechtley Ryan Trowbridge Morgan Kaufmann Publishers Front Matter Maya Python for Games and Film Maya Python for Games and Film A Complete Reference for Maya Python and the Maya Python API Adam Mechtley Ryan Trowbridge AMSTERDAM • BOSTON • HEIDELBERG • LONDON • NEW YORK • OXFORD • PARIS • SAN DIEGO • SAN FRANCISCO • SINGAPORE • SYDNEY • TOKYO Morgan Kaufmann Publishers is an imprint of Elsevier Copyright Acquiring Editor: Laura Lewin Development Editor: Sara Scott Project Manager: Sarah Binns Designer: Alisa Andreola Morgan Kaufmann Publishers is an imprint of Elsevier 225 Wyman Street, Waltham MA 02451 This book is printed on acid-free paper © 2012 Elsevier Inc All rights reserved No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or any information storage and retrieval system, without permission in writing from the publisher Details on how to seek permission, further information about the Publisher’s permissions policies and our arrangements with organizations such as the Copyright Clearance Center and the Copyright Licensing Agency, can be found at our website: www.elsevier.com/permissions This book and the individual contributions contained in it are protected under copyright by the Publisher (other than as may be noted herein) Notices Knowledge and best practice in this field are constantly changing As new research and experience broaden our understanding, changes in research methods, professional practices, or medical treatment may become necessary Practitioners and researchers must always rely on their own experience and knowledge in evaluating and using any information, methods, compounds, or experiments described herein In using such information or methods they should be mindful of their own safety and the safety of others, including parties for whom they have a professional responsibility To the fullest extent of the law, neither the Publisher nor the authors, contributors, or editors, assume any liability for any injury and/or damage to persons or property as a matter of products liability, negligence or otherwise, or from any use or operation of any methods, products, instructions, or ideas contained in the material herein Library of Congress Cataloging-in-Publication Data Application submitted British Library Cataloguing-in-Publication Data A catalogue record for this book is available from the British Library ISBN: 978-0-12-378578-7 For information on all Morgan Kaufmann publications, visit our Web site at www.mkp.com or www.elsevierdirect.com Typeset by: diacriTech, India 11 12 13 14 15 Printed in the United States of America Acknowledgments We would like to thank the many people who made this book possible Foremost, we want to thank our wives, Laurel Klein and Brenda Trowbridge, without whose unflagging support we would have been hopeless in this endeavor We would also like to thank the various contributors to this project for their individual efforts, including Seth Gibson of Riot Games for Chapters and 5, Kristine Middlemiss of Autodesk for Chapter 8, and Dean Edmonds of Autodesk for his technical editing, a man whose power to explain is surpassed only by his knowledge of the topics covered herein We would also like to thank the team at Focal Press who has helped out on this project, including Sara Scott, Laura Lewin, and Anaïs Wheeler Your support and patience has been a blessing Thanks also to Steve Swink for putting us in touch with the wonderful people at Focal Press We want to thank all of the people in the Maya Python and API community who have been essential not only for our own growth, but also for the wonderful state of knowledge available to us all Though we will undoubtedly leave out many important people, we want to especially thank Chad Dombrova, Chad Vernon, Paul Molodowitch, Ofer Koren, and everyone who helps maintain the tech-artists.org and PyMEL communities Last, but certainly not least, we want to thank our readers for supporting this project Please get in touch with us if you have any feedback on the book! Introduction: Welcome to Maya Python Imagine you are creating animations for a character in Maya As you are creating animations for this character, you find that you are repeating the following steps: Reference a character Import a motion capture animation Set the frame range Reference the background scene Configure the camera If you are working on a large production, with 10 to 50 animators, these simple steps can pose a few problems If we break down this process, there are many good places for tools: First, animators need to look up the correct path to the character This path may change at any given time, so having animators handpick this file could result in picking the wrong file A simple tool with a list of characters can make this task quick and reliable Next, you would want a tool to organize and manage importing the motion capture data correctly onto the character’s controls This tool could also set the frame range for the animation and move the camera to the correct location in the process The last step, referencing the correct background scene, could easily take a minute each time an animator manually searches for the correct file You could create another simple tool that shows a list of all the backgrounds from which to pick Hopefully you can see that such tools would save time, make file selection more accurate, and let the animators focus on their creative task The best way to create such tools is by using one of Maya’s built-in scripting languages—particularly Python Python is a scripting language that was originally developed outside of Maya, and so it offers a powerful set of features and a huge user base In Maya 8.5, Autodesk added official support for Python scripting The inclusion of this language built upon Maya’s existing interfaces for programming (the MEL scripting language and the C++ API) Since Maya Embedded Language (MEL) has been around for years, you might wonder why Python even matters A broader perspective quickly reveals many important advantages: Community: MEL has a very small user base compared to Python because only Maya developers use MEL Python is used by all kinds of software developers and with many types of applications Power: Python is a much more advanced scripting language and it allows you to things that are not possible in MEL Python is fully object-oriented, and it has the ability to communicate effortlessly with both the Maya Command Engine and the C++ API, allowing you to write both scripts and plugins with a single language Even if you write plug-ins in C++, Python lets you interactively test API code in the Maya Script Editor! Cross-platform: Python can execute on any operating system, which removes the need to recompile tools for different operating systems, processor architectures, or software versions In fact, you not need to compile at all! Industry Standard: Because of Python’s advantages, it is rapidly being integrated into many other content-creation applications important for entertainment professionals Libraries can be easily shared between Maya and other applications in your pipeline, such as MotionBuilder Python versus MEL There are many reasons to use Python as opposed to MEL, but that doesn’t mean you have to give up on MEL completely! If your studio already has several MEL tools there is no reason to convert them if they are already doing the job You can seamlessly integrate Python scripts into your development pipeline with your current tools Python can call MEL scripts and MEL can call Python scripts Python is a deep language like C++ but its syntax is simple and very easy to pick up Nonetheless, Python handles complex data more gracefully than MEL MEL programmers sometimes try to imitate complex data structures, but doing so often requires messy code and can be frustrating to extend Since Python is object-oriented and it allows nested variables, it can handle these situations more easily Moreover, Python can access files and system data much faster than MEL, making your tools more responsive for artists in production Programmers also have many more options in Python than in MEL Since Python has been around much longer, you might find another user already created a module to help Python perform the task you need to If you don’t understand some of the language used yet, don’t worry This book is here to help you understand all of these concepts and emerge production-ready! MStatus class, 279, 281 MString, 281 MStringArray, 281 MSyntax, 294, 299, 315 MTransformationMatrix class, 278 MTypeId, 354 multiplyDivide node, 42 Mutability, 35–36 MVector class, 272, 273f, 274 N Nested lists, 54–56, 55–56f Node class, definition, 354–355 Node creator class, 356 Node initializer class, 356–357 Nodes, 11 listing of, 76–77 None type, 37 normalize() method, 280 Number types, 43–44 Numeric operators, 44–45, 44t NURBS surface, 348–349f O Object-oriented programming (OOP), 194 class implementation in Python, 150 inheritance, 164–168, 264–265 instantiation, 150–151 in Maya, 168–175 virtual functions and polymorphism, 265 versus procedural programming, 148–151, 168–175 Objects, 294, 294 Observation, Maya tool design, 181 OOP See Object-oriented programming OpenMayaMPx module, 290 Operators, 46–49, 47t concatenation, 47 dictionary, 59t, 59–60 indexing, 47–49, 48f set, 57t, 57–58 slicing, 47–49, 48f Option windows, 198 in Maya, 190–191 optwin.py module, 218 OS X, 140 outColor attribute, 103 P Packages, 121–125 create.py, 122–123 init py, 124–125 math.py, 123 Parametric sphere nodes, 333f parent command, 185 partial() function, 204–205 pass keyword, 65 pasteBtnCmd() method, 229 pi attribute, 115 plug argument, 357 Plug arrays, 363–364 implementing, 364–368 Plugs, 330–331 polyCube command, 15, 16f, 17–18, 21, 24–25, 52 polyCube node, 330 polyExtrudeFace command, 311 Polygon Primitives, 15 Polymorphism, 265 polyPoke command, 312 polySphere command, 9, 11, 15, 38, 38 polySphere nodes, 13, 38, 41, 75, 340 Pose Manager window, 224–226, 225f Positional argument, 69 print(), 65 print() function, 81 proc keyword, 64 Procedural programming versus OOP, 148–151, 168–175 process_all_textures(), 65 process_diffuse() function, 105 Property Editor, 242–243 dynamic string property in, 245f Proxy classes, 281–282, 290 pSphereShape node, 13 Push button widget, 244f Push–pull system, 334–336 PyMEL, 113, 168 advantages and disadvantages, 171–172 example, 172–175 features of, 169–171 installing, 168 introduction to, 168–169 PyNodes, 169–170 PyQt, 254–257 installation, 254–255 using in earlier versions of Maya, 255–257 in Maya 2011+, 255–257 Python, 5, 263, 263f, 274, 277 and C++ API, 281–283 class implementation in, 150 command reference, 24–26, 24f commands, 15–19, 16f core object types, 19–22, 20t data model, 34–37 IDE, 140–145 configuration, 141–145 to create projects, 144 debugging, 145 downloading, 140–141 to Maya, 144–145 views, 142–143 keywords, 33–34 Maya API, communicates with, 268–270 online documentation, 26–27 Script Editor, 8–10 version, 26 python command, 188, 203 Python functions, 64–75 anatomy of, 64–66 Python path, 127–140 environment variable, 135–140 sys.path, 128–129 userSetup scripts, 131–133 Python search path, 122 Pyuic4, 254 Q Qt creator, 241–242, 243f designer, 237, 239–246, 252f application, 240f hands on, 241–246 types of forms, 239 GUI loading, 246–254 toolkit, 235, 235f and MAYA, 234–237 signals and slots, 241 Software Development Kit (SDK), 237–239 links for, 238t tools benefit of, 234 installation, 237–239 QtCore module, 255 Query mode, 23–24 R Radio button groups, 219–220 radioMenuItemCollection Radius command, 200 flag, 315 raise statement, 96 range() function, 81–84 Readability, 361 redoIt() method, 313, 323–325 new nodes creation, 323–324 Reference counting, 36f, 36–37 registerCommand(), 292 reload() function, 125 rename command, 75 return statement, 96 Return values, 25, 74–75 Right mouse button (RMB), rotatedBy method, 278–279 RotateOrder rowLayout flag, 297 command, 210 S saveBtnCmd() method, 230–231 saveHierarchy() function, 227–228 Script Editor, 8–10 Scripted command, anatomy of, 289–293 command class definition, 290 command creator, 291 doIt(), 291 initialization, 292–293 OpenMayaMPx module, 290 uninitialization, 292–293 Scripted plug-ins, 287–289, 288f Sculpt Geometry Tool, 184 select command, 77 Selecting nodes, 76–77 setAttr command, 40–41, 170, 334 setdefault(), 60 function, 73 setDisconnectBehavior() method, 367 setIndexMatters() method, 367 setObjectType(), 318 setParent command, 222 Sets, 57–58 operators, 57–58, 57t setText() method, 174 setupWindowAttributes() method, 200 setWindow() method, 256–257 shadingEngine nodes, 340 shadingGroup node, 13 shape nodes, 13, 41, 341–342, 344, 346 showWindow command, 196, 214 Signals and slots in Qt, 241 widgets mapping with, 251–254 Simplified Wrapper and Interface Generator (SWIG), 254, 268 skinCluster, 37 Slicing, 47–49 Smooth tool, 191 spHelloWorld command, 288 spike module, 118–120, 118f str(), 32 String(s), 19–20 escape sequences, 50–51 formatting, 52–53, 53t multiline, 50–51 passing, 202–204 raw strings, 51 Unicode, 51–52 supportsToolAction, 199–200 SWIG See Simplified Wrapper and Interface Generator Synopsis, 25 Syntax, 293–308 creator, 298–301, 317–318 command objects, 300–301 flag arguments, 299–300 doIt(), 302–305 object validation, 303–304 storing flag arguments, 304–305 doItQuery(), 305–308 initialization of, 301–302 syntaxCreator(), 298 sys.executable, 138 Systemwide environment variables, setups and, 137–140 sys.version, 138 T textField command, 174 Tools creating, 224–232 in Maya, 183–191 marking menus, 186–190, 187f, 189f option windows, 190–191 selection, 184–186 Transform nodes, 13, 40–42, 75, 195, 224, 228, 340, 340 editing, 325 Triggering DG Evaluation, 336 try clause, 97 try statement, 96–97 Tuple, 19, 21 Type, 34 type(), 32 type() function, 75 U uiFile flag, 249 uiString flag, 249 Underworld, 347–350 Undo and redo, 313–314 MDGModifier, 314 mechanism of Maya, 308–313, 309–312f undoInfo command, 310 undoIt() method, 325–326 Unicode string, 51–52 Uninitialization, 359–360 uninitializePlugin(), 292 User interface design, 180 userSetup scripts, 131–133 userSetup.mel, 131–133 userSetup.py, 131 useSelectionAsDefault(), 300 V Value, 34 Variable-length argument lists using double asterisk (**) operator, 71 using single (*) operator, 71 Variables, 30–37, 32t with Maya commands, 37–42 in MEL, 33 verbose flag, 249 Virtual functions, 265 Void* pointers, 281 W while statement, 94–96 Widgets, 240–241 with signals and slots, mapping, 251–254 Window class, building base, 198–218 executing commands with GUI objects, 206–215 layouts and controls, 206–215 menus and menu items, 199–201 window command, 196, 199, 212–213 Windows, 139–140, 196–198, 197f Pose Manager, 224–226, 225f Wing IDE, 141, 143f World space, 296, 304, 320 Wrappers, 254 Writability, 361 WYSIWYG tool, 239 .. .Maya Python for Games and Film A Complete Reference for Maya Python and the Maya Python API Adam Mechtley Ryan Trowbridge Morgan Kaufmann Publishers Front Matter Maya Python for Games and Film. .. and Film Maya Python for Games and Film A Complete Reference for Maya Python and the Maya Python API Adam Mechtley Ryan Trowbridge AMSTERDAM • BOSTON • HEIDELBERG • LONDON • NEW YORK • OXFORD •... 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