Illusion - Tuning a Randomizer Tree in Blender

Goal: Load a spec YAML, edit the randomizer tree visually, preview the result, and export the tuned spec.

Level: Intermediate

Time: ~20 minutes

Background

Tuning a randomizer tree by editing YAML and re-running a generation job is slow: you change a number, wait for a render, and guess from the output whether the change was right.

The telekinesis-illusion Blender extension closes that loop. It provides a node-graph editor for randomizer trees and runs the engine in-process inside Blender, so Load Assets builds a real BinPickingWorker and the preview uses the same code path the production pipeline does. You see the randomized scene as you edit it, then export the result as a spec YAML the Worker consumes.

In this tutorial you will load an existing spec, re-randomize the scene, edit the tree, preview your changes, and save the tuned spec.

Complete Install telekinesis-illusion first, including the extension and its Asset Directory setting. The extension ships no 3D assets, so without that setting the material list stays empty and Load Assets fails on missing model paths.

Use a dedicated .blend file

Load Assets resets the entire .blend file – BlenderProc's reset clears every object, mesh, and material, and cannot be scoped to one scene. Work in an empty or dedicated file.

1. Open the Randomizer Tree Editor

Switch any editor to Illusion Randomizer Tree – it is listed directly in the editor-type menu, under General – and click New.

Press N and open the Illusion tab to get the tool panel, which holds every button used below.

2. Load a Spec YAML

Click Load YAML and pick an existing spec, for example one of the configs/*.yaml files in your telekinesis-illusion checkout. The nodes appear as a graph: assets, randomizers, physics, and the worker output settings.

Arrange Nodes lays the graph out in execution-order columns, which is the quickest way to read an unfamiliar spec.

You can also start from scratch and build a tree with Shift+A.

3. Load the Assets

Click Load Assets. This imports the models referenced by the spec and builds the worker behind the preview.

It is the slow step, and it is only needed when the assets themselves change – not after every edit.

4. Change the Scene

Click Change Scene to re-randomize everything: which objects are visible, their materials, the background, and the camera. This is exactly what a generation run does for each image, so it is the honest preview of what your dataset will look like.

To judge framing and lighting:

• Camera View / Free View (or Numpad 0) toggles the camera framing.
• Set viewport shading to Rendered for real materials and HDRI lighting.
• Camera poses are keyframed one per view – use the View slider or scrub the timeline to step through them.

5. Edit the Randomizer Tree

Select a node and edit its fields. Show Sampling Volumes draws wireframe overlays for the selected node, which is the fastest way to see what a number actually controls:

Node selected	Overlay
Camera Pose Randomizer	Sampling volume or shell radii, point of interest, and one frustum per sampled view
Pose Randomizer	Grid cell markers, or the drop-region box for the random strategy
Asset	Bounding box of each visible instance of that asset
Instance Count Randomizer	The instances its targets actually produced
Material Randomizer	The objects it will re-material
Physics Simulator	Only the objects with Active In Simulation ticked

Not every edit is applied by the same button. Pose and camera settings show up on the next Preview Scene; anything that changes composition or appearance needs a Change Scene:

Setting	Applied by
Pose Randomizer (any field), Camera Pose Randomizer	Preview Scene
Asset – Scale	Preview Scene
Instance Count Randomizer (min/max per role)	Change Scene
Material Randomizer, Background Randomizer	Change Scene
Physics Simulator	Either – it runs after randomizing in both modes
Asset – model path, per-asset counts, role, preprocess	Load Assets

When you edit a deferred setting, Change Scene turns red and the panel says what is waiting on it, so a setting that has not taken effect yet is visibly deferred rather than apparently broken.

6. Preview Your Changes

Click Preview Scene to re-sample object poses and camera views only, keeping the materials, background, and object selection from the last Change Scene. This is what you want while iterating on layout and framing: the scene does not change underneath you between attempts.

For continuous feedback, tick Live Preview and drag a field – live updates use the same geometry-only path, so the same deferred settings still need a Change Scene.

7. Export the Tuned Spec

Click Save YAML to write the tree back out as a spec.

Before running it, check the values the worker is sensitive to:

• Base Output Directory must be a real path – some checked-in specs carry an absolute path from whichever machine last edited them.
• Shard Size must be at least 2, and Num Images must be at least the shard size, or the run produces no images.

Then generate the dataset outside Blender, in the telekinesis-illusion environment:

conda activate telekinesis-illusion
python examples/generate_synthetic_data_with_bin_picking_worker.py \
  --spec-file /path/to/spec.yaml --no-preview

When the Scene Ignores a Setting

Set Log Level to Info and open Window ▸ Toggle System Console – the system console, not Blender's Python console, since the engine logs to stdout.

At Info level the randomizers report every placement decision. Giving up on <name>, hiding... is the one to look for: an object that cannot be placed without collision is reverted and hidden, so a too-dense grid or too-tight drop region shows up as objects that seem to ignore your settings rather than as an error.

Each randomize also prints the pose-sampling configuration the worker actually holds. If a value you changed is missing from that line, the edit did not reach the spec. If it is there but the scene ignores it, the cause is usually downstream – most often physics settling, which re-orients everything it simulates and washes out a sampled Z rotation. Untick the Physics Simulator node to see the sampled poses on their own.

Some fields are preview-only for now

BinPickingWorker currently derives a few values itself rather than reading them from the spec: Instance Count Randomizer nodes, Target Objects on all randomizers, Material Randomizer types, and Background Randomizer categories. They round-trip through YAML correctly and their overlays show what they would affect, but the generated dataset ignores them. Node links are likewise decorative today – execution order is fixed in the worker.

Summary

You have:

• Loaded an existing spec YAML into the node-graph editor and laid it out in execution order.
• Re-randomized a full scene, and iterated on poses and framing with the geometry-only preview.
• Used sampling-volume overlays to see what each node controls.
• Exported the tuned tree back to a spec YAML ready for a generation run.

Next Steps

• Run the exported spec end to end in Generating a Dataset with a Worker.
• Look up any field you changed in the spec YAML reference.
• Read what each node does in the Randomizer Nodes reference.