README.md

---
title: AnomalDrive
emoji: 👁
colorFrom: green
colorTo: red
sdk: gradio
sdk_version: 5.45.0
app_file: app.py
pinned: false
short_description: Advanced ML-powered anomaly detection for GPS tracking data
---

# 🛣️ Vehicle Anomaly Detection System

An advanced machine learning-powered anomaly detection system for GPS tracking data with a beautiful Gradio interface.

## 🚀 Features

- **Multiple ML Models**: Ensemble of Isolation Forest, One-Class SVM, and LSTM Autoencoder
- **Beautiful UI**: Modern Gradio interface with interactive visualizations
- **Real-time Processing**: Handles up to 2000 GPS points with detailed analysis
- **Comprehensive Output**: Point-by-point analysis, risk factors, and JSON export
- **Interactive Maps**: GPS route visualization with anomaly highlighting
- **Performance Analytics**: Speed, altitude, and confidence distribution charts

## 📊 Processing Performance

- **CPU-only processing**: 45-90 seconds for 2000 samples
- **HuggingFace Spaces ready**: Optimized for cloud deployment
- **Memory efficient**: Handles large datasets with rolling window processing

## 🔧 Installation

### Local Installation

```bash
# Clone or download the project
cd anomaly

# Install dependencies
pip install -r requirements.txt

# Run the Gradio app
python gradio_app.py
```

### HuggingFace Spaces Deployment

1. Create a new Space on HuggingFace
2. Upload all files including the `models/` directory
3. Set `app_file` to `app.py`
4. The app will automatically launch

## 📁 Input Format

Your CSV file must contain these columns:

| Column | Description | Range |
|--------|-------------|-------|
| `randomized_id` | Vehicle identifier | Any string |
| `lat` | Latitude | -90 to 90 |
| `lng` | Longitude | -180 to 180 |
| `spd` | Speed (km/h) | 0 to 300 |
| `azm` | Azimuth/heading (degrees) | 0 to 360 |
| `alt` | Altitude (meters) | Any number |

### Sample Data

```csv
randomized_id,lat,lng,spd,azm,alt
VEHICLE001,40.7128,-74.0060,45.5,90.0,100.0
VEHICLE001,40.7138,-74.0070,48.2,92.0,102.0
VEHICLE002,40.7500,-73.9800,35.2,180.0,90.0
```

**Maximum**: 2000 samples per upload
**Minimum**: 5 samples required

## 🎯 Anomaly Detection

The system detects various types of anomalies:

### Speed Anomalies
- Excessive speeding (>120 km/h)
- Sudden acceleration/deceleration
- Speed inconsistencies

### Movement Anomalies
- Erratic GPS patterns
- Sharp turns at high speed
- Altitude inconsistencies

### Behavioral Patterns
- Route deviations
- Stop-and-go patterns
- Unusual driving sequences

## 📈 Output Features

### 1. Detailed Results
- Point-by-point analysis
- Normal vs. anomaly classification
- Confidence scores and alert levels
- Risk factor identification

### 2. Interactive Visualizations
- GPS route mapping with anomaly markers
- Speed and altitude profiles
- Confidence score distributions
- Multi-panel analysis dashboard

### 3. Summary Statistics
- Processing performance metrics
- Overall anomaly rates
- Alert level distributions
- Risk factor rankings

### 4. JSON Export
Complete machine-readable results including:
- All detection scores
- Driving metrics
- Risk assessments
- Timestamps and metadata

## 🔬 Technical Details

### ML Models Used
1. **Isolation Forest**: Tree-based anomaly detection
2. **One-Class SVM**: Support vector-based outlier detection  
3. **LSTM Autoencoder**: Deep learning sequence anomaly detection

### Feature Engineering
- 18 engineered features including:
  - Speed patterns and statistics
  - Acceleration and jerk calculations
  - Angular velocity and curvature
  - Rolling window aggregations
  - Risk scoring algorithms

### Performance Optimization
- Efficient batch processing
- Memory-optimized feature calculation
- CPU-friendly model inference
- Progressive result streaming

## 🛡️ Privacy & Security

- **Local Processing**: All analysis happens in your environment
- **No Data Upload**: Your GPS data never leaves the system
- **Real-time Analysis**: No data storage or logging
- **Secure Processing**: Industry-standard ML pipeline

## 🚀 Deployment Options

### Local Development
```bash
python gradio_app.py
# Access at http://localhost:7860
```

### HuggingFace Spaces
- Perfect for sharing and collaboration
- No setup required
- Automatic scaling
- Public or private deployment

### Docker (Optional)
```dockerfile
FROM python:3.9-slim
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
CMD ["python", "gradio_app.py"]
```

## 📞 Support

For issues or questions:
1. Check the sample data format
2. Ensure your CSV has all required columns
3. Verify data is within expected ranges
4. Check for missing values or invalid entries

## 🔮 Future Enhancements

- Real-time streaming support
- Custom alert thresholds
- Historical trend analysis
- Fleet management dashboard
- Advanced route optimization
- Multi-vehicle correlation analysis

---

**Made with ❤️ using Gradio, PyTorch, and Advanced ML**

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference