🎥 RAVN - Security Camera System

Advanced security camera management platform with face recognition, PTZ control, and real-time video processing.

A Python-based desktop application for professional surveillance operations, combining OpenCV computer vision with a modern PyQt5 interface.

---

📋 Overview

RAVN provides enterprise-grade security camera management with:

• Real-time video capture from RTSP sources (IP cameras, NVRs)
• Intelligent face recognition for person identification and alerts
• PTZ control (Pan-Tilt-Zoom) for dynamic camera positioning
• Video recording with configurable codec and quality
• Configuration management for multi-site deployments
• Professional GUI with status monitoring and settings

Ideal for security operations centers, retail surveillance, and facility monitoring.

---

🛠️ Tech Stack

Component	Technology
Language	Python 3.8+
GUI Framework	PyQt5
Computer Vision	OpenCV
Camera Protocol	RTSP, ONVIF
Face Recognition	Deep learning models
Video Codec	H.264, MJPEG
Logging	Python logging module

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• pip package manager
• RTSP-compatible IP camera or NVR
• 1GB RAM minimum (4GB+ recommended for multiple streams)

Installation

# 1. Clone the repository
git clone https://github.com/bragestoefringshaug/RAVN
cd RAVN

# 2. Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env

Configuration

Edit .env with your environment:

RTSP_URL=rtsp://username:password@camera.local:554/stream
FRAME_WIDTH=1920
FRAME_HEIGHT=1080
ENABLE_RECORDING=true
RECORDING_PATH=./recordings

Run the Application

python src/main.py

The GUI will launch with an automatic first-time setup wizard.

---

🎯 Features

Core Capabilities

1. Camera Management

• Connect to multiple RTSP sources
• Real-time frame capture and display
• Configurable resolution and bitrate
• Connection health monitoring

2. Face Recognition

• Detect faces in video stream
• Identify known persons from database
• Alert on suspicious activity
• Export recognition logs

3. PTZ Control

• Remote pan, tilt, zoom operations
• Preset position save/load
• Smooth motion control
• ONVIF protocol support

4. Video Recording

• Continuous or event-triggered recording
• Configurable quality and codec
• Timestamp embedding
• Automatic cleanup policies

5. Configuration & Settings

• Per-site camera profiles
• User preferences persistence
• Security and API settings
• Export/import configurations

---

📁 Project Structure

RAVN/
├── src/
│   ├── main.py                    # Application entry point
│   ├── Camera.py                  # Camera capture & recording
│   ├── face_recognition/          # Face detection & identification
│   │   ├── face_detector.py
│   │   ├── face_recognizer.py
│   │   └── models/
│   ├── gui/                       # PyQt5 user interface
│   │   ├── main_window.py
│   │   ├── settings_dialog.py
│   │   ├── ptz_window.py
│   │   └── widgets/
│   ├── ptz/                       # Pan-Tilt-Zoom control
│   │   ├── ptz_controller.py
│   │   └── presets.py
│   └── utils/                     # Utilities and helpers
│       ├── icons.py
│       ├── logging_config.py
│       └── validators.py
├── config/
│   ├── config_manager.py          # Configuration persistence
│   ├── settings.py                # Runtime settings
│   └── presets.json               # PTZ presets
├── data/                          # Application data (logs, cache)
├── resources/                     # Icons, assets
├── requirements.txt               # Python dependencies
├── .env                           # Environment variables
└── README.md

---

🔧 Development

Architecture

RAVN follows a modular architecture:

1. Camera Module (Camera.py) — Handles RTSP connections and video I/O
2. Face Recognition — Pluggable detection/recognition system
3. PTZ Controller — ONVIF client for camera control
4. GUI Layer — PyQt5 interface with threaded rendering
5. Config Manager — Persistent settings and state

Environment Setup

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run with debug logging
LOGLEVEL=DEBUG python src/main.py

Key Classes

CameraCapture

from src.Camera import CameraCapture

with CameraCapture(rtsp_url="rtsp://...") as camera:
    success, frame = camera.read()
    if success:
        process(frame)

PTZController

from src.ptz import PTZController

ptz = PTZController(onvif_url="http://camera.local:8080/onvif/device_service")
ptz.pan(0.5)    # Pan right
ptz.zoom(1.2)   # Zoom in

Adding Custom Integrations

Example: Slack alerts on face detection

# In face_recognizer.py
if confidence > ALERT_THRESHOLD:
    send_slack_alert({
        'person': name,
        'confidence': confidence,
        'timestamp': datetime.now(),
        'snapshot': frame
    })

---

📊 API Reference

Camera Methods

Method	Parameters	Returns	Description
start()	—	bool	Connect and initialize camera
stop()	—	bool	Disconnect and cleanup
read()	—	(bool, ndarray)	Get next frame
record()	output_path	bool	Start recording session
stop_record()	—	bool	End recording

PTZ Methods

Method	Parameters	Returns	Description
pan(speed)	-1.0 to 1.0	bool	Horizontal movement
tilt(speed)	-1.0 to 1.0	bool	Vertical movement
zoom(factor)	float	bool	Zoom in/out
goto_preset(id)	string	bool	Move to saved position
save_preset(name)	string	bool	Save current position

Configuration

from config.settings import Settings

# Get settings
rtsp_url = Settings.get_rtsp_url()
recording_path = Settings.get_recording_path()

# Set settings
Settings.set_enable_recording(True)
Settings.save()

---

🔐 Security

• RTSP Authentication: Credentials stored in encrypted .env
• ONVIF Security: TLS support for camera control
• Recording Privacy: Optional redaction zones
• Access Control: User roles and permissions (configurable)
• Audit Logging: All operations logged with timestamps

---

📝 Configuration Examples

Basic Single Camera

RTSP_URL=rtsp://admin:password@192.168.1.100:554/stream
FRAME_WIDTH=1920
FRAME_HEIGHT=1080
ENABLE_FACE_RECOGNITION=true
ENABLE_RECORDING=false

Multi-Camera with Recording

Create separate .env files per site:

configs/
├── warehouse.env
├── reception.env
└── entrance.env

Launch with: python src/main.py --config configs/warehouse.env

---

🐛 Troubleshooting

Camera Won't Connect

[ERROR] Camera connection failed: Connection refused

• Verify camera IP and credentials
• Ensure RTSP port (typically 554) is open
• Check firewall rules

Face Recognition Not Working

• Verify face detection model is downloaded
• Ensure face database is properly configured
• Check frame resolution is at least 480p

High CPU Usage

• Reduce frame resolution
• Disable face recognition if not needed
• Lower recording bitrate
• Use hardware acceleration (if supported)

PTZ Not Responding

• Verify ONVIF endpoint URL
• Check camera firmware supports PTZ
• Ensure network connectivity to camera

---

📦 Dependencies

Package	Version	Purpose
opencv-python	>=4.8.0	Video capture & processing
PyQt5	>=5.15.0	GUI framework
numpy	>=1.24.0	Array operations
onvif-zeep	>=0.2.12	ONVIF camera control
requests	>=2.31.0	HTTP client
python-dotenv	>=1.0.0	Environment management

---

🎯 Future Roadmap

• Multi-camera dashboard with synchronized view
• Cloud integration (AWS, Azure) for remote monitoring
• Mobile app for smartphone monitoring
• Analytics — traffic counting, behavior analysis
• Event timeline — searchable incident log
• Webhook integrations — Slack, Teams, webhooks
• Database backend — PostgreSQL for scalability

---

📄 License

MIT License — open for use and extension.

---

👤 Author

Brage Støfringshaug
Specialized in Python backend systems, computer vision applications, and security infrastructure.

📧 bragestofringshaug@gmail.com
🔗 https://github.com/bragestoefringshaug

---

Contributing

Issues and pull requests welcome! Please include:

• Description of issue/feature
• Environment details (Python version, OS, camera model)
• Logs from data/logs/ directory

---

Support

• 📖 Full documentation: GitHub Wiki
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions