Telekinesis Agentic Skill Library

Appearance

Install telekinesis-illusion ​

telekinesis-illusion is the synthetic data generation engine of the Data Engine. It renders physically simulated, pixel-accurate datasets.

These instructions install version 0.3.2, the latest release and the version these docs cover. The package includes the bpy 4.5 runtime, so no separate Blender installation is required. Example models, materials and HDRIs are downloaded automatically the first time you use them.

Create a Python environment ​

telekinesis-illusion requires Python 3.11. A Miniconda environment is one way to create it:

bash
conda create -n telekinesis-illusion python=3.11
conda activate telekinesis-illusion

Install the package ​

bash
pip install telekinesis-illusion==0.3.2

That is all you need. The example models, materials and HDRIs are not part of the wheel; they download automatically the first time a script asks for them, so there is no repository to clone.

Verify the install ​

Check the installed version:

bash
pip show telekinesis-illusion | head -2          # Version: 0.3.2

Then run the official synthetic data example from the telekinesis-examples repository, as a small CPU render without the interactive viewer:

bash
git clone https://github.com/telekinesis-ai/telekinesis-examples.git
cd telekinesis-examples
python examples/dataengine/synthetic_data_generation/quickstart_object_based_data_generation.py --no-preview --device CPU --num-images 2 --resolution 128 --samples 4

The first run downloads the example assets (about 180 MB) to ~/.cache/telekinesis/telekinesis-illusion/; later runs reuse them. The example then writes two JPEG images and coco_annotations.json under output/synthetic_data_<timestamp>_<id>/ and logs Generation complete: 2 images from 1 samples.

The same folder holds quickstart_parts_in_bin.py (physics) and generate_synthetic_data_with_bin_picking_worker.py (a complete worker run from bin_picking_example.yaml).

Install the optional FiftyOne viewer only when you need interactive dataset inspection:

bash
pip install "telekinesis-illusion[viewer]==0.3.2"

Rendering hardware

Rendering defaults to CUDA. Pass device="CPU" to RenderConfig (or --device CPU to the example scripts) when no NVIDIA GPU is available, or use "METAL" on Apple silicon, "HIP" on AMD, and "OPTIX" on NVIDIA RTX cards. No GPU is required for the verification run above.

Generate your first dataset
Build a randomizer one node at a time and render a labeled COCO dataset of parts in mid-air.
Open tutorial →

Legacy: Blender Extension ​

Deprecated: works only with telekinesis-illusion 0.1.1

The Blender extension is deprecated. It currently only works with the previously released telekinesis-illusion 0.1.1 (bundled with the extension, on the deprecated BlenderProc dependency), not with 0.3.2. An updated extension is coming soon. Until then, use the legacy package from the extension's 0.1.1 release on GitHub. You do not need it to generate data with 0.3.2.

The extension provides a node-graph editor for randomizer trees, with a live preview of the randomized scene. It bundles its own Python dependencies, including telekinesis-illusion 0.1.1, so no pip install is needed inside Blender.

Install the extension ​

  1. Download the telekinesis_illusion_randomizer-<version>.zip asset from the extension's v0.1.1 release, not from a newer release page.
  2. 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….
  3. Open a new editor and set its type to Illusion Randomizer Tree (under General), then click New. Press N and 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 an assets/ folder containing models/, hdris/, and materials/, such as the one in a telekinesis-illusion checkout.

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:

python
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.

Next Steps ​

Synthetic Data Generation

The randomizer tree, the generation loop, and the dataset formats telekinesis-illusion writes.

Explore →

Config Based Synthetic Dataset Generation

Run a complete bin-picking dataset from one YAML file: shards, merging, and a YOLO or COCO export.

Explore →

Legacy: Randomizer Tuning in Blender

Deprecated extension, works only with telekinesis-illusion 0.1.1. An update is coming soon.

Explore →

Support ​

Join Discord

Ask questions, share what you're building, and get help from the community.

Join →

Report a bug?

Found a bug or something not working as expected? Raise an issue on our GitHub.

Raise an issue →