A fast subset of maya.cmds
cmdx
is a Python wrapper for the Maya Python API 2.0 and a fast subset of the maya.cmds
module, with persistent references to nodes.
If you fit in either of these groups, then cmdx
is for you.
- You like
cmds
, but wish to type less - You like
PyMEL
, but wish it was faster
On average, cmdx
is 140x faster than PyMEL, and 2.5x faster than maya.cmds
at common tasks; at best, it is 1,300x faster than PyMEL.
- See Command Reference for technical details
- See Measurements and Timings for details
- See
help()
for examples on a particular command, e.g.help(cmdx.Node)
Date | Version | Event |
---|---|---|
Aug 2019 | 0.4.0 | Public release |
Feb 2018 | 0.1.0 | Extracted into its own repository |
Jun 2017 | 0.0.0 | Starts as an internal module |
Maya | Status |
---|---|
2015 | |
2016 | |
2017 | |
2018 |
cmdx
was written for performance critical run-time tasks in Maya, listening to thousands of events, reading from and writing to thousands of attributes each frame, without affecting user interactivity. It doesn't capture all of cmds
, but rather a small subset related to parts relevant to these types of performance critical tasks.
Usecase | Description |
---|---|
Real-time processing | Such as responding to user input without interruption |
Data intensive processing | Such as processing thousands of attributes on thousands of nodes at once |
Plug-in creation | Provides both superclasses and compatible API for performing most if not all calls in compute() or draw() using cmdx . |
cmdx is a single file and can either be copy/pasted into your project, downloaded as-is, cloned as-is or installed via pip
.
$ pip install cmdx
- Pro tip: Never use the latest commit for production. Instead, use the latest release. That way, when you read bug reports or make one for yourself you will be able to match a version with the problem without which you will not know which fixes apply to you nor would we be able to help you. Installing via pip or conda as above ensures you are provided the latest stable release. Unstable releases are suffixed with a
.b
, e.g.0.5.0.b1
.
With so many options for interacting with Maya, when or why should you choose cmdx
?
- Performance
- Declarative plug-ins
- Node and attribute reuse
- Transactions
- Hashable References
- Signals
- PEP8 Dual Syntax
Table of contents
- System Requirements
- Syntax
- Performance
- Goals
- Overhead
- Query Reduction
- Interoperability
- Units
- Node Types
- Node Creation
- Attribute Query and Assignment
- Connections
- Plug-ins
- Iterators
- Transactions
- Modifier
- Signals
- PEP8 Dual Syntax
- Comparison
- YAGNI
- Timings
- Measurements
- Evolution
- FAQ
- Debugging
- Flags
- References
- Notes
- Examples
cmdx
runs on Maya 2015 SP3 and above (SP2 does not work).
It may run on older versions too, but those are not being tested. To bypass the version check, see CMDX_IGNORE_VERSION
.
cmdx
supports the legacy syntax of maya.cmds
, along with an object-oriented syntax, similar to PyMEL.
Legacy
Familiar and fast.
>>> import cmdx
>>> joe = cmdx.createNode("transform", name="Joe")
>>> benji = cmdx.createNode("transform", name="myChild", parent=joe)
>>> cmdx.addAttr(joe, longName="myAttr", defaultValue=5.0, attributeType="double")
>>> cmdx.connectAttr(joe + ".myAttr", benji + ".tx")
>>> cmdx.setAttr(joe + ".myAttr", 5)
>>> cmdx.delete(joe)
Modern
Faster and most concise.
>>> import cmdx
>>> joe = cmdx.createNode("transform", name="Joe")
>>> benji = cmdx.createNode("transform", name="myChild", parent=joe)
>>> joe["myAttr"] = cmdx.Double(default=5.0)
>>> joe["myAttr"] >> benji["translateX"]
>>> joe["tx"] = 5
>>> cmdx.delete(joe)
Commands
createNode
getAttr
setAttr
addAttr
connectAttr
listRelatives
listConnections
Attribute Types
Double
Double3
Enum
String
Angle
Distance
Time
Message
Boolean
Divider
Long
Compound
NurbsCurve
cmdx
is fast, faster than cmds
by 2-5x and PyMEL by 5-150x, because of how it uses the Maya API 2.0, how classes are built and the (efficient) pre-processing happening on import.
See Measurements for performance statistics and comparisons between MEL, cmds, cmdx, PyMEL, API 1.0 and 2.0.
How?
The fastest you can possibly get with Python inside Maya is through the Maya Python API 2.0. cmdx
is a thin wrapper around this library that provides a more accessible and readable interface, whilst avoiding as much overhead as possible.
With PyMEL as baseline, these are the primary goals of this project, in order of importance.
Goal | Description |
---|---|
Fast | Faster than PyMEL, and cmds |
Lightweight | A single Python module, implementing critical parts well, leaving the rest to cmds |
Persistent | References to nodes do not break |
Do not crash | Working with low-level Maya API calls make it susceptible to crashes; cmdx should protect against this, without sacrificing performance |
No side effects | Importing cmdx has no affect any other module |
External | Shipped alongside your code, not alongside Maya; you control the version, features and fixes. |
Vendorable | Embed an appropriate version of cmdx alongside your own project |
PEP8 | Continuous integration ensures that every commit follows the consistency of PEP8 |
Examples | No feature is without examples |
cmdx
tracks node access via a Maya API callback. This callback is called on node destruction and carries an overhead to normal Maya operation when deleting nodes, most noticeably when creating a new scene (as it causes all nodes to be destroyed at once).
In the most extreme circumstance, with 100,000 nodes tracked by cmdx
, all nodes are destroyed in 4.4 seconds. Without this callback, the nodes are destroyed in 4.3 seconds.
This accounts for an overhead of 1 ms/node destroyed.
This overhead can be bypassed with Rogue Mode.
Test
To confirm this for yourself, run the below in your Script Editor; it should take about 30-60 seconds depending on your hardware.
# untested
import time
import timeit
import cmdx
import os
def setup():
for i in range(100000):
cmdx.createNode("transform")
def rogue():
os.environ["CMDX_ROGUE_MODE"] = "1"
cmds.file(new=True, force=True)
reload(cmdx)
setup()
def nonrogue():
os.environ.pop("CMDX_ROGUE_MODE", None)
cmds.file(new=True, force=True)
reload(cmdx)
setup()
t1 = timeit.Timer(
lambda: cmds.file(new=True, force=True),
setup=rogue
).repeat(repeat=2, number=2)
t2 = timeit.Timer(
lambda: cmds.file(new=True, force=True),
setup=nonrogue
).repeat(repeat=4, number=1)
print("rogue: %.3f ms" % (min(t1) * 1000))
print("nonrogue: %.3f ms" % (min(t2) * 1000))
Beyond making queries faster is making less of them.
Any interaction with the Maya API carries the overhead of translating from Python to C++ and, most of the time, back to Python again. So in order to make cmdx
fast, it must facilitate re-use of queries where re-use makes sense.
Any node created or queried via cmdx
is kept around until the next time the same node is returned, regardless of the exact manner in which it was queried.
For example, when encode
d or returned as children of another node.
>>> node = cmdx.createNode("transform", name="parent")
>>> cmdx.encode("|parent") is node
True
This property survives function calls too.
>>> def function1():
... return cmdx.createNode("transform", name="parent")
...
>>> def function2():
... return cmdx.encode("|parent")
...
>>> _ = cmds.file(new=True, force=True)
>>> function1() is function2()
True
In fact, regardless of how a node is queried, there is only ever a single instance in cmdx
of it. This is great for repeated queries to nodes and means nodes can contain an additional level of state, beyond the one found in Maya. A property which is used for, amongst other things, optimising plug reuse.
node = cmdx.createNode("transform")
node["translateX"] # Maya's API `findPlug` is called
node["translateX"] # Previously found plug is returned
node["translateX"] # Previously found plug is returned
node["translateX"] # ...
Whenever an attribute is queried, a number of things happen.
- An
MObject
is retrieved via string-comparison - A relevant plug is found via another string-comparison
- A value is retrieved, wrapped in a Maya API object, e.g. MDistance
- The object is cast to Python object, e.g. MDistance to
float
This isn't just 4 interactions with the Maya API, it's also 3 interactions with the Maya scenegraph. An interaction of this nature triggers the propagation and handling of the dirty flag, which in turn triggers a virtually unlimited number of additional function calls; both internally to Maya - i.e. the compute()
method and callbacks - and in any Python that might be listening.
With module level caching, a repeated query to either an MObject
or MPlug
is handled entirely in Python, saving on both time and computational resources.
In addition to reusing things internally, you are able to re-use things yourself by using nodes as e.g. keys to dictionaries.
>>> _ = cmds.file(new=True, force=True)
>>> node = cmdx.createNode("animCurveTA")
>>> nodes = {node: {"key": "value"}}
>>> for node in cmdx.ls(type="animCurveTA"):
... assert node in nodes
... assert nodes[node]["key"] == "value"
...
The hash of the node is guaranteed unique, and the aforementioned reuse mechanism ensure that however a node is referenced the same reference is returned.
Utilities
Here are some useful utilities that leverages this hash.
>>> import cmdx
>>> node = cmdx.createNode("transform")
>>> node == cmdx.fromHash(node.hashCode)
True
>>> node == cmdx.fromHex(node.hex)
True
These tap directly into the dictionary used to maintain references to each cmdx.Node
. The hashCode
is the one from maya.api.OpenMaya.MObjectHandle.hashCode()
, which means that if you have an object from the Maya Python API 2.0, you can fetch the cmdx
equivalent of it by passing its hashCode
.
However keep in mind that you can only retrieve nodes that have previously been access by cmdx
.
>>> from maya.api import OpenMaya as om
>>> fn = om.MFnDagNode()
>>> mobj = fn.create("transform")
>>> handle = om.MObjectHandle(mobj)
>>> assert_raises(KeyError, cmdx.fromHash, handle.hashCode())
>>> node = cmdx.Node(mobj)
>>> node = cmdx.fromHash(handle.hashCode())
A more robust alternative is to instead pass the MObject
directly.
from maya.api import OpenMaya as om
import cmdx
fn = om.MDagNode()
mobj = fn.create("transform")
node = cmdx.Node(mobj)
This will use the hash if a cmdx
instance of this MObject
already exist, else it will instantiate a new. The performance difference is slim and as such this is the recommended approach. The exception is if you happen to already has either an MObjectHandle
or a corresponding hashCode
at hand, in which case you can save a handful of cycles per call by using fromHash
or fromHex
.
For persistent metadata, one practice is to use a Maya string
attribute and store arbitrary data there, serialised to string.
For transient metadata however - data that doesn't need or should persist across sessions - you can rely on the node reuse mechanism of cmdx
.
# Get reference to existing node
node = cmdx.encode("|myNode")
node.data["myData"] = {
"awesome": True
}
This data is then preserved with the node for its lifetime. Once the node is destroyed - e.g. on deleting it or opening a new scene - the data is destroyed along with it.
The data is stored entirely in Python so there is no overhead of interacting with the Maya scenegraph per call or edit.
To make persistent data, you may for example associate a given ID with a file on disk or database path and automatically load the data into it on node creation.
...
cmdx
complements cmds
, but does not replace it.
Commands such as menuItem
, inViewMessage
and move
are left out and considered a convenience; not sensitive to performance-critical tasks such as generating nodes, setting or connecting attributes etc.
Hence interoperability, where necessary, looks like this.
from maya import cmds
import cmdx
group = cmds.group(name="group", empty=True)
cmds.move(group, 0, 50, 0)
group = cmdx.encode(group)
group["rotateX", cmdx.Radians] = 3.14
cmds.select(cmdx.decode(group))
An alternative to cmdx.decode
is to simply cast it to str
, which will convert a cmdx
node into the equivalent shortest path.
cmds.select(str(group))
Another aspect of cmdx
that differ from cmds
is the number arguments to functions, such as listConnections
and ls
.
from maya import cmds
import cmdx
node = cmdx.createNode("transform")
cmds.listConnections(str(node), source=True)
cmdx.listConnections(str(node), source=True)
TypeError: listConnections() got an unexpected keyword argument 'source'
The reason for this limitation is because the functions cmds
- Submit an issue or pull-request with commands you miss
cmdx
takes and returns values in the units used by the UI. For example, Maya's default unit for distances, such as translateX
is in Centimeters.
import cmdx
node = cmdx.createNode("transform")
node["translateX"] = 5
node["translateX"]
# 5
To return translateX
in Meters, you can pass in a unit explicitly.
node["translateX", cmdx.Meters]
# 0.05
To set translateX
to a value defined in Meters, you can pass that explicitly too.
node["translateX", cmdx.Meters] = 5
Or use the alternative syntax.
node["translateX"] = cmdx.Meters(5)
The following units are currently supported.
- Angular
Degrees
Radians
AngularMinutes
AngularSeconds
- Linear
Millimeters
Centimeters
Meters
Kilometers
Inches
Feet
Miles
Yards
Not all attribute editing supports units.
transform = cmdx.createNode("transform")
tm = transform["worldMatrix"][0].asTransformationMatrix()
# What unit am I?
tm.translation()
The same applies to orientation.
tm.rotation()
In circumstances without an option, cmdx takes and returns a default unit per type of plug, similar to maya.api
Defaults
Type | Unit |
---|---|
Linear | Centimeter |
Angular | Radian |
Time | Second |
All of this performance is great and all, but why hasn't anyone thought of this before? Are there no consequences?
I'm sure someone has, and yes there are.
With every command made through maya.cmds
, the undo history is populated such that you can undo a block of commands all at once. cmdx
doesn't do this, which is how it remains fast, but also impossible to undo. Any node created or attribute changed is permanent, which is why it is that much more important that you take care of the creations and changes that you make.
For undoable operations, see the section on using Modifier
.
...
Nodes are created much like with maya.cmds
.
import cmdx
cmdx.createNode("transform")
For a 5-10% performance increase, you may pass type as an object rather than string.
cmdx.createNode(cmdx.Transform)
Only the most commonly used and performance sensitive types are available as explicit types.
tAddDoubleLinear
tAddMatrix
tAngleBetween
tMultMatrix
tAngleDimension
tBezierCurve
tBlendShape
tCamera
tChoice
tChooser
tCondition
tTransform
tTransformGeometry
tWtAddMatrix
Unlike PyMEL and for best performance, cmdx
does not wrap each node type in an individual class. However it does wrap the those with a corresponding API function set.
Node Type | Features |
---|---|
Node |
Lowest level superclass, this host most of the functionality of cmdx |
DagNode |
A subclass of Node with added functinality related to hierarchy |
ObjectSet |
A subclass of Node with added functinality related to sets |
Any node that isn't a DagNode
or ObjectSet
is wrapped in this class, which provides the basic building blocks for manipulating nodes in the Maya scenegraph, including working with attributes and connections.
import cmdx
add = cmdx.createNode("addDoubleLinear")
mult = cmdx.createNode("multDoubleLinear")
add["input1"] = 1
add["input2"] = 1
mult["input1"] = 2
mult["input2"] << add["output"]
assert mult["output"] == 4
Any node compatible with the MFnDagNode
function set is wrapped in this class and faciliates a parent/child relationship.
import cmdx
parent = cmdx.createNode("transform")
child = cmdx.createNode("transform")
parent.addChild(child)
Any node compatible with the MFnSet
function set is wrapped in this class and provides a Python list-like interface for working with sets.
import cmdx
objset = cmdx.createNode("objectSet")
member = cmdx.createNode("transform")
objset.append(member)
for member in objset:
print(member)
NOTE:
MFnSet
was first introduced to the Maya Python API 2.0 in Maya 2016 and has been backported to work withcmdx
in Maya 2015, leveraging the equivalent functionality found in API 1.0. It does however mean that there is a performance impact in Maya <2016 of roughly 0.01 ms/node.
Attributes are accessed in a dictionary-like fashion.
import cmdx
node = cmdx.createNode("transform")
node["translateX"]
# 0.0
Evaluation of an attribute is delayed until the very last minute, which means that if you don't read the attribute, then it is only accessed and not evaluated and cast to a Python type.
attr = node["rx"]
The resulting type of an attribute is cmdx.Plug
type(attr)
# <class 'cmdx.Plug'>
Which has a number of additional methods for query and assignment.
attr.read()
# 0.0
attr.write(1.0)
attr.read()
# 1.0
attr.read()
is called when printing an attribute.
print(attr)
# 1.0
For familiarity, an attribute may also be accessed by string concatenation.
attr = node + ".tx"
Attributes about attributes, such as keyable
and channelBox
are native Python properties.
import cmdx
node = cmdx.createNode("transform")
node["translateX"].keyable = False
node["translateX"].channelBox = True
These also have convenience methods for use where it makes sense for readability.
# Hide from Channel Box
node["translateX"].hide()
Working with arrays is akin to the native Python list.
node = createNode("transform")
node["myArray"] = Double(array=True)
node["myArray"].append(1.0) # Explicit append
node["myArray"].extend([2.0, 3.0]) # Explicit extend
node["myArray"] += 6.0 # Append via __iadd__
node["myArray"] += [1.1, 2.3, 999.0] # Append multiple values
Sometimes, a value is queried when you know it hasn't changed since your last query. By passing cmdx.Cached
to any attribute, the previously computed value is returned, without the round-trip the the Maya API.
import cmdx
node = cmdx.createNode("transform")
node["tx"] = 5
assert node["tx"] == 5
node["tx"] = 10
assert node["tx", cmdx.Cached] == 5
assert node["tx"] == 10
Using cmdx.Cached
is a lot faster than recomputing the value, sometimes by several orders of magnitude depending on the type of value being queried.
The time
argument of cmdx.getAttr
enables a query to yield results relative a specific point in time. The time
argument of Plug.read
offers this same convenience, only faster.
import cmdx
from maya import cmds
node = cmdx.createNode("transform")
cmds.setKeyframe(str(node), attribute="tx", time=[1, 100], value=0.0)
cmds.setKeyframe(str(node), attribute="tx", time=[50], value=10.0)
cmds.keyTangent(str(node), attribute="tx", time=(1, 100), outTangentType="linear")
These both have children, and are accessed like a Python list.
node = cmdx.createNode("transform")
decompose = cmdx.createNode("decomposeMatrix")
node["worldMatrix"][0] >> decompose["inputMatrix"]
Array attributes are created by an additional argument.
node = cmdx.createNode("transform")
node["myArray"] = cmdx.Double(array=True)
Compound attributes are created as a group.
node = cmdx.createNode("transform")
node["myGroup"] = cmdx.Compound(children=(
cmdx.Double("myGroupX")
cmdx.Double("myGroupY")
cmdx.Double("myGroupZ")
))
Both array and compound attributes can be written via index or tuple assignment.
node["myArray"] = (5, 5, 5)
node["myArray"][1] = 10
node["myArray"][2]
# 5
Maya boasts a library of classes that provide mathematical convenience functionality, such as rotating a vector, multiplying matrices or converting between Euler degrees and Quaternions.
You can access these classes via the .as*
prefix of cmdx
instances.
import cmdx
nodeA = cmdx.createNode("transform")
nodeB = cmdx.createNode("transform", parent=nodeA)
nodeC = cmdx.createNode("transform")
nodeA["rotate"] = (4, 8, 15)
tmA = nodeB["worldMatrix"][0].asTransformationMatrix()
nodeC["rotate"] = tmA.rotation()
Now nodeC
will share the same worldspace orientation as nodeA
(note that nodeB
was not rotated).
One useful aspect of native types is that you can leverage their operators, such as multiplication.
matA = nodeA["worldMatrix"][0].asMatrix()
matB = nodeB["worldInverseMatrix"][0].asMatrix()
tm = cmdx.TransformationMatrix(matA * matB)
relativeTranslate = tm.translation()
relativeRotate = tm.rotation()
Maya's MVector
is exposed as cmdx.Vector
.
from maya.api import OpenMaya as om
import cmdx
vec = cmdx.Vector(1, 0, 0)
# Dot product
vec * cmdx.Vector(0, 1, 0) == 0.0
# Cross product
vec ^ cmdx.Vector(0, 1, 0) == om.MVector(0, 0, 1)
Maya's MEulerRotation
is exposed as cmdx.EulerRotation
and cmdx.Euler
Maya's MTransformationMatrix
is exposed as cmdx.TransformationMatrix
, cmdx.Transform
and cmdx.Tm
.
Editing the cmdx
version of a Tm is meant to be more readable and usable in maths operations.
import cmdx
from maya.api import OpenMaya as om
# Original
tm = om.MTransformationMatrix()
tm.setTranslation(om.MVector(0, 0, 0))
tm.setRotation(om.MEulerRotation(cmdx.radians(90), 0, 0, cmdx.kXYZ))
# cmdx
tm = cmdx.Tm()
tm.setTranslation((0, 0, 0))
tm.setRotation((90, 0, 0))
In this example, cmdx
assumes an MVector
on passing a tuple, and that when you specify a rotation you intended to use the same unit as your UI is setup to display, in most cases degrees.
In addition to the default methods, it can also do multiplication of vectors, to e.g. transform a point into the space of a given transform.
import cmdx
tm = cmdx.TransformationMatrix()
tm.setTranslation((0, 0, 0))
tm.setRotation((90, 0, 0))
pos = cmdx.Vector(0, 1, 0)
# Move a point 1 unit in Y, as though it was a child
# of a transform that is rotated 90 degrees in X,
# the resulting position should yield Z=1
newpos = tm * pos
assert newpos == cmdx.Vector(0, 0, 1)
Maya's MQuaternion
is exposed via cmdx.Quaternion
In addition to its default methods, it can also do multiplication with a vector.
q = Quaternion(0, 0, 0, 1)
v = Vector(1, 2, 3)
assert isinstance(q * v, Vector)
asDouble()
->float
asMatrix()
->MMatrix
asTransformationMatrix()
(aliasasTm()
) ->MTransformationMatrix
asQuaternion()
->MQuaternion
asVector
->MVector
Filter children by a search query, similar to MongoDB.
cmds.file(new=True, force=True)
a = createNode("transform", "a")
b = createNode("transform", "b", parent=a)
c = createNode("transform", "c", parent=a)
b["bAttr"] = Double(default=5)
c["cAttr"] = Double(default=12)
# Return children with this attribute only
a.child(query=["bAttr"]) == b
a.child(query=["cAttr"]) == c
a.child(query=["noExist"]) is None
# Return children with this attribute *and value*
a.child(query={"bAttr": 5}) == b
a.child(query={"bAttr": 1}) is None
# Search with multiple queries
a.child(query={
"aAttr": 12,
"visibility": True,
"translateX": 0.0,
}) == b
Sometimes, it only makes sense to query the children of a node for children with a shape of a particular type. For example, you may only interested in children with a shape node.
import cmdx
a = createNode("transform", "a")
b = createNode("transform", "b", parent=a)
c = createNode("transform", "c", parent=a)
d = createNode("mesh", "d", parent=c)
# Return children with a `mesh` shape
assert b.child(contains="mesh") == c
# As the parent has children, but none with a mesh
# the below would return nothing.
assert b.child(contains="nurbsCurve") != c
cmdx
supports reading and writing of geometry attributes via the *Data
family of functions.
Drawing a line
import cmdx
parent = cmdx.createNode("transform")
shape = cmdx.createNode("nurbsCurve", parent=parent)
shape["cached"] = cmdx.NurbsCurveData(points=((0, 0, 0), (0, 1, 0), (0, 2, 0)))
This creates a new nurbsCurve
shape and fills it with points.
Drawing an arc
Append the degree
argument for a smooth curve.
import cmdx
parent = cmdx.createNode("transform")
shape = cmdx.createNode("nurbsCurve", parent=parent)
shape["cached"] = cmdx.NurbsCurveData(
points=((0, 0, 0), (1, 1, 0), (0, 2, 0)),
degree=2
)
Drawing a circle
Append the form
argument for closed loop.
import cmdx
parent = cmdx.createNode("transform")
shape = cmdx.createNode("nurbsCurve", parent=parent)
shape["cached"] = cmdx.NurbsCurveData(
points=((0, 0, 0), (1, 1, 0), (0, 2, 0)),
degree=2,
form=cmdx.kClosed
)
Connect one attribute to another with one of two syntaxes, whichever one is the most readable.
a, b = map(cmdx.createNode, ("transform", "camera"))
# Option 1
a["translateX"] >> b["translateX"]
# Option 2
a["translateY"].connect(b["translateY"])
Legacy syntax is also supported, and is almost as fast - the overhead is one additional call to str.strip
.
cmdx.connectAttr(a + ".translateX", b + ".translateX")
cmdx
is fast enough for use in draw()
and compute()
of plug-ins. It also comes with a declarative method of writing Maya plug-ins. "Declarative" means that rather than writing instructions for your plug-in, you write a description of it.
Before
from maya.api import OpenMaya as om
class MyNode(om.MPxNode):
name = "myNode"
typeid = om.MTypeId(0x85006)
@staticmethod
def initializer():
tAttr = om.MFnTypedAttribute()
MyNode.myString = tAttr.create(
"myString", "myString", om.MFnData.kString)
tAttr.writable = True
tAttr.storable = True
tAttr.hidden = True
tAttr.array = True
mAttr = om.MFnMessageAttribute()
MyNode.myMessage = mAttr.create("myMessage", "myMessage")
mAttr.writable = True
mAttr.storable = True
mAttr.hidden = True
mAttr.array = True
xAttr = om.MFnMatrixAttribute()
MyNode.myMatrix = xAttr.create("myMatrix", "myMatrix")
xAttr.writable = True
xAttr.storable = True
xAttr.hidden = True
xAttr.array = True
uniAttr = om.MFnUnitAttribute()
MyNode.currentTime = uniAttr.create(
"currentTime", "ctm", om.MFnUnitAttribute.kTime, 0.0)
MyNode.addAttribute(MyNode.myString)
MyNode.addAttribute(MyNode.myMessage)
MyNode.addAttribute(MyNode.myMatrix)
MyNode.addAttribute(MyNode.currentTime)
MyNode.attributeAffects(MyNode.myString, MyNode.myMatrix)
MyNode.attributeAffects(MyNode.myMessage, MyNode.myMatrix)
MyNode.attributeAffects(MyNode.currentTime, MyNode.myMatrix)
After
Here is the equivalent plug-in, written with cmdx
.
import cmdx
class MyNode(cmdx.DgNode):
name = "myNode"
typeid = cmdx.MTypeId(0x85006)
attributes = [
cmdx.String("myString"),
cmdx.Message("myMessage"),
cmdx.Matrix("myMatrix"),
cmdx.Time("myTime", default=0.0),
]
affects = [
("myString", "myMatrix"),
("myMessage", "myMatrix"),
("myTime", "myMatrix"),
]
Defaults can either be specified as an argument to the attribute, e.g. cmdx.Double("MyAttr", default=5.0)
or in a separate dictionary.
This can be useful if you need to synchronise defaults between, say, a plug-in and external physics simulation software and if you automatically generate documentation from your attributes and need to access their defaults from another environment, such as sphinx.
import cmdx
import external_library
class MyNode(cmdx.DgNode):
name = "myNode"
typeid = cmdx.MTypeId(0x85006)
defaults = external_library.get_defaults()
attributes = [
cmdx.String("myString"),
cmdx.Message("myMessage"),
cmdx.Matrix("myMatrix"),
cmdx.Time("myTime"),
]
Where defaults
is a plain dictionary.
import cmdx
class MyNode(cmdx.DgNode):
name = "myNode"
typeid = cmdx.MTypeId(0x85006)
defaults = {
"myString": "myDefault",
"myTime": 1.42,
}
attributes = [
cmdx.String("myString"),
cmdx.Message("myMessage"),
cmdx.Matrix("myMatrix"),
cmdx.Time("myTime"),
]
This can be used with libraries such as jsonschema
, which is supported by other languages and libraries like C++ and sphinx.
cmdx
exposes the native math libraries of Maya, and extends these with additional functionality useful for drawing to the viewport.
import cmdx
from maya.api import OpenMaya as om
from maya import OpenMayaRender as omr1
renderer = omr1.MHardwareRenderer.theRenderer()
gl = renderer.glFunctionTable()
maya_useNewAPI = True
class MyNode(cmdx.LocatorNode):
name = "myNode"
classification = "drawdb/geometry/custom"
typeid = cmdx.TypeId(0x13b992)
attributes = [
cmdx.Distance("Length", default=5)
]
def draw(self, view, path, style, status):
this = cmdx.Node(self.thisMObject())
length = this["Length", cmdx.Cached].read()
start = cmdx.Vector(0, 0, 0)
end = cmdx.Vector(length, 0, 0)
gl.glBegin(omr1.MGL_LINES)
gl.glColor3f(0.1, 0.65, 0.0)
gl.glVertex3f(start.x, start.y, start.z)
gl.glVertex3f(end.x, end.y, end.z)
gl.glEnd()
view.endGL()
def isBounded(self):
return True
def boundingBox(self):
this = cmdx.Node(self.thisMObject())
multiplier = this["Length", cmdx.Meters].read()
corner1 = cmdx.Point(-multiplier, -multiplier, -multiplier)
corner2 = cmdx.Point(multiplier, multiplier, multiplier)
return cmdx.BoundingBox(corner1, corner2)
initializePlugin = cmdx.initialize(MyNode)
uninitializePlugin = cmdx.uninitialize(MyNode)
Of interest is the..
cmdx.Node(self.thisMObject())
A one-off (small) cost, utilising the Node Re-use mechanism ofcmdx
to optimise instantiation of new objects.- Attribute access via
["Length"]
, fast and readable compared to itsOpenMaya
equivalent - Custom units via
["Length", cmdx.Meters]
- Custom vectors via
cmdx.Vector()
- Attribute value re-use, via
cmdx.Cached
.boundingBox
is called first, computing the value ofLength
, which is later re-used indraw()
; saving on previous FPS
Generate templates from your plug-ins automatically.
Any method on a Node
returning multiple values do so in the form of an iterator.
a = cmdx.createNode("transform")
b = cmdx.createNode("transform", parent=a)
c = cmdx.createNode("transform", parent=a)
for child in a.children():
pass
Because it is an iterator, it is important to keep in mind that you cannot index into it, nor compare it with a list or tuple.
a.children()[0]
ERROR
a.children() == [b, c]
False # The iterator does not equal the list, no matter the content
From a performance perspective, returning all values from an iterator is equally fast as returning them all at once, as cmds
does, so you may wonder why do it this way?
It's because an iterator only spends time computing the values requested, so returning any number less than the total number yields performance benefits.
i = a.children()
assert next(i) == b
assert next(i) == c
For convenience, every iterator features a corresponding "singular" version of said iterator for readability.
assert a.child() == b
More iterators
a.children()
a.connections()
a.siblings()
a.descendents()
cmdx
supports the notion of an "atomic commit", similar to what is commonly found in database software. It means to perform a series of commands as though they were one.
The differences between an atomic and non-atomic commit with regards to cmdx
is the following.
- Commands within an atomic commit are not executed until committed as one
- An atomic commit is undoable as one
(1) means that if a series of commands where to be "queued", but not committed, then the Maya scenegraph remains unspoiled. It also means that executing commands is faster, as they are merely added to the end of a series of commands that will at some point be executed by Maya, which means that if one of those commands should fail, you will know without having to wait for Maya to spend time actually performing any of the actions.
Known Issues
It's not all roses; in order of severity:
- Errors are not known until finalisation, which can complicate debugging
- Errors are generic; they don't mention what actually happened and only says
RuntimeError: (kFailure): Unexpected Internal Failure #
- Not all attribute types can be set using a modifier
- Properties of future nodes are not known until finalisation, such as its name, parent or children
Modifiers in cmdx
extend the native modifiers with these extras.
- Automatically undoable Like
cmds
- Transactional Changes are automatically rolled back on error, making every modifier atomic
- Debuggable Maya's native modifier throws an error without including what or where it happened.
cmdx
provides detailed diagnostics of what was supposed to happen, what happened, attempts to figure out why and what line number it occurred on. - Name templates Reduce character count by delegating a "theme" of names across many new nodes.
For example.
import cmdx
with cmdx.DagModifier() as mod:
node1 = mod.createNode("transform")
node2 = mod.createNode("transform", parent=node1)
mod.connect(node1 + ".translate", node2 + ".translate")
mod.setAttr(node1 + ".rotate", (1, 2, 3))
Now when calling undo
, the above lines will be undone as you'd expect.
If you prefer, modern syntax still works here.
with cmdx.DagModifier() as mod:
parent = mod.createNode("transform", name="MyParent")
child = mod.createNode("transform", parent=parent)
parent["translate"] = (1, 2, 3)
parent["rotate"] >> parent["rotate"]
And PEP8.
with cmdx.DagModifier() as mod:
parent = mod.create_node("transform", name="MyParent")
child = mod.create_node("transform", parent=parent)
parent["translate"] = (1, 2, 3)
parent["rotate"] >> parent["rotate"]
Name templates look like this.
with cmdx.DagModifier(template="myName_{type}"):
node = mod.createNode("transform")
assert node.name() == "myName_transform"
This makes it easy to move a block of code into a modifier without changing things around. Perhaps to test performance, or to figure out whether undo support is necessary.
The modifier is quite limited in what features it provides; in general, it can only modify the scenegraph, it cannot query it.
- It cannot read attributes
- It cannot set complex attribute types, such as meshes or nurbs curves
- It cannot query a future hierarchy, such as asking for the parent or children of a newly created node
Furthermore, there are a few limitations with regards to modern syntax.
- It cannot connect an existing attribute to one on a newly node, e.g.
existing["tx"] >> new["tx"]
- ...
Maya offers a large number of callbacks for responding to native events in your code. cmdx
wraps some of these in an alternative interface akin to Qt Signals and Slots.
import cmdx
def onDestroyed():
pass
node = cmdx.createNode("transform")
node.onDestroyed.append(onDestroyed)
Write in either Maya-style mixedCase
or PEP8-compliant snake_case
where it makes sense to do so. Every member of cmdx
and its classes offer a functionally identical snake_case
alternative.
Example
import cmdx
# Maya-style
cmdx.createNode("transform")
# PEP8
cmdx.create_node("transform")
When to use
Consistency aids readability and comprehension. When a majority of your application is written using mixedCase
it makes sense to use it with cmdx
as well. And vice versa.
This section explores the relationship between cmdx
and (1) MEL, (2) cmds, (3) PyMEL and (4) API 1/2.
Maya's Embedded Language (MEL) makes for a compact scene description format.
createNode transform -n "myNode"
setAttr .tx 12
setAttr .ty 9
On creation, a node is "selected" which is leveraged by subsequent commands, commands that also reference attributes via their "short" name to further reduce file sizes.
A scene description never faces naming or parenting problems the way programmers do. In a scene description, there is no need to rename nor reparent; a node is created either as a child of another, or not. It is given a name, which is unique. No ambiguity.
From there, it was given expressions, functions, branching logic and was made into a scripting language where the standard library is a scene description kit.
cmds
is tedious and pymel
is slow. cmds
is also a victim of its own success. Like MEL, it works with relative paths and the current selection; this facilitates the compact file format, whereby a node is created, and then any references to this node is implicit in each subsequent line. Long attribute names have a short equivalent and paths need only be given at enough specificity to not be ambiguous given everything else that was previously created. Great for scene a file format, not so great for code that operates on-top of this scene file.
PyMEL is 31,000 lines of code, the bulk of which implements backwards compatibility to maya.cmds
versions of Maya as far back as 2008, the rest reiterates the Maya API.
Line count
PyMEL has accumulated a large number of lines throughout the years.
root@0e540f42ee9d:/# git clone https://github.com/LumaPictures/pymel.git
Cloning into 'pymel'...
remote: Counting objects: 21058, done.
remote: Total 21058 (delta 0), reused 0 (delta 0), pack-reused 21058
Receiving objects: 100% (21058/21058), 193.16 MiB | 15.62 MiB/s, done.
Resolving deltas: 100% (15370/15370), done.
Checking connectivity... done.
root@0e540f42ee9d:/# cd pymel/
root@0e540f42ee9d:/pymel# ls
CHANGELOG.rst LICENSE README.md docs examples extras maintenance maya pymel setup.py tests
root@0e540f42ee9d:/pymel# cloc pymel/
77 text files.
77 unique files.
8 files ignored.
http://cloc.sourceforge.net v 1.60 T=0.97 s (71.0 files/s, 65293.4 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
Python 67 9769 22410 31251
DOS Batch 2 0 0 2
-------------------------------------------------------------------------------
SUM: 69 9769 22410 31253
-------------------------------------------------------------------------------
Another wrapping of the Maya API is MRV, written by independent developer Sebastian Thiel for Maya 8.5-2011, and Metan
Unlike cmdx
and PyMEL, MRV (and seemingly Metan) exposes the Maya API as directly as possible.
See the Comparison page for more details.
The Maya Ascii file format consists of a limited number of MEL commands that accurately and efficiently reproduce anything you can achieve in Maya. This format consists of primarily 4 commands.
createNode
addAttr
setAttr
connectAttr
You'll notice how there aren't any calls to reparent, rename otherwise readjust created nodes. Nor are there high-level commands such as cmds.polySphere
or cmds.move
. These 4 commands is all there is to represent the entirety of the Maya scenegraph; including complex rigs, ugly hacks and workarounds by inexperienced and seasoned artists alike.
The members of cmdx
is a reflection of this simplicity.
However, convenience members make for more readable and maintainable code, so a balance must be struck between minimalism and readability. This balance is captured in cmdx.encode
and cmdx.decode
which acts as a bridge between cmds
and cmdx
. Used effectively, you should see little to no performance impact when performing bulk-operations with cmdx
and passing the resulting nodes as transient paths to cmds.
cmdx
is on average 142.89x
faster than PyMEL
on these common tasks.
Times | Task | |
---|---|---|
cmdx is | 2.2x faster | addAttr |
cmdx is | 4.9x faster | setAttr |
cmdx is | 7.5x faster | createNode |
cmdx is | 2.6x faster | connectAttr |
cmdx is | 50.9x faster | long |
cmdx is | 16.6x faster | getAttr |
cmdx is | 19.0x faster | node.attr |
cmdx is | 11.3x faster | node.attr=5 |
cmdx is | 1285.6x faster | import |
cmdx is | 148.7x faster | listRelatives |
cmdx is | 22.6x faster | ls |
cmdx
is on average 2.53x
faster than cmds
on these common tasks.
Times | Task | |
---|---|---|
cmdx is | 1.4x faster | addAttr |
cmdx is | 2.3x faster | setAttr |
cmdx is | 4.8x faster | createNode |
cmdx is | 2.1x faster | connectAttr |
cmdx is | 8.0x faster | long |
cmdx is | 1.8x faster | getAttr |
cmdx is | 0.0x faster | import |
cmdx is | 1.8x faster | listRelatives |
cmdx is | 0.5x faster | ls |
Run
plot.py
to reproduce these numbers.
Below is a performance comparisons between the available methods of manipulating the Maya scene graph.
MEL
cmds
cmdx
PyMEL
API 1.0
API 2.0
Surprisingly, MEL
is typically outdone by cmds
. Unsurprisingly, PyMEL
performs on average 10x slower than cmds
, whereas cmdx
performs on average 5x faster than cmds
.
Shorter is better.
Both cmdx
and PyMEL perform some amount of preprocessing on import.
Retrieving the long name of any node, e.g. cmds.ls("node", long=True)
.
Both cmdx
and PyMEL offer an object-oriented interface for reading and writing attributes.
# cmdx
node["tx"].read()
node["tx"].write(5)
# PyMEL
pynode.tx().get()
pynode.tx().set(5)
cmdx
started as a wrapper for cmds
where instead of returning a transient path to nodes, it returned the new UUID attribute of Maya 2016 and newer. The benefit was immediate; no longer had I to worry about whether references to any node was stale. But it impacted negatively on performance. It was effectively limited to the performance of cmds
plus the overhead of converting to/from the UUID of each absolute path.
The next hard decision was to pivot from being a superset of cmds
to a subset; to rather than wrapping the entirety of cmds
instead support a minimal set of functionality. The benefit of which is that more development and optimisation effort is spent on less functionality.
These are some of the resources used to create this project.
Why is it crashing?
cmdx
should never crash (if it does, please submit a bug report!), but the cost of performance is safety. maya.cmds
rarely causes a crash because it has safety procedures built in. It double checks to ensure that the object you operate on exists, and if it doesn't provides a safe warning message. This double-checking is part of what makes maya.cmds
slow; conversely, the lack of it is part of why cmdx
is so fast.
Common causes of a crash is:
- Use of a node that has been deleted
- ... (add your issue here)
This can happen when, for example, you experiment in the Script Editor, and retain access to nodes created from a different scene, or after the node has simply been deleted.
Can I have attribute access via ".", e.g.
myNode.translate
?
Unfortunately not, it isn't safe.
The problem is how it shadows attribute access for attributes on the object itself with attributes in Maya. In the above example, translate
could refer to a method that translates a given node, or it could be Maya's .translate
attribute. If there isn't a method in cmdx
to translate a node today, then when that feature is introduced, your code would break.
Furthermore it makes the code more difficult to read, as the reader won't know whether an attribute is referring to an Maya attribute or an attribute or method on the object.
With the dictionary access - e.g. myNode["translate"]
, there's no question about this.
Why is PyMEL slow?
...
Doesn't PyMEL also use the Maya API?
Yes and no. Some functionality, such as listRelatives
call on cmds.listRelatives
and later convert the output to instances of PyNode
. This performs at best as well as cmds
, with the added overhead of converting the transient path to a PyNode
.
Other functionality, such as pymel.core.datatypes.Matrix
wrap the maya.api.OpenMaya.MMatrix
class and would have come at virtually no cost, had it not inherited 2 additional layers of superclasses and implemented much of the computationally expensive functionality in pure-Python.
Either whilst developing for or with cmdx
, debugging can come in handy.
For performance, you might be interested in CMDX_TIMINGS below. For statistics on the various types of reuse, have a look at this.
import cmdx
cmdx.createNode("transform", name="MyTransform")
cmdx.encode("|MyTransform")
print(cmdx.NodeReuseCount)
# 0
cmdx.encode("|MyTransform")
cmdx.encode("|MyTransform")
print(cmdx.NodeReuseCount)
# 2
Available Statistics
Gathering these members are cheap and happens without setting any flags.
cmdx.NodeReuseCount
cmdx.NodeInitCount
cmdx.PlugReuseCount
For performance and debugging reasons, parts of cmdx
can be customised via environment variables.
IMPORTANT - The below affects only the performance and memory characteristics of
cmdx
, it does not affects its functionality. That is to say, these can be switched on/off without affecting or require changes to your code.
Example
$ set CMDX_ENABLE_NODE_REUSE=1
$ mayapy
NOTE: These can only be changed prior to importing or reloading
cmdx
, as they modify the physical layout of the code.
This opt-in variable enables cmdx
to keep track of any nodes it has instantiated in the past and reuse its instantiation in order to save time. This will have a neglible impact on memory use (1 mb/1,000,000 nodes)
node = cmdx.createNode("transform", name="myName")
assert cmdx.encode("|myName") is node
Like node reuse, this will enable each node to only ever look-up a plug once and cache the results for later use. These two combined yields a 30-40% increase in performance.
Print timing information for performance critical sections of the code. For example, with node reuse, this will print the time taken to query whether an instance of a node already exists. It will also print the time taken to create a new instance of said node, such that they may be compared.
WARNING: Use sparingly, or else this can easily flood your console.
Do not bother cleaning up after yourself. For example, callbacks registered to keep track of when a node is destroyed is typically cleaned up in order to avoid leaking memory. This however comes at a (neglible) cost which this flag prevents.
cmdx
was written with Maya 2015 SP3 and above in mind and will check on import whether this is true to avoid unexpected side-effects. If you are sure an earlier version will work fine, this variable can be set to circumvent this check.
If you find this to be true, feel free to submit a PR lowering this constant!
In order to save on performance, cmdx
holds onto MObject
and MFn*
instances. However this is discouraged in the Maya API documentation and can lead to a number of problems unless handled carefully.
The carefulness of cmdx
is how it monitors the destruction of any node via the MNodeMessage.addNodeDestroyedCallback
and later uses the result in access to any attribute.
For example, if a node has been created..
node = cmdx.createNode("transform")
And a new scene created..
cmds.file(new=True, force=True)
Then this reference is no longer valid..
node.name()
Traceback (most recent call last):
...
ExistError: "Cannot perform operation on deleted node"
Because of the above callback, this will throw a cmdx.ExistError
(inherits RuntimeError
).
This callback, and checking of whether the callback has been called, comes at a cost which "Rogue Mode" circumvents. In Rogue Mode, the above would instead cause an immediate and irreversible fatal crash.
The existence of this variable disables any of the above optimisations and runs as safely as possible.
Additional thoughts.
createNode
of OpenMaya.MDagModifier
is ~20% faster than cmdx.createNode
excluding load. Including load is 5% slower than cmdx
.
from maya.api import OpenMaya as om
mod = om.MDagModifier()
def prepare():
New()
for i in range(10):
mobj = mod.createNode(cmdx.Transform)
mod.renameNode(mobj, "node%d" % i)
def createManyExclusive():
mod.doIt()
def createManyInclusive():
mod = om.MDagModifier()
for i in range(10):
mobj = mod.createNode(cmdx.Transform)
mod.renameNode(mobj, "node%d" % i)
mod.doIt()
def createMany(number=10):
for i in range(number):
cmdx.createNode(cmdx.Transform, name="node%d" % i)
Test("API 2.0", "createNodeBulkInclusive", createManyInclusive, number=1, repeat=100, setup=New)
Test("API 2.0", "createNodeBulkExclusive", createManyExclusive, number=1, repeat=100, setup=prepare)
Test("cmdx", "createNodeBulk", createMany, number=1, repeat=100, setup=New)
# createNodeBulkInclusive API 2.0: 145.2 ms (627.39 µs/call)
# createNodeBulkExclusive API 2.0: 132.8 ms (509.58 µs/call)
# createNodeBulk cmdx: 150.5 ms (620.12 µs/call)
One-off examples using cmdx
.
Zeroing out rotate
by moving them to jointOrient
.
from maya import cmds
import cmdx
for joint in cmdx.ls(selection=True, type="joint"):
joint["jointOrient", cmdx.Degrees] = joint["rotate"]
joint["rotate"] = 0
Transferring the orientation of a series of joints to the jointOrient