You are viewing the documentation for Deformable v0.3.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:

sh
blender --command extension install-file -r user_default -e deformable-blender-v0.1.0-linux-x64.zip

Restart 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:

sh
blender -b scene.blend -a

Render 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:

sh
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:

text
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 s

It 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:

sh
blender -b --python drop_sphere.py
python
import 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:

text
Frame 48: lowest point -0.02 m, 4495 faces

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 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_input finds 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_scene
Create Primitive Object deformable_create_primitive_object primitive: CUBE, SPHERE, CYLINDER, CONE, PYRAMID or ICOSPHERE
Create Object from Polygon Mesh deformable_create_object_from_polygon_mesh maximum_area, quality, maximum_edge_length, anisotropy_scale, anisotropy_direction
Create Object with Autocage deformable_create_object_with_autocage scale_gap, target_face_count, maximum_edge_length, breakable
Create Bare Object deformable_create_bare_object source: POLYGON_MESH, POLYGON_MESH_WITH_AUTOCAGE, TRIANGLE_MESH, TETRAHEDRAL_MESH or NON_CLOSED_POLYGON_MESH; thickness; direction: Both, Up or Down; span_layers
Create Autocage Mesh deformable_create_autocage_mesh
Add Surface Mesh to Object deformable_add_surface_mesh breakable
Use Tetrahedral Mesh as Surface Mesh deformable_use_tetrahedral_mesh_as_surface_mesh
Create Splinters from Image deformable_create_splinters_from_image image_library, image_file, allow_nonconvex
Import Splinter Mesh deformable_import_splinter_mesh mesh_name
Add Splinters to Object deformable_add_splinters_to_object
Make Breakable, Make Unbreakable deformable_set_breakable breakable: True or False
Make Dynamic, Make Kinematic deformable_set_type type: Dynamic or Kinematic
Enable, Disable deformable_set_enabled enabled: True or False
Wait on Update, Don’t Wait on Update deformable_set_wait wait: True or False
Update Now deformable_update_now
Duplicate Object deformable_duplicate_object
Assign Material Preset deformable_assign_material_preset preset, such as "rubber"
Assign Material from Active deformable_assign_material_from_active
Add Glue Region deformable_add_glue_region
Add New Region deformable_add_region kind: PASSIVE, MATERIAL or DENSITY; preset for a material region
Make Mesh into Region deformable_make_mesh_into_region kind: PASSIVE, GLUE, MATERIAL or DENSITY; preset for a material region
Verify Mesh deformable_verify_mesh angle_threshold_degrees, gap_threshold, planar_threshold, check_uv_consistency, uv_threshold, same_uv, convex, closed_boundary, self_intersection: SKIP, PER_ISLAND or FULL
Check Co-located Vertices deformable_check_co_located_vertices
Find Intersecting Objects deformable_find_intersecting_objects
Keep Intersecting Objects in Selection deformable_keep_intersecting_objects
Simulate Frame Range deformable_simulate_frame_range
Bake Simulation deformable_bake_simulation
Free Simulation deformable_free_simulation
Extract Output Shapes deformable_extract_output_shapes
Properties > Add Modifier > Deformable deformable_add_modifier 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.