Troubleshooting Starship Analyzer

This page provides solutions to common problems you may encounter when using Starship Analyzer.

Installation Issues

PyTorch Installation Failures

Problem: Error installing PyTorch or CUDA compatibility issues.

Solution:

1. Try installing with CPU-only version: python setup.py --force-cpu
2. Check your CUDA version with nvidia-smi and install a compatible PyTorch version
3. Visit PyTorch's installation page for specific instructions

# For manual PyTorch installation with CUDA 11.8
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

EasyOCR Installation Issues

Problem: Error installing EasyOCR or its dependencies.

Solution:

1. Install required system libraries:
   • Windows: No additional libraries needed
   • Ubuntu/Debian: sudo apt-get install libgl1-mesa-glx
   • macOS: brew install libomp
2. Try installing with pip directly: pip install easyocr
3. Ensure you have C++ build tools installed on your system

OpenCV Dependencies Missing

Problem: OpenCV fails to initialize due to missing system libraries.

Solution:

• Windows: Install Visual C++ Redistributable
• Ubuntu/Debian: sudo apt-get install libsm6 libxext6 libxrender-dev libgl1-mesa-glx
• macOS: brew install gcc libomp

Runtime Issues

High Memory Usage

Problem: Application uses too much RAM and crashes.

Solution:

1. Reduce batch size in processing options
2. Process every Nth frame instead of every frame
3. Use lower resolution videos
4. Close other memory-intensive applications
5. Add swap space/virtual memory to your system

Slow Processing Speed

Problem: Video processing is extremely slow.

Solution:

1. Enable GPU acceleration if available
2. Reduce video resolution
3. Increase frame sampling interval
4. Optimize batch size for your system
5. Close other CPU/GPU intensive applications
6. Consider upgrading hardware for large-scale processing

OCR Quality Issues

Problem: Poor quality text recognition from telemetry overlay.

Solution:

1. Use higher resolution video sources
2. Enable debug mode to see OCR detection regions
3. Adjust WHITE_THRESHOLD in settings if necessary
4. Try processing a different part of the video where telemetry is clearer
5. Use videos where telemetry isn't obscured by bright backgrounds

Engine Detection Problems

Problem: Incorrect engine status detection.

Solution:

1. Enable debug mode to view engine detection points
2. Adjust brightness threshold if necessary
3. Check that the video format matches expected layout
4. Use official SpaceX webcasts which have consistent engine views
5. Select video segments where engines are clearly visible

Data Issues

Missing or Incomplete Data

Problem: Processed data has gaps or missing values.

Solution:

1. Check the logs for processing errors
2. Try processing with a higher frame sampling rate
3. Use debug mode to identify frames with recognition issues
4. Ensure the video has clear telemetry overlays
5. Filter or interpolate data in post-processing

Inaccurate Telemetry Values

Problem: Extracted telemetry values don't match what's visible in the video.

Solution:

1. Enable debug mode to see OCR detection regions
2. Verify the video has standard SpaceX telemetry formatting
3. Try processing at a higher resolution
4. Check logs for OCR confidence values
5. Manually verify a few frames to confirm correct ROI positioning

Visualization Issues

Plots Not Generating

Problem: Visualization doesn't produce expected plots.

Solution:

1. Check if data file exists and contains valid data
2. Verify that matplotlib and dependencies are correctly installed
3. Check logs for plotting errors
4. Ensure you have write permissions to the output directory
5. Try a different output format (PNG, SVG, etc.)

Plot Quality Issues

Problem: Generated plots have rendering issues or are low quality.

Solution:

1. Adjust DPI settings for output files
2. Check for compatible font installations
3. Update matplotlib to the latest version
4. Try a different output format
5. For interactive plots, check browser compatibility

Log File Analysis

If you're experiencing issues not covered here, check your log files:

1. Locate the latest log file in the logs directory
2. Look for ERROR or WARNING messages
3. Check system information at the start of the log
4. Note any exception stack traces
5. Share relevant log sections when seeking support

Getting Additional Help

If you're still experiencing issues:

1. Search for similar issues in the GitHub repository
2. Create a new issue with:
   • Detailed description of the problem
   • Steps to reproduce
   • Log file contents
   • System information
   • Screenshots if applicable
3. For urgent assistance, contact the project maintainers directly

System-Specific Solutions

Windows-Specific Issues

• Path length limitations: Use shorter installation paths
• Antivirus interference: Add exceptions for the project directory
• Command prompt limitations: Use PowerShell for better output handling

macOS-Specific Issues

• Permissions issues: Ensure proper permissions with chmod +x setup.py
• Video codecs: Install VLC or ffmpeg for broader codec support
• M1/M2 compatibility: Use Python versions built for Apple Silicon

Linux-Specific Issues

• Missing libraries: Install development packages with apt/yum/etc.
• Permission issues: Use sudo for system-level installations
• Display issues: Install required X11 packages for visualization