Install telekinesis-illusion
telekinesis-illusion is the synthetic data generation engine of the Data Engine. It renders physically simulated, perfectly labeled datasets from a randomizer tree.
telekinesis-illusion is installed from source and ships with a small default asset collection, so the examples run without any downloads. It renders through a bundled, modified BlenderProc that uses the bpy package, so no separate Blender installation is required to generate data. Blender is only needed for the optional extension in steps 4 and 5, which lets you tune randomizer trees interactively.
Create a Python environment
telekinesis-illusion requires Python 3.11. A Miniconda environment is recommended – install Miniconda from docs.conda.io if you do not have it.
conda create -n telekinesis-illusion python=3.11
conda activate telekinesis-illusionClone the repository and install
telekinesis-illusion bundles a modified BlenderProc 2.8.0 that renders through an external bpy package (4.2.17 LTS). Install it first, then the package itself:
git clone https://github.com/telekinesis-ai/telekinesis-illusion.git
cd telekinesis-illusion
# Install the bundled BlenderProc
cd BlenderProc
pip install -e .
# Install telekinesis-illusion from the repository root
cd ..
pip install -e .Verify the install
Run one of the bundled examples:
python examples/quickstart_flying_things.pyThis generates a five-image COCO instance-segmentation dataset and opens it in the preview viewer. The first run takes a few minutes while the render kernels compile – Loading render kernels (may take a few minutes the first time) in the terminal is expected.
To use your own assets instead of the bundled ones, organize them in the same layout (models/, hdris/, materials/) and point telekinesis-illusion at that directory.
Install the Blender extension
The Blender extension provides a node-graph editor for randomizer trees, with a live preview of the randomized scene. It is optional: data generation works without it.
The extension bundles its own copies of telekinesis-illusion and BlenderProc as extension wheels, so no pip install is needed inside Blender.
- Download
telekinesis_illusion_randomizer-<version>.zipfrom the extension releases page. - Install it into Blender 4.2 LTS, either by dragging the zip onto an open Blender window, or via Edit ▸ Preferences ▸ Add-ons ▸ ▼ ▸ Install from Disk….
- Open a new editor and set its type to Illusion Randomizer Tree (under General), then click New. Press
Nand open the Illusion tab for the tool panel.
Point the extension at your assets
The extension ships no 3D assets. Set the asset directory to the assets/ folder of your telekinesis-illusion checkout – the one containing models/, hdris/, and materials/.
Open Edit ▸ Preferences ▸ Add-ons, find Illusion Randomizer Tree, and set Asset Directory.
The same setting can be applied from Blender's Python console, which is useful when the add-on entry is hard to locate in the preferences list:
import bpy
prefs = bpy.context.preferences.addons[
"bl_ext.user_default.telekinesis_illusion_randomizer"
].preferences
prefs.asset_directory = r"C:\path\to\telekinesis-illusion\assets"
bpy.ops.wm.save_userpref()Without this setting, the material list stays empty and loading assets fails on missing model paths.
Blender extension requirements
The extension currently supports Blender 4.2 LTS on Windows x64 only. Loading assets resets the Blender scene, so use a dedicated or empty .blend file for randomizer-tree work.
Rendering hardware
Rendering targets an NVIDIA GPU through OptiX. On Windows, disabling sleep and energy-saving modes noticeably speeds up long generation runs.
Next Steps
Synthetic Data Generation
The randomizer tree, the generation loop, and the dataset formats telekinesis-illusion writes.
Explore →Generating a Dataset with a Worker
Run a complete, spec-driven bin-picking dataset: shards, merging, and train/valid/test splits.
Explore →Tuning a Randomizer Tree in Blender
Load a spec, edit the tree with a live preview of the randomized scene, and export the tuned YAML.
Explore →