README.md

---
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](/docs)
2. Try the `POST /process/image` endpoint
3. Upload any image with people
4. Get instant people count and annotated result!

### Test the API
```bash
# 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)
```javascript
// 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
```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
```bash
# 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