You are viewing the documentation for Deformable v0.2.1, an older version. Read the latest, v0.9.0
Maya Plugin
How the plugin works
How the Maya plugin builds deformable objects from nodes in their history, the shapes it adds, the Attribute Editor, the tool nodes, the start frame, Maya's history commands and the locked Deformable Scene.
On this page
This page shows how the Maya plugin puts the ideas of How the engine works into Maya: nodes, shapes, the Attribute Editor and the Time Slider.
Deformable objects
A deformable object is a mesh transform whose shapes are fed by a deformableObject node in its history. The create
actions build the whole network for you. For a mesh pSphere1 made with Create Object with Autocage, it is:
| Node | What it does |
|---|---|
| Tool nodes | Turn your mesh into tetrahedrons and a prepared render surface: here Autocage, Tetrahedralize and Prepare. See Tool nodes. |
| deformableMaterial | Holds the ten material values, with a Preset menu. |
| deformableObject | Makes the mesh a deformable object of the simulation, and holds its settings: Type, Disabled, Self Collision, Never Sleep, Show Inner Faces and Start Splintered. |
| deformableScene | Simulates its objects together. Each object hands it its rest data, and it hands each object back its state on every frame. |
The tools read your mesh as it stands at the start frame, history included. A deformer or an animated rig before them, such as a skinCluster or a blendShape, gives the object its start frame’s shape, and play is never slowed by the tools. You can edit the mesh or a tool at any frame: the tools compute again, and the next play from the start frame uses what they make.
Make every change to the transform before you create the object. Freeze its transformations then, with Modify > Freeze Transformations, if you want to. After Create Object, freezing would move the shapes the deformableObject feeds but not the mesh its tools read, so the object refuses it with Freeze Transformations does not apply to a deformable object: undo it, and freeze before Create Object. Undo it with Ctrl+Z.
The render surface keeps each face’s shading group, every UV set with the current one, and each corner’s normal, locked normals included. See Shading.
The shapes of an object
The network adds shapes under the object’s transform. The shaded one comes first, so the Attribute Editor and the Channel Box show it when you select the transform:
| Shape | What it shows | Shown |
|---|---|---|
p |
The deformed render surface. A bare object has none. | Yes |
p |
Your mesh, as you made it, with its history. The tools read it. | No: an intermediate object |
p |
The cage a Triangulate or an Autocage made, which Tetrahedralize fills. | No: a template |
p |
The tetrahedrons at rest, which a Kinematic object and its driven vertices follow. Deform or key it to drive the object. See Paint Driven Vertices. | No: a template |
p |
The simulated tetrahedrons, with the colour sets island and strain. A bare object shows it, in orange. Others get it the first time you show it. |
No, but on a bare object |
Edit Deformable > Show Shape and Hide Shape show and hide them for the selected objects: Surface Mesh, Input Surface Mesh (the mesh the surface is made from), Cage, Driven Tetrahedral Mesh, Simulated Tetrahedral Mesh, Splinters and Regions. Hide Shape makes the input surface mesh an intermediate object again.
Disassemble and detach
Edit Deformable > Disassemble Object takes each selected object apart into the meshes it was made of: it leaves its Deformable Scene, its network is deleted, and your mesh shows again with its own history. Its splinter cages, an added surface mesh and the regions under it move beside it. The report says how many it took apart, such as Disassembled 1 object.
Edit Deformable > Detach takes one part off each selected object:
| Item | What it does |
|---|---|
| Surface Mesh (shelf: Detach Surface Mesh) | Takes the render surface away: the object becomes a bare object and shows its tetrahedrons in orange. A surface mesh you added moves beside it. |
| Splinters (shelf: Detach Splinters) | Takes the splinter cages off its Prepare, and moves them beside it. |
| Fields | Stops the fields selected with it pushing it, or every field when none is selected. See Detach Fields. |
When nothing has the part, it warns Nothing to detach.
The Deformable Scene
A Deformable Scene holds one simulation: a locator transform deformableScene1 with the shape
deformableSceneShape1. The first create action makes one, or Deformable Scene > Create Scene, or
Create Scene on the shelf, which selects the one
the Maya scene has. It draws a small arrow along gravity, in the viewport only, never in renders. Its settings are in
the Attribute Editor: Start Frame, Gravity, Scale, Substeps, Disable, and the Glue All section.
See Simulation settings.
Gravity defaults to (0, −9.81, 0), down Maya’s Y axis. A new object joins the first Deformable Scene by name, at the scene’s next free element.
The Deformable Scene is locked, so Maya’s own history commands on one object cannot delete it or reach the other objects through it. Maya’s Delete refuses it, with Cannot delete locked node ‘deformableScene1’. Use Deformable Scene > Delete Scene instead. See Delete.
More than one Deformable Scene
Each Deformable Scene simulates its own objects. To split the objects of a Maya scene between two:
- Choose Deformable Scene > Create New Scene. It makes
deformableScene2, with its shapedeformableSceneShape2, on Maya’s time, locked like the first. Create Scene only selects the scene the Maya scene has, and Maya’s Duplicate gives a copy that is not on Maya’s time. - Select the objects to move, then the Deformable Scene they should join.
- Choose Edit Deformable > Move to Scene.
Each object leaves the scene it was in and joins the selected one, with the fields that push it. The report names the scene, such as Moved 2 objects to deformableScene2. Without a Deformable Scene selected, the objects move to the one new objects join.
An object in no Deformable Scene does not simulate. The plugin names it once, such as Deformable: Add to a Deformable Scene to simulate: pCube1.
Object order
A Deformable Scene takes its objects in the order of its objects elements, which is the order you made them in. A
rename never changes it, so a scene simulates the same before and after you rename objects or reopen the file. The
same holds for an object’s regions.
The Attribute Editor
Select a deformable object and open the Attribute Editor (Ctrl+A). Its tabs show the surface shape, then the nodes upstream of it: pSphere1_deformableObject, its tools and its pSphere1_deformableMaterial. The Channel Box lists them under INPUTS. To go straight to one node, choose Edit Deformable > Select > Deformable Scene, Deformable Object or Deformable Material, or Deformable Material > Select Material Node.
| Node | Attribute Editor sections |
|---|---|
| deformableObject | Status; Object Attributes: Type, Disabled, Self Collision, Never Sleep; Surface: Show Inner Faces, Start Splintered |
| deformableMaterial | Material Attributes: the Preset menu, then the ten values. See Materials. |
| deformableScene | Status; Scene Attributes: Start Frame, Gravity, Scale, Substeps, Disable; Glue All; Fields; Bake: Bake Directory |
| deformableTriangulate | Status; Triangulate Attributes: Maximum Area, Quality, Closed Boundary, Run; Anisotropy |
| deformableTetrahedralize | Status; Tetrahedralize Attributes: Maximum Edge Length, Run; Anisotropy |
| deformableExtrude | Status; Extrude Attributes: Thickness, Direction, Run |
| deformableSpanLayers | Status; Span Layers Attributes: Run |
| deformableAutocage | Status; Autocage Attributes: Scale Gap, Target Face Count, Target Tetrahedron Count, Run |
| deformablePrepare | Status; Prepare Attributes: Clip Mode, UV Scale, Inner Group Id, Run |
| deformableSplinter | Status; Splinter Attributes: Source, Image Library, Image File, Mesh Library, Mesh File, Size, Origin, Allow Nonconvex |
What each setting does is on Preparing meshes, Render surfaces and Fracture and splinters.
The Status section shows Compute State (Ready, Waiting, Computing or Cancelled), Error Message, Warning Message and, on the nodes that make tetrahedrons, Tetrahedron Count. The Deformable Scene’s Status Message shows what the scene says now, empty when nothing is wrong.
In the Attribute Editor’s Help menu, Help on a Deformable node type opens its section of this guide.
Node types
The plugin registers ten node types. You rarely make them by hand: the actions build and connect them.
| Node type | What it does |
|---|---|
| deformableTriangulate | Runs the Triangulate tool: your mesh, triangulated into a cage. |
| deformableTetrahedralize | Runs the Tetrahedralize tool: fills a closed triangle cage with tetrahedrons. |
| deformableExtrude | Runs the Extrude tool: one layer of tetrahedrons under a triangle mesh. |
| deformableSpanLayers | Runs the Span Layers tool: tetrahedrons between two layers with the same triangles. |
| deformableAutocage | Runs the Autocage tool: a new closed cage around any mesh. |
| deformablePrepare | Runs the Prepare tool: clips a render surface to the tetrahedrons and attaches it to them. |
| deformableSplinter | Makes a splinter cage from a line drawing or a mesh, for Prepare. |
| deformableMaterial | Holds the ten material values, with a Preset menu. |
| deformableObject | Makes a mesh a deformable object of a Deformable Scene. |
| deformableScene | Holds one simulation: the deformable objects that collide with each other. |
The tools are explained in How the engine works.
Tool nodes
Seven nodes run a tool: Triangulate, Tetrahedralize, Extrude, Span Layers, Autocage, Prepare and Splinter. The plugin stores their output in the scene file, so a reopened file computes nothing again. Prepare is the exception: its output is not stored, and it prepares the surface again the first time the file shows it.
While Triangulate, Tetrahedralize, Autocage or Prepare run in the background:
- the progress bar at the bottom of Maya’s window shows them, with how long each has run, such as Deformable: Tetrahedralize (pSphere1) 0:42;
- their Compute State shows Computing.
Press Esc while the progress bar shows them to cancel them all. A cancelled node shows Cancelled and keeps its last output until one of its inputs changes.
A node shows its error or warning in the Status section of its Attribute Editor. A new error or warning also goes, once, to the Script Editor and the Command Line, with the object and the node it belongs to, such as Deformable: pSphere1: Deformable Tetrahedralize: INVALID_CAGE: …. In mayapy and in a batch render, the tools run as Maya asks for them, without the progress bar.
Run: Auto or Wait
Every tool node but Splinter has a Run attribute. A node set to Wait shows Waiting. To switch every tool of the selected objects, choose Edit Deformable > Wait on Update or Don’t Wait on Update. To compute the waiting tools once, and the cancelled ones again, choose Edit Deformable > Update Now, or click Update Now on the shelf. Update Now also computes the tools of a selected Autocage Mesh or splinter cage.
When you open a file whose tools wait, the plugin says which, such as Deformable: 2 tools wait for Update Now: pSphere1_deformableTetrahedralize, pSphere1_deformablePrepare.
The start frame
The start frame is the Start Frame of the Deformable Scene, in the Scene Attributes section. Create Scene sets it to the start of the playback range. It does not follow the Time Slider afterwards: change it on the scene when your shot starts elsewhere. Simulate Frame Range and Bake Simulation run from the start frame to the end of the playback range.
The tool nodes read their inputs at the start frame. Play from the start frame waits for the tools still computing first, with Maya’s busy cursor, and says so: Deformable: Play waits for the start frame to compute, with the tools it waits for. Simulate Frame Range and Bake Simulation also finish every tool first.
When a rule stops the simulation, the Script Editor and the Command Line say so, once, with the scene’s name:
- Deformable: deformableScene1: Play from the start frame when you jump ahead without playing;
- Deformable: deformableScene1: Return to the start frame to apply changes after you change what the world is built from, such as an object’s mesh, the scene’s Gravity or a region’s place;
- Deformable: deformableScene1: Set Playback speed to Play every frame: a dropped frame is never simulated when playback skips frames. Create Scene sets Play every frame for you.
See Play.
Animated values are read at the frame
The simulation reads animated values at the frame it computes: frame 10 uses what frame 10 shows. A Kinematic object follows its keys on the same frame, a keyed material value applies at its frame, and an object whose Type turns Dynamic at frame 20 first moves at frame 20.
The values read on every frame are the object’s Type, the scene’s Disable, every material value, the transform and the driven tetrahedral mesh of each object, which Kinematic objects and driven vertices follow, the passive regions and the fields. Keys on them play with the simulation. Any other change asks you to return to the start frame.
Units and axes
Maya stores lengths in centimetres, but the simulation reads one Maya unit as one metre, as Maya’s own nCloth does. Gravity is 9.81 down Y. So leave Maya’s working unit at centimetre and treat one unit as one metre: a sphere of radius 1 is a 2 m ball.
To model at real size in centimetres, set Scale on the Deformable Scene to 0.01. Set it to 0.01 too if you
change the working unit to metre in Windows > Settings/Preferences > Preferences > Settings: Maya still stores
centimetres, so a 1 m cube reaches the simulation as 100 units. See
Scale.
Count the tetrahedrons
The plugin counts the tetrahedrons at the start frame:
- After a create action, once its tools finish, the Script Editor names the new object with its count and the scene’s total, such as Deformable: Made pCube1: 94 tetrahedrons; scene total 2,006. During the trial, a scene over the limit adds the limit to that line, as a warning.
- The Tetrahedron Count in the Status section of the object’s deformableObject, and of its Tetrahedralize, Extrude or Span Layers node, shows the count of that node.
A bare object shows its tetrahedrons, 4 triangles each, so Maya’s Display > Heads Up Display > Poly Count also works on it: divide its triangle count by 4.
The outputs of a deformable object
The deformableObject node gives these outputs. The first three feed the object’s shapes; scripts read the others.
| Output | What it holds |
|---|---|
output |
The deformed render surface, with your shading, UV sets and normals, in the object’s space. Feeds _. |
output |
The simulated tetrahedrons, 4 triangles each on points they share, with the face colour sets island (the piece each belongs to) and strain (how much it is stretched). Feeds _. |
output |
The tetrahedrons at rest. Feeds _. |
output, output, output |
One value per tetrahedron: its island, its strain measure and its flags. |
output, output, output |
One point on each inner face that opened at this frame, in the object’s space: its position, its outward direction and the index of its tetrahedron. |
To emit dust or sparks where an object cracks, see Fracture points.
To see the pieces, choose Edit Deformable > Show Shape > Simulated Tetrahedral Mesh, select that shape, and pick
its island colour set in Mesh Display > Color Set Editor, in the Modeling menu set.
Shading
The render surface keeps the shading of the mesh it is made from, face by face, through every fracture, and every UV set, with the one current on your mesh. Each corner keeps the normal your mesh shows, hard or soft, locked normals included. A bare object’s tetrahedrons, and a surface that Use Tetrahedral Mesh as Surface Mesh made from an autocage or from the outer faces of tetrahedrons, are shaded as a whole, with the first shading group of the mesh.
The inner faces that a crack opens take the first shading group of the surface, unless you give them their own with Assign Inner Material.
Maya does not pass a shading change of your mesh down to the surface. After you assign other materials to the mesh, select the object and choose Edit Deformable > Refresh Surface Mesh. See Change the surface.
History and the locked scene
Maya’s own history commands reach through the network, so use the plugin’s instead:
| Instead of | Use | Why |
|---|---|---|
| Edit > Delete by Type > History on a deformable object | Edit Deformable > Delete History | Maya’s deletes the mesh the object was made from and freezes its surface where it stands, so the object no longer follows the simulation. |
| Modify > Freeze Transformations after Create Object | Freeze before you create the object | The object refuses it with an error until you undo it. |
| Edit > Duplicate | Edit Deformable > Duplicate Object | Maya’s copies the shapes without the network that moves them. See Duplicate Object. |
| Edit > Delete on the Deformable Scene | Deformable Scene > Delete Scene | The scene is locked against Maya’s Delete. |
| Edit > Duplicate on the Deformable Scene | Deformable Scene > Create New Scene | Maya’s copy is not on Maya’s time, so it never steps. |
If you used one of Maya’s by mistake, undo it with Ctrl+Z.
Delete History
Edit Deformable > Delete History deletes the construction history of the meshes the selected objects are made from, such as a polySphere node or a deformer, and keeps their networks, their Deformable Scene and the other objects. The report says how many, such as Deleted the history of 1 object.
Delete
Edit Deformable > Delete deletes the selected deformable objects, each with the nodes it alone is made of, and the selected Deformable Scenes. Deformable Scene > Delete Scene is the same action. A deleted scene’s objects stay, in no scene. The report says what it deleted, such as Deleted 1 object and 1 Deformable Scene.
Maya’s own Delete of a deformable object’s transform, or of a group that holds it, also takes its deformableObject, its tools and its own materials, and takes it out of its scene. One undo brings it all back. What other objects share stays, such as a region or a material.