top of page
Writer's pictureDilen Shah

Introduction to Maya API


Before diving into Maya API, it is important to first understand what the Maya API is, what functionality it offers beyond that of scripting with Maya commands, and what are the trade-offs. In general, the Maya API is faster, more flexible, more powerful, and can do almost anything Maya commands can. If this is true, why use my commands at all?

  • Functionality can be extended through plug-ins

  • UIs, tools and automation can be implemented through scripting

  • Maya Commands

  • Maya API

But first, starting at a very high level, Maya is an open product. This means that anyone can change the existing features or add new functionality through scripting or plugins. No doubt everyone watching this have either written their own scripts or at the very least downloaded a few from the web to enhance their workflow. Generally speaking, plugins extend Maya with new nodes, contexts, and more, while scripting, on the other hand, is very useful for UI creation, workflow tools, and automation. Now, when I say Maya is an open product, this should not be confused with being open-sourced.


You do not have access to the source code for Maya, and any changes or feature additions are accomplished using one of 2 programming interfaces provided by the software.

This is Maya Commands and the Maya API.

The image above taken from Maya's documentation shows the architecture of Maya's programming interfaces. Each element in the top row is a supported programming language. There is Mel, Python and C++ or Microsoft's. NET.


The middle row contains Maya's two programming interfaces, Maya commands and the Maya API. The bottom row is simply the Maya application itself, the way this image is set up, the language is directly above each interface are supported by that interface. This means Mel can only use Maya commands and C++/.NET can only use the Maya API. Python is unique in that it can take advantage of both Maya commands and the Maya API.


Maya commands


This is in the form of scripts written in either Mel or Python if you are not already aware and this is taken directly from the documentation. Mel is a scripting language at the heart of Maya, Maya's user interface is created primarily using Mel, and Mel provides an easy way to extend the functionality of Maya. Everything you can do using Maya's graphical interface can be automated and extended using Mel. For Python scripts, Maya commands, more commonly known as the Maya Commands module, is just a wrapper for Mel, and this is the big reason why the Maya command syntax is implemented the way it is.


Maya API


The Maya API is a public API that was created for writing plugins using C++. In more recent releases, Autodesk has added the Python API and the .NET API, and this lets developers access the API using either Python scripting or Microsoft's .NET technology. Focusing on the Python API. There are currently two versions, Python API 1.0 and Python API 2.0. According to the documentation, Python API 2.0 provides a more Pythonic workflow and improve performance.


Just to keep in mind, as of Maya 2019, the 2.0 version of the API is still incomplete, so it will be necessary to use API 1.0 for some classes. That being said, it is possible to use both API 1.0 and 2.0 in the same script, but objects from the two APIs cannot interact.


So what can the Maya API do that my commands cannot? The primary purpose of the Maya API is to extend Maya.

  • Nodes

  • Commands

  • Contexts/Tools

  • Manipulators

  • Emitters

  • Fields

  • File Translators

  • much more...

Of course, it should be noted that each of these examples must be written as a plugin. A simple script will not suffice, and any new types need to be registered with Maya. With Maya commands, you are constrained by the existing functionality of Maya. However, in many cases, this is more than enough.


Maya commands are great for automating tasks and creating tools that improve an artist workflow, often saving many hours of otherwise manual labour. And it very much has a place alongside the Maya API. Now, just a moment ago, I said the Maya API was created for writing plugins and when C++ was the only option for gaining access to the API. This was true. If you wanted to run code that utilizes the Maya API, it needed to be C++ Code compiled as a Maya plugin and loaded through Maya's Plugin manager.


The addition of the Maya Python API changes this since it's released. The Maya API can be used in regular Python scripts without having to restrict the API code to plugins. One of the most common examples of this is the MQtUtil class that is used by most UIs built with PySide2.


Maya API vs Maya Commands


The Maya API offers numerous significant advantages over Maya commands and yet most tools and scripts are written using my commands, why is this?

  • Before Python, the Maya API required creating a C++ plug-in

  • This was always a challenge as that required knowledge of C++ and the ability to compile C++ as a Maya plug-in and different Operating systems (Linux, Windows and Mac)

  • Maya Python API removed the need for C++

Of course, this is no longer the case, the Maya Python API allows scripts and plugins to be written in python, not only is python a much easier programming language to learn, but it also provides a very robust set of built-in and third-party packages and it doesn't need to be compiled. Python removes the often complex task of building a C++ project.


While Python has widely replaced Mel as a scripting language of choice in Maya and for very good reasons, most scripts are still written using Maya Commands using the Maya Commands module. Part of this has to do with legacy scripts, many Mel scripts have been ported to Python, both public releases and pipeline tools. It is much quicker to convert them using Maya commands since the command syntax is so similar, additionally, many artists, animators and TDs first learn to script using Mel and then transition to using Python using Maya commands is much easier, this is especially true for individuals who have learned to code in their spare time to augment their current skills, the majority of people writing scripts for Maya are not full-time programmers, setting these reasons aside most users continue to work with Maya commands and anyone learning to code in Maya is learning python and Maya commands, and despite all the advantages of using the Maya API, there are two very big reasons why Maya commands remains so popular.

  • It's Easier

  • DG/DAG interactions are hidden (Maya API: needs manual implementation)

  • Undo support is built-in (Maya API: needs manual implementation)

  • Fewer lines of code

  • Faster to get something up and running (prototype)


So the big question is, Why would anyone want to use the Maya API instead of Maya commands, fortunately, there are some very compelling reasons to use it using either Python or C++.

  • Creating new nodes, contexts, etc... requires the Maya API

  • This is not possible with Maya Commands

  • Far more access to Maya's internals than Maya Commands provides

  • With this switch, an Extra level of control requires more code

  • Maya API is usually faster often much faster than Maya Commands

  • Maintain interactive speeds for artists often requires using Maya API


The addition of the Maya python API offers one additional benefit: you can prototype in Python and convert to C++ if you find extra performance is required. It is often faster to generate in Python but when it comes to maximizing speed in threading C++ is usually the best option.


If you are simply building tools to automate repetitive tasks then the Maya command is an excellent choice. Weirdly, this interface shines, however, to do anything that adds something truly new to Maya to extend the core architecture the Maya API is essential.


C++ vs Python


Let's discuss the pros and cons of using python as opposed to C++.


Maya API (C++)


Pros

  • Faster Code execution

  • Multi-threading

  • API is written for C++

Cons

  • Builds(compiling and linking)

  • OS and Maya version dependent

  • C++ is more complex and less forgiving


Maya Python API


Pros

  • Faster to develop

  • Python is easier to write and maintain

  • Version independent

Cons

  • Slower code execution

  • Limited threading

  • API is written for C++



Final Thoughts


For anyone new to the Maya API who isn't proficient with C++, starting with the Maya Python API is likely the best option.


Focus on the core concepts of the Maya API without having to fight with C++ builds.


Prototyping plug-ins in Python is another area where the Python API shines.


If performance increases are required, the plug-in then can be ported to C++


I have written a couple of other posts on Maya API, please do check them out as well.


I will be adding more posts related to this in the coming weeks with actual written examples and code.


Until next time.


Recent Posts

See All

留言


bottom of page