meshController

Introduction

meshController 2.0.0 is a Maya C++ plugin for high-performance mesh controls, surface pinning, and deformation workflows in production facial and character rigs. V2 replaces the legacy mesh tracking design with one centralized, data-only overlay per driver while retaining the established shapeControl, vertexWrap, and surface pin tools.

• Surface Pin — bind any number of rig controls to a deforming mesh surface so that they track position, orientation, and twist precisely, with full undo/redo and parallel evaluation via TBB. A core advantage is the localInverseMatrix input, which solves the double-transform problem inline — no extra utility nodes required when the pin drives offset controls in a facial rig hierarchy. The node also preserves the current transform offset at bind time, so controls retain their authored pose.
• vertexWrap — a lightweight deformer that snaps split or matching-topology meshes directly to a driver mesh via one-to-one vertex mapping. Designed for large numbers of small individual control shapes; benefits significantly from Maya's parallel evaluation manager.
• Data-only mesh controls — meshControlDataOverlay stores compact patch topology and driver-vertex mappings, then draws every patch through retained VP2 GPU buffers. No duplicate hidden draw meshes are generated.

What's New in V2.0

Node Summary

Quick Start

• 1

  Load the plugin. All nodes and commands become available immediately.

  import maya.cmds as cmds
  cmds.loadPlugin("meshController")

• 2

  vertexWrap — select the driver mesh first, then one or more split-topology target meshes, and run. Each target vertex snaps to its closest driver vertex at bind time.

  cmds.select(['face_driver_GEO', 'ctrl_mesh_A', 'ctrl_mesh_B'])
  cmds.vertexWrap()

• 3

  surfacePinBind — position your controls at bind pose, select the mesh followed by the controls, then bind. maintainOffset preserves the current world transform; inverse cancels the control's own local TRS to avoid double-transform in a facial rig hierarchy.

  cmds.select(['head_GEO'] + cmds.ls('lip_ctrl_*'))
  cmds.surfacePinBind(maintainOffset=True, inverse=True)
  
  # Append more controls to the same node later
  cmds.select(['head_GEO', 'brow_ctrl_L'])
  cmds.surfacePinBind(node='surfacePin1', maintainOffset=True, inverse=True)

• 4

  surfaceUVPinBind — same workflow as surfacePinBind but pins are stored in UV space. Prefer this when the driver mesh topology may change during production but its UV layout stays stable.

  cmds.select(['head_GEO'] + cmds.ls('cheek_ctrl_*'))
  cmds.surfaceUVPinBind(maintainOffset=True)

• 5

  shapeControlCreate — select a mesh or curve to use as the control shape, then run. Baked mode copies the shape once (fastest); live mode keeps it connected to the source and follows deformation.

  cmds.select('my_ctrl_curve')
  cmds.shapeControlCreate()             # baked, fastest, does not follow deformation
  cmds.shapeControlCreate(live=True)   # follows source deformation, heavier

• 6

  meshControlDataBind — select the driver first, followed by one or more patch meshes. Every patch vertex must resolve to a driver vertex within the bind tolerance.

  cmds.select(['face_driver_GEO', 'brow_A_proxy', 'brow_B_proxy'], r=True)
  overlay = cmds.meshControlDataBind(
      name='face_meshControlDataOverlay',
      bindTolerance=0.0001,
      hidePatches=False)

  The manager provides the same workflow through New Overlay, and is recommended when a scene contains multiple rigs.

Manager UI

Mesh Control Manager 2.0.0 provides the recommended workflow for data overlays, patch selection targets, tracked ShapeControls, creation utilities, and pinning. Open it from a Python tab in Maya's Script Editor:

import meshControlManagerUI
window = meshControlManagerUI.show()

Active Driver and Status

The Active Driver menu chooses which overlay the manager edits. Selecting a patch, linked control, driver, or overlay can switch the active entry automatically; enable Lock to keep the current rig active while selecting elsewhere. This is the central control for scenes containing multiple imported or referenced rigs.

Mouse Tracking: Patches

The patch list displays transform names. Patch identity is resolved through the overlay's indexed patchSourceMeshes message connections rather than saved DAG strings, so namespaces and node renaming do not invalidate the binding. Use Refresh after an external rename to update a visible label.

Bind tolerance

Bind tolerance is the maximum world-space distance between each patch vertex and its matched driver vertex. The default is 0.0001. Increase it only when patches are not perfectly aligned; binding fails if any patch vertex falls outside the threshold and warns if multiple patch vertices map to the same driver vertex.

Mouse Tracking: Shape Controls

Add existing shapeControl nodes to this tab when they must depth-compete with data-overlay patches. Tracked ShapeControls hand hover ownership to the Active Driver overlay; untracked ShapeControls continue using their normal standalone hover. The tracked control does not need a deformation or driver connection.

Patch Behavior

Selection Targets

Right-click patch rows to assign animator-facing controls without adding one custom attribute per patch. Targets are persisted through message connections and used for viewport selection and readout.

Create and Pin

vertexWrap Node

vertexWrap is a MPxDeformerNode designed for split or matching-topology meshes. At bind time it computes a one-to-one vertex mapping from each driven mesh to the driver. At evaluation time there is no proximity search, no weight solve, and no barycentric interpolation — it reads the current driver points and directly writes each driven vertex to its mapped driver position, scaled by the deformer envelope. This makes it the minimal-cost option whenever topology correspondence already exists.

Driver point reads are cached per evaluation cycle behind a mutex; per-vertex write work is lockless, so the deformer scales cleanly under Maya's parallel evaluation manager (EMP).

Attributes

Performance

Evaluation-time comparison against Maya's built-in proximityWrap (surface and snap modes) and the legacy wrap deformer. Test scene: split-topology mesh controls bound to a deforming face geometry driver. Timing measured over multiple playback passes; DG, EMS, and EMP modes recorded separately.

Detailed results

vertexWrap Command

Creates a vertexWrap deformer and computes the vertex mapping for all selected target meshes. Select the driver mesh first, then one or more target meshes.

# Select driver first, then targets
cmds.select(['driver_GEO', 'target_A', 'target_B'])
cmds.vertexWrap()

# Optional: name the node
cmds.vertexWrap(name='face_vertexWrap')

surfacePin Node

surfacePin is a MPxNode that reads a deforming mesh each frame and outputs a world-space 4×4 matrix per control, derived from the mesh surface at the control's stored bind position. The orientation encodes the local TBN frame: X = tangent, Y = bitangent, Z = surface normal.

Bind data (barycentric weights, vertex indices, tangent coefficients) is baked at bind time by surfacePinBind and stored in storable attributes. At runtime, only the deformed mesh positions are read — no closet-point searches occur per frame.

How the surface frame is built

For each control i per compute frame:

1. Interpolate mesh position using stored barycentric weights over 3 triangle vertices → world position.
2. Reconstruct a smooth normal by blending per-vertex local-topology normals (vertex ring averages) at the 3 triangle corners.
3. Reconstruct the tangent from stored edge-relative coefficients (a·edge₀ + b·edge₁), projected onto the normal plane. This prevents world-space drift as the mesh deforms.
4. Compute bitangent as N × T. Assemble the 4×4 matrix.
5. Optionally apply the stored bind offset (for -maintainOffset mode) via pre-/post-multiply of bind inverse and bind control matrices.
6. Apply parent-inverse and/or control-inverse compensation if connected.

The TBB parallel_for loop runs over all N controls simultaneously when parallel evaluation is active.

Attributes

Per-Frame Inputs

Stored Bind Data (Storable)

Outputs

Connection Diagram

surfacePinBind Command

Creates a surfacePin node (or appends to an existing one), bakes all bind data from the mesh at its current deformed state, and wires the full connection graph. Fully undoable.

Syntax

# Create a new node
surfacePinBind mesh ctrl0 ctrl1 ... [flags]

# Append controls to an existing node
surfacePinBind [mesh] ctrl0 ctrl1 ... -node surfacePin1 [flags]

# Rebind all controls using stored mesh (no arguments)
surfacePinBind -node surfacePin1

Returns the name of the surfacePin node.

Flags

Examples

// Basic bind: snap controls to mesh surface
surfacePinBind head_GEO ctrl_0 ctrl_1 ctrl_2;

// Maintain current world positions
surfacePinBind head_GEO mouth_ctrl -maintainOffset;

// Cancel local double-transform (inverse mode)
surfacePinBind head_GEO lip_ctrl -inverse true;

// Translate-only following
surfacePinBind head_GEO brow_ctrl_L -connect translate;

// Append to existing node
surfacePinBind head_GEO new_ctrl_0 -node surfacePin1;

// Rebind all controls after repositioning
surfacePinBind -node surfacePin1;

import maya.cmds as cmds

# Basic bind
node = cmds.surfacePinBind('head_GEO', 'ctrl_0', 'ctrl_1')

# Maintain offset
node = cmds.surfacePinBind('head_GEO', 'mouth_ctrl', maintainOffset=True)

# maintainOffset + inverse — creates a new surfacePin node
node = cmds.surfacePinBind('head_GEO', 'lip_ctrl', maintainOffset=True, inverse=True)

# maintainOffset + inverse — appends to an existing node
node = cmds.surfacePinBind('head_GEO', 'brow_ctrl', node='surfacePin1', maintainOffset=True, inverse=True)

# Translate-only
node = cmds.surfacePinBind('head_GEO', 'cheek_ctrl', connect='translate')

# Rebind in-place
cmds.surfacePinBind(node=node)

surfaceUVPin Node

surfaceUVPin is a UV-space variant of surfacePin. Rather than storing vertex indices at bind time, it stores the UV coordinates of each pin location. At runtime, those UVs are resolved back to triangle barycentric coordinates within the current UV triangle set.

This makes pins stable across topology changes that preserve UV layout — a common workflow when sculpting or re-topo'ing a mesh while retaining its UV map. The trade-off is a one-time UV-triangle rebuild cost whenever the UV set changes.

Key differences from surfacePin

Attributes

UV Bind Data (Storable)

surfaceUVPinBind Command

Creates a surfaceUVPin node and binds controls. Flags are a subset of surfacePinBind:

# Python
node = cmds.surfaceUVPinBind('head_GEO', 'ctrl_0', 'ctrl_1')
node = cmds.surfaceUVPinBind('head_GEO', 'mouth_ctrl', maintainOffset=True)

shapeControl Node

A VP2 MPxLocatorNode with a full MPxDrawOverride that renders in DX11/OpenGL/Metal. It accepts an optional geometry input (inGeometry) and draws the connected mesh or NURBS curve directly in the viewport using the locator's transform, with configurable draw style, line width, color, transparency, and X-ray mode.

Key display attributes

shapeControlCreate Command

Select a mesh or curve first, then run. By default the command bakes the source geometry into the control at creation time — the result is lightweight because no live connection to the original source is needed during playback. Use live=True to keep the source connected so the control shape follows deformation.

# Baked — fastest, does not follow deformation
cmds.select('my_ctrl_shape_GEO')
cmds.shapeControlCreate()

# Live — follows source deformation, heavier
cmds.shapeControlCreate(live=True)

meshControlDataOverlay Node

meshControlDataOverlay is a centralized VP2 MPxLocatorNode with an MPxGeometryOverride. It stores each patch's topology and driver-vertex mapping as compact arrays, evaluates the current driver geometry, and submits batched base, selected, hover, and wireframe render items. GPU vertex/index buffers are retained and static index data is reused until topology changes.

The driver's worldMesh[instance] connects to inMesh. Driver transform changes, animation time, geometry revisions, and topology revisions invalidate the appropriate caches. Picking uses the same evaluated driver state as drawing, including animated frames and transformed drivers.

Display Attributes

Binding and Identity

meshControlDataBind Command

Select the driver mesh first, then one or more patch meshes. At bind time, each patch vertex is mapped to the closest driver vertex inside the bind tolerance. The command stores patch triangle/edge topology, connects source and default control messages, and creates one meshControlDataOverlay for the driver.

meshControlDataBind driver patch0 [patch1 ...] [flags]

# Selection-driven Python example
cmds.select(['face_GEO', 'brow_A_proxy', 'brow_B_proxy'], r=True)
overlay = cmds.meshControlDataBind(
    name='face_meshControlDataOverlay',
    bindTolerance=0.0001,
    hidePatches=False)

Viewport Interaction

A plug-in lifetime Qt event filter follows Maya model-panel viewports. For each mouse position it evaluates visible overlays, traverses their patch BVHs, tests tracked ShapeControls, and compares results with scene depth. Only the closest visible candidate receives hover.

Selection

• A patch selection commits on left-button release over the same patch, not on press.
• Dragging after press cancels patch selection, allowing manipulators to begin normally.
• Shift adds to the Maya selection; Ctrl removes from it.
• Alt bypasses overlay interaction so Maya camera orbit, pan, and zoom remain available.
• Custom patchControl[] targets take priority; otherwise the patch transform or configured parent is selected.

Manipulator Priority

Move, scale, rotate, and universal manipulator regions suppress patch hover and click capture. The rotate tool reserves the full disc inside its outer ring. Returning from another patch to a handle clears the previous patch hover immediately, so the handle can be dragged on mouse press.

Multiple Viewports and Isolate Select

Viewport ownership follows the model panel receiving the event rather than one permanently active panel. Overlay picking therefore works across switched and newly used viewports. Isolate Select membership is resolved per panel so related drivers, patches, controls, and the hover marker can participate without leaking interaction from non-isolated rigs.

Multiple Overlays

All live meshControlDataOverlay nodes are considered during one mouse event. V2 compares candidate depth globally, applies hover to the winning overlay, and clears stale hover and selected visual state on the others. Imported and namespaced rigs therefore remain independent while sharing the same viewport interaction service.

Performance Benchmarks

Evaluation time measured against Maya's built-in uvPin and proximityPin nodes. Tests use a deforming animated sphere mesh (80-subdivision, ~10K vertices) driven by a blendShape + animated transform group, with controls distributed in a Fibonacci sphere pattern. Parallel evaluation enabled, 120 frames × 2 repeats.

Technical Notes

Node IDs

TBB Parallelism

Both surfacePin and surfaceUVPin use tbb::parallel_for over the N-control loop in compute(). The node scheduling type is kParallel, so Maya's parallel evaluation manager can also run multiple node evaluations concurrently across the DG.

Tangent Stability

Tangents are stored as two scalar coefficients [a, b] relative to the containing triangle's edge vectors, not as a world-space direction. At runtime: T = a·edge₀ + b·edge₁. This means the tangent deforms with the mesh geometry and never drifts due to world-space rotation or scale — a common artifact in UV-tangent or fixed-reference approaches.

Smooth Normal Reconstruction

Rather than using Maya's cached face-vertex normals (which can produce seams at hard edges), surfacePin computes local topology normals at runtime: for each triangle corner vertex, it averages the cross products of the surrounding edge pairs in a configurable vertex ring, then barycentric-blends those three corner normals. This produces C⁰-continuous normals across the surface and handles hard edges correctly.