Intelligent observing session planner for astrophotography with Seestar S50 integration
Astronomus is a comprehensive observing session planning tool that helps astrophotographers maximize their imaging time by intelligently scheduling deep sky objects throughout the night. The application accounts for astronomical phenomena, weather conditions, and equipment limitations to create optimal observation plans.
Perfect for:
- 🔭 Seestar S50 telescope users
- 🌌 Astrophotography enthusiasts
- 📊 Data-driven session planning
- 🌐 Any location worldwide
Smart Scheduling
- Greedy algorithm with urgency-based lookahead optimizes target selection
- Field rotation calculation for alt-az mounts
- Automated daily plan generation at noon
Comprehensive Catalog
- 12,400+ objects from OpenNGC catalog
- Messier, NGC, and IC catalogs
- Advanced filtering by type, magnitude, constellation
- Search by catalog ID or common name
Weather Integration
- 7Timer astronomical seeing and transparency forecasts
- OpenWeatherMap cloud cover and conditions
- Composite weather scoring for target selection
Seestar S50 Integration
- Direct export to seestar_alp CSV format
- QR code sharing for mobile workflow
- Optimized for 50mm f/5 optics (1.27° × 0.71° FOV)
- Alt-az mount field rotation compensation
GPU Processing
- CUDA-accelerated image stacking with CuPy
- Sigma-clipped mean stacking for outlier rejection
- Auto-stretch matching Seestar native output
- NVIDIA MPS for efficient GPU sharing
Automatic Planning
- Daily plan generation at configurable time
- Celery Beat scheduler for periodic tasks
- Webhook notifications for plan creation
- Database-backed configuration
Multiple Export Formats
- seestar_alp CSV (recommended)
- Seestar Plan Mode JSON
- Human-readable text
- CSV for analysis
- Complete JSON export
Frontend Catalog Browser
- Interactive catalog exploration UI
- Advanced search and filtering
- Target preview and details
Live Session Tracking
- Real-time execution monitoring
- Progress updates during imaging
- Weather-based re-planning
Comet/Asteroid Ephemeris
- Automated position calculations
- Integration with MPC and JPL databases
- Moving object tracking
Mosaic Planning
- Multi-panel session planning
- FOV overlap calculation
- Automatic stitching support
Multi-Telescope Support
- Equipment profiles
- Simultaneous telescope control
- Cloud observation coordination
# Start all services
docker-compose up -d
# Access the application
open http://localhost:9247That's it! The default configuration works out of the box for testing.
# Setup
git clone https://github.com/irjudson/astronomus.git
cd astronomus/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Configure
cp .env.example .env
# Edit .env with your settings
# Run
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 9247 --reloadTo use Seestar S50 telescope control features, you need the RSA private key for authentication with firmware 6.45+.
Run the extraction script:
cd backend
./scripts/extract_seestar_key.shThe script will:
- Look for the Seestar APK in
/tmp/ - Extract the embedded RSA private key
- Save it to
backend/secrets/seestar_private_key.pem
If you already have the key, create the file manually:
mkdir -p backend/secrets
# Paste your PEM key into:
nano backend/secrets/seestar_private_key.pem
chmod 600 backend/secrets/seestar_private_key.pemIf you need assistance obtaining the key:
- Open an issue: GitHub Issues
- Contact the maintainer for instructions
Note: The key is extracted from the official Seestar app and is required for the authentication protocol used by firmware 6.45+. This is the same key used by the official app.
- Quick Start - Get started in 5 minutes
- User Guide - How to use the planner
- API Documentation - API endpoints and examples
- Seestar Integration - Using with Seestar S50
- Daily Planning - Automatic plan generation
- Architecture - System design and components
- Development Setup - Native installation guide
- Testing Guide - Running and writing tests
- Processing Design - Image processing pipeline
- Docker Deployment - Production deployment
- Configuration Reference - All environment variables
- GPU Configuration - NVIDIA MPS setup
Complete documentation index →
┌─────────────────────────────────────────────────────┐
│ Frontend (Vue.js) │
│ http://localhost:9247 │
└──────────────────┬──────────────────────────────────┘
│ HTTP/REST API
┌──────────────────▼──────────────────────────────────┐
│ FastAPI Backend (Python 3.11) │
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│ │ Planner │ │ Catalog │ │ Weather │ │
│ │ Service │ │ Service │ │ Service │ │
│ └────────────┘ └────────────┘ └──────────────┘ │
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│ │ Processing │ │ Telescope │ │ Export │ │
│ │ Service │ │ Service │ │ Service │ │
│ └────────────┘ └────────────┘ └──────────────┘ │
└──────────────────┬──────────────────────────────────┘
│
┌─────────────┼─────────────┐
│ │ │
┌────▼────┐ ┌────▼─────┐ ┌───▼──────┐
│PostgreSQL│ │ Redis │ │ Celery │
│ Database │ │ Broker │ │ Workers │
└──────────┘ └──────────┘ └──────────┘
Backend
- Python 3.11+
- FastAPI for REST API
- SQLAlchemy for ORM
- Alembic for migrations
- Celery for background tasks
Database
- PostgreSQL for data persistence
- Redis for message broker
Processing
- CuPy for GPU acceleration (CUDA 12.8+)
- NumPy for CPU fallback
- Astropy for FITS file handling
- Skyfield for astronomical calculations
Frontend
- Vue.js 3 (new, in migration)
- Vite for build tooling
- Pinia for state management
- Vue Router for SPA navigation
- Tailwind CSS for styling
- Vanilla JavaScript (legacy, being phased out)
Deployment
- Docker and Docker Compose
- NVIDIA Container Toolkit for GPU
- Celery Beat for scheduling
Location: Three Forks, Montana
- Latitude: 45.9183°N
- Longitude: 111.5433°W
- Elevation: 1234m (4049 ft)
- Timezone: America/Denver
Planning:
- Min altitude: 30°
- Max altitude: 70° (to avoid high field rotation)
- Setup time: 30 minutes
- Planning mode: Balanced
Telescope: Seestar S50
- Aperture: 50mm
- Focal length: 50mm (f/5)
- FOV: 1.27° × 0.71°
- Max exposure: 10 seconds
For alt-az mounts, field rotation rate (degrees/minute):
rate = 15 × cos(latitude) / cos(altitude) × |sin(azimuth)|
The scheduler:
- Prefers 45-65° altitude range (optimal)
- Avoids zenith during meridian passage
- Scores targets based on rotation rate
Composite score (0-1) based on weighted components:
| Component | Weight | Factors |
|---|---|---|
| Visibility | 40% | Altitude, duration, field rotation |
| Weather | 30% | Cloud cover, humidity, wind, seeing |
| Object Quality | 30% | Brightness, size match to FOV |
Targets setting within the lookahead window (30 minutes) receive priority bonus to avoid missing time-sensitive objects.
Planning:
POST /api/plan- Generate observing planGET /api/plans- List saved plansPOST /api/plans/{id}/execute- Execute plan on telescope
Catalog:
GET /api/targets- List DSO targets (paginated)GET /api/targets/{id}- Get target detailsGET /api/targets/search- Search catalogGET /api/targets/stats- Catalog statistics
Weather:
GET /api/weather/current- Current conditionsGET /api/weather/forecast- Multi-hour forecastGET /api/astronomy/weather/7timer- Astronomical seeing
Processing:
POST /api/process/auto- Auto-process FITS filePOST /api/process/stack-and-stretch- Stack and stretchGET /api/process/jobs/{id}- Job status
System:
GET /api/health- Health checkGET /api/docs- OpenAPI documentation
Minimum:
- Python 3.11+
- Docker 20.10+ and Docker Compose 2.0+ (Docker installation)
- OR PostgreSQL 14+ and Redis 6+ (Native installation)
Optional:
- NVIDIA GPU with CUDA 12.8+ for GPU-accelerated processing
- OpenWeatherMap API key (free tier) for weather forecasts
OS Support:
- Linux (tested on Ubuntu 22.04+)
- macOS (tested on 12.0+)
- Windows via WSL2
# Start services
docker-compose up -d
# Run test suite
docker exec astronomus pytest
# Run with coverage
docker exec astronomus pytest --cov=app
# Run specific test
docker exec astronomus pytest tests/test_planner_service.pyTest Coverage: 471 tests passing, 3 skipped
Contributions are welcome! Areas of interest:
Features:
- Additional DSO catalogs (Caldwell, Arp, Sharpless)
- Comet/asteroid ephemeris integration
- Mosaic planning capabilities
- Advanced image processing algorithms
Improvements:
- Enhanced scheduling algorithms
- Additional export formats
- UI/UX enhancements
- Performance optimizations
Documentation:
- Additional examples and tutorials
- Translation to other languages
- Video guides
Process:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Follow development guidelines
- Run tests and ensure they pass (
pytest) - Submit a pull request
MIT License - See LICENSE for details
Free for:
- Personal use
- Commercial use
- Modification
- Distribution
Requirements:
- Include copyright notice
- Include license text
Software:
- FastAPI - Modern Python web framework
- Skyfield - Astronomical calculations
- Astropy - Astronomy tools for Python
- CuPy - GPU-accelerated computing
Data Sources:
- OpenNGC - Open NGC/IC catalog (CC-BY-SA-4.0)
- OpenWeatherMap - Weather forecasts
- 7Timer - Astronomical seeing forecasts
Community:
- Seestar S50 Users - Telescope community
- smart-underworld/seestar_alp - Seestar automation tools
Documentation: docs/INDEX.md
Issues: GitHub Issues
Discussions: GitHub Discussions (for questions)
Made for stargazers, by stargazers 🔭✨