Metadata-Version: 2.4
Name: telekinesis-lens
Version: 0.1.1
Summary: Detection dataset visualizer and AI-assisted video/image annotation studio for the Telekinesis SDK.
Author-email: Telekinesis <support@telekinesis.ai>
License: Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: loguru>=0.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn<1,>=0.30
Requires-Dist: pyyaml>=6.0
Requires-Dist: win32more-Microsoft.Windows.SDK.Win32Metadata<0.9,>=0.8.71.0.25; sys_platform == "win32"
Requires-Dist: telekinesis-ai
Requires-Dist: telekinesis-trackers
Provides-Extra: gpu
Requires-Dist: telekinesis-trackers[gpu]; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

<div align="center">
  <p>
    <a href="https://telekinesis.ai" target="_blank">
      <img
        width="100%"
        src="https://assets.telekinesis.ai/Telekinesis+Banner.png"
        alt="Telekinesis"
      >
    </a>
  </p>

  <br>

[![PyPI version](https://img.shields.io/pypi/v/telekinesis-lens)](https://pypi.org/project/telekinesis-lens/)
[![License](https://img.shields.io/pypi/l/telekinesis-lens)](https://pypi.org/project/telekinesis-lens/)
[![Python versions](https://img.shields.io/pypi/pyversions/telekinesis-lens)](https://pypi.org/project/telekinesis-lens/)

</div>

<p align="center">
  <a href="https://github.com/telekinesis-ai">GitHub</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://discord.gg/7NnQ3bQHqm">Discord</a>
</p>

# 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](https://docs.conda.io/en/latest/miniconda.html).

2. Create a Python 3.11 or 3.12 environment:

   ```bash
   conda create -n telekinesis-lens python=3.11
   ```

3. Activate it:

   ```bash
   conda activate telekinesis-lens
   ```

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

   ```bash
   pip install telekinesis-lens
   ```

   For NVIDIA GPU tracking, add the `gpu` flag:

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

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

```bash
lens
```

Open a dataset folder or video immediately:

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

Or launch it from Python:

```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](DEVELOPMENT.md)
- Release notes: [CHANGELOG.md](CHANGELOG.md)
- Telekinesis documentation: [docs.telekinesis.ai](https://docs.telekinesis.ai)
- Telekinesis examples: [telekinesis-examples](https://github.com/telekinesis-ai/telekinesis-examples)

## Support

For issues and questions:

- Open an issue in the Lens repository.
- Contact the Telekinesis team at
  [support@telekinesis.ai](mailto:support@telekinesis.ai) or on
  [Discord](https://discord.com/invite/7NnQ3bQHqm).
