# Camera Simulation Usage Guide

This guide provides comprehensive instructions for using the camera simulation system in the meteor edge client for development, testing, and continuous integration.

## Table of Contents

1. [Quick Start](#quick-start)
2. [Configuration](#configuration)
3. [Camera Source Types](#camera-source-types)
4. [Development Workflow](#development-workflow)
5. [Testing Strategies](#testing-strategies)
6. [CI/CD Integration](#cicd-integration)
7. [Troubleshooting](#troubleshooting)
8. [Performance Optimization](#performance-optimization)

## Quick Start

### Prerequisites

```bash
# Ensure you have Rust installed
rustc --version

# Install FFmpeg (optional, for full video support)
# Ubuntu/Debian:
sudo apt-get install ffmpeg libavcodec-dev libavformat-dev

# macOS:
brew install ffmpeg

# For V4L2 loopback on Linux:
sudo apt-get install v4l2loopback-dkms v4l2loopback-utils
```

### Basic Usage

```bash
# Build with camera simulation support
cargo build --features camera_sim

# Run with test pattern
cargo run --features camera_sim -- --camera-source "test:meteor"

# Run with video file
cargo run --features camera_sim -- --camera-source "file:test_data/meteor_video.mp4"

# Run with specific test pattern
cargo run --features camera_sim -- --camera-source "test:checkerboard"
```

## Configuration

### TOML Configuration

Add camera simulation configuration to your `meteor-client-config.toml`:

```toml
[camera]
# Source type: "device", "file", "test_pattern", "v4l2_loopback", "network"
source_type = "test_pattern"

# Test pattern configuration
[camera.test_pattern]
type = "simulated_meteor"  # Options: static, noise, bar, meteor, checkerboard, gradient
fps = 30.0
width = 1280
height = 720
duration_seconds = 300  # Optional, infinite if not specified

# File input configuration
[camera.file]
path = "test_data/meteor_capture.mp4"
loop = true
playback_speed = 1.0

# V4L2 loopback configuration (Linux only)
[camera.v4l2_loopback]
device = "/dev/video10"
input_file = "test_data/meteor_capture.mp4"  # Optional

# Performance settings
[camera.performance]
enable_memory_optimization = true
max_camera_memory_mb = 64
buffer_pool_size = 20
```

### Command Line Options

```bash
# Specify camera source directly
--camera-source "test:meteor"          # Meteor simulation pattern
--camera-source "test:static"          # Static test pattern
--camera-source "test:noise"           # Random noise pattern
--camera-source "test:bar"             # Moving bar pattern
--camera-source "test:checkerboard"    # Checkerboard pattern
--camera-source "test:gradient"        # Gradient pattern

# File sources
--camera-source "file:video.mp4"       # Video file input
--camera-source "file:/path/to/video.mp4"  # Absolute path

# Device sources
--camera-source "device:0"             # Camera device index
--camera-source "v4l2:/dev/video10"    # V4L2 loopback device (Linux)

# Test mode options
--test-mode                             # Enable test mode
--frames 100                           # Capture specific number of frames
--benchmark-mode                       # Enable performance benchmarking
```

## Camera Source Types

### 1. Test Patterns

Synthetic patterns generated in real-time for testing detection algorithms.

```bash
# Available patterns:
cargo run --features camera_sim -- --camera-source "test:static"       # Fixed pattern
cargo run --features camera_sim -- --camera-source "test:noise"        # Random noise
cargo run --features camera_sim -- --camera-source "test:bar"          # Moving bar
cargo run --features camera_sim -- --camera-source "test:meteor"       # Meteor simulation
cargo run --features camera_sim -- --camera-source "test:checkerboard" # Alternating squares
cargo run --features camera_sim -- --camera-source "test:gradient"     # Gradient pattern
```

**Meteor Simulation Features:**
- Random meteor events every 3-10 seconds
- Realistic brightness variations (2-4x normal brightness)
- Multiple meteor events per capture session
- Deterministic patterns for testing

### 2. File Reader

Read video files for testing with realistic astronomical data.

```bash
# Supported formats: MP4, AVI, MKV, MOV
cargo run --features camera_sim -- --camera-source "file:test_data/meteor_2024.mp4"

# With FFmpeg support (more formats):
cargo run --features "camera_sim,ffmpeg" -- --camera-source "file:complex_video.mkv"
```

**Features:**
- Automatic loop playback
- Variable playback speed
- Resolution detection from filename
- Frame rate detection
- Seeking support (with FFmpeg)

### 3. V4L2 Loopback (Linux Only)

Use virtual V4L2 devices for testing with external video streams.

```bash
# Setup virtual camera
sudo scripts/setup_virtual_camera.sh start meteor_video.mp4

# Use virtual camera
cargo run --features camera_sim -- --camera-source "v4l2:/dev/video10"

# Multiple virtual cameras
sudo scripts/setup_virtual_camera.sh start-all meteor_video.mp4
cargo run --features camera_sim -- --camera-source "v4l2:/dev/video11"
```

**Use Cases:**
- Testing with external streaming sources
- Integration with existing camera testing tools
- Multi-camera simulation
- Real-time video processing testing

### 4. FFmpeg Integration (Optional)

Enhanced video processing with FFmpeg backend.

```bash
# Enable FFmpeg support
cargo build --features "camera_sim,ffmpeg"

# Supports additional formats and hardware acceleration
cargo run --features "camera_sim,ffmpeg" -- --camera-source "file:high_res_video.mkv"
```

**Benefits:**
- Hardware acceleration support
- Broader format compatibility
- Advanced video processing capabilities
- Frame-accurate seeking

## Development Workflow

### 1. Algorithm Development

```bash
# Start with static pattern for basic testing
cargo run --features camera_sim -- --camera-source "test:static" --frames 100

# Test with meteor simulation
cargo run --features camera_sim -- --camera-source "test:meteor" --frames 1000

# Use real video data for validation
cargo run --features camera_sim -- --camera-source "file:real_meteor_capture.mp4"
```

### 2. Performance Testing

```bash
# Benchmark different patterns
cargo run --release --features camera_sim -- --benchmark-mode --camera-source "test:meteor"

# Test file reader performance
cargo run --release --features camera_sim -- --benchmark-mode --camera-source "file:1080p_video.mp4"

# Memory leak testing
scripts/test_camera_simulation.sh memory
```

### 3. Integration Testing

```bash
# Run comprehensive test suite
scripts/test_camera_simulation.sh all

# Test specific components
scripts/test_camera_simulation.sh patterns    # Test pattern generators
scripts/test_camera_simulation.sh files       # Test file readers
scripts/test_camera_simulation.sh performance # Performance benchmarks
scripts/test_camera_simulation.sh concurrent  # Concurrent access
scripts/test_camera_simulation.sh errors      # Error handling
```

## Testing Strategies

### Unit Testing

```bash
# Run camera simulation unit tests
cargo test --features camera_sim camera_sim::

# Test specific modules
cargo test --features camera_sim test_pattern
cargo test --features camera_sim file_reader
cargo test --features camera_sim camera_source_factory
```

### Integration Testing

```bash
# End-to-end camera simulation test
cargo test --features camera_sim integration_camera_simulation

# Test with real detection pipeline
cargo test --features camera_sim test_meteor_detection_pipeline
```

### Performance Testing

```bash
# Benchmark frame generation
cargo bench --features camera_sim bench_pattern_generation

# Memory usage analysis
cargo run --features camera_sim -- --profile-memory --camera-source "test:meteor"

# Throughput testing
cargo run --release --features camera_sim -- --measure-throughput --frames 10000
```

### Automated Testing

Create test data:

```bash
# Generate test videos
scripts/test_camera_simulation.sh

# This creates:
# - test_data/test_480p.mp4
# - test_data/test_720p.mp4
# - test_data/test_1080p.mp4
# - test_data/meteor_simulation.mp4
```

## CI/CD Integration

### Docker Integration

```dockerfile
# Dockerfile for testing environment
FROM rust:1.70

# Install dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg libavcodec-dev libavformat-dev \
    v4l2loopback-dkms v4l2loopback-utils

# Copy and build
COPY . /app
WORKDIR /app
RUN cargo build --features "camera_sim,ffmpeg"

# Run tests
CMD ["cargo", "test", "--features", "camera_sim"]
```

### Test Data Management

```bash
# Download test videos for CI
curl -O https://example.com/test_videos/meteor_test_suite.zip
unzip meteor_test_suite.zip -d test_data/

# Verify test data
ls -la test_data/
# - meteor_bright.mp4      (bright meteor events)
# - meteor_faint.mp4       (faint meteor events)
# - meteor_multiple.mp4    (multiple meteors)
# - background_only.mp4    (no meteors, background)
# - noise_test.mp4         (high noise conditions)
```

## Troubleshooting

### Common Issues

#### 1. "Camera source not available"
```bash
# Check if feature is enabled
cargo build --features camera_sim

# Verify source specification
cargo run --features camera_sim -- --camera-source "test:meteor"  # Correct
cargo run --features camera_sim -- --camera-source "test:invalid" # Incorrect
```

#### 2. "File not found" errors
```bash
# Check file path
ls -la test_data/your_video.mp4

# Use absolute path
cargo run --features camera_sim -- --camera-source "file:/absolute/path/to/video.mp4"
```

#### 3. V4L2 device errors (Linux)
```bash
# Check if module is loaded
lsmod | grep v4l2loopback

# Load module manually
sudo modprobe v4l2loopback devices=1 video_nr=10

# Check device permissions
ls -la /dev/video*
sudo chmod 666 /dev/video10
```

#### 4. FFmpeg build errors
```bash
# Install development libraries
sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev

# Or disable FFmpeg support
cargo build --features camera_sim  # Without FFmpeg
```

### Performance Issues

#### High memory usage
```toml
# Reduce buffer pool size
[camera.performance]
buffer_pool_size = 10
max_camera_memory_mb = 32
```

#### Low frame rate
```bash
# Check system resources
top
htop

# Reduce resolution or frame rate
cargo run --features camera_sim -- --camera-source "test:meteor" --resolution 640x480
```

### Debugging

#### Enable debug logging
```bash
RUST_LOG=debug cargo run --features camera_sim -- --camera-source "test:meteor"
```

#### Memory leak detection
```bash
valgrind --leak-check=full ./target/debug/meteor-edge-client --camera-source "test:static"
```

#### Performance profiling
```bash
perf record ./target/release/meteor-edge-client --camera-source "test:meteor" --frames 1000
perf report
```

## Performance Optimization

### Memory Optimization

```rust
// Use smaller buffer pools for resource-constrained devices
let frame_pool = Arc::new(HierarchicalFramePool::new(8)); // Reduced from 20

// Enable memory optimization
camera_config.enable_memory_optimization = true;
camera_config.max_camera_memory = 32 * 1024 * 1024; // 32MB limit
```

### CPU Optimization

```bash
# Use release builds for performance testing
cargo build --release --features camera_sim

# Enable specific CPU features
RUSTFLAGS="-C target-cpu=native" cargo build --release --features camera_sim
```

### Network Optimization

```toml
# For network streams (future feature)
[camera.network]
buffer_size_mb = 16
connection_timeout_ms = 5000
read_timeout_ms = 1000
```

### Platform-Specific Optimizations

#### Raspberry Pi
```toml
[camera.pi]
frame_width = 1280
frame_height = 720
fps = 15.0  # Conservative for Pi
buffer_pool_size = 4
enable_memory_optimization = true
```

#### High-Performance Server
```toml
[camera.server]
frame_width = 1920
frame_height = 1080
fps = 60.0
buffer_pool_size = 32
enable_hardware_acceleration = true
```

## Best Practices

### 1. Test Data Organization
```
test_data/
├── meteors/
│   ├── bright_meteors.mp4
│   ├── faint_meteors.mp4
│   └── multiple_meteors.mp4
├── backgrounds/
│   ├── clear_sky.mp4
│   ├── cloudy_sky.mp4
│   └── high_noise.mp4
└── synthetic/
    ├── patterns.mp4
    └── calibration.mp4
```

### 2. Configuration Management
```bash
# Environment-specific configs
meteor-client-config.dev.toml     # Development
meteor-client-config.test.toml    # Testing
meteor-client-config.prod.toml    # Production
```

### 3. Continuous Validation
```bash
# Regular test suite execution
crontab -e
0 */6 * * * cd /path/to/project && scripts/test_camera_simulation.sh
```

This comprehensive guide should enable you to effectively use the camera simulation system for development, testing, and deployment of the meteor edge client.