Zapi

Public Interface can be imported via

from zoo.libs.maya import zapi

Classes

class DGNode(node=None)

Bases: object

Base Maya node class for Dependency graph nodes.

Subclasses should implement create() serializeFromScene() methods, can be instantiated directly.

The intention with the class is to create a thin layer around maya MObject for DGNodes to allow working with the maya api 2.0 easier. Much of the code here calls upon zoo.libs.maya.api helper functions.

Any method which returns a node will always return a DGNode, any method that returns an attribute will return a Plug instance.

from zoo.libs.maya import zapi
multi = zapi.DGNode()
multi.create(name="testNode", nodeType="multipleDivide")
# set the input1 Vector by using the zoo lib helpers
multi.input1.set(zapi.Vector(10,15,30))
multi2 = zapi.DGNode()
multi2.create(name="dest", Type="plusMinusAverage")
# connect the output plug to unconnected elementPlug of the plus minus average node
multi.connect("output", multi2.input3D.nextAvailableElementPlug())
Parameters:

node (om2.MObject, None) – The maya node that this class will operate on, if None then you are expected to call create()

setObject(mObject)

Set’s the MObject For this DGNode instance

Parameters:

mObject (om2.MObject) – The maya api om2.MObject representing a MFnDependencyNode

object()

Returns the object of the node

Return type:

om2.MObject

handle()

Returns the MObjectHandle instance attached to the class. Client of this function is responsible for dealing with object existence.

Return type:

om2.MObjectHandle

typeId()

Returns the maya typeId from the functionSet

Returns:

The type id or -1. if -1 it’s concerned a invalid node.

Return type:

int

hasFn(fnType)

Returns whether the underlying MObject has the specified om2.MFn.kConstant type.

Parameters:

fnType (om2.MFn.kConstant) – The om2.MFn kType

Returns:

Return type:

bool

apiType()

Returns the maya apiType int

Return type:

int

property typeName

Returns the maya apiType int

Return type:

int

exists()

Returns True if the node is currently valid in the maya scene

Return type:

bool

fullPathName(partialName=False, includeNamespace=True)

returns the nodes scene name, this result is dependent on the arguments, by default always returns the full path

Parameters:
  • partialName (bool) – the short name of the node

  • includeNamespace (bool) – True if the return name includes the namespace, default True

Return longName:

the nodes Name

Rtype longName:

str

name(includeNamespace=True)

Returns the name for the node which is achieved by the name or id use self.fullPathName for the nodes actually scene name

rename(name, maintainNamespace=False, mod=None, apply=True)

Renames this node, If

Parameters:
  • name (str) – the new name

  • maintainNamespace (bool) – If True then the current namespace if applicable will be maintained on rename eg. namespace:newName

  • mod (om2.MDGModifier) – Modifier to add the operation to

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Returns:

True if succeeded

Return type:

bool

property isLocked

Returns True if the current node is locked, calls upon om2.MFnDependencyNode().isLocked

Return type:

bool

lock(state, mod=None, apply=True)

Sets the lock state for this node

Parameters:
  • state (bool) – the lock state to change too.

  • mod (zapi.dgModifier) – If None then one will be created and doIt will be called immediately

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Returns:

True if the node was set

Return type:

zapi.dgModifier

isReferenced()

Returns true if this node is referenced.

Return type:

bool

isDefaultNode()

Returns True if this node is a default Maya node.

Return type:

bool

mfn()

Returns the Function set for the node

Returns:

either the dag node or dependencyNode depending on the types node

Return type:

om2.MDagNode or om2.MDependencyNode

renameNamespace(namespace)

Renames the current namespace to the new namespace

Parameters:

namespace (str) – the new namespace eg. myNamespace:subnamespace

setNotes(notes)

Sets the note attributes value, if the note attribute doesn’t exist it’ll be created.

Parameters:

notes (str) – The notes to add.

Returns:

The note plug.

Return type:

Plug

namespace()

Returns the current namespace for the node

Returns:

the nodes namespace

Return type:

str

parentNamespace()

returns the parent namespace from the node

Returns:

The parent namespace

Return type:

str

removeNamespace(modifier=None, apply=True)

Removes the namespace from the node

Parameters:
  • modifier (om2.MDGModifier or om2.MDagModifier) – Modifier to add rename operation too.

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Returns:

True if the namespace was removed

Return type:

bool

delete(mod=None, apply=True)

Deletes the node from the scene, subclasses should implement this method if the class creates multiple nodes

Parameters:
  • mod (om2.MDGModifier or om2.MDagModifier) – Modifier to add the delete operation too.

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Returns:

True if the node gets deleted successfully

Return type:

bool

hasAttribute(attributeName)

Returns True or False if the attribute exists on this node

Parameters:

attributeName (str) – the attribute Name

Return type:

bool

addAttribute(name, Type=6, mod=None, **kwargs)

Helper function to add an attribute to this node

Parameters:
  • name (str) – the attributeName

  • Type (int or None) – For full support list of types see module zoo.libs.maya.api.attrtypes or None for compound type.

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one.

Returns:

the MPlug for the new attribute

Return type:

Plug

addProxyAttribute(sourcePlug, name)

Creates a proxy attribute where the created plug on this node will be connected to the source plug while still being modifiable.

Parameters:
  • sourcePlug (Plug) – The plug to copy to the current node which will become the primary attribute.

  • name (str) – The name for the proxy attribute, if the attribute already exists then no proxy will happen.

Returns:

The Proxy Plug instance.

Return type:

Plug or None.

createAttributesFromDict(data, mod=None)

Creates an attribute on the node given a dict of attribute data

Data is in the form:

{
    "channelBox": true,
    "default": 3,
    "isDynamic": true,
    "keyable": false,
    "locked": false,
    "max": 9999,
    "min": 1,
    "name": "jointCount",
    "softMax": null,
    "softMin": null,
    "Type": 2,
    "value": 3
}
Parameters:
  • data (dict) – The serialized form of the attribute

  • mod (om2.MDGModifier) – The MDagModifier to add to, if none it will create one

Returns:

A list of created MPlugs

Return type:

list[Plug]

addCompoundAttribute(name, attrMap, isArray=False, mod=None, **kwargs)

Creates a Compound attribute with the given children attributes.

Parameters:
  • name (str) – The compound longName

  • attrMap (list(dict())) – [{“name”:str, “type”: attrtypes.kType, “isArray”: bool}]

  • isArray (bool) – Is this compound attribute an array

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one.

Returns:

The Compound MPlug

Return type:

zoo.libs.maya.zapi.base.Plug

attrMap = [{"name": "something", "type": attrtypes.kMFnMessageAttribute, "isArray": False}]
print attrMap
# result <OpenMaya.MObject object at 0x00000000678CA790> #
renameAttribute(name, newName)

Renames an attribute on the current node.

Parameters:
  • name (str) – The existing attribute to rename.

  • newName (str) – The new attribute name, this will be both the short and long names.

Returns:

True if complete.

Return type:

bool

Raises:

AttributeError – When the attribute doesn’t exist.

deleteAttribute(name, mod=None)

Remove’s the attribute for this node given the attribute name

Parameters:
  • name (str) – The attribute name

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one

Return type:

bool

setAttribute(name, value, mod=None, apply=True)

Sets the value of the attribute if it exists

Parameters:
  • name (str) – The attribute name to set

  • value (maya value type) – The value to for the attribute, see zoo.libs.maya.api.plugs.setPlugValue

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Returns:

True if the attribute value was changed.

Return type:

bool

attribute(name)

Finds the attribute ‘name’ on the node if it exists

Parameters:

name (str) – the attribute Name

Return type:

Plug or None

setLockStateOnAttributes(attributes, state=True)

Locks and unlocks the given attributes

Parameters:
  • attributes (seq(str)) – a list of attribute name to lock.

  • state (bool) – True to lock and False to unlock.

Returns:

True is successful

Return type:

bool

showHideAttributes(attributes, state=True)

Shows or hides and attribute in the channel box

Parameters:
  • attributes (seq(str)) – attribute names on the given node

  • state (bool) – True for show False for hide, defaults to True

Returns:

True if successful

Return type:

bool

findAttributes(*names)

Searches the node for each attribute name provided and returns the plug instance.

Parameters:

names (iterable[str]) – list of attribute names without the node name

Returns:

each element is the matching plug or None if not found.

Return type:

iterable[Plug or None]

iterAttributes()

Generator function to iterate over all the attributes on this node, calls on zoo.libs.maya.api.nodes.iterAttributes

Returns:

A generator function containing MPlugs

Return type:

Generator(Plug)

attributes()

Generator function to iterate over all the attributes on this node, calls on zoo.libs.maya.api.nodes.iterAttributes

Returns:

A generator function containing MPlugs

Return type:

Generator(Plug)

iterExtraAttributes(skip=None, filteredTypes=None, includeAttributes=None)

Generator function that loops all extra attributes of the node

Return type:

Generator(Plug)

iterProxyAttributes()

Generator function which returns all proxy attributes on this node.

Return type:

list[Plug]

iterConnections(source=True, destination=True)
Parameters:
  • source (bool) – if True then return all nodes downstream of the node

  • destination (bool) – if True then return all nodes upstream of this node

Returns:

Return type:

generator

sources()

Generator Function that returns a tuple of connected MPlugs.

Returns:

First element is the Plug on this node instance, the second if the connected MPlug

Return type:

Generator(tuple(Plug, Plug))

destinations()

Generator Function that returns a tuple of connected MPlugs.

Returns:

First element is the Plug on this node instance, the second if the connected MPlug

Return type:

Generator(tuple(Plug, Plug))

connect(attributeName, destinationPlug, modifier=None, apply=True)

Connects the attribute on this node as the source to the destination plug

Parameters:
  • attributeName (str) – the attribute name that will be used as the source

  • destinationPlug (Plug) – the destinationPlug

  • modifier (om2.MDagModifier) – The MDagModifier to add to, if none it will create one

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Returns:

True if the connection was made

Return type:

bool

connectDestinationAttribute(attributeName, sourcePlug)

Connects the attribute on this node as the destination to the source plug

Parameters:
  • attributeName (str) – the attribute name that will be used as the source

  • sourcePlug (Plug) – the sourcePlug to connect to

Returns:

True if the connection was made

Return type:

bool

create(name, nodeType, mod=None)

Each subclass needs to implement this method to build the node into the application scene The default functionality is to create a maya dependencyNode

Parameters:
  • name (str) – The name of the new node

  • nodeType (str) – the maya node type to create

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one

serializeFromScene(skipAttributes=(), includeConnections=True, extraAttributesOnly=False, useShortNames=False, includeNamespace=True)

This method is to return a dict that is compatible with JSON.

Parameters:
  • skipAttributes (list[str] or None) – The list of attribute names to serialization.

  • includeConnections (bool) – If True find and serialize all connections where the destination is this node.

  • extraAttributesOnly (bool) – If True then only extra attributes will be serialized

  • useShortNames (bool) – If True only the short name of nodes will be used.

  • includeNamespace (bool) – Whether to include the namespace as part of the node.

Return type:

dict

static sourceNode(plug)

Source node of the plug.

Parameters:

plug (Plug) – Plug to return the source node of

Returns:

Either the source node or None if it’s not connected.

Return type:

DGNode or None

sourceNodeByName(plugName)

Source Node by name

Parameters:

plugName (str) – Name of the plug to return the source node of

Returns:

Return type:

DGNode or None

class DagNode(node=None)

Bases: DGNode

Base node for DAG nodes, contains functions for parenting, iterating the Dag etc

serializeFromScene(skipAttributes=(), includeConnections=True, includeAttributes=(), extraAttributesOnly=True, useShortNames=False, includeNamespace=True)

This method is to return a dict that is compatible with JSON

Return type:

dict

create(name, nodeType, parent=None, mod=None)

Each subclass needs to implement this method to build the node into the application scene The default functionality is to create a maya DagNode

Parameters:
  • name (str) – The name of the new node

  • nodeType (str) – the maya node type to create

  • parent (om2.MObject) – The parent object

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one

dagPath()

Returns the MDagPath of this node. Calls upon om2.MFnDagNode().getPath()

Return type:

om2.MDagPath

depth()

Returns the depth level this node sits within the hierarchy.

Return type:

int

parent()

Returns the parent nodes as an MObject

Return type:

om2.MObject or DagNode or None

root()

Returns the Root DagNode Parent from this node instance

Return type:

DagNode

child(index, nodeTypes=())

Finds the immediate child object given the child index

Parameters:
  • index (int) – the index of the child to find

  • nodeTypes (tuple(om2.MFn.kType)) – Node mfn type eg. om2.MFn.kTransform

Returns:

Returns the object as a DagNode instance

Return type:

DagNode

children(nodeTypes=())

Returns all the children nodes immediately under this node

Returns:

A list of mObjects representing the children nodes

Return type:

list(DagNode)

shapes()

Finds and returns all shape nodes under this dagNode instance

Return type:

list[DagNode]

iterShapes()

Generator function which iterates all shape nodes directly below this node

Returns:

Return type:

list[DagNode]

deleteShapeNodes()

Deletes all shape nodes on this node.

iterParents()

Generator function to iterate each parent until to root has been reached.

Return type:

Generator(:class`DagNode`)

iterChildren(node=None, recursive=True, nodeTypes=None)

kDepthFirst generator function that loops the Dag under this node

Parameters:
  • node (DagNode) – The maya object to loop under , if none then this node will be used,

  • recursive (bool) – If true then will recursively loop all children of children

  • nodeTypes (tuple(om2.MFn.kType)) –

Returns:

Return type:

collections.Iterable[DagNode or DGNode]

addChild(node)

Child object to re-parent to this node

Param:

node: the child node

siblings(nodeTypes=(MockExt.OpenMaya.MFn.kTransform,))

Generator function to return all sibling nodes of the current node. This requires this node to have a parent node.

Parameters:

nodeTypes (tuple) – A tuple of om2.MFn.kConstants

Returns:

Return type:

Generator(DagNode)

setParent(parent, maintainOffset=True, mod=None, apply=True)

Sets the parent of this dag node

Parameters:
  • parent (DagNode or None) – the new parent node

  • maintainOffset (bool) – Whether to maintain its current position in world space.

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Returns:

The maya MDagModifier either provided via mod argument or a new instance.

Return type:

dagModifier

hide(mod=None, apply=True)

Sets the current node visibility to False

Parameters:
  • mod (om2.MDGModifier or om2.MDagModifier) – The mdg modifier to use

  • apply (bool) – Apply instantly if true, false otherwise

Returns:

Return type:

bool

isHidden()

Returns whether this node is visible :rtype: bool

show(mod=None, apply=True)

Sets the current node visibility to 1.0

Parameters:
  • mod (om2.MDGModifier or om2.MDagModifier) – The mdg modifier to use

  • apply (bool) – Apply instantly if true, false otherwise

Returns:

Return type:

bool

setVisible(vis, mod=None, apply=True)

Set visibility of node

Parameters:
  • vis (bool) – Set visibility on or off

  • mod (om2.MDGModifier or om2.MDagModifier) – MDG Modifier

  • apply (bool) – Apply immediately or later

Returns:

Return type:

transformationMatrix(rotateOrder=None, space=MockExt.OpenMaya.MSpace.kWorld)

Returns the current nodes matrix in the form of a MTransformationMatrix.

Parameters:
  • rotateOrder (int) – The Rotation order to use. zapi.kRotateOrder_XYZ

  • space (om2.MSpace) – The coordinate space to use, either kWorldSpace or kObjectSpace

Returns:

The maya TransformationMatrix instance

Return type:

TransformationMatrix

translation(space=MockExt.OpenMaya.MSpace.kWorld, sceneUnits=False)

Returns the translation for this node.

Parameters:
  • space (om2.MFn.type) – The coordinate system to use

  • sceneUnits (bool) – Whether the translation vector needs to be converted to sceneUnits .ie meters Maya stores distances i.e. translation in centimeters regardless on scene units. default False.

Returns:

the object translation in the form om2.MVector

Return type:

om2.MVector

rotation(space=MockExt.OpenMaya.MSpace.kTransform, asQuaternion=True)

Returns the rotation for the node

Parameters:
  • space (om2.MFn.type) – The coordinate system to use

  • asQuaternion (bool) – If True then rotations will be return in Quaternion form

Returns:

the rotation in the form of euler rotations

Return type:

om2.MEulerRotation or om2.MQuaternion

scale(space=MockExt.OpenMaya.MSpace.kTransform)

Return the scale for this node in the form of a MVector.

Parameters:

space (zapi.MSpace) – the coordinate space to retrieve ,either

Returns:

The object scale

Return type:

om2.MVector

setWorldMatrix(matrix)

Sets the world matrix of this node.

Parameters:

matrix (MMatrix) – The world matrix to set

worldMatrix(ctx=MockExt.OpenMaya.MDGContext.kNormal)

Returns the world matrix of this node in the form of MMatrix.

Parameters:

ctx (om2.MDGContext) – The MDGContext to use. ie. the current frame.

Returns:

The world matrix

Return type:

om2.MMatrix

worldMatrixPlug(index=0)

Returns the world matrix plug of this node.

Parameters:

index (int) – The index of the world matrix to return.

Returns:

The world matrix plug

Return type:

Plug

worldInverseMatrixPlug(index=0)

Returns the world matrix plug of this node, by default returns the first element which is typically what you want.

Parameters:

index (int) – The index of the world matrix to return.

Returns:

The world inverse matrix plug.

Return type:

Plug

matrix(ctx=MockExt.OpenMaya.MDGContext.kNormal)

Returns the local MMatrix for this node.

Parameters:

ctx (om2.MDGContext) – The MDGContext to use. ie. the current frame.

Return type:

MMatrix

setMatrix(matrix)

Sets the local matrix for this node.

Parameters:

matrix (om2.MMatrix) – The local matrix to set.

parentInverseMatrix(ctx=MockExt.OpenMaya.MDGContext.kNormal)

Returns the parent inverse matrix.

Parameters:

ctx (om2.MDGContext) – The MDGContext to use. ie. the current frame.

Returns:

the parent inverse matrix

Return type:

om2.MMatrix

parentInverseMatrixPlug(index=0)

Returns the parent inverse matrix plug, by default returns the first element which is typically what you want.

Parameters:

index (int) – The index of the world matrix to return.

Returns:

The parent inverse matrix Plug instance

Return type:

Plug

offsetMatrix(targetNode, space=MockExt.OpenMaya.MSpace.kWorld, ctx=MockExt.OpenMaya.MDGContext.kNormal)

Returns the offset Matrix between this node and the targetNode.

Parameters:
  • targetNode (zapi.DagNode) – The Target Transform Node to diff.

  • space (om2.MSpace.kWorld) – The coordinate space.

  • ctx (om2.MDGContext) – The MDGContext to use. ie. the current frame.

decompose(ctx=MockExt.OpenMaya.MDGContext.kNormal)

Returns the world matrix decomposed for this node.

Parameters:

ctx (om2.MDGContext) – The MDGContext to use. ie. the current frame.

Return type:

tuple[om2.MVector, om2.MQuaternion, tuple[float, float, float]]

resetTransform(translate=True, rotate=True, scale=True)

Resets the local translate, rotate, scale attributes to 0, 0, 0

Parameters:
  • translate (bool) – Whether to reset translate attributes.

  • rotate (bool) – Whether to reset rotate attributes.

  • scale (bool) – Whether to reset scale attributes.

setTranslation(translation, space=None, sceneUnits=False)

Sets the translation component of this control, if cvs is True then translate the cvs instead.

Parameters:
  • translation (om2.MVector) – The MVector that represent the position based on the space given. Default False.

  • space (int) – the space to work on eg.MSpace.kObject or MSpace.kWorld

  • sceneUnits (bool) – Whether the translation vector needs to be converted to sceneUnits .ie meters Maya stores distances i.e. translation in centimeters regardless on scene units.

setRotation(rotation, space=MockExt.OpenMaya.MSpace.kWorld)

Set’s the rotation on the transform control using the space.

Parameters:
  • rotation (om2.MEulerRotation or om2.MQuaternion or seq) – the eulerRotation to rotate the transform by

  • space (om2.MSpace) – the space to work on

setScale(scale)

Applies the specified scale vector to the transform or the cvs

rotationOrder()

Returns the rotation order for this node

Returns:

The rotation order

Return type:

int

setRotationOrder(rotateOrder=0, preserve=True)

Sets rotation order for this instance.

Parameters:
  • rotateOrder (int) – zoo.libs.maya.api.constants.kRotateOrder defaults to XYZ

  • preserve – Sets the transform’s rotation order. If True then the X,Y, Z rotations will be modified so that the resulting rotation under the new order is the same as it was under the old. If False then the X, Y, Z rotations are unchanged.

Type:

bool

setPivot(vec, type_=('t', 'r', 's'), space=None)

Sets the pivot point of the object given the MVector

Parameters:
  • vec (om.MVector) – float3

  • type (sequence(str)) – t for translate, r for rotation, s for scale

  • space (om2.MSpace) – the coordinate space

connectLocalTranslate(driven, axis=(True, True, True), force=True)

Connect’s the local translate plugs to the driven node.

Parameters:
  • driven (DGNode) – The node that will be driven by the current instance

  • axis (tuple(bool)) – A 3Tuple consisting of bool if True then the translate(element) will be connected

  • force (bool) – IF True the connections will be forced by first disconnecting any existing connections.

connectLocalRotate(driven, axis=(True, True, True), force=True)

Connect’s the local Rotate plugs to the driven node.

Parameters:
  • driven (DGNode) – The node that will be driven by the current instance

  • axis (tuple(bool)) – A 3Tuple consisting of bool if True then the rotate(element) will be connected

  • force (bool) – IF True the connections will be forced by first disconnecting any existing connections.

connectLocalScale(driven, axis=(True, True, True), force=True)

Connect’s the local scale plugs to the driven node.

Parameters:
  • driven (DGNode) – The node that will be driven by the current instance

  • axis (tuple(bool)) – A 3Tuple consisting of bool if True then the scale (element) will be connected

  • force (bool) – IF True the connections will be forced by first disconnecting any existing connections.

connectLocalSrt(driven, scaleAxis=(True, True, True), rotateAxis=(True, True, True), translateAxis=(True, True, True), force=True)

Connect’s the local translate, rotate, scale plugs to the driven node.

Parameters:
  • driven (DGNode) – The node that will be driven by the current instance

  • translateAxis (tuple(bool)) – A 3Tuple consisting of bool if True then the translate(element) will be connected

  • rotateAxis (tuple(bool)) – A 3Tuple consisting of bool if True then the rotate(element) will be connected

  • scaleAxis (tuple(bool)) – A 3Tuple consisting of bool if True then the rotate(element) will be connected

  • force (bool) – IF True the connections will be forced by first disconnecting any existing connections.

aimToChild(aimVector, upVector)

Aims this node to first child transform in the hierarchy, if theres no children then the rotation we be reset to 0,0,0.

Parameters:
  • aimVector (Vector) – The directional vector to aim at the child.

  • upVector (Vector) – The UpVector.

boundingBox()

Returns the Bounding information for this node.

Return type:

om2.MBoundingBox

setShapeColour(colour, shapeIndex=None)

Sets the color of this node transform or the node shapes. if shapeIndex is None then the transform colour will be set, if -1 then all shapes

Parameters:
  • colour (tuple(float)) –

  • shapeIndex (int or None) –

connectLocalTrs(driven, scaleAxis=(True, True, True), rotateAxis=(True, True, True), translateAxis=(True, True, True), force=True)

Connect’s the local translate, rotate, scale plugs to the driven node.

Parameters:
  • driven (DGNode) – The node that will be driven by the current instance

  • translateAxis (tuple(bool)) – A 3Tuple consisting of bool if True then the translate(element) will be connected

  • rotateAxis (tuple(bool)) – A 3Tuple consisting of bool if True then the rotate(element) will be connected

  • scaleAxis (tuple(bool)) – A 3Tuple consisting of bool if True then the rotate(element) will be connected

  • force (bool) – IF True the connections will be forced by first disconnecting any existing connections.

class ObjectSet(node=None)

Bases: DGNode

Maya Object Set Wrapper Class

create(name, mod=None, members=None)

Creates the MFnSet node and sets this instance MObject to the new node

Parameters:
  • name (str) – the name for the ObjectSet

  • mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one

  • members (list[DGNode]) – A list of nodes to add as members

Returns:

Instance to self

Return type:

ContainerAsset

addMember(node)

Add a new Node to the set.

Parameters:

node (DGNode) – The Node to add as a new member to this set.

Returns:

True if the node was added, False if not. usually False if the provided node doesn’t exist

addMembers(newMembers)

Add a list of new objects to the set.

Parameters:

newMembers (iterable[DGNode]) – A list of Nodes to add as new members to this set.

isMember(node)

Returns true if the given object is a member of this set.

Parameters:

node (DGNode) – The Node to check for membership

Returns:

Returns true if the given object is a member of this set.

Return type:

bool

members(flatten=False)

Get the members of this set as a list.

It is possible to ask for the returned list to be flattened. This means that all sets that exist inside this set will be expanded into a list of their contents.

Parameters:

flatten (bool) – whether to flatten the returned list.

Returns:

A list of all members in this set, if flatten is True then the result will contain it’s child sets members as well.

Return type:

list[DGNode]

union(otherSets)

This method calculates the union of two or more sets.

The result will be the union of this set and the set passed into the method.

Parameters:

otherSets (list[ObjectSet]) – The other ObjectSets to unionize.

Returns:

union of this set and the set passed into the method.

Return type:

list[DGNode]

intersectsWith(otherSet)

Returns true if this set intersects with the given set.

An intersection occurs if there are any common members between the two sets.

Parameters:

otherSet (ObjectSet) – The other ObjectSet to intersect.

Returns:

True if the other ObjectSet intersects

Return type:

bool

removeMember(member)

Remove an object from the set.

Parameters:

member (DGNode) – The Member node to remove

removeMembers(members)

Remove items of the list from the set.

Parameters:

members (list[DGNode]) – The member nodes to remove

clear()

Removes all members from this ObjectSet

intersection(otherSet)

This method calculates the intersection of two sets.

The result will be the intersection of this set and the set passed into the method.

Parameters:

otherSet (ObjectSet) – The other ObjectSet instance to intersect

Returns:

Resulting list of intersected members

Return type:

list[DGNode]

parent()

Returns the parent ObjectSet

Returns:

The Attached parent object

Return type:

ObjectSet or None

memberSets(flatten=False)

Returns the child objectSets.

Parameters:

flatten (bool) – If True then this functions recursively walks through the hierarchy

Returns:

A list of object sets which have this set as it’s parent

Return type:

list[:class`ObjectSet`]

getIntersection(otherSet)

This method calculates the intersection of two sets.

The result will be the intersection of this set and the set passed into the method.

Parameters:

otherSet (ObjectSet) – The other ObjectSet instance to intersect

Returns:

Resulting list of intersected members

Return type:

list[DGNode]

getMembers(flatten=False)

Get the members of this set as a list.

It is possible to ask for the returned list to be flattened. This means that all sets that exist inside this set will be expanded into a list of their contents.

Parameters:

flatten (bool) – whether to flatten the returned list.

Returns:

A list of all members in this set, if flatten is True then the result will contain it’s child sets members as well.

Return type:

list[DGNode]

getUnion(otherSets)

This method calculates the union of two or more sets.

The result will be the union of this set and the set passed into the method.

Parameters:

otherSets (list[ObjectSet]) – The other ObjectSets to unionize.

Returns:

union of this set and the set passed into the method.

Return type:

list[DGNode]

class BlendShape(node=None)

Bases: DGNode

Abstracts maya’s blendShape node and adds some high level functionality

primaryBaseObject()

Returns the primary driven mesh object ie. the first shape.

Return type:

DagNode

baseObjects()

Generator functions which returns all current base objects

Return type:

Iterable[DagNode

targetCount()

Returns the total number of target shapes.

Return type:

int

envelope()

Returns the envelope attributes value.

Return type:

float

setEnvelope(value)

Sets the blender envelope value.

Parameters:

value (float) – envelope value.

Returns:

whether setting the value succeeded.

Return type:

bool

renameTarget(name, newName)

Renames the target weight alias to the new Name.

Parameters:
  • name (str) – The current weight name i.e. browUp

  • newName (str) – The newName from the weight, Any space will be converted to “_”

Returns:

The new Name which was created.

Return type:

str

iterTargetIndexPairs()

Iterates over the target index pairs of the BlendShape node.

Returns:

A generator that yields each target index pair as a tuple containing the alias and index.

Return type:

generator

targets(baseObjectIndex=0)

returns the mesh object for all connected targets

targetGroupPlug(targetIndex, baseObjectIndex=0)

Method to get the target group plug of a blend shape node.

Parameters:
  • targetIndex (int) – The index of the target group.

  • baseObjectIndex (int) – The index of the base object (default is 0).

Returns:

The target group plug.

Return type:

maya.api.OpenMaya.MPlug

targetInbetweenPlug(targetIndex, logicalIndex, baseObjectIndex=0)

Returns the plug representing the in-between value for the target item.

Parameters:
  • targetIndex (int) – The index of the target shape in the blend shape node.

  • logicalIndex (int) – The logical index of the target item in the target shape.

  • baseObjectIndex (int) – The index of the base object in the blend shape node. Default is 0.

Returns:

The plug representing the in-between value for the target item.

Return type:

om2.MPlug

targetIdxByName(name)

Get the index of a target by its name.

Parameters:

name (str) – The name of the target.

Returns:

The index of the target.

Return type:

int

Raises:

AttributeError – If the target doesn’t exist.

targetInbetweenName(targetIndex, logicalIndex)

Returns the target in-between name for the given target index and logical index.

Parameters:
  • targetIndex (int) – The index of the target

  • logicalIndex (int) – The logical index of the inbetween

Returns:

The name of the inbetween

Return type:

str

targetIndexWeights(targetIndex, baseObjectIndex=0)

Returns the target index weights for a given target index and base object index.

Parameters:
  • targetIndex (int) – The index of the target.

  • baseObjectIndex (int) – The index of the base object. Default is 0.

Returns:

The target index weights.

Return type:

generator

targetWeights()

Returns the target weights of the blend shape node.

Returns:

A generator that yields tuples containing the logical index and weight of each target weight plug.

Return type:

generator[int, float]

targetPaintWeights(targetIndex, baseObjectIndex=0)

Returns the paint weights for a given target index and base object index.

Parameters:
  • targetIndex (int) – Index of the target shape.

  • baseObjectIndex (int) – Index of the base object.

Returns:

A set of weight indices and their associated float values.

Return type:

set

basePaintWeights(baseObjectIndex=0)

Returns the paint weights for a given base object index.

Parameters:

baseObjectIndex (int) – The index of the base object to paint weights for.

Returns:

A set of tuples containing the weight index and weight value.

Return type:

set

setTargetInbetweenName(name, targetIndex, logicalIndex)

Sets the name of the target inbetween.

Parameters:
  • name (str) – The name of the target inbetween to set

  • targetIndex (int) – The index of the target in the inbetween array

  • logicalIndex (int) – The logical index of the inbetween to set

Returns:

An empty string indicating success

Return type:

str

setTargetWeights(weightList)

Sets the target weights for the blend shape node.

Parameters:

weightList (list[tuple]) – A list of tuples containing index and weight values to set for the target weights.

setTargetWeightValue(targetIndex, value)

Sets the target weight value for the given target index.

Parameters:
  • targetIndex (int) – Index of the target weight to set.

  • value (float) – Value to set the target weight to.

setBasePaintWeights(weightList, baseObjectIndex=0)

Set the paint weights for the base object in the blend shape node.

Parameters:
  • weightList (list(tuple(int, float))) – The list of weights to set. Each item in the list should be a tuple containing the index and value of the weight.

  • baseObjectIndex (int) – The index of the base object in the blend shape node. Defaults to 0.

setTargetPaintWeights(weightList, targetIndex, baseObjectIndex=0)

This method sets the paint weights for the specified target index and base object index in the blend shape node. The paint weights are provided as a list of tuples, where each tuple contains the weight index and value to set. The weight index represents the specific vertex or control point to set the weight on, and the value represents the weight value to set.

Parameters:
  • weightList (list[(int, float)]) – A list of tuples containing the weight index and value to set.

  • targetIndex (int) – The index of the target blend shape node.

  • baseObjectIndex (int) – The index of the base object. Default is 0.

Example usage:

# Assuming 'blendShapeNode' is a valid 'BlendShape' object
blendShapeNode.setTargetPaintWeights([(0, 1.0), (1, 0.8), (2, 0.2), ...], 0, 0)
class AnimCurve(node=None)

Bases: DGNode

addKeysWithTangents(times, values, tangentInType=MockExt.OpenMayaAnim.MFnAnimCurve.kTangentGlobal, tangentOutType=MockExt.OpenMayaAnim.MFnAnimCurve.kTangentGlobal, tangentInTypeArray=None, tangentOutTypeArray=None, tangentInXArray=None, tangentInYArray=None, tangentOutXArray=None, tangentOutYArray=None, tangentsLockedArray=None, weightsLockedArray=None, convertUnits=True, keepExistingKeys=False, change=None)

Add a set of new keys with the given corresponding values and tangent types at the specified times.

Note

This method only works for Anim Curves of type kAnimCurveTA, kAnimCurveTL and kAnimCurveTU.

Parameters:
  • times (om2.MTimeArray) – Times at which keys are to be added

  • values (list[float]) – Values to which the keys is to be set

  • tangentInType (int) – In tangent type for all the added keys ie. kTangentGlobal

  • tangentOutType (int) – Out tangent type for all the added keys ie. kTangentGlobal

  • tangentInTypeArray (list[int]) – In tangent types for individual added keys

  • tangentOutTypeArray (list[int]) – Out tangent types for individual added keys

  • tangentInXArray (list[float]) – Absolute x value of the slope of in tangent

  • tangentInYArray (list[float]) – Absolute y value of the slope of in tangent

  • tangentOutXArray (list[float]) – Absolute x value of the slope of out tangent

  • tangentOutYArray (list[float]) – Absolute y value of the slope of out tangent

  • tangentsLockedArray (list[int]) – Lock or unlock the tangents

  • weightsLockedArray (list[int]) – Lock or unlock the weights

  • convertUnits (bool) – Whether to convert to UI units before setting

  • keepExistingKeys (bool) – Specifies whether the new keys should be merged with existing keys, or if they should be cut prior to adding the new keys

  • change (MAnimCurveChange) – Cache to store undo/redo information.

setPrePostInfinity(pre, post, change=None)

Set the behaviour of the curve for the range occurring before the first key and after the last Key.

undoChange = om2Anim.MAnimCurveChange()
curve = zapi.DGNode("myCurve", "animCurveTU")
curve.setPrePostInfinity(zapi.kInfinityConstant, zapi.kInfinityConstant, undoChange)
Parameters:
  • pre (int) – Sets the behaviour of the curve for the range occurring before the first key.

  • post (int) – Set the behaviour of the curve for the range occurring after the last Key.

  • change (om2Anim.MAnimCurveChange) –

class DisplayLayer(node=None)

Bases: DGNode

class NurbsCurve(node=None)

Bases: DagNode

Wrapper class for OpenMaya Api 2.0 MFnNurbsCurve function set providing common set of methods.

length(tolerance=MockExt.OpenMaya.MFnNurbsCurve.kPointTolerance)

Returns the arc length of this curve or 0.0 if it cannot be computed.

Parameters:

tolerance (float) – Max error allowed in the calculation.

Return type:

float

cvPositions(space=MockExt.OpenMaya.MSpace.kObject)

Returns the positions of all the curve’s control vertices.

Parameters:

space (int) – A MSpace constant giving the coordinate space in which the point is given.

Return type:

om2.MPointArray

class Mesh(node=None)

Bases: DagNode

Wrapper class for OpenMaya Api 2.0 MFnMesh function set providing common set of methods.

assignedUVs(uvSet)

Returns a tuple containing all the UV assignments for the specified UV set.

The first element of the returned tuple is an array of counts giving the number of UVs assigned to each face of the mesh. The count will either be zero, indicating that that face’s vertices do not have UVs assigned, or else it will equal the number of the face’s vertices. The second element of the tuple is an array of UV IDs for all the face-vertices which have UVs assigned.

Parameters:

uvSet – The UvSet to return the Uvs for.

Type:

uvSet: str

Return type:

tuple[list[int], list[int]]

class Camera(node=None)

Bases: DagNode

Wrapper class for OpenMaya Api 2.0 MFnCamera function set providing common set of methods.

aspectRatio()

Returns the aspect ratio for the camera.

Return type:

float

centerOfInterestPoint(space=MockExt.OpenMaya.MSpace.kObject)

Returns the center of interest point for the camera.

Parameters:

space (int) – Specifies the coordinate system for this operation.

Return type:

om2.MPoint

eyePoint(space=MockExt.OpenMaya.MSpace.kObject)

Returns the eye point for the camera.

Parameters:

space (int) – Specifies the coordinate system for this operation

Return type:

om2.MPoint

aspectRatioLimits()

Returns the minimum and maximum aspect ratio limits for the camera.

:rtype tuple[float, float]

filmApertureLimits()

Returns the maximum and minimum film aperture limits for the camera.

Return type:

tuple[float, float]

filmFrustum(distance, applyPanZoom=False)

Returns the film frustum for the camera (horizontal size, vertical size, horizontal offset and vertical offset). The frustum defines the projective transformation.

Parameters:
  • distance (float) – Specifies the focal length.

  • applyPanZoom (bool) – Specifies whether to apply 2D pan/zoom.

Return type:

tuple[float, float, float, float]

filmFrustumCorners(distance, applyPanZoom=False)

Returns the film frustum for the camera. The frustum defines the projective transformation.

element 0 is the bottom left element 1 is the top left element 2 is the top right element 3 is the bottom right

:param distance Specifies the focal length. :type distance: float :param applyPanZoom specifies whether to apply 2D pan/zoom. :type applyPanZoom: bool

Return type:

om2.MPointArray

focalLengthLimits()

Returns the maximum and minimum focal length limits for the camera.

Return type:

tuple[float, float]

portFieldOfView(width, height)

Returns the horizontal and vertical field of view in radians from the given viewport width and height.

Parameters:
  • width (int) – width of viewport.

  • height – height of viewport.

Return type:

tuple[float, float]

renderingFrustum(windowAspect)

Returns the rendering frustum (left, right, bottom and top) for the camera. This is the frustum that the maya renderer uses.

Parameters:

windowAspect (float) – windowAspect.

Return type:

tuple[float, float, float, float]

viewParameters(windowAspect, applyOverscan=False, applySqueeze=False, applyPanZoom=False)

Returns the intermediate viewing frustum (apertureX, apertureY, offsetX and offsetY) parameters for the camera.

The aperture and offset are used by getViewingFrustum() and getRenderingFrustum() to compute the extent (left, right, top, bottom) of the frustum in the following manner:

left = focal_to_near * (-0.5*apertureX + offsetX)
right = focal_to_near * (0.5*apertureX + offsetX)
bottom = focal_to_near * (-0.5*apertureY + offsetY)
top = focal_to_near * (0.5*apertureY + offsetY)

Here, focal_to_near is equal to cameraScale if the camera is orthographic, or it is equal to ((nearClippingPlane / (focalLength * MM_TO_INCH)) * cameraScale) where MM_TO_INCH equals 0.03937. :param windowAspect: windowAspect. :type windowAspect: float :param applyOverscan Specifies whether to apply overscan. :type applyOverscan: bool :param applySqueeze Specifies whether to apply the lens squeeze ratio of the camera. :type applySqueeze: bool :param applyPanZoom Specifies whether to apply 2D pan/zoom. :type applyPanZoom: bool :rtype: tuple[float, float, float, float]

viewingFrustum(windowAspect, applyOverscan=False, applySqueeze=False, applyPanZoom=False)

Returns the viewing frustum (left, right, bottom and top) for the camera.

Parameters:
  • windowAspect (float) – windowAspect.

  • applyOverscan (bool) – Specifies whether to apply overscan.

  • applySqueeze (bool) – Specifies whether to apply the lens squeeze ratio of the camera.

  • applyPanZoom (bool) – Specifies whether to apply 2D pan/zoom.

Return type:

tuple[float, float, float, float]

horizontalFieldOfView()

Returns the horizontal field of view for the camera.

Return type:

float

isOrtho()

Returns True if the camera is in orthographic mode.

Return type:

bool

postProjectionMatrix(context=None)

Returns the post projection matrix used to compute film roll on the film back plane.

Parameters:

context (om2.MDGContext) – DG time-context to specify time of evaluation.

Return type:

om2.MFloatMatrix

projectionMatrix(context)

Returns the orthographic or perspective projection matrix for the camera.

The projection matrix that maya’s software renderer uses is almost identical to the OpenGL projection matrix. The difference is that maya uses a left-hand coordinate system and so the entries [2][2] and [3][2] are negated.

Parameters:

context (om2.MDGContext) – DG time-context to specify time of evaluation.

Return type:

om2.MFloatMatrix

rightDirection(space=MockExt.OpenMaya.MSpace.kObject)

Returns the right direction vector for the camera.

Parameters:

space (int) – Specifies the coordinate system for this operation.

Type:

om2.MVector

set(wsEyeLocation, wsViewDirection, wsUpDirection, horizFieldOfView, aspectRatio)

Convenience routine to set the camera viewing parameters.

The specified values should be in world space where applicable.

This method will only work when the world space information for the camera is available, i.e. when the function set has been initialized with a DAG path.

Parameters:
  • wsEyeLocation (MPoint) – Eye location to set in world space.

  • wsViewDirection (MVector) – View direction to set in world space.

  • wsUpDirection (MVector) – Up direction to set in world space.

  • horizFieldOfView (float) – The horizontal field of view to set.

  • aspectRatio (float) – The aspect ratio to set.

setAspectRatio(aspectRatio)

Set the aspect ratio of the View.

The aspect ratio is expressed as width/height.

..note::

This also modifies the entity’s scale transformation to reflect the new aspect ratio.

Parameters:

aspectRatio (float) – The aspect ratio to be set.

setCenterOfInterestPoint(centerOfInterest, space=MockExt.OpenMaya.MSpace.kObject)

Positions the center-of-interest of the camera keeping the eye-point fixed in space.

This method changed the orientation and translation of the camera’s transform attributes as well as the center-of-interest distance.

This method will only work when the world space information for the camera is available, i.e. when the function set has been initialized with a DAG path.

Parameters:
  • centerOfInterest (om2.MPoint or om2.MVector) – Center of interest point to be set.

  • space (int) – Specifies the coordinate system for this operation.

setEyePoint(eyeLocation, space=MockExt.OpenMaya.MSpace.kObject)

Positions the eye-point of the camera keeping the center of interest fixed in space.

This method changed the orientation and translation of the camera’s transform attributes

as well as the center-of-interest distance.

This method will only work when the world space information for the camera is available,

i.e. when the function set has been initialized with a DAG path.

Parameters:
  • eyeLocation (om2.MPoint) – The eye location to set.

  • space (int) – Specifies the coordinate system for this operation.

setHorizontalFieldOfView(fov)

Sets the horizontal field of view for the camera.

Parameters:

fov (float) – The horizontal field of view value to be set.

setNearFarClippingPlanes(near, far)

Set the distances to the Near and Far Clipping Planes.

Parameters:
  • near (float) – The near clipping plane value to be set.

  • far (float) – The far clipping plane value to be set.

setVerticalFieldOfView(fov)

Sets the vertical field of view for the camera.

Parameters:

fov (float) – The vertical field of view value to be set.

upDirection(space=MockExt.OpenMaya.MSpace.kObject)

Returns the up direction vector for the camera.

Parameters:

space (int) – Specifies the coordinate system for this operation.

Type:

om2.MVector

verticalFieldOfView()

Returns the vertical field of view for the camera.

Return type:

float

viewDirection(space=MockExt.OpenMaya.MSpace.kObject)

Returns the view direction for the camera

Parameters:

space (int) – Specifies the coordinate system for this operation.

Type:

om2.MVector

class IkHandle(node=None)

Bases: DagNode

SCENE_UP = 0
OBJECT_UP = 1
OBJECT_UP_START_END = 2
OBJECT_ROTATION_UP = 3
OBJECT_ROTATION_UP_START_END = 4
VECTOR = 5
VECTOR_START_END = 6
RELATIVE = 7
FORWARD_POSITIVE_X = 0
FORWARD_NEGATIVE_X = 1
FORWARD_POSITIVE_Y = 2
FORWARD_NEGATIVE_Y = 3
FORWARD_POSITIVE_Z = 4
FORWARD_NEGATIVE_Z = 5
UP_POSITIVE_Y = 0
UP_NEGATIVE_Y = 1
UP_CLOSET_Y = 2
UP_POSITIVE_Z = 3
UP_NEGATIVE_Z = 4
UP_CLOSET_Z = 5
UP_POSITIVE_X = 6
UP_NEGATIVE_X = 7
UP_CLOSET_X = 8
vectorToForwardAxisEnum(vec)

This method takes a vector and determines the forward axis direction based on the values of the vector. The vector should be a list or tuple of three floats representing the x, y, and z values respectively. The method will return an enum value indicating the forward axis direction.

The forward axis direction is determined by finding the axis with the largest magnitude in the vector. If the sum of the values in the vector is negative, the method will return the corresponding negative forward axis enum value.

The available forward axis enum values are:

  • IkHandle.FORWARD_NEGATIVE_X: The negative X axis

  • IkHandle.FORWARD_NEGATIVE_Y: The negative Y axis

  • IkHandle.FORWARD_NEGATIVE_Z: The negative Z axis

If the sum of the values in the vector is not negative, the method will return the axis index corresponding to the forward axis direction.

The possible axis indexes are:

  • mayamath.XAXIS: The X axis

  • mayamath.YAXIS: The Y axis

  • mayamath.ZAXIS: The Z axis

Parameters:

vec (list or tuple (3 floats)) – A vector representing the forward axis

Returns:

An enum value representing the forward axis direction

Return type:

int

Example usage:

vec = [1.0, 0.0, 0.0] result = vectorToForwardAxisEnum(vec) # result should be mayamath.XAXIS

vec = [-1.0, 0.0, 0.0] result = vectorToForwardAxisEnum(vec) # result should be IkHandle.FORWARD_NEGATIVE_X

vectorToUpAxisEnum(vec)

This method takes a vector and determines the Up axis direction based on the values of the vector. The vector should be a list or tuple of three floats representing the x, y, and z values respectively. The method will return an enum value indicating the up axis direction.

The up axis direction is determined by finding the axis with the largest magnitude in the vector. If the sum of the values in the vector is negative, the method will return the corresponding negative up axis enum value.

The available up axis enum values are:

  • IkHandle.UP_NEGATIVE_X: The negative X axis

  • IkHandle.UP_POSITIVE_Y: The negative Y axis

  • IkHandle.UP_NEGATIVE_Z: The negative Z axis

If the sum of the values in the vector is not negative, the method will return the axis index corresponding to the forward axis direction.

The possible axis indexes are:

  • mayamath.XAXIS: The X axis

  • mayamath.YAXIS: The Y axis

  • mayamath.ZAXIS: The Z axis

Example usage:

ik_handle = IkHandle() vec = [0.0, 1.0, 0.0] up_axis_enum = ik_handle.vectorToUpAxisEnum(vec) print(up_axis_enum) # Output: 2 (IkHandle.UP_POSITIVE_Y)

class SkinCluster(node=None)

Bases: DGNode

recacheBindMatrices(modifier=None, apply=True)
class Plug(node, mPlug)

Bases: object

Plug class which represents a maya MPlug but providing an easier solution to access connections and values.

Parameters:
  • node (DGNode or DagNode) – The DGNode or DagNode instance for this Plug

  • mPlug (om2.MPlug) – The Maya plug

exists()

Whether this plug is valid, same as MPlug.isNull.

Return type:

bool

partialName(includeNodeName=False, includeNonMandatoryIndices=True, includeInstancedIndices=True, useAlias=False, useFullAttributePath=True, useLongNames=True)

Returns the partial name for the plug. by default This method will always return the long name excluding the node name.

Return type:

str

isProxy()

Whether this plug is a proxy attribute.

Return type:

bool

setAsProxy(sourcePlug)

Sets the current attribute as a proxy attribute and connects to the sourcePlug.

Parameters:

sourcePlug (Plug) – The source plug to connect to this plug.

array()

Returns the plug array for this array element.

Return type:

Plug

parent()

Returns the parent Plug if this plug is a compound.

Returns:

The parent Plug.

Return type:

Plug

children()

Returns all the child plugs of this compound plug.

Returns:

A list of child plugs.

Return type:

iterable(Plug)

child(index)

Returns the child plug by index.

Parameters:

index (int) – The child index

Returns:

The child plug.

Return type:

Plug

element(index)

Returns the logical element plug if this plug is an array.

Parameters:

index (int) – The element index

Returns:

The Element Plug.

Return type:

Plug

elementByPhysicalIndex(index)

Returns the element plug by the physical index if this plug is an array.

Parameters:

index (int) – the physical index.

Returns:

The element Plug.

Return type:

Plug

nextAvailableElementPlug()

Returns the next available output plug for this array.

Availability is based and connections of element plug and their children

Return type:

Plug

nextAvailableDestElementPlug()

Returns the next available input plug for this array.

Availability is based and connections of element plug and their children

Return type:

Plug

plug()

Returns the maya MPlug object.

Returns:

The maya MPlug object

Return type:

om2.MPlug

node()

Returns the attached Node class for this plug.

Returns:

The DGNode class or DagNode for this Plug.

Return type:

DagNode or DGNode

apiType()

Returns the internal zoo attribute type constant

Return type:

int

connect(plug, children=None, force=True, mod=None, apply=True)
disconnect(plug, modifier=None, apply=True)

Disconnect destination plug

Parameters:
  • plug (Plug or om2.MPlug) – Destination

  • modifier (om2.DGModifier) – The DGModifier to add to, if none it will create one

  • apply (bool) – If True then the plugs value will be set immediately with the Modifier if False it’s the client responsibility to call modifier.doIt()

Returns:

Returns the provided Modifier or a new Modifier instance

Return type:

om2.MDGModifier

disconnectAll(source=True, destination=True, modifier=None)

Disconnects all plugs from the current plug

Parameters:
  • source (bool) – if true disconnect from the connected source plug if it has one

  • destination (bool) – if true disconnect from the connected destination plug if it has one

  • modifier (om2.MDGModifier) – The MDGModifier to add to, if none it will create one

Returns:

Return type:

tuple[bool, om2.MDGModifier]

source()

Returns the source plug from this plug or None if it’s not connected

Return type:

Plug or None

sourceNode()

Returns the source node from this plug or None if it’s not connected

Return type:

DGNode or None

destinationNodes()

Generator function which returns all destination nodes in the form of one of our zapi node types.

Return type:

iterable[DGNode]

destinations()

Returns all destination plugs connected to this plug

Return type:

collections.Iterable[Plug]

mfn()

Returns the maya function set for this plug

Returns:

Returns the subclass of MFnBase for this attribute type ie. MFnTypeAttribute

Return type:

om2.MFnBase

mfnType()

Returns the maya MFn attribute type

value(ctx=MockExt.OpenMaya.MDGContext.kNormal)

Get value of the plug, if mObject is returned the DG/Dag node

Returns:

The value of the plug

default()

Returns the default value of this plug.

:rtype:str or int or float

setDefault(value)

Sets the default for this plug if supported.

Parameters:

value (int or flaat or string) – The default value to set

Returns:

Whether the default was set.

Return type:

bool

setFromDict(**plugInfo)
set(value, mod=None, apply=True)

Sets the value of this plug

Parameters:
  • value (maya data type.) – The om2 value type, bool, float,str, MMatrix, MVector etc

  • mod (zapi.dgModifier or zapi.dagModifier) – The zapi.kModifier instance or None.

  • apply (bool) – If True then the plugs value will be set immediately with the Modifier if False it’s the client responsibility to call modifier.doIt()

Raise:

ReferenceObjectError, in the case where the plug is not dynamic and is referenced.

isAnimated()

Returns true when the current plug is animated.

Return type:

bool

Raise:

ObjectDoesntExistError When the current Plug doesn’t exist.

findAnimation()

Find the animCurve(s) that are animating a given attribute (MPlug).

In most cases an attribute is animated by a single animCurve and so just that animCurve will be returned. It is possible to setup a series of connections where an attribute is animated by more than one animCurve, although Maya does not currently offer a UI to do so. Compound attributes are not expanded to include any child attributes.

Return type:

list[AnimCurve]

isFreeToChange()
addEnumFields(fields)

Adds a list of field names to the plug, if a name already exists it will be skipped. Adding a field will always be added to the end.

Parameters:

fields (list[str]) – A list of field names to add.

Raise:

ReferenceObjectError, in the case where the plug is not dynamic and is referenced.

enumFields()

Returns a list of the enum fields for this plug. A InvalidTypeForPlugError error will be raised if the plug isn’t compatible.

Raise:

InvalidTypeForPlugError when the plug isn’t an enum type.

setFields(fields)

Sets the list fields for this plug

Parameters:

fields (list[str]) – The list of fields to set for this plug

Raise:

errors.InvalidTypeForPlugError, raised when the plug isn’t an Enum attribute.

delete(modifier=None, apply=True)

Deletes the plug from the attached Node. If batching is needed then use the modifier parameter to pass a base.MDGModifier, once all operations are done call modifier.doIt()

Parameters:
  • modifier (om2.DGModifier) – The DGModifier to add to, if none it will create one

  • apply (bool) – If True then the plugs value will be set immediately with the Modifier if False it’s the client responsibility to call modifier.doIt()

Returns:

Maya DGModifier

Return type:

om2.MDGModifier

Raise:

ReferenceObjectError, in the case where the plug is not dynamic and is referenced

deleteElements(modifier=None, apply=True)

Deletes all array elements from this plug. If batching is needed then use the modifier parameter to pass a base.MDGModifier, once all operations are done call modifier.doIt().

Parameters:
  • modifier (om2.DGModifier) – The DGModifier to add to, if none it will create one.

  • apply (bool) – If True then the plugs value will be set immediately with the Modifier if False it’s the client responsibility to call modifier.doIt().

Returns:

Maya DGModifier.

Return type:

om2.MDGModifier

Raise:

ReferenceObjectError, in the case where the plug is not dynamic and is referenced.

Raise:

TypeError, in case this plug is not an array.

rename(name, mod=None)

Renames the current plug.

Parameters:
  • name (str) – The new name of the plug

  • mod (maya.api.OpenMaya.MDGModifier) – The DagModifier instance to use or None.

Returns:

True if renamed.

Return type:

bool

lockAndHide()

Locks the plug and hides the attribute from the channel box

hide()

Hides the attribute from the channel box and makes the attribute non-keyable

show()

Displays the attribute in the channelBox

setKeyable(state)

Sets the keyable state of the attribute

lock(state)

Sets the current plugs lock state.

Parameters:

state (bool) – True if the plug is to be locked.

serializeFromScene()
displayLayers(default=False)

Returns all displays in the scene.

Parameters:

default (bool) – If True then default layers will be included in the result.

Returns:

The scene display layers.

Return type:

list[DagNode]

createDag(name, nodeType, parent=None, mod=None)

Creates a maya dag node and returns a :class::DagNode instance

Parameters:
  • name (str) – The name for the node, must be unique

  • nodeType (str) – The maya Dag node type

  • parent (DagNode or None) – The parent Node or None

  • mod (maya.api.OpenMaya.MDGModifier) – The DagModifier instance to use or None.

Return type:

DagNode

createDG(name, nodeType, mod=None)

Creates a maya dg node and returns a :class::DGNode instance

Parameters:
  • name (str) – The name for the node, must be unique

  • nodeType (str) – The maya Dg node type

  • mod (maya.api.OpenMaya.MDGModifier) – The DagModifier instance to use or None.

Return type:

DGNode

nodeByObject(node)

Given a MObject return the correct Hive base node class

Parameters:

node (om2.MObject) – The maya om2 api MObject to cast.

Return type:

DagNode or DGNode

nodeByName(nodeName)

Returns a dag node instance given the maya node name, expecting fullPathName.

Parameters:

nodeName (str) – The maya node name

Return type:

DGNode or DagNode

nodesByNames(nodeNameList)

nodeByName except uses a list

Parameters:

nodeNameList (list[str]) – List of maya node names

Returns:

a list of maya node paths to convert to zapi nodes

Return type:

collections.Iterable[DagNode]

ls(*args, **kwargs)

The zapi version of cmds.ls.

Return type:

list[DGNode]

plugByName(path)

Returns the Plug instance for the provided path to the plug

Parameters:

path (str) – The fullPath to the plug.

Raise:

InvalidPlugPathError

Returns:

The Plug instance matching the plug path.

Return type:

Plug

lockNodeContext(func)

Decorator function to lock and unlock the meta, designed purely for the metaclass.

Parameters:

func (function) – The function to decorate.

Returns:

The decorated function.

Return type:

function

lockStateAttrContext(node, attrNames, state)

Context manager which handles the lock state for a list of attributes on a node.

Parameters:
  • node (DGNode) – The Node to lock the attributes on.

  • attrNames (list[str]) – The List of attribute names excluding the node name.

  • state (bool) – The lock state to set to while within the context scope

fullNames(dagNodes)

Helper function to get full names of dagNodes

Parameters:

dagNodes (list[DagNode] or Iterable[DagNode]) – DagNodes

Returns:

a list of fullPaths

Return type:

list[str]

shortNames(dagNodes)

Helper function to get the short names of DGNode

Parameters:

dagNodes (list[DGNode] or collections.Iterable[DGNode]) – An iterable of DGNodes/DagNodes.

Returns:

A list of short names for the provided nodes.

Return type:

list[str]

alphabetizeDagList(dagList)

Sorts a dag API object list by lowercase short names

Parameters:

dagList (list[DagNode]) – A list of API dag objects

Returns:

A list of API dag objects now sorted alphabetically

selected(filterTypes=())

Get dag nodes from selected objects in maya

Parameters:

filterTypes (tuple(om2.MFn.kConstant)) – a tuple of om2.MFn types to filter selected Nodes

Returns:

A list of DGNode nodes

Return type:

iterable[DGNode]

select(objects, mod=None, apply=True)

Selects all nodes in objects, this uses cmds.select.

Parameters:
  • objects (iterable[DGNode]) – DG Nodes to select

  • mod (maya.api.OpenMaya.MDagModifier or maya.api.OpenMaya.MDGModifier) – The Dag/DG modifier to run the command in

  • apply (bool) – Apply the modifier immediately if true, false otherwise

Rtype mod:

maya.api.OpenMaya.MDGModifier

selectByNames(names, mod=None, apply=True)

Same as select(), except it uses the names instead

Parameters:
  • names (iterable[str]) – Names of the nodes

  • apply – Apply the MDagModifier immediately

  • mod (maya.api.OpenMaya.MDagModifier or maya.api.OpenMaya.MDGModifier) – The Dag/DG modifier

Rtype mod:

maya.api.OpenMaya.MDGModifier

clearSelection(mod=None, apply=True)
duplicateAsTransform(source, name, parent=None, mod=None)

Creates a new Transform from the source but maintains the transform and rotationOrder

Parameters:
  • source (zapi.DagNode) – The source node to copy the transform from

  • name (str) – The node name to use

  • parent (DagNode or None) – The parent Node or None

  • mod (maya.api.OpenMaya.MDGModifier) – The DagModifier instance to use or None.

Returns:

The newly created Transform node

Return type:

DagNode

class ContainerAsset(node=None)

Bases: DGNode

Maya Asset container class

members()

Returns the current members of this container.

Return type:

map[:class:`DGNode]`

isCurrent()

Returns whether this current container is the current active container.

If True this means all new nodes will automatically be added to this container.

Return type:

bool

makeCurrentContext(value)

Context manager “with” which makes this container temporarily active.

Parameters:

value (bool) – Active state.

makeCurrent(value)

Set this container to be currently active.

Parameters:

value (bool) – Whether to make the container currently active

property blackBox

Returns the current black box attribute value

Returns:

True if the contents of the container is public

Return type:

bool

setObject(mObject)

Set’s the MObject For this DGNode instance

Parameters:

mObject (om2.MObject) – The maya api om2.MObject representing a MFnDependencyNode

create(name, parent=None)

Creates the MFn Container node and sets this instance MObject to the new node

Parameters:

name (str) – the name for the container

Returns:

Instance to self

Return type:

ContainerAsset

addNodes(objects, force=False)

Adds the provided nodes to the container without publishing them

Parameters:
  • objects (list[DGNode]) – The nodes the add to this container

  • force (bool) – If True then nodes will be disconnected from their current containers before they are added.

addNode(node, force=False)

Adds the provided node to the container without publishing it.

Parameters:
  • node (DGNode) – The node the add to this container

  • force (bool) – If True then nodes will be disconnected from their current containers before they are added.

publishAttributes(attributes)

Publishes the provided attributes to the container.

Parameters:

attributes (list[Plug]) – The attributes to publish to this containers interface.

publishAttribute(plug)

Publishes the provided plug to the container.

Parameters:

plug (Plug) – The plug to publish

publishNode(node)

Publishes the given node to the container.

Parameters:

node (DGNode) – The Node to publish.

publishNodes(publishNodes)

Publishes the given nodes to the container.

Parameters:

publishNodes (list[DGNode]) – The Nodes to publish.

publishNodeAsChildParentAnchor(node)

Publishes the node as child and parent anchor to container.

Parameters:

node (class object) – node to be published as child and parent anchor

setParentAncher(node)

Set the node as a parent anchor to the container.

Parameters:

node (class object) – node to be set as parent anchor

setChildAnchor(node)

Sets the specified child node as the anchor for the container asset.

Parameters:

node (DagNode) – The child node to set as the anchor.

childAnchor()

Gets the child anchor node of the ContainerAsset.

Returns:

The child anchor node.

Return type:

DGNode

parentAnchor()

This method returns the parent anchor of a ContainerAsset.

Returns:

The parent anchor of the ContainerAsset.

Return type:

DGNode

unPublishAttributes()

Unpublishes the attributes of the ContainerAsset.

unPublishAttribute(attributeName)

Removes the specified attribute from being published as an input or output on the node’s container.

Parameters:

attributeName (str) – Name of the attribute to be unpublished, exclude the node name.

Returns:

returns True if the attribute is successfully unpublished, False otherwise

Return type:

bool

unPublishNode(node)

Remove a node from the container and break any connections to other published attributes.

Parameters:

node (DGNode) – The node to be removed

removeUnboundAttributes()

Remove any unbound attributes from the container

subContainers()

Returns a Generator containing all sub containers.

Return type:

list[Container]

getSubContainers()

Returns a Generator containing all sub containers.

Return type:

list[Container]

publishedNodes()

Returns a list of node objects that are published by the current container node.

Return type:

list[DGNode or DagNode]

publishedAttributes()

Returns a list of attribute plugs that are published by the current container node.

Return type:

Plug

serializeFromScene(skipAttributes=(), includeConnections=True, includeAttributes=(), useShortNames=False, includeNamespace=False)

This method is to return a dict that is compatible with JSON.

Parameters:
  • skipAttributes (list[str] or None) – The list of attribute names to serialization.

  • includeConnections (bool) – If True find and serialize all connections where the destination is this node.

  • extraAttributesOnly (bool) – If True then only extra attributes will be serialized

  • useShortNames (bool) – If True only the short name of nodes will be used.

  • includeNamespace (bool) – Whether to include the namespace as part of the node.

Return type:

dict

delete(removeContainer=True)

Deletes the current container

Parameters:

removeContainer (bool) – If True then the container will be deleted, false and the members will be removed but the container won’t be deleted.

namespaceContext(namespace)

Context manager which temporarily sets the current namespace, if the namespace doesn’t exist it will be created.

Parameters:

namespace (str) – The maya Namespace to use, ie. “MyNamespace” or “:MyNamespace”

tempNamespaceContext(namespace)

Creates a temporary namespace that only lives for the life time of the scope

Parameters:

namespace (str) – The Temporary maya Namespace to use, ie. “tempNamespace” or “:tempNamespace”

Errors

exception ObjectDoesntExistError

Bases: Exception

Raised anytime the current object is operated on and it doesn’t exist.

exception InvalidPlugPathError

Bases: Exception

Raised when Provided path doesn’t contain ‘.’

exception ReferenceObjectError

Bases: Exception

Raised when an object is a reference and the requested operation is not allowed on a reference

exception InvalidTypeForPlugError

Bases: Exception

Raised anytime an operation happens on a plug which isn’t compatible with the datatype, ie. setting fields on non Enum type.

exception ExistingNodeAttributeError

Bases: Exception

Raised when attempting to create an attribute that already exists

Node Creation helpers

createPolyPlane(name, **kwargs)

Creates a single polyPlane.

All arguments are the same as cmds.polyPlane :param name: The name for the polyPlane :type name: str :return: returns all nodes created as Zapi nodes. construction history node will be the second element if constructionHistory=True. :rtype: list[base.DagNode, base.DGNode]

createPolyCube(name, **kwargs)

Creates a single polyCube.

All arguments are the same as cmds.polyCube :param name: The name for the polyCube :type name: str :return: returns all nodes created as Zapi nodes. construction history node will be the second element if constructionHistory=True. :rtype: list[base.DagNode, base.DGNode]

createPolySphere(name, **kwargs)

Creates a single polySphere.

All arguments are the same as cmds.polySphere :param name: The name for the polySphere :type name: str :return: returns all nodes created as Zapi nodes. construction history node will be the second element if constructionHistory=True. :rtype: list[base.DagNode, base.DGNode]

distanceBetween(firstNode, secondNode, name)

Creates a distance between node and connects the ‘firstNode’ and ‘secondNode’ world space matrices.

Parameters:
  • firstNode (MObject) – The start transform node

  • secondNode (MObject) – The second transform node

  • name (str) – The name for the new node.

Returns:

the Three nodes created by the function in the form of a tuple, the first element is the distance between node, the second is the start node decompose matrix, the third element is the second node decompose matrix.

Return type:

base.DGNode

multiplyDivide(input1, input2, operation, name)

Creates a multiply divide node with the given and setups the input connections.

List of operations:

no operation = 0,
multiply = 1,
divide = 2,
power = 3

:param input1:the node attribute to connect to the input1 value or use int for value :type input1: MPlug or MVector :param input2:the node attribute to connect to the input2 value or use int for value :type input2: MPlug or MVector :param operation: the int value for operation :type operation: int :param name: The name for the new node :type name: str :return, the multiplyDivide node MObject :rtype: MObject

blendColors(color1, color2, name, blender)

Creates a blend colors node.

Parameters:
  • color1 (om2.MColor or base.Plug) – If the type is a Plug then the color1 plug on the new node will be connected the given plug.

  • color2 (om2.MColor or base.Plug) – If the type is a MPlug then the color2 plug on the new node will be connected the given plug.

  • name (str) – The new floatMath node name.

  • blender (float or base.Plug) – If the type is a Plug then the blender plug on the new node will be connected the given plug.

Returns:

The new colorBlend node as a MObject

Return type:

om2.MObject

floatMath(floatA, floatB, operation, name)

Creates a floatMath node from the lookdev kit builtin plugin

Parameters:
  • floatA (float or base.Plug) – If the type is a Plug then the floatA plug on the new node will be connected the given plug.

  • floatB (float or base.Plug) – If the type is a MPlug then the floatB plug on the new node will be connected the given plug.

  • operation (int) – The operation attributes value

  • name (str) – The new floatMath node name.

Returns:

The floatMath node MObject

Return type:

base.DGNode

blendTwoAttr(input1, input2, blender, name)
pairBlend(name, inRotateA=None, inRotateB=None, inTranslateA=None, inTranslateB=None, weight=None, rotInterpolation=None)
conditionVector(firstTerm, secondTerm, colorIfTrue, colorIfFalse, operation, name)
Parameters:
  • firstTerm (zapi.Plug or float) – The condition nodes firstTerm to compare against the second term.

  • secondTerm (zapi.Plug or float) – The condition nodes secondTerm.

  • colorIfTrue (zapi.Plug or list[zapi.Plug] or om2.MVector) – seq of zapi.Plug or a single zapi.Plug (compound).

  • colorIfFalse (zapi.Plug or list[zapi.Plug] or om2.MVector) – seq of zapi.Plug or a single zapi.Plug (compound).

  • operation (int) – the comparison operator.

  • name (str) – the new name for the node.

Returns:

The newly created Condition node.

Return type:

base.DGNode

logicFloat(floatA, floatB, operation, outBool, name)

Creates a floatLogic node and sets connections/values.

Parameters:
  • floatA (base.Plug or float) –

  • floatB (base.Plug or float) –

  • operation (base.Plug or int) –

  • outBool (base.Plug or None) –

  • name (str) – The name for the node

Returns:

Return type:

base.DGNode

conditionFloat(floatA, floatB, condition, outFloat, name)

Creates a floatCondition node and sets connections/values.

Parameters:
  • floatA (base.Plug or float) –

  • floatB (base.Plug or float) –

  • condition (base.Plug or bool) –

  • outFloat (base.Plug or None) –

  • name (str) – The name for the node

Returns:

Return type:

base.DGNode

createAnnotation(rootObj, endObj, text=None, name=None)
createMultMatrix(name, inputs, output)
createDecompose(name, destination, translateValues=(True, True, True), scaleValues=(True, True, True), rotationValues=(True, True, True), inputMatrixPlug=None)

Creates a decompose node and connects it to the destination node.

Parameters:
  • name (str) – the decompose Matrix name.

  • destination (base.DGNode or None) – the node to connect to

  • translateValues (list(str)) – the x,y,z to apply must have all three if all three are true then the compound will be connected.

  • scaleValues (list(str)) – the x,y,z to apply must have all three if all three are true then the compound will be connected.

  • rotationValues (list(str)) – the x,y,z to apply must have all three if all three are true then the compound will be connected.

  • inputMatrixPlug (base.Plug) – The input matrix plug to connect from.

Returns:

the decompose node

Return type:

base.DGNode

createQuatToEuler(name, inputQuat, output=None)

Creates the quatToEuler maya node and sets up the connections.

Parameters:
  • name (str) – The name for the quatToEuler node

  • inputQuat (base.Plug or list[base.Plug]) – the Plugs to connect to the inputQuat plug if a single plug is provided then it’s expected to be a compound plug

  • output (base.Plug or list[base.Plug] or None) – the Plugs to connect to the outputRotate plug if a single plug is provided then it’s expected to be a compound plug

Returns:

The quatToEuler maya node

Return type:

base.DGNode

createReverse(name, inputs, outputs)

Create a Reverse Node

Parameters:
  • name (str) – The name for the reverse node to have, must be unique

  • inputs (base.Plug or tuple[Plug]) – If Plug then the plug must be a compound.

  • outputs (base.Plug or tuple[Plug]) – If Plug then the plug must be a compound.

Returns:

base.DGNode representing the reverse node

Return type:

base.DGNode

Raises:

ValueError if the inputs or outputs is not an om2.MPlug

createSetRange(name, value, min_, max_, oldMin, oldMax, outValue=None)

Generates and connects a setRange node.

input/output arguments take an iterable, possibles values are om2.MPlug,

float or None.

if a value is None it will be skipped this is useful when you want some not connected or set to a value but the other is left to the default state. If MPlug is passed and its a compound it’ll be connected.

Parameters:
  • name (str) – the new name for the set Range node

  • value (iterable(om2.MPlug or float or None)) –

  • min (iterable(om2.MPlug or float or None)) –

  • max (iterable(om2.MPlug or float or None)) –

  • oldMin (iterable(om2.MPlug or float or None)) –

  • oldMax (iterable(om2.MPlug or float or None)) –

  • outValue (iterable(om2.MPlug or float or None)) –

Returns:

the created setRange node

Return type:

base.DGNode

one = nodes.createDagNode("one", "transform")
two = nodes.createDagNode("two", "transform")
end = nodes.createDagNode("end", "transform")

oneFn = om2.MFnDagNode(one)
twoFn = om2.MFnDagNode(two)
endFn = om2.MFnDagNode(end)
values = [oneFn.findPlug("translate", False)]
min_ = [twoFn.findPlug("translate", False)]
max_ = [twoFn.findPlug("translate", False)]
oldMax = [0.0,180,360]
oldMin = [-10,-720,-360]
reload(creation)
outValues = [endFn.findPlug("translateX", False), endFn.findPlug("translateY", False), None]
pma = creation.createSetRange("test_pma", values, min_, max_, oldMin, oldMax, outValues)
createPlusMinusAverage1D(name, inputs, output=None, operation=1)

Creates a plusMinusAverage node and connects the 1D inputs and outputs.

Parameters:
  • name (str) – the plus minus average node name

  • inputs (iterable(plug or float)) – tuple of MPlugs and/or float values, each value will be applied to a new Input1D element. If the value is MPlug then it will be connected.

  • output (iterable(plug)) – A tuple of downstream MPlugs to connect to.

  • operation (int) – The plus minus average node operation value.

Returns:

The plus minus average MObject

Return type:

base.DGNode

one = nodes.createDagNode("one", "transform")
two = nodes.createDagNode("two", "transform")
end = nodes.createDagNode("end", "transform")

oneFn = om2.MFnDagNode(one)
twoFn = om2.MFnDagNode(two)
endFn = om2.MFnDagNode(end)
inputs = [oneFn.findPlug("translateX", False), twoFn.findPlug("translateX", False)]
outputs = [endFn.findPlug("translateX", False)]
pma = creation.createPlusMinusAverage1D("test_pma", inputs, outputs)
# Result: <OpenMaya.MObject object at 0x000002AECB23AE50> #
createPlusMinusAverage2D(name, inputs, output=None, operation=1)

Creates a plusMinusAverage node and connects the 2D inputs and outputs.

Parameters:
  • name (str) – the plus minus average node name

  • inputs (iterable(plug or float)) – tuple of MPlugs and/or float values, each value will be applied to a new Input2D element. If the value is MPlug then it will be connected.

  • output (iterable(plug)) – A tuple of downstream MPlugs to connect to.

  • operation (int) – The plus minus average node operation value.

Returns:

The plus minus average MObject

Return type:

base.DGNode

createPlusMinusAverage3D(name, inputs, output=None, operation=1)

Create’s a plusMinusAverage node and connects the 3D inputs and outputs.

Parameters:
  • name (str) – The plus minus average node name.

  • inputs (iterable(plug or float).) – tuple of MPlugs and/or float values, each value will be applied to a new Input3D element. If the value is MPlug then it will be connected.

  • output (iterable(plug) or None) – A tuple of downstream MPlugs to connect to.

  • operation (int) – The plus minus average node operation value.

Returns:

The plus minus average MObject.

Return type:

base.DGNode

one = nodes.createDagNode("one", "transform")
two = nodes.createDagNode("two", "transform")
end = nodes.createDagNode("end", "transform")

oneFn = om2.MFnDagNode(one)
twoFn = om2.MFnDagNode(two)
endFn = om2.MFnDagNode(end)
inputs = [oneFn.findPlug("translate", False), twoFn.findPlug("translate", False)]
outputs = [endFn.findPlug("translate", False)]
pma = creation.createPlusMinusAverage3D("test_pma", inputs, outputs)
# Result: <OpenMaya.MObject object at 0x000002AECB23AE50> #
createControllerTag(node, name, parent=None, visibilityPlug=None)

Create a maya kControllerTag and connects it up to the ‘node’.

Parameters:
  • node (base.DagNode) – The Dag node to tag

  • name (str) – The name for the kControllerTag

  • parent (base.DGNode or None) – The Parent kControllerTag mObject or None

  • visibilityPlug (base.Plug or None) – The Upstream Plug to connect to the visibility mode Plug

Returns:

The newly created kController node as a MObject

Return type:

base.DGNode

createIkHandle(name, startJoint, endJoint, solverType='ikRPsolver', parent=None, **kwargs)

Creates an Ik handle and returns both the ikHandle and the ikEffector as DagNode

Parameters:
  • name (str) – The name of the ikhandle.

  • startJoint (DagNode) – The Start joint

  • endJoint (base.DagNode) – The end joint for the effector

  • solverType (str) – “ikRPSolver” or “ikSCsolver” or “ikSplineSolver”

  • parent (base.DagNode) – The zapi Dag node to be the parent of the Handle.

  • curve(str) – The full path to the curve.

  • priority(int) – 1

  • weight(float) – 1.0

  • positionWeight(float) – 1.0

  • forceSolver(bool) – True

  • snapHandleFlagToggle(bool) – True

  • sticky(bool) – False

  • createCurve(bool) – True

  • simplifyCurve(bool) – True

  • rootOnCurve(bool) – True

  • twistType(str) – “linear”

  • createRootAxis(bool) – False

  • parentCurve(bool) – True

  • snapCurve(bool) – False

  • numSpans(int) – 1

  • rootTwistMode(bool) – False

Returns:

The handle and effector as zapi.DagNode

Return type:

tuple[base.IkHandle, base.DagNode]

createDisplayLayer(name)

Creates a standard displayLayer

Todo::

nodes as an argument.

nurbsCurveFromPoints(name, points, shapeData=None, parent=None)

Space Switching

buildConstraint(driven, drivers, constraintType='parent', trace=True, **kwargs)

This function builds a space switching constraint.

Currently, Supporting types of:

#. kParentConstraint
#. kPointConstraint
#. kOrientConstraint
#. kScaleConstraint
#. kMatrixConstraint, However doesn't support space switching.
Parameters:
  • driven – The transform to drive

  • drivenzapi.DagNode

  • drivers – A dict containing the target information(see below example)

  • drivers – dict or None

  • constraintType (str) – The constraint type :see above: CONSTRAINT_TYPES

  • trace (bool) – Whether the constraint and all nodes created should be tracked via metaData.

  • kwargs (dict) – The constraint extra arguments to use ie. maintainOffset etc.

  • (bool) (maintainOffset) – Whether to maintain the offset transformation.

Return type:

tuple[Constraint, list[base.DagNode]]

hasConstraint(node)

Determines if this node is constrained by another, this is done by checking the constraints compound attribute

Parameters:

node (base.DagNode) – the node to search for attached constraints

Return type:

bool

iterConstraints(node)

Generator function that loops over the attached constraints, this is done by iterating over the compound array attribute constraints.

Parameters:

node (base.DagNode) – The node to iterate, this node should already have the compound attribute

Returns:

First element is a list a driven transforms, the second is a list of utility nodes used to create the constraint.

Return type:

list[Constraint]

findConstraint(node, constraintType)

Searches the upstream graph one level in search for the corresponding kConstraintType

Parameters:
  • node (base.DagNode) – The node to search upstream from

  • constraintType (str) –

Returns:

Constraint class instance.

Return type:

Constraint

deleteConstraintMapAttribute(node, modifier=None)

Removes the constraint metaData if present on the provided node.

The metadata is found if the zooConstraint attribute is found.

Parameters:
  • node (zapi.DgNode) – The node the remove the metadata from.

  • modifier (zapi.dgModifier or None) – The Modifier instance to use.

Returns:

The provided modifier instance or the newly created one.

Return type:

zapi.dgModifier or None

deleteConstraints(objects, modifier=None)

Animation

gimbalTolerance(obj, ctx=MockExt.OpenMaya.MDGContext.kNormal)

Determines the gimbal tolerance value between 0 and 1 for the current Rotation Order.

Parameters:
  • obj (zapi.DagNode) – The node to check.

  • ctx (om2.MDGContext) – The time MDGContext instance to use other MDGContext.kNormal

Returns:

A value between 0 and 1

Return type:

float

allGimbalTolerances(obj, frames=None, step=1)

Determines the gimbal tolerance value between 0 and 1 for all rotation Orders.

If Frames is specified then an average is calculated for each rotationOrder across all Specified frames.

Parameters:
  • obj (zapi.DagNode) – The Object to query gimbal on.

  • frames (list[int]) – The individual frames to query ie. [0,1,2,3], if None then only the current state is queried.

  • step (int) – The amount of keys to skip between samples.

Return type:

list[float]

setRotationOrderOverFrames(nodes, rotationOrder, bakeEveryFrame=False, frameRange=None)

Change the rotation order of the specified nodes while preserving animation.

from zoo.libs.maya import zapi
# to set to XYZ
setRotationOrderOverFrames(zapi.selected(), zapi.kRotateOrder_XYZ)

Note

you should run this inside of your own undo chunk

Parameters:
  • nodes (iterable[DagNode]) – A list of Dag Nodes ie. transforms to convert

  • rotationOrder (int) – a rotation order to set to ie.zapi.kRotateOrder_XYZ

  • bakeEveryFrame (bool) – If True then all frames between the start and end will be baked.

  • frameRange – The start and end range to bake, defaults to None so only existing keys we be updated.

Type:

list[int, int]

keyFramesForNodes(objects, attributes, bakeEveryFrame=False, frameRange=None)

For each node yield the appropriate keyframes and rotationOrder.

See keyFramesForNode() for details.

Parameters:
  • objects (iterable[DagNode]) – A list of Dag Nodes ie. transforms to convert

  • attributes (list[str]) – The list of attributes to take into account of when reading keyframes.

  • bakeEveryFrame (bool) – If True then all frames between the start and end will be baked.

  • frameRange (list[int, int]) – The start and end range to bake, defaults to None so only existing keys we be updated.

Returns:

A generator function where each element contain a dict of {“keys”: [], “rotationOrder”: int, “name”: “”}

Return type:

iterable[dict]

keyFramesForNode(node, attributes, defaultKeyFrames=None, bakeEveryFrame=False, frameRange=None)

Returns the key frames, rotationOrder and name for the node based on the provided arguments.

Note

When bakeEveryFrame is True and frameRange is not None then the provided default is returned. This is Due to the need to cache the key list to optimise the function across multiple requests. When frameRange is None and BakeEveryFrame is True then the function will query the min and max keyFrames for the attributes and return all keyFrames on whole numbers between them.

Parameters:
  • node (base.DagNode) – The animated node to read.

  • attributes (list[str]) – The list of attributes to take into account of when reading keyframes.

  • defaultKeyFrames (list[int] or None) – Default keyframes to use when bakeEveryFrame is True and provided frameRange.

  • bakeEveryFrame (bool) – If True then all frames between the start and end will be baked.

  • frameRange (list[int, int]) – The start and end range to bake, defaults to None so only existing keys we be updated.

Returns:

Returns a dict containing a unique flat list of keys for the provided attributes, the rotationOrder for the node and the node name

Return type:

dict

autoKeyKeyFrameContext(state=False)

Context manager for autoKeyKeyframe.

Example:
with autoKeyKeyFrameContext():

cmds.setAttr(“pCube1.tx”, 10) cmds.setAttr(“pCube1.ty”, 10) cmds.setAttr(“pCube1.tz”, 10)

frameRanges(frames)

Generate a list of frame ranges from a given list of frames.

Parameters:

frames (list) – List of frames.

Returns:

List of frame ranges.

Return type:

list