night-sky 0.4.0
Offline, cross-platform, Python-based planetarium and sky chart generator.
License: MIT
Requires Python: >=3.10

# Night Sky Viewer

Night Sky is an offline, cross-platform planetarium with professional-grade accuracy, rich catalogs, and a polished GUI. Run it on Linux, macOS, or Windows. Explore 2D and 3D skies, plan observations, and export publication-quality charts.

## Why Night Sky stands out
- **Accuracy first**: Optional high-accuracy ephemerides (JPL DE421), refraction and light-pollution controls, time-scale awareness (UTC/TT), twilight filtering, and horizon/refraction modeling.
- **Rich data**: Default bright catalog plus a rich (~108k-star) set, Messier + NGC/IC deep-sky objects, and custom catalog support. Constellations, Moon phase, planets, and DSOs are all built-in.
- **Immersive visuals**: 2D Rect/Dome and 3D OpenGL dome views, horizon gradient and compass, Milky Way band placeholder, theme presets (Night, Astro Red, High Contrast), label density and limiting magnitude controls.
- **Interactive & extensible**: Click-to-pick objects with details, preset skies, settings import/export/reset, plugin loader, custom catalogs, and offline help.
- **High-DPI exports**: PNG exports include labels (as seen), N/E markers, scale bar, legend, and optional metadata—ready for print at 300–600 DPI.

## Quick start
Requirements: Python 3.10+.

```bash
# from PyPI (recommended)
python3 -m pip install night-sky
night-sky  # launches the GUI

# or run from source
python3 -m pip install -r requirements.txt
python3 -m pip install .
python3 -m night_sky
```

Use the control dock to set location, date/time, projection (Rect/Dome), view (2D/3D), themes, limiting magnitude, label density, light pollution, refraction, and ephemeris accuracy. Click objects to see details in the info pane. The Help menu opens offline tutorials.

## Example sky: “Titanic Night”
Recreate a famous historical sky to see accuracy in action:
- Location: 41.7325 N, -49.9469 E (North Atlantic)
- Time (UTC): 1912-04-15 02:20
- Set the date/time and lat/lon in the control dock, choose Dome view, adjust limiting magnitude for faint horizon stars, and export at high resolution for print.

## Saving & exporting
- Click **Export PNG**. Choose size (2000–4000 px recommended) and fill optional metadata (title, observer, location, datetime).
- Exports include labels (matching on-screen placement), N/E markers, scale bar, and legend. Suitable for print at 300–600 DPI.

## Feature overview
- **Views**: 2D Rectangular Alt/Az and Dome projections; 3D OpenGL dome (auto-fallback to 2D if OpenGL unavailable).
- **Catalogs**: Bright default, rich (~108k) star set, Messier + NGC/IC DSOs, custom CSVs via catalog selector or plugins.
- **Ephemerides**: Optional JPL DE421 download for high-accuracy Sun/Moon/planets; refraction; light pollution slider; time-scale (UTC/TT).
- **Themes & overlays**: Night/Astro Red/High Contrast; label density and limiting magnitude; constellations; Moon phase; planet/DSO labels; horizon compass; Milky Way placeholder band.
- **Interactivity**: Click object info; preset skies; settings import/export/reset; plugin loader; offline help.
- **Export**: High-DPI PNG with legend, metadata, scale bar, and N/E markers.

## Data files
- Stars: `night_sky/data/stars_extended.csv` (default) and `night_sky/data/stars_rich.csv` (rich).
- Deep-sky: `night_sky/data/messier.csv`, `night_sky/data/ngc_ic.csv`.
- Constellations: `night_sky/data/constellations_lines.csv`.
- Cities: `night_sky/data/cities.csv`.

You can supply a custom CSV (id,name,ra_deg,dec_deg,mag) via the catalog selector or place a plugin in `~/.night_sky/plugins/` to add data/overlays.

### Scientific assumptions
- Default ephemerides are accurate for general use; enable “High-accuracy ephemerides” to download a JPL DE kernel for more precise Sun/Moon/planet positions.
- Refraction and light-pollution controls are first-order approximations; aberration/precession toggles are available in advanced controls.

## Headless smoke test
```bash
export QT_QPA_PLATFORM=offscreen  # for headless CI/servers
python3 - <<'PY'
from datetime import datetime, timezone
from night_sky.sky_model import SkyModel
sm = SkyModel(limiting_magnitude=6.0)
snap = sm.compute_snapshot(0.0, 0.0, datetime.now(timezone.utc))
print("visible stars:", len(snap.visible_stars))
PY
```

## Roadmap / TODO (highlights)
- Installers/bundles (MSI/DMG/AppImage), visual regression tests, better Milky Way texture.
- Search/go-to, time-lapse/events pane, FOV overlays and coordinate grids, richer import UX.
- Full i18n/accessibility, improved 3D picking, Gaia-scale optional catalog download.

See `docs/RELEASE_NOTES.md` and `docs/TODO.md` for current status and plans.