Metadata-Version: 2.4
Name: batesposture
Version: 1.1.1
Summary: Discreet system-tray posture monitor powered by MediaPipe and OpenCV.
Project-URL: Homepage, https://wtbates99.github.io/batesposture/
Project-URL: Repository, https://github.com/wtbates99/batesposture
Project-URL: Bug Tracker, https://github.com/wtbates99/batesposture/issues
License: MIT
License-File: LICENSE
Keywords: mediapipe,opencv,posture,system-tray,webcam
Classifier: Environment :: X11 Applications :: Qt
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: mediapipe>=0.10.21
Requires-Dist: numpy>=1.26.4
Requires-Dist: opencv-python>=4.11.0.86
Requires-Dist: plyer>=2.1.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: pyqt6>=6.9.1
Description-Content-Type: text/markdown

# BatesPosture

A real-time posture monitoring application that uses computer vision to analyse your posture through your webcam. Integrated into the system tray, it provides instant visual feedback, configurable alerts, and session analytics to help maintain proper ergonomics while working.

## Features

- Real-time posture scoring (0–100) with colour-coded tray icon
- System tray integration — always visible, never in your way
- Live dashboard with sparkline history and session statistics (avg, min, max, best streak)
- Persistent dashboard history — sparkline survives closing and reopening the window
- Configurable tracking intervals (continuous or scheduled) with break reminders
- Desktop notifications with cooldown throttling and focus-mode suppression
- Onboarding wizard with 6-second calibration to capture your personal baseline
- SQLite database logging with CSV export
- Rotating log files for persistent diagnostics (`~/.batesposture_logs/app.log`)
- Adaptive resolution — automatically drops to 640×480 on low-end hardware when enabled
- GPU acceleration toggle (forces MediaPipe complexity-2 model)
- All processing happens locally — no video or pose data leaves your machine

## Technical Stack

- **MediaPipe** — pose landmark detection (33 body landmarks, configurable model complexity)
- **OpenCV** — frame capture, CLAHE enhancement, landmark visualisation
- **PyQt6** — system tray, dashboard window, settings dialog, onboarding wizard
- **NumPy** — vectorised posture metric computation and rolling score buffer
- **SQLite3** (WAL mode) — persistent storage for scores, landmarks, and dashboard history
- **psutil** — hardware detection for adaptive resolution
- Python `threading.Lock` — thread-safe score buffering between camera and UI threads
- `logging.handlers.RotatingFileHandler` — 5 MB / 3-backup rotating log files

## Install

BatesPosture is distributed via **[PyPI](https://pypi.org/project/batesposture/)** — no unsigned binaries, no SmartScreen warnings.

```bash
pip install batesposture
batesposture
```

Or run without installing:

```bash
pip install batesposture
python -m batesposture
```

**Requirements:** Python 3.10+, a webcam, and Windows 10/11 or a modern Linux desktop (Ubuntu 20.04+, Fedora 35+, etc.).

**Linux / GNOME:** may need the [AppIndicator extension](https://extensions.gnome.org/extension/615/appindicator-support/) for system-tray support.

## Development Setup

This project uses [uv](https://github.com/astral-sh/uv) for dependency management.

```bash
# Install all dependencies (including dev/test tools)
uv sync --all-groups

# Run the application
uv run python -m batesposture

# Run tests
uv run python -m pytest
```

### Releasing a new version

1. Bump the version in `pyproject.toml`
2. Commit and push, then tag the commit:
   ```bash
   git tag v1.0.0
   git push origin v1.0.0
   ```
3. GitHub Actions runs tests, builds the wheel, and publishes to PyPI automatically.
4. A GitHub Release is created with install instructions.

> **PyPI setup:** the first publish requires creating a [trusted publisher](https://docs.pypi.org/trusted-publishers/) on PyPI pointing to this repo with environment name `pypi` and workflow `build.yml`.

## Usage

1. Launch the app — the tray icon appears (grey circle when idle)
2. Click the tray icon → **Start Tracking** (or `Ctrl+Shift+T`)
3. The icon updates in real time: red (poor) → amber (fair) → green (excellent)
4. Open the dashboard (`Ctrl+Shift+D`) to see live video, sparkline, and session stats
5. Configure alerts, intervals, and thresholds via **Settings** (`Ctrl+,`)
6. Export session data to CSV via **Export Data as CSV…**

## Configuration via Environment Variables

All settings can be overridden at startup with the prefix `POSTURE_<SECTION>_<FIELD>`:

```bash
# Run at 15 FPS on a slower machine
POSTURE_RUNTIME_DEFAULT_FPS=15 batesposture

# Automatically drop to 640×480 on low-end hardware
POSTURE_RUNTIME_ADAPTIVE_RESOLUTION=true batesposture

# Enable GPU-optimised MediaPipe model
POSTURE_ML_ENABLE_GPU=true batesposture

# Silence notifications
POSTURE_RUNTIME_NOTIFICATIONS_ENABLED=false batesposture

# Use a different camera
POSTURE_RUNTIME_DEFAULT_CAMERA_ID=1 batesposture
```

See `batesposture/services/settings_service.py` → `KEY_TO_SECTION_FIELD` for a full list of available keys.

## Default Tuning Values

| Constant | Default | Description |
|---|---|---|
| `POOR_POSTURE_THRESHOLD_DEFAULT` | 60 | Score below which a notification fires |
| `SCORE_THRESHOLD_DEFAULT` | 65 | Score used to track good-posture streaks |
| `DEFAULT_POSTURE_WEIGHTS` | `(0.2, 0.2, 0.15, 0.15, 0.15, 0.1, 0.05)` | Per-metric contribution to overall score |
| `BREAK_REMINDER_MINUTES` | 50 | Minutes of continuous tracking before a break prompt |
| `CALIBRATION_DURATION_SECONDS` | 6 | Baseline sample length during onboarding |
| `CALIBRATION_TIMEOUT_MARGIN_SECONDS` | 6 | Extra seconds before the calibration thread is cancelled |

## Privacy

All video processing runs locally. Pose landmarks and scores are only written to the local SQLite database when database logging is explicitly enabled. No data is transmitted externally.

## Troubleshooting

**Camera not detected**
- Try a different camera index: `POSTURE_RUNTIME_DEFAULT_CAMERA_ID=1`

**Calibration fails during onboarding**
- Ensure adequate lighting and that your head and shoulders are fully in frame
- Move closer to the camera and try again

**Performance issues / lag**
- Enable adaptive resolution: `POSTURE_RUNTIME_ADAPTIVE_RESOLUTION=true`
- Reduce frame rate: `POSTURE_RUNTIME_DEFAULT_FPS=15`
- Lower model complexity in **Settings → Advanced → Model complexity** (0 is fastest)

**GPU acceleration not working**
- The `enable_gpu` toggle forces MediaPipe complexity-2 and relies on the device's ONNX Runtime or CUDA support. Falls back to CPU silently if unavailable.

**Log files**
- `~/.batesposture_logs/app.log` (rotates at 5 MB, keeps 3 backups)

## Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.
