Nodes

class ConnectMatrixMethod(value)

Bases: IntEnum

Options for connecting a matrix to a nodes offsetParentMatrix attribute

are_nodes_aligned(node_a, node_b)

Return True if two nodes are roughly aligned, meaning their axes point mostly in the same directions.

connect_matrix(matrix: pymel.core.Attribute, node: pymel.core.nt.Transform, method: ConnectMatrixMethod = ConnectMatrixMethod.KEEP_WORLD, keep_joint_hierarchy=True)

Connect a world matrix to a node, optionally preserving or changing transform attributes to adjust accordingly (see ConnectMatrixMethod).

Uses either the offsetParentMatrix, or decomposes and connects via transform attributes.

When using offsetParentMatrix, inheritsTransform will be disabled to keep the connection simple.

Parameters:

• matrix – A matrix attribute

• node – A transform node

• method – The method to use for adjusting the node’s transform after connecting

• keep_joint_hierarchy – When true, joints are handled specially, and instead of connecting to the offsetParentMatrix and disabling inheritsTransform, a joint matrix constrain is used. This is necessary if joint animation baking and export will be used.

convert_scale_constraint_to_world_space(scale_constraint)

Modify a scale constraint to make it operate better with misaligned axes between the leader and follower by plugging the worldMatrix of the leader node into the scale constraint.

Parameters:

scale_constraint – A ScaleConstraint node

create_offset_transform(node, name='{0}_offset')

Create a transform that is inserted as the new parent of a node, at the same world location as the node. This effectively transfers the local matrix of a node into the new transform, zeroing out the attributes of the node (usually for animation). This includes absorbing the rotate-axis of the node.

Parameters:

• node (PyNode) – A node to create an offset for

• name (str) – The name to use for the new transform. Accepts a single format argument which will be the name of node

decompose_and_connect_matrix(matrix: pymel.core.Attribute, node: pymel.core.nt.Transform, inherits_transform: bool = False)

Decompose a matrix and connect it to the translate, rotate, scale, and shear of a transform node.

Parameters:

• matrix – A world space matrix attribute

• node – A transform node

• inherits_transform – If true, add a multMatrix node to compute the local matrix before decomposing, If false, disable inheritsTransform on the node and connect the world space matrix directly.

Returns:

The decomposeMatrix node

disable_color_override(node)

Disable drawing overrides for a node and all its shapes.

Parameters:

node (PyNode) – A transform node

disconnect_offset_matrix(follower, preserve_position=True, preserve_transform_values=True, keep_inherit_transform=False)

Disconnect any inputs to the offsetParentMatrix of a node, and re-enable inheritsTransform.

Parameters:

• follower (PyNode) – A node with input connections to offsetParentMatrix

• preserve_position (bool) – If true, preserve the followers world space position

• preserve_transform_values (bool) – If true, preserve_position will not affect the current translate, rotate, and scale values of the follower by absorbing any offset into the follower’s offsetParentMatrix.

• keep_inherit_transform (bool) – If true, inheritsTransform will not be changed

duplicate_branch(root, end, parent=None, name_fmt='{0}')

Duplicate a node branch from root to end (inclusive).

Parameters:

• root (PyNode) – The root node of the branch.

• end (PyNode) – The end node of the branch.

• parent (PyNode) – The parent node of the new node branch.

• name_fmt (str) – The naming format to use for the new nodes. Will be formatted with the name of the original nodes.

freeze_offset_matrix(transform)

Freeze the translate, rotate, and scale of a transform by moving its current local matrix values into its offsetParentMatrix. This operation is idempotent.

freeze_pivot(transform)

Freeze the given transform such that its local pivot becomes zero, but its world space pivot remains unchanged.

Parameters:

transform – A Transform node

freeze_pivots_for_hierarchy(transform)

Freeze pivots on a transform and all its descendants.

Parameters:

transform – A Transform node

freeze_scales_for_hierarchy(node: pymel.core.nt.DagNode)

Freeze scales on a transform and all its descendants without affecting pivots. Does this by parenting all children to the world, freezing, then restoring the hierarchy.

Parameters:

node (pm.PyNode) – A Transform node

full_constraint(leader, follower)

Fully constrain a follower node to a leader node. Does this by creating a parent and scale constraint.

Parameters:

• leader (PyNode or str) – The leader node of the constraint

• follower (PyNode or str) – The follower node of the constraint

Returns:

A parentConstraint and a scaleConstraint node

get_all_parents(node, include_node=False)

Return all parents of a node

Parameters:

• node – A node to find parents for.

• include_node – A bool, whether to include the given node in the result.

Returns:

A list of nodes

get_assemblies(nodes)

Return any top-level nodes (assemblies) that contain a list of nodes

Parameters:

nodes – A list of node long-names. Does not support short names or PyNodes.

get_attr_dimension(attr)

Return the dimension of an Attribute

Parameters:

attr (Attribute) – The attribute to check

get_attr_or_value_dimension(attr_or_value)

Return the dimension of an attribute or attribute value (such as a list or tuple)

Parameters:

attr_or_value – An Attribute or value that can be set on an attribute

get_axis(value)

Returns a pm.dt.Vector.Axis for the given value

Parameters:

value – Any value representing an axis, accepts 0, 1, 2, 3, x, y, z, w as well as pm.dt.Vector.Axis objects

get_axis_vector(axis, sign=1)

Return a vector for a signed axis

get_closest_aligned_axes(matrix)

Given a matrix, find and return signed axes closest to the x, y, and z world axes.

Parameters:

matrix – A transformation matrix

Returns ((axisX, signX), (axisY, signY), (axisZ, signZ))

get_closest_aligned_axis(matrix, axis=0)

Given a matrix, find and return the signed axis that is most aligned with a specific axis.

Parameters:

• matrix – A transformation matrix

• axis – The axis to check against

Returns (axis, sign)

get_closest_aligned_relative_axis(node_a, node_b, axis=0)

Return the signed axis of node A that is most aligned with an axis of node B.

Returns (axis, sign)

get_compound_attr_index(child_attr)

Return the index of the given compound child attribute.

Parameters:

child_attr (Attribute) – An attribute that is the child of a compound attr.

get_descendants_top_to_bottom(node, **kwargs)

Return a list of all the descendants of a node, in hierarchical order, from top to bottom.

Parameters:

• node (PyNode) – A dag node with children

• **kwargs – Kwargs given to the listRelatives command

get_euler_rotation_from_matrix(matrix)

Return the euler rotation in degrees of a matrix

get_expanded_attr_names(attrs)

Given a list of compound attribute names, return a list of all leaf attributes that they represent. Only supports the more common transform attributes.

e.g. [‘t’, ‘rx’, ‘ry’] -> [‘tx’, ‘ty’, ‘tz’, ‘rx’, ‘ry’]

Parameters:

attrs (list of str) – The attributes to expand

get_node_branch(root, end)

Return all nodes in a transform hierarchy branch starting from root and descending to end.

Returns None if the end node is not child of root.

Parameters:

• root (PyNode) – The top node of a branch

• end (PyNode) – The end node of a branch, must be a child of root

get_other_axes(value, include_w=False)

Return a list of all other axes other than the given axis.

Parameters:

• value – Any value representing an axis, accepts 0, 1, 2, 3, x, y, z, w as well as pm.dt.Vector.Axis objects.

• include_w – If True, include the W axis.

get_override_color(node) → LinearColor | None

Return the override color of a node.

Parameters:

node (PyNode) – A transform node

Returns:

The color (RGB tuple), or None if color is not overridden.

get_parent_nodes(nodes)

Returns the top-most parent nodes of all nodes in a list.

Parameters:

nodes – A list of nodes

get_relative_matrix(node, base_node)

Return the matrix of a node relative to a base node.

Parameters:

• node (PyNode) – The node to retrieve the matrix from

• base_node (PyNode) – The node to which the matrix will be relative

get_rotation_matrix(matrix)

Return a matrix representing only the rotation of a TransformationMatrix

get_scale_matrix(matrix)

Return a matrix representing only the scale of a TransformationMatrix

get_transform_hierarchy(transform, include_parent=True)

Return a list of (parent, [children]) tuples for a transform and all of its descendants.

Parameters:

• transform – A Transform node.

• include_parent – A bool, when True, the relationship between the transform and its parent is included.

get_translation_midpoint(a, b)

Return a vector representing the middle point between the world translation of two nodes.

Parameters:

• a – A transform node

• b – A transform node

match_world_matrix(leader: pymel.core.nt.Transform, *followers: pymel.core.nt.Transform)

Set the world matrix of one or more nodes to match a leader’s world matrix.

Parameters:

• leader – A transform

• followers – One or more transforms to update

normalize_euler_rotations(node)

Modify the rotation of a transform node such that its euler rotations are in the range of 0..360

parent_in_order(nodes)

Parent the given nodes to each other in order. Leaders then followers, eg. [A, B, C] -> A|B|C

Parameters:

nodes – A list of nodes to parent to each other in order

safe_get_attr(node, attr_name)

Return an attribute from a node by name. Returns None if the attribute does not exist.

Parameters:

• node (PyNode) – The node with the attribute.

• attr_name (str) – The attribute name.

set_constraint_locked(constraint, locked)

Lock all important attributes on a constraint node

Parameters:

• constraint – A ParentConstraint or ScaleConstraint node

• locked – A bool, whether to make the constraint locked or unlocked

set_override_color(node, color: LinearColor, skip_enable_overrides=False)

Set the override color of a node

Parameters:

• node (PyNode) – A transform node

• color (tuple of float) – An RGB color, 0..1

• skip_enable_overrides (bool) – If True, skip enabling the overrides, just set the color. Faster if overrides are already enabled.

set_parent(children, parent)

Parent one or more nodes to a new parent node. Resolves situations where a node is currently a parent of its new parent.

Parameters:

• children – A list of nodes to reparent

• parent – A node to use as the new parent

set_relative_matrix(node, matrix, base_node)

Set the world matrix of a node, given a matrix that is relative to a different base node.

Parameters:

• node (PyNode) – The node to modify

• matrix (Matrix) – A matrix relative to the base node.

• base_node (PyNode) – The node that the matrix is relative to.

set_transform_hierarchy(hierarchy)

Re-parent one or more transform nodes.

Parameters:

hierarchy – A list of (parent, [children]) tuples

set_world_matrix(node, matrix, translate=True, rotate=True, scale=True)

Set the world matrix of a node.

unfreeze_offset_matrix(transform)

Unfreeze the translate, rotate, and scale of a transform by moving its current offset parent matrix values into its translate, rotate, and scale. This operation is idempotent.