Rig¶

Skeletonutils¶

poleVectorPosition(start, mid, end, distance=-1.0)¶

This function gets the position of the pole vector from 3 MVectors

Parameters:

start (MVector) – the start vector
mid (MVector) – the mid vector
end (MVector) – the end vector
distance – The pole vector distance from the mid-position along the normal, if -1 then the distance from the start and mid will be used.

Type:

distance: float

Returns:

the vector position of the pole vector

Return type:

MVector

Raises:

AssertionError – Raises when the poleMultiplier is 0

convertToNode(node, parent, prefix, nodeType='joint')¶

Converts a node into a joint but does not delete the node , transfers matrix over as well

Parameters:

node – mobject, the node that will be converted
parent – mobject to the transform to parent to
prefix – str, the str value to give to the start of the node name
nodeType – str, the node type to convert to. must be a dag type node

Returns:

mObject, the mobject of the joint

convertToSkeleton(rootNode, prefix='skel_', parentObj=None)¶

Converts a hierarchy of nodes into joints that have the same transform, with their name prefixed with the “prefix” arg.

Parameters:

rootNode (om2.MObject) – anything under this node gets converted.
prefix (str) – The name to add to the node name .
parentObj (om2.MObject) – The node to parent to skeleton to.

Returns:

MObject

jointLength(joint)¶

Retrieves the length of the child by subtracting the position of the parent joint

Parameters:: joint (om2.MObject) – The joint to query.
Returns:: The length of the joint
Return type:: float

chainLength(start, end)¶

Returns the Total length between the specified start and end joints.

Parameters:

start (om2.MObject) – The start joint which must be the parent of the specified end.
end (om2.MObject) – The end joint which must be a child of the specified start.

Returns:

The total length

Return type:

float

jointRoot(node, depthLimit=256)¶

Walks the parent hierarchy starting from the provided node and returns the root joint.

Parameters:

node (om2.MObject or None) – The joint to find root from.
depthLimit (int) – The depth limit to travel before exiting if the root isn’t found first. Defaults to 256.

Returns:

The root joint.

Return type:

om2.MObject

Align¶

createPolyPlaneFromPlane(name, plane, position=None, template=True, **kwargs)¶

Creates a PolyPlane based on the provided MPlane and position.

name="testPlane"
plane = om2.MPlane()
plane.setPlane(om2.MVector(0,1,0), 10)
mesh = createPolyPlaneFromPlane(name, plane)

Parameters:

name (str) – The name for the polyPlane
plane (om2.MPlane) – The MPlane instance
position (zapi.Vector) – if None then the position we be the center point of the MPlane.
template (bool) – Sets the state of the template draw mode of the plane

Returns:

The Transform of the created polyPlane

Return type:

zapi.DagNode

constructPlaneFromPositions(positionVectors, nodes, rotateAxis=MockExt.OpenMaya.MVector)¶

Constructs a MPlane instance based on the averaged normal of the nodes rotations.

Parameters:

positionVectors (list[om2.MVector, om2.MVector, om2.MVector]) – either a list of 3 vectors for a 3 point normal or 2 vectors
nodes (list[DagNode]) – a list of nodes which will have their rotations read to attempt to figure out the best normal direction e.g. uses the rotation to flip the normal.

Returns:

The construct plane based on the provided points

Return type:

om2.MPlane

alignNodesIterator(nodes, plane, skipEnd=True)¶

Generator function that loops each node protects it’s position in the world and returns each node, and it’s target.

This functions will handle setting translations while compensating for hierarchy state. The order of returned nodes will be in reverse(from child -> parent) of the provide list.

nodes = list(zapi.selected()) # in this example we're expecting to use 3 nodes only
currentPositions = [i.translation(space=zapi.kWorldSpace) for i in nodes]
plane = constructPlaneFromNodes(currentPositions)
for node, target in alignNodesIterator(nodes, plane):
    # do something ie. custom alignment

Parameters:

nodes (list[zapi.DagNode]) – The list of nodes to align
plane (om2.MPlane) – The MPlane where each node will be protected on too.

Returns:

first element is the node to set alignment, second element is the target node

Return type:

generator[zapi.DagNode, zapi.DagNode]

orientNodesIterator(nodes)¶

Generator function that loops each node, and it’s target.

Returns:: first element is the node to set alignment, second element is the target node
Return type:: generator[zapi.DagNode, zapi.DagNode]

alignHierarchy(start, end, plane, primaryAxis, secondaryAxis)¶

Aligns and positions every node between start and end so they sit on the plane.

Parameters:

start (zapi.DagNode) – The start node .
end (zapi.DagNode) – The end node.
plane (om2.MPlane) – The calculated Plane to align all nodes too.
primaryAxis (om2.MVector) – The primary(aim) axis for each node.
secondaryAxis (om2.MVector) – The Secondary vector for all the nodes in the chain.

projectAndOrientNodes(nodes, plane, primaryAxis, secondaryAxis, skipEnd=True)¶

Given the provided nodes each node will be protected on to the plane and have its rotations aligned.

For the sake of flexibly in how to apply the rotations depending on client workflow and node types, all rotations will be applied directly to the world rotations , for joints their joint orient will be reset to zero.

Parameters:

nodes (list[zapi.DagNode]) – The full list of nodes from parent to child.
plane (om2.MPlane) – The calculated Plane to align all nodes too.
primaryAxis (om2.MVector) – The primary(aim) axis for each node.
secondaryAxis (om2.MVector) – The Secondary vector for all the nodes in the chain.
skipEnd (bool) – If True the last node will not be aligned.

orientNodes(nodes, primaryAxis, secondaryAxis, worldUpAxis, skipEnd=True)¶

Given the provided nodes each node will be aligned to the next in the list

For the sake of flexibly in how to apply the rotations depending on client workflow and node types, all rotations will be applied directly to the world rotations , for joints their joint orient will be reset to zero.

Parameters:

nodes (list[zapi.DagNode]) – The full list of nodes from parent to child.
worldUpAxis (om2.MVector) – The calculated Plane to align all nodes too.
primaryAxis (om2.MVector) – The primary(aim) axis for each node.
secondaryAxis (om2.MVector) – The Secondary vector for all the nodes in the chain.
skipEnd (bool) – If True the last node will not be aligned.

worldAxisToRotation(axis, invert=False, rotateOrder=0)¶

Given an axis, return the world rotation to align to that axis.

Parameters:

axis (int) – Axis index to align to e.g. mayamath.XAXIS
invert (bool) – Whether to invert the rotation.
rotateOrder (int) – The rotation order to use. e.g. zapi.kRotateOrder_XYZ

Returns:

The world rotation to align to the axis.

Return type:

zapi.EulerRotation

planeNormalToRotation(sourcePosition, plane)¶

Given a source position and a plane, return the world rotation to align to that plane.

Parameters:

sourcePosition (zapi.Vector) – The source position to align to the plane.
plane (zapi.Plane) – The plane to align to.

Returns:

The worldRotation which aligns to the plane.

Return type:

zapi.EulerRotation

matrixToPlane(matrix)¶

Given a world matrix this extracts the Y rotation and returns a MPlane.

Parameters:: matrix (zapi.Vector) – The world matrix to extract the rotation from.
Returns:: The plane from the matrix.
Return type:: zapi.Plane