API Reference: commands

advBlendshapeTools.api.commands provides Python functions for exporting, importing, and transferring blendshape data. These functions wrap the underlying MEL/Python commands and are the recommended entry point for pipeline scripts.

Export and Import

advBlendshapeTools.api.commands.export_deltas(blendshape: str, output_file: str, threshold: float = 0.0, correspondence_data: str = '') → None

Export blendshape deltas

Parameters:

  • blendshape – Name of the blendShape node.

  • output_file – Output .deltas file path.

  • threshold – Minimum delta magnitude to include.

  • correspondence_data – JSON string of correspondence groups When non-empty, passed as-constraintData to the C++ command, overriding any advCorrespondence attribute on the node. When empty (default), the C++ command reads from the node attribute.

advBlendshapeTools.api.commands.import_deltas(mesh: str, input_file: str, method: str, threshold: float = 0.0, max_dropoff_distance: float = 0.0, target_names: list[str] | None = None, apply_constraints: bool = True) → str

Import blendshape deltas from a binary file.

Parameters:

  • mesh – Target mesh transform name. An existing blendShape node on the mesh is reused; otherwise one is created as ‘{meshShortName}_blendShape’ (DAG path prefix and namespace stripped).

  • input_file – Input .deltas file path.

  • method – Interpolation method (lowercase).

  • threshold – ignore deltas smaller than this value.

  • max_dropoff_distance – Topology method only. Maximum distance a source vertex can influence a target vertex; 0 = unlimited.

  • target_names – Optional list of specific targets to import.

  • apply_constraints – When False, passes -applyConstraints False to skip the constraint solver even if constraint data is present in the file.

Returns:

blendshape node name.

Return type:

str

advBlendshapeTools.api.commands.transfer_deltas(source_blendshape: str, source_mesh: str, target_meshes: list[str], method: str, threshold: float = 0.0, max_dropoff_distance: float = 0.0, include_combinations: bool = False, target_names: list[str] | None = None, apply_constraints: bool = True, connect_targets: bool = True, copy_input_connections: bool = False) → list

Transfer blendshape deltas to target meshes.

Parameters:

  • source_blendshape – Source blendShape node name.

  • source_mesh – Source mesh transform name.

  • target_meshes – list of target mesh transforms. Existing blendShape nodes on the meshes are reused; otherwise one is created per mesh as ‘{meshShortName}_blendShape’ (DAG path prefix and namespace stripped).

  • method – Interpolation method (lowercase).

  • threshold – Ignore deltas smaller than this value.

  • max_dropoff_distance – Topology method only. Maximum distance a source vertex can influence a target vertex; 0 = unlimited.

  • include_combinations – Whether to include combination shapes.

  • target_names – Optional subset of target names to transfer. Transfers all if None or empty.

  • apply_constraints – When False, passes -applyConstraints False to skip the constraint solver even if constraint data is present on the node.

  • connect_targets – Custom method only. When False, skip connecting the created blendshape’s targets back to the source blendshape’s weights.

  • copy_input_connections – Custom method only. When True, instead of chaining the created blendshape’s targets to the source blendshape’s weights, copy the source targets’ upstream input connections (animation curves, rig attributes) directly onto the matching created targets. Mutually exclusive with connect_targets.

Returns:

list of created blendshape node names.

Live Wrap Deformer

advBlendshapeTools.api.commands.create_wrap(source_mesh: str, target_mesh: str, method: str, source_uv_set: str = '', target_uv_set: str = '', max_dropoff_distance: float = 0.0) → str

Create a live advBlendshapeWrap deformer driving target_mesh from source_mesh.

Any existing advBlendshapeWrap node found in target_mesh’s history is deleted first, so repeated calls always rebuild a fresh deformer with the current settings rather than reusing a stale one.

Parameters:

  • source_mesh – Source mesh transform whose live deformation drives the wrap. Must have deformation history (e.g. a blendShape) so Maya keeps an intermediate ‘orig’ shape as the rest pose; if it doesn’t, the deformer logs a Maya warning and passes target_mesh through unchanged until one exists.

  • target_mesh – Target mesh transform to deform live.

  • method – ‘uv’ or ‘topology’ (case-insensitive).

  • source_uv_set – UV set name on source_mesh. Used for method=’uv’.

  • target_uv_set – UV set name on target_mesh. Used for method=’uv’.

  • max_dropoff_distance – Topology method only. Maximum distance a source vertex can influence a target vertex; 0 = unlimited.

Returns:

Name of the created advBlendshapeWrap deformer node.

Return type:

str

File Queries

advBlendshapeTools.api.commands.get_file_targets(file_path: str) → list

Get target names from a blendshape .deltas file.

Parameters:

file_path – Path to the .deltas file.

Returns:

list of target name strings.

advBlendshapeTools.api.commands.get_file_vtx_count(file_path: str) → int

Get vertex count from a blendshape .deltas file.

Parameters:

file_path – Path to the .deltas file.

Returns:

Vertex count of the blendshape.

Return type:

int

advBlendshapeTools.api.commands.get_bweights_file_targets(file_path: str) → list

Get target names from bweights file. :param file_path: Path to bweights file.

Returns:

list of target name strings.

Return type:

list[str]

advBlendshapeTools.api.commands.get_bweights_file_vtx_count(file_path: str) → int

Get file vertex count from bweights file. :param file_path: Path to bweights file.

Returns:

vertex count

Return type:

int

advBlendshapeTools.api.commands.get_file_component_names(file_path: str) → list

Get component names from file. :param file_path: Path to .components file.

Returns:

List of component names.

Return type:

list[str]

advBlendshapeTools.api.commands.get_file_component_vtx_count(file_path: str) → int

Get component vertex count from a .components file. :param file_path: Path to .components file.

Returns:

Vertex count from file

Return type:

int

Weight Maps

advBlendshapeTools.api.commands.export_weights(blendshape: str, output_file: str) → None

Export blendshape deformer and target paint weights to a .bweights file.

Parameters:

  • blendshape – Name of the blendShape node.

  • output_file – Output .bweights file path.

advBlendshapeTools.api.commands.import_weights(mesh: str, input_file: str, method: str, blendshape: str | None = None) → None

Import blendshape weights from a .bweights file.

Parameters:

  • mesh – Target mesh transform name.

  • input_file – Input .bweights file path.

  • method – Remapping method when vertex counts differ (‘index’, ‘uv’, ‘topology’).

  • blendshape – Blendshape node name. Auto-detected from mesh if None.

advBlendshapeTools.api.commands.transfer_weights(source_blendshape: str, target_meshes: list[str], method: str = 'uv', target_blendshapes: list[str] | None = None) → list[str]

Transfer blendshape weights to target meshes. :param source_blendshape: Name of the blendShape node. :param target_meshes: List of target meshes. :param method: Topology method. (Default ‘uv’). :param target_blendshapes: List of target blendshapes.

Returns:

blendshape node names that received the weights.

Return type:

list[str]

advBlendshapeTools.api.commands.has_non_default_weights(blendshape: str) → bool

Return True if the blendshape has any weight values that differ from 1.0.

Checks both the deformer-level per-vertex mask and all target paint weights.

Parameters:

blendshape – Name of the blendShape node.

Returns:

True if any weight != 1.0 anywhere on the node.

Return type:

bool

Component Selections

advBlendshapeTools.api.commands.export_components(mesh: str, output_file: str, set_name: str) → None

Export components to components file. :param mesh: Mesh to export. :param output_file: Output file name. :param set_name: Component set name.

advBlendshapeTools.api.commands.import_components(mesh: str, input_file: str, set_name: str, method: str = 'uv') → list

Import components. :param mesh: Mesh to import. :param input_file: Input file name. :param set_name: Component set name. :param method: Topology method. (Default ‘uv’).

Returns:

List of components names.

Return type:

list[str]

Batch Operations

Batch functions accept lists of dataclass entries and process them in a single pass. Failures are logged per-entry and skipped without aborting the rest of the batch.

class advBlendshapeTools.api.commands.BlendshapeExportEntry(blendshape_node: str, file_path: str, threshold: float = 0.0)

Describes a single blendshape export operation for use with batch_export_blendshapes.

class advBlendshapeTools.api.commands.BlendshapeImportEntry(mesh: str, file_path: str, method: str, threshold: float = 0.0, max_dropoff_distance: float = 0.0, target_names: list[str] | None = None, overwrite: bool = False)

Describes a single blendshape import operation for use with batch_import_blendshapes.

advBlendshapeTools.api.commands.batch_export_blendshapes(export_entries: list[BlendshapeExportEntry]) → list[str]

Batch export blendshape nodes to .deltas files.

Parameters:

export_entries – list of BlendshapeExportEntry instances, one per export operation.

Returns:

file paths that were successfully exported.

Return type:

list[str]

advBlendshapeTools.api.commands.batch_import_blendshapes(import_entries: list[BlendshapeImportEntry]) → list[str]

Batch import blendshapes from .deltas files onto scene meshes.

Parameters:

import_entries – list of BlendshapeImportEntry instances, one per import operation.

Returns:

blendshape node names that were created.

Return type:

list[str]

class advBlendshapeTools.api.commands.WeightExportEntry(blendshape_node: str, file_path: str)

Describes a single weight export for use with batch_export_weights.

class advBlendshapeTools.api.commands.WeightImportEntry(mesh: str, file_path: str, method: str = 'uv', blendshape: str | None = None)

Describes a single weight import for use with batch_import_weights.

advBlendshapeTools.api.commands.batch_export_weights(export_entries: list[WeightExportEntry]) → list[str]

Batch export weight maps from blendshape nodes to .bweights files.

Parameters:

export_entries – list of WeightExportEntry instances.

Returns:

file paths that were successfully exported.

Return type:

list[str]

advBlendshapeTools.api.commands.batch_import_weights(import_entries: list[WeightImportEntry]) → None

Batch import weight maps from .bweights files onto meshes.

Parameters:

import_entries – list of WeightImportEntry instances.

class advBlendshapeTools.api.commands.ComponentExportEntry(mesh: str, file_path: str, set_name: str)

Describes a single component export for use with batch_export_components.

The current Maya selection filtered to mesh is captured at call time.

class advBlendshapeTools.api.commands.ComponentImportEntry(mesh: str, file_path: str, set_name: str, method: str = 'uv')

Describes a single component import for use with batch_import_components.

advBlendshapeTools.api.commands.batch_export_components(export_entries: list[ComponentExportEntry]) → list[str]

Batch export component selections to .components files.

The current Maya selection filtered to each entry’s mesh is what gets captured. In a scripted workflow the caller must ensure the correct selection is active for each entry before invoking this function.

Parameters:

export_entries – list of ComponentExportEntry instances.

Returns:

file paths that were successfully exported.

Return type:

list[str]

advBlendshapeTools.api.commands.batch_import_components(import_entries: list[ComponentImportEntry]) → list[list[str]]

Batch import component selections from .components files.

Per-entry checks (failures are logged, an empty list is appended for that entry):

  • mesh exists and is a transform node.

  • file path exists on disk.

  • set name exists in the file.

Parameters:

import_entries – list of ComponentImportEntry instances.

Returns:

one component string list per entry in the same order.

Failed entries produce an empty list.

Return type:

list[list[str]]

Utilities

advBlendshapeTools.api.commands.simple_transfer(source_blendshape: BlendShapeNode, target_mesh: str, connect_targets: bool = True, copy_input_connections: bool = False, target_names: list[str] | None = None, suffix_name: str = '__custom', threshold: float = 0.0) → BlendShapeNode

Bake blendshape targets onto a {shortName}__custom duplicate of the target mesh.

Use this when the target mesh is driven by a custom rig, either bound to the source mesh (proximity wrap, etc.) or driven by the source blendshape’s weights. Each source target is activated at weight=1.0, the target mesh pose is captured as a duplicate, then a new blendshape is built from those snapshots.

Parameters:

  • source_blendshape – Source BlendShapeNode driving the rig.

  • target_mesh – Target mesh transform whose deformed states will be baked.

  • connect_targets – If True, connect matching target weights from source to new blendshape.

  • copy_input_connections – If True, copy the source targets’ upstream input connections onto the matching new targets instead of chaining to the source blendshape’s weights. Mutually exclusive with connect_targets.

  • target_names – Optional subset of target names to bake. Uses all targets if None or empty.

  • suffix_name – suffix name for the duplicate mesh

  • threshold – Minimum vertex delta magnitude to keep. Deltas smaller than this are snapped back to the base pose. 0 = no filtering.

Returns:

New blendshape node created on the {shortName}__custom duplicate.

Return type:

BlendShapeNode

advBlendshapeTools.api.commands.auto_name_combinations(blendshape_nodes: str | list[str]) → None

Rename connected combinationShape nodes based on their drivers.

Renamed as {Driver1}_{Driver2}_CS.

Parameters:

blendshape_nodes – A blendShape node name, or a list of them.

advBlendshapeTools.api.commands.rebuild_blendshape(blendshape: str, threshold: float = 0.0) → str

Rebuild a blendshape in place via export/import round-trip.

Exports the node’s deltas (and paint weights, if any) to temporary files, deletes the node and its combination nodes, recreates an empty node with the same name on the same mesh, then re-imports. Target attribute connections, live extracted-target geometry connections, in-betweens, target directories, visibility, and combination shapes are preserved. Targets come back in their original order (index gaps/orphans are cleaned up); they are not re-sorted.

Parameters:

  • blendshape – Name of the blendShape node to rebuild.

  • threshold – Delta magnitude below which a vertex delta is dropped. Defaults to 0.0.

Returns:

The rebuilt blendShape node name.

Return type:

str