AL.omx.utils

Warning

The utils within this package are mainly for internal use only, they are more likely to be changed, so use them at your own risk.

AL.omx.utils._nodes

AL.omx.utils._nodes.closestAvailableNodeName(nodeName, _maximumAttempts=10000)[source]

Return the closest node name that does not exist in Maya.

Args:

nodeName (str): the input name. _maximumAttempts (int, optional): The maximum attempts before get a node name that does not exists.

Returns:

str | None: Return the closest name that is available if nodeName is a valid Maya: node name, otherwise None.

Examples:

Say in Maya scene we have nodes my_motion:ctrl, my_motion:ctrl1 closestAvailableNodeName(‘my_motion:ctrl’) -> ‘my_motion:ctrl2’

AL.omx.utils._nodes.createSelectionList(*objects, silent=True)[source]

An convenient util to create a MSelectionList from arbitrary number of inputs.

Args:

objects (any): A list of any supported input for MSelectionList creation.: e.g. MObject, str, MDagPath, MPlug, MUuid, etc.

Returns:

om2.MSelectionList if success, otherwise None.

AL.omx.utils._nodes.findDagPath(nodeName)[source]

Find the MDagPath by name

Args:: nodeName (str): full or short name of the dag node
Returns:: om2.MDagPath if found or None otherwise

AL.omx.utils._nodes.findNode(nodeName)[source]

Find the dependency node MObject by name

Args:: nodeName (str): full or short name of the node
Returns:: om2.MObject if found or None otherwise

AL.omx.utils._nodes.partitionNameAndTrailingDigits(inputName)[source]

Separate a node name into (name, trailingDigits)

Args:: inputName (str): the input name to partition.
Returns:: (str, int) if inputName has non-digit name and trailing digits.
Examples:: partitionNameAndTrailingDigits(‘’) -> (None, None) partitionNameAndTrailingDigits(‘my_motion:name’) -> (‘my_motion:name’, None) partitionNameAndTrailingDigits(‘2343’) -> (None, 2343) partitionNameAndTrailingDigits(‘my_motion:name12’) -> (‘my_motion:name’, 12)

AL.omx.utils._plugs

class AL.omx.utils._plugs.XAttrType(*values)[source]

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)[source]

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.utils._plugs.XPlugState(*values)[source]

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)[source]

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)[source]

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.utils._plugs.attributeTypeAndFnFromPlug(plug)[source]

Get the attribute type and MFn*Attribute class for the plug.

Args:: plug (om2.MPlug): The plug to query type and attribute functor for.
Returns:: om2.MFn.*, om2.MFn*Attribute.

AL.omx.utils._plugs.createAttributeDummy()[source]

Create a dummy node with a message attribute called ‘kMessage’, this is often for a connection to force Maya to create an element plug etc.

Notes:: Usually this temp node will need to be removed soon after the attribute is used. More info in the notes for getOrExtendMPlugArray().
Returns:: om2.MObject: The MObject created.

AL.omx.utils._plugs.findPlug(plugName, node=None)[source]

Find the om2.MPlug by name (and node)

It allows to pass either attribute name plus node om2.MObject or the full plug path without a node.

Args:: plugName (str): plug name or node.attr node(om2.MObject, optional): node of the plug, it is optional.
Returns:: om2.MPlug if found None otherwise

AL.omx.utils._plugs.findSubplugByName(plug, token)[source]

Give a plug recursively through all nested compounds looking for plug by name

Args:: plug (om2.MPlug): The compound plug. token (str): The attribute name / path
Returns:: om2.MPlug: The child / descendent plug.

AL.omx.utils._plugs.getOrExtendMPlugArray(arrayPlug, logicalIndex, dummy=None)[source]

Get the element plug by logicIndex if the element exists, otherwise extend the array until the logical index exists.

Args:

arrayPlug (om2.MPlug): A valid array plug.

logicalIndex (int): The logical index.

dummy (None | om2.MObject, optional): The dummy MObject that contains a ‘kMessage’,: createAttributeDummy() will be called to create one if it is None.

Notes:

Using this function without a persistent dummy in quick iterations will most likely hard crash Maya for you as it struggles to create, connect from and delete nodes repeatedly in a short span of time. Use autoDummy (dummy argument = None) sparingly and only if you are certain this runs with plenty elbow room around it or only once.

Returns:

om2.MPlug: The plug at the logical index, or None if it is not a valid array plug.

AL.omx.utils._plugs.iterAttributeFnTypesAndClasses()[source]: Iter through all the attribute MFn types and its MFn*Attribute classes.

AL.omx.utils._plugs.nextAvailableElement(plug)[source]

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

Args:: plug (om2.MPlug): the array plug to get the element plug for.
Returns:: om2.MPlug: the next available element plug, or null plug if failed.

AL.omx.utils._plugs.nextAvailableElementIndex(plug)[source]

Get the next available element index that does not exist yet.

Args:: plug (om2.MPlug): the array plug to get the index for.
Returns:: int: the next available element index, -1 if failed.

AL.omx.utils._plugs.nodeDotAttrFromPlug(plug)[source]

Return nodeName.attribute str representation of the plug.

Notes:

plug.partialName() will not give you a unique nodeName.attribute if the: node is duplicatly named.

Args:

plug (om2.MPlug): A Maya MPlug

Returns:

str: the nodePartialPathName.attribute

AL.omx.utils._plugs.plugEnumNames(plug)[source]

Get enum name list from an enum plug, None otherwise.

Args:: plug (om2.MPlug): the enum plug to get the enum name list.
Returns:: tuple | None: A tuple of enum names, None if failed.

AL.omx.utils._plugs.plugIsValid(plug)[source]

Checks for plug validity working around various Maya issues. See notes.

Notes:: Courtesy of Maya having issues when a plug; - can be obtained that is fully formed - responds to methods such as isCompound, isElement etc. - also respond negatively to isNull BUT actually has an uninitialized array in its stream and will therefore hard crash if queried for anything relating to its array properties such as numElements etc.
Args:: plug (om2.MPlug): The plug to do validity check.
Returns:: bool: True if it is a valid plug, False otherwise.

AL.omx.utils._plugs.setValueOnPlug(plug, value, elideLock=False, exclusionPredicate=<function <lambda>>, inclusionPredicate=<function <lambda>>, faultTolerant=True, _wasLocked=False, modifier=None, doIt=True, asDegrees=False)[source]

Set plug value using a modifier.

Args:

plug (om2.MPlug): The plug to set to the specified value contained in the following argument.

value (any): the value to set the plug to

elideLock (bool, optional): Whether we unlock the plug (only) during value setting.

exclusionPredicate (function, optional): See valueAndTypesFromPlug

inclusionPredicate (function, optional): See valueAndTypesFromPlug

faultTolerant (bool, optional): Whether to raise on errors or proceed silently

_wasLocked (bool, optional): internal use only, this is required for plugLock eliding: functions to play nice with elision conditions, since the decorator will always run first and unlock the plug, and therefore has to be able to signal the wrapped function of the previous state of the plug for both the check AND restoration of the lock before an eventual exception

modifier (om2.MDGModifier, optional): to support modifier for undo/redo purpose.

doIt (bool, optional): True means modifier.doIt() will be called immediately to apply the plug value change.: False enable you to defer and call modifier.doIt() later in one go.
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:

None if for whatever reason the operation is invalid or has effected no change Otherwise it will return the original value (so it can be stored for undo support). Normally the pattern would be None as invalid op, False for no change, and True for change affected, but given the previous value for a boolean attribute could reasonably be False as a value we have to use None for both invalid as well as ineffective, and rely on the user to invoke the call as non fault tolerant and catching specific exceptions for no-change

Todo:

In support of the last note in the return description we need fine grained exceptions to enable this function to act in a ternary fashion

AL.omx.utils._plugs.valueAndTypesFromPlug(plug, context=<_OpenMaya name='mock.MDGContext.kNormal' id='140690864928240'>, exclusionPredicate=<function <lambda>>, inclusionPredicate=<function <lambda>>, faultTolerant=True, flattenComplexData=True, asDegrees=False)[source]

Retrieves the value, attribute functor type, and attribute type per functor for any given plug.

Args:

plug (om2.MPlug): A maya type plug of any description

context (om2.MDGContext, optional): The maya context to retrieve the plug at. This isn’t always applicable,: and w indicate so in the switches when it’s not, but it’s always accepted When a context isn’t passed the default is kNormal, which is current context at current time.
exclusionPredicate (function, optional): Predicated on the attribute functor internal to the function: this enables us to filter by an internal which preceeds the plug check stages, enabling things such as early filtering of hidden attributes or factory ones etc.
inclusionPredicate (function, optional): Predicated on the attribute functor internal to the function: this enables us to filter by an internal which preceeds the plug check stages, enabling things such as early filtering by specific attribute functor calls before choosing to opt in.

faultTolerant (bool, optional): Whether to raise on errors or proceed silently.

flattenComplexData (bool, optional): Whether to convert MMatrix to list of doubles.

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

Returns:

tuple | None: This will return None if it doesn’t raise but is unable to read.: E.G. a predicate is off value or the plug is a compound. If something of note is found it’s returned as a triplet of value, fnType, attrType, with value being potentially an MPlug

Todo:

Escalate faultTolerant to have levels for maya failures vs finer grained failures

AL.omx.utils._plugs.valueFromPlug(plug, context=<_OpenMaya name='mock.MDGContext.kNormal' id='140690864928240'>, faultTolerant=True, flattenComplexData=True, returnNoneOnMsgPlug=False, asDegrees=False)[source]

Get the value of the plug.

Args:

plug (om2.MPlug): The plug to get the value from.

context (om2.MDGContext, optional): The DG context to get the value for.

faultTolerant (bool, optional): Whether to raise on errors or proceed silently

flattenComplexData (bool, optional): Whether to convert MMatrix to list of doubles

returnNoneOnMsgPlug (bool, optional): Whether we return None on message plug or the plug itself.

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

Returns:

om2.MFn.*, om2.MFn*Attribute.

AL.omx.utils._modifiers

class AL.omx.utils._modifiers.MModifier[source]

Bases: MDagModifier

MModifier is a om2.MDagModifier that implements the ability to create both DG and DAG node.

createDGNode(typeName)[source]

Create a DG node of the type.

Args:: typeName (str): The Maya node type name.
Returns:: om2.MObject: The DG node created.

createDagNode(typeName, parent=<_OpenMaya name='mock.MObject.kNullObj' id='140690864982784'>)[source]

Create a DAG node of type typeName.

Args:: typeName (str): The Maya node type name. parent (om2.MObject, optional): The parent MObject.
Returns:: om2.MObject: The DAG node created.

createNode(*args, **kwargs)[source]

Create DAG or DG node based on the internal mode state.

Returns:: om2.MObject: The DAG/DG node created.

redoIt()[source]: Actually perform the action in the modifier.

class AL.omx.utils._modifiers.ToDGModifier(mmodifer)[source]

Bases: object

A python context to use an MModifier in DG mode, which means MModifier.createNode() will create a DG node.

class AL.omx.utils._modifiers.ToDagModifier(mmodifer)[source]

Bases: object

A python context to use an MModifier in DAG mode, which means MModifier.createNode() will create a DAG node.

AL.omx.utils._contexts

class AL.omx.utils._contexts.UndoStateSwitcher(state=True)[source]

Bases: object

A context to switch on/off the undo recording state.

It is mainly for the unittest on the operation undoability, to make sure the undo is recorded.

AL.omx.utils._exceptions

exception AL.omx.utils._exceptions.NullXPlugError[source]

Bases: RuntimeError

Used when an unexpected null XPlug is encountered.

exception AL.omx.utils._exceptions.PlugArrayOutOfBounds(message)[source]

Bases: Exception

Used for when an array’s plug index does not exist.

exception AL.omx.utils._exceptions.PlugAttributePredicateError(plug)[source]

Bases: Exception

An exception raised when calling predicate function ends in error.

exception AL.omx.utils._exceptions.PlugLockedForEditError(plug)[source]

Bases: Exception

An exception raised when calling predicate function results in an error.

exception AL.omx.utils._exceptions.PlugMayaInvalidException(plug, message='')[source]

Bases: Exception

This is very specific Exception for invalid maya plug.

Notes:

Sometimes Maya generates plugs in an invalid state that are perfectly legal, but won’t behave as expected. These plugs can hard crash Maya when manipulated or queried. The most common example are arrays of compounds without any elements.

This is to be used for those cases, and for those cases only.

exception AL.omx.utils._exceptions.PlugUnhandledTypeException(plug, typeID, subTypeID, message='')[source]

Bases: Exception

This is used when a plug of a certain type is found that is not handled in code.