Telescope Detection System

Real-time object detection system for monitoring astronomical telescopes and desert wildlife using Reolink cameras and NVIDIA GPUs.

Features

• Ultra-fast detection: 11-21ms inference with YOLOX
• Object tracking: Track animals across frames with unique IDs, dwell time, and movement analytics
• Multi-camera support: Monitor multiple angles simultaneously with fault-tolerant startup
• GPU OOM graceful degradation: Automatic memory management prevents crashes with progressive quality reduction
• Performance optimizations: Empty frame filtering (30-50% throughput gain) + sparse detection (3x GPU load reduction)
• Clips directory authentication: Optional Bearer token authentication for saved wildlife clips
• Motion filtering: Background subtraction to eliminate false positives from static objects
• Time-of-day filtering: Species activity patterns reduce false positives (e.g., birds at night → likely bugs/bats)
• Automatic reconnection: Cameras reconnect automatically if connection is lost
• 80 COCO classes: Wildlife-relevant categories (person, bird, cat, dog, etc.)
• Per-class filtering: Customizable confidence thresholds and size constraints per detection class
• Optional species classification: iNaturalist Stage 2 (10,000 species) with geographic filtering + time-aware re-ranking
• Web interface: Live video streams with real-time detection overlays and GPU memory monitoring
• Automatic snapshots: Save interesting detections to disk with configurable cooldown
• MIT License: Fully open source

Quick Start

1. Install Dependencies

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

2. Configure Cameras

Copy the credentials template and add your camera passwords:

cp camera_credentials.example.yaml camera_credentials.yaml
nano camera_credentials.yaml  # Add your passwords

Edit config/config.yaml to set camera IPs and detection preferences.

3. Run the System

python main.py

Access the web interface at http://localhost:8000

4. Run as a Service (Recommended)

For production use with auto-start on boot:

sudo ./service.sh install
sudo ./service.sh start
./service.sh logs -f  # Watch logs

See SERVICE_SETUP.md for complete service documentation.

Documentation

Setup & Configuration

• Configuration Reference - All config options explained
• Service Setup - Running as systemd service
• Camera Credentials - Secure credential storage

Features & Usage

• Snapshot Feature - Automatic image/video saving
• Species Classification (Stage 2) - Fine-grained species ID
• GPU OOM Graceful Degradation - Memory management and crash prevention
• API Reference - WebSocket and HTTP endpoints

Performance & Troubleshooting

• Performance Guide - Benchmarks and optimization
• Troubleshooting - Common issues and solutions
• Architecture - System design and components

Training & Development

• Training Guide - Train custom models
• Annotation Guide - Label your own dataset

Testing

# Test camera connection
python tests/test_camera_connection.py

# Benchmark GPU inference
python tests/test_inference.py

# Measure end-to-end latency
python tests/test_latency.py

Project Structure

telescope_cam_detection/
├── config/                      # Configuration files
├── src/                         # Core application modules
├── web/                         # Web interface (HTML/JS)
├── docs/                        # Complete documentation
├── tests/                       # Test scripts
├── models/                      # Model weights
├── training/                    # Training infrastructure
├── clips/                       # Saved detection snapshots
└── main.py                      # Application entry point

System Requirements

• OS: Ubuntu 22.04+ (or similar Linux)
• GPU: NVIDIA GPU with CUDA support (A30 recommended)
• Python: 3.11+
• RAM: 8GB+ recommended
• Network: Local network access to Reolink cameras

Performance

With NVIDIA A30:

• Inference: 11-21ms per frame
• FPS: 25-30 sustained
• Latency: 25-35ms end-to-end
• Memory: ~2GB VRAM per camera

See Performance Guide for optimization strategies and benchmarks.

Development Roadmap

• ✅ Phase 1: Core detection system (complete)
• ✅ Phase 2: Species classification (complete)
• 🔨 Phase 3: Custom telescope training (in progress)
• 📋 Phase 4: Collision detection and alerts (planned)

Troubleshooting

Having issues? Check the Troubleshooting Guide for common problems and solutions.

Quick fixes:

• Camera not connecting? Run python tests/test_camera_connection.py
• GPU not working? Check with nvidia-smi and verify CUDA is available
• High latency? See Performance Guide for optimization tips

API

WebSocket

Connect to ws://localhost:8000/ws/detections for real-time detection events.

HTTP

• GET / - Web interface
• GET /health - Health check
• GET /stats - Performance metrics
• GET /video/feed - MJPEG video stream

See API Reference for complete documentation.

Credits

Built with these excellent open-source projects:

• YOLOX (Apache 2.0) - Object detection
• iNaturalist/EVA02 (Apache 2.0) - Species classification
• PyTorch (BSD-3) - Deep learning framework
• OpenCV (Apache 2.0) - Computer vision
• FastAPI (MIT) - Web framework

License

MIT License - see LICENSE for details. All dependencies use permissive licenses (Apache 2.0, BSD, MIT).

Support

• 📖 Documentation: See docs/ directory
• 🐛 Issues: GitHub Issues
• 📊 Logs: ./service.sh logs or check logs/ directory