Plugin Commands¶

The Advanced Blendshape Tools plugin provides the following MEL/Python commands for importing, exporting and transferring blendshapes. In addition to blendshape utilities, there are blendshape weight and component operations.

Interpolation Methods¶

When importing or transferring blendshapes, you can choose from 3 different interpolation methods (-method / -mt flag).

Method	Description	Best For	Limitations
`index`	Direct 1-to-1 transfer by vertex index.	Identical meshes (same vertex count and order).	Strictly requires identical topology. No interpolation occurs.
`uv`	Interpolates deltas based on UV proximity. Finds the nearest K vertices in UV space.	Meshes with different topologies but matching UV layouts.	Requires good UVs (no overlaps). discontinuous at UV seams if not handled correctly.
`topology`	Uses surface distance and connectivity (K-nearest neighbors in 3D space).	Meshes with different topologies where UVs might be poor, but shapes are geometrically aligned.	Can result in “pushed” vertices if shapes are far apart.

advBlendshapeExport¶

Exports blendshape deltas from a source blendshape node to a file.

Flags

Long Name	Short Name	Type	Description
`-blendshape`	`-bs`	String	Required. The source blendshape node to export from.
`-outputFile`	`-o`	String	Required. The output file path.
`-deltaThreshold`	`-dt`	Double	Minimum delta magnitude to include. Vertices with movement smaller than this are ignored. Default: 0.0000.
`-constraintData`	`-cd`	String	JSON string of correspondence constraint groups (`advCorrespondence` format). When provided, overrides the `advCorrespondence` attribute stored on the blendShape node.

Example

import maya.cmds as cmds

# Export 'blendShape1' to file
cmds.advBlendshapeExport(blendshape='blendShape1', output='C:/temp/blendshape.deltas')

advBlendshapeImport¶

Imports blendshape deltas from a file onto a target mesh.

Flags

Long Name	Short Name	Type	Description
`-mesh`	`-m`	String	The target mesh to apply shapes to. Optional: derived from the blendshape’s base geometry when omitted.
`-blendshape`	`-bs`	String	Required. The blendshape node to import into. Node creation is handled by the caller (see `advBlendshapeTools.api.commands.find_or_create_blendshape`).
`-inputFile`	`-i`	String	Required. The input file path containing source deltas.
`-method`	`-mt`	String	Interpolation methods: `"uv"`, `"topology"`, or `"index"`. Default: `"uv"`.
`-maxDropoffDistance`	`-mdd`	Double	`topology` method only. Maximum distance a source vertex can influence a target vertex, with a smooth taper to zero at this distance. `0` = unlimited. Default: 0.0.
`-targetNames`	`-tn`	List (String)	List of specific target names to import. If specified, only these targets are imported.
`-applyConstraints`	`-ac`	Boolean	Apply stored correspondence constraint groups after interpolation. Only runs for `index` method. Default: `True`.
`-deltaThreshold`	`-dt`	Double	Minimum delta magnitude to include. Targets with no deltas above this threshold are pruned. Set to 0.0 to keep all targets. Default: 0.0000.

Examples

import maya.cmds as cmds
from advBlendshapeTools.api.commands import find_or_create_blendshape

# Import into an existing blendshape node
# Useful when you want to add targets to a pre-configured blendshape
cmds.advBlendshapeImport(
    blendshape='target_mesh_blendShape',
    inputFile='C:/temp/blendshape.deltas',
    method='uv'
)

# Import specific targets into an existing blendshape
cmds.advBlendshapeImport(
    blendshape='target_mesh_blendShape',
    inputFile='C:/temp/blendshape.deltas',
    method='index',
    targetNames=['target1', 'target2', 'target3']
)

advBlendshapeTransfer¶

Transfers blendshapes directly from a source blendshape node to one or more target meshes.

Flags

Long Name	Short Name	Type	Description
`-sourceBlendshape`	`-sbs`	String	Required. The source blendshape node.
`-sourceMesh`	`-sm`	String	Required. The source mesh that the source blendshape deforms.
`-targetMeshes`	`-tm`	String (Multi)	Required. One or more target meshes to transfer to.
`-targetBlendshapes`	`-tbs`	String (Multi)	Required. Existing blendshape nodes for each target mesh. Count must match `-targetMeshes`. Node creation is handled by the caller (see `advBlendshapeTools.api.commands.find_or_create_blendshape`).
`-method`	`-mt`	String	Interpolation method: `"uv"`, `"topology"`, or `"index"`. Default: `"uv"`.
`-maxDropoffDistance`	`-mdd`	Double	`topology` method only. Maximum distance a source vertex can influence a target vertex, with a smooth taper to zero at this distance. `0` = unlimited. Default: 0.0.
`-includeCombinations`	`-ic`	Boolean	If true, attempts to transfer combination shapes and connections. Default: True.
`-applyConstraints`	`-ac`	Boolean	Apply stored correspondence constraint groups after transfer. Only runs for `index` method. When `False`, constraint groups are also not written to the target blendshape node. Default: `True`.
`-deltaThreshold`	`-dt`	Double	Minimum delta magnitude to include. Targets with no deltas above this threshold are pruned. Set to 0.0 to keep all targets. Default: 0.0000.

Examples

import maya.cmds as cmds
from advBlendshapeTools.api.commands import find_or_create_blendshape

# Transfer shapes using UV interpolation (different topology but with similar UV layout)
new_bs = cmds.advBlendshapeTransfer(
    sourceBlendshape='source_blendshape',
    sourceMesh='source_mesh',
    targetMeshes=['target_mesh1'],
    targetBlendshapes=[find_or_create_blendshape('target_mesh1')],
    method='uv'
)

# Transfer to multiple meshes at once
target_meshes = ['target_mesh1', 'target_mesh2', 'target_mesh3']
# Find/Create blendshape nodes for each mesh mesh before transfer.
target_blendshapes = [find_or_create_blendshape(m) for m in target_meshes]
created_nodes = cmds.advBlendshapeTransfer(
    sourceBlendshape='source_blendshape',
    sourceMesh='source_mesh',
    targetMeshes=target_meshes,
    targetBlendshapes=target_blendshapes,
    method='uv'
)

advBlendshapeFile¶

Queries information from an exported blendshape file without importing it.

Note: When quering, the data is in it’s raw state from the time of export. Usage

cmds.advBlendshapeFile(filePath, query=True, [flags])  

Arguments

filePath (String): The positional argument specifying the path to the blendshape file (.deltas).

Flags

Long Name	Short Name	Type	Description
`-weightCount`	`-wc`	Boolean	Returns the number of blendshape targets in the file (int).
`-vertexCount`	`-vc`	Boolean	Returns the vertex count of the source mesh in the file (int).
`-targets`	`-t`	Boolean	Returns a list of all target names in the file (string array).
`-combinations`	`-c`	Boolean	Returns the combination shapes as a JSON string. This string can be parsed into a dictionary where keys are output targets and values are lists of input targets.
`-deltas`	`-d`	Boolean	Returns all target deltas as a JSON string. Format: `{"targetName": [[x, y, z], ...], ...}`. Each target contains an array of delta vectors in vertex order.

Example

import maya.cmds as cmds
import json

file_path = "C:/temp/blendshape.deltas"

# Query number of weights
weight_count = cmds.advBlendshapeFile(file_path, query=True, weightCount=True)
print(f"Target count: {weight_count}")

# Query combination shapes (JSON output)
json_str = cmds.advBlendshapeFile(file_path, query=True, combinations=True)
combinations = json.loads(json_str)
print(f"Combinations: {combinations}")

# Check vertex count for compatibility
file_vtx_count = cmds.advBlendshapeFile(file_path, query=True, vertexCount=True)
target_vtx_count = cmds.polyEvaluate("pSphere1", vertex=True)

if file_vtx_count == target_vtx_count:
    print("Vertex count matched. Can use 'index' method")
else:
    print("Vertex count mismatch. Use 'uv' or 'topology' method")

# Query delta data for all targets
deltas_json = cmds.advBlendshapeFile(file_path, query=True, deltas=True)
deltas = json.loads(deltas_json)

# Access deltas for a specific target
for target_name, delta_list in deltas.items():
    print(f"Target '{target_name}' has {len(delta_list)} deltas")
    for i, delta in enumerate(delta_list[:3]):  # Print first 3 deltas
        print(f"  [{i}]: {delta}")

Blendshape Weight Maps¶

These commands operate on base and per-target paintable weight maps stored in .bweights files.

`advBWeightExport`¶

Exports modified base and per-target weight maps from a blendshape node to a .bweights file.

Flags

Long Name	Short Name	Type	Description
`-blendshape`	`-bs`	String	Required. The blendshape node to export from.
`-outputFile`	`-o`	String	Required. Output `.bweights` file path.

Example

import maya.cmds as cmds

cmds.advBWeightExport(blendshape='blendShape1', outputFile='C:/temp/head.bweights')

`advBWeightImport`¶

Imports per-target weight maps from a .bweights file onto a mesh’s blendshape node. Supports remapping when topology differs from the source.

Flags

Long Name	Short Name	Type	Description
`-mesh`	`-m`	String	Required. Target mesh transform name.
`-inputFile`	`-if`	String	Required. Input `.bweights` file path.
`-method`	`-me`	String	Remapping method: `"index"`, `"uv"`, or `"topology"`. Default: `"index"`.
`-blendshape`	`-bs`	String	Specific blendshape node to target. If omitted, the blendShape node deforming the mesh is used. Required if more than one blendShape node deforms the mesh.

Notes

"index" requires identical vertex counts between source and target.
"uv" and "topology" remap weights spatially and work across different topologies.

Example

import maya.cmds as cmds

# Same topology, direct index mapping
cmds.advBWeightImport(mesh='headMesh', inputFile='C:/temp/head.bweights')

# Different topology, UV-based remapping
cmds.advBWeightImport(
    mesh='target_mesh1',
    inputFile='C:/temp/head.bweights',
    method='uv'
)

`advBWeightTransfer`¶

Transfers per-target weight maps directly from a source blendshape node to one or more target meshes, without writing an intermediate file.

Flags

Long Name	Short Name	Type	Description
`-sourceBlendshape`	`-sbs`	String	Required. The source blendshape node.
`-targetMeshes`	`-tm`	String (Multi)	Required. One or more target mesh transform names.
`-method`	`-mt`	String	Remapping method: `"index"`, `"uv"`, or `"topology"`. Default: `"topology"`.
`-targetBlendshapes`	`-tbs`	String (Multi)	Existing blendshape nodes for each target mesh. If omitted, the blendShape node deforming each target mesh is used (blendshapes that only drive weights through connections are ignored); a mesh is skipped if more than one blendShape node deforms it. Count must match `-targetMeshes` if specified.

Returns: list[str] blendshape node names that received the weights.

Example

import maya.cmds as cmds


# Transfer to multiple target meshes at once
cmds.advBWeightTransfer(
    sourceBlendshape='source_blendshape',
    targetMeshes=['target_mesh1', 'target_mesh2', 'target_mesh3'],
    method='uv'
)

`advBWeightsFile`¶

Queries metadata from a .bweights file without importing it.

Note: When quering, the data is in it’s raw state from the time of export.

Usage

cmds.advBWeightsFile(filePath, query=True, [flags])

Arguments

filePath (String): Path to the .bweights file.

Flags

Long Name	Short Name	Type	Description
`-targets`	`-t`	Boolean	Returns the list of target names stored in the file (string array).
`-vertexCount`	`-vc`	Boolean	Returns the vertex count of the source mesh (int).
`-baseWeights`	`-bw`	Boolean	Returns the global deformer weight map as a float array (one value per vertex). An empty array means all weights are 1.0 (unmodified).
`-targetWeights`	`-tw`	Boolean	Returns all per-target weight maps as a JSON string. Format: `{"targetName": [w0, w1, ...], ...}`. An empty array for a target means all weights are 1.0 (unmodified).

Note: The weight values returned reflect the state of the mesh at export time. When importing or transferring weights to a different topology, new weight values are computed by the remapping algorithm, the exported values are not used directly.

Example

import maya.cmds as cmds
import json

file_path = 'C:/temp/head.bweights'

targets = cmds.advBWeightsFile(file_path, query=True, targets=True)
print(f"Targets: {targets}")

vtx_count = cmds.advBWeightsFile(file_path, query=True, vertexCount=True)
print(f"Vertex count: {vtx_count}")

# Query the envelope deformer mask (empty = all 1.0)
base_weights = cmds.advBWeightsFile(file_path, query=True, baseWeights=True)
print(f"Base weights: {base_weights}")

# Query all per-target weight maps
target_weights = json.loads(cmds.advBWeightsFile(file_path, query=True, targetWeights=True))
for name, weights in target_weights.items():
    print(f"  {name}: {len(weights)} values")

Component Selections¶

These commands save and restore named vertex component selections using .components files. Selections are stored relative to mesh topology and can be remapped to different meshes on import or transfer.

`advComponentsExport`¶

Exports a named vertex component selection to a .components file.

Flags

Long Name	Short Name	Type	Description
`-mesh`	`-m`	String	Required. Mesh transform that owns the selection.
`-file`	`-f`	String	Required. Output `.components` file path.
`-setName`	`-sn`	String	Required. Name to assign to this component set in the file.

Example

import maya.cmds as cmds

cmds.advComponentsExport(mesh='target_mesh1', file='C:/temp/target_mesh1.components', setName='my_set')

`advComponentsImport`¶

Imports a named vertex component selection from a .components file onto a target mesh, optionally remapping across different topologies.

Flags

Long Name	Short Name	Type	Description
`-mesh`	`-m`	String	Required. Target mesh transform.
`-file`	`-f`	String	Required. Input `.components` file path.
`-setName`	`-sn`	String	Required. Name of the component set to import from the file.
`-method`	`-mt`	String	Remapping method: `"index"`, `"uv"`, or `"topology"`. Default: `"topology"`.

Returns: String[] vertex component strings selected on the target mesh.

Example

import maya.cmds as cmds

# Different topology, remap by UV proximity
result = cmds.advComponentsImport(
    mesh='target_mesh1',
    file='C:/temp/target_mesh1.components',
    setName='my_set',
    method='uv'
)

`advComponentFile`¶

Queries metadata from a .components file without importing it.

Note: When quering, the data is in it’s raw state from the time of export.

Usage

cmds.advComponentFile(filePath, query=True, [flags])

Arguments

filePath (String): Path to the .components file.

Flags

Long Name	Short Name	Type	Description
`-names`	`-n`	Boolean	Returns the list of component set names stored in the file (string array).
`-vertexCount`	`-vc`	Boolean	Returns the vertex count of the source mesh (int).
`-components`	`-c`	String	Returns the raw component indices for the named set (int array). Pass the set name as the flag value. Does not use query mode.
`-type`	`-ty`	String	Returns the component type for the named set: `"vertex"`, `"edge"`, or `"face"`. Pass the set name as the flag value. Does not use query mode.

Example

import maya.cmds as cmds

file_path = 'C:/temp/target_mesh1.components'

names = cmds.advComponentFile(file_path, query=True, names=True)
print(f"Sets: {names}")

vtx_count = cmds.advComponentFile(file_path, query=True, vertexCount=True)
print(f"Vertex count: {vtx_count}")

# Query indices and type for a named set
comp_type = cmds.advComponentFile(file_path, type='my_set')
indices = cmds.advComponentFile(file_path, components='my_set')

# Build component strings from raw indices
type_token = {'vertex': 'vtx', 'edge': 'e', 'face': 'f'}[comp_type]
components = [f"headMesh.{type_token}[{i}]" for i in indices]
cmds.select(components)

Plugin Commands¶

Interpolation Methods¶

advBlendshapeExport¶

advBlendshapeImport¶

advBlendshapeTransfer¶

advBlendshapeFile¶

Blendshape Weight Maps¶

advBWeightExport¶

advBWeightImport¶

advBWeightTransfer¶

advBWeightsFile¶

Component Selections¶

advComponentsExport¶

advComponentsImport¶

advComponentFile¶

`advBWeightExport`¶

`advBWeightImport`¶

`advBWeightTransfer`¶

`advBWeightsFile`¶

`advComponentsExport`¶

`advComponentsImport`¶

`advComponentFile`¶