telekinesis-illusion

telekinesis-illusion is a python package for procedurally generating physically simulated synthetic datasets for training computer vision models in robotics applications.

Open source under GPL-3.0-or-later.

Full documentation: Telekinesis Agentic OS: Illusion.

Installation

1. Create the enviornment;

   conda create -n telekinesis-illusion python=3.11
   

   conda activate telekinesis-illusion
   

2. Install the package:

   Via pip: The simplest way to install telekinesis-illusion.

   python -m pip install telekinesis-illusion
   

   Via GitHub: Alternatively, if you need to make changes to telekinesis-illusion or use a different branch.

   git clone https://github.com/telekinesis-ai/telekinesis-illusion.git
   

   cd telekinesis-illusion
   

   python -m pip install -e .
   

Tested configurations

The following configurations have been manually tested with telekinesis-illusion 0.2.2 and Python 3.11. This list records known-working setups; other configurations may also work.

Quickstart

The example scripts are run from the Git checkout and are not included in the package installed from PyPI. Follow the GitHub installation above, then run these commands from the repository root. The examples rely on the checkout's assets/ directory, and the worker example also uses configs/.

The examples default to CUDA (--device CUDA); pass --device CPU to select CPU rendering:

python examples/quickstart_flying_things.py --preview

python examples/quickstart_parts_in_bin.py --preview

python examples/generate_synthetic_data_with_bin_picking_worker.py --spec_file configs/example_bin_picking_gearwheel_2.yaml --preview

The bin-picking worker defaults to this example YAML with preview disabled. Use --spec_file PATH to select another YAML and --preview or --no-preview to control the viewer.

For another asset tree, pass asset_dir to Scene, or set metadata.asset_directory in the worker YAML. Relative YAML asset paths resolve against that YAML file. Interactive FiftyOne previews require the optional viewer dependencies:

python -m pip install "telekinesis-illusion[viewer]"

Optional dependencies

Optional dependencies are grouped by use case and are not required for basic dataset generation.

Install an extra with the published package:

python -m pip install "telekinesis-illusion[viewer]"

For an editable source checkout, include the extra in the local install:

python -m pip install -e ".[dev]"

Multiple extras can be installed together:

python -m pip install -e ".[dev,docs,viewer]"
python -m pip install -e ".[dev,docs,viewer]"

The quoted commands work in Windows PowerShell and Command Prompt, as well as Linux shells such as Bash.

Tested configurations

The following configurations have been manually tested with. This list records known-working setups; other configurations may also work.

Documentation

Find the documentation for Illusion at: Telekinesis Agentic OS: Illusion.

Citation

@software{telekinesis_illusion,
  author = {Telekinesis GmbH},
  title  = {Telekinesis-Illusion: Synthetic Data Generation for Robotics},
  year   = {2026},
  url    = {https://gitlab.com/telekinesis/illusion},
  note   = {GPL-3.0-or-later}
}