meshController

Introduction

meshController is a Maya C++ plugin that provides high-performance surface pinning and mesh deformation tooling for production facial and character rigging. It ships six node types and five commands targeting two core workflows:

• 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.
• Viewport Tooling — a custom VP2 locator (shapeControl), a mesh surface overlay (meshControlOverlay), and an interactive placement mode (meshControlMode).

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

  meshControlMode — interactive viewport mode that tracks split-topology control meshes bound to a vertexWrap node. Select the driver and target meshes, then bind to the node to start tracking:

  cmds.select('driverA', 'a', 'b', r=True)
  cmds.meshControlMode(bind='driverA_vertexWrap')

  # Primary on/off
  cmds.meshControlMode(enable=True)       # enable / refresh tracking from mesh selection
  cmds.meshControlMode(enable=False)      # disable mode

Manager UI

A single window that consolidates all plugin commands — tracking, display, binding, and pinning — without needing to run commands manually. Open it with:

import meshControlManagerUI
meshControlManagerUI.show()

Status Bar

A color-coded dot at the top of the window shows the current mode state at a glance:

Tracked Meshes

Lists all meshes currently tracked by meshControlMode. Double-clicking a row selects that mesh in the Maya viewport.

Click Target

Controls the meshControlSelectParent attribute on the meshes selected in the list. When checked, clicking that mesh's overlay patch in the viewport selects its parent transform instead of the mesh itself. Supports tristate when multiple rows with mixed values are selected.

Overlay Display

Three toggles that update the meshControlOverlay node draw attributes live:

Build

Shortcut buttons for creating nodes. All respect the current Maya selection.

Pin

Creates surface pin binds from the current Maya selection (mesh first, then controls). Options apply to both pin types where supported:

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)

meshControlOverlay Node

A VP2 locator that draws a surface marker at a tracked hit position on a source mesh, with an optional wireframe overlay and in-viewport transform readout. It receives hit-point and hit-normal data (from meshControlMode) via the hitPosition and hitNormal attributes, and renders a configurable marker at that location in real time.

The overlay caches the source mesh geometry (triangulated positions and face normals) with a serial number invalidation strategy — geometry is only rebuilt when the source mesh changes shape or topology. The draw override uses a precomputed MMatrix cache for world-to-overlay transforms.

Key attributes

meshControlMode Command

An interaction and overlay system for working with mesh-based controls. It tracks selected meshes, draws hover and selection overlays via meshControlOverlay, and supports binding a driver mesh to driven control meshes through vertexWrap. Internally, a Qt QObject event filter intercepts mouse-move events in the active viewport and performs a ray-cast against the tracked surface on each move, updating the overlay hit position in real time.

Using meshControlOverlay for batched drawing makes this significantly more efficient than many separate live shapeControl nodes — all draw data goes through one overlay node with no per-mesh VP2 draw call overhead.

# Bind driver + targets to a vertexWrap node and start tracking
cmds.select('driverA', 'a', 'b', r=True)
cmds.meshControlMode(bind='driverA_vertexWrap')

Selection Behavior

Clicking a hovered tracked patch selects its selection target. The target is resolved in order:

1. If the patch has meshControlSelectNode connected → selects that connected transform
2. Else if the attribute meshControlSelectParent on the tracked mesh is true → selects the parent transform
3. Otherwise → selects the mesh transform itself (default)

Flags

# Tracking
cmds.meshControlMode(enable=True)       # enable / refresh tracking from mesh selection
cmds.meshControlMode(enable=False)      # disable mode
cmds.meshControlMode(append=True)       # append selected meshes to tracked list
cmds.meshControlMode(remove=True)       # remove selected meshes from tracked list
cmds.meshControlMode(clear=True)        # clear tracked meshes

# Display
cmds.meshControlMode(xray=True)         # draw overlay in xray
cmds.meshControlMode(wireframe=True)    # draw wireframe overlay
cmds.meshControlMode(marker=True)       # draw hover marker

# Utility
cmds.meshControlMode(select=True)       # select the overlay node
cmds.meshControlMode(reactivate=True)   # reinstall / reactivate viewport mouse filter

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.