AL.omx

AL.omx contains all the public-facing APIs. They will be carefully maintained.

class AL.omx.JournalContext(state=True)

Bases: object

A python context where you set the journal state by force.

Notes:

Turning on by calling setJournalToggle(True)() will slowdown omx performance globally. This is the suggested way to have the journal temporarily set to on/off.

__init__(state=True)

class AL.omx.TrackCreatedNodes

Bases: object

A Python Context Decorator to temporarily track nodes that have been created with omx

Examples:

# The class can be used as decorator, or python context:

@TrackCreatedNodes()
def methodToCreateNodes():
    # Create nodes
    nodesCreated = omx.queryTrackedNodes()

def methodToCreateNodes():
    with TrackCreatedNodes() as tracker:
        # Create nodes
        nodesCreated = tracker.trackedNodes()

trackedNodes(queryAll=False)

Get the om2.MObjectHandle(s) created that are tracked.

Args:

queryAll (bool, optional): Whether return all batches of om2.MObjectHandles or just the last batch.

Returns:

[om2.MObjectHandle]: Created nodes.

class AL.omx.XAttrType(*values)

Bases: IntFlag

A high-level type of a XPlug attribute in the OMX system.

Args:

enum (int, XAttrType): the enum value.

Notes:

Do not store and use the integer values of these constants directly, as they are not guaranteed unchanged in future versions. Also, it simplifies all the type constants defined in Maya API and provides a set of high-level enums whose values can be map to multiple constants in om2.MFnData.Type, om2.MFnUnitAttribute.Type, om2.MFnNumericData.Type, etc.

ADDR = 128

ALL = 35184372088832

All the attribute types supported in Maya.

ANGLE = 256

ANY = 536870912

ARRAY = 35635200

BOOL = 1

BYTE = 2

CHAR = 4

COMPOUND = 4294967296

DISTANCE = 512

DOUBLE = 64

DOUBLE2 = 2199023255552

DOUBLE3 = 4398046511104

DOUBLE4 = 8796093022208

DOUBLE_ARRAY = 32768

DYN_ARRAY = 33554432

ENUM = 1073741824

FLOAT = 32

FLOAT2 = 549755813888

FLOAT3 = 1099511627776

FLOATING = 96

FLOAT_ARRAY = 65536

GENERIC = 8589934592

INT = 16

INT also includes INT, LONG and INT64, as they are all int in Python.

INT2 = 137438953472

INT2 includes LONG2

INT3 = 274877906944

INT3 includes LONG3

INT_ARRAY = 131072

LATTICE = 4194304

LIGHT_DATA = 17179869184

MATRIX = 8192

MATRIX_ARRAY = 1048576

MESH = 2097152

MESSAGE = 2147483648

NID = 268435456

NOBJECT = 134217728

NUMERIC = 17454747091071

NURBS_CURVE = 8388608

OTHERS = 17592186044416

PLUGIN = 2048

PLUGIN includes PLUGIN_GEOMETRY.

POINT_ARRAY = 262144

SHORT = 8

SHORT2 = 34359738368

SHORT3 = 68719476736

SPHERE = 16777216

STRING = 4096

STRING_ARRAY = 16384

SUBD_SURFACE = 67108864

TIME = 1024

TYPED = 1073739776

UNIT = 1792

VECTOR = 17454747090944

VECTOR_ARRAY = 524288

matches(plug)

Check if the plug matches this attribute type.

Notes:

You can use bitwise OR operator to combine multiple types together and use it to check if the plug matches any of the types, for example: XAttrType.INT | XAttrType.FLOAT

Args:

plug (om2.MPlug | omx.XPlug): The plug to check.

Returns:

bool: True if the plug matches this attribute type, False otherwise.

class AL.omx.XFn(obj)

Bases: object

Easy wrapper around om2 MFn* mainly to query and edit MObject. This is served as a convenient replacement of om2.MFn classes.

__eq__(other)

Add support for XNode comparison.

__hash__()

Add support for using XNode for containers that require uniqueness, e.g. dict key.

__init__(obj)

Creates a new XFn

Args:

obj (om2.MObject | XNode | om2.MFnBase | string): A object to wrap

Returns:

XFn: An instance of a XFn object

__ne__(other)

Add support for XNode comparison.

__repr__()

Get the more unambiguous str representation. This is mainly for debugging purposes.

Returns:

str

__str__()

Returns an easy-readable str representation of this XNode.

Construct a minimum unique path to support duplicate MObjects in scene. For invalid MObject we return the last known name with a suffix (dead) or (invalid) respectively.

Returns:

str: the string representation.

getChild(index)

Get the child DAG node by index.

Raises:

RuntimeErrors: if it is not a DAG node, or there is no such child at the index.

Args:

index (int): The index of child.

Returns:

omx.XNode: the child XNode.

getFullPath()

Return the full path of the DAG node, or name for the DG node.

getMFnClass()

Return the actual om2.MFn* class that is used by this XFn

Returns:

type: The om2.MFn* class object.

getName(namespaced=True)

Return the name of the node.

Args:

namespaced (bool): Whether we return namspaced or unnamespaced.

getNamespace()

Return the namespace of the node.

getParent(index=0)

Get the DAG parent by index.

Raises:

RuntimeErrors: if it is not a DAG node, or there is no such parent at the index.

Args:

index (int): The index of parent. Default to 0 as most of time we ask for the

the first parent unless it is instanced.

Returns:

omx.XNode: the parent XNode.

getPath()

Return the minimum path of the DAG node, or name for the DG node.

getShape(index=0)

Get the DAG shape by index. Note that this will raise exception if it is not a Dag node, or there is no such shape at the index.

Args:

index (int): The index of shape.

Returns:

omx.XNode: the shape XNode.

hasChildAtIndex(index=0)

Check if there is a DAG child at the given index.

Returns:

boolean: True if there is a DAG child at the given index.

hasDagNode()

Return if this XFn is attached to a Dag node.

Returns:

boolean: True if it is a Dag node.

hasParentAtIndex(index=0)

Check if there is a DAG parent at the given index.

Returns:

boolean: True if there is a parent at the given index.

hasShapeAtIndex(index=0)

Check if there is a shape at the given index.

Returns:

boolean: True if there is a shape at the given index.

iterAncestors(predicate=<function XFn.<lambda>>)

Iter all the ancestor XNodes.

Raises:

RuntimeErrors: if it is not a DAG node.

Args:

predicate (callable): A callable object that takes an xnode as an argument and

returns True to include an ancestor or False to ignore it.

Notes:

If an ancestor node is filtered out, we will still keep iterating its potential ancestors. The iteration will be depth-first. The world virtual root node will not be included in the iteration.

To-Do:

Cover the imagePlane special case.

Yields:

omx.XNode: The ancestor XNode.

iterChildren(predicate=<function XFn.<lambda>>)

Iter all the child XNodes.

Raises:

RuntimeErrors: if it is not a DAG node.

Args:

predicate (callable): A callable object that takes an xnode as an argument and

returns True to include a child or False to ignore it.

Yields:

omx.XNode: The child XNode.

iterDescendants(predicate=<function XFn.<lambda>>)

Iter all the descendant XNodes.

Raises:

RuntimeErrors: if it is not a DAG node.

Args:

predicate (callable): A callable object that takes an xnode as an argument and

returns True to include a descendant or False to ignore it.

Notes:

If an ancestor node is filtered out, we will still keep iterating its potential descendants. The iteration will be depth-first.

Yields:

omx.XNode: The descendant XNode.

iterShapes(predicate=<function XFn.<lambda>>)

Iter all the shape XNodes.

Raises:

RuntimeErrors: if it is not a DAG node.

Args:

predicate (callable): A callable object that takes an xnode as an argument and

returns True to include a shape or False to ignore it.

Yields:

omx.XNode: The shape XNode.

iterXPlugs(attrType=<XAttrType.ALL: 35184372088832>, states=<XPlugState.ALL: 32768>, predicate=<function XFn.<lambda>>)

Iterate over all XPlugs on the XNode that this XFn wraps, that matches the criteria. Check out omx.XNode.iterXPlugs() for more details.

object()

Returns the associated MObject

Raises:

RuntimeError: When the MObject is invalid.

Returns:

om2.MObject: the associated MObject

xnode()

Get the MObject the XFn was attached to and return as a XNode.

Notes:

Invalid XNode will be returned instead of None on failure.

Returns:

omx.XNode

class AL.omx.XModifier(immediate=False)

Bases: object

A wrapper around MModifier that supports XNode instances directly

Notes:

When created in immediate mode, every time any modifier method is run on this object the doIt method is also run from within a dynamic AL_OMXCommand instance to allow undoing. Immediate mode will always be much slower than non-immediate mode, and is only there to allow simple experiments from the Maya script editor.

__init__(immediate=False)

Creates a new XModifier instance.

Args:

immediate (bool, optional): Specifies if this XModifier should behave in immediate mode. Defaults to False.

addAttribute(node, attribute)

Adds an attribute to a node.

Adds an operation to the modifier to add a new dynamic attribute to the given dependency node. If the attribute is a compound its children will be added as well, so only the parent needs to be added using this method.

Args:

node (XNode | om2.MObject): the node to add an attribute to

attribute (om2.MObject): the attribute MObject

Returns:

XModifier: A reference to self

addExtensionAttribute(nodeClass, attribute)

Adds an extension attribute to a node class

Notes:

Adds an operation to the modifier to add a new extension attribute to the given node class. If the attribute is a compound its children will be added as well, so only the parent needs to be added using this method.

Args:

nodeClass (om2.MNodeClass): The node class

attribute (om2.MObject): The attribute MObject to add

Returns:

XModifier: A reference to self

commandToExecute(command)

Adds an operation to the modifier to execute a MEL command.

Notes:

The command should be fully undoable otherwise unexpected results may occur. If the command contains no undoable portions whatsoever, the call to doIt() may fail, but only after executing the command. It is best to use multiple commandToExecute() calls rather than batching multiple commands into a single call to commandToExecute(). They will still be undone together, as a single undo action by the user, but Maya will better be able to recover if one of the commands fails.

Args:

command (str): The command string

Returns:

XModifier: A reference to self

connect(*args, **kwargs)

Connects two plugs.

Adds an operation to the modifier that connects two plugs in the dependency graph. It is the user’s responsibility to ensure that the source and destination attributes are of compatible types. For instance, if the source attribute is a nurbs surface then the destination must also be a nurbs surface. Plugs can either be specified with node and attribute MObjects or with MPlugs.

Note:

Arguments v1: If any plug is an array plug, it will expect another is also an array plug with matched data type, and it will try to connect at array level:

source (XPlug | om2.MPlug): The source plug dest (XPlug | om2.MPlug): The destination plug

Arguments v2: If any plug is an array plug, it will try to connect at the next available element level:

sourceNode (MObject): The source MObject sourceAttr (MObject): The source attribute MObject destNode (MObject): The destination MObject destAttr (MObject): The destination attribute MObject

Returns:

XModifier: A reference to self

createDGNode(typeName, nodeName='')

Creates a DG node.

Args:

typeName (str): the type of the object to create, e.g. “transform”.

nodeName (str, optional): the node name, if non empty will be used in a modifier.renameObject call. Defaults to “”.

Returns:

XNode: A XNode instance around the created MObject.

createDagNode(typeName, parent=<_OpenMaya name='mock.MObject.kNullObj' id='140690864982784'>, nodeName='', manageTransformIfNeeded=True, returnAllCreated=False)

Creates a DAG node.

Adds an operation to the modifier to create a DAG node of the specified type. If a parent DAG node is provided the new node will be parented under it. If no parent is provided and the new DAG node is a transform type then it will be parented under the world. In both of these cases the method returns the new DAG node.

If no parent is provided and the new DAG node is not a transform type then a transform node will be created and the child parented under that. The new transform will be parented under the world and it is the transform node which will be returned by the method, not the child.

None of the newly created nodes will be added to the DAG until the modifier’s doIt() method is called.

Notes:

If you try to use createDagNode() to create an empty NurbsCurve or Mesh, calling bestFn() on the returned XNode will give you MFnNurbsCurve or MFnMesh but these are invalid to work with. You will end up getting a misleading “Object does not exist.” error as Maya doesn’t like an empty NurbsCurve or Mesh.

Raises:

TypeError if the node type does not exist or if the parent is not a transform type.

Args:

typeName (str): the type of the object to create, e.g. “transform”.

parent (om2.MObject | XNode, optional): An optional parent for the DAG node to create.

nodeName (str, optional): the node name, if non empty will be used in a modifier.renameObject call. Defaults to “”.

manageTransformIfNeeded (bool, optional): when you create a shape without a parent, Maya will create both transform and shape, and return parent om2.MObject instead. if manageTransformIfNeeded is True, than we will also rename the transform, and return shape MObject instead. Most of time we keep it default True value.

returnAllCreated (bool, optional): If True, it will return all newly created nodes, potentially including any new parent transforms and the shape of the type.

Returns:

XNode | list: An _xnode.XNode instance around the created MObject, or the list of all created nodes, if returnAllCreated is True.

createNode(typeName, *args, **kwargs)

Convenience method to be able to use an XModifier when a MDagModifier or MDGModifier is expected.

Args:

typeName (str): the type of the object to create, e.g. “transform”

Returns:

om2.MObject: The created MObject

deleteNode(node)

Deletes the node

Adds an operation to the modifer which deletes the specified node from the Dependency Graph. If the modifier already contains other operations on the same node (e.g. a disconnect) then they should be committed by calling the modifier’s doIt() before the deleteNode operation is added.

Args:

node (XNode | om2.MObject): The object to delete.

Returns:

XModifier: A reference to self

disconnect(*args, **kwargs)

Disconnects two plugs

Adds an operation to the modifier that breaks a connection between two plugs in the dependency graph. Plugs can either be specified with node and attribute MObjects or with MPlugs.

Note:

Arguments v1: It works for all the scenarios, including disconnecting two array plugs at array level.

source (XPlug | om2.MPlug): The source plug dest (XPlug | om2.MPlug): The destination plug

Arguments v2: Unlike the connect() version, it does not work on array attributes.

sourceNode (MObject): The source MObject sourceAttr (MObject): The source attribute MObject destNode (MObject): The destination MObject destAttr (MObject): The destination attribute MObject

Returns:

XModifier: A reference to self

doIt(keepJournal=False)

Executes the operations held by this modifier in Maya.

Notes:

In immediate mode this will actually execute doIt from within a dynamic Maya command to allow undo to function.

If doIt() is called multiple times in a row, without any intervening calls to undoIt(), then only the operations which were added since the previous doIt() call will be executed. If undoIt() has been called then the next call to doIt() will do all operations.

Args:

keepJournal (bool, optional): Retains the journal for further inspection. Defaults to False.

isClean()

Returns True if the modifier has nothing to do.

Notes:

It will also return True if the modifier has already been used by a Command.

Returns:

bool: the clean state.

journal()

Returns the current list of operations to run.

Returns:

list(str): A list of strings describing the operations to run.

linkExtensionAttributeToPlugin(plugin, attribute)

Links an extension attribute to a plugin

The plugin can call this method to indicate that the extension attribute defines part of the plugin, regardless of the node type to which it attaches itself. This requirement is used when the plugin is checked to see if it is in use or if is able to be unloaded or if it is required as part of a stored file. For compound attributes only the topmost parent attribute may be passed in and all of its children will be included, recursively. Thus it’s not possible to link a child attribute to a plugin by itself. Note that the link is established immediately and is not affected by the modifier’s doIt() or undoIt() methods.

Args:

plugin (om2.MObject): The plugin attribute (om2.MObject): The attribute MObject

Returns:

XModifier: A reference to self

newPlugValue(plug, value)

Sets a new plug value.

Adds an operation to the modifier to set the value of a plug, where value is an MObject data wrapper, such as created by the various MFn*Data classes.

Args:

plug (XPlug | om2.MPlug): The plug value (om2.MObject): The value

Returns:

XModifier: A reference to self

newPlugValueBool(plug, value)

Adds an operation to the modifier to set a value onto a bool plug.

Args:

plug (XPlug | om2.MPlug): The plug value (bool): The value

Returns:

XModifier: A reference to self

newPlugValueChar(plug, value)

Adds an operation to the modifier to set a value onto a char (single byte signed integer) plug.

Args:

plug (XPlug | om2.MPlug): The plug value (int): The value

Returns:

XModifier: A reference to self

newPlugValueDouble(plug, value)

Adds an operation to the modifier to set a value onto a double-precision float plug.

Args:

plug (XPlug | om2.MPlug): The plug value (float): The value

Returns:

XModifier: A reference to self

newPlugValueFloat(plug, value)

Adds an operation to the modifier to set a value onto a single-precision float plug.

Args:

plug (XPlug | om2.MPlug): The plug value (float): The value

Returns:

XModifier: A reference to self

newPlugValueInt(plug, value)

Adds an operation to the modifier to set a value onto an int plug.

Args:

plug (XPlug | om2.MPlug): The plug value (int): The value

Returns:

XModifier: A reference to self

newPlugValueMAngle(plug, value)

Adds an operation to the modifier to set a value onto an angle plug.

Args:

plug (XPlug | om2.MPlug): The plug value (om2.MAngle): The value

Returns:

XModifier: A reference to self

newPlugValueMDistance(plug, value)

Adds an operation to the modifier to set a value onto a distance plug.

Args:

plug (XPlug | om2.MPlug): The plug value (om2.MDistance): The value

Returns:

XModifier: A reference to self

newPlugValueMTime(plug, value)

Adds an operation to the modifier to set a value onto a time plug.

Args:

plug (XPlug | om2.MPlug): The plug value (om2.MTime): The value

Returns:

XModifier: A reference to self

newPlugValueShort(plug, value)

Adds an operation to the modifier to set a value onto a short integer plug.

Args:

plug (XPlug | om2.MPlug): The plug value (int): The value

Returns:

XModifier: A reference to self

newPlugValueString(plug, value)

Adds an operation to the modifier to set a value onto a string plug.

Args:

plug (XPlug | om2.MPlug): The plug value (str): The value

Returns:

XModifier: A reference to self

pythonCommandToExecute(callable_)

Adds an operation to execute a python command

Adds an operation to the modifier to execute a Python command, which can be passed as either a Python callable or a string containing the text of the Python code to be executed. The command should be fully undoable otherwise unexpected results may occur. If the command contains no undoable portions whatsoever, the call to doIt() may fail, but only after executing the command. It is best to use multiple calls rather than batching multiple commands into a single call to pythonCommandToExecute(). They will still be undone together, as a single undo action by the user, but Maya will better be able to recover if one of the commands fails.

Args:

callable (callable | str): The command to execute

Returns:

XModifier: A reference to self

removeAttribute(node, attribute)

Removes a dynamic attribute.

Adds an operation to the modifier to remove a dynamic attribute from the given dependency node. If the attribute is a compound its children will be removed as well, so only the parent needs to be removed using this method. The attribute MObject passed in will be set to kNullObj. There should be no function sets attached to the attribute at the time of the call as their behaviour may become unpredictable.

Args:

node (XNode | om2.MObject): the node to remove the attribute from

attribute (om2.MObject): the attribute MObject

Returns:

XModifier: A reference to self

removeExtensionAttribute(nodeClass, attribute)

Removes an extension attribute.

Adds an operation to the modifier to remove an extension attribute from the given node class. If the attribute is a compound its children will be removed as well, so only the parent needs to be removed using this method. The attribute MObject passed in will be set to kNullObj. There should be no function sets attached to the attribute at the time of the call as their behaviour may become unpredictable.

Args:

nodeClass (om2.MNodeClass): The node class

attribute (om2.MObject): The attribute MObject to add

Returns:

XModifier: A reference to self

removeExtensionAttributeIfUnset(nodeClass, attribute)

Removes an extension attribute.

Adds an operation to the modifier to remove an extension attribute from the given node class, but only if there are no nodes in the graph with non-default values for this attribute. If the attribute is a compound its children will be removed as well, so only the parent needs to be removed using this method. The attribute MObject passed in will be set to kNullObj. There should be no function sets attached to the attribute at the time of the call as their behaviour may become unpredictable.

Args:

nodeClass (om2.MNodeClass): The node class

attribute (om2.MObject): The attribute MObject to add

Returns:

XModifier: A reference to self

removeMultiInstance(plug, breakConnections)

Adds an operation to the modifier to remove an element of a multi (array) plug.

Args:

plug (XPlug | om2.MPlug): The plug

breakConnections (bool): breaks the connections

Returns:

XModifier: A reference to self

renameAttribute(node, attribute, newShortName, newLongName)

Adds an operation to the modifer that renames a dynamic attribute on the given dependency node.

Args:

node (XNode | om2.MObject): the node to rename the attribute on

attribute (om2.MObject): the attribute MObject

newShortName (str): The new short name

newLongName (str): The new long name

Returns:

XModifier: A reference to self

renameNode(node, newName)

Adds an operation to the modifer to rename a node.

Args:

node (XNode | om2.MObject): the node to rename

newName (str): the new name

Returns:

XModifier: A reference to self

reparentNode(node, newParent=None, absolute=False)

Adds an operation to the modifier to reparent a DAG node under a specified parent.

Raises TypeError if the node is not a DAG node or the parent is not a transform type.

If no parent is provided then the DAG node will be reparented under the world, so long as it is a transform type. If it is not a transform type then the doIt() will raise a RuntimeError.

Args:

node (om2.MObject | XNode): The DAG node to reparent

newParent (om2.MObject | XNode, optional): The new parent. Defaults to None.

absolute (bool, optional): Whether or not we try to maintain the world transform of the node. If the node has some transform channels locked, it will try to fill the unlocked channels with debug message.

Returns:

XModifier: A reference to self

setNodeLockState(node, newState)

Adds an operation to the modifier to set the lockState of a node.

Args:

node (XNode | om2.MObject): the node to lock

newState (bool): the lock state

Returns:

XModifier: A reference to self

undoIt(keepJournal=False)

Undo the modifier operation in Maya. In immediate mode this function does nothing, as you should already be able to undo it in Maya.

Notes:

It is only used in the scenario that a user creates a modifier manually by calling omx.newModifier()

Args:

keepJournal (bool, optional): Retains the journal for further inspection. Defaults to False.

unlinkExtensionAttributeFromPlugin(plugin, attribute)

Unlinks an extension attribute from a plugin.

The plugin can call this method to indicate that it no longer requires an extension attribute for its operation. This requirement is used when the plugin is checked to see if it is in use or if is able to be unloaded or if it is required as part of a stored file. For compound attributes only the topmost parent attribute may be passed in and all of its children will be unlinked, recursively. Thus it’s not possible to unlink a child attribute from a plugin by itself. Note that the link is broken immediately and is not affected by the modifier’s doIt() or undoIt() methods.

Args:

plugin (om2.MObject): The plugin

attribute (om2.MObject): The attribute MObject to add

Returns:

XModifier: A reference to self

class AL.omx.XNode(obj)

Bases: object

Easy wrapper around om2 objects mainly to access plugs.

__eq__(other)

Add support for XNode comparison.

__hash__()

Add support for using XNode for containers that require uniqueness, e.g. dict key.

__init__(obj)

Creates a new XNode

Args:

obj (om2.MObject | XNode | om2.MFnBase | string): A object to wrap

Returns:

XNode: An instance of a XNode object

__ne__(other)

Add support for XNode comparison.

__repr__()

Get the more unambiguous str representation. This is mainly for debugging purposes.

Returns:

str

__str__()

Returns an easy-readable str representation of this XNode.

Construct a minimum unique path to support duplicate MObjects in scene. For invalid MObject we return the last known name with a suffix (dead) or (invalid) respectively.

Returns:

str: the string representation.

apiType()

Returns the function set type for the object.

Returns:

om2.MFn: Returns a constant indicating the type of the internal Maya object. If the MObject is null MFn.kInvalid will be returned.

basicFn()

Returns the basic MFnDAGNode or MFnDependencyNode for the associated MObject

Notes:

Usually you would use xnode.bestFn() to get the most useful function set. But for an empty nurbsCurve or an empty mesh node, only xnode.basicFn() will work as expected.

Returns:

om2.MFnDagNode | om2.MFnDependencyNode: For a DAG node or a DG node respectively.

bestFn()

Returns the best MFn function set for the associated MObject

Raises:

RuntimeError: if no MFn is found for the wrapped MObject

Returns:

om2.MFn*: the best MFn object for this MObject (usually a om2.MFnTransform or a om2.MFnDependencyNode)

createDagNode(typeName, nodeName='')

Creates a child DAG node on the current node if possible.

Adds an operation to the modifier to create a DAG node of the specified type. If a parent DAG node is provided the new node will be parented under it. If no parent is provided and the new DAG node is a transform type then it will be parented under the world. In both of these cases the method returns the new DAG node.

If no parent is provided and the new DAG node is not a transform type then a transform node will be created and the child parented under that. The new transform will be parented under the world and it is the transform node which will be returned by the method, not the child.

None of the newly created nodes will be added to the DAG until the modifier’s doIt() method is called.

Raises:

TypeError if the node type does not exist or if the parent is not a transform type.

Args:

typeName (string): the type of the object to create, e.g. “transform”

nodeName (str, optional): the node name, if non empty will be used in a modifier.renameObject call. Defaults to “”.

Returns:

XNode: An XNode instance around the created MObject.

hasFn(fn)

Tests whether object is compatible with the specified function set.

Args:

fn (om2.MFn): MFn type constant

Returns:

bool: Returns True if the internal Maya object supports the specified function set specified by fn.

isAlive()

Returns the live state of the current MObject associated with this XNode. An object can still be ‘alive’ but not ‘valid’ (eg. a deleted object that resides in the undo queue).

Returns:

bool: the live state

isNull()

Tests whether there is an internal Maya object.

Returns:

bool: Returns True if the MObject is not referring to any Maya internal internal object (i.e. it is equivalent to kNullObj).

isValid()

Returns the validity of the current MObject associated with this XNode.

Returns:

bool: the valid state

iterXPlugs(attrType=<XAttrType.ALL: 35184372088832>, states=<XPlugState.ALL: 32768>, predicate=<function XNode.<lambda>>)

Iterate over all XPlugs on this XNode that matches the criteria.

Args:

attrType (XAttrType, optional): The attribute type to filter on. Defaults to XAttrType.ALL. states (XPlugState, optional): The plug states to filter on. Defaults to XPlugState.ALL. predicate (callable, optional): A function that takes an XPlug and returns a bool to further filter the plugs. Defaults to a function that always returns True.

Notes:

Both the attrType and state parameters are int flags support the bitwise OR:

for plug in xnode.iterXPlugs(attrType=XAttrType.BOOL | XAttrType.FLOATING, states=XPlugState.VISIBLE):

# do something with visible bool or float numeric plugs

Unlike attrType, states also support list/tuple so that you can specify multiple states that need to be matched all:

for plug in xnode.iterXPlugs(states=(XPlugState.KEYABLE, XPlugState.SETTABLE)):

# do something with keyable plugs whose values are also settable. # For more filter options, use the predicate parameter.

Yields:

XPlug: The next XPlug that matches the criteria.

object()

Returns the associated MObject

Raises:

RuntimeError: When the MObject is invalid.

Returns:

om2.MObject: the associated MObject

xFn()

Returns the XFn function set wrapper for the associated MObject

Returns:

omx.XFn*: the XFn object for this MObject that you can use it as a function set.

class AL.omx.XPlug(*args, **kwargs)

Bases: MPlug

You can use omx.XPlug over an om2.MPlug to take advantage of the extra convenience features.

Examples:

xplug = xnode.attr
xplug.get()                 # Get you the value of the plug
xplug.set(value)            # Set the value of the plug
xplug[0]                    # The element xplug by the logicial index 0 if xplug is an array plug.
xplug['childAttr']          # The child xplug named 'childAttr' if xplug is a compound plug.
xplug.xnode()               # Get you the parent xnode.

# You can also initialise XPlug directly from a string.
xplug = om2.XPlug("node.attr")

Invalid Examples:

xplug['childAttr.attr1']    # This won't work, use xplug['childAttr']['attr1'] instead.
xplug['childAttr[0]']       # This won't work, use xplug['childAttr'][0] instead.
...

class UnlockedModification(xplug)

Bases: object

__init__(xplug)

__contains__(key)

Add support for the key in xPlug syntax.

Checks if the index is an existing index of an array, or the str name is a valid child of a compound.

Args:

key (int | str): The array element plug logical index or the child plug name.

Notes:

We can extend to accept om2.MPlug or omx.XPlug as the input to check, but here we just stay lined up with __getitem__().

Returns:

bool: True if index or name is valid, False otherwise.

__getitem__(key)

Adds support for the xplug[key] syntax where you can get one of an array’s elements, or a compound’s child, as XPlug.

Args:

key (int | str): The array element plug logical index or the child plug name.

Returns:

XPlug

Raises:

AttributeError if compound plug doesn’t have the child with name, TypeError for all the other cases.

__init__(*args, **kwargs)

Notes:

XPlug supports initialization from the following types: om2.XPlug() # Null plug. om2.XPlug(str) # Init from a node.attr string. Supports child of compound attribute and array attribute. om2.XPlug(mplug) # Init from another om2.MPlug om2.XPlug(xplug) # Init from another omx.XPlug om2.XPlug(mobj, mobj) # Init from a node MObject, and an attribute MObject.

__iter__()

Adds support for the for p in xPlug syntax so you can iter through an array’s elements, or a compound’s children, as XPlugs.

Yields:

XPlug

__repr__()

Get the more unambiguous str representation. This is mainly for debugging purposes.

Returns:

str

__str__()

Returns an easy-readable str representation of this XPlug. Constructs a minimum unique path to support duplicate MObjects in scene. “NullPlug” will be returned if this plug isNull.

Returns:

str

child(index)

Returns the child at index as an XPlug, if this plug is of type compound.

Args:

index (int): The child index.

Returns:

omx.XPlug | NullPlug : A valid XPlug or NullPlug (as an XPlug)

connectFrom(source, force=False)

Connect this plug to a source plug

This is an alias to connect

Args:

source (om2.MPlug | XPlug): source plug

force (bool, optional): override existing connection

connectTo(destination, force=False)

Connect this plug to a destination plug

Args:

destination (om2.MPlug | XPlug): destination plug

force (bool, optional): override existing connection

destinations()

Get the destination plugs as a list of XPlugs for valid outgoing connections.

Returns:

List[omx.XPlug, ] | []

disconnectFromSource()

Disconnect this plug from a source plug, if it’s connected

enumNames()

Get the enum name tuple if it is an enum attribute, otherwise None.

Returns:

tuple of strs: The tuple of enum names.

get(asDegrees=False)

Get the value of the plug.

Args:

asDegrees (bool, optional): For an angle unit attribute we return the value in degrees or in radians.

nextAvailable()

Get the next available element plug that does not exist yet for this array plug.

Returns:

omx.XPlug | None

set(value, asDegrees=False)

Set plug to the value.

Notes:

For enum attribute, you can set value by both short int or a valid enum name string. To retrieve the valid enum names, use XPlug.enumNames()

This method does many checks to make sure it works for different types of attributes. If you know the type of attribute, the preference would be to use the set*() methods instead, they are more lightweight and have better performance.

Args:

value (any): The plug value to set.

asDegrees (bool, optional): When it is an angle unit attribute, if this is True than we take the value as degrees, otherwise as radians.This flag has no effect when it is not an angle unit attribute.

Returns:

The previous value if it is simple plug and the set was successful. None or empty list otherwise.

setAngle(value)

Adds an operation to the modifier to set a value onto an angle plug.

Args:

value (om2.MAngle): the value.

setBool(value)

Adds an operation to the modifier to set a value onto a bool plug.

Args:

value (bool): the value.

setChannelBox(channelBox)

Set the plug’s channelBox state.

setChar(value)

Adds an operation to the modifier to set a value onto a char (single byte signed integer) plug.

Args:

value (int): the value.

setCompoundDouble(value)

Adds an operation to the modifier to compound attribute’s double plugs children.

Args:

value ([double]): the list of double value whose amount should be

no larger to the amount of children.

setDistance(value)

Adds an operation to the modifier to set a value onto a distance plug.

Args:

value (om2.MDistance): the value.

setDouble(value)

Adds an operation to the modifier to set a value onto a double-precision float plug.

Args:

value (float): the value.

setFloat(value)

Adds an operation to the modifier to set a value onto a single-precision float plug.

Args:

value (float): the value.

setInt(value)

Adds an operation to the modifier to set a value onto an int plug.

Args:

value (int): the value.

setKeyable(keyable)

Set the plug’s keyable state.

setLocked(locked)

Set the plug’s lock state.

setShort(value)

Adds an operation to the modifier to set a value onto a short integer plug.

Args:

value (int): the value.

setString(value)

Adds an operation to the modifier to set a value onto a string plug.

Args:

value (str): the value.

setTime(value)

Adds an operation to the modifier to set a value onto a time plug.

Args:

value (om2.MTime): the value.

source()

Returns the source connection as an XPlug.

Returns:

omx.XPlug | NullPlug : A valid XPlug if there is a source connection, NullPlug (as an XPlug) if is there is no source connection.

xnode()

Get the MObject the plug belongs to and return as a XNode.

Notes:

Invalid XNode will be returned instead of None on failure.

Returns:

omx.XNode

class AL.omx.XPlugState(*values)

Bases: IntFlag

A high-level state of a XPlug in the OMX system.

Args:

enum (int | XPlugState): the plug state.

ALL = 32768

ARRAY = 64

CHANNELBOX = 4

Those visible in the channel box but may not be keyable.

CHILD = 512

COMPOUND = 256

DESTINATION = 32

The plug that are connected and controlled by another plug.

DYNAMIC = 1024

All the user added attributes.

ELEMENT = 128

INVISIBLE = 65536

KEYABLE = 1

LOCKED = 2

NETWORKED = 4096

NONNETWORKED = 524288

PROCEDURAL = 8192

PROXY = 16384

SETTABLE = 8

The plug is not locked, and the value can be changed by user.

SOURCE = 16

The plug that connects to and controls other plugs.

SOURCE_DEST = 48

We avoid using CONNECTED as it is ambiguous, because the user might think it means the plug is connected, but technically it means either connected or connect to others.

STATIC = 2048

All the attributes come with the MPXNode definition.

UNCONNECTED = 262144

UNSETTABLE = 131072

VISIBLE = 5

All the plugs that are visible in the channel box.

classmethod matchAll(states, plug)

Check if the plug has all the states.

Args:

states (omx.XPlugState | list[omx.XPlugState]): The states to check. Returns False immediately if any one of the states do not match.

plug (om2.MPlug | omx.XPlug): The plug to check.

Returns:

bool: True if the plug has all the states, False otherwise.

matches(plug)

Check if the plug has the state.

Args:

plug (om2.MPlug | omx.XPlug): The plug to check.

Returns:

bool: True if the plug has the state, False otherwise.

AL.omx.commandModifierContext(command)

A Python Context Manager to be used within ALCommand doIt method.

This modifier ensures a non-immediate XModifier is added to the current list of modifiers, and called doIt on exit.

Notes:

This is a util only for AL internal use.

Args:

command (Command): The command instance

AL.omx.createDGNode(typeName, nodeName='')

Creates a DG Node within the current active XModifier

Args:

typeName (str): The node type name.

nodeName (str, optional): The node name (to be used in mod.renameNode after creation). Defaults to “”.

Returns:

XNode | [XNode]: The created XNode.

AL.omx.createDagNode(typeName, parent=<_OpenMaya name='mock.MObject.kNullObj' id='140690864982784'>, nodeName='', returnAllCreated=False)

Creates a DAG Node within the current active XModifier

Note:

We automatically work around a limitation of the om2.MDagModifier here, where Maya would return the shape’s parent transform MObject. Instead we return an XNode for the newly created Shape node if the type is of Shape.

Args:

typeName (str): The type of the DAG node to create.

parent (XNode | om2.MObject | om2.MFnDagNode | str, optional): The parent of the DAG node to create. Defaults to om2.MObject.kNullObj.

nodeName (str, optional): The name of the node to create (used to call mod.renameNode after creation). Defaults to “”.

returnAllCreated (bool, optional): If True, it will return any newly created nodes, including potential new parent transform and the shape of the type.

Returns:

XNode | [XNode]: The created XNode or a list of XNodes, based on returnAllCreated argument.

AL.omx.currentModifier()

Returns the last XModifier from the current modifier list. If the current list is empty it creates and returns a new immediate XModifier.

Returns:

XModifier: A XModifier instance ready to use.

AL.omx.doIt()

Runs doIt on all current modifiers, similar to om2.MDGModifier.doIt().

AL.omx.isJournalOn()

Query if we are actually recording journal for each creation or edit by omx.

AL.omx.newAnimCurveModifier()

Creates a new om2anim.MAnimCurveChange object, adds it to the current list of modifiers and returns it.

Returns:

om2anim.MAnimCurveChange: The newly created MAnimCurveChange

AL.omx.newModifier()

Creates a new non-immediate XModifier, adds it to the current list of modifiers and returns it.

Returns:

XModifier: The newly created XModifier

AL.omx.newModifierContext()

Create a new XModifier for the context, and call XModifier.doIt() on context exit.

Notes:

Any edits done within the python context, they are using the new XModifier.

AL.omx.queryTrackedNodes(queryAll=False)

The mobject handles to the nodes that have been created since tracking has been started.

Args:

queryAll (bool, optional): If true, return the entire list of handles, otherwise just the handles since startTrackingNodes has last been called.

Returns:

list[om2.MObjectHandle]: The list of created nodes.

AL.omx.setJournalToggle(state)

By default we don’t keep journal for all the creation or edit by omx. Use this function to turn it on.

Notes:

Keep in mind this is a global state, turning on journal will slow down the overall performance!

Another way to toggle the journal on is to set it to None (default value) and set the logging level to logging.DEBUG for AL.omx._xmodifier.

Also turning the journal on only makes omx start to record journal, the creation or edits that are already done still won’t be in the journal.

Args:

state (bool | None): the state of toggle.

True = force on, off = force off, None = depends on it is DEBUG logging level