Maya API Intro

Overview

Different from Maya Command, Maya API offers more low level access to Maya’s feature. You can think of Maya in multiple layers:

Bottom Layer: System OSMaya Core: The entire Maya program written in C++Maya API: Designated API exposed to developers, which can access Maya CoreMaya Command: Helper Functions calling multiple Maya APIMaya GUI: User graphics interface

While Maya Command (MEL/Python) is most commonly used to write scripts, because it has fast prototyping and easy to learn. The downside is that it is often slow and can’t offer low level access to Maya Core.

Maya API on the other hand, is complicated, but offers faster speed and most flexibility. It comes with Python and C++. Python API has version 1.0 and 2.0.

difference between Python API vs C++ API

API1.0 vs 2.0

API 1.0 (Before 2012) has acess to more features offered in C++ API 2.0 faster and more pythonic, but some class such as OpenMayaFX, OpenMayaDeformerNode is not supported.

General Format

Plug-in Sample

API 1.0

import sys import maya.OpenMayaMPx as mpx import maya.OpenMaya as om pluginName = 'pyTemplate' sampleShortFlagName = '-s' sampleLongFlagName = '-sample' class PyTemplate(mpx.MPxCommand): def __init__(self): mpx.MPxCommand.__init__(self) def doIt(self, args): print 'doIt' self.parseArgument(args) self.redoIt() def redoIt(self): # this is optional print 'redoIt' def undoIt(self): # this is also optional print 'undoIt' def parseArgument(self, args): argData = om.MArgParser(self.syntax(), args) if argData.isFlagSet(sampleShortFlag): self.sample = argData.flagArgumentDouble(sampleShortFlag, 0) print self.sample def isUndoable(self): # this is required when undo and redo is available return True def cmdCreator(): return mpx.asMPxPtr(PyParticle()) def syntaxCreator(): # use this only when custom argument is defined syntax = om.MSyntax() syntax.addFlag(sampleShortName, sampleLongName, om.MSyntax.kDouble) return syntax def initializePlugin(mobject): mplugin = mpx.MFnPlugin(mobject) try: mplugin.registerCommand(pluginName, cmdCreator, syntaxCreator) except: sys.stderr.write('fail to register: ' + pluginName) raise def uninitializePlugin(mobject): mplugin = mpx.MFnPlugin(mobject) try: mplugin.deregisterCommand(pluginName) except: sys.stderr.write('fail to de-register: ' + pluginName) raise

API 2.0

import sys import maya.OpenMaya as om pluginName = 'pyTemplate' sampleShortFlagName = '-s' sampleLongFlagName = '-sample' def maya_useNewAPI(): pass class PyTemplate(mpx.MPxCommand): def __init__(self): mpx.MPxCommand.__init__(self) def doIt(self, args): print 'doIt' self.parseArgument(args) def parseArgument(self, args): argData = om.MArgParser(self.syntax(), args) if argData.isFlagSet(sampleShortFlag): self.sample = argData.flagArgumentDouble(sampleShortFlag, 0) print self.sample def cmdCreator(): return PyTemplate() def syntaxCreator(): syntax = om.MSyntax() syntax.addFlag(sampleShortName, sampleLongName, om.MSyntax.kDouble) return syntax def initializePlugin(mobject): mplugin = mpx.MFnPlugin(mobject) try: mplugin.registerCommand(pluginName, cmdCreator, syntaxCreator) except: sys.stderr.write('fail to register: ' + pluginName) raise def uninitializePlugin(mobject): mplugin = mpx.MFnPlugin(mobject) try: mplugin.deregisterCommand(pluginName) except: sys.stderr.write('fail to de-register: ' + pluginName) raise

Difference

import module 1.0 has a seperate maya.OpenMayaMPx along with maya.OpenMaya 2.0 has maya.api.OpenMaya including the original MPx commandmaya_useNewAPI 2.0 use this function to declare using API 2.0cmd creator 1.0 uses a MPx pointer object to point to instance of the class 2.0 director returns the instance of the classother syntax difference will be discussed later

Creating Command with Argument and Flags

Defination:“Flags” vs “Argument”

Take this as an example: cmds.group(‘circle1’, ‘sphere1’, name=‘group1’)     ‘circle1’ and ‘sphere1’ are arguments     name is the flag and ‘group1’ is the value

Another example: cmds.polyCube(sx=10, axis=[0, 0, 1])     no argument is specified     sx is the flag’s short name, subdivisionX is the flag’s long name     [0, 0, 1] is axis flag’s value, each individual number is called parameters

Procedure

step 1: Declare flag name outside the class

firstFlagShortName = '-f' firstFlagLongName = '-first' secondFlagShortName = '-s' secondFlagLongName = '-second' # more flags ...

step 2: Add flag and argument in syntax creator outside of class

(this syntax creator will be further included in the plugin initialize function)

def syntaxCreator(): '''create a OpenMaya.MSyntax object to store flags and argument''' syntax = om.MSyntax() '''add flags with short name, long name, and value type''' syntax.addFlag(firstFlagShortName, firstFlagLongName, om.MSyntax.kDouble) syntax.addFlag(secondFlagShortName, secondFlagLongName, (om.MSyntax.kDouble, om.MSyntax.kDouble, om.MSyntax.kDouble)) # add more flags ... '''add argument using MSyntax.addArg() function''' '''add argument is not discussed, refer to document later''' return syntax

step 3: Parsing Flags, called inside the class’s doIt function

def parseArguments(self, args): '''instanitiate MArgParser ojbect, self.syntax() refers to the syntax created in step 2''' argData = om.MArgParser(self.syntax(), args) '''check if certain flags are set''' if argData.isFlagSet(firstFlagShortName): firstValue = argData.flagArgumentString(firstFlagShortName, 0) if argData.isFlagSet(secondFlagShortName): secondParam0 = argData.flagArgumentInt(secondFlagShortName, 0) secondParam1 = argData.flagArgumentInt(secondFlagShortName, 1) secondParam2 = argData.flagArgumentInt(secondFlagShortName, 2) # parse more flags ...