Metadata-Version: 2.4
Name: telekinesis-illusion
Version: 0.2.3
Summary: A synthetic data generation package.
Author-email: Telekinesis <support@telekinesis.ai>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://telekinesis.ai
Project-URL: Documentation, https://docs.telekinesis.ai
Project-URL: Telekinesis Examples Repository, https://github.com/telekinesis-ai/telekinesis-examples
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: ~=3.11.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2,>=1.26
Requires-Dist: Pillow>=10
Requires-Dist: h5py>=3.10
Requires-Dist: loguru>=0.7.3
Requires-Dist: opencv-contrib-python-headless==4.11.0.86
Requires-Dist: tqdm>=4.67.1
Requires-Dist: pycocotools>=2.0.11
Requires-Dist: bpy==4.5.14
Requires-Dist: trimesh==4.12.2
Requires-Dist: imageio>=2.34.1
Requires-Dist: scikit-learn>=1.5.0
Requires-Dist: scikit-image>=0.23.2
Requires-Dist: rich>=13.7.1
Requires-Dist: pypng>=0.20220715.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.11
Requires-Dist: GitPython>=3.1
Provides-Extra: dev
Requires-Dist: ruff==0.15.9; extra == "dev"
Requires-Dist: pylint==4.0.5; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Provides-Extra: viewer
Requires-Dist: fiftyone==1.17.0; extra == "viewer"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocstrings[python]<1,>=0.25; extra == "docs"
Requires-Dist: mkdocs-awesome-pages-plugin<3,>=2; extra == "docs"
Dynamic: license-file

<div align="center">
  <p>
    <a href="https://gitlab.com/telekinesis/illusion">
      <img width="100%" src="media/images/telekinesis_banner.png" />
    </a>
  </p>

  <p align="center">
    <a href="https://docs.telekinesis.ai">
      <img src="https://img.shields.io/badge/docs-telekinesis.ai-blue" />
    </a>
    <a href="LICENSE">
      <img src="https://img.shields.io/badge/license-GPL--3.0--or--later-green" />
    </a>
  </p>

  <p>
    <a href="https://docs.telekinesis.ai/">Docs</a>
    &nbsp;•&nbsp;
    <a href="https://github.com/telekinesis-ai/telekinesis-illusion">GitHub</a>
    &nbsp;•&nbsp;
    <a href="https://discord.gg/S5v8bYAnc6">Discord</a>
    &nbsp;•&nbsp;
    <a href="https://www.linkedin.com/company/telekinesis-ai/">LinkedIn</a>
    &nbsp;•&nbsp;
    <a href="https://x.com/telekinesis_ai">X</a>
    &nbsp;•&nbsp;
    <a href="https://telekinesis.ai/">Website</a>
  </p>
</div>

#  `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](LICENSE).

Full documentation: [Telekinesis Agentic OS: Illusion](https://docs.telekinesis.ai/data-engine/synthetic-datasets/overview.html).

## Installation

1. Create the enviornment;
    ```bash
    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`.
    ```bash
    python -m pip install telekinesis-illusion
    ```
    Via GitHub: Alternatively, if you need to make changes to `telekinesis-illusion` or use a different branch.
    ```bash
    git clone https://github.com/telekinesis-ai/telekinesis-illusion.git
    ```

    ```bash
    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.

| Operating system | Hardware |
|---|---|
| Windows 11 Pro | NVIDIA GeForce RTX 3090 |
| Windows 11 Pro | NVIDIA GeForce RTX 2060 |
| macOS Tahoe 26.3 | Apple MacBook Pro with M5 Pro (CPU only) |
| Ubuntu 20.04.5 LTS | NVIDIA GeForce RTX 3080 |

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

Run the exmamples:
```bash
python examples/quickstart_flying_things.py --preview
```
```bash
python examples/quickstart_parts_in_bin.py --preview
```
```bash
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:
```bash
python -m pip install "telekinesis-illusion[viewer]"
```
### Optional dependencies

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

| Extra | Purpose |
|---|---|
| `viewer` | Installs FiftyOne for interactive dataset previews. Generation with `--no-preview` does not require it. |
| `dev` | Installs pytest, coverage, benchmarking, Ruff, and Pylint for developing and checking the package. |
| `docs` | Installs MkDocs and the plugins used to build the project documentation. |

Install an extra with the published package:

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

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

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

Multiple extras can be installed together:

```bash
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](https://docs.telekinesis.ai/).

## Citation

```bibtex
@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}
}
```
