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
Split the Blender UI horizontally by hovering your mouse over the top-left corner until the cursor turns into a crosshair, then click and drag downward.
In the newly split panel, set the editor type to Illusion Randomizer Tree – it is listed directly in the editor-type menu in the top-left corner of the panel's header, under General – and click New.
Open the Illusion tab in the sidebar to get the tool panel, which holds every button used below. If the sidebar is not visible, press N.
Missing asset directory
If you see the warning "No asset directory set", make sure to set the asset directory as described in step 5 of Install telekinesis-illusion.
2. Load a Spec YAML and the Assets
Click Load YAML and pick an existing spec, for example one of the configs/*.yaml files in your telekinesis-illusion checkout. In this tutorial we load the default configs/example_bin_picking_gearwheel_2.yaml.
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.
Then 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.
Load Assets resets the .blend file
As noted above, this clears every object, mesh, and material in the file. Make sure you are working in an empty or dedicated .blend file before clicking it.
3. 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.
Set the viewport shading to Rendered for real materials and HDRI lighting by clicking the rightmost button with a sphere in the top-right corner of the 3D viewport.
Toggle the camera framing by clicking Camera View to see a preview of what your dataset will look like for this randomizer tree.
Click Change Scene again to re-randomize everything and preview a different potential scene from the future dataset.
4. Edit the Randomizer Tree and Preview Your Changes
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.
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.
The following video shows a simple modification of the randomizer tree where the scale of the gears is changed from 1.0 to 2.0 and the physics simulator is deactivated. Both take effect on Preview Scene, so no full Change Scene is needed to see them.
5. 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-previewWhen 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.