Maya API Extension’s¶
In zoo we use mayas api quite extensively for operations which have a rather noticeable performance impact ie. rigging and animation.
While our front end api Zapi is still being extended as we go when need to contain more functionality with a OOP interface. What lies here as our library code which wraps maya api(mainly om2) into a set of raw Maya api functions and classes where required.
Attrtypes¶
This module contains a centralized way of handling the many maya attribute types
which are spread across many attribute classes and these constant values
tend to conflict with each other. By using the kConstant type in this
module in conjunction with zoo.libs.maya.api.plugs
and
zoo.libs.maya.api.nodes.addAttribute()
functions you will have a single entry
point in manipulating maya attributes.
- kMFnNumericBoolean = 0¶
kMFnNumericBoolean
- kMFnNumericShort = 1¶
kMFnNumericShort
- kMFnNumericInt = 2¶
kMFnNumericInt
- kMFnNumericLong = 2¶
kMFnNumericLong
- kMFnNumericByte = 4¶
kMFnNumericByte
- kMFnNumericFloat = 5¶
kMFnNumericFloat
- kMFnNumericDouble = 6¶
kMFnNumericDouble
- kMFnNumericAddr = 7¶
kMFnNumericAddr
- kMFnNumericChar = 8¶
kMFnNumericChar
- kMFnUnitAttributeDistance = 9¶
kMFnUnitAttributeDistance
- kMFnUnitAttributeAngle = 10¶
kMFnUnitAttributeAngle
- kMFnUnitAttributeTime = 11¶
kMFnUnitAttributeTime
- kMFnkEnumAttribute = 12¶
kMFnkEnumAttribute
- kMFnDataString = 13¶
kMFnDataString
- kMFnDataMatrix = 14¶
kMFnDataMatrix
- kMFnDataFloatArray = 15¶
kMFnDataFloatArray
- kMFnDataDoubleArray = 16¶
kMFnDataDoubleArray
- kMFnDataIntArray = 17¶
kMFnDataIntArray
- kMFnDataPointArray = 18¶
kMFnDataPointArray
- kMFnDataVectorArray = 19¶
kMFnDataVectorArray
- kMFnDataStringArray = 20¶
kMFnDataStringArray
- kMFnDataMatrixArray = 21¶
kMFnDataMatrixArray
- kMFnCompoundAttribute = 22¶
kMFnCompoundAttribute
- kMFnNumericInt64 = 23¶
kMFnNumericInt64
- kMFnNumericLast = 24¶
kMFnNumericLast
- kMFnNumeric2Double = 25¶
kMFnNumeric2Double
- kMFnNumeric2Float = 26¶
kMFnNumeric2Float
- kMFnNumeric2Int = 27¶
kMFnNumeric2Int
- kMFnNumeric2Long = 27¶
kMFnNumeric2Long
- kMFnNumeric2Short = 29¶
kMFnNumeric2Short
- kMFnNumeric3Double = 30¶
kMFnNumeric3Double
- kMFnNumeric3Float = 31¶
kMFnNumeric3Float
- kMFnNumeric3Int = 32¶
kMFnNumeric3Int
- kMFnNumeric3Long = 32¶
kMFnNumeric3Long
- kMFnNumeric3Short = 34¶
kMFnNumeric3Short
- kMFnNumeric4Double = 35¶
kMFnNumeric4Double
- kMFnMessageAttribute = 36¶
kMFnMessageAttribute
- mayaNumericTypeToInternalType(mayaType)¶
Returns the zoo internal attribute type for the maya numeric type
- Parameters
mayaType (om2.MFnNumericData.kBoolean) – The maya attribute type
- Returns
One of our internal types ie. kMFnNumericBoolean
- Return type
- numericTypeToMayaFnType(Type)¶
Returns the numeric attribute function object and the data type numericData.ktype for the provided zoo type or None,None.
- mayaUnitTypeToInternalType(mayaType)¶
Returns the zoo internal attribute type for the maya unit attribute type
- Parameters
mayaType (om2.MFnUnitAttribute.kDistance) – The maya attribute type
- Returns
One of our internal types ie. kMFnUnitAttributeDistance
- Return type
- mayaMFnDataTypeToInternalType(mayaType)¶
Returns the zoo internal attribute type for the maya TypeAttribute type.
- Parameters
mayaType (om2.MFnData.kString) – The maya attribute type
- Returns
One of our internal types ie. kMFnDataString
- Return type
- mayaTypeToInternalType(mayaType)¶
Returns the zoo internal attribute type for the maya attribute type
- Parameters
mayaType (om2.MFn.kEnumAttribute, om2.MFn.kMessageAttribute , om2.MFn.kMatrixAttribute) – The maya attribute type
- Returns
One of our internal types ie. kMFnkEnumAttribute, kMFnMessageAttribute, kMFnDataMatrix
- Return type
- typeToString(attrType, default=None)¶
Returns the zoo attribute type as as a string name .. example:
typeToString(attrtypes.kMFnNumericBoolean) # “kMFnNumericBoolean”
- mayaTypeFromType(Type)¶
Converts the zoo attribute constant type to the maya type.
- mayaTypeToPythonType(mayaType)¶
From the maya data type return the same type but as a python type ie. MMatrix -> list
- pythonTypeToMayaType(dataType, value)¶
Anim¶
- currentTimeInfo()¶
Returns a dict of all the current timeline settings
- Return type
currentTimeInfo() # result {"currentTime": om2.MTime, "start": 0, "end": 1, "unit": 12, "fps": 25}
- setCurrentRange(start, end, newCurrentFrame)¶
Set’s maya’s frame range and the current time number.
- formatFrameRange()¶
Return’s mayas current frame range as a format string.
- Returns
“0:100” startframe:endFrame
- Return type
- formatFrame()¶
Returns the current frame rate as a formatted string.
- Returns
“0:100(30 FPS)” startFrame:endFrame(FPS)
- Return type
- formatCurrentTime()¶
- maintainTime()¶
Context manager for preserving (resetting) the time after the context
- iterFrameRangeDGContext(start, end, step=1)¶
Generator function to iterate over a time range returning a MDGContext for the current frame.
- iterFramesDGContext(frames, step=1)¶
Generator function to iterate over a time range returning a MDGContext for the current frame.
- serializeAnimCurve(animCurveNode)¶
Callbacks¶
- class MCallbackIdWrapper(callbackId)¶
Bases:
object
Wrapper class to handle cleaning up of MCallbackIds from registered MMessage
- removeCallbacksFromNode(mobject)¶
- Parameters
mobject (om2.MObject) – The node to remote all node callbacks from
- Returns
the number of callbacks removed
- Return type
- removeCallbacksFromNodes(mobjects)¶
Will remove all callbacks from each node.
- Parameters
mobjects (sequence(MObject)) – The nodes to remove callbacks from
- Returns
total count of all callbacks removed
- Return type
- class CallbackSelection(func, *args, **kwargs)¶
Bases:
object
Class handles the management of a single selection callback which can be stored in a GUI.
To activate the callback use start() To cleanup run stop()
- Note
Selected objects are passed to the callback as a keyword argument “selection”
from zoo.libs.maya.api import nodes def myCallbackFunction(selection): # do stuff to the selection which is a list of OpenMaya.MObjectHandle for MObjectHandle in selection: if not i.isValid() or not i.isAlive(): continue # print the fullPathName of the selected, FYI: this has arguments for stripping namespace etc too. print(nodes.nameFromMObject(i.object())) callbackInstance = CallbackSelection(myCallbackFunction) # add the function here callbackInstance.start() callbackInstance.stop()
- mayaSelectionChanged(*args, **kwargs)¶
The Open Maya 2 code for monitoring a selection callback with a short and longname list of strings
- start()¶
Creates and stores the selection callback on this instance.
- stop()¶
Cleans up the instance by removing the maya api callback
Curves¶
- getCurveData(shape, space=MockExt.OpenMaya.MSpace.kObject, includeColours=True)¶
From a given NurbsCurve shape node serialize the cvs positions, knots, degree, form rgb colours
- Parameters
shape – MObject that represents the NurbsCurve shape
space (om2.MSpace) –
- Returns
dict
nurbsCurve = cmds.circle()[1] # requires an MObject of the shape node data = curve_utils.getCurveData(api.asMObject(nurbsCurve))
- createCurveShape(parent, data, space=MockExt.OpenMaya.MSpace.kObject, mod=None)¶
Create a specified nurbs curves based on the data.
- Parameters
- Returns
A 2 tuple the first element is the MObject of the parent and the second is a list of mobjects represents the shapes created.
- Return type
iterable[
om2.MObject
, list[om2.MObject
]]
- createCurveFromPoints(name, points, shapeDict={'cvs': (), 'degree': 3, 'form': 1, 'knots': (), 'matrix': (1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0), 'outlinerColor': (0.0, 0.0, 0.0), 'overrideColorRGB': (0.0, 0.0, 0.0), 'overrideEnabled': False, 'overrideRGBColors': False, 'useOutlinerColor': False}, parent=None)¶
- createBezierCurve(name, points, degree=3, knots=None, parent=None)¶
Creates a Bezier curve from the provided points and degree and returns an om2.MObject.
- Parameters
name (str) – The name for the curve
points (list[list[float, float, float]]) – 2D list of point positions.
degree (int) – The curve degree, default is 3.
knots (list[float] or None) – point knots, must be len(points) + degree -1. If None knots will be auto generated.
parent (
om2.MObject
or None) – The parent transform for the curve, if None a new transform is created.
- Returns
The curve as a MObject.
- Return type
om2.MObject
- serializeCurve(node, space=MockExt.OpenMaya.MSpace.kObject, includeColours=True)¶
From a given transform serialize the shapes curve data and return a dict compatible with Json.
- Parameters
node (MObject) – The MObject that represents the transform above the nurbsCurves
- Returns
returns the dict of data from the shapes
- Return type
- mirrorCurveCvs(curveObj, axis='x', space=None)¶
Mirrors the the curves transform shape cvs by a axis in a specified space
- Parameters
- Example
nurbsCurve = cmds.circle()[0] mirrorCurveCvs(api.asMObject(nurbsCurve), axis=’y’, space=om.MSpace.kObject)
- iterCurvePoints(dagPath, count, space=MockExt.OpenMaya.MSpace.kObject)¶
Generator Function to iterate and return the position, normal and tangent for the curve with the given point count.
- Parameters
dagPath (om2.MDagPath) – the dagPath to the curve shape node
count (int) – the point count to generate
space (om2.MSpace) – the coordinate space to query the point data
- Returns
The first element is the Position, second is the normal, third is the tangent
- Return type
tuple(MVector, MVector, MVector)
- matchCurves(driver, targets, space=MockExt.OpenMaya.MSpace.kObject)¶
Function that matches the curves from the driver to all the targets.
- Parameters
driver (om2.MObject) – the transform node of the shape to match
targets (list(om2.MObject) or tuple(om2.MObject)) – A list of transform that will have the shapes replaced
- curveCvs(dagPath, space=MockExt.OpenMaya.MSpace.kObject)¶
Generator Function to iterate and return the position, normal and tangent for the curve with the given point count.
- Parameters
dagPath (om2.MDagPath) – the dagPath to the curve shape node
space (om2.MSpace) – the coordinate space to query the point data
- Returns
The first element is the Position, second is the normal, third is the tangent
- Return type
tuple(om2.MPoint)
- iterCurveParams(dagPath, count)¶
Generator Function to iterate and return the Parameter
- attachNodeToCurveAtParam(curve, node, param, name, rotate=True, fractionMode=False)¶
Attaches the given node to the curve using a motion path node.
- Parameters
curve (om2.MObject) – nurbsCurve Shape to attach to
node (om2.MObject) – the node to attach to the curve
param (float) – the parameter float value along the curve
name (str) – the motion path node name to use
rotate (bool) – Whether to connect rotation from the motion path to the node.
fractionMode (bool) – True if the motion path should use fractionMode(0.1) vs False(0-2)
- Returns
motion path node
- Return type
om2.MObject
- iterGenerateSrtAlongCurve(dagPath, count, name, rotate=True, fractionMode=False)¶
Generator function to iterate the curve and attach transform nodes to the curve using a motionPath
- Parameters
dagPath (om2.MDagPath) – the dagpath to the nurbscurve shape node
count (int) – the number of transforms
name (str) – the name for the transform, the motionpath will have the same name plus “_mp”
rotate (bool) – Whether to connect rotation from the motion path to the SRT.
fractionMode (bool) – True if the motion path should use fractionMode(0.1) vs False(0-2)
- Returns
Python Generator first element is the created transform node, the second is the motionpath node
- Return type
Generate(tuple(om2.MObject, om2.MObject))
- rotationsAlongCurve(curveShape, count, aimVector, upVector, worldUpVector)¶
Returns the position and rotation along the curve incrementally based on the jointCount provided.
- Parameters
curveShape (
om2.MDagPath
) – The NurbsCurve shape DagPath to use.count (int) – The number of points along the curve to use.
aimVector (
om2.MVector
) – The primary axis to align along the curve. ie. om2.MVector(1.0,0.0,0.0)upVector (
om2.MVector
) – The upVector axis to use. ie. om2.MVector(0.0,1.0,0.0)worldUpVector (
om2.MVector
) – The secondary world up Vector to use. ie. om2.MVector(0.0,0.0,1.0)
- Returns
Returns a generator containing the position and rotation.
- Return type
tuple[
om2.MVector
,om2.MQuaternion
]
Deformers¶
This modules handles maya native deformer queries including serializing weights etc.
- class SkinCluster(cluster)¶
Bases:
object
Thin wrapper class around getting and setting skin weights
- influenceWeights()¶
Returns a dictionary containing the influence objects data.
- Returns
A dictionary with the influence objects data, where the keys are the partial names of the influence objects and the values are lists of weights corresponding to each influence object.
- Return type
- blendWeights()¶
Returns the blend weights of the cluster as a tuple :return: :rtype:
- geometryComponentsFromSet(mobjectSet)¶
Returns the dagpath and geometry components from the maya set mobject
- skinClustersFromJoints(joints)¶
From a set of joints, find and retrieve the skinClusters as om2.MObject
- Parameters
joints (list[
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
]) – a sequence of zapi DagNodes representing kJoint- Returns
the retrieved skin clusters from the joints
- Return type
list[
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
]
- skinClustersFromJoint(joint)¶
Skin clusters from joint
- Parameters
joint (
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
) – Joint as DagNode- Returns
- Return type
list[
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
]
- skinClustersConnectedMeshes(skinClusters)¶
Returns mesh list from skinClusters
- Parameters
skinClusters (list[
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
]) – skinClusters as dag/dg node- Return nodes
The connected meshes
- Rtype nodes
list[
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
]
- jointsConnectedMeshes(joints)¶
- jointConnectedMeshes(joint)¶
Get connected meshes from joints
- Parameters
joint (
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
) – Joint as dag/dg node- Returns
List of geometries connected
- Return type
list[
zoo.libs.maya.zapi.base.DagNode or zoo.libs.maya.zapi.base.DGNode
]
- clusterUpstreamFromNode(node)¶
Find’s and returns the skin clusters upstream of the given node
- Parameters
node (om2.MObject) – the DGNode to query
- Returns
theA sequence of skin cluster nodes
- Return type
list(om2.MObject)
- serializeClusters(clusters)¶
For the given skin clusters, serialize them to a dict
- Parameters
clusters (list(om2.MObject)) – A sequence of MObjects representing the skinClusters
- Return type
list(dict)
- serializeSkinWeightsFromShapes(shapes)¶
Serializes the geometry shape skinCluster weights to a dict.
example:
{my|objectName: {"points": [[11.720806121826172,11.951449566072865,0.47714900970458984,1]], "skinData": [{ "name": "roboRig:skinCluster_hand01_L", "maxInfluence": 5, "maintainMaxInfluences": true, "skinningMethod": 0, "weights": { "|L_wrist": [1,0,1,0] }] } }
- Parameters
shapes (om2.MObject) – The MObjects representing the shape nodes to serialize
- Return type
- applyWeightsFromData(data, shape)¶
- createAndImportWeightsFromShapes(filePath, shapes)¶
Loads the skin data from the filePath and loads it on the shapeNodes.
If any of the shapes have existing skinClusters then the weights will be replaced. Otherwise a skin cluster will be created.
Generic¶
- class MObjectHandleWrap(*args: Any, **kwargs: Any)¶
Bases:
MObjectHandle
Simple class to do what Autodesk should of done, this class makes the MObjectHandle hashable so it can be used in sets and dicts correctly.
- Note:
maya’s documentation says >, >=, <, <= but this isn’t true at all part from the errors the c++ docs don’t specify it so c++ is right, geez get your shit right.
- isValidMObjectHandle(mObjHandle)¶
Checks whether the MObjectHandle is valid in the scene and still alive
- Parameters
mObjHandle – OpenMaya.MObjectHandle
- isValidMObject(mObj)¶
Checks whether the MObject is valid in the scene.
- Parameters
mObj (OpenMaya.MObject.) – The mobject to validate.
- Returns
Whether or not this MObject is currently valid in the scene.
- Return type
bool.
- compareMObjects(a, b)¶
Compares two nodes and returns whether they’re equivalent or not - the compare is done on MObjects not strings.
- asMObject(name)¶
- asEuler(rotation)¶
Converts tuple(float3) into a MEulerRotation
- Parameters
rotation (tuple(float)) – a tuple of 3 elements in degrees which will be converted to redians for the eulerRotation
- Return type
MEulerRotation
- eulerToDegrees(euler)¶
- softSelection()¶
Gets the current component softSelection
- intToMTransformRotationOrder(rotateOrder)¶
- stripNamespaceFromName(name)¶
Does what maya’s om2.MNamespace.stripNamespaceFromName(name) was suppose to do. Autodesk results:
name = u'|agagaa:NewNamespace1:joint1|agagaa:NewNamespace1:joint2|agagaa:NewNamespace1:joint3 om2.MNamespace.stripNamespaceFromName(name) # 'joint3' generic.stripNamespaceFromName(name) # u'|joint1|joint2|joint3'
Nodes¶
- exception MissingObjectByName¶
Bases:
Exception
- exception AttributeAlreadyExists¶
Bases:
Exception
- asMObject(name)¶
Returns the MObject from the given name
- Parameters
name (str or MObjectHandle or MDagPath) – The name to get from maya to convert to a mobject
- Returns
The mobject for the given str
- Return type
MObject
- nameFromMObject(mobject, partialName=False, includeNamespace=True)¶
This returns the full name or partial name for a given mobject, the mobject must be valid.
- Parameters
- Returns
the name of the mobject
- Return type
from zoo.libs.maya.api import nodes node = nodes.asMobject(cmds.polyCube()) print nodes.nameFromMObject(node, partial=False) # returns the fullpath, always prepends '|' eg '|polyCube' print nodes.nameFromMObject(node, partial=True) # returns the partial name eg. polyCube1
- toApiMFnSet(node)¶
Returns the appropriate mObject from the api 2.0
- Parameters
node (str, MObjectHandle) – str, the name of the node
- Returns
MFnDagNode, MPlug, MFnDependencyNode
- Return type
MPlug or MFnDag or MFnDependencyNode
from zoo.libs.maya.api import nodes node = cmds.polyCube()[0] # str nodes.toApiObject(node) # Result MFnDagNode node = cmds.createNode("multiplyDivide") nodes.toApiObject(node) # Result MFnDependencyNode
- asDagPath(node)¶
- setNodeColour(node, colour, outlinerColour=None, useOutlinerColour=False, mod=None)¶
Set the given node mobject override color can be a mobject representing a transform or shape
- Parameters
node (mobject) – the node which you want to change the override colour of
colour (MColor or tuple) – The RGB colour to set
- getNodeColourData(node)¶
- Parameters
node (MObject) – The maya node mobject that you want to get the override colour from
- Returns
{“overrideEnabled”: bool, “overrideColorRGB”: plugs.getAttr(plug), “overrideRGBColors”: plugs.getAttr(overrideRGBColors)}
- Return type
- createDagNode(name, nodeType, parent=None, modifier=None, apply=True)¶
Creates a new dag node and if there’s a parent specified then parent the new node
- Parameters
- Returns
The newly create nodes mobject
- Return type
MObject
- createDGNode(name, nodeType, mod=None, apply=True)¶
Creates and dependency graph node and returns the nodes mobject
- lockNode(mobject, state=True, modifier=None)¶
Set the lock state of the node
- Parameters
mobject (MObject) – the node mobject to set the lock state on
state (bool) – the lock state for the node
- lockNodeContext(mobject, state)¶
- unlockConnectedAttributes(mobject)¶
Unlocks all connected attributes to this node
- Parameters
mobject (MObject) – MObject representing the DG node
- unlockedAndDisconnectConnectedAttributes(mobject)¶
Unlcoks and disocnnects all attributes on the given node
- Parameters
mobject (MObject) – MObject respresenting the DG node
- containerFromNode(mobj)¶
Finds and returns the AssetContainer mobject from the give node.
- Parameters
mobj (om2.MObject) – The om2.MObject representing the node to filter.
- Returns
The container MObject found from the mobject else None
- Return type
om2.MObject or None
- childPathAtIndex(path, index)¶
From the given MDagPath return a new MDagPath for the child node at the given index.
- Returns
MDagPath, this path’s child at the given index
- childPaths(path)¶
Returns all the MDagPaths that are a child of path.
- Parameters
path (maya.api.OpenMaya.MDagPath) –
- Returns
child MDagPaths which have path as parent
- Return type
list[maya.api.OpenMaya.MDagPath]
- childPathsByFn(path, fn)¶
Get all children below path supporting the given MFn.type
- Parameters
path – MDagpath
fn – member of MFn
- Returns
list(MDagPath), all matched paths below this path
- iterShapes(path, filterTypes=())¶
Generator function which all the shape dagpaths directly below this dagpath
- Parameters
path – The MDagPath to search
- Returns
list(MDagPath)
- shapes(path, filterTypes=())¶
:Depreciated Use IterShapes()
- shapeAtIndex(path, index)¶
Finds and returns the shape DagPath under the specified path for the index
- Parameters
path (om2.MDagPath) – the MDagPath to the parent node that you wish to search under
index (int) – the shape index
- Return type
om2.MDagPath or None
- childTransforms(path)¶
Returns all the child transform from the given DagPath
- Returns
list(MDagPath) to all transforms below path
- setParent(child, newParent, maintainOffset=False, mod=None, apply=True)¶
Sets the parent for the given child
- Parameters
child (om2.MObject) – the child node which will have its parent changed
newParent (om2.MObject) – The new parent for the child
maintainOffset (bool) – if True then the current transformation is maintained relative to the new parent
mod (om2.MDagModifier) – The MDagModifier to add to, if none it will create one
apply (bool) – Apply the modifier immediately if true, false otherwise
- Return type
- childContext(parent)¶
- hasParent(mobject)¶
Determines if the given MObject has a mobject
- Parameters
mobject (MObject) – the MObject node to check
- Return type
- rename(mobject, newName, modifier=None, apply=True)¶
Renames the given mobject node, this is undoable.
- Parameters
mobject (om2.MObject) – the node to rename
newName (str) – the new unique name for the node
modifier (om2.MDGModifier or None) – if you pass a instance then the rename will be added to the queue then returned otherwise a new instance will be created and immediately executed.
apply (bool) – Apply the modifier immediately if true, false otherwise
Note
If you pass a MDGModifier then you should call doIt() after calling this function
- parentPath(path)¶
Returns the parent nodes MDagPath
- Parameters
path (MDagpath) – child DagPath
- Returns
MDagPath, parent of path or None if path is in the scene root.
- isValidMDagPath(dagPath)¶
Determines if the given MDagPath is valid
- Parameters
dagPath – MDagPath
- Returns
bool
- iterParents(mobject)¶
- isSceneRoot(node)¶
- isUnderSceneRoot(node)¶
Determines if the specified node is currently parented to world.
- Parameters
node (
om2.MObject
) – The maya Dag MObject- Return type
- iterChildren(mObject, recursive=False, filter=None)¶
Generator function that can recursive iterate over the children of the given MObject.
- Parameters
mObject (MObject) – The MObject to traverse must be a MObject that points to a transform
recursive (bool) – Whether to do a recursive search
filter (tuple or None) – tuple(om.MFn) or None, the node type to find, can be either ‘all’ for returning everything or a om.MFn type constant does not include shapes
- Returns
om.MObject
- breadthFirstSearchDag(node, filter=None)¶
- getChildren(mObject, recursive=False, filter=(MockExt.OpenMaya.MFn.kTransform,))¶
- This function finds and returns all children mobjects under the given transform, if recursive then including
sub children.
- Parameters
mObject – om.MObject, the mObject of the transform to search under
recursive – bool
filter – tuple(om.MFn.kTransform, the node type to filter by
- Returns
list(MFnDagNode)
- iterAttributes(node, skip=None, includeAttributes=())¶
- iterExtraAttributes(node, skip=None, filteredTypes=None, includeAttributes=None)¶
Generator function to iterate over all extra plugs(dynamic) of a given node.
- Parameters
node (om2.MObject) – The DGNode or DagNode to iterate
filteredTypes (tuple(attrtypes.kType)) –
- Returns
Generator function with each item equaling a om2.MPlug
- Return type
iterable[om2.MPlug]
- iterConnections(node, source=True, destination=True)¶
Returns a generator function containing a tuple of MPlugs
- Parameters
- Returns
tuple of om2.MPlug instances, the first element is the connected MPlug of the given node(
node
) The second element is the connected MPlug from the other node.- Return type
Generator(tuple(om2.MPlug, om2.MPlug))
- iterKeyablePlugs(node)¶
- iterChannelBoxPlugs(node)¶
- getRoots(nodes)¶
- getRoot(mobject)¶
Traversals the objects parent until the root node is found and returns the MObject
- Parameters
mobject – MObject
- Returns
MObject
- getParent(mobject)¶
Returns the parent MFnDagNode if it has a parent else None
- Parameters
mobject – MObject
- Returns
MObject or None
- isValidMObject(node)¶
- delete(node)¶
Delete the given nodes
- Parameters
node –
- removeUnknownNodes()¶
- getOffsetMatrix(startObj, endObj, space=MockExt.OpenMaya.MSpace.kWorld, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns The offset matrix between two objects.
- Parameters
startObj (
om2.MObject
) – Start Transform MObject.endObj (
om2.MObject
) – End Transform MObject.space (om2.MSpace.kSpace) – Coordinate space to use.
ctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
The resulting Offset MMatrix.
- Return type
om2.MMatrix
- getMatrix(mobject, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the MMatrix of the given mobject
- Parameters
mobject (
om2.MObject
) – MObjectctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
om2.MMatrix
- worldMatrixPlug(mobject)¶
- getWorldMatrix(mobject, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the worldMatrix value as an MMatrix.
- Parameters
mobject (
om2.MObject
) – the MObject that points the dagNodectx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
MMatrix
- decomposeMatrix(matrix, rotationOrder, space=MockExt.OpenMaya.MSpace.kWorld)¶
- parentInverseMatrixPlug(mobject)¶
- getWorldInverseMatrix(mobject, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the world inverse matrix of the given MObject
- Parameters
mobject (
om2.MObject
) – MObjectctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
MMatrix
- getParentMatrix(mobject, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the parent matrix of the given MObject
- Parameters
mobject (
om2.MObject
) – MObjectctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
MMatrix
- getParentInverseMatrix(mobject, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the parent inverse matrix from the MObject
- Parameters
mobject (
om2.MObject
) – MObjectctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
MMatrix
- hasAttribute(node, name)¶
Searches the node for a give a attribute name and returns True or False
- Parameters
node – MObject, the nodes MObject
name – str, the attribute name to find
- Returns
bool
- setMatrix(mobject, matrix, space=MockExt.OpenMaya.MSpace.kTransform)¶
Sets the objects matrix using om2.MTransform.
- Parameters
mobject (
om2.MObject
) – The transform MObject to modifymatrix (
om2.MMatrix
) – The maya MMatrix to setspace (
om2.MSpace.kWorld
) – The coordinate space to set the matrix by
- setTranslation(obj, position, space=None, sceneUnits=False)¶
- getTranslation(obj, space=None, sceneUnits=False)¶
- cvPositions(shape, space=None)¶
- setCurvePositions(shape, points, space=None)¶
- setRotation(node, rotation, space=MockExt.OpenMaya.MSpace.kTransform)¶
- getRotation(obj, space, asQuaternion=False)¶
- Parameters
obj (om2.MObject or om2.MDagPath) –
space –
asQuaternion –
- Returns
- Return type
- setCompoundAsProxy(compoundPlug, sourcePlug)¶
- addProxyAttribute(node, sourcePlug, **kwargs)¶
- addCompoundAttribute(node, longName, shortName, attrMap, isArray=False, apply=True, mod=None, **kwargs)¶
Add compound attribute.
- Parameters
node (om2.MObject) – the node to add the compound attribute too.
longName (str) – The compound longName
shortName (str) – The compound shortName
isArray (bool) – Whether
apply (bool) – If True then the value we be set on the Plug instance by calling doIt on the modifier.
mod (
om2.MDGModifier
) – Apply the modifier instantly or leave it to the caller.attrMap (list(dict())) – [{“name”:str, “type”: attrtypes.kType, “isArray”: bool}]
- Returns
the MObject attached to the compound attribute
- Return type
om2.MFnCompoundAttribute
attrMap = [{"name":"something", "Type": attrtypes.kMFnMessageAttribute, "isArray": False}] print attrMap # result <OpenMaya.MObject object at 0x00000000678CA790> #
- addAttributesFromList(node, data)¶
Creates an attribute on the node given a list(dict) of attribute data:
[{ "channelBox": true, "default": 3, "isDynamic": true, "keyable": false, "locked": false, "max": 9999, "min": 1, "name": "jointCount", "softMax": null, "softMin": null, "Type": 2, "value": 3 "isArray": True }]
- Parameters
data (dict) – The serialized form of the attribute
- Returns
A list of create MPlugs
- Return type
list(om2.MPlug)
- addAttribute(node, longName, shortName, attrType=6, isArray=False, apply=True, mod=None, **kwargs)¶
This function uses the api to create attributes on the given node, currently WIP but currently works for string,int, float, bool, message, matrix. if the attribute exists a ValueError will be raised.
- Parameters
node – MObject
longName (str) – The long name for the attribute.
shortName (str) – str, the shortName for the attribute.
attrType (attrtypes.kConstant) – attribute Type, attrtypes constants.
isArray (bool) – Is the attribute an array?.
mod (
om2.MDGModifier
) – The Undo Modifier to use.apply (bool) – if False the attribute will be immediately created on the node else just return the attribute instance.
channelBox(bool) – Should the attribute be displayed in the Channel Box?.
keyable(bool) – Can keys be set on the attribute?.
default – The default value for the attribute.
value – The value for the attribute to use.
enums – List of fields which this attribute will have, only valid for EnumAttribute.
storable(bool) – Should attr value be stored when written to file?.
writable(bool) – Is the attribute writable?.
connectable(bool) – Can connections be made to the attribute?.
min(int,float) – Returns the attribute’s hard minimum value(s).
max(int,float) – Returns the attribute’s hard maximum value(s).
softMin(int,float) – Returns the attribute’s soft minimum value.
softMax(int,float) – Returns the attribute’s soft maximum value.
locked(bool) – True if plug is locked against changes.
- Return type
om2.MFnAttribute
# message attribute attrMobj = addAttribute(myNode, "testMsg", "testMsg", attrType=attrtypes.kMFnMessageAttribute, isArray=False, apply=True) # double angle attrMobj = addAttribute(myNode, "myAngle", "myAngle", attrType=attrtypes.kMFnUnitAttributeAngle, keyable=True, channelBox=False) # double angle attrMobj = addAttribute(myNode, "myEnum", "myEnum", attrType=attrtypes.kMFnkEnumAttribute, keyable=True, channelBox=True, enums=["one", "two", "three"])
- serializeNode(node, skipAttributes=None, includeConnections=True, includeAttributes=(), extraAttributesOnly=False, useShortNames=False, includeNamespace=True)¶
This function takes an om2.MObject representing a maya node and serializes it into a dict, This iterates through all attributes, serializing any extra attributes found, any default attribute has not changed (defaultValue) and not connected or is an array attribute will be skipped. if arg includeConnections is True then all destination connections are serialized as a dict per connection.
- Parameters
node (om2.MObject) – The node to serialize
skipAttributes (list or None) – The list of attribute names to serialization.
includeConnections (bool) – If True find and serialize all connections where the destination is this node.
includeAttributes (iterable) – If Provided then only these attributes will be serialized
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
Returns values:
{ "attributes": [ { "Type": 10, "channelBox": false, "default": 0.0, "isArray": false, "isDynamic": true, "keyable": true, "locked": false, "max": null, "min": null, "name": "toeRest", "softMax": 3.14, "softMin": -1.7, "value": 0.31353071143768485 }, ], "connections": [ { "destination": "|legGlobal_L_cmpnt|control|configParameters", "destinationPlug": "plantLength", "source": "|legGlobal_L_guide_heel_ctrl|legGlobal_L_guide_tip_ctrl", "sourcePlug": "translateZ" }, ], "name": "|legGlobal_L_cmpnt|control|configParameters", "parent": "|legGlobal_L_cmpnt|control", "type": "transform" }
- deserializeNode(data, parent=None, includeAttributes=True)¶
example Data:
{ "attributes": [ { "Type": 10, "channelBox": false, "default": 0.0, "isArray": false, "isDynamic": true, "keyable": true, "locked": false, "max": null, "min": null, "name": "toeRest", "softMax": 3.14, "softMin": -1.7, "value": 0.31353071143768485 }, ], "name": "|legGlobal_L_cmpnt|control|configParameters", "parent": "|legGlobal_L_cmpnt|control", "type": "transform" }
- Parameters
- Returns
The created node MObject, a list of created attributes
- Return type
tuple(MObject, list(om2.MPlug))
- setLockStateOnAttributes(node, attributes, state=True)¶
Locks and unlocks the given attributes
- showHideAttributes(node, attributes, state=True)¶
Shows or hides and attribute in the channelbox
- mirrorJoint(node, parent, translate, rotate, mirrorFunction=0)¶
- mirrorTransform(node, parent, translate, rotate, mirrorFunction=0)¶
Mirror’s the translation and rotation of a node relative to another unless the parent is specified as om2.MObject.kNullObj in which case world.
- Parameters
- Returns
mirrored translation vector and the mirrored rotation matrix
- Return type
om2.MVector, om2.MMatrix
- mirrorNode(node, parent, translate, rotate, mirrorFunction=0)¶
- matchTransformMulti(targetPaths, source, translation=True, rotation=True, scale=True, space=MockExt.OpenMaya.MSpace.kWorld, pivot=False)¶
Matches the transform(SRT) for a list of nodes to another node.
- Parameters
targetPaths (list(om2.MDagPath)) – A list om2.MDagPaths to snap to the source
source (om2.MObject) – The source transform node switch the target nodes will match
translation (bool) – True to match translation
rotation (bool) – True to match rotation
scale (bool) – True to match scale
space (int) – coordinate space
pivot (True to match pivot) –
- Returns
True if passed
- Return type
- matchTransformSingle(targetPath, source, translation=True, rotation=True, scale=True, space=MockExt.OpenMaya.MSpace.kWorld, pivot=False)¶
Matches the transform(SRT) for a list of nodes to another node.
- Parameters
targetPath (om2.MDagPath) – om2.MDagPath to snap to the source
source (om2.MObject) – The source transform node switch the target nodes will match
translation (bool) – True to match translation
rotation (bool) – True to match rotation
scale (bool) – True to match scale
space (int) – coordinate space
pivot (True to match pivot) –
- Returns
True if passed
- Return type
- swapOutgoingConnections(source, destination, plugs=None)¶
- Parameters
source – The source node to transfer connections from
destination – The destination node to transfer connections to.
plugs – plug list to to swap, if None is used then all connections will be swapped
- Return type
om2.modifier the maya modifier which will require you to call doIt()
Todo
deal with selected child attributes when only the compound is selected
Plugs¶
- asMPlug(name)¶
Returns the MPlug instance for the given name
- Parameters
name – The mobject to convert to MPlug
- Rtype name
str
- Returns
MPlug, or None
- connectPlugs(source, destination, mod=None, force=True, apply=True)¶
Connects two MPlugs together
- connectVectorPlugs(sourceCompound, destinationCompound, connectionValues, force=True, modifier=None, apply=True)¶
- Parameters
sourceCompound (om2.MPlug) –
destinationCompound (om2.MPlug) –
connectionValues (seq(str)) – Bool value for each axis if all axis are tre then just connect the compound
- Return type
om2.MDGModifier
- disconnectPlug(plug, source=True, destination=True, modifier=None)¶
Disconnect the plug connections, if ‘source’ is True and the ‘plug’ is a destination then disconnect the source from this plug. If ‘destination’ True and plug is a source then disconnect this plug from the destination. This function will also lock the plugs otherwise maya raises an error
- Parameters
- Returns
True if succeed with the disconnection
- Return type
- Raises
maya api error
- removeElementPlug(plug, elementNumber, mod=None, apply=False)¶
Functional wrapper for removing a element plug(multiinstance)
- Parameters
plug (om2.MPlug) – The plug array object
elementNumber (int) – the element number
mod (om2.MDGModifier or None) – If None then a om2.MDGModifier object will be created and returned else the one thats passed will be used.
apply (bool) – If False then mod.doIt() will not be called, it is the clients reponsiblity to call doIt, useful for batch operations.
- Returns
The MDGModifier instance which contains the operation stack.
- Return type
om2.MDGModifier
- removeUnConnectedEmptyElements(plugArray, mod=None)¶
Removes all unconnected array plug elements.
This works by iterating through all plug elements and checking the isConnected flag, if the element plug is a compound then we can the children too.
Note
Currently only handles two dimensional arrays.
- Parameters
plugArray (
om2.MPlug
) – The plug array instance.mod (
om2.MDGModifier
or None) – If passed then this modifier will be used instead of creating a new one.
- Returns
The MDGModifier instance, if one is passed in the mod argument then that will be returned.
- Return type
om2.MDGModifier
- isValidMPlug(plug)¶
Checks whether the MPlug is valid in the scene
- Parameters
plug – OpenMaya.MPlug
- Returns
bool
- setLockedContext(plug)¶
Context manager to set the ‘plug’ lock state to False then reset back to what the state was at the end
- Parameters
plug (om2.MPlug) – the MPlug to work on
- setLockState(plug, state)¶
Sets the ‘plug’ lock state
- filterConnected(plug, filter)¶
Filters all connected plugs by name using a regex with the filter argument. The filter is applied to the plugs connected plug eg. if nodeA.translateX is connected to nodeB.translateX and this func is used on nodeA.translateX then nodeB.translateX will have the filter applied to the plug.name() :param plug: The plug to search the connections from. :type plug: om2.MPlug :param filter: the regex string :type filter: str :rtype: iterable(om2.MPlug)
- filterConnectedNodes(plug, filter, source=True, destination=False)¶
- iterDependencyGraph(plug, alternativeName='', depthLimit=256, transverseType='down')¶
This recursive function walks the dependency graph based on the name. so each node it visits if that attribute exists it will be return. example connections : nodeA.test -> nodeB.test -> nodeC.test [nodeA,nodeB, nodeC] will be return as a generator
- serializePlug(plug)¶
Take’s a plug and serializes all necessary information into a dict.
Return data is in the form:
{name: str, "isDynamic": bool, "default": type, "min": type, "max": type, "softMin": type, "softMax": type}
- Parameters
plug (MPlug) – the valid MPlug to serialize
- Returns
with out connection data.
- Return type
- serializeConnection(plug)¶
Take’s destination om2.MPlug and serializes the connection as a dict.
- Parameters
plug (om2.MPlug) – A om2.MPlug that is the destination of a connection
- Returns
{sourcePlug: str, destinationPlug: str, source: str, # source node destination: str} # destination node
- Return type
- enumNames(plug)¶
Returns the ‘plug’ enumeration field names.
- Parameters
plug (om2.MPlug) – the MPlug to query
- Returns
A sequence of enum names
- Return type
list(str)
- enumIndices(plug)¶
Returns the ‘plug’ enums indices as a list.
- Parameters
plug (om2.MPlug) – The MPlug to query
- Returns
a sequence of enum indices
- Return type
list(int)
- plugDefault(plug)¶
- setAttributeFnDefault(attribute, default)¶
- setPlugDefault(plug, default)¶
- hasPlugMin(plug)¶
- hasPlugMax(plug)¶
- hasPlugSoftMin(plug)¶
- hasPlugSoftMax(plug)¶
- getPlugMin(plug)¶
- getPlugMax(plug)¶
- getSoftMin(plug)¶
- setSoftMin(plug, value)¶
- setAttrSoftMin(attribute, value)¶
- getSoftMax(plug)¶
- setSoftMax(plug, value)¶
- setAttrSoftMax(attribute, value)¶
- setAttrMin(attribute, value)¶
- setMin(plug, value)¶
- setAttrMax(attribute, value)¶
- setMax(plug, value)¶
- getPlugValue(plug, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the Plug value for the MDGContext
- Parameters
plug (
om2.MPlug
) – The Maya Plug instance to queryctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- getPlugAndType(plug, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Given an MPlug, get its value
- Parameters
plug (
om2.MPlug
) – MPlugctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
the dataType of the given plug. Will return standard python types where necessary eg. float else maya type
- Return type
tuple(int, plugValue)
- getNumericValue(plug, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the maya numeric type and value from the given plug
- Parameters
plug (om2.MPlug) – The plug to get the value from
ctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Return type
attrtypes.kType,
- getTypedValue(plug, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
Returns the maya type from the given typedAttributePlug
- Parameters
plug – MPLug
ctx (
om2.MDGContext
) – The MDGContext to use. ie. the current frame.
- Returns
maya type
- setPlugInfoFromDict(plug, **kwargs)¶
Sets the standard plug settings via a dict.
- Parameters
plug (om2.MPlug) – The Plug to change
kwargs (dict) – currently includes, default, min, max, softMin, softMin, value, Type, channelBox, keyable, locked.
data = { "Type": 5, # attrtypes.kType "channelBox": true, "default": 1.0, "isDynamic": true, "keyable": true, "locked": false, "max": 99999, "min": 0.0, "name": "scale", "softMax": None, "softMin": None, "value": 1.0, "children": [{}] # in the same format as the parent info } somePLug = om2.MPlug() setPlugInfoFromDict(somePlug, **data)
- setPlugValue(plug, value, mod=None, apply=True)¶
Sets the given plug’s value to the passed in value.
- Parameters
plug (
om2.MPlug
) – MPlug, The node plug.value – type, Any value of any data type.
mod (
om2.MDGModifier
) – Apply the modifier instantly or leave it to the caller.apply (bool) – If True then the value we be set on the Plug instance by calling doIt on the modifier.
- Returns
if mod is not none then the created one will be returned.
- Return type
om2.MDGModifier
- getPlugFn(obj)¶
Returns the MfunctionSet for the MObject
- Parameters
obj (MObject) – MObject that has the MFnAttribute functionset
- hasChildPlugByName(parentPlug, childName)¶
- iterChildren(plug)¶
- plugType(plug)¶
- getPythonTypeFromPlugValue(plug, ctx=MockExt.OpenMaya.MDGContext.kNormal)¶
- nextAvailableElementPlug(arrayPlug)¶
Returns the next available element plug from th plug array, if the plugArray is a compoundArray then the children of immediate children of the compound is searched.
How does it work? Loops through all current elements looking for a outgoing connection, if one doesn’t exist then this element plug is returned. if the element plug is a compound then if immediate children are searched and the element parent plug will be returned if there’s a connection.
- Parameters
arrayPlug (om2.MPlug) – the plugArray to search.
- nextAvailableDestElementPlug(arrayPlug)¶
Scene¶
- removeFromActiveSelection(node)¶
remove the node from the selection forcefully Otherwise maya can crash if someone deletes that node afterwards
- getSelectedNodes(filter=None)¶
Returns the selected nodes
- Returns
list(MObject)
- iterSelectedNodes(filter=None)¶
- keepSelection()¶
- getNodesCreatedBy(function, *args, **kwargs)¶
returns a 2-tuple containing all the nodes created by the passed function, and the return value of said function
- Parameters
function – func, the function to call and inspect
- Return type
tuple(MObject)
- iterDag(root, includeRoot=True, nodeType=None)¶
Generator function to walk the node hierarchy, if a nodeType is provided then the function will only return that mobject apitype.
- worldPositionToScreen(camera, point, width, height)¶
- isPointInView(camera, point, width, height)¶
- serializeNodes(graphNodes, skipAttributes=None, includeConnections=True)¶
- serializeSelectedNodes(skipAttributes, includeConnections)¶
- deserializeNodes(data)¶
- aimNodes(targetNode, driven, aimVector=None, upVector=None, worldUpVector=None)¶
- aimSelected(aimVector=None, upVector=None)¶
Aim the the selected nodes to the last selected node.
- Parameters
aimVector (om2.MVector) – see mayamath.aimToNode for details
upVector (om2.MVector) – see mayamath.aimToNode for details
- dgIterator(*args, **kwargs)¶
A more ideal python DGIterator for maya, this function just wraps the iterator in a try/finally statement so that we dont need to call iterator.next(). See maya.api.OpenMaya.MItDependencyGraph documentation for the arguments
- Return type
Generator(om2.MItDependencyGraph)
mesh = asMObject("pCube1") for dgIter in dgIterator(mesh, om2.MFn.kSkinClusterFilter, om2.MItDependencyGraph.kUpstream): dgIter.currentNode()
- iterReferences()¶
Generator function that returns a Mobject for each valid referene node.
- Returns
Generator function with each element representing the reference node
- Return type
Generator(om2.MObject)