LivePyxel

LivePyxel is a Python-based GUI for fast pixel annotation of images captured directly from a webcam feed. It’s designed to speed up dataset preparation for instance segmentation and other ML workflows.

Tutorials

• Getting started: https://ugarcil.github.io/LivePyxel/tutorials.html

Requirements

• Python: 3.9 – 3.12 recommended
• OS: Windows, macOS, or Linux
• Core deps (installed for you via pip unless using a conda env below):
  • PyQt5 (Qt5)
  • OpenCV (cv2)
  • NumPy

Tip: If you’re on Windows and prefer Conda, see the Conda section; Conda’s Qt/OpenCV packages are very reliable there.

Option A — Quick install from PyPI (recommended for users)

pip install --upgrade pip
pip install livepyxel

Run the app:

LivePyxel
# or
livepyxel
# or
python -m livepyxel

(Optional) Create a virtual environment first

Windows (PowerShell / cmd):

python -m venv .venv
.\.venv\Scripts\activate
pip install --upgrade pip
pip install livepyxel
LivePyxel

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install livepyxel
LivePyxel

Option B — Conda environments

You can use Conda to manage Python and heavy binary deps (Qt, OpenCV, NumPy), and then install LivePyxel from PyPI without re-installing those deps via pip.

1) End users (install the released package)

Run the file environment.yml at the repo root

This will create a new env called livepyxel-env, then run the app:

conda activate livepyxel
LivePyxel

Option C — From source with pip (no Conda)

For contributors who prefer pure pip/venv:

git clone https://github.com/UGarCil/LivePyxel.git
cd LivePyxel

python -m venv .venv
.\.venv\Scripts\activate   # Windows
# source .venv/bin/activate  # macOS/Linux

pip install --upgrade pip
pip install -e .            # editable install for development
LivePyxel

If you have defined dev extras in pyproject.toml, you can do:

pip install -e ".[dev]"

Troubleshooting

• Command not found: make sure your virtualenv/conda env is activated before running LivePyxel.
• Black window / missing icons: ensure you’re on the latest version and that package data is included (it is by default from PyPI). If running from source, verify livepyxel/icons/ exists.
• Import errors when running a module directly: launch via LivePyxel or python -m livepyxel (not by python livepyxel/imageAnnotator.py) so package-relative imports work.
• OpenCV or Qt conflicts in Conda: stick to the Conda packages (pyqt, opencv, numpy) and use pip ... --no-deps for LivePyxel.
• Python version: prefer Python 3.9–3.12. Python 3.13 support is pending upstream wheels for some deps.

License

This project is released under the MIT License. See LICENSE for details.

Links

• Docs & Tutorials: https://ugarcil.github.io/LivePyxel/
• Issues: https://github.com/UGarCil/LivePyxel/issues
• PyPI: https://pypi.org/project/livepyxel/