README.md

metadata

title: Advanced Real-Time Faint Detection on Video
emoji: 🌍
colorFrom: pink
colorTo: pink
sdk: gradio
sdk_version: 5.25.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: Faint Detection on Video with Customizable Alert Zone

Advanced Real-Time Faint Detection on Video with User-Defined Alert Zone

This repository contains a Hugging Face Spaces demo for detecting faint (or post‑faint) scenarios in video files using an integrated deep learning model for person detection, tracking, and pose estimation. The application is built in Python and leverages:

• OpenCV for video processing.
• Yolov11spose for unified person detection, multi‑object tracking, and pose estimation.
• PyTorch as the deep learning backend.
• Gradio for a user‑friendly web interface.

Features

• Video File Input:
  Upload an MP4 video file to the demo.

• User-Defined Alert Zone:
  The demo includes an interactive interface that allows the user to:

  • Load the first frame of a video into an image editor.
  • Draw an alert zone on the first frame using red strokes.
  • Preview the extracted alert zone polygon (displayed in red) before processing.
  • The faint detection is applied only for persons whose mid-hip keypoint falls within the defined alert zone.

• Integrated Detection, Tracking, and Pose Estimation:
  The system uses a single unified Yolov11spose model, which returns both bounding boxes and pose keypoints with an integrated tracker.

  • The model detects persons and tracks them across frames.
  • It extracts keypoints that can be used to verify if a person is lying down, thus improving the accuracy of faint detection.

• Velocity-Based Motionlessness Detection:
  The system computes the displacement of each person’s bottom-center point over time. If the movement stays below a set threshold for a defined duration, the person is considered static.

• Timing and Thresholding:
  The demo tracks how long a person remains static (via integrated pose and velocity analysis). If this duration exceeds a user‑defined threshold (between 1 and 600 seconds), the person is flagged as "FAINTED."

• Annotated Output:
  The processed video displays:

  • Annotated bounding boxes and labels (e.g., Upright, Static, FAINTED).
  • Red polygon for the alert zone.
  • Red dot = mid-hip reference (used for alert zone inclusion).
  • Blue dot = bottom-center point (used for velocity calculation).

How It Works

1. Alert Zone Setup:

   • Video Upload & Frame Extraction:
     Upload your video file and click Load First Frame to Editor to extract the initial frame.
   • Defining the Alert Zone:
     Use the image editor to draw your alert zone on the first frame using red strokes.
   • Alert Zone Preview:
     Click Preview Alert Zone to extract and visualize the polygon approximation of your alert zone.

2. Unified Detection and Tracking:

   • Yolov11spose with Integrated Tracker and Pose Estimation:
     The unified model processes each frame to detect persons, track them across frames, and extract keypoints that reflect the persons’ posture.

3. Faint Detection Logic:

   • Pose-Based Analysis:
     The model’s keypoint outputs are used to assess if the person is lying down by comparing the vertical positions of the shoulders and hips.
   • Velocity Analysis:
     The displacement of the person’s bottom-center is computed over consecutive frames. If the movement is below a preset velocity threshold, the individual is considered motionless.
   • Alert Zone Confinement:
     A person is analyzed only if their mid-hip keypoint is within the drawn alert zone polygon.

4. Output Generation:

   • Processed frames are annotated with the person’s status (Upright, Static, FAINTED) and stitched back into a video.
   • Mid-hip and bottom-center points are drawn for visual inspection.
   • The annotated output video is displayed through the Gradio interface.

Running on Hugging Face Spaces

This demo is optimized for Hugging Face Spaces and supports GPU acceleration during video processing to maximize performance.

To Deploy:

1. Fork or clone this repository on Hugging Face Spaces.
2. All dependencies listed in requirements.txt will be installed automatically.
3. Launch the Space and upload a video file to test the demo.

Running Locally

1. Clone the Repository:

   git clone https://github.com/your_username/advanced-faint-detection.git
   cd advanced-faint-detection