README

Presence

A gentle welfare monitoring system for elderly care. Uses a webcam and computer vision to keep an eye on someone — detecting their presence, tracking movement, spotting falls, and speaking up when something seems wrong.

Built for the situation where you want passive, non-intrusive monitoring of a loved one, with voice alerts that feel more like a caring companion than a surveillance system.

Features

Person detection — YOLOv8 identifies when someone is in frame
Movement tracking — frame differencing within the person's bounding box detects motion
Posture and fall detection — pose estimation (YOLOv8-pose) classifies standing, sitting, slumped, lying, and fallen postures
Verbal status updates — speaks contextual updates every 30 seconds ("Jon is resting", "Good morning Jon") via browser TTS or Python fallback
Stillness alerts — after 2 minutes without movement: "Hello Jon, are you ok?"
Fall alerts — 20-second confirmation window before alerting, to avoid false alarms
Gesture control — raise a hand for "yes/ready", cross arms for "no", wave both hands to recalibrate
Interactive calibration — voice-guided camera setup walks you through checking visibility from different positions in the room
Web dashboard — real-time status page with SSE, viewable from any device on the network
Adaptive voice output — uses browser speech synthesis when the dashboard is open, falls back to Python TTS (gTTS/pyttsx3) when it's not

Requirements

Python 3.10+
Webcam
NVIDIA GPU recommended (YOLO falls back to CPU but will be slow)

Installation

bash

git clone <repo-url>
cd presence
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

The YOLOv8 model weights (yolov8n.pt, yolov8n-pose.pt) are included in the repo.

Usage

bash

source venv/bin/activate
python -m src

This opens a local camera window and starts the web dashboard.

Controls

Key	Action
`q`	Quit
`d`	Dismiss alert and reset timer
`s`	Skip calibration (during setup)
`c`	Capture screenshot with captions

Web Dashboard

Available at http://localhost:5020 (auto-increments if the port is taken). Open it on a phone or tablet for remote monitoring. The dashboard also handles voice output — if a browser is connected, speech goes through it instead of the local machine.

Gestures

Gesture	Meaning
Raise one hand	Yes / Ready
Cross arms	No
Wave both hands above head	Recalibrate

Configuration

Edit the constants at the top of src/main.py:

python

VERBAL_UPDATE_INTERVAL = 30   # Seconds between spoken status updates
STILLNESS_ALERT = 120         # Seconds of no movement before "are you ok?"
FALL_ALERT_DELAY = 20         # Seconds to confirm a fall before alerting
PERSON_NAME = "Jon"           # Name used in spoken messages

How It Works

Detection — YOLOv8 runs at ~2 fps, finding the largest person in frame

Movement — the person's bounding box is cropped, converted to grayscale, blurred, and diffed against the previous frame. Pixel changes above a threshold count as movement

Posture — YOLOv8-pose extracts 17 keypoints. Torso angle, head position relative to shoulders, and hip-to-ankle distance determine posture. Falls back to bounding box aspect ratio when pose data is unavailable

State machine — transitions between away, moving, settling, resting, still, and alert states drive contextual verbal updates

Calibration — a guided setup walks the user through five positions (center, left, right, close, far) using voice prompts and gesture feedback, checking camera coverage

Dashboard — Flask serves the web UI, pushing state via Server-Sent Events. The browser speaks updates using the Web Speech API

Project Structure

shell

presence/
├── src/
│   ├── __main__.py    # Package entry point
│   ├── main.py        # Core loop, Flask app, verbal status generator
│   ├── detector.py    # Person detection (YOLOv8)
│   ├── movement.py    # Movement tracking via frame differencing
│   ├── posture.py     # Posture/fall detection (YOLOv8-pose + box fallback)
│   ├── gestures.py    # Gesture recognition from pose keypoints
│   └── setup.py       # Interactive camera calibration assistant
├── web/
│   ├── templates/
│   │   └── index.html
│   └── static/
│       ├── app.js     # Dashboard logic, SSE client, browser TTS
│       └── style.css
├── screenshots/       # Captured frames (press 'c' during monitoring)
├── yolov8n.pt         # YOLOv8 nano model weights
├── yolov8n-pose.pt    # YOLOv8 nano pose model weights
└── requirements.txt