bbox-overlay
Minimal Python overlay to draw bounding boxes on top of the screen (Linux/X11).
Highlights
- Lightweight X11 overlay using thin border windows.
- Optional labels and color control.
- Simple CLI with JSON input.
Requirements
- Linux/X11 (or WSLg/XWayland on Windows 11).
- Tkinter (e.g.
sudo apt-get install python3-tkon Ubuntu).
Install
PyPI
python3 -m pip install bbox-overlay
Editable (dev)
python3 -m pip install -e .[dev]
Usage
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--timeoutis 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
labelfield in each box object. - Colors accept Tk names (
red,cyan) or hex (#RRGGBB).
Development
ruff check .
ruff format .
mypy bbox_overlay
pytest
Project links
- Source: https://github.com/albertoburgosplaza/bbox-overlay
- Issues: https://github.com/albertoburgosplaza/bbox-overlay/issues
- Changelog: https://github.com/albertoburgosplaza/bbox-overlay/blob/main/CHANGELOG.md
CLI options
bbox-overlay --help
1 maintainer
Metadata
1 maintainer
Release files for bbox-overlay 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bbox_overlay-0.1.3.tar.gz | 7.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bbox_overlay-0.1.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 14.6 kB
Release files / bbox_overlay-0.1.3.tar.gz
| Download URL | bbox_overlay-0.1.3.tar.gz |
|---|---|
| Size | 7.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
39ce27815e12c2f564a4e12c018d15ffee09727d487e63c1fa8fcbbd335e1acf
|
|
BLAKE2b-256 checksum How to use checksums |
8c6a7bd081c6aacdc7ee1e78ec98dd98d19814902458487e62fd001307d818ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 20, 2025.
Transparency logRelease files / bbox_overlay-0.1.3-py3-none-any.whl
| Download URL | bbox_overlay-0.1.3-py3-none-any.whl |
|---|---|
| Size | 7.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
388986ced6d748a0ac03eb50e3f38e9fb43c111ccfd319e9a07a08160d8ced7a
|
|
BLAKE2b-256 checksum How to use checksums |
e649d52523bd426f402363aaed607462bf93f4ad8b90f30080c022bf4ebc302a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 20, 2025.
Transparency log
