A fast subset of <a href=http://help.autodesk.com/cloudhelp/2018/ENU/Maya-Tech-Docs/CommandsPython/index.html><code>maya.cmds</code></a> For Maya 2018-2025

About

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)

News

| Date | Version | Event |:---------|:----------|:---------- | Dec 2023 | 0.6.3 | Cloning of attributes | Apr 2020 | 0.6.0 | Stable Undo/Redo, dropped support for Maya 2015-2016 | Mar 2020 | 0.5.1 | Support for Maya 2022 | Mar 2020 | 0.5.0 | Stable release | 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

Status

| Maya | Status |:----------|:---- | 2017 | | 2018 | | 2019 | | 2020 | | 2022 |

Usecases

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.

Install

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.

Vendoring

Note: Advanced topic, you can skip this

Unlike PyMEL and cmds, cmdx is designed to be distributed alongside your tool. That means multiple copies of cmdx can coincide within the same Maya/Python session. But because the way Undo/Redo is handled, the cmdx.py module is also loaded as a Maya command plug-in.

You can either ignore this, things to look out for is errors during undo coming from another tool or global module directory, even though the command came from your tool. Alternatively, you can follow this recommendation.

mytool/
    vendor/
        __init__.py
        cmdx_mytool.py

From here, you can either from .vendor import cmdx_mytool as cmdx or you can put the following into the __init__.py of the vendor/ package.

from . import cmdx_mytool as cmdx

This would then allow your users to call..

from mytool.vendor import cmdx

..as though the module was called just cmdx.py.

What is novel?

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
PEP8 Dual Syntax

Table of contents

System Requirements
Syntax
Performance
Goals
Overhead
Query Reduction
- Node Reuse
- Plug Reuse
- Hashable References
- Metadata
Interoperability
Units
Node Types
Node Creation
Attribute Query and Assignment
- Meta Attributes
- Arrays
- Cached
- Time
- Native Types
- Contains
Connections
Plug-ins
- Defaults
- Draw
- Compute
- Manipulators
Iterators
Transactions
Modifier
Signals
PEP8 Dual Syntax
Comparison
- MEL
- PyMEL
- cmds
- API 1.0
- API 2.0
- MRV
- metan
YAGNI
Timings
Measurements
- Overall Performance
- import
- createNode
- getAttr
- setAttr
- connectAttr
- long
- node
- ls
Evolution
FAQ
Debugging
Flags
- CMDX_ENABLE_NODE_REUSE
- CMDX_ENABLE_PLUG_REUSE
- CMDX_ENABLE_UNDO
- CMDX_TIMINGS
- CMDX_MEMORY_HOG_MODE
- CMDX_IGNORE_VERSION
- CMDX_ROGUE_MODE
- CMDX_SAFE_MODE
References
Notes
- MDagModifier
Examples

System Requirements

cmdx runs on Maya 2017 above.

It may run on older versions too, but those are not being tested. To bypass the version check, see CMDX_IGNORE_VERSION.

Syntax

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

Performance

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.

Goals

With PyMEL as baseline, these are the primary goals of this project, in order of importance.

| Goal | Description |:----------------|:------------- | Readable | For code that is read more than it is written | 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

Cmdx

Install / Use

README