Metadata-Version: 2.4
Name: bbox-overlay
Version: 0.1.2
Summary: Simple screen overlay for drawing bounding boxes
Home-page: https://github.com/albertoburgosplaza/bbox-overlay
Author-email: Alberto Burgos Plaza <albertoburgosplaza@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/albertoburgosplaza/bbox-overlay
Project-URL: Issues, https://github.com/albertoburgosplaza/bbox-overlay/issues
Keywords: bbox,overlay,x11,tkinter
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# bbox-overlay

Minimal Python overlay to draw bounding boxes on top of the screen (Linux/X11).

## Requirements

- Linux/X11 (or WSLg/XWayland on Windows 11).
- Tkinter (e.g. `sudo apt-get install python3-tk` on Ubuntu).

## Install

### PyPI

```bash
python3 -m pip install bbox-overlay
```

### Editable (dev)

```bash
python3 -m pip install -e .[dev]
```

## Usage

```bash
bbox-overlay --boxes '[{"x":100,"y":100,"w":200,"h":150,"label":"cat"}]'
```

- Close with `Esc`, `Ctrl+C`, or any key in the console (when `--timeout` is omitted).
- Coordinates are pixel-based, origin at top-left.
- The overlay uses thin border windows per box to avoid fullscreen opacity on X11.
- Labels are optional and use the `label` field in each box object.
- Colors accept Tk names (`red`, `cyan`) or hex (`#RRGGBB`).

## Development

```bash
ruff check .
ruff format .
mypy bbox_overlay
pytest
```

## CLI options

```bash
bbox-overlay --help
```
