meteor_detection_system/meteor-edge-client/CAMERA_SIMULATION_USAGE.md

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
2. Configuration
3. Camera Source Types
4. Development Workflow
5. Testing Strategies
6. CI/CD Integration
7. Troubleshooting
8. Performance Optimization

Quick Start

Prerequisites

# 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

# 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:

[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

# 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.

# 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.

# 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.

# 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.

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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 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

# 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"

# 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

# 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)

# 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

# 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

# Reduce buffer pool size
[camera.performance]
buffer_pool_size = 10
max_camera_memory_mb = 32

Low frame rate

# 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

RUST_LOG=debug cargo run --features camera_sim -- --camera-source "test:meteor"

Memory leak detection

valgrind --leak-check=full ./target/debug/meteor-edge-client --camera-source "test:static"

Performance profiling

perf record ./target/release/meteor-edge-client --camera-source "test:meteor" --frames 1000
perf report

Performance Optimization

Memory Optimization

// 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

# 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

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

Platform-Specific Optimizations

Raspberry Pi

[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

[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

# Environment-specific configs
meteor-client-config.dev.toml     # Development
meteor-client-config.test.toml    # Testing
meteor-client-config.prod.toml    # Production

3. Continuous Validation

# 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.