Util Nodes

class AlignMatrixPrimaryMode(value)

Bases: IntEnum

An enumeration.

class AlignMatrixSecondaryMode(value)

Bases: IntEnum

An enumeration.

class ConditionOperation(value)

Bases: IntEnum

An enumeration.

class FloatMathOperation(value)

Bases: IntEnum

An enumeration.

class MultiplyDivideOperation(value)

Bases: IntEnum

An enumeration.

class PlusMinusAverageOperation(value)

Bases: IntEnum

An enumeration.

class VectorProductOperation(value)

Bases: IntEnum

An enumeration.

add(*inputs)

Return an attribute that represents the given inputs added together.

align_matrix_to_direction(matrix, keep_axis, align_axis, align_direction, align_matrix) → pymel.core.Attribute

Align a matrix by pointing a secondary axis in a direction, while preserving a primary axis.

Parameters:

  • matrix – A transformation matrix value or attribute

  • keep_axis – A vector value or attribute representing the primary aim axis to keep locked

  • align_axis – A vector value or attribute representing the secondary align axis to try to adjust

  • align_direction – The direction vector value or attribute that the secondary axis should align to

  • align_matrix – A matrix applied to the direction vector

align_matrix_to_point(matrix, keep_axis, align_axis, align_target_point, align_matrix)

Align a matrix by pointing a secondary axis at a location, while preserving a primary axis.

Parameters:

  • matrix – A transformation matrix value or attribute

  • keep_axis – A vector value or attribute representing the primary aim axis to keep locked

  • align_axis – A vector value or attribute representing the secondary align axis to try to adjust

  • align_target_point – The point value or attribute that the secondary axis should aim at

  • align_matrix – A matrix applied to the align_target_point

Returns:

average(*inputs)

Return an attribute that represents the average of the given inputs.

blend2(a, b, blender)

Given two inputs of 1D, 2D, or 3D using a blender value, create a blend node and return the output attribute. If 1D, returns the outputX, if 2D or 3D, returns the output.

blend_matrix(input_matrix, target_matrix, weight)
Parameters:

  • input_matrix – A matrix value or attribute

  • target_matrix – A matrix value or attribute

  • weight – A weight value or attribute (0..1)

blend_matrix_multi(input_matrix, *targets_and_weights)

Blend a matrix towards one or more target matrices using a blendMatrix node. The order matters, since blends are calculated in a stack, i.e. the results of the previous blend get blended with next target and so on.

Parameters:

  • input_matrix – A transformation matrix value or attribute

  • *targets_and_weights – A list of tuples containing (target matrix, weight) values or attributes

choice(selector, *inputs) → pymel.core.Attribute

Create a choice node that selects an input based on a selector.

Parameters:

  • selector – The selector value or attribute.

  • *inputs – The array of input values or attributes to select based on the selector.

clamp(input, min, max)

Return an attribute that represents the given input clamped in the range [min, max]. All inputs can be either attributes or values.

compose_matrix(translate=None, rotate=None, scale=None) → pymel.core.Attribute

Compose a matrix using separate translate, rotate, and scale values using a composeMatrix utility node

Parameters:

  • translate – A translation vector or attribute

  • rotate – A euler rotation vector or attribute

  • scale – A scale vector or attribute

condition(first_term, second_term, true_val, false_val, operation)

Create a condition that returns either true_val or false_val based on the comparison of first_term and second_term.

Parameters:

  • first_term – The first term to compare against.

  • second_term – The second term to compare against.

  • true_val – The value or attribute to use if the condition is true.

  • false_val – The value or attribute to use if the condition is false.

  • operation (ConditionOperation) – The condition node operation to use

create_utility_node(node_type, **kwargs)

Create and return a utility node. Sets or connects any attributes defined by kwargs.

cross(a, b) → pymel.core.Attribute

Calculate the cross product of two vectors using a vectorProduct node

Parameters:

  • a – A vector value or attribute

  • b – A vector value or attribute

decompose_matrix(matrix)

Create a decomposeMatrix utility node.

Returns:

The decomposeMatrix node (not output attributes).

distance(a, b, ws=True, make_local=True)

Return an attribute on a distance node that represents the distance between nodes A and B.

Parameters:

  • a – Node A

  • b – Node B

  • ws – Use world space matrices

  • make_local – If True, makes both matrix inputs to the distance utils be matrices local to node A.

divide(a, b)

Return an attribute that represents a / b.

dot(a, b) → pymel.core.Attribute

Calculate the dot product of two vectors using a vectorProduct node

Parameters:

  • a – A vector value or attribute

  • b – A vector value or attribute

equal(a, b, true_val, false_val)

Return an attribute that represents true_val if a == b else false_val. Inputs can be either attributes or values.

get_constraint_weight_attr(leader, constraint)

Return the weight attribute from a constraint that corresponds to a specific leader node.

Parameters:

  • leader (PyNode) – A node that is one of the leaders of a constraint.

  • constraint (PyNode) – A constraint node.

get_input_connections(input_val, dest_attr)

Return a list of (src, dst) tuples representing connections to be made between an input and destination attribute. Input can be a simple value or an Attribute, and the results are intended for use with set_or_connect_attr.

More than one connection tuple may be returned in situations where the input and destination dimensions don’t match. e.g. ([1, 2], input) -> (1, inputX), (2, inputY)

Parameters:

  • input_val – An Attribute or value to set or connect to the destination attribute.

  • dest_attr (Attribute) – The attribute that will receive the input value.

get_largest_dimension_attr(attrs)

Return the attr that has the largest dimension.

Parameters:

attrs – A list of Attributes

get_output_attr(input)

Return the output attr of a utility node.

Most of the time this is a standard output based on the node type, but some nodes have more than one output attr, and one is selected based on the input.

Matches the dimension of the input (if its an attribute), e.g. if inputX is given, outputX will be returned.

Examples

multiplyDivide.input1 -> multiplyDivide.output1 multiplyDivide.input1X -> multiplyDivide.output1X setRange.min -> setRange.outValue condition.colorIfTrueR -> condition.outColorR plusMinusAverage.input2D[0].input2Dx -> plusMinusAverage.output2Dx

Parameters:

input – A PyNode or Attribute for which to return an output.

Returns:

An Attribute that matches the input, or None if the input is unhandled

get_plus_minus_average_output_attr(input)

Return the output attr of a plusMinusAverage node. Returns the output that matches the dimension of the input (if it’s an attribute), otherwise returns the 1D output.

Parameters:

input – A PyNode or Attribute for which to return an output

Returns:

An Attribute of the node, which could be one of output1D, output2D, output3D or any children. Returns output1D if the given input is the node and not an attribute.

greater_or_equal(a, b, true_val, false_val)

Return an attribute that represents true_val if a >= b else false_val. Inputs can be either attributes or values.

greater_than(a, b, true_val, false_val)

Return an attribute that represents true_val if a > b else false_val. Inputs can be either attributes or values.

inverse_matrix(matrix) → pymel.core.Attribute

Invert a matrix using a inverseMatrix node

Parameters:

matrix – A matrix value or attribute

less_or_equal(a, b, true_val, false_val)

Return an attribute that represents true_val if a <= b else false_val. Inputs can be either attributes or values.

less_than(a, b, true_val, false_val)

Return an attribute that represents true_val if a < b else false_val. Inputs can be either attributes or values.

matrix_multiply_point(matrix, point) → pymel.core.Attribute

Multiply a point vector by a matrix using a vectorProduct node

Parameters:

  • matrix – A transformation matrix value or attribute

  • point – A vector value or attribute representing a location

matrix_multiply_vector(matrix, vector) → pymel.core.Attribute

Multiply a direction vector by a matrix using a vectorProduct node

Parameters:

  • matrix – A transformation matrix value or attribute

  • vector – A vector value or attribute representing a direction

max_float(a, b)

Return an attribute that represents max(a, b). Only supports float values.

min_float(a, b)

Return an attribute that represents min(a, b). Only supports float values.

multiply(a, b)

Return an attribute that represents a * b.

not_equal(a, b, true_val, false_val)

Return an attribute that represents true_val if a != b else false_val. Inputs can be either attributes or values.

pow(a, b)

Return an attribute that represents a ^ b.

set_or_connect_attr(attr, val)

Set or connect the given value into the given attribute. Handles finding the correct inputs on the target utility node automatically, as well as plugging n-dimension inputs into m-dimension attributes.

Parameters:

  • attr – A Attribute to set or connect

  • val – A PyNode, Attribute or value

Returns:

A list of Attributes that were set or connected

set_range(value, min, max, old_min, old_max)

Return an attribute that represents the given input mapped from the range [old_min, old_max] to the range [min, max]. All inputs can be either attributes or values.

sqrt(a)

Return an attribute that represents the square root of a.

subtract(*inputs)

Return an attribute that represents the given inputs subtracted in sequential order. Eg. input[0] - input[1] - … - input[n] All inputs can be either attributes or values.