You are viewing the documentation for Deformable v0.4.1, an older version. Read the latest, v0.9.0
Maya Plugin
Command line and scripting
Install, simulate and render from a terminal with mayapy and Render, build Deformable scenes with Python scripts, every Deformable action as a Python function, the runtime commands and their flags, and fracture points for particles.
On this page
Everything in the Deformable menus is a Python function you can call from a script, and Maya can simulate and render a scene without opening its window. This page is for pipeline work: render farms, batch jobs and scene-building scripts.
The examples call mayapy and Render by name. They are in Maya’s bin folder:
| System | Folder |
|---|---|
| macOS | /Applications/Autodesk/maya2027/Maya.app/Contents/bin |
| Linux | /usr/autodesk/maya2027/bin |
| Windows | C:\Program Files\Autodesk\Maya2027\bin |
Install from a terminal
Unzip the plugin into a modules folder, as
Install the plugin shows, and Maya, mayapy and
Render find it there. A scene file that holds Deformable nodes loads the plugin when it opens. A script that builds a
scene loads it with cmds.loadPlugin("deformable").
On a render farm, unzip it into a shared folder and point Maya at it with the MAYA_MODULE_PATH environment variable,
which lists the folders that hold .mod files:
export MAYA_MODULE_PATH=/studio/maya/modulesRestart Maya after you install a new version: a running Maya keeps the plugin it loaded.
Render from a terminal
Maya’s Render command renders a scene file without opening Maya’s window. Give it the full path of the file. The
plugin simulates each frame as the render reaches it, and a baked scene renders its bake:
Render -r arnold -s 1 -e 48 /projects/shot/shot.maRender the whole range from the start frame. The Deformable Scene’s Start Frame is an attribute of the scene, so
-s does not move it: a render that starts after the start frame renders a scene that is not baked at rest. To render
frames 10 to 48 of a simulation that starts at frame 1, bake it and save the file first. The render then reads those
frames from the bake. See Bake Simulation.
The plugin prints what it does, each line starting with Deformable:, so a render log shows it:
| Line | When |
|---|---|
Deformable: deformable |
A frame was simulated, in that many seconds. Each Deformable Scene that stepped follows, with how long its step took and the mean step since the start frame. |
Deformable: deformable |
The simulation reached the end of the playback range. |
Deformable: deformable |
The render starts where the simulation cannot reach, and the named objects are not baked. |
Deformable: deformable |
The scene changed after its bake, or the bake folder is missing, so the scene simulates instead. |
Deformable: p |
A node shows a new error or warning. |
Deformable: deformable |
The scene says something new, such as Play from the start frame. See Troubleshooting. |
Deformable: deformable |
Play left the named objects out and simulates the others. See An object stays still at Play. |
A message is printed when it appears, not again on each frame.
Simulate from a terminal
mayapy is Maya’s Python: it runs a script with Maya and the plugin, without a window. This command opens a file and
plays every frame from the start frame to the end of the playback range, as Simulate Frame Range does:
mayapy -c "import maya.standalone; maya.standalone.initialize(); from maya import cmds; cmds.file('/projects/shot/shot.ma', open=True); from deformable_maya import commands; commands.run('deformableSimulateFrameRange')"The frame cache lives only in memory, so this command saves nothing. Use it to time a simulation, or to check that a file simulates on a render node before you render it. It prints a line for each frame, with about how long the frames left take, and one for the whole range:
Deformable: deformableScene1: frame 1 of 48 in 0.04 s · less than a minute left
Deformable: deformableScene1: frame 2 of 48 in 2.61 s · about 1 min left
…
Deformable: deformableScene1: frame 48 of 48 in 2.38 s
Deformable: deformableScene1: Simulated frames 1–48 in 1 min 55 sIt stops where a scene says something that stops the simulation, and prints where and why, such as
Deformable: deformableScene1: Stopped at frame 1: No Deformable Scene: choose Deformable Scene > Create Scene.
Advice, such as objects that no Deformable Scene takes, is printed and the range goes on.
To keep the frames, bake instead: commands.run('deformableBakeSimulation'), then save the file with
cmds.file(save=True).
Build a scene with a script
This script builds the scene of Getting started: a brick sphere that
falls onto a floor. It sets one scene setting, saves the file, bakes 48 frames beside it, and prints what the sphere
looks like at the end. Save it as drop_sphere.py and run it with mayapy drop_sphere.py:
import os
import maya.standalone
maya.standalone.initialize(name="python")
from maya import cmds
cmds.loadPlugin("deformable")
from deformable_maya import commands
# A new scene, 48 frames long.
cmds.file(new=True, force=True)
cmds.playbackOptions(minTime=1, maxTime=48)
# A sphere 3 units up, in an autocage, made of brick. The first create action adds the Deformable Scene.
sphere = cmds.polySphere(name="ball")[0]
cmds.setAttr(sphere + ".translateY", 3)
cmds.select(sphere)
commands.run("deformableCreateObjectWithAutocage")
commands.run("deformableAssignMaterialPreset", preset="brick")
# A floor 20 units wide, extruded 0.2 down, that does not move, rendered with the plane's shading.
floor = cmds.polyPlane(name="floor", width=20, height=20, subdivisionsWidth=1, subdivisionsHeight=1)[0]
cmds.select(floor)
commands.run("deformableCreateBareObject", source="nonClosedPolygonMesh", thickness=0.2, direction="down")
commands.run("deformableUseTetrahedralMeshAsSurfaceMesh")
commands.run("deformableSetType", type="kinematic")
# Ten substeps a frame, on the scene's shape.
cmds.setAttr("deformableSceneShape1.substeps", 10)
# Save, then bake every frame into the folder beside the file, and save the bake's record.
cmds.file(rename=os.path.abspath("drop_sphere.ma"))
cmds.file(save=True, type="mayaAscii")
commands.run("deformableBakeSimulation")
cmds.file(save=True)
cmds.currentTime(48)
cmds.getAttr("deformableSceneShape1.simulatedFrame")
lowest = cmds.exactWorldBoundingBox("ball_surfaceMesh")[1]
print(f"Frame 48: lowest point {lowest:.2f}, {cmds.polyEvaluate('ball_surfaceMesh', face=True)} faces")
maya.standalone.uninitialize()After the plugin’s lines, it prints a line such as this one. The sphere lies broken on the floor, and its surface has gained the faces of the cracks:
Frame 48: lowest point -0.02, 3788 facesThe file drop_sphere.ma and its folder deformable_cache_drop_sphere are beside the script, ready to render.
A few things to know when you script the plugin:
- The actions work on the selection. Each create action selects what it made, so the next action applies to it. Bake Simulation, Free Simulation and Simulate Frame Range are the exceptions: they act on every Deformable Scene.
- The tools compute as Maya asks for them. In
mayapyand a batch render, they run at once, on the main thread. In Maya’s window they run in the background;cmds.deformableJobs(finish=True)waits for them all. - A saved file needs no update. The plugin stores the tool outputs in the file. A script that opens a saved file can simulate or render right away, as in the commands above.
- A script bakes over a bake. Bake Simulation asks before it overwrites a bake only in Maya’s window. Another
file’s bake, such as that of
shot.mabesideshot.mb, it bakes over only withoverwrite=True.
Read the simulation from a script
Maya evaluates only what something asks for. In Maya’s window, the viewport asks for what it shows; in mayapy,
nothing does. So a script that steps the time must also read the Deformable Scene’s simulatedFrame on every frame,
or the frames it skips are never simulated:
for frame in range(1, 49):
cmds.currentTime(frame)
cmds.getAttr("deformableSceneShape1.simulatedFrame")simulatedFrame is the frame the scene shows: the frame it simulated, replayed or read from its bake. Read it after
setting the time, before you read an object’s outputs.
The actions as Python functions
Every menu item and shelf button runs an action of the deformable_maya Python package, which the module puts on
Maya’s Python path. Run one by its key:
from deformable_maya import commands
commands.run("deformableCreatePrimitiveObject", primitive="sphere")
commands.run("deformableSetType", type="kinematic")commands.run(key, **flags) takes the flags by their camelCase names, as below; a flag you leave out takes its
default. Each action is also a function of a module of deformable_maya.actions, which takes the flags in snake_case,
such as deformable_maya.actions.create.create_primitive_object(primitive="sphere"). commands.actions() gives
every action of the menus by its key.
An action works on the selection, as the menu item does, and is one undo step. When the selection does not fit, it
prints a warning that says what to select, such as Deformable: Select one or more deformable objects, changes
nothing and returns None. Any other failure raises an exception, after it took back what the action did.
| Key | Menu item | Flags |
|---|---|---|
deformable |
Deformable Scene > Create Scene, Create New Scene | new: True to create another Deformable Scene |
deformable |
Deformable Object > Create Primitive Object | primitive: cube, sphere, cylinder, cone, pyramid or platonic |
deformable |
Deformable Object > Create Object from Polygon Mesh | maximum, quality, maximum, anisotropy, anisotropy |
deformable |
Deformable Object > Create Object with Autocage | scale, target, maximum, breakable |
deformable |
Deformable Object > Create Bare Object | source: polygon, polygon, triangle, tetrahedral or non; thickness; direction: both, up or down; span |
deformable |
Deformable Object > Create Autocage Mesh | |
deformable |
Deformable Object > Add Surface Mesh to Object | breakable |
deformable |
Deformable Object > Use Tetrahedral Mesh as Surface Mesh | |
deformable |
Deformable Object > Create Splinters from Image | image, such as "rough_ or "Custom"; image; allow |
deformable |
Deformable Object > Import Splinter Mesh | mesh, such as "brick_; mesh, an OBJ file |
deformable |
Deformable Object > Add Splinters to Object | |
deformable |
Deformable Object > Add Glue Region | |
deformable |
Deformable Object > Add New Region | type: passive, material or density; preset for a material region |
deformable |
Deformable Object > Make Mesh into Region | type: passive, glue, material or density; preset for a material region |
deformable |
Deformable Object > Apply Field to Object | |
deformable |
Deformable Object > Verify Mesh | angle, gap, planar, check, uv, same, convex, closed, self: skip, per or full |
deformable |
Deformable Object > Check Co-located Vertices | |
deformable |
Edit Deformable > Make Breakable, Make Unbreakable | breakable: True or False |
deformable |
Edit Deformable > Make Dynamic, Make Kinematic | type: dynamic or kinematic |
deformable |
Edit Deformable > Enable, Disable | enabled: True or False |
deformable |
Edit Deformable > Wait on Update, Don’t Wait on Update | wait: True or False |
deformable |
Edit Deformable > Update Now | |
deformable |
Edit Deformable > Duplicate Object | |
deformable |
Edit Deformable > Move to Scene | |
deformable |
Edit Deformable > Disassemble Object, Detach | component: "" for the whole object, surface, splinters or fields |
deformable |
Edit Deformable > Delete, Deformable Scene > Delete Scene | |
deformable |
Edit Deformable > Delete History | |
deformable |
Edit Deformable > Refresh Surface Mesh | |
deformable |
Edit Deformable > Assign Inner Material | |
deformable |
Edit Deformable > Show Shape | shape: surface, input, cage, driven, simulated, splinters or regions |
deformable |
Edit Deformable > Hide Shape | shape, as Show Shape |
deformable |
Edit Deformable > Paint Driven Vertices | |
deformable |
Edit Deformable > Select, Deformable Material > Select Material Node | type: scene, object or material |
deformable |
Edit Deformable > Intersecting Objects > Find Intersecting Objects | |
deformable |
Edit Deformable > Intersecting Objects > Keep Intersecting Objects in Selection | |
deformable |
Deformable Material > Assign Material Preset | preset, such as "rubber" |
deformable |
Deformable Material > Assign Material from Active | |
deformable |
Deformable Scene > Simulate Frame Range | |
deformable |
Deformable Scene > Bake Simulation | overwrite: True to skip the question in Maya’s window and bake over another file’s bake |
deformable |
Deformable Scene > Free Simulation | |
deformable |
Deformable Scene > Extract Output Shapes | |
deformable |
Deformable Scene > Preferences…, Deformable Help > License… | |
deformable |
Deformable Help > User Guide | |
deformable |
Deformable Help > Scripting Reference | |
deformable |
Deformable Help > Copy Support Info | |
deformable |
Deformable Help > About Deformable |
The create actions return the transforms they made, Extract Output Shapes the meshes it made, Simulate Frame Range and Bake Simulation whether every frame ran, and Free Simulation and Delete how many objects they took.
Runtime commands
The plugin also adds five Maya commands, for MEL and maya.cmds. The actions use them; scripts need them for what the
actions do not do, such as waiting for the tools or reading a bake. None of them is undoable, except
deformableLoadSplinterImage and deformableAssignMaterialPreset, which change a node.
deformableJobs
The tool jobs: Triangulate, Tetrahedralize, Autocage and Prepare computing in the background.
| Flag | Short | Argument | What it does |
|---|---|---|---|
-list |
-l |
Returns the running jobs, oldest first, each as its label and running time, such as Tetrahedralize (p. |
|
-cancel |
-c |
Cancels every job. Returns the names of their nodes, which show Cancelled. | |
-finish |
-f |
Brings every tool node up to date: computes each, waits for every job and applies its result, until nothing changes, so a chain of tools computes through. | |
-apply |
-a |
Applies the jobs that finished, as Maya’s window does every tenth of a second. | |
-update |
-u |
Computes the tool nodes named after the flags, or every tool node, once, even those set to Wait or cancelled. As Update Now. | |
-asynchronous |
-as |
on or off |
Runs the jobs in the background, as Maya’s window does, or at once, as mayapy does. With -query, returns the setting. |
-waiting |
-w |
With -query: whether a finished job waits to be applied. |
cmds.deformableJobs(finish=True)
cmds.deformableJobs("pSphere1_deformableTetrahedralize", update=True)deformableMessages
The messages the nodes queue: each new error or warning of a node, and each new message of a scene. The plugin shows
them in the Script Editor and on the Command Line; mayapy and a batch render print them as they happen.
| Flag | Short | Argument | What it does |
|---|---|---|---|
-take |
-t |
Returns the messages queued, oldest first, as a flat list of level and text, such as ["WARNING", "Deformable: deformable, and empties the queue. |
|
-playback |
-p |
on or off |
Tells the nodes a playback runs: while it does, each message is queued once, however often the playback loops. |
deformableBake
A Deformable Scene’s frame cache and disk bake. Every flag but -frameCacheLimit takes the scene, its transform or its
shape, with -scene. Bake with the Bake Simulation action, which writes the record that lets the bake play after
a reopen; the -begin and -finish flags it uses write no record.
| Flag | Short | Argument | What it does |
|---|---|---|---|
-scene |
-sc |
scene | The Deformable Scene. |
-begin |
-bg |
folder | Starts writing a bake into the folder: the frame after the start frame builds the simulation anew, and each frame it steps is written. |
-range |
-rk |
text | With -begin: the key of the inputs over the range, which the bake keeps in its index. |
-owner |
-ow |
file path | With -begin: the absolute path of the scene file that bakes it, which the bake keeps in its index with its path from the bake folder, so another file that bakes to the same folder leaves the bake alone. |
-finish |
-fi |
Ends writing the bake. Returns whether a bake was written. | |
-free |
-fr |
Frees the simulation, the frames kept and the bake played or written, and deletes the bake files in -folder. |
|
-folder |
-fo |
folder | With -free or -enable: the bake folder. |
-frames |
-fm |
Returns the frames of the bake being written, else of the bake that plays. | |
-enable |
-enb |
on or off |
Plays the bake in -folder, or the last one begun or played, or stops playing it. |
-range |
-rg |
on or off |
Tells the scene that Simulate Frame Range steps the frames, which prints its own lines. |
-playing |
-pl |
Returns the folder of the bake the scene plays, empty for none. | |
-world |
-wf |
Returns the frame the scene’s simulation stands at, nothing without one. | |
-render |
-rw |
Returns what a render of the frame the scene stands at would say: that it shows objects without the simulation. Empty when the frame shows them simulated or baked. | |
-frame |
-fcl |
bytes | Sets the memory every Deformable Scene keeps its frames in, now and for scenes made later, as Frame Cache Limit does. |
cmds.deformableBake(scene="deformableScene1", playing=True)
cmds.deformableBake(frameCacheLimit=4 * 1024**3)deformableLoadSplinterImage
Reads an image with Maya’s own image readers, any format Maya reads, into a Deformable Splinter, which traces it when its Image Library is Custom. Returns the image’s width and height. Undoable. It refuses a node whose image or file name is connected or locked.
| Flag | Short | Argument | What it does |
|---|---|---|---|
-node |
-n |
node | The Deformable Splinter. |
-file |
-f |
path | The image file, which becomes the node’s Image File too. Without it, the node’s Image File is read again, as Reload in the Attribute Editor does. |
cmds.deformableLoadSplinterImage(node="splinters1_deformableSplinter", file="/projects/shot/cracks.png")deformableAssignMaterialPreset
Gives Deformable Material nodes a preset, its values and its Preset together, in one undoable step, or copies
another material’s preset and values. It works on the materials named after the flags, or on the selected ones, and
returns the materials it wrote. It refuses a node that is no Deformable Material and a value that is connected or
locked. The Attribute Editor’s Preset menu runs it. To give a preset to deformable objects or material regions, use
the deformableAssignMaterialPreset action, which finds their materials.
| Flag | Short | Argument | What it does |
|---|---|---|---|
-preset |
-p |
name | The preset, such as rubber, or Custom, which only marks the values as set by hand. |
-source |
-s |
material | The Deformable Material to copy the preset and the values from. |
cmds.deformableAssignMaterialPreset("pSphere1_deformableMaterial", preset="glass")Fracture points
Each deformable object gives one point on each inner face that opens at a frame, on its deformableObject:
outputFracturePositions, outputFractureNormals and outputFractureTetrahedrons. The points are in the object’s
space, and exist only on the frame their faces open. See
The outputs of a deformable object.
To emit dust where an object cracks, emit an nParticle on each point, with an expression that runs on every frame. For
the sphere ball of the script above:
-
Make an nParticle object with nothing selected: in the Script Editor, on a MEL tab, run
nParticle -name dust;. -
Choose Windows > Animation Editors > Expression Editor, name the expression
dustFromCracks, paste this, and click Create:// Emits one dust particle on each face of ball that cracks open at this frame. float $points[] = `getAttr ball_deformableObject.outputFracturePositions`; float $m[] = `getAttr ball.worldMatrix`; for ($i = 0; $i < size($points); $i += 4) { float $x = $points[$i]; float $y = $points[$i + 1]; float $z = $points[$i + 2]; emit -object dust -position ($x * $m[0] + $y * $m[4] + $z * $m[8] + $m[12]) ($x * $m[1] + $y * $m[5] + $z * $m[9] + $m[13]) ($x * $m[2] + $y * $m[6] + $z * $m[10] + $m[14]); } -
Go to the start frame and play.
Each point comes as four numbers, x y z w, and the expression moves it into world space with the object’s world
matrix. The dust appears where the sphere cracks, at about frame 17, and the nucleus solver moves it on from there. A
replayed or baked frame gives the same points, so the dust comes back each time you play from the start frame, and a
render of the whole range from the start frame emits it too. Give dust the look you want in its Attribute Editor, such
as a short Lifespan and a cloud Particle Render Type.
To read the points from Python at the frame shown, in world space:
from maya import cmds
from maya.api import OpenMaya
matrix = OpenMaya.MMatrix(cmds.getAttr("ball.worldMatrix[0]"))
positions = cmds.getAttr("ball_deformableObject.outputFracturePositions") or []
points = [OpenMaya.MPoint(position) * matrix for position in positions]