Maya - Using the Python API
The Python API is contained in the maxwell
module. Importing this module does not try to load the API, so it's safe to do it at any time. However, calling most functions can throw the maxwell.APILoadError
exception if the Maxwell plug-in is not loaded or cannot be opened. The only functions which can be called when Maxwell is not present are those that are static in the C++ API (e.g. the callback methods described in the previous section).
Most Python functions have identical return types and arguments as their C++ counterparts, with two notable exceptions: the MString
class is replaced by regular Python strings, and Maya array classes are replaced with plain Python lists of the contained type (e.g. a list of MVector
objects instead of MVectorArray
). Functions which return boolean values in the C++ API to indicate success or failure raise exceptions instead in Python. The Create* methods from MaxwellMayaAPI
are replaced by calling the constructors of the respective types directly. A few methods are changed so that they work in a manner which is better suited to the Python programming practices (e.g., the GetNumLayers
and GetLayer
methods have been replaced by a single GetLayers
method which returns a list of layers in the material). This documentation will describe the methods using the C++ syntax, noting Python differences where they exist.
Since the API classes are contained in a module, the MaxwellMaya
prefix used in the C++ names is not necessary. For example, the Python equivalent of the MaxwellMayaCamera
C++ class is simply maxwell.Camera
.
All the enum values declared in MaxwellMayaAPI.h
exist as numeric constants in the maxwell
module, regardless of the class in which they were contained in C++. For example, the material layer blending modes can be accessed as maxwell.BlendMode_Normal
and maxwell.BlendMode_Additive
, even though in C++ they were declared inside the MaxwellMayaMaterialLayer
class.
All the methods raise maxwell.Error
or an exception derived from it (this does not cover Python runtime errors, such as passing the wrong number of arguments to a function). The subclasses of this are:
APILoadError
: the Maxwell plug-in is not present or there's a mismatch between the Python API and the C++ API (the latter indicates an installation problem).ExporterStateError
: the function call is invalid in the current state of the exporter. For example, you can only create meshes when the exporter is running.ParameterError
: an invalid parameter was passed, e.g. declaring that a mesh has 10 vertices and then only passing 9 inSetPositions
.
maxwell.Error
is thrown directly (e.g. out of memory conditions, or I/O error while trying to read a material from a MXM file). The string value of all the exception objects contains a human-readable description of the error.