Real-Time-Person-Elderly-Fall-Detection-System README

The project's README from github.com/AwaisShah75/Real-Time-Person-Elderly-Fall-Detection-System. As one markdown file: README.md.

🛡️ Real-Time Person & Elderly Fall Detection System

Advanced Occlusion Resilience, Kinematic State Machine & Edge AI Architecture

An enterprise-grade, edge-compatible AI computer vision system designed to detect accidental falls in real-time under severe visual occlusions (behind furniture, tables, beds, couches) while completely eliminating false positives from daily activities such as sitting down, tying shoelaces, or sleeping in bed.

🌟 Key Highlights

🚀 Quickstart Guide (1 Command to Run)

You only need ONE command:

python run.py

*(Or on Windows, simply double-click run.bat)*

🎮 Interactive Menu Options:

======================================================================
  🛡️  AI PERSON & ELDERLY FALL DETECTION SYSTEM
  Advanced Occlusion Resilience & Kinematic Tracking
======================================================================
  Select an input option:
   [1] 📹 Live Webcam (Real-time monitoring)
   [2] 📁 Custom Video File (Auto-detects videos + Drag & Drop)
   [3] 🧪 Synthetic Occlusion Fall Demo (Built-in test)
   [4] ❌ Exit
======================================================================

📦 Included Benchmark Video Suite (sample_videos/)

The repository includes real-world benchmark fall test videos:

# Video File Scenario & Purpose Expected Result
1 sample_videos/standing_fall_1.mp4 🏃 Sudden collapse fall from standing Instant [ALERT] FALL DETECTED
2 sample_videos/standing_fall_2.mp4 🍌 Slip & backward fall from standing Instant [ALERT] FALL DETECTED
3 sample_videos/sitting_to_fall.mp4 🪑 Senior citizen falling off chair Instant [ALERT] FALL DETECTED
4 sample_videos/bed_rollout_fall.mp4 🛏️ Roll-out fall from bed onto floor Instant [ALERT] FALL DETECTED
5 sample_videos/normal_activity_no_fall.mp4 🚶 Walking, sitting & sleeping (ADL) MONITORING (RESTING) (Zero False Alarms)

🧠 Technical Architecture & Biomechanical Pipeline

  ┌─────────────────┐     ┌──────────────────────┐     ┌────────────────────────┐
  │ Video / Webcam  │ ──> │ YOLOv8-Pose Backbone │ ──> │  Occlusion Resilience  │
  │     Stream      │     │  Keypoint Extractor  │     │   & Bone Imputation    │
  └─────────────────┘     └──────────────────────┘     └────────────────────────┘
                                                                    │
  ┌─────────────────┐     ┌──────────────────────┐                  ▼
  │ HUD Visualizer  │ <── │ Multi-Stage Fall FSM │ <── ┌────────────────────────┐
  │  & Alert Engine │     │  State Transitions   │     │  Kinematic Extractor   │
  └─────────────────┘     └──────────────────────┘     │ (v_y, Angle, ω, Energy)│
                                                       └────────────────────────┘

1. Biomechanical Features

2. State Machine Logic Flow

 [ MONITORING ] ──( v_y > 0.7 h/s OR ω > 35°/s )──> [ FALL_DETECTED ]
       ▲                                                     │
       │                                            ( > 1.5s Stillness )
  ( Stands Up )                                              │
       │                                                     ▼
 [ MONITORING ] <──────( Upright Motion )─────── [ CONFIRMED_FALL ]

📁 Repository File Structure

d:\A New Fall Detecion Sytem\
├── run.bat                          # One-click Windows desktop launcher
├── run.py                           # Interactive CLI runner with continuous loop
├── fall_detection_all_in_one.py     # Standalone all-in-one pipeline (Zero sub-dependencies)
├── core/
│   ├── detector.py                  # YOLOv8-Pose wrapper & keypoint extractor
│   ├── tracker.py                   # Multi-person temporal tracklet manager
│   ├── occlusion.py                 # Occlusion engine, Kalman extrapolation & bone imputation
│   ├── kinematics.py                # Biomechanical kinematic feature engine
│   ├── state_machine.py             # Multi-stage Fall State Machine
│   └── visualizer.py                # Telemetry HUD visualizer & alert banners
├── sample_videos/                   # Benchmark fall test dataset
│   ├── standing_fall_1.mp4          # Sudden collapse fall
│   ├── standing_fall_2.mp4          # Slip and fall
│   ├── sitting_to_fall.mp4          # Chair fall
│   ├── bed_rollout_fall.mp4         # Bed roll-out fall
│   └── normal_activity_no_fall.mp4  # Normal ADL baseline (zero false alarm test)
├── test_generator.py                # Synthetic occlusion test scenario generator
├── requirements.txt                 # Clean dependency manifest
├── FALL_DETECTION_SYSTEM_DESIGN.md  # Comprehensive research & mathematical design spec
└── README.md                        # Documentation & quickstart guide

🛠️ Advanced CLI Usage (Direct Bypass)

If you prefer direct command-line execution without the interactive menu:

# Run on webcam (device 0)
python fall_detection_all_in_one.py --source 0 --show

# Run on a specific video file
python fall_detection_all_in_one.py --source sample_videos/standing_fall_1.mp4 --show --save output_result.mp4

# Run synthetic occlusion demo
python fall_detection_all_in_one.py --source demo --show

📜 Scientific Reference & Design Document

For full mathematical formulations, biomechanical formulas, Kalman filter state equations, and multi-view homography matrices, refer to: 👉 FALL_DETECTION_SYSTEM_DESIGN.md

Real-Time-Person-Elderly-Fall-Detection-System (AwaisShah75/Real-Time-Person-Elderly-Fall-Detection-System)

pose-estimation
Searching Database…

275 ·GitHub
Real-Time-Person-Elderly-Fall-Detection-System
What is this?It's an edge AI computer vision system that detects falls in real time, especially for elderly people, even when partially hidden behind furniture, while avoiding false alarms from normal activities like sitting or sleeping.
Is this a trained model I need to set up myself, or a ready-to-run app?It is a ready-to-run Python application built around an already lightweight pose-estimation engine; no custom model training is required.
How do I get it running?Launch it with a single command, or on Windows just double-click run.bat, which opens an interactive menu letting you stream a webcam, feed in a custom video, or run a synthetic fall demo.
Does it tell a real fall apart from someone just lying down or sleeping?Yes, it has dedicated resting/sleeping rejection logic that keeps horizontal resting on a bed in a calm 'MONITORING (RESTING)' state instead of triggering an alarm, based on biomechanical signals like torso angle and descent velocity.
Does this only run on Windows?No, it is a Python script that runs cross-platform; Windows users just get an extra run.bat shortcut for convenience.
How does it keep tracking a fall when the person is hidden behind furniture?It uses a 4-tier occlusion resilience pipeline: kinematic bone-constraint imputation, temporal velocity extrapolation, furniture ROI tracking, and bone-length clamping to reconstruct and track the body even when knees or ankles are blocked from view.
What exactly triggers a fall alert?An alert fires instantly when the system measures a rapid vertical descent faster than 0.7 body-heights per second, or a sudden posture collapse where the torso angle changes more than 35 degrees per second.
What test videos come with the project?The samplevideos/ folder ships benchmark clips covering standing falls, a chair fall, a bed roll-out fall, and a normal-activity clip, used to verify correct alerts and zero false alarms.
Where can I read the full math behind it?The FALLDETECTIONSYSTEMDESIGN.md file in the repo documents the biomechanical formulas, Kalman filter state equations, and homography matrices used in the detection pipeline.
What are similar projects?X-AnyLabeling, avatarify-python, Deep-Live-Cam, facefusion, freemocap, itsgiving, mediapipe, openpose
Which topics is it in?surveillance, healthcare, health, webcam, pose-estimation, edge-ai, video-processing, real-time, artificial-intelligence, computer-vision, monitoring, terminal
Creator
AwaisShah75
Size
6 MB
Stars
275
Updated
CommitAug 18
Age
2mo
Commits · 90 Days