Metadata-Version: 2.4
Name: telekinesis-lens
Version: 0.1.0
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.10
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.10
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-datatypes
Requires-Dist: telekinesis-dataengine
Requires-Dist: telekinesis-trackers[runtime]; python_version >= "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# Telekinesis Lens

Telekinesis Lens is a local React/TypeScript annotation studio backed by a Python FastAPI service. It opens YOLO/COCO datasets, image folders, and videos without uploading data.

## Installation

The Python distribution name is `telekinesis-lens`. It requires Python 3.10 or newer.

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

The command starts the local server and opens the GUI in your browser. PyPI wheels
and source distributions include the compiled interface: no Node.js, npm, or
manual build is needed after installation.

For editable development installs:

```bash
git clone git@gitlab.com:telekinesis/lens.git
cd lens
npm ci --prefix web
npm run build --prefix web
python -m pip install -e ".[dev]"
```

The standard install includes FastAPI, Uvicorn, NumPy, OpenCV, Pillow, PyYAML, Loguru, Telekinesis DataEngine, and Telekinesis datatypes. On Python 3.11 or newer it also includes Telekinesis trackers with runtime dependencies. Node.js is needed only to develop or rebuild the web UI.

## Run

```bash
telekinesis-lens
telekinesis-lens --dataset /path/to/dataset
telekinesis-lens --video /path/to/video.mp4
```

`python -m telekinesis.lens` is equivalent. Use `--no-browser` to start only the local server or `--port` to choose a port. Lens uses the web Studio exclusively; there is no separate Python desktop GUI.

From Python:

```python
import telekinesis.lens as lens

lens.launch("/path/to/dataset")
```

This runs the local service until interrupted and opens the UI in your browser.
If Lens is already running on the chosen port, it opens the dataset in that session.
Use `lens.launch(port=5152, open_browser=False)` to choose another port or skip opening the browser.

The browser handles the interface; the local service reads media and saves annotations
in place. On Windows, browsing uses the modern native Shell picker through generated
Windows SDK bindings, installed automatically by pip. Files are not uploaded or copied
just to open a workspace.

## Workflows

- Browse and filter samples by status, split, and annotated class.
- Draw/edit boxes, polygons, and masks in Studio with explicit save and revision checks.
- Select a mask and use Mask eraser (`E`) to remove areas with an adjustable radius; undo/redo works for each stroke.
- Run schema-backed Retina/Cornea operations on one image or a configurable preview batch, review predictions, then approve the same configuration for the full dataset.
- Propagate masks a chosen number of frames ahead with CUTIE, SAM3, or another registered compatible tracker. The count is limited to the remaining frames.
- Export YOLO detection/segmentation or COCO ZIPs. By default only classes containing annotations in the export scope are included; empty classes can be explicitly requested.

AI results remain reviewable predictions until saved. Optional integrations require their Python packages and model weights; missing models report an error instead of generating simulated results.

## Development

Run the API and Vite development server in separate terminals:

```bash
python -m telekinesis.lens --no-browser
cd web
npm run dev
```

Vite proxies `/api` to port 5151. Production assets are built into `src/telekinesis/lens/web/static/`.

```bash
python -m pytest
cd web
npm run build
npx playwright install chromium
npm test
```

The main implementation lives in `web/src/` (React), `src/telekinesis/lens/web/` (HTTP API/workspaces), and `src/telekinesis/lens/core/` (shared vision, tracking, geometry, and export bridges).

## Packaging and PyPI releases

Maintainers need Node.js 22 and Python 3.10+ to build a release:

```bash
npm ci --prefix web
npm run build --prefix web
python -m pip install build twine
python -m build
python -m twine check --strict dist/*
python scripts/check_release.py
```

Start with an empty `dist/` directory. The build refuses to produce a wheel or
source distribution without compiled UI assets. `python -m build` also rebuilds
the wheel from the source distribution, checking that it is self-contained.
Install the resulting wheel in a fresh virtual environment and run
`python scripts/smoke_install.py` to check the installed command and GUI assets.

The GitLab pipeline follows the Telekinesis `develop`/`main` release workflow.
Develop pushes publish a `.devN` package to GitLab. Main builds compile the UI,
validate that the wheel and source distribution contain the same compiled GUI,
publish to TestPyPI, and verify a clean install. Publishing the same build to
PyPI and GitLab is manual; successful approvals create the tag and bump the next
patch version on `develop`. See [DEVELOPMENT.md](DEVELOPMENT.md).

One-time GitLab setup:

1. Add your PyPI API token as a masked, protected CI/CD variable named
   `TWINE_PASSWORD`. The pipeline uses `__token__` as the username.
2. Protect the `v*` tag pattern and restrict release-tag creation to maintainers.
3. Ensure GitLab Docker runners are available for the pipeline.

To release, update `version` in `pyproject.toml` and `__version__` in
`src/telekinesis/lens/__init__.py`, commit the changes, and push a matching tag:

```bash
git tag v0.1.0
git push origin v0.1.0
```

The pipeline rejects tags that do not match the package version. Use a new version
for each release; PyPI does not allow replacing an uploaded distribution.

References: [GitLab CI configuration](https://docs.gitlab.com/ci/yaml/) and
[PyPI upload credentials](https://packaging.python.org/en/latest/specifications/pypirc/).
