README.md

metadata

title: Crowd Detection API
emoji: 👥
colorFrom: blue
colorTo: red
sdk: docker
pinned: false
license: mit

👥 Crowd Detection & Disaster Management API

A real-time crowd monitoring system with anomaly detection, emergency alerts, and WebSocket broadcasting capabilities, deployed on Hugging Face Spaces.

🚀 Features

• Real-time People Counting using YOLOv8
• Crowd Density Heatmaps for visualization
• Anomaly Detection (stampede, fallen person detection)
• Emergency Alert System with WebSocket broadcasting
• Zone-based Monitoring with capacity management
• RTSP Stream Processing for live camera feeds
• Video File Analysis for uploaded content
• RESTful API with interactive documentation

🎯 Quick Demo

Upload an Image

1. Go to the API Documentation
2. Try the POST /process/image endpoint
3. Upload any image with people
4. Get instant people count and annotated result!

Test the API

# Health Check
curl https://YOUR-USERNAME-crowd-detection-api.hf.space/health

# Get Demo Zones
curl https://YOUR-USERNAME-crowd-detection-api.hf.space/zones/heatmap

📊 API Endpoints

Core Features

• POST /process/image - Analyze uploaded images for people counting
• GET /zones/heatmap - Get zones with crowd density data
• GET /health - API health status
• GET / - API information and quick start guide

Advanced Features

• POST /monitor/rtsp - Start monitoring RTSP streams
• POST /process/video - Process uploaded video files
• POST /emergency - Send emergency alerts
• GET /crowd-flow - Get crowd flow analytics

WebSocket Endpoints

• ws://YOUR-SPACE-URL/ws/alerts - Real-time alerts
• ws://YOUR-SPACE-URL/ws/frames/{camera_id} - Live video frames
• ws://YOUR-SPACE-URL/ws/live-map - Live map updates

🛠️ Technology Stack

• Backend: FastAPI + Python 3.9
• AI/ML: YOLOv8 (Ultralytics), PyTorch, OpenCV
• Data Processing: NumPy, SciPy
• Deployment: Docker on Hugging Face Spaces
• Real-time: WebSockets for live updates

🎮 Usage Examples

JavaScript (Browser)

// Test people counting
const formData = new FormData();
formData.append('file', imageFile);

fetch('/process/image', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => {
    console.log('People count:', data.people_count);
    // Display annotated image
    document.getElementById('result').src = data.annotated_image;
});

// WebSocket alerts
const ws = new WebSocket('wss://YOUR-SPACE-URL/ws/alerts');
ws.onmessage = (event) => {
    const alert = JSON.parse(event.data);
    console.log('Alert received:', alert);
};

Python

import requests
import websockets
import asyncio

# Upload image for analysis
with open('crowd_image.jpg', 'rb') as f:
    response = requests.post(
        'https://YOUR-SPACE-URL/process/image',
        files={'file': f}
    )
    result = response.json()
    print(f"People detected: {result['people_count']}")

# WebSocket connection
async def listen_alerts():
    uri = "wss://YOUR-SPACE-URL/ws/alerts"
    async with websockets.connect(uri) as websocket:
        async for message in websocket:
            data = json.loads(message)
            print(f"Alert: {data}")

cURL

# Process image
curl -X POST "https://YOUR-SPACE-URL/process/image" \
  -F "file=@crowd_photo.jpg"

# Start RTSP monitoring
curl -X POST "https://YOUR-SPACE-URL/monitor/rtsp" \
  -d "camera_id=cam1&rtsp_url=rtsp://example.com/stream&zone_id=zone1"

# Send emergency alert
curl -X POST "https://YOUR-SPACE-URL/emergency" \
  -d "emergency_type=MEDICAL&message=Medical emergency&location=Gate 1"

🏗️ Architecture

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Input Layer   │ => │ AI Processing│ => │  Output Layer   │
├─────────────────┤    ├──────────────┤    ├─────────────────┤
│ • Image Upload  │    │ • YOLOv8      │    │ • People Count  │
│ • Video Stream  │    │ • OpenCV      │    │ • Heatmaps      │
│ • RTSP Feed     │    │ • Anomaly     │    │ • Alerts        │
│ • WebSocket     │    │   Detection   │    │ • WebSocket     │
└─────────────────┘    └──────────────┘    └─────────────────┘

🚦 System Status

• ✅ AI Models: YOLOv8s loaded and ready
• ✅ Image Processing: Real-time people detection
• ✅ WebSocket: Live alerts and updates
• ✅ API Documentation: Interactive Swagger UI
• ⚡ Performance: Optimized for Hugging Face Spaces

📈 Performance

• Image Processing: ~1-3 seconds per image
• People Detection Accuracy: >90% (YOLOv8s)
• Supported Formats: JPG, PNG, MP4, AVI, RTSP
• Concurrent Users: Scales with Hugging Face Spaces
• Model Size: ~20MB (YOLOv8s)

🔒 Privacy & Security

• No Data Storage: Images processed in memory only
• Temporary Files: Automatically cleaned up
• No Logging: Personal data not logged
• CORS Enabled: Secure browser access
• Rate Limiting: Built-in request throttling

🌟 Use Cases

Public Safety

• Crowd Management: Monitor capacity at events
• Emergency Response: Detect anomalies and alert teams
• Traffic Analysis: Count people flow in areas

Smart Cities

• Urban Planning: Analyze pedestrian patterns
• Public Transport: Monitor station capacity
• Event Management: Real-time crowd control

Business Intelligence

• Retail Analytics: Customer flow analysis
• Venue Management: Occupancy monitoring
• Security Systems: Automated surveillance