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 examples default to CUDA (--device CUDA); pass --device CPU to select CPU rendering:

Run the exmamples:

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.

The checkout includes the original example assets. 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]"

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

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}
}