You are viewing the documentation for Deformable v0.3.1, an older version. Read the latest, v0.9.0
Blender Plugin
Command line and scripting
Install, simulate and render from a terminal, and build Deformable scenes with Python scripts in Blender.
On this page
Everything in the Object > Deformable menu is a Blender operator, so you can run it from a Python script, and Blender can simulate and render a scene without opening its window. This page is for pipeline work: render farms, batch jobs and scene-building scripts.
Install from a terminal
Install and enable the plugin in your user Blender, with the .zip file you downloaded, such as
deformable-blender-v0.1.0-linux-x64.zip:
blender --command extension install-file -r user_default -e deformable-blender-v0.1.0-linux-x64.zipRestart Blender after you reinstall the plugin: a running Blender keeps the version it loaded.
Render from a terminal
Background mode (-b) runs Blender without a window. The plugin simulates each frame as the render reaches it, and
a baked scene renders its bake:
blender -b scene.blend -aRender the whole range from the start frame. To render part of the range from a saved bake, see Render from the command line.
The plugin prints what it does, each line starting with Deformable:, so a render log shows it:
| Line | When |
|---|---|
Deformable: Scene: frame 12 of 48 in 2.41 s · Deformable Scene step 2.30 s, mean 2.35 s |
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: Scene: 47 frames simulated in 113.20 s |
The simulation reached its end frame. |
Deformable: Scene: Frame 10 renders Cube without the simulation: render from frame 1, or bake first |
The render starts where the simulation cannot reach, and the named objects are not baked. |
Deformable: Sphere: Deformable Tetrahedralize: <message> |
A node shows a new error or warning. |
Deformable: Scene: <message> |
The status bar would show a new message, such as Play from the start frame. See Troubleshooting. |
Deformable: Created Sphere: 212 tetrahedrons; scene total 218 |
A create action’s object was counted, once its tools finished. |
Deformable: Scene: Left out of the simulation: Bolt (its tetrahedrons are too small). See Troubleshooting. |
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
--python-expr runs a line of Python after the file loads. This command plays every frame from the start frame to
the end frame, as Simulate Frame Range does:
blender -b scene.blend --python-expr "import bpy; bpy.ops.object.deformable_simulate_frame_range()"The 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: Scene: frame 1 of 48 in 0.04 s · less than a minute left
Deformable: Scene: frame 2 of 48 in 2.61 s · about 1 min left
…
Deformable: Scene: frame 48 of 48 in 2.38 s
Deformable: Scene: Simulated frames 1–48 in 1 min 55 sIt stops where the status bar would show a message that stops the simulation, prints where and why, such as
Deformable: Scene: Stopped at frame 1: No Deformable Scene: choose Object > Deformable > Create Scene, and returns
{'CANCELLED'}. Advice, such as objects that no Deformable Scene takes, is printed and the range goes on.
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 modifier setting, simulates 48 frames, prints what the sphere looks like at the end,
and saves the file. Save it as drop_sphere.py and run it in background mode:
blender -b --python drop_sphere.pyimport os
import bpy
def set_input(blender_object, name, value):
"""Set the Deformable modifier setting with this name, as on the modifier panel."""
for modifier in blender_object.modifiers:
if modifier.type != "NODES" or modifier.node_group is None:
continue
for item in modifier.node_group.interface.items_tree:
if item.item_type == "SOCKET" and item.in_out == "INPUT" and item.name == name:
getattr(modifier.properties.inputs, item.identifier).value = value
return
raise KeyError(f"{blender_object.name} has no setting {name}")
# Start from an empty scene, 48 frames long.
bpy.ops.wm.read_homefile(use_empty=True)
scene = bpy.context.scene
scene.frame_end = 48
# A UV sphere 3 m up, in an autocage, made of brick.
bpy.ops.mesh.primitive_uv_sphere_add(location=(0.0, 0.0, 3.0))
sphere = bpy.context.active_object
bpy.ops.object.deformable_create_object_with_autocage()
bpy.ops.object.deformable_assign_material_preset(preset="brick")
# A 20 m floor, extruded 0.2 m down, that does not move, rendered with the plane's materials.
bpy.ops.mesh.primitive_plane_add(size=20.0)
bpy.ops.object.deformable_create_bare_object(source="NON_CLOSED_POLYGON_MESH", thickness=0.2, direction="Down")
bpy.ops.object.deformable_use_tetrahedral_mesh_as_surface_mesh()
bpy.ops.object.deformable_set_type(type="Kinematic")
# The first create action added the Deformable Scene object.
set_input(bpy.data.objects["Deformable Scene"], "Substeps", 10)
# Let the plugin run its tools, then simulate every frame.
for _ in range(10):
for blender_object in scene.objects:
blender_object.update_tag()
bpy.context.view_layer.update()
scene.frame_set(scene.frame_start)
bpy.ops.object.deformable_simulate_frame_range()
evaluated = sphere.evaluated_get(bpy.context.evaluated_depsgraph_get())
surface = evaluated.to_mesh()
lowest = min((evaluated.matrix_world @ vertex.co).z for vertex in surface.vertices)
print(f"Frame {scene.frame_current}: lowest point {lowest:.2f} m, {len(surface.polygons)} faces")
evaluated.to_mesh_clear()
bpy.ops.wm.save_as_mainfile(filepath=os.path.abspath("drop_sphere.blend"))After the plugin’s line for each frame, 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 m, 4495 facesA 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 and Free Simulation are the exceptions: they act on every deformable object of the scene.
- The tools run after a change. In Blender’s window, the plugin runs its tools in the background once your script returns, so build the scene in a script, then play. In background mode, it runs them only when Blender updates the scene, which is why the script tags every object and updates the view layer a few times before it simulates.
- A saved file needs no update. The plugin stores every tool output in the file. A script that opens a saved file can simulate or render right away, as in the commands above.
- Settings live on the modifier.
set_inputfinds a setting by the name the modifier panel shows. A name used by two panels, such as Run, sets the first one.
The actions as operators
Every action is in bpy.ops.object. Its options match the fields of the Adjust Last Operation panel.
| Action | Operator | Options |
|---|---|---|
| Create Scene | deformable_ |
|
| Create Primitive Object | deformable_ |
primitive: CUBE, SPHERE, CYLINDER, CONE, PYRAMID or ICOSPHERE |
| Create Object from Polygon Mesh | deformable_ |
maximum_, quality, maximum_, anisotropy_, anisotropy_ |
| Create Object with Autocage | deformable_ |
scale_, target_, maximum_, breakable |
| Create Bare Object | deformable_ |
source: POLYGON_, POLYGON_, TRIANGLE_, TETRAHEDRAL_ or NON_; thickness; direction: Both, Up or Down; span_ |
| Create Autocage Mesh | deformable_ |
|
| Add Surface Mesh to Object | deformable_ |
breakable |
| Use Tetrahedral Mesh as Surface Mesh | deformable_ |
|
| Create Splinters from Image | deformable_ |
image_, image_, allow_ |
| Import Splinter Mesh | deformable_ |
mesh_ |
| Add Splinters to Object | deformable_ |
|
| Make Breakable, Make Unbreakable | deformable_ |
breakable: True or False |
| Make Dynamic, Make Kinematic | deformable_ |
type: Dynamic or Kinematic |
| Enable, Disable | deformable_ |
enabled: True or False |
| Wait on Update, Don’t Wait on Update | deformable_ |
wait: True or False |
| Update Now | deformable_ |
|
| Duplicate Object | deformable_ |
|
| Assign Material Preset | deformable_ |
preset, such as "rubber" |
| Assign Material from Active | deformable_ |
|
| Add Glue Region | deformable_ |
|
| Add New Region | deformable_ |
kind: PASSIVE, MATERIAL or DENSITY; preset for a material region |
| Make Mesh into Region | deformable_ |
kind: PASSIVE, GLUE, MATERIAL or DENSITY; preset for a material region |
| Verify Mesh | deformable_ |
angle_, gap_, planar_, check_, uv_, same_, convex, closed_, self_: SKIP, PER_ or FULL |
| Check Co-located Vertices | deformable_ |
|
| Find Intersecting Objects | deformable_ |
|
| Keep Intersecting Objects in Selection | deformable_ |
|
| Simulate Frame Range | deformable_ |
|
| Bake Simulation | deformable_ |
|
| Free Simulation | deformable_ |
|
| Extract Output Shapes | deformable_ |
|
| Properties > Add Modifier > Deformable | deformable_ |
entry: the menu entry’s name, such as "Deformable Object (Autocage)" |
An action that cannot run with the current selection raises a RuntimeError that says what to select, such as
Select one or more deformable objects. One that refuses its input, such as a mesh that fails the check, reports a
warning and returns {'CANCELLED'}. Most actions report what they did, such as Made 2 objects Kinematic, and
Blender prints a report in the terminal as Info: Made 2 objects Kinematic.