You are viewing the documentation for Deformable v0.8.0, 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. - Undo needs a step. An operator called from a script saves no undo step unless the call passes
Trueafter the execution context, as inbpy.ops.object.deformable_detach_surface_mesh("EXEC_DEFAULT", True). To let the user undo what a script did, pass it, or callbpy.ops.ed.undo_push(message="My script")after the change. Without a step, an undo does not take the change back.
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_ |
|
| Detach Surface Mesh | deformable_ |
|
| Detach Splinters | 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.