The Problem

Care facilities and home‑care providers need an on‑device method to flag genuine falls of seniors in real time while ignoring normal activities (sitting, dressing, sleeping). Existing solutions either require cloud inference, generate many false alarms, or cannot operate when the person is partially hidden behind furniture.

What This Does

The repository implements a lightweight, edge‑compatible fall‑detection pipeline built on YOLO‑v8 pose and a custom kinematic state‑machine. Video frames (live webcam, file, or synthetic demo) are fed to the pose model (yolov8n-pose.pt). Joint coordinates are post‑processed by core/kinematics.py and core/occlusion.py to reconstruct missing limbs, then evaluated by core/state_machine.py to emit a fall alert only when velocity or angular‑change thresholds are crossed.

Key files:

FileResponsibility
main.pyCLI entry point; parses menu choice and launches the selected runner (run.py).
run.pyCentral loop that loads video source, calls core/detector.py for each frame, and visualises results via core/visualizer.py.
core/detector.pyWraps the YOLO‑v8 pose model, returns raw keypoints.
core/kinematics.pyComputes joint velocities, angles, and applies anthropometric constraints.
core/occlusion.pyImputes hidden joints using bone‑length ratios and temporal extrapolation.
core/state_machine.pyImplements the 4‑tier fall decision logic (velocity > 0.7 m/s, Δθ > 35°/s, occlusion handling, resting‑state filter).
core/tracker.pyMaintains per‑person identity across frames (used by the visualizer).
core/visualizer.pyDraws skeletons, HUD telemetry, and prints alert messages.
fall_detection_all_in_one.pyConvenience script that runs the full pipeline without the interactive menu.
test_generator.pyGenerates synthetic occlusion scenarios used by menu option 3.

How It Is Wired

  1. Start – Execution begins in run.py (invoked by python run.py or via the menu in main.py).
  2. Source Selection – run.py opens a video capture (cv2.VideoCapture) based on the user’s choice (webcam, file list, or synthetic generator).
  3. Frame Loop – For each frame: core/detector.detect(frame) loads yolov8n-pose.pt (via PyTorch) and returns a dict of joint coordinates. core/occlusion.impute(keypoints) fills missing joints using the bone‑ratio model. core/kinematics.compute(keypoints) calculates per‑joint velocities and torso angle rates. core/state_machine.update(kinematics, occlusion_flags) evaluates the fall criteria; on a positive decision it sets a global fall_detected flag. * core/visualizer.render(frame, keypoints, fall_detected) draws the skeleton, velocity vectors, and prints [ALERT] FALL DETECTED when appropriate.
  4. Output – The loop writes annotated frames to a window; no external I/O (database, network) is performed. The only side‑effect is console logging and optional video saving (not currently exposed).

The state machine is the widest‑impact component: it consumes outputs from both kinematics and occlusion, and its decision propagates to the visualizer and any downstream alerting system. Changing its thresholds directly affects false‑positive/negative rates. All other modules are leaf nodes with single‑direction calls, making them relatively low‑risk to modify.

No cyclic imports are present; the call graph is a simple linear flow from run.py → detector → occlusion → kinematics → state machine → visualizer.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Real-Time-Person-Elderly-Fall-Detection-System
cd Real-Time-Person-Elderly-Fall-Detection-System

# Install Python dependencies
python -m venv .venv && source .venv/bin/activate   # optional but recommended
pip install -r requirements.txt

# Run the interactive menu (Windows double‑click run.bat works as well)
python main.py          # shows the 4‑option menu
# or directly launch the default pipeline
python run.py

No additional configuration files, environment variables, or API keys are required. The only external asset is the pre‑trained pose model yolov8n-pose.pt, which is already committed.

Real‑World Use

A senior‑living facility could deploy the script on a modest edge PC attached to a hallway camera. The device runs python run.py --source /dev/video0 (the --source flag is implicit in the menu) and streams alerts to a local MQTT broker by extending core/state_machine.update to publish when fall_detected becomes true.

# Example extension in core/state_machine.py
if self.fall_detected:
    mqtt_client.publish("facility/fall", payload=json.dumps({"timestamp": time.time()}))

Code Health & Issues

  • Medium – No CI/CD pipeline – repository lacks .github/, Makefile, or other automation configs.
  • Medium – No LICENSE file – legal reuse and distribution rights are unclear.
  • Low – No lockfile – requirements.txt is present, but no requirements-lock.txt or pipfile.lock, risking non‑reproducible environments.
  • Low – Limited test coverage – only test_generator.py exists; no unit tests for detector, kinematics, or state machine.

No static analysis warnings were detected beyond the above SDLC observations.

The Bottom Line

The project delivers a self‑contained, CPU‑friendly fall‑detection pipeline with clear modular separation (detector, occlusion handling, kinematics, state machine, visualizer). It is ready for rapid prototyping or edge deployment, but it lacks formal testing, CI, and licensing. Engineers planning production use should add tests, lock dependencies, and define a license before integration.