OmUtil

Maya utility functions. Using almost exclusively OpenMaya commands.

author:Mischa Kolbe <mischakolbe@gmail.com>

Note

I am using this terminology when talking about plugs:

• Array plug: A plug that allows any number of connections.

  Example: “input3D” is the array plug of the plugs “input3D[i]”.

• Array plug element: A specific plug of an array plug.

  Example: “input3D[7]” is an array plug element of “input3D”.

• Parent plug: A plug that can be split into child plugs associated with it

  Example: “translate” is the parent plug of [“tx”, “ty”, “ty”]

• Child plug: A plug that makes up part of a parent plug.

  Example: “translateX” is a child plug of “translate”

• Foster child plug: A plug that is a child of a child plug.

  Example: “ramp1.colorEntryList[0].colorR” ->

  colorR is a foster child plug of colorEntryList[0], since color is the child plug of colorEntryList[0] and colorR the child of color.

om_util.get_all_mobjs_of_type(dependency_node_type)

Get all MObjects in the current Maya scene of the given OpenMaya-type.

Parameters:dependency_node_type (OpenMaya.MFn) – OpenMaya.MFn-type. Returns:List of MObjects of matching type. Return type:list

Example

get_all_mobjs_of_type(OpenMaya.MFn.kDependencyNode)

om_util.get_array_mplug_by_index(mplug, index, physical=True)

Get array element MPlug of given mplug by its physical or logical index.

Note

.input3D -> .input3D[3]

PHYSICAL INDEX: This function will NOT create a plug if it doesn’t exist! Therefore this function is particularly useful for iteration through the element plugs of an array plug.

The index can range from 0 to numElements() - 1.

LOGICAL INDEX: Maya will create a plug at the requested index if it doesn’t exist. This function is therefore very useful to reliably get an array element MPlug, even if that particular index doesn’t necessarily already exist.

The logical index is the sparse array index used in MEL scripts.

Parameters:

• mplug (MPlug) – MPlug whose array element MPlug to get.
• index (int) – Index of array element plug.
• physical (bool) – Look for element at physical index. If set to False it will look for the logical index!

Returns:

MPlug at the requested index.

Return type:

MPlug or None

om_util.get_array_mplug_elements(mplug)

Get all array element MPlugs of the given mplug.

Note

.input3D -> .input3D[0], .input3D[1], …

Parameters:mplug (MPlug) – MPlug whose array element MPlugs to get. Returns:List of array element MPlugs. Return type:list

om_util.get_attr_of_mobj(mobj, attr)

Get value of attribute on MObject.

Note

Basically cmds.getAttr() that works with MObjects.

Parameters:

• mobj (MObject or MDagPath or str) – Node whose attr should be queried.
• attr (str) – Name of attribute.

Returns:

Value of queried plug.

Return type:

list or tuple or int or float or bool or str

om_util.get_child_mplug(mplug, child)

Get the child MPlug of the given mplug.

Note

.t -> .tx

Parameters:

• mplug (MPlug) – MPlug whose child MPlug to get.
• child (str) – Name of the child plug

Returns:

Child MPlug or None if that doesn’t exist.

Return type:

MPlug or None

om_util.get_child_mplugs(mplug)

Get all child MPlugs of the given mplug.

Note

.t -> [.tx, .ty, .tz]

Parameters:mplug (MPlug) – MPlug whose child MPlugs to get. Returns:List of child MPlugs. Return type:list

om_util.get_dag_path_of_mobj(mobj, full=False)

Get the dag path of an MObject. Either partial or full.

Note

The flag “full” defines whether a full or partial DAG path should be returned. “Partial” simply means the shortest unique DAG path to describe the given MObject. “Full” always gives the entire DAG path.

Parameters:

• mobj (MObject or MDagPath or str) – Node whose long name is requested.
• full (bool) – Return either the entire or partial DAG path. See Note.

Returns:

DAG path to the given MObject.

Return type:

str

om_util.get_mdag_path(mobj)

Get an MDagPath from the given mobj.

Parameters:mobj (MObject or MDagPath or str) – MObject to get MDagPath for. Returns:MDagPath of the given mobj. Return type:MDagPath

om_util.get_mfn_dag_node(node)

Get an MFnDagNode of the given node.

Parameters:node (MObject or MDagPath or str) – Node to get MFnDagNode for. Returns:MFnDagNode of the given node. Return type:MFnDagNode

om_util.get_mobj(node)

Get the MObject of the given node.

Parameters:node (MObject or MDagPath or str) – Maya node requested as an MObject. Raises:RuntimeError – If the given string doesn’t represent a unique, existing Maya node in the scene. Returns:MObject instance that is a reference to the given node. Return type:MObject

om_util.get_mplug_of_mobj(mobj, attr)

Get MPlug from the given MObject and attribute combination.

Parameters:

• mobj (MObject) – MObject of node.
• attr (str) – Name of attribute on node.

Returns:

MPlug of the given node/attr combination.

Return type:

MPlug

om_util.get_mplug_of_node_and_attr(node, attr_str, expand_to_shape=True, __shape_lookup=False)

Get an MPlug to the given node & attr combination.

Parameters:

• node (MObject or MDagPath or str) – Node whose attr should be queried.
• attr_str (str) – Name of attribute.
• expand_to_shape (bool) – If the given node is a transform with shape nodes underneath it; check for the attribute on the shape node, if it can’t be found on the transform. Defaults to True.
• __shape_lookup (bool) – Flag to specify that an automatic lookup due to expand_to_shape is taking place. This must never be set by the user! Defaults to False.

Returns:

MPlug of given node.attr or None if that doesn’t exist.

Return type:

MPlug or None

Raises:

RuntimeError – If the desired mplug does not exist.

om_util.get_mplug_of_plug(plug)

Get the MPlug to any given plug.

Parameters:plug (MPlug or str) – Name of plug; “name.attr” Returns:MPlug of the requested plug. Return type:MPlug

om_util.get_name_of_mobj(mobj)

Get the name of an MObject.

Parameters:mobj (MObject) – MObject whose name is requested. Returns:Name of given MObject. Return type:str

om_util.get_node_type(node, api_type=False)

Get the type of the given Maya node.

Note

More versatile version of cmds.nodeType()

Parameters:

• node (MObject or MDagPath or str) – Node whose type should be queried.
• api_type (bool) – Return Maya API type.

Returns:

Type of Maya node

Return type:

str

om_util.get_parent(node)

Get parent of the given node.

Note

More versatile version of cmds.listRelatives(node, parent=True)[0]

Parameters:node (MObject or MDagPath or str) – Node to get parent of. Returns:Name of node’s parent. Return type:str

om_util.get_parent_mplug(mplug)

Get the parent MPlug of the given mplug.

Note

.tx -> .t

Parameters:mplug (MPlug) – MPlug whose parent MPlug to get. Returns:Parent MPlug or None if that doesn’t exist. Return type:MPlug or None

om_util.get_parents(node)

Get parents of the given node.

Parameters:node (MObject or MDagPath or str) – Node whose parents are queried. Returns:Name of parents in an ascending list: First parent first. Return type:list

om_util.get_selected_nodes_as_mobjs()

Get all currently selected nodes in the scene as MObjects.

Returns:List of MObjects of the selected nodes in the Maya scene. Return type:list

om_util.get_shape_mobjs(mobj)

Get the shape MObjects of a given MObject.

Parameters:mobj (MObject or MDagPath or str) – MObject whose shapes are requested. Returns:List of MObjects of the shapes of given MObject. Return type:list

om_util.get_unique_mplug_path(mplug)

Get a unique path to the given MPlug.

Note

MPlug instances don’t return unique paths by default. Therefore they don’t support non unique items. This is a work-around for that issue.

Parameters:mplug (str or MPlug) – Name or MPlug of attribute. Returns:Unique path to attribute: node.attribute Return type:str Raises:ValueError – If given object is neither a string or an MPlug instance.

om_util.is_instanced(node)

Check if a Maya node is instantiated.

Parameters:node (MObject or MDagPath or str) – Node to check if it’s instantiated. Returns:Whether given node is instantiated. Return type:bool

om_util.is_valid_mplug(mplug)

Check whether given mplug is a valid MPlug.

Parameters:mplug (MObject or MPlug or MDagPath or str) – Potential MPlug. Returns:True if given mplug actually is an MPlug instance. Return type:bool

om_util.rename_mobj(mobj, name)

Rename the given MObject.

Note

This is currently NOT undoable!!! Therefore be careful!

Parameters:

• mobj (MObject) – Node to be renamed.
• name (str) – New name for the node.

Returns:

New name of renamed mobj

Return type:

str

om_util.select_mobjs(mobjs)

Select the given MObjects in the Maya scene.

Parameters:mobjs (list) – List of MObjects to be selected.

Todo

For some reason the version below (utilizing OpenMaya-methods) only
selects the nodes, but they don't get selected in the outliner or
viewport! Therefore using the cmds-version for now.

m_selection_list = OpenMaya.MSelectionList()
for mobj in mobjs:
    m_selection_list.add(mobj)
OpenMaya.MGlobal.setActiveSelectionList(
    m_selection_list,
    OpenMaya.MGlobal.kReplaceList
)
return m_selection_list

om_util.set_mobj_attribute(mobj, attr, value)

Set attribute on given MObject to the given value.

Note

Basically cmds.setAttr() that works with MObjects.

Parameters:

• mobj (MObject or MDagPath or str) – Node whose attribute should be set.
• attr (str) – Name of attribute.
• value (int or float or bool or str) – Value plug should be set to.

Todo

Use OpenMaya API only! Check: austinjbaker.com/mplugs-setting-values

om_util.split_attr_string(attr)

Split string referring to an attr on a Maya node into its elements.

Note

“attr_a[attr_a_index].attr_b[attr_b_index]. …” -> [(attr_a, attr_a_index), (attr_b, attr_b_index), …]

The index for an attribute that has no index will be None.

Parameters:attr (str) – Name of attribute. Returns:List of tuples of the form (attribute, attribute-index) Return type:list Raises:ValueError – If given string is not in the pattern described in Note.

om_util.split_node_string(node)

Split string referring to a Maya node name into its separate elements.

Note

“namespace1:namespace2:some|dag|path|node” -> (namespaces, dag_path, node)

Parameters:

node (str) – Name of Maya node, potentially with namespaces & dagPath.

Returns:

Tuple of the form (namespaces, dag_path, node)

Return type:

tuple

Raises:

• ValueError – If given string is not in the pattern described in Note.
• RuntimeError – If the given string looks like it stands for multiple Maya-nodes; a string that yields multiple regex-matches.

om_util.split_plug_string(plug)

Split string referring to a plug into its separate elements.

Note

“namespace:some|dag|path|node.attr_a[attr_a_index].attr_b” -> (namespace, dag_path, node, [(attr_a, attr_a_index), (attr_b, None)])

Parameters:plug (str) – Name of plug; “name.attr” Returns:Tuple of elements that make up plug (namespace, dag_path, node, attrs) Return type:tuple