An intelligent fall detection system designed for edge devices, combining MediaPipe pose estimation with rule-based algorithms for real-time monitoring. Features hybrid processing architecture, lightweight video recording, and automated API integration.

• Real-time Fall Detection: Multi-algorithm fusion with 5 detection methods
• Edge-Optimized Architecture: Hybrid sync/async processing for resource-constrained devices
• Ultra-lightweight Video Recording: JPEG-based ring buffer with 95% memory savings
• Privacy Protection: Optional skeleton-only visualization mode
• Automated Event Management: Cooldown mechanism, retry logic, and dual API endpoints
• Production Ready: Docker containerization with resource limits and health checks
• Experiment Mode: Comprehensive data collection for model training and analysis

• Computer Vision: OpenCV 4.8.1 (headless build for edge devices)
• Pose Estimation: MediaPipe 0.10.21 (Lite model for low-latency inference)
• Async I/O: aiohttp 3.9+ (non-blocking video encoding and API uploads)
• Environment Management: uv (fast Python package installer)

• Angle-based Detection: Body tilt analysis using hip-to-shoulder vectors
• Height-based Detection: Vertical position tracking with dynamic thresholds
• Velocity-based Detection: Rapid movement analysis using temporal derivatives
• Landmark-based Detection: Key point position analysis (nose-to-hip ratio)
• Multi-criteria Voting: Ensemble method combining all algorithms

• Hybrid Processing Architecture: Synchronous OpenCV capture + asynchronous event processing
• JPEG-compressed Ring Buffer: Circular buffer with 70% quality compression
• Async Video Encoder: Background MP4 encoding with mp4v codec
• Dual API Client: Success (multipart upload) + Failure (JSON notification) endpoints
• Event Manager: Queue-based processing with 15s cooldown and retry logic
• Configuration System: YAML + Environment variables with validation

Prerequisites: Docker and Docker Compose installed

1. Download MediaPipe model:

   • URL: https://storage.googleapis.com/mediapipe-models/pose_landmarker/pose_landmarker_lite/float16/latest/pose_landmarker_lite.task
   • Save to: src/utils/pose_landmarker_lite.task

2. Configure environment:

   • Copy .env.example to .env
   • Set API_BASE_URL and API endpoints
   • Adjust CAMERA_ID if needed (default: 0)

3. Deploy:

   • docker-compose up -d (start in background)
   • docker-compose logs -f (view logs)
   • docker-compose down (stop)

Prerequisites: Python 3.11+ and uv installed

1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Install dependencies: uv sync
3. Download MediaPipe model (see Docker step 1)
4. Configure .env file
5. Run: uv run python main.py or uv run fall-detect

BinaryHitters-WatchOut-DL/
├── main.py                           # Entry point with async architecture
├── requirements.txt                  # Python dependencies
├── Dockerfile                        # Multi-stage Docker build
├── docker-compose.yml               # Container orchestration
├── .env.example                     # Environment variables template
├── CLAUDE.md                        # Development guidelines
└── src/                             # Main source package
    ├── __init__.py                  # Package exports
    ├── detectors/                   # Detection algorithms
    │   ├── __init__.py
    │   └── fall_detector.py         # FallDetectorRuleBased class
    ├── camera/                      # Camera integration
    │   ├── __init__.py
    │   └── live_detector.py         # LiveCameraFallDetector (refactored)
    ├── video/                       # NEW: Video processing
    │   ├── __init__.py
    │   ├── ring_buffer.py           # Lightweight ring buffer with JPEG compression
    │   └── encoder.py               # Async video encoder (MP4/H264)
    ├── api/                         # NEW: API integration
    │   ├── __init__.py
    │   └── client.py                # Async API client with retry logic
    ├── events/                      # NEW: Event management
    │   ├── __init__.py
    │   └── manager.py               # Fall event manager with cooldown
    ├── config/                      # NEW: Configuration management
    │   ├── __init__.py
    │   └── settings.py              # Environment-based settings
    └── utils/                       # Utility modules
        ├── __init__.py
        ├── constants.py             # Constants and configurations
        ├── visualization.py         # Drawing and visualization functions
        └── pose_landmarker_lite.task # MediaPipe model (download separately)

┌─────────────┐     ┌──────────────┐     ┌────────────────┐     ┌─────────────┐
│   Camera    │────▶│ MediaPipe    │────▶│ Fall Detector  │────▶│ Ring Buffer │
│  (OpenCV)   │     │ Pose Model   │     │  (5 Methods)   │     │  (JPEG)     │
└─────────────┘     └──────────────┘     └────────┬───────┘     └─────────────┘
                                                   │
                                           Fall Detected?
                                                   │
                                                   ▼
                                         ┌──────────────────┐
                                         │  Event Manager   │
                                         │   (Async Queue)  │
                                         └────────┬─────────┘
                                                  │
                                   ┌──────────────┼──────────────┐
                                   ▼              ▼              ▼
                            Clip Extract    Video Encode    API Upload
                             (15s window)    (MP4/H264)     (Retry x3)

• Main Thread: Synchronous OpenCV capture + pose detection (for macOS GUI compatibility)
• Worker Thread: Asynchronous event loop for video encoding and API uploads
• Benefit: Maintains real-time camera processing while handling I/O-intensive tasks in background

• Voting System: Configurable threshold (default: 1/5 methods must detect fall)
• Temporal Analysis: 5-frame window for velocity calculation
• Adaptive Thresholds: Height drop ratio (20%), angle threshold (45°), velocity threshold (0.08)
• Visibility Filtering: Ignores low-confidence landmarks (min: 50%)

• JPEG Compression: Reduces frame size by 95% (70% quality setting)
• Circular Storage: 30-second rolling window at 15 FPS (~450 frames)
• Frame Skipping: Saves every 2nd frame (configurable) to reduce buffer writes
• Memory Footprint: ~20MB vs ~400MB uncompressed

• 15-Second Cooldown: Prevents duplicate uploads for same fall incident
• Timestamp Tracking: Maintains last fall detection time
• Queue-based Processing: Ensures sequential handling of fall events

• Dual Endpoint Strategy:
  • Primary: Multipart video upload with metadata
  • Fallback: JSON-only notification when video upload fails
• Exponential Backoff: 3 retry attempts with increasing delays (1s, 2s, 4s)
• Async Upload: Non-blocking I/O prevents camera pipeline stalls
• Device Check-in: Periodic heartbeat to backend (configurable interval)

• Skeleton-only Rendering: Displays stick figure without background video
• No Raw Frame Storage: Only skeleton landmarks saved in privacy mode
• GDPR-friendly: Reduces personal data exposure

• Data Collection: Saves landmarks, detection details, and video clips
• Timestamped Output: Organized directory structure for analysis
• Training Support: Facilitates ML model improvement and validation

Key settings in .env file:

• Method: POST (multipart/form-data)
• Fields: video (MP4), timestamp, datetime, device_id, clip_duration, fall_info (JSON)
• Response: 200 OK on successful upload

• Method: POST (application/json)
• Body: event_type, error, timestamp, datetime, device_id, fall_info
• Use Case: Triggered when video upload fails after retries

• Method: POST (application/json)
• Body: device_id, timestamp, status
• Interval: Configurable (default: 300s)

Memory Usage:

• JPEG-compressed ring buffer: ~20 MB (vs ~400 MB uncompressed)
• Total system RAM: 250-300 MB
• Docker container limit: 512 MB (with 256 MB reserved)

CPU Usage:

• MediaPipe Lite model: Optimized for edge devices
• Async I/O: Video encoding doesn't block detection pipeline
• mp4v codec: Faster than H264 on CPU-only devices
• Expected usage: 40-60% single core (Raspberry Pi 4 equivalent)

Network:

• Video upload: ~1-2 MB per fall event (15s clip at 1 Mbps)
• Retry mechanism: Exponential backoff reduces burst traffic
• Heartbeat: Lightweight JSON payload every 5 minutes

1. Headless Mode: Disables GUI rendering to save CPU cycles
2. Frame Skipping: Reduces buffer writes by 50% (saves every 2nd frame)
3. JPEG Compression: 95% memory reduction with minimal quality loss
4. Async Processing: I/O operations don't block real-time detection
5. Lite Pose Model: MediaPipe's smallest model for low-latency inference
6. Resource Limits: Docker constraints prevent OOM on constrained devices

Following CLAUDE.md guidelines:

• Loose Coupling: Modular architecture with clear interfaces (detectors, video, API, events)
• Clear Architecture: Layered design (camera → detection → events → API)
• English Documentation: Comprehensive inline comments and docstrings
• Proper Logging: Using Python logging module (no print statements)
• Environment Management: uv-based dependency management for reproducible builds

MIT License - Part of the BinaryHitters-WatchOut-DL system

• MediaPipe (Google): Pose estimation framework
• OpenCV: Computer vision library
• aiohttp: Asynchronous HTTP client library

Project: WatchOut Fall Detection System Organization: BinaryHitters Maintained by: BinaryHitters Team