# Mush3D for Maya Documentation

## Introduction

Mush3D is a powerful sculpting and corrective shape plugin for Autodesk Maya. It provides a layer-based, non-destructive workflow for creating and managing mesh deformations, making it ideal for character artists, modelers, and animators.

## Use Cases

Mush3D is a versatile tool that can be integrated into various stages of a production pipeline:

- General 3D Sculpting: At its core, Mush3D is a robust sculpting toolset. You can create detailed characters, environments, and props using its comprehensive brush system and layer-based workflow, all within the Maya environment.
- On-the-Fly Shot Sculpting: For animated scenes, Mush3D allows artists to make quick adjustments and improvements directly on posed or animated meshes. This is perfect for fixing problematic deformations or adding subtle details to a character's performance in a specific shot.
- Advanced Corrective Shapes for Rigging: Mush3D excels at creating sophisticated corrective shapes. By using the Tangent Space mode, you can sculpt corrections that hold up even as the underlying mesh deforms. Combined with the Auto-Keyframe Solver, you can automate the blending of these shapes, creating a robust and flexible character rig.
- Enhancing Machine Learning Training Data: The quality of training data is crucial for machine learning models. Mush3D can be used to refine and clean up animated data, ensuring that the corrective shapes are consistent and well-behaved across all animations. The Auto-Keyframe feature is particularly useful here, as it can propagate corrections across entire animation sequences, improving the overall quality of the dataset.

## UI Overview: The Mush3D Editor

The main interface for Mush3D is the "Mush3D Editor" window. It's divided into several key areas:

### Deformer Management

This section allows you to manage the core `muCorrectiveShape` deformer nodes in your scene.

- Deformer Field: Displays the currently selected Mush3D deformer.
- Pick Button: Opens a menu to select an existing deformer or create a new one.
- Trash Button: Deletes the currently selected deformer from the scene.

### Brush Palette

A vertical toolbar on the left provides access to a variety of sculpting brushes:

- Clay: Adds or removes volume, simulating the feel of clay.
- Move: Grabs and pulls the mesh surface.
- Crease: Creates sharp, defined lines and wrinkles.
- Inflate: Expands the mesh outwards from the surface normal.
- Clone: Copies surface detail from a reference mesh to the current layer.
- Wrinkle: Creates complex, fine wrinkles based on a rest mesh.
- Vector: Displaces the mesh based on a vector map.
- Erase: Reverts sculpted details back to the base mesh state.
- Mask: Paints a mask to protect areas from being affected by other brushes.

### Layer Stack

This is the heart of the Mush3D workflow. It allows you to work on different details in isolated layers.

- Add/Remove Layer: Creates a new layer or deletes the selected one.
- Auto Animate: Automatically keys the visibility and intensity of selected layers.
- Mesh To Layer: Calculates the difference between two selected meshes and adds it as deltas to the current layer.
- Set Reference Mesh: Defines a reference mesh for the Clone and Wrinkle brushes.
- Layer List: Displays all layers with controls for visibility, name, intensity, and base frame.

### Layer Settings

Provides access to settings for the currently selected layer:

- Tangent Space: Controls whether deformations are calculated in tangent space, which is essential for preserving details on a deforming mesh.
- Iterations: This setting acts as a powerful shape preservation mechanism, similar to a localized Delta Mush. It intelligently smooths the corrective shape, preventing it from breaking or collapsing as the underlying mesh deforms throughout an animation. Higher values increase this smoothing effect, ensuring the sculpted details remain stable and well-defined across different poses.

### Global Settings

Controls that affect the entire tool:

- Lower/Higher Res: Navigates between subdivision levels of the mesh.
- Wireframe Opacity: Adjusts the visibility of the mesh wireframe during sculpting.
- Symmetry: Toggles symmetrical sculpting across an axis.
- Extract Vector Map: Launches the command to extract a vector displacement map from the current sculpt.

## Core Concepts

The UI is powered by a robust C++ backend that integrates seamlessly with Maya.

- `CorrectiveShape` Node: This is the main deformer node that manages all the layers, sculpting data, and mesh manipulations. All the UI operations ultimately modify the attributes of this node.
- Custom Commands: The plugin registers several custom commands (e.g., `muMeshToLayer`, `muExtractVectorDisplacement`) that are called by the UI scripts to perform complex operations.
- Custom Context: A custom sculpting context (`mush3dCtxCmd`) is used to handle the brush-based interaction in the viewport.

## Maya Integration

Mush3D is designed to work seamlessly with Maya's native tools and workflows. When you select a layer in the Mush3D Editor, the plugin automatically connects that layer's data to the mesh's tweak node.

This powerful integration means you can:

- Use Maya's Sculpting Brushes: Switch to Maya's Sculpting Shelf and use any of the native brushes to modify the selected Mush3D layer.
- Direct Vertex Manipulation: Enter component mode (F9) and directly move, rotate, or scale vertices. These changes will be stored on the active Mush3D layer.

## Subdivision Levels

Mush3D provides a flexible and non-destructive subdivision workflow, allowing you to sculpt on different levels of detail without ever altering the original mesh's topology or point order. This is particularly useful for production assets where the base mesh needs to remain intact.

### How it Works

When you enter sculpt mode, you can use the "Lower Res" and "Higher Res" buttons, or the Ctrl + Middle Mouse Button + Drag hotkey, to navigate between subdivision levels. The mesh you see in the viewport is a temporary representation, not the actual mesh itself. This allows for a fluid and interactive sculpting experience.

### Key Features

- Unified Layer System: Unlike other sculpting applications that require separate layers for each subdivision level, Mush3D stores all changes in a single, unified layer. Whether you're making broad strokes on a low-resolution level or adding fine details on a high-resolution one, all your edits are consolidated into the currently selected layer.
- Automatic Propagation: When you make a change on a lower subdivision level, the edits are automatically propagated up to the highest level when you release the mouse button. This ensures that your forms and details remain consistent across all levels.
- Non-Destructive Workflow: Because the subdivision levels are just representations, your original animated mesh is never altered. This preserves the point order and ensures that your asset remains compatible with your rigging and animation pipeline.

## Hotkeys and Controls

Mush3D uses a combination of mouse buttons and modifier keys for efficient sculpting:

- Sculpt: Left Mouse Button
- Brush Size: Middle Mouse Button + Drag Left/Right
- Brush Intensity: Shift + Middle Mouse Button + Drag Left/Right
- Change Subdivision Level: Ctrl + Middle Mouse Button + Drag Left/Right
- Isolate Faces: Ctrl + Shift + Left Mouse Button + Drag to show only the faces within the selection. Releasing Shift while dragging will hide the faces within the selection.
- Unhide All Faces: Ctrl + Shift + Left Mouse Button (Single Click) on an empty area.

## Basic Workflow

Here’s a simple step-by-step guide to get started with Mush3D:

1. Create a Deformer: Select a polygon mesh in your scene. In the Mush3D Editor, click the "Pick" button next to the Deformer field and choose "Add New". This will create and assign a `muCorrectiveShape` deformer to your mesh.
2. Add a Layer: In the Layer Stack, click the "Add Layer" button to create your first sculpting layer.
3. Start Sculpting: Select a brush from the Brush Palette (e.g., Clay). Your cursor will change in the viewport, and you can now sculpt directly on your mesh.
4. Adjust Intensity: Use the "Intensity" slider for your layer to blend your sculpted details in or out.
5. Extract a Map: Once you are happy with your sculpt, click the "Extract Vector Map" button in the Settings section to bake your details into a vector displacement map.

## Auto-Keyframe Solver

The Auto-Keyframe feature provides a powerful way to automate the animation of your corrective shapes. It creates a solver that analyzes the deformation of the mesh and drives the intensity of one or more layers accordingly.

### How it Works

When you trigger the Auto-Keyframe function, Mush3D performs the following steps:

1. Analyzes the Sculpted Area: It identifies the vertices that are affected by the currently selected layer(s).
2. Creates a Point Solver: A dedicated `muPointSolver` node is created to manage the relationship between the base mesh and the corrective layers.
3. Sets Features: The solver captures the 3D positions of the affected vertices on the base mesh and on each selected corrective layer. These positions serve as "features" or targets.
4. Connects Layer Intensity: The solver's output is connected directly to the "Intensity" attribute of the selected layers. As the input mesh deforms and tries to match the target features, the solver calculates the necessary intensity value for each layer to produce the desired shape.

### Usage

To use the solver:

1. Select one or more sculpted layers in the Layer Stack.
2. Click the "Auto Animate" button .
3. A solver network will be created in the background. Now, as you animate or deform the base mesh (e.g., through joints), the intensity of your selected corrective layers will be driven automatically to match the sculpted pose. This is particularly useful for complex areas like shoulders or elbows where multiple corrective shapes need to blend together.

## Licensing

Mush3D is available for download from the official website. Upon installation, the plugin will operate in a trial mode until a valid license is provided.

### Activation

To activate your copy of Mush3D, you can purchase a license from the website and apply it through the "Licensing" menu in the Mush3D Editor.

### License Server for Offline Environments

For studios and companies with restricted internet access on artist workstations, we provide a floating license server. This solution allows multiple users on a local network to share a pool of licenses. The license server for both Windows and Linux can be downloaded from www.mush3d.com.

How it works:

- A single machine on your network is designated as the license server. This machine requires an internet connection to activate and validate the purchased licenses with the Mush3D licensing backend.
- Client machines running Maya on the same network can then request a license seat from the local server without needing a direct internet connection themselves.
- The server manages the available seats, granting and releasing them as users open and close the Mush3D plugin.

#### Firewall Configuration

For the licensing system to function correctly, you may need to configure your firewall with the following rules:

- License Server Machine: Must have outbound access to `mush3d.com` on TCP port 443 (HTTPS) to activate and validate licenses.
- Client Machines: Must have access to the license server machine on the port the server is running on. The default port is `57321`, but this can be configured.