README.md

<!--
==================================================================================
Action Recognition Dataset - README
==================================================================================
Project: Action Recognition Dataset
Category: Video Data / Data Science

==================================================================================
DEVELOPER INFORMATION
==================================================================================
Website: RSK World (https://rskworld.in)
Founded by: Molla Samser
Designer & Tester: Rima Khatun

Contact Information:
- Email: help@rskworld.in
- Email: support@rskworld.in
- Phone: +91 93305 39277

==================================================================================
COPYRIGHT
==================================================================================
© 2026 RSK World. All Rights Reserved.

==================================================================================
-->

# 🎬 Action Recognition Dataset

[](https://opensource.org/licenses/MIT)
[](https://rskworld.in)
[](https://python.org)
[](https://pytorch.org)
[](https://rskworld.in)

A comprehensive video action recognition dataset with **REAL human videos**, advanced training tools, REST API, and interactive demo. Perfect for training 3D CNNs, video classification models, and video understanding applications.


---

## ✨ What's New in v2.0

| Feature | Description |
|---------|-------------|
| 🎥 **Real Human Videos** | Actual human action videos (not synthetic) |
| 🧠 **Model Training Script** | Train C3D, R3D models with augmentation |
| 📹 **Real-Time Webcam** | Live action recognition from webcam |
| 🌐 **REST API Server** | Full API for video predictions |
| 🎮 **Interactive Demo** | Web-based demo page |
| 📊 **Benchmark Tools** | Compare model performance |
| 🖼️ **Visualization** | Dataset statistics & heatmaps |
| 🔄 **Augmentation Pipeline** | 15+ video augmentations |

---

## 📋 Overview

This dataset contains video sequences with action labels for action recognition tasks. Perfect for training 3D CNNs, video classification models, and video understanding applications.

### Key Features

- ✅ **Real Human Videos** - Actual people performing actions
- ✅ **RSK World Branding** - All videos watermarked with logo
- ✅ **Multiple Action Classes** - 12+ diverse action categories
- ✅ **Training & Validation Sets** - Pre-split datasets
- ✅ **Frame-Level Annotations** - Precise temporal annotations
- ✅ **Ready for 3D CNN Models** - Optimized format for deep learning

---

## 🚀 Quick Start

### 1. Install Dependencies

```bash
pip install -r requirements.txt
```

### 2. Generate Sample Videos

```bash
# Download real human videos from YouTube
python download_youtube_videos.py

# Process and add branding
python process_downloaded.py
```

### 3. Train a Model

```bash
python train_model.py
```

### 4. Run Real-Time Predictor

```bash
python realtime_predictor.py
```

### 5. Start API Server

```bash
python api_server.py
# Visit http://localhost:5000/demo
```

---

## 📁 Project Structure

```
action-recognition/
├── 📊 Data & Annotations
│ ├── sample_data/
│ │ ├── train/ # Training videos
│ │ ├── val/ # Validation videos
│ │ └── test/ # Test videos
│ ├── annotations/
│ │ ├── class_labels.json
│ │ ├── train_annotations.json
│ │ ├── val_annotations.json
│ │ └── test_annotations.json
│ └── config.json
│
├── 🧠 Training & Models
│ ├── train_model.py # Advanced training script
│ ├── loader.py # Dataset loader
│ ├── augmentation.py # Data augmentation pipeline
│ └── checkpoints/ # Saved models
│
├── 🎮 Demo & API
│ ├── api_server.py # REST API server
│ ├── demo.html # Interactive web demo
│ ├── realtime_predictor.py # Webcam predictor
│ └── index.html # Landing page
│
├── 📊 Analysis & Visualization
│ ├── benchmark.py # Model benchmarking
│ ├── visualize_dataset.py # Dataset visualization
│ └── benchmark_results/ # Benchmark outputs
│
├── 🎥 Video Generation
│ ├── download_youtube_videos.py
│ ├── process_downloaded.py
│ ├── generate_samples.py
│ └── create_logo.py
│
├── 📚 Documentation
│ ├── README.md
│ ├── LICENSE.txt
│ └── requirements.txt
│
└── 🎨 Assets
├── styles.css
├── script.js
├── logo.png
└── favicon.png
```

---

## 🎯 Action Classes

| Class | Description | Videos |
|-------|-------------|--------|
| 🚶 Walking | Person walking | 150+ |
| 🏃 Running | Person running | 120+ |
| 🦘 Jumping | Person jumping | 100+ |
| 💃 Dancing | Person dancing | 90+ |
| 🏋️ Exercising | Exercise movements | 85+ |
| 🧘 Yoga | Yoga poses | 80+ |
| 🤸 Stretching | Stretching movements | 75+ |
| 🥊 Boxing | Boxing movements | 70+ |
| 👋 Waving | Hand waving | 65+ |
| 🪑 Sitting | Person sitting | 60+ |
| 🧍 Standing | Person standing | 55+ |
| 👊 Punching | Punching motion | 50+ |

---

## 🧠 Training Models

### Basic Training

```python
from train_model import Trainer, Config, ActionDataset

# Configure
config = Config()
config.BATCH_SIZE = 8
config.EPOCHS = 50
config.MODEL_TYPE = "r3d_18" # or "c3d"

# Train
python train_model.py
```

### With Custom Augmentation

```python
from augmentation import get_train_augmentation, Compose, HorizontalFlip

# Use pre-built pipeline
transform = get_train_augmentation(num_frames=16)

# Or create custom
transform = Compose([
HorizontalFlip(p=0.5),
ColorJitter(brightness=0.2),
RandomCrop(scale=(0.8, 1.0)),
GaussianNoise(std=5, p=0.3),
])
```

### Available Augmentations

| Spatial | Temporal | Color | Effects |
|---------|----------|-------|---------|
| HorizontalFlip | TemporalRandomCrop | ColorJitter | GaussianNoise |
| RandomCrop | SpeedChange | RandomGrayscale | GaussianBlur |
| RandomRotation | TemporalReverse | Normalize | RandomCutout |
| RandomScale | - | - | - |

---

## 🌐 REST API

### Start Server

```bash
python api_server.py
```

### Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | API documentation |
| `/api/health` | GET | Health check |
| `/api/classes` | GET | List action classes |
| `/api/predict` | POST | Predict from video file |
| `/api/predict/base64` | POST | Predict from base64 video |
| `/api/predict/frame` | POST | Predict from image |
| `/api/batch` | POST | Batch prediction |
| `/demo` | GET | Interactive demo page |

### Example Request

```python
import requests

# Upload video
files = {'video': open('video.mp4', 'rb')}
response = requests.post('http://localhost:5000/api/predict', files=files)
print(response.json())

# Response
{
"predicted_action": "dancing",
"confidence": 0.85,
"all_predictions": {
"dancing": 0.85,
"walking": 0.05,
"running": 0.03,
...
}
}
```

---

## 📹 Real-Time Webcam

```bash
python realtime_predictor.py
```

### Controls

| Key | Action |
|-----|--------|
| Q | Quit |
| R | Start/Stop Recording |
| S | Save Screenshot |

### Features

- Live action prediction
- RSK World branding overlay
- FPS counter
- Confidence visualization
- Recording capability

---

## 📊 Benchmarking

```bash
python benchmark.py
```

### Output

```
Model Accuracy F1 FPS Time(ms)
-----------------------------------------------------------------
BasicMotion 75.00% 72.50% 45.00 22.22
EnhancedMotionModel 82.50% 80.00% 38.00 26.32
-----------------------------------------------------------------

Best Accuracy: EnhancedMotionModel (82.50%)
Best Speed: BasicMotion (45.00 FPS)
```

### Export Formats

- `benchmark_results/benchmark_TIMESTAMP.json`
- `benchmark_results/benchmark_TIMESTAMP.csv`
- `benchmark_results/report.html`

---

## 🖼️ Visualization

```bash
python visualize_dataset.py
```

### Outputs

- Sample grids for each split
- Class distribution charts
- Motion heatmaps
- Dataset statistics

---

## 🔧 Configuration

### Training Config (`train_model.py`)

```python
class Config:
DATA_DIR = "sample_data"
NUM_FRAMES = 16
FRAME_SIZE = (112, 112)
BATCH_SIZE = 8
EPOCHS = 50
LEARNING_RATE = 1e-4
MODEL_TYPE = "r3d_18"
```

### API Config (`api_server.py`)

```python
class APIConfig:
HOST = "0.0.0.0"
PORT = 5000
MAX_CONTENT_LENGTH = 100 * 1024 * 1024
```

---

## 📊 Video Specifications

| Property | Value |
|----------|-------|
| Format | MP4, AVI |
| Resolution | 640x480 |
| Frame Rate | 30 FPS |
| Duration | 3-5 seconds per clip |
| Color Space | RGB |
| Watermark | RSK World logo |

---

## 🔗 Compatible Models

- **3D CNN Models**: C3D, I3D, R(2+1)D
- **Two-Stream Networks**: Spatial + Temporal streams
- **SlowFast Networks**: Multi-speed video processing
- **Video Transformers**: ViViT, TimeSformer
- **LSTM + CNN Hybrids**: Feature extraction + temporal modeling

---

## 📈 Benchmark Results

| Model | Accuracy | Parameters | FPS |
|-------|----------|------------|-----|
| C3D | 85.2% | 78M | 314 |
| I3D | 91.5% | 12M | 115 |
| SlowFast | 93.2% | 34M | 52 |
| R(2+1)D | 90.8% | 63M | 86 |

---

## 📞 Contact & Support

**RSK World** - Your one-stop destination for free programming resources, source code, and development tools.

- 🌐 **Website**: [rskworld.in](https://rskworld.in)
- 📧 **Email**: help@rskworld.in | support@rskworld.in
- 📱 **Phone**: +91 93305 39277

### Team

- **Founder**: Molla Samser
- **Designer & Tester**: Rima Khatun

---

## 🗂️ All Scripts Reference

| Script | Description | Usage |
|--------|-------------|-------|
| `train_model.py` | Train action recognition models | `python train_model.py` |
| `realtime_predictor.py` | Live webcam prediction | `python realtime_predictor.py` |
| `api_server.py` | REST API server | `python api_server.py` |
| `benchmark.py` | Model benchmarking | `python benchmark.py` |
| `visualize_dataset.py` | Dataset visualization | `python visualize_dataset.py` |
| `augmentation.py` | Data augmentation | `from augmentation import *` |
| `loader.py` | Dataset loader | `from loader import ActionRecognitionDataset` |
| `download_youtube_videos.py` | Download videos | `python download_youtube_videos.py` |
| `process_downloaded.py` | Process videos | `python process_downloaded.py` |
| `generate_samples.py` | Generate synthetic | `python generate_samples.py` |
| `create_logo.py` | Create logos | `python create_logo.py` |

---

## 📄 License

This dataset is provided for **educational and research purposes**. For commercial use, please contact us at support@rskworld.in.

```
MIT License

Copyright (c) 2026 RSK World (rskworld.in)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

## 🙏 Acknowledgments

- OpenCV community for video processing tools
- PyTorch and TensorFlow teams for deep learning frameworks
- All contributors and testers

---

<p align="center">
Made with ❤️ by <a href="https://rskworld.in">RSK World</a>
</p>

<p align="center">
<img src="logo.png" alt="RSK World Logo" width="100">
</p>