Real-time, privacy-first Windows desktop app for webcam hand-landmark tracking and 0–10 finger counting.
HandCount AI detects your hand(s) through a webcam and counts fingers (0–10) in real time — fully offline, with no data ever leaving your PC. It uses MediaPipe for hand landmark detection and a custom geometry engine for accurate finger-state classification, wrapped in a clean PySide6 desktop UI.
- 🔒 100% local processing — no internet, no cloud, no telemetry
- ✋ Supports 1 or 2 hands with correct Left/Right handedness
- 🎯 Stabilized counting (no flicker) using majority-vote smoothing
- 🖥️ Simple dashboard, settings, and about pages
 |
 |
| Dashboard | Settings |
 |
 |
| About | Live Hand Tracking |
 |
 |
 |
 |
| Feature | Description |
|---|---|
| 🎥 Real-time webcam processing | Captures and processes video via OpenCV in a background thread |
| 🔢 Finger counting (0–10) | Counts fingers across one or two hands simultaneously |
| ✋ Single & dual-hand support | Tracks up to 2 hands at once (configurable up to 4) |
| 🖐️ Arbitrary finger combinations | Works for any combination of extended/folded fingers |
| Correctly labels hands even when the preview is mirrored | |
| 🦴 Landmark visualization | Draws hand skeleton overlay on the live feed |
| 📉 Temporal stabilization | Sliding-window majority voting removes count flicker |
| 🪞 Mirrored camera toggle | Flip the preview horizontally |
| 📊 FPS display | Live frame-rate overlay |
| ⚙️ Adjustable camera settings | Resolution, camera index, detection/tracking confidence |
| 🖥️ Dashboard / Settings / About pages | Full PySide6 desktop UI |
| 🌐 Offline functionality | No internet connection required — model runs locally |
| 🔐 Privacy-first | No video is recorded, stored, or uploaded |
| 🛠️ Error handling & recovery | Auto frame-read retries with user-friendly error popups |
Runtime
- Python
>=3.10(tested on 3.14.6) - PySide6
>=6.5.0— Qt6 GUI framework - OpenCV
opencv-python>=4.8.0— video capture & frame processing - MediaPipe
>=0.10.0— hand landmark detection (Tasks API) - NumPy
>=1.24.0— geometry & vector math
Development & Build
- pytest
>=7.4.0— testing (49 tests, all passing) - PyInstaller
>=6.0.0— packaging into a standalone Windows app - setuptools / wheel — build backend
Webcam Hardware
│ (OpenCV VideoCapture)
▼
CameraWorker (background thread)
│ (BGR → RGB conversion)
▼
MediaPipe Hand Detector
│ (21 3D joint landmarks per hand)
▼
Geometry Engine
│ (joint angles, distances, finger posture)
▼
Finger Counter
│ (0–10 total finger count)
▼
Stabilizer
│ (majority voting, removes flicker)
▼
Renderer + PySide6 UI
▼
Your Screen
HandCount-AI/
├── assets/
│ ├── icons/
│ └── models/ # bundled MediaPipe model (offline use)
├── docs/
│ ├── architecture.md
│ ├── privacy.md
│ └── testing.md
├── scripts/
│ └── build_windows.py # builds the standalone .exe
├── src/handcount/
│ ├── main.py
│ ├── app/ # app state & lifecycle
│ ├── camera/ # webcam capture worker
│ ├── services/ # config & logging
│ ├── ui/ # PySide6 pages & widgets
│ └── vision/ # detection, geometry, counting, stabilizer
├── tests/ # 49 automated tests
├── requirements.txt
├── pyproject.toml
└── LICENSE
The easiest way to install HandCount AI on Windows. No Python or coding knowledge required.
- Go to the Releases page.
- Download
HandCountAI-Setup-v1.0.0.exe. - Double-click the downloaded installer.
- Follow the installation wizard.
- Launch HandCount AI from the Start Menu or Desktop shortcut.
Note: The installer is currently not code-signed, so Windows may display a SmartScreen or Unknown Publisher warning.
Use HandCount AI without installing it.
- Go to the Releases page.
- Download
HandCountAI-v1.0.0-Windows-x64.zip. - Extract the entire ZIP to any folder.
- Open the extracted folder.
- Double-click
HandCountAI.exe.
⚠️ Important: Don't moveHandCountAI.exeout of its folder. It requires the bundled files and folders located alongside it to run correctly.
Run HandCount AI directly from the source code.
# 1. Clone the repository
git clone https://github.com/aryankumar-04/HandCount-AI.git
cd HandCount-AI
# 2. Create & activate a virtual environment (Windows PowerShell)
python -m venv venv
.\venv\Scripts\Activate.ps1
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run the app
python src/handcount/main.py
# 5. (Optional) Run in debug mode
python src/handcount/main.py --debug
# 6. Run the test suite
python -m pytest
---
## 🔒 Privacy & Security
| Question | Answer |
|---|---|
| Is video recorded to disk? | ❌ No |
| Are frames saved as images? | ❌ No |
| Is anything uploaded online? | ❌ No |
| Are cloud APIs used? | ❌ No |
| Is internet required to run? | ❌ No |
| Is telemetry/analytics collected? | ❌ No |
| Are user accounts required? | ❌ No |
Local files only:
- `%LOCALAPPDATA%\HandCountAI\config.json` — your settings
- `%LOCALAPPDATA%\HandCountAI\logs\handcount.log` — diagnostic logs (auto-redacted, rotates at 5MB)
---
## ✅ Testing
```text
49 passed in 7.49sCovers: hand geometry & finger-state math, finger counting accuracy, handedness stability, stabilization logic, state machine transitions, config persistence, and UI integration.
- OS: Windows 10 / 11 (64-bit)
- Python (dev only): 3.10 – 3.14
- Webcam: Any standard USB or built-in webcam
This project is licensed under the MIT License — see LICENSE for details.
Maintained by aryankumar-04
⭐ If you find this project useful, consider giving it a star!