Cross-platform desktop satellite tracking & orbital analysis for amateur radio operators.

OrbitDeck is a desktop application for satellite tracking and orbital analysis — a roomy UI with embedded plots, built for amateur-radio operators who work the birds. It is tracking and analysis only: radio (CAT) and rotator control are intentionally out of scope, since excellent dedicated tools already cover that.

OrbitDeck ships its own pure-Python SGP4 propagator and a bundled coastline set, so it runs fully offline with only matplotlib, numpy, and certifi. For the best performance and accuracy, the optional extras are strongly recommended — they add the reference sgp4 C-accelerated propagator (faster, and fully correct for deep-space / geostationary objects) and cartopy for full-resolution Natural Earth coastlines. See Optional extras and the install & build guide.

git clone https://github.com/prstoetzer/OrbitDeck
cd OrbitDeck
pip install -e .
orbitdeck

Or without installing:

pip install -r requirements.txt
python run.py

The base install pulls only matplotlib, numpy, and certifi, so it is quick and reliable on every platform. On first launch OrbitDeck loads a small bundled catalog (ISS, SO-50, AO-91, CAS-4B, RS-44) so every screen works immediately offline. Click Update GP (online) to pull the live AMSAT catalog, and use the Satellites screen to fetch SatNOGS transponder data for the selected bird.

⚠️ Pass times from the bundled catalog are illustrative, not real. The demo elements are stamped to the current date so the geometry is sensible, but their orbital phase is synthetic — they will not tell you when a satellite is actually overhead. A yellow banner reminds you while demo (or stale) data is loaded. Click Update GP (online) for accurate, on-the-air pass times. SGP4 is only trustworthy within ~1–2 weeks of an element set's epoch, so refresh periodically.

OrbitDeck runs fully on its bundled, pure-Python building blocks, but the optional packages are strongly recommended for the best experience and performance — install them unless you have a reason not to:

The simplest path is pip install "orbitdeck[full]", which pulls every extra. cartopy depends on the GEOS/PROJ system libraries (see docs/INSTALL.md for the one apt/dnf line per distro); if it's awkward on your platform, install [accurate] and [excel] and skip [maps].

tkinter note: the python.org installers for Windows and macOS include tkinter. On Linux it's a separate package: sudo apt install python3-tk (Debian/Ubuntu/Raspberry Pi OS), sudo dnf install python3-tkinter (Fedora), or sudo pacman -S tk (Arch).

📖 Per-platform install, run & build instructions — including how to install Python and build with every optional dependency on Windows, macOS, Debian/Ubuntu, Fedora, Arch, and Raspberry Pi OS — are in docs/INSTALL.md. To build native packages (.deb, .rpm, Arch PKGBUILD, AppImage, Flatpak) see packaging/PACKAGING.md; for a standalone PyInstaller app see packaging/BUILD.md.

The table below lists the screens in the exact order they appear in the left-hand navigation menu.

A Pass alarms toggle in the top bar raises AOS / TCA / LOS notifications (a gentle audible cue, the in-app status line, and a native desktop toast for "starting soon" and AOS) for favorite satellites' next passes, so you don't miss a rising bird while working in another screen or another app.

(Shortcuts are ignored while you're typing in a text field.)

Every satellite-specific screen has a Report… button that saves a clean, printable PDF for the selected satellite — a comprehensive document with orbital analysis, next passes, the equator-crossing schedule, a 3-day sky-track grid, the 60-day illumination raster and the 30-day pass progression. Additional one-click reports print a 7-day favorites schedule (Home), mutual windows (Mutual Windows), a 60-day illumination summary (Illumination), a 30-day pass progression (Pass Progression), and a 3-day sky-track grid (Next Passes).

For full, step-by-step documentation of every screen and workflow, see the OrbitDeck manual.

Settings, favorites, your site and the cached catalog persist under ~/.orbitdeck/.

The orbital core uses the WGS72 gravity model to match the GP/TLE mean elements. Key conventions:

• range-rate (for Doppler) is taken from the SGP4 velocity vector, not by differencing slant range;
• eclipse uses the cylindrical Earth-shadow test;
• beta angle is the orbit-plane-to-Sun angle;
• mutual windows are true two-station co-visibility.

Propagation backend. OrbitDeck ships its own dependency-free pure-Python implementation, orbitdeck/engine/sgp4_lite.py, and runs entirely on it out of the box. It is verified against the canonical Vallado AIAA-2006-6753 reference vector (catalog 88888) to about one centimetre at epoch and is accurate for near-Earth LEO — essentially every FM and linear amateur satellite (SO-50, the AO/FO/CAS birds, the ISS, RS-44, etc.), where it tracks the reference sgp4 package to well under a kilometre across a typical pass.

Installing the optional accurate extra (pip install "orbitdeck[accurate]") adds the C-accelerated reference sgp4 package. orbitdeck/engine/propagator.py detects it at runtime and uses it automatically — no configuration needed.

Deep-space orbits (GEO/HEO). For deep-space orbits (orbital period ≥ 225 min — e.g. the geostationary QO-100 / Es'hail-2, AO-7's ~12-hour orbit, or Molniya-type orbits), full reference SDP4 gives the most correct positions. The bundled propagator's deep-space terms are only approximate, so when it is in use for such an object OrbitDeck flags it in the header with a reduced-accuracy warning — an approximate model can mis-place a geostationary bird badly enough to imply it rises and sets when it does not. Installing the reference backend removes the warning and restores full accuracy:

pip install "orbitdeck[accurate]"   # or simply: pip install sgp4

In short: the base install is exact enough for everyday LEO satellite operating, but installing accurate (or full) is strongly recommended — it is faster and is the correct choice for deep-space birds and for the last bit of precision.

orbitdeck.engine has no GUI dependency, so you can script with it:

import time
from orbitdeck.engine import SatDb, Predictor, Observer

db = SatDb()
db.load_gp_json(open("gp.json").read())

pred = Predictor()
pred.set_site(Observer(lat=39.93, lon=-74.89, alt_m=20, valid=True))
pred.set_sat(db.get(25544))               # ISS

for p in pred.predict_passes(time.time(), min_el=5.0, max_n=5):
    print(p.aos, round(p.max_el, 1))

The engine is a full headless library: catalog loading (SatDb), live look angles, passes, nodes, eclipses, Doppler and link budgets (engine.linkbudget), target/rove planning (engine.planning), Sun/Moon/planet/EME geometry (engine.celestial), and a large set of orbital-mechanics helpers (engine.analysis). Complete API documentation is in docs/ENGINE.md.

For headless boxes and SSH sessions there's OrbitTerm, a curses companion that runs in any terminal with no GUI and no extra dependencies. It reuses this same engine and the shared ~/.orbitdeck config and catalog cache, so its numbers match the desktop app.

orbitterm            # if installed via pip
python -m orbitterm  # from a source checkout

It covers live tracking, a scrollable pass table, an ASCII sky radar and world ground-track map, full orbital analysis, and transponder Doppler dials with a live shift curve. See orbitterm/README.md for the screen and key reference.

orbitdeck/
├─ run.py                      dev entry point (python run.py)
├─ pyproject.toml              packaging + `orbitdeck` console script
├─ orbitdeck.spec              PyInstaller spec (standalone app bundle)
├─ docs/                       MANUAL.md, INSTALL.md, ENGINE.md, img/
├─ packaging/                  native packagers: PACKAGING.md, BUILD.md,
│                              PKGBUILD, orbitdeck.spec.rpm, debian/,
│                              .desktop + AppStream metainfo
├─ tests/                      pytest suite, split by area (propagation,
│                              oscarlocator, radio, reports, planning, …)
└─ orbitdeck/
   ├─ engine/                  portable orbital core (no GUI)
   │  ├─ sgp4_lite.py          vendored pure-Python SGP4/SDP4 (WGS72)
   │  ├─ propagator.py         backend selector (reference sgp4, lite fallback)
   │  ├─ satdb.py              GP/OMM + SatNOGS parsing, SatEntry/Transponder
   │  └─ predict.py            look angles, passes, Doppler, eclipse, beta,
   │                           footprint, mutual windows, Maidenhead grid
   ├─ data/                    bundled offline catalog + simplified coastline
   └─ gui/                     Tkinter app
      ├─ app.py                main window, nav, theme, clock loop
      ├─ store.py              state, persistence, online fetch (stdlib only)
      ├─ mapdraw.py            world basemap (cartopy if present, else bundled)
      └─ screens/              one module per screen

• GP elements: AMSAT daily bulletin (newark192.amsat.org).
• Transponders: SatNOGS DB transmitters API.

Both are fetched with the Python standard library only; no API key required.

pip install -e ".[dev]"
pytest -q
ruff check orbitdeck      # lint

The 130+ tests are organised by area under tests/ (test_propagation.py, test_oscarlocator.py, test_radio.py, test_reports.py, test_planning.py, and so on), with shared fixtures in tests/conftest.py. CI runs the suite on Python 3.8/3.10/3.12. Because sgp4 and cartopy are optional, one CI job runs the full suite without them, guaranteeing the bundled fallback propagator and coastlines stay correct on their own (with deep-space orbits flagged as approximate, exactly as the app does at runtime).

By design, OrbitDeck does not include radio/CAT control (Icom CI-V, Yaesu, Kenwood, IcomNet, rigctld) or rotator control (rotctld). The engine still computes the Doppler-corrected frequencies and look angles those subsystems would consume, so a rig/rotator bridge could be added later — but it is not part of OrbitDeck.

OrbitDeck provides a full tracking and orbital-analysis surface:

Satellites catalog; all of the Orbital-Analysis pages (Info, Live, Next Pass, Ground Track, Doppler, Nodal/J2, Sun-Beta, Pass Outlook, Orbit Position, EQX map and list); Next Passes; Pass detail & polar; Mutual windows; multi-day pass progression; 60-day illumination; live Track; world map with footprint and terminator; an interactive 3D globe; Sun/Moon and Celestial; Workable grids, US states, and DXCC; rove planning; a broad Learn teaching suite; Space Weather (F10.7 / Kp / A from NOAA SWPC); Settings; GP-age warnings; online GP (AMSAT) and transponder (SatNOGS) fetch.

The only capabilities intentionally excluded are radio (CAT) and rotator control — see above.

Notes on the workable overlays. Grids are computed geometrically (no bundled data). US states use multi-point interior sampling per state, and DXCC uses per-entity reference points for a practical set of the commonly worked / spread entities. Both are footprint-scale accurate and intentionally lightweight; a footprint grazing a border may briefly list a neighbour, which is correct at footprint scale (both are workable).

OrbitDeck is written by Paul Stoetzer, N8HM. Source code, the issue tracker, and releases are on GitHub: github.com/prstoetzer/OrbitDeck.

If you find OrbitDeck useful, please consider joining and/or donating to AMSAT — the Radio Amateur Satellite Corporation — at www.amsat.org.

AMSAT is a volunteer, member-supported non-profit organization that designs, builds, arranges launches for, and operates the amateur radio satellites that OrbitDeck is built to track. Founded in 1969, AMSAT has kept amateur radio in space for over half a century, building everything from the early OSCAR satellites to today's linear-transponder and FM birds that this program helps you work. The organization receives no government funding: membership dues and donations are what fund the design and launch of the next generation of amateur satellites. Supporting AMSAT directly helps keep these satellites — and the hobby of satellite operating — alive.

MIT — see LICENSE.

OrbitDeck is an independent project; its satellite-tracking math follows the public Vallado SGP4 reference.