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.

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:

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

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:

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:

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/.

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:

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.

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:

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 and PyPI upload credentials.