GitHub  •  LinkedIn  •  X  •  Discord

Telekinesis Lens

Telekinesis Lens is a local visual dataset studio for inspecting, annotating, and exporting image and video datasets. Its React interface runs in the browser while a local FastAPI service reads and updates files on your computer.

It includes:

• YOLO, COCO, image-folder, and video workspaces
• Box, polygon, and mask annotation tools with undo and redo
• AI click-to-mask initialization and video mask propagation
• Dataset filtering, class management, review, and export
• CPU and NVIDIA GPU tracker runtime options
• A compiled GUI included in every Python wheel and source distribution

Lens installs both the telekinesis-ai SDK and the telekinesis-trackers package as direct dependencies. CPU tracking is the default; the gpu installation flag adds the NVIDIA runtime dependencies.

Release Model

Telekinesis Lens is currently in active development (pre-1.0). Features and APIs may evolve between minor releases. Install or upgrade to the newest compatible version for the latest fixes and capabilities.

Installation

1. Create an isolated environment. We recommend Miniconda.

2. Create a Python 3.11 or 3.12 environment:

   conda create -n telekinesis-lens python=3.11
   

3. Activate it:

   conda activate telekinesis-lens
   

4. Install Lens. The standard installation includes the CPU tracker runtime:

   pip install telekinesis-lens
   

   For NVIDIA GPU tracking, add the gpu flag:

   pip install "telekinesis-lens[gpu]"
   

   The GPU extra installs telekinesis-trackers[gpu], including ONNX Runtime GPU, CUDA 12 user-space libraries, cuDNN, and CuPy. It requires a compatible NVIDIA driver. Because Trackers includes CPU ONNX Runtime in its base package, finish the switch by replacing that runtime:

   pip uninstall -y onnxruntime onnxruntime-gpu
   pip install "onnxruntime-gpu[cuda,cudnn]>=1.21,<1.27" "cupy-cuda12x[ctk]>=14,<15"
   

   This follows the current Trackers installation contract and prevents the CPU and GPU distributions from sharing the same Python module directory.

The published distribution is named telekinesis-lens; its Python module is telekinesis.lens. The compiled interface is included, so users do not need Node.js or npm.

Example

Start Lens:

lens

Open a dataset folder or video immediately:

lens "/path/to/dataset-or-video"

Or launch it from Python:

from telekinesis import lens

lens.launch("/path/to/dataset-or-video")

Lens opens at http://127.0.0.1:5151. Files remain local and annotations are saved back to the selected workspace.

Workflows

• Browse and filter samples by status, split, and annotated class.
• Draw and edit boxes, polygons, and masks with explicit saving.
• Refine masks using positive/negative AI clicks and the mask eraser.
• Propagate masks through video frames and cancel propagation when needed.
• Review AI predictions before accepting them as annotations.
• Export YOLO detection/segmentation or COCO datasets.

Resources

• Contributor setup and releases: DEVELOPMENT.md
• Release notes: CHANGELOG.md
• Telekinesis documentation: docs.telekinesis.ai
• Telekinesis examples: telekinesis-examples

Support

For issues and questions:

• Open an issue in the Lens repository.
• Contact the Telekinesis team at support@telekinesis.ai or on Discord.