API Reference: blendshape_node

advBlendshapeTools.api.blendshape_node provides the Python interface for inspecting and manipulating Maya blendShape nodes. The module is importable from inside Maya or from mayapy during pipeline scripts.

BlendShapeNode

class advBlendshapeTools.api.blendshape_node.BlendShapeNode(blend_shape: str)

TARGET_ITEM = 6000

__init__(blend_shape: str)

Initialize BlendShapeNode.

Parameters:

blend_shape – Name of an existing blendShape node.

__str__() → str

Return str(self).

classmethod list_blendshapes(in_namespace: str | None = None) → list[BlendShapeNode]

List all blendshapes in the scene, optionally filtered by namespace.

Parameters:

in_namespace – Namespace to filter by. If None, returns all blendshapes.

Returns:

BlendShapeNodes found in the scene.

Return type:

list[BlendShapeNode]

classmethod create(name: str | None = None, geometry: list[str] | None = None, **kwargs) → BlendShapeNode

Create a new blendshape node.

Parameters:

• name – Name for the new blendShape node.

• geometry – Meshes to pass to cmds.blendShape. Uses selection if None.

Returns:

The newly created node.

Return type:

BlendShapeNode

property targets: list[str]

Blendshape target names.

Type:

list[str]

property base_mesh: str

Name of the base geometry shape (deformed shape).

Type:

str

property transform: str

Name of the transform node above the base mesh.

Type:

str

property combination_connections: dict[str, dict]

Mapping of combination shape output targets to their configuration.

Returns:

Maps each output target name to a dict with

’inputs’ (list of driver target names) and ‘method’ (int).

Return type:

dict[str, dict]

get_target_index(target_name: str) → int

Returns the weight array index for a target name.

Parameters:

target_name – Name of the target.

Returns:

Target index, or -1 if not resolvable.

Return type:

int

Raises:

AttributeError – If target_name does not exist on this node.

target_exists(target_name: str) → bool

Check whether a target name exists on this node.

Parameters:

target_name – Name of the target.

Returns:

True if the target exists.

Return type:

bool

disconnect_targets(inputs_only: bool = False) → tuple[list[list[str]], list[list[str]]]

Disconnect all target weight attributes from their connections.

Parameters:

inputs_only – When True, only incoming connections are severed; outgoing connections (e.g. weights driving set-driven keys on joints) are kept so they still drive downstream rigs while weights are changed.

Returns:

(input_connections, output_connections) for later reconnection.

Return type:

tuple

reconnect_targets(input_connections: list[list[str]], output_connections: list[list[str]], other_blendshape_node: str | None = None) → list[str]

Reconnect blendshape target attributes from previously captured connection data.

Parameters:

• input_connections – List of [source_plug, attr] pairs.

• output_connections – List of [attr, destination_plug] pairs.

• other_blendshape_node – If provided, reconnects to this node instead of self.

Returns:

List of ‘node.targets’ that failed to reconnect.

Return type:

list[str]

remove_target(target_name: str) → None

Remove a target from the blendshape node.

Parameters:

target_name – Name of the target to remove.

rename_target(old_name: str, new_name: str) → None

Rename a blendshape target alias.

Parameters:

• old_name – Current alias name of the target.

• new_name – New alias name to assign.

reset_weights() → None

Reset all target weights to zero (skips targets with incoming connections).

extract_target(target_name: str) → str

Extract a target shape as a new mesh in the scene.

If a mesh named target_name already exists, returns it directly.

Parameters:

target_name – Name of the target to extract.

Returns:

Name of the extracted mesh.

Return type:

str

get_inbetween_info(target_name: str) → list[dict]

Get in-between weight and name info for a target.

Parameters:

target_name – Name of the parent target.

Returns:

Entries sorted by weight, each with ‘weight’, ‘name’, and ‘item_idx’ keys.

Return type:

list[dict]

get_target_components(target_name: str, indices: bool = False) → list | None

Get the vertex components that have non-zero deltas on a target’s main shape.

Parameters:

• target_name – Name of the target.

• indices – If True, return integer vertex indices instead of component strings.

Returns:

Component strings (‘vtx[N]’), integer indices,

or None if no components exist.

Return type:

list[str] | list[int] | None

get_target_weights(target_name: str, invert: bool = False) → list[float]

Get the per-vertex paint mask weights for a target.

Parameters:

• target_name – Name of the target.

• invert – If True, return 1.0 - weight for each vertex.

Returns:

Per-vertex weight values (one per vertex).

Return type:

list[float]

set_target_weights(target_name: str, weights: list[float]) → None

Set the per-vertex paint mask weights for a target.

Parameters:

• target_name – Name of the target.

• weights – Per-vertex weight values, one per vertex in order.

get_base_weights() → list[float]

Get the deformer-level per-vertex weight mask.

Returns:

Per-vertex weight values (one per vertex).

Returns all-1.0 if the attribute is not set or unavailable.

Return type:

list[float]

set_base_weights(weights: list[float]) → None

Set the deformer-level per-vertex weight mask.

Parameters:

weights – Per-vertex weight values, one per vertex in order.

smooth_weights(weights: list[float], iterations: int) → list[float]

Apply Laplacian smoothing to a weight array using vertex adjacency.

Parameters:

• weights – Per-vertex weight values, one per vertex.

• iterations – Number of smoothing passes.

Returns:

Smoothed weight values.

Return type:

list[float]

list_target_directories() → list[int]

Returns the indices of all target directories on this node.

Returns:

Directory indices (index 0 is the root placeholder).

Return type:

list[int]

get_directory_name(directory_index: int) → str

Get the name of a target directory.

Parameters:

directory_index – Index of the target directory.

Returns:

Directory name, or empty string if not set.

Return type:

str

set_directory_name(directory_index: int, name: str) → None

Set the name of a target directory.

Parameters:

• directory_index – Index of the target directory.

• name – Name to assign.

get_directory_children(directory_index: int) → list[int]

Get the child indices for a directory.

Positive values are target indices; negative values are sub-directory indices (multiply by -1 to get the actual directory index).

Parameters:

directory_index – Index of the target directory.

Returns:

Child indices.

Return type:

list[int]

set_directory_children(directory_index: int, child_indices: list[int]) → None

Set the child indices for a directory.

Parameters:

• directory_index – Index of the target directory.

• child_indices – List of child indices (positive=target, negative=sub-directory).

get_directory_parent(directory_index: int) → int

Get the parent directory index for a directory.

Parameters:

directory_index – Index of the target directory.

Returns:

Parent directory index, or 0 if at root level.

Return type:

int

set_directory_parent(directory_index: int, parent_index: int) → None

Set the parent directory index for a directory.

Parameters:

• directory_index – Index of the target directory.

• parent_index – Index of the parent directory.

get_target_parent_directory(target_index: int) → int

Get the parent directory for a target.

Parameters:

target_index – Weight array index of the target.

Returns:

Parent directory index, or 0 if at root level.

Return type:

int

set_target_parent_directory(target_index: int, directory_index: int) → None

Set the parent directory for a target.

Parameters:

• target_index – Weight array index of the target.

• directory_index – Directory index to assign as parent.

remove_empty_directories() → None

Remove all directories that contain no targets or sub-directories.

create_target_directory(name: str, child_indices: list[int] | None = None, parent_index: int = 0) → int

Create a new target directory.

Parameters:

• name – Display name for the directory.

• child_indices – Target indices (positive) or sub-directory indices (negative) to add.

• parent_index – Parent directory index. 0 = root.

Returns:

Index of the newly created directory.

Return type:

int

get_directory_parent_visibility() → dict[int, bool]

Return the inherited (parent) visibility of each non-root directory.

Returns:

Parent visibility keyed by directory index.

Return type:

dict[int, bool]

propagate_directory_visibility() → None

Recompute inherited directory/target visibility from the directory tree.

Module-level helpers

advBlendshapeTools.api.blendshape_node.connect_blendshape_targets(source_blendshape_node: BlendShapeNode, target_blendshape_nodes: list[BlendShapeNode]) → None

Connect matching target names from a source blendshape to one or more target blendshapes.

Parameters:

• source_blendshape_node – The blendshape to drive from.

• target_blendshape_nodes – Blendshapes to receive connections.

advBlendshapeTools.api.blendshape_node.disconnect_attributes(node: str, attribute_list: list[str], inputs_only: bool = False) → tuple[list[list[str]], list[list[str]]]

Disconnect a node’s input and output connections for the given attributes.

Useful for temporarily disconnecting connections to reconnect them later.

Parameters:

• node – Name of dag node.

• attribute_list – List of attribute names to disconnect.

• inputs_only – When True, only incoming connections are severed; outgoing connections are left intact. Use this when the attributes drive downstream rigs (e.g. set-driven keys on joints) that must keep responding while the attribute values are changed.

Returns:

(input_connections, output_connections) where each is a list of

[plug, attr] pairs capturing the severed connections. When inputs_only is True, output_connections is empty.

Return type:

tuple

advBlendshapeTools.api.blendshape_node.reconnect_attributes(node: str, input_connections: list[list[str]], output_connections: list[list[str]]) → list[str]

Reconnect node input and output connections.

Parameters:

• node – Name of dag node.

• input_connections – List of [source_plug, attr] pairs to connect as inputs.

• output_connections – List of [attr, destination_plug] pairs to connect as outputs.

Returns:

List of ‘node.attribute’ strings that failed to reconnect.

Return type:

list[str]

Exceptions

exception advBlendshapeTools.api.blendshape_node.BlendShapeNodeError