Skip to content

irjudson/astronomus

BranchesTags

Repository files navigation

Astronomus

Intelligent observing session planner for astrophotography with Seestar S50 integration

License Python FastAPI

What is Astronomus?

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

Key Features

✅ Implemented

Smart Scheduling

  • Greedy algorithm with urgency-based lookahead optimizes target selection
  • Field rotation calculation for alt-az mounts
  • Per-azimuth local horizon profile with linear interpolation
  • Satellite avoidance: blocked-interval scheduling using Celestrak visual TLEs
  • Planet/moon wishlist items scheduled as real time-blocks (Meeus magnitudes, ring tilt)
  • Comet targets in plan via MPC ephemeris; "visible comets tonight" card in Tonight view
  • Automated daily plan generation at noon with Celery Beat

Unmanned Capture Automation

  • Auto-execute at dusk — Celery Beat computes astronomical twilight, queues plan at exact time
  • Scope connectivity retries — TCP-pings S50 every 5 min, up to 6 attempts
  • Weather watchdog — aborts session if rain, excess wind, or high humidity detected
  • Session webhooks — scope unreachable, session started, completed/aborted notifications
  • Automation settings tab — all thresholds configurable in UI

Comprehensive Catalog

  • 12,400+ objects from OpenNGC, Caldwell (109), Arp Atlas (50), Sharpless HII (50)
  • User-defined custom targets with CRUD API, image thumbnails, and "My Targets" tab
  • Advanced filtering by type, magnitude, constellation
  • Score-based sorting, visible-tonight filter, nearby-objects proximity search

Weather Integration

  • 7Timer astronomical seeing and transparency forecasts
  • Local Ambient Weather WS-2902 station (temp, humidity, wind, dew point)
  • Open-Meteo 7-day daily forecast with color-coded astronomy score strip
  • Composite weather scoring integrated into target selection

Seestar S50 Integration

  • Direct WiFi plan upload via set_plan API — "Send to Scope" button in Plan view
  • MJPEG live preview stream (/api/telescope/preview/stream)
  • Telescope-driven horizon scan (brightness-ratio sky/terrain detection)
  • Full telescope control: goto, capture, focus, gain, dew heater, polar alignment
  • Optimized for 50mm f/5 optics (1.27° × 0.71° FOV)

Live Session Tracking

  • Live now-marker advances in real time during active session
  • NowPlayingPanel: current/next target, frame progress bar, auto-advance on completion
  • "Done →" button to skip to next target; extend target duration inline

GPU Processing

  • CUDA-accelerated FITS stacking with CuPy
  • Sigma-clipped mean stacking for outlier rejection
  • Auto-stretch matching Seestar native output
  • NVIDIA MPS for efficient GPU sharing

Vue 3 SPA

  • Tonight / Sky / Plan / Observe / Archive navigation
  • Interactive timeline drag-editing with real-time conflict detection
  • Wishlist, saved plans, gap-filling optimizer
  • Toast notifications, settings modal with Horizon and Automation tabs

📋 Next Up

Post-Capture Processing UI

  • Archive tab backend is functional; file ingest, job queue UI, and batch export in progress

Unmanned Capture Reliability

  • Manual "run now" trigger, dry-run validation, webhook delivery visibility

See full roadmap →

Quick Start

Docker (Recommended)

# Start all services
docker-compose up -d

# Access the application
open http://localhost:9247

That's it! The default configuration works out of the box for testing.

Full quick start guide →

Native Development

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

Development guide →

Seestar S50 Authentication Setup

To use Seestar S50 telescope control features, you need the RSA private key for authentication with firmware 6.45+.

Automatic Key Extraction

Run the extraction script:

cd backend
./scripts/extract_seestar_key.sh

The script will:

  1. Look for the Seestar APK in /tmp/
  2. Extract the embedded RSA private key
  3. Save it to backend/secrets/seestar_private_key.pem

Manual Key Provision

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

Getting Help

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

Documentation

For Users

For Developers

For Operators

Complete documentation index →

Architecture

┌─────────────────────────────────────────────────────┐
│              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 │
└──────────┘  └──────────┘  └──────────┘

Detailed architecture →

Tech Stack

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 3 + Vite + Pinia + Vue Router
  • Tailwind CSS for styling

Deployment

  • Docker and Docker Compose
  • NVIDIA Container Toolkit for GPU
  • Celery Beat for scheduling

Default Configuration

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

Configuration guide →

Key Algorithms

Field Rotation Calculation

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

Target Scoring

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

Urgency-Based Scheduling

Targets setting within the lookahead window (30 minutes) receive priority bonus to avoid missing time-sensitive objects.

API Endpoints

Planning:

  • POST /api/plan - Generate observing plan
  • GET /api/plans - List saved plans
  • POST /api/plans/{id}/execute - Execute plan on telescope

Catalog:

  • GET /api/targets - List DSO targets (paginated)
  • GET /api/targets/{id} - Get target details
  • GET /api/targets/search - Search catalog
  • GET /api/targets/stats - Catalog statistics

Weather:

  • GET /api/weather/current - Current conditions
  • GET /api/weather/forecast - Multi-hour forecast
  • GET /api/astronomy/weather/7timer - Astronomical seeing

Processing:

  • POST /api/process/auto - Auto-process FITS file
  • POST /api/process/stack-and-stretch - Stack and stretch
  • GET /api/process/jobs/{id} - Job status

System:

  • GET /api/health - Health check
  • GET /api/docs - OpenAPI documentation

Complete API documentation →

Requirements

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

Testing

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

Test Coverage: 726 tests passing (unit + integration), 49 skipped (hardware)

Testing guide →

Contributing

Contributions are welcome! Areas of interest:

Features:

  • Mosaic planning (multi-panel FOV, overlap calculator)
  • Advanced image processing algorithms
  • Mobile PWA / offline favorites
  • Interactive sky map overlay

Improvements:

  • Enhanced scheduling algorithms
  • Additional export formats
  • UI/UX enhancements
  • Performance optimizations

Documentation:

  • Additional examples and tutorials
  • Translation to other languages
  • Video guides

Process:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Follow development guidelines
  4. Run tests and ensure they pass (pytest)
  5. Submit a pull request

Development guide →

License

MIT License - See LICENSE for details

Free for:

  • Personal use
  • Commercial use
  • Modification
  • Distribution

Requirements:

  • Include copyright notice
  • Include license text

Acknowledgments

Software:

  • FastAPI - Modern Python web framework
  • Skyfield - Astronomical calculations
  • Astropy - Astronomy tools for Python
  • CuPy - GPU-accelerated computing

Data Sources:

Community:

Support

Documentation: docs/INDEX.md

Issues: GitHub Issues

Discussions: GitHub Discussions (for questions)

Made for stargazers, by stargazers 🔭✨

About

Intelligent observing session planner — AI-assisted target selection, weather integration, and imaging schedule optimization.

Topics

desktop-app python ai astronomy original astrophotography observing-planner

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages